types-mediawiki-response 1.0.0-alpha.1

package/dist/core/edit.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `action=edit` response — result of a page edit, returned under a top-level
+ * `edit` object.
+ *
+ * Fields present depend on the outcome:
+ * - create: `new: true` plus `oldrevid: 0` / `newrevid` / `newtimestamp`;
+ * - changed: `oldrevid` / `newrevid` / `newtimestamp` (no `new`);
+ * - nochange: `nochange: true`, no revision ids.
+ * `watched` appears when the edit applied a watch. Most hard failures (bad
+ * token, protected page, `createonly` on an existing page) surface as a
+ * top-level {@link ApiErrorResponse}, not `result: "Failure"`.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Edit
+ */
+import type { ContentModel, Flag, Timestamp } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** The `edit` object of an `action=edit` response. */
+export interface ApiEditResult {
+    /** Outcome of the request. Open union; the failure branch is documented below. */
+    result: "Success" | "Failure" | (string & {});
+    /** Page id of the edited page. */
+    pageid?: number;
+    /** Normalized page title. */
+    title?: string;
+    /** Content model of the page. */
+    contentmodel?: ContentModel;
+    /** `true` when the edit created the page. A {@link Flag}. */
+    new?: Flag;
+    /** `true` when the supplied text equaled the current text. A {@link Flag}. */
+    nochange?: Flag;
+    /** `true` when the page was added to the user's watchlist. A {@link Flag}. */
+    watched?: Flag;
+    /**
+     * When the watch applied by this edit expires. Only alongside
+     * {@link watched}, and only when the watch carries an expiry.
+     */
+    watchlistexpiry?: Timestamp;
+    /** Revision id before the edit; `0` when the page was created. */
+    oldrevid?: number;
+    /** Revision id created by the edit. */
+    newrevid?: number;
+    /** Timestamp of the new revision. */
+    newtimestamp?: Timestamp;
+    /**
+     * `true` when the edit auto-created a temporary account for the (formerly
+     * anonymous) editor. A {@link Flag}.
+     *
+     * @since MediaWiki 1.41
+     */
+    tempusercreated?: Flag;
+    /**
+     * Full URL to redirect to after a temporary-account auto-creation.
+     * Present only alongside {@link tempusercreated}.
+     *
+     * @since MediaWiki 1.41
+     */
+    tempusercreatedredirect?: string;
+    /** Machine-readable failure code. */
+    code?: string;
+    /** Human-readable failure description. */
+    info?: string;
+}
+/** Response of `action=edit`. */
+export interface ApiEditResponse extends ApiEnvelope {
+    edit: ApiEditResult;
+}

package/dist/core/emailuser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `action=emailuser` response — sends an email to another user; needs CSRF and
+ * both the sender's `sendemail` right and a confirmed address. The result keys
+ * under `emailuser`.
+ *
+ * `ApiEmailUser` reports the outcome **in-band** (not as a top-level
+ * {@link ApiErrorResponse}): `result` is `Success`, `Warnings`, or `Failure`,
+ * and `warnings`/`errors` carry message specs. The keys are dropped when the
+ * status carries none of that kind — except under the default `bc`
+ * `errorformat`, which keeps them as empty arrays. A `Failure` also occurs on
+ * a wiki without a mail transport.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Email
+ */
+import type { ApiSpecMessage } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** Response of `action=emailuser`. */
+export interface ApiEmailUserResponse extends ApiEnvelope {
+    emailuser: {
+        /** Whether the message was accepted, or accepted with warnings, or failed. */
+        result: "Success" | "Warnings" | "Failure" | (string & {});
+        /** Non-fatal messages (e.g. subject/text transformations). */
+        warnings?: ApiSpecMessage[];
+        /** In-band delivery errors (present when `result` is `Failure`). */
+        errors?: ApiSpecMessage[];
+    };
+}

package/dist/core/expandtemplates.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `action=expandtemplates` response — expands wikitext (resolving templates and
+ * variables) without a full page parse, returned under a top-level
+ * `expandtemplates` object. Useful to preview template output or collect the
+ * page properties a snippet would set.
+ *
+ * Under `formatversion=2` `volatile` is a real boolean. `properties` carries
+ * settings parsed from magic words (e.g. `defaultsort` from `{{DEFAULTSORT}}`).
+ *
+ * @see https://www.mediawiki.org/wiki/API:Parsing_wikitext#expandtemplates
+ */
+import type { ApiEnvelope } from "../envelope";
+/** Page settings surfaced by `prop=properties`. Open key set. */
+export interface ApiExpandTemplatesProperties {
+    /** Sort key set by `{{DEFAULTSORT}}`. */
+    defaultsort?: string;
+    /** Display title set by `{{DISPLAYTITLE}}`. */
+    displaytitle?: string;
+    /** Other page properties set by parser functions or hooks. */
+    [key: string]: unknown;
+}
+/** One category the output would add. */
+export interface ApiExpandTemplatesCategory {
+    /** Category name. */
+    category: string;
+    /** Sort key; empty string when the default sort key applies. */
+    sortkey: string;
+}
+/** The `expandtemplates` object of a successful response. */
+export interface ApiExpandTemplatesResult {
+    /** The expanded wikitext. `prop=wikitext`. */
+    wikitext?: string;
+    /** XML parse tree of the input wikitext. `prop=parsetree`. */
+    parsetree?: string;
+    /** Whether the result varies per-user / request. `prop=volatile`; a real `boolean`. */
+    volatile?: boolean;
+    /** Cache TTL in seconds; `prop=ttl`, present only when the frame carries one. */
+    ttl?: number;
+    /** Page settings parsed from the output. `prop=properties`. */
+    properties?: ApiExpandTemplatesProperties;
+    /** Categories the output would add. `prop=categories`; absent when the output adds none. */
+    categories?: ApiExpandTemplatesCategory[];
+    /** ResourceLoader modules the output depends on. `prop=modules`. */
+    modules?: string[];
+    /** Always empty; deprecated. Emitted with `prop=modules`. */
+    modulescripts?: never[];
+    /** ResourceLoader module styles the output depends on. `prop=modules`. */
+    modulestyles?: string[];
+    /** Parser-magic JS config variables. `prop=jsconfigvars`. */
+    jsconfigvars?: unknown;
+    /** The JS config variables serialized as a JSON string. `prop=encodedjsconfigvars`. */
+    encodedjsconfigvars?: string;
+}
+/** Response of `action=expandtemplates`. */
+export interface ApiExpandTemplatesResponse extends ApiEnvelope {
+    expandtemplates: ApiExpandTemplatesResult;
+    /**
+     * XML parse tree of the input wikitext, emitted at the root level (outside
+     * {@link expandtemplates}) by the legacy `generatexml` parameter; with
+     * `prop=parsetree` the same tree is reported inside
+     * {@link ApiExpandTemplatesResult.parsetree} instead.
+     *
+     * @deprecated since MediaWiki 1.25 (`generatexml`); use `prop=parsetree`.
+     */
+    parsetree?: string;
+}

package/dist/core/filerevert.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `action=filerevert` response — reverts a file to an older archived version;
+ * needs CSRF, title-level `edit`/`upload` rights on the file, and `reupload`
+ * (or `reupload-own` when reverting one's own upload). The result keys under
+ * `filerevert`: `result` is `Success`, or `Failure` with an in-band `errors`
+ * array (a per-item outcome, not a top-level {@link ApiErrorResponse}).
+ *
+ * @see https://www.mediawiki.org/wiki/API:Filerevert
+ */
+import type { ApiSpecMessage } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** Response of `action=filerevert`. */
+export interface ApiFileRevertResponse extends ApiEnvelope {
+    filerevert: {
+        /** Outcome of the revert. */
+        result: "Success" | "Failure" | (string & {});
+        /** In-band messages when the revert did not apply. */
+        errors?: ApiSpecMessage[];
+    };
+}

package/dist/core/imagerotate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `action=imagerotate` response — rotates a file by 90/180/270°, creating a new
+ * archived version; needs CSRF and title-level `edit`/`upload` rights on the
+ * file. The result is a top-level `imagerotate` **array** with one entry per
+ * targeted file.
+ *
+ * A per-file failure is reported in-band (`result:"Failure"` plus an `errors`
+ * array), not as a top-level error: the hard checks fail with
+ * `apierror-filedoesnotexist` / `apierror-filetypecannotberotated` /
+ * `apierror-filenopath`, and an otherwise failed rotation/upload surfaces the
+ * message codes of its Status (e.g. `backend-fail-*` from file storage).
+ * Titles the pageSet could not resolve (invalid, special, interwiki, missing)
+ * come back as problem entries without a `result`.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Imagerotate
+ */
+import type { Flag, NamespaceIndex, ApiSpecMessage } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** One file entry of an `action=imagerotate` response. */
+export interface ApiImageRotateEntry {
+    /** Page id of the file (keyed as `id`, not `pageid`). */
+    id?: number;
+    /** Page id, for entries describing a `pageid=` that did not resolve. */
+    pageid?: number;
+    /** Revision id, for entries describing a `revid=` that did not resolve. */
+    revid?: number;
+    /** Namespace index (6 = File). */
+    ns?: NamespaceIndex;
+    /** File title. */
+    title?: string;
+    /** The title does not correspond to an existing page. A {@link Flag}. */
+    missing?: Flag;
+    /** A `missing` title that is nonetheless "known" (e.g. a redlinked file). A {@link Flag}. */
+    known?: Flag;
+    /** The requested title is malformed or otherwise invalid. A {@link Flag}. */
+    invalid?: Flag;
+    /** Reason the title is invalid (localized wikitext), alongside `invalid`. */
+    invalidreason?: string;
+    /** The requested title is a Special: page (not rotated). A {@link Flag}. */
+    special?: Flag;
+    /** Interwiki prefix, for entries describing an interwiki title. */
+    iw?: string;
+    /** Per-file outcome. */
+    result?: "Success" | "Failure" | (string & {});
+    /** In-band messages when the rotation failed. */
+    errors?: ApiSpecMessage[];
+}
+/** Response of `action=imagerotate`. */
+export interface ApiImageRotateResponse extends ApiEnvelope {
+    imagerotate: ApiImageRotateEntry[];
+}

package/dist/core/import.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `action=import` response — imports pages from an XML dump (uploaded file or an
+ * interwiki source); needs CSRF and the `import` (and `importupload` for file
+ * uploads) right. The result is a top-level `import` **array**, one entry per
+ * imported page.
+ *
+ * Shape comes from `ApiImportReporter::reportPage` (via `ApiQueryBase::addTitleInfo`):
+ * a successful page carries `ns`/`title` plus a `revisions` count; an
+ * un-importable title carries `title` + an `invalid` flag.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Import
+ */
+import type { Flag, NamespaceIndex } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** One imported page reported by `action=import`. */
+export interface ApiImportEntry {
+    /** Target namespace the page was imported into. */
+    ns?: NamespaceIndex;
+    /** Imported page title. */
+    title?: string;
+    /** Number of revisions successfully imported. */
+    revisions?: number;
+    /** The title was invalid or non-importable. A {@link Flag}. */
+    invalid?: Flag;
+}
+/** Response of `action=import`. */
+export interface ApiImportResponse extends ApiEnvelope {
+    import: ApiImportEntry[];
+}

package/dist/core/index.d.ts

@@ -0,0 +1,40 @@
+export * from "./query";
+export * from "./parse";
+export * from "./compare";
+export * from "./edit";
+export * from "./move";
+export * from "./purge";
+export * from "./delete";
+export * from "./block";
+export * from "./watch";
+export * from "./rollback";
+export * from "./patrol";
+export * from "./options";
+export * from "./expandtemplates";
+export * from "./protect";
+export * from "./revisiondelete";
+export * from "./checktoken";
+export * from "./languagesearch";
+export * from "./acquiretempusername";
+export * from "./clearhasmsg";
+export * from "./validatepassword";
+export * from "./userrights";
+export * from "./changecontentmodel";
+export * from "./setpagelanguage";
+export * from "./managetags";
+export * from "./tag";
+export * from "./mergehistory";
+export * from "./setnotificationtimestamp";
+export * from "./emailuser";
+export * from "./clientlogin";
+export * from "./resetpassword";
+export * from "./createaccount";
+export * from "./changeauthenticationdata";
+export * from "./removeauthenticationdata";
+export * from "./login";
+export * from "./logout";
+export * from "./filerevert";
+export * from "./imagerotate";
+export * from "./stashedit";
+export * from "./upload";
+export * from "./import";

package/dist/core/languagesearch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `action=languagesearch` response — searches language names for autocomplete
+ * UIs. Matches by exact code, then by prefix/infix on the name in the user's
+ * language or the autonym; `typos` enables Levenshtein-tolerant matching
+ * (default 1).
+ *
+ * Core since 1.46 (previously served by the Universal Language Selector
+ * extension).
+ *
+ * @see https://www.mediawiki.org/wiki/API:Languagesearch
+ * @since MediaWiki 1.46
+ */
+import type { ApiEnvelope } from "../envelope";
+/** Response of `action=languagesearch`. */
+export interface ApiLanguageSearchResponse extends ApiEnvelope {
+    /**
+     * Matched languages keyed by language code, with the display name as the
+     * value (e.g. `"zh": "zh – chinese"`). Exact code matches come first; the
+     * remaining order is deterministic (grouped by the script of the first
+     * character, prefix matches before infix). A PHP map, so an empty result
+     * serializes as `[]`.
+     */
+    languagesearch?: Record<string, string> | unknown[];
+}

package/dist/core/login.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `action=login` response — the legacy main-account login. **Deprecated** in
+ * favour of `action=clientlogin`; core emits a `login` deprecation warning
+ * (an {@link ApiEnvelope} `warnings` fact) alongside the result. Modeled anyway
+ * because clients still call it.
+ *
+ * `ApiLogin` emits `result` (`Success`/`Failed`/`NeedToken`/`WrongToken`/
+ * `Aborted`) plus, on success, `lguserid`/`lgusername`; `token` and `reason`
+ * appear on the respective paths. Throttled logins are not a separate result —
+ * they surface as `Failed` with a `login-throttled` reason. The response
+ * carries no `cookieprefix`/`sessionid`.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Login
+ */
+import type { ApiEnvelope } from "../envelope";
+/** Response of the deprecated `action=login`. */
+export interface ApiLoginResponse extends ApiEnvelope {
+    login: {
+        /** Login outcome. */
+        result: "Success" | "Failed" | "NeedToken" | "WrongToken" | "Aborted" | (string & {});
+        /** Human-readable reason, emitted when `result` is `Failed` or `Aborted`. */
+        reason?: string;
+        /** Login token echoed back on a `NeedToken` round trip. */
+        token?: string;
+        /** User id of the logged-in account (legacy `lguserid` spelling). */
+        lguserid?: number;
+        /** User name of the logged-in account (legacy `lgusername` spelling). */
+        lgusername?: string;
+    };
+}

package/dist/core/logout.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `action=logout` response — logs the current session out; needs CSRF. 1.43's
+ * `ApiLogout` calls `addValue` on **no** key: a successful logout returns an
+ * empty body (only the response {@link ApiEnvelope} remains). Logging out an
+ * anonymous session adds a `notloggedin` warning to the envelope.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Logout
+ */
+import type { ApiEnvelope } from "../envelope";
+/**
+ * Response of `action=logout`. No payload keys are emitted on success; the type
+ * exists so the shape is explicit (the `logout.status` object older builds
+ * returned is gone in 1.43).
+ */
+export interface ApiLogoutResponse extends ApiEnvelope {
+}

package/dist/core/managetags.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `action=managetags` response — defines/removes change tags; needs CSRF. As
+ * written in 1.43 core, every operation (including non-delete ones) requires
+ * the `deletechangetags` right, and operations other than `delete` additionally
+ * require `managechangetags`. The result echoes the operation under
+ * `managetags`.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Managetags
+ */
+import type { ApiSpecMessage } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** `action=managetags` operation. Open union for forward compatibility. */
+export type ApiManageTagsOperation = "activate" | "create" | "deactivate" | "delete" | (string & {});
+/** Response of `action=managetags`. */
+export interface ApiManageTagsResponse extends ApiEnvelope {
+    managetags: {
+        /** The operation that was performed. */
+        operation: ApiManageTagsOperation;
+        /** Tag name acted on. */
+        tag: string;
+        /** Whether the operation succeeded. */
+        success: boolean;
+        /** Log entry id recorded for the operation. */
+        logid?: number;
+        /** Non-fatal messages (e.g. a deprecation notice). */
+        warnings?: ApiSpecMessage[];
+    };
+}

package/dist/core/mergehistory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `action=mergehistory` response — merges the revision history of one page into
+ * another; needs CSRF and the `mergehistory` (sysop) right. The result keys under
+ * `mergehistory`.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Mergehistory
+ */
+import type { Timestamp } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** Response of `action=mergehistory`. */
+export interface ApiMergeHistoryResponse extends ApiEnvelope {
+    mergehistory: {
+        /** Source page title (history moved out of). */
+        from: string;
+        /** Destination page title (history merged into). */
+        to: string;
+        /**
+         * Cutoff timestamp up to which revisions were merged, as ISO 8601. Echoes
+         * the `timestamp` parameter when supplied; with a full-history merge (no
+         * `timestamp` given) it is the current server time.
+         */
+        timestamp: Timestamp;
+        /** Reason supplied with the merge; `''` when none was given. */
+        reason: string;
+    };
+}

package/dist/core/move.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `action=move` response — result of renaming/moving a page, returned under a
+ * top-level `move` object.
+ *
+ * Note under `formatversion=2`: `redirectcreated` / `moveoverredirect` /
+ * `talkmoveoverredirect` are real booleans (present as `false`), `reason` is
+ * always present (`''` when none was supplied), and there is **no `result`
+ * key** on a successful move. `subpages` is polymorphic: an array of per-subpage
+ * outcomes when any subpage could be processed, or an object `{ errors }` when
+ * the whole subpage move failed (e.g. the namespace forbids them).
+ *
+ * @see https://www.mediawiki.org/wiki/API:Move
+ */
+import type { ApiSpecMessage } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/** One subpage move outcome within `subpages`/`subpages-talk`. */
+export interface ApiMoveSubpage {
+    /** Old subpage title. */
+    from?: string;
+    /** New subpage title, when the subpage moved. */
+    to?: string;
+    /** Why the subpage did not move, when it failed. */
+    errors?: ApiSpecMessage[];
+}
+/** The object form of `subpages`, returned only when the whole move failed. */
+export interface ApiMoveSubpageErrors {
+    /** Why no subpage could be moved. */
+    errors?: ApiSpecMessage[];
+}
+/** The `move` object of a successful `action=move` response. */
+export interface ApiMoveResult {
+    /** Original title. */
+    from: string;
+    /** New title. */
+    to: string;
+    /** Move reason (the edit summary); `''` when none was supplied. */
+    reason: string;
+    /** Whether a redirect was left at `from`. A real `boolean`. */
+    redirectcreated: boolean;
+    /** Whether the destination title already existed (redirect or not). A real `boolean`. */
+    moveoverredirect: boolean;
+    /** Original talk-page title (present with `movetalk=1`). */
+    talkfrom?: string;
+    /** New talk-page title (present with `movetalk=1`). */
+    talkto?: string;
+    /** Whether the talk-page destination already existed (redirect or not). A real `boolean`. */
+    talkmoveoverredirect?: boolean;
+    /** Why the talk-page move failed, instead of `talkfrom`/`talkto`. */
+    "talkmove-errors"?: ApiSpecMessage[];
+    /**
+     * Subpage move outcome (`movesubpages=1`). `formatversion=2` returns either
+     * an array of per-subpage outcomes or an object of errors, so both shapes are
+     * allowed.
+     */
+    subpages?: ApiMoveSubpage[] | ApiMoveSubpageErrors;
+    /** Talk subpage outcome (`movesubpages=1` + `movetalk=1`); same polymorphism as `subpages`. */
+    "subpages-talk"?: ApiMoveSubpage[] | ApiMoveSubpageErrors;
+}
+/** Response of `action=move`. */
+export interface ApiMoveResponse extends ApiEnvelope {
+    move: ApiMoveResult;
+}

package/dist/core/options.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `action=options` response — changing (or resetting) user preferences. Set via
+ * `optionname`/`optionvalue` (or `change=name=value&…`, or `reset=1`), with a
+ * CSRF token.
+ *
+ * On success `options` is the plain string `"success"`. Errors surface as a
+ * top-level {@link ApiErrorResponse}.
+ *
+ * @see https://www.mediawiki.org/wiki/API:Options
+ */
+import type { ApiEnvelope } from "../envelope";
+/** Response of `action=options`. */
+export interface ApiOptionsResponse extends ApiEnvelope {
+    /** Success sentinel (`"success"`); failures come back as a top-level error. */
+    options: "success" | (string & {});
+}