wiki-saikou

Wiki Saikou

SUPER COOL api package for MediaWiki

- 同时兼容浏览器&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 wiki-saikou
# Yarn? sure:
yarn add wiki-saikou
# Or just npm:
npm install wiki-saikou

Then, import it to your project:

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

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

import('https://unpkg.com/wiki-saikou?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:

new MediaWikiApi(baseURL?: string, options?: Partial<FexiosConfigs>)

• 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: {LylaRequestOptions}

login(username: string, password: string): Promise<{ result: 'Success' | 'Failed'; lguserid: number; lgusername: string }>

Login your account.

get<T = any>(params: MwApiParams, options?: FexiosRequestOptions): Promise<FexiosFinalContext<T>>

Make GET request

post<T = any>(body: MwApiParams, options?: LylaRequestOptions): Promise<FexiosFinalContext<T>>

Make POST request

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

Make POST request with specified token.

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

工具函数 Auxiliary utilities

get request {Fexios}

Get Fexios instance of current MediaWikiApi instance

MediaWikiApi.normalizeParamValue(params: MwApiParams[keyof MwApiParams]): string | File | undefined (static)

Normalize input params to standard MediaWiki request params.

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

MediaWikiApi.createRequestHandler(baseURL: string, options?: Partial<FexiosRequestOptions>): Fexios (static)

Create your own Fexios instance.

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

get/set defaultOptions {AxiosRequestOptions} (responsive* getter/setter)

defaults: {}

get/set 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)