MediaWiki Api

- 同时兼容浏览器&Node.js 环境 - - Support both browser and Node.js environment -

本库提供了与原版 new mw.Api() 非常相似的 api 请求封装。让你在非 MediaWiki 环境中轻松实现各种 wiki 操作。使用 TypeScript 编写~ The library provides the out of box accessing to MediaWiki API in both browsers & Node.js, and the syntax is very similar to vanilla new mw.Api(). TypeScript definition included~

特色功能 Features

• Similar API to the vanilla new mw.Api()
• Parameter Schema automatic compliance: { "foo": ["bar", "baz"], watch: false } → { "foo": "bar|baz" }
• Token caching and retry mechanism
• TypeScript support
• With unit tests
• User authentication supports out of the box *(also applicable to Node.js!)

开箱即用/Out of box

安装/installation

# Via pnpm:
pnpm add mediawiki-api-axios
# Yarn? sure:
yarn add mediawiki-api-axios
# Or just npm:
npm install mediawiki-api-axios

Then, import it to your project:

import { MediaWikiApi } from 'mediawiki-api-axios'
const api = new MediaWikiApi('https://zh.moegirl.org.cn/api.php')
// ...

在浏览器中直接使用/Use directly in the browser

import('https://unpkg.com/mediawiki-api-axios@latest/dist/index.js?module').then(
  ({ MediaWikiApi }) => {
    const api = new MediaWikiApi('https://zh.moegirl.org.cn/api.php')
    // ...
  }
)

Then use it just like the new mw.Api()

使用方法/Usage

You can find some sample code snippets here.

Below is the documentation of MediaWikiApi.

MediaWikiApi {class MediaWikiApi}

Main methods:

Constructor new MediaWikiApi(baseURL?: string, options?: AxiosRequestConfig)

• baseURL: API endpoint of your target wiki site (e.g. https://mediawiki.org/w/api.php)
  • Not required but with conditions: If you are using it in the browser environment, and the website runs MediaWiki. The instance will automatically use the API endpoint of current wiki.
• options: {AxiosRequestConfig}

login(username: string, password: string): Promise<{ status: 'PASS' | 'FAIL'; username: string }>

Login you account.

get<T = any>(params: MwApiParams, options?: AxiosRequestConfig): Promise<AxiosResponse<T>>

Make GET request

post<T = any>(body: MwApiParams, options?: AxiosRequestConfig): Promise<AxiosResponse<T>>

Make POST request

postWithToken<T = any>(tokenType: MwTokenName, body: MwApiParams, options?: AxiosRequestConfig): Promise<AxiosResponse<T>>

Make POST request with specified token.

type MwTokenName =
  | 'createaccount'
  | 'csrf'
  | 'login'
  | 'patrol'
  | 'rollback'
  | 'userrights'
  | 'watch'

Auxiliary utilities

MediaWikiApi.ajax {AxiosInstance} (getter)

Get AxiosInstance of current MediaWikiApi instance

MediaWikiApi#adjustParamValue(params: MwApiParams): Record<string: string> (static)

Adjust input params to standard MediaWiki request params.

• string[] → string: ['foo', 'bar', 'baz'] → 'foo|bar|baz
• false → undefined: remove false items

MediaWikiApi#createAxiosInstance(payload: { baseURL: string; params: MwApiParams; options: AxiosRequestConfig }) (static)

Create your own axios instance.

Warning: The instance created by this method does not include responsive getters/setters (described below) and the out of box cookie controls.

MediaWikiApi.defaultOptions {AxiosRequestOptions} (responsive* getter/setter)

defaults: {}

MediaWikiApi.defaultParams {MwApiParams} (responsive* getter/setter)

defaults:

this.defaultParams = {
  action: 'query',
  errorformat: 'plaintext',
  format: 'json',
  formatversion: 2,
}

*About the responsive getter/setter

Modifying these properties on the instance will automatically recreate the Axios instance of current MediaWikiApi instance. You can modify them directly and safely.

MIT License

Copyright (c) 2022 萌娘百科 User:机智的小鱼君 (A.K.A. Dragon-Fish)