vstarck / nodemw

MediaWiki API client written in node.js

nodemw

MediaWiki API client written in node.js

Requirements

• nodejs

Dependencies

• vows
• request

Installation

Using npm

npm install nodemw

Or Download the latest stable version via GitHub.

Development version

git clone https://github.com/macbre/nodemw.git

Features

• HTTP requests are stored in queue and performed in serial, there's no risk of flooding the server
• nodemw core uses promise pattern powered by deferred-js library
• nodemw supports articles creation / edit / move / delete, file uploads (using given content or via provided URL)

Where it's used

• Over 10k edits on Poznań Wiki as Pyrabot - scripts repository

First script

An example script can be found in /examples directory.

cd examples
node pagesInCategory.js

Running unit tests

npm test

How to use it?

Creating a bot instance

  var bot = require('nodemw');

  // pass configuration object
  var client = new bot({
      server: 'en.wikipedia.org',  // host name of MediaWiki-powered site
      path: '/w',                  // path to api.php script
      debug: false                // is more verbose when set to true
  });

  client.getArticle('foo', function(data) {
      // ...
  });

Config file

nodemw can use config files as well as objects directly provided to bot object constructor.

 // read config from external file
 var client = new bot('config.js');

Config file is a JSON-encoded object with the following fields (see /examples/config-DIST.js file):

{
      "server": "en.wikipedia.org",  // host name of MediaWiki-powered site
      "path": "/w",                  // path to api.php script
      "debug": false,                // is more verbose when set to true
      "username": "foo",             // account to be used when logIn is called (optional)
      "password": "bar",             // password to be used when logIn is called (optional)
      "domain": "custom_ldap",       // domain name for authentication (optional)
      "userAgent": "Custom UA",      // define custom bot's user agent
      "concurrency": 5               // how many API requests can be run in parallel (defaults to 3)
}

Making direct API calls

nodemw allows you make direct calls to MediaWiki API (example querying Semantic MediaWiki API):

var bot = require('nodemw'),
  client = new bot({
		server: 'semantic-mediawiki.org',
		path: '/w'
	}),
	params = {
		action: 'ask',
		query: '[[Modification date::+]]|?Modification date|sort=Modification date|order=desc'
	};

client.api.call(params /* api.php parameters */, function(info /* processed query result */, next, data /* raw data */) {
	console.log(data && data.query && data.query.results);
});

Bot methods

The last parameter of each function in nodemw API is a callback which will be fired when the requested action is done.

bot.logIn(username, password, callback)

Log-in using given credentials - read more

bot.getCategories(prefix, callback)

Gets the list of all categories on a wiki

bot.getPagesInCategory(category, callback)

Gets the list of pages in a given category - read more

bot.getPagesByPrefix(prefix, callback)

Gets the list of pages by a given prefix - read more

bot.getArticle(title, callback)

Gets article content and its meta data - read more

bot.edit(title, content, summary, callback)

Creates / edits an article - read more

bot.delete(title, reason, callback)

Deletes an article - read more

bot.token(title, action, callback)

Returns token required for a number of MediaWiki API operations

bot.whoami(callback)

Gets information about current bot's user (including rights and rate limits) - read more

bot.move(from, to, summary, callback)

Moves (aka renames) given article - read more

bot.getImages(callback)

Gets list of all images on a wiki

bot.getImageUsage(filename, callback)

Gets list of all articles using given image

bot.getImagesFromArticle(title, callback)

Get list of all images that are used on a given page - read more

bot.getImageInfo(filename, callback)

Gets metadata (including uploader, size, dimensions and EXIF data) of given image

bot.getLog(type, start, callback)

Get entries form Special:Log - read more

bot.expandTemplates(content, title, callback)

Returns XML with preprocessed wikitext - read more

bot.fetchUrl(url, callback)

Makes a GET request to provided resource and returns its content.

bot.getRecentChanges(start, callback)

Returns entries from recent changes (starting from a given point)

bot.getRecentChanges(start, callback)

Returns entries from recent changes (starting from a given point)

client.getQueryPage(queryPage, callback)

Returns entries from QueryPage-based special pages

bot.upload(filename, content, summary /* or extraParams */, callback)

Uploads a given raw content as a File:[filename] - read more

bot.uploadByUrl(filename, url, summary /* or extraParams */, callback)

Uploads a given external resource as a File:[filename]

bot.getTemplateParamFromXml(tmplXml, paramName)

Gets a value of a given template parameter from article's preparsed content (see expandTemplates)

bot.getExternalLinks(title, callback)

Gets all external links used in article

bot.getBacklinks(title, callback)

Gets all articles that links to given article

Helpers

bot.getConfig(key, def)

Gets config entry value (returns def value if not found)

bot.setConfig(key, val)

Sets config entry value