Merge pull request #14 from ChlodAlejandro/main

`Rest`, `ForeignRest`

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 {};

mw/Rest.d.ts

@@ -0,0 +1,143 @@
+import {
+    ApiEditPageParams,
+    ApiParseParams,
+    ApiQueryAllMessagesParams,
+    ApiRollbackParams,
+    ApiUploadParams,
+} from "../api_params";
+
+export interface RestOptions {
+    ajax: JQuery.AjaxSettings;
+}
+
+export type RestResponse = Record<string, any>; // 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.<string, any>} query
+             * @param {Object.<string, any>} [headers]
+             * @returns {JQuery.Promise<RestResponse>}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-get
+             */
+            get(
+                path: string,
+                query: Record<string, any>,
+                headers?: Record<string, any>
+            ): JQuery.Promise<RestResponse>;
+
+            /**
+             * Perform REST API post request.
+             *
+             * Note: only sending application/json is currently supported.
+             *
+             * @param {string} path
+             * @param {Object.<string, any>} body
+             * @param {Object.<string, any>} [headers]
+             * @returns {JQuery.Promise<RestResponse>}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-post
+             */
+            post(
+                path: string,
+                body: Record<string, any>,
+                headers?: Record<string, any>
+            ): JQuery.Promise<RestResponse>;
+
+            /**
+             * Perform REST API PUT request.
+             *
+             * Note: only sending application/json is currently supported.
+             *
+             * @param {string} path
+             * @param {Object.<string, any>} body
+             * @param {Object.<string, any>} [headers]
+             * @returns {JQuery.Promise<RestResponse>}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-put
+             */
+            put(
+                path: string,
+                body: Record<string, any>,
+                headers?: Record<string, any>
+            ): JQuery.Promise<RestResponse>;
+
+            /**
+             * Perform REST API DELETE request.
+             *
+             * Note: only sending application/json is currently supported.
+             *
+             * @param {string} path
+             * @param {Object.<string, any>} body
+             * @param {Object.<string, any>} [headers]
+             * @returns {JQuery.Promise<RestResponse>}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-delete
+             */
+            delete(
+                path: string,
+                body: Record<string, any>,
+                headers?: Record<string, any>
+            ): JQuery.Promise<RestResponse>;
+
+            /**
+             * Perform the API call.
+             *
+             * @param {string} path
+             * @param {JQuery.AjaxSettings?} ajaxOptions
+             * @returns {JQuery.Promise<RestResponse>} 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<RestResponse>;
+        }
+    }
+}
+
+export {};

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<string, number>;
-}
-
-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 {};
+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<string, number>;
+}
+
+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 {};

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";

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.