mwbot-ts

import { Mwbot } from 'mwbot-ts';

Mwbot.init(initOptions, defaultRequestOptions).then((mwbot) => {
  // Use `mwbot` for your purposes...
});

import { Mwbot, MwbotInitOptions } from 'mwbot-ts';

const initOptions: MwbotInitOptions = {
  /**
   * The API endpoint. This property is required.
   */
  apiUrl: 'https://en.wikipedia.org/w/api.php', // Required
  /**
   * User agent for the application. Typed as optional, but should always be included
   * per https://www.mediawiki.org/wiki/API:Etiquette#The_User-Agent_header
   */
  userAgent: 'MyCoolBot/1.0.0 (https://github.com/Foo/MyCoolBot)', // Example
  /**
   * Default interval (in milliseconds) between specific actions.
   */
  interval: 5000, // Defaults to 5 seconds; optional
  /**
   * API actions between which to enforce an interval.
   */
  intervalActions: ['edit', 'move', 'upload'], // Defaults to these 3; optional
  /**
   * Whether to suppress warnings returned by the API.
   */
  suppressWarnings: false, // Defaults to false

  // One of the following must be provided for authentification:
  credentials: {
    oAuth2AccessToken: 'Your OAuth 2.0 access token'
  },
  credentials: {
    consumerToken: 'Your OAuth 1.0a consumer token',
    consumerSecret: 'Your OAuth 1.0a consumer secret',
    accessToken: 'Your OAuth 1.0a access token',
    accessSecret: 'Your OAuth 1.0a access secret'
  },
  credentials: {
    username: 'Your bot username',
    password: 'Your bot password'
  },
  credentials: {
    anonymous: true // For anonymous access; the client will be limited to non-write requests
  }
};

Mwbot.init(initOptions).then((mwbot) => {
  // Use `mwbot` for your purposes...
});

// Use for standard GET-based queries (read-only, short parameters)
mwbot.get({
  action: 'query',
  titles: 'Wikipedia:Sandbox',
  prop: 'info',
  format: 'json',
  formatversion: '2'
})
.then(console.log);

// Use for standard write operations or when POST is required
mwbot.post({
  action: 'purge',
  titles: 'Wikipedia:Sandbox',
  format: 'json',
  formatversion: '2'
})
.then(console.log);

// Use when a GET request may exceed URL length limits
mwbot.nonwritePost({
  action: 'query',
  list: 'blocks',
  bkusers: [/* very long field */], // Note: `mwbot-ts` accepts array inputs
  bklimit: 'max',
  format: 'json',
  formatversion: '2'
})
.then(console.log);

// Performs a read-only API request, letting mwbot-ts decide the appropriate HTTP method
// Automatically switches from GET to POST if the query is too long to fit in the URL
mwbot.fetch({
  action: 'query',
  titles: [/* A field that can be either short or long */],
  format: 'json',
  formatversion: '2'
})
.then(console.log);

// Performs a raw HTTP GET request to an arbitrary external API
const res = await mwbot.rawRequest({
  method: 'GET',
  url: 'https://api.github.com/repos/nodejs/node',
  headers: {
    'User-Agent': `mwbot-ts/${MWBOT_VERSION} (https://github.com/Dr4goniez/mwbot-ts)`
  },
  timeout: 10000,
  responseType: 'json'
});

console.log(res.data.full_name); // "nodejs/node"

// Cancels all ongoing HTTP requests issued by this instance
mwbot.abort();

// Performs an API request with automatic continuation
// By default, continues up to 10 times (or until complete)
mwbot.continuedRequest({
  action: 'query',
  list: 'logevents',
  leprop: 'ids|title|timestamp',
  letype: 'newusers',
  lelimit: 'max',
  format: 'json',
  formatversion: '2'
})
.then(console.log);

// Performs batched API requests when a multi-value field exceeds the limit
// Automatically splits the field and bundles the responses
mwbot.massRequest({
  action: 'query',
  list: 'blocks',
  bkprop: 'user|timestamp|expiry|restrictions|flags',
  bklimit: 'max',
  bkusers: [/* very long field */],
  format: 'json',
  formatversion: '2'
}, 'bkusers')
.then(console.log);

// Example for using a "watch" token
mwbot.postWithToken('watch', {
  action: 'watch',
  titles: 'Wikipedia:Sandbox',
  format: 'json',
  formatversion: '2',
  // `token` parameter automatically appended
})
.then(console.log);

// Creates a page titled 'Bar'
mwbot.create(
  'Bar',            // Page title
  '* Test. --~~~~', // Page content
  'test'            // Optional edit summary
)
.then(console.log);

// Edits an existing page titled 'Foo' and replaces its entire content
mwbot.save(
  'Foo',            // The page title
  '* Test. --~~~~', // The page content
  'test'            // Optional edit summary
)
.then(console.log);

// Adds a new section to page 'Foo'
mwbot.newSection(
  'Foo',              // The page title
  'Bot notice',       // The section title
  'Hi. ~~~~',         // The section content
  'Bot: Notification' // Optional edit summary
)
.then(console.log);

// Edits 'Bar' by transforming the existing content
mwbot.edit(
  'Bar',
  (wikitext, revision) => {
    const newContent = wikitext.content + '\n* Test. --~~~~';
    return { text: newContent }; // Parameters to `action=edit`
  }
)
.then(console.log);

import { MwbotError } from 'mwbot-ts';

// ...

const response = await mwbot.save(...args).catch((err: MwbotError) => err);
if (response instanceof MwbotError) {
  if (response.code !== 'aborted') {
    console.error(response); // MwbotError object
  }
} else {
  console.log(response); // ApiResponseEditSuccess
}

const exists = async (title: string): Promise<boolean> => {
  // mwbot.read() rejects if the page doesn't exist
  const res = await mwbot.read(title).catch(() => false);
  return !!res; // true if the page exists; otherwise false
};

import { Mwbot } from 'mwbot-ts';

class Mwbot2 extends Mwbot {

  /**
   * Checks if the given page exists. Returns `null` if the request fails.
   * @param title
   */
  exists(title: string): Promise<boolean | null> {
    return this.get({
      action: 'query',
      titles: title,
      format: 'json',
      formatversion: '2'
    }).then((res) => {
      const page = res.query?.pages?.[0];
      return page ? !page.missing : null;
    }).catch(() => null);
  }

}

Mwbot2.init(initOptions).then(async (mwbot) => {

  // ✓ Fully type-safe, no TypeScript errors
  const sandExists = await mwbot.exists('Wikipedia:Sandbox');
  console.log(sandExists);

  // ✓ Superclass methods and properties are still accessible
  console.log(mwbot.config.get('wgNamespaceIds'));

});

class Mwbot2 extends Mwbot {

  purgeDeep(
    titles: (string | Title)[],
    additionalParams: ApiParams = {},
    requestOptions: MwbotRequestConfig = {}
  ) {
    additionalParams = Object.assign(
      { forcerecursivelinkupdate: true },
      additionalParams
    );
    return this.purge(titles, additionalParams, requestOptions);
  }

}

mwbot.post({
  action: 'edit',
  title: 'Wikipedia:Sandbox',
  appendtext: '\n* Test. --~~~~',
  format: 'json',
  formatversion: '2'
})
.catch(console.error);

import { MwbotError } from 'mwbot-ts';

// ...

const response = await mwbot.request(params).catch((err: MwbotError) => err);
if (response instanceof MwbotError) {
  if (response.code !== 'aborted') {
    console.error(response); // MwbotError object
  }
} else {
  console.log(response); // JSON response
}

const wikitext = new mwbot.Wikitext('some wikitext');

const wikitext = await mwbot.Wikitext.newFromTitle('Wikipedia:Sandbox');

const text =
  'My name is <b>Foo</b><!-- not "Bar"! -->.\n' +
  'You can ping me using <nowiki>{{PingFoo}}</nowiki>.';

const wikitext = new mwbot.Wikitext(text);
console.log(wikitext.parseTags());

const text =
  '== Foo ==\n' +
  '=== Bar ===\n' +
  '[[Main page]]\n' +
  '== Baz ==\n' +
  '[[Another page]]';

const wikitext = new mwbot.Wikitext(text);
console.log(wikitext.parseSections());

const text =
  '{{#if:{{{1|}}}\n' +
  '<!--|{{{type}}}-->' +
  '|{{{1}}}\n' +
  '|{{{2|empty}}}\n' +
  '}}';

const wikitext = new mwbot.Wikitext(text);
console.log(wikitext.parseParameters());

const text =
  '{{Foo\n' +
  '|anchor={{#if:{{ns:0}}|Foo|Bar}}\n' +
  '|logo=[[File:Img.png|thumb|Mr. [[Foo]]|300px]]\n' +
  '}}';

const wikitext = new mwbot.Wikitext(text);
console.dir(wikitext.parseTemplates(), {depth: null});

const text =
  '[[File:Img.png|thumb|right|300px]]\n' +
  "'''Foo''' is a [[metasyntactic variable]]<!--[[metavariable]]-->.";

const wikitext = new mwbot.Wikitext(text);
console.dir(wikitext.parseWikilinks(), {depth: null});

// Example: Remove empty <noinclude> tags from "Wikipedia:Sandbox"
const result = await mwbot.edit('Wikipedia:Sandbox', (wikitext) => {

  const oldContent = wikitext.content;
  const newContent = wikitext.modifyTags((tag, _i, _arr) => {
    const isEmptyNoinclude =
      tag.name === 'noinclude' &&
      // Ignore e.g., <nowiki><noinclude></noinclude></nowiki>
      !tag.skip &&
      // Ignore <noinclude />
      !tag.selfClosing &&
      // Eliminate uncertainty
      !tag.unclosed &&
      // Has no content or only whitespace
      !tag.content?.trim();

    // A string return indicates "replace `tag.text` with this value";
    // `null` means no change.
    return isEmptyNoinclude ? '' : null;
  });

  if (oldContent === newContent) {
    // A tranformation predicate returning `null` will cancel the edit
    // via a Promise rejection with an "aborted" error code
    console.log('Edit cancelled.');
    return null;
  }

  // Return API parameters for `action=edit`
  // Partial specification is acceptable because `edit()` provides default parameters
  return { text: newContent };

}).catch((err: MwbotError) => err);

// Uniform error handling
if (result instanceof MwbotError) {
  if (result.code !== 'aborted') {
    console.error(result); // Failure
  }
} else {
  console.log(result); // Success
}

// Example: Insert {{Section resolved}} to the beginning of second-level sections
const text =
  '== Foo ==<!--\n-->\n' +
  '* Foo. --~~~~\n' +
  '=== Foo2 ===\n' +
  '* Foo2. --~~~~\n' +
  '== Bar ==\n' +
  '* Bar. --~~~~\n' +
  '== Baz ==\n' +
  '* Baz. --~~~~';

const wikitext = new mwbot.Wikitext(text);
const content = wikitext.modifySections((section) => {
  // Do not modify sections that are not level 2
  if (section.level !== 2) {
    return null;
  }

  // Check whether the section heading ends with a newline; if not, add one
  const newline = section.heading.endsWith('\n') ? '' : '\n';

  // Insert the template between the heading and the content
  return section.heading + newline + '{{Section resolved|1=~~~~}}\n' + section.content;
});
console.log(content);

// Rename {{{1}}} to {{{User}}}
const text =
  '{{#if:{{{1|}}}\n' +
  '|{{{1}}}\n' +
  '|{{{Ip|Foo}}}\n' +
  '}}';

const wikitext = new mwbot.Wikitext(text);
const content = wikitext.modifyParameters((parameter) => {
  if (parameter.key === '1' && !parameter.skip) {
    const value = parameter.value !== null ? '|' + parameter.value : '';
    return '{{{User' + value + '}}}';
  } else {
    return null;
  }
});
console.log(content);

// Add "|done" to {{Status}} and leave a bot comment
const text =
  '=== Global lock for Foo ===\n' +
  '{{Status}}\n' +
  '*{{LockHide|1=Foo}}\n' +
  'Long-term abuse. [[User:Bar|Bar]] ([[User talk:Bar|talk]]) 00:00, 1 January 2025 (UTC)';

const wikitext = new mwbot.Wikitext(text);

// Modify {{Status}}
let status: ParsedTemplate | null = null;
let content = wikitext.modifyTemplates((template) => {
  if (status) {
    return null;
  }
  const isStatus =
    mwbot.Template.is(template, 'ParsedTemplate') &&
    template.title.getPrefixedDb() === 'Template:Status' &&
    !template.skip;
  if (isStatus) {
    status = template;
    return template
      .insertParam('1', 'done', true, 'end')
      .stringify({suppressKeys: ['1']});
  }
  return null;
});
if (status === null) {
  return;
}

// Leave a bot comment
const containingSection = wikitext.identifySection(status);
if (!containingSection) {
  return;
}
content = wikitext.modifySections((section) => {
  if (section.index === containingSection.index) {
    return section.text.trim() + "\n: '''Robot clerk note:''' {{done}} by Baz. ~~~~\n";
  }
  return null;
});

console.log(content);

// Replace all instances of [[Category:Foo]] with [[Category:Bar]]
const text =
  'This category belongs to [[:Category:Foo]].\n' +
  '[[Category:Foo|*]]';

const wikitext = new mwbot.Wikitext(text);
const NS_CATEGORY = mwbot.config.get('wgNamespaceIds').category;

const content = wikitext.modifyWikilinks((link) => {
  const isFoo =
    mwbot.Wikilink.is(link, 'ParsedWikilink') &&
    link.title.getNamespaceId() === NS_CATEGORY && link.title.getMain() === 'Foo' &&
    !link.skip;
  if (isFoo) {
    const colon = link.title.hadLeadingColon() ? ':' : '';
    link.setTitle(colon + 'Category:Bar'); // Preserve the leading colon, if present
    return link.stringify();
  }
  return null;
});
console.log(content);

const config = mwbot.config;
console.log(config.get('wgFormattedNamespaces'));
console.log(config.get('wgUserRights')); // This key is exclusive to mwbot-ts