From efd6b2fc8e1ad954365a136b2d9ead691823c6e4 Mon Sep 17 00:00:00 2001 From: ChlodAlejandro Date: Thu, 14 Jul 2022 04:52:32 +0800 Subject: [PATCH 1/3] mw.Rest, mw.ForeignRest --- mw/ForeignRest.d.ts | 59 ++++++++++++++++++ mw/Rest.d.ts | 146 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 mw/ForeignRest.d.ts create mode 100644 mw/Rest.d.ts diff --git a/mw/ForeignRest.d.ts b/mw/ForeignRest.d.ts new file mode 100644 index 0000000..631fd66 --- /dev/null +++ b/mw/ForeignRest.d.ts @@ -0,0 +1,59 @@ +import { RestOptions } from "./Rest"; + +interface ForeignRestOptions extends RestOptions { + /** + * Perform all requests anonymously. Use this option if the target wiki may otherwise not + * accept cross-origin requests, or if you don't need to perform write actions or read + * restricted information and want to avoid the overhead. + */ + anonymous?: boolean; +} + +declare global { + namespace mw { + /** + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignRest + */ + class ForeignRest extends mw.Rest { + /** + * Create an object like `mw.Rest`, but automatically handling everything required + * to communicate with another MediaWiki wiki via cross-origin requests (CORS). + * + * The foreign wiki must be configured to accept requests from the current wiki. See https://www.mediawiki.org/wiki/Manual:$wgCrossSiteAJAXdomains for details. + * + * ```js + * var api = new mw.ForeignRest( 'https://commons.wikimedia.org/w/rest.php' ); + * api.get( '/page/Main_Page/html' ) + * .done( function ( data ) { + * console.log( data ); + * } ); + * ``` + * + * Authentication-related MediaWiki extensions may extend this class to ensure that + * the user authenticated on the current wiki will be automatically authenticated on + * the foreign one. These extension modules should be registered using the + * ResourceLoaderForeignApiModules hook. See CentralAuth for a practical example. + * The general pattern to extend and override the name is: + * + * ```js + * function MyForeignRest() {}; + * OO.inheritClass( MyForeignRest, mw.ForeignRest ); + * mw.ForeignRest = MyForeignRest; + * ``` + * + * @param {string | mw.Uri} url URL pointing to another wiki's rest.php endpoint. + * @param {mw.ForeignApi} foreignActionApi + * @param {ForeignRestOptions?} options + * @since 1.26 + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor + */ + constructor( + url: string | mw.Uri, + foreignActionApi: mw.ForeignApi, + options?: ForeignRestOptions + ); + } + } +} + +export {}; diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts new file mode 100644 index 0000000..93ec0fe --- /dev/null +++ b/mw/Rest.d.ts @@ -0,0 +1,146 @@ +import { + ApiEditPageParams, + ApiParseParams, + ApiQueryAllMessagesParams, + ApiRollbackParams, + ApiUploadParams, +} from "../api_params"; + +export interface RestOptions { + ajax: JQuery.AjaxSettings; +} + +export type RestResponse = Record; // Unknown JSON object + +declare global { + namespace mw { + /** + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest + */ + class Rest { + /** + * Constructor to create an object to interact with the REST API of a particular + * MediaWiki server. mw.Rest objects represent the REST API of a particular + * MediaWiki server. + * + * ```js + * var api = new mw.Rest(); + * api.get( '/v1/page/Main_Page/html' ) + * .done( function ( data ) { + * console.log( data ); + * } ); + * + * api.post( '/v1/page/Main_Page', { + * token: 'anon_token', + * source: 'Lörem Ipsüm', + * comment: 'tästing', + * title: 'My_Page' + * }, { + * 'authorization': 'token' + * } ) + * .done( function ( data ) { + * console.log( data ); + * } ); + * ``` + * + * @param {RestOptions} options + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-constructor + */ + constructor(options?: RestOptions); + + /** + * @private + */ + defaultOptions: RestOptions; + + /** + * Abort all unfinished requests issued by this Api object. + * + * @returns {void} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-abort + */ + abort(): void; + + /** + * Perform REST API get request. + * + * @param {string} path + * @param {Object.} query + * @param {Object.} [headers] + * @returns {JQuery.Promise} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-get + */ + get( + path: string, + query: Record, + headers?: Record + ): JQuery.Promise; + + /** + * Perform REST API post request. + * + * Note: only sending application/json is currently supported. + * + * @param {string} path + * @param {Object.} body + * @param {Object.} [headers] + * @returns {JQuery.Promise} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-post + */ + post( + path: string, + body: Record, + headers?: Record + ): JQuery.Promise; + + /** + * Perform REST API PUT request. + * + * Note: only sending application/json is currently supported. + * + * @param {string} path + * @param {Object.} body + * @param {Object.} [headers] + * @returns {JQuery.Promise} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-put + */ + put( + path: string, + body: Record, + headers?: Record + ): JQuery.Promise; + + /** + * Perform REST API DELETE request. + * + * Note: only sending application/json is currently supported. + * + * @param {string} path + * @param {Object.} body + * @param {Object.} [headers] + * @returns {JQuery.Promise} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-delete + */ + delete( + path: string, + body: Record, + headers?: Record + ): JQuery.Promise; + + /** + * Perform the API call. + * + * @param {string} path + * @param {JQuery.AjaxSettings?} ajaxOptions + * @returns {JQuery.Promise} API response data and the jqXHR object + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax + */ + ajax( + path: string, + ajaxOptions?: JQuery.AjaxSettings + ): JQuery.Promise; + } + } +} + +export {}; From 326eb48bbfd302e3f12241f8444e3a57e0b9cc91 Mon Sep 17 00:00:00 2001 From: ChlodAlejandro Date: Thu, 14 Jul 2022 04:54:25 +0800 Subject: [PATCH 2/3] export Rest classes in index --- mw/index.d.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mw/index.d.ts b/mw/index.d.ts index 1940cdf..cdc1b86 100644 --- a/mw/index.d.ts +++ b/mw/index.d.ts @@ -2,6 +2,7 @@ import "./Api"; import "./config"; import "./cookie"; import "./ForeignApi"; +import "./ForeignRest"; import "./hook"; import "./html"; import "./language"; @@ -10,6 +11,7 @@ import "./log"; import "./Map"; import "./message"; import "./notification"; +import "./Rest"; import "./storage"; import "./template"; import "./Title"; From 4575ae9fdc28921a34454ed9d89fd706d93fcee4 Mon Sep 17 00:00:00 2001 From: ChlodAlejandro Date: Thu, 14 Jul 2022 05:06:18 +0800 Subject: [PATCH 3/3] reformat --- mw/Rest.d.ts | 5 +--- mw/experiments.d.ts | 60 ++++++++++++++++++++++----------------------- mw/message.d.ts | 2 +- 3 files changed, 32 insertions(+), 35 deletions(-) diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts index 93ec0fe..f2b1021 100644 --- a/mw/Rest.d.ts +++ b/mw/Rest.d.ts @@ -135,10 +135,7 @@ declare global { * @returns {JQuery.Promise} API response data and the jqXHR object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ - ajax( - path: string, - ajaxOptions?: JQuery.AjaxSettings - ): JQuery.Promise; + ajax(path: string, ajaxOptions?: JQuery.AjaxSettings): JQuery.Promise; } } } diff --git a/mw/experiments.d.ts b/mw/experiments.d.ts index 97c41d5..89bc5ff 100644 --- a/mw/experiments.d.ts +++ b/mw/experiments.d.ts @@ -1,30 +1,30 @@ -interface Experiment { - /** - * The name of the experiment - */ - name: string; - /** - * Whether the experiment is enabled - */ - enabled: boolean; - /** - * An object consisting of the experiment's buckets ("control" and at least one bucket) and their probabilities (a number < 1, eg 0.25) - */ - buckets: Record; -} - -declare global { - namespace mw { - namespace experiment { - /** - * Get a bucket for a user for the given experiment - * @param {string} token A unique identifier for the user - * @param {Experiment} experiment The expermient to get a bucket from - * @returns {string} The name of the chosen bucket (for example, if the buckets were "control", "a" and "b", it could return "b") - */ - function getBucket(experiment: Experiment, token: string): string; - } - } -} - -export {}; \ No newline at end of file +interface Experiment { + /** + * The name of the experiment + */ + name: string; + /** + * Whether the experiment is enabled + */ + enabled: boolean; + /** + * An object consisting of the experiment's buckets ("control" and at least one bucket) and their probabilities (a number < 1, eg 0.25) + */ + buckets: Record; +} + +declare global { + namespace mw { + namespace experiment { + /** + * Get a bucket for a user for the given experiment + * @param {string} token A unique identifier for the user + * @param {Experiment} experiment The expermient to get a bucket from + * @returns {string} The name of the chosen bucket (for example, if the buckets were "control", "a" and "b", it could return "b") + */ + function getBucket(experiment: Experiment, token: string): string; + } + } +} + +export {}; diff --git a/mw/message.d.ts b/mw/message.d.ts index 0c3c3fe..9493694 100644 --- a/mw/message.d.ts +++ b/mw/message.d.ts @@ -2,7 +2,7 @@ declare global { namespace mw { function message(key: string, ...parameters: string[]): mw.Message; - const messages: mw.Map<{[key: string]: string}>; + const messages: mw.Map<{ [key: string]: string }>; /** * Object constructor for messages.