types-mediawiki-response 1.1.0 → 1.2.0

package/dist/extensions/centralauth.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Opt-in extension pack: **CentralAuth** (`list=globalallusers`,
+ * `list=globalgroups`, `list=globalusers`, `list=wikisets`,
+ * `action=centralauthtoken`, `action=globaluserrights`,
+ * `action=setglobalaccountstatus`, `action=deleteglobalaccount`,
+ * `action=createlocalaccount`).
+ *
+ * Not in the default export: importing anything from this file — even just the
+ * field-group type you are about to use — activates the augmentation shipped at
+ * the bottom, which merges the field groups into the root package automatically
+ * (no manual `declare module`):
+ *
+ * ```ts
+ * import type {} from 'types-mediawiki-response/ext/centralauth';
+ * ```
+ *
+ * fv2 notes: `list=globalallusers` ids are real numbers, while `list=wikisets`
+ * carries the database id **as a string up to MediaWiki 1.45 and as a number
+ * from 1.46** (its `WikiSet::newFromRow` picked up an `intval()` cast). When a
+ * write action's operation fails — `createlocalaccount`, or the unmerge /
+ * lock-hide step of `deleteglobalaccount` / `setglobalaccountstatus` — the
+ * messages are reported **in band** under the root `error` key as a nested list
+ * of {@link ApiSpecMessage} rows rather than as a standard `ApiErrorResponse`;
+ * `setglobalaccountstatus` still returns its (unchanged) result object alongside
+ * that `error` key. Input validation failures (e.g. an unknown global account)
+ * are ordinary top-level errors.
+ *
+ * @see https://www.mediawiki.org/wiki/Extension:CentralAuth
+ */
+import type { ApiSpecMessage } from "../common";
+import type { Expiry, Timestamp } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/**
+ * One `list=globalallusers` entry. `aguprop` controls which fields beyond
+ * {@link ApiGlobalCentralUser.id} / {@link ApiGlobalCentralUser.name} appear.
+ * Hidden accounts (suppressed from public lists) never appear here at all.
+ */
+export interface ApiGlobalCentralUser {
+    /** Global account id. */
+    id: number;
+    /** Global account name. */
+    name: string;
+    /**
+     * Global groups of the account, `[]` when it is in none. `aguprop=groups`.
+     * Expired group memberships are not included.
+     */
+    groups?: string[];
+    /**
+     * The account is attached to (has a local account on) the requesting wiki;
+     * an empty-string marker (stays `""` under fv2 rather than becoming `true`).
+     * `aguprop=existslocally`.
+     */
+    existslocally?: "";
+    /**
+     * The account is locked globally; an empty-string marker (see
+     * {@link ApiGlobalCentralUser.existslocally}). `aguprop=lockinfo`.
+     */
+    locked?: "";
+}
+/**
+ * One `list=globalgroups` entry: a global group defined on the wiki farm. The
+ * rows derive from the `global_group_permissions` table, so groups are only
+ * listed once they have at least one permission granted.
+ */
+export interface ApiGlobalGroup {
+    /** Global group name, e.g. `global-sysop` (site-configured, not fixed). */
+    name: string;
+    /** Permissions granted to the group. `ggpprop=rights`. */
+    rights?: string[];
+}
+/**
+ * One `list=wikisets` entry: a named wiki set (a list of wikis used for global
+ * group restrictions). The key set is farm-configured.
+ */
+export interface ApiWikiSet {
+    /**
+     * Wiki set id. A string up to MediaWiki 1.45 (fv2 passes the raw `ws_id`
+     * column through), a number from 1.46 once the value is cast to int.
+     */
+    id: string | number;
+    /** Wiki set name. */
+    name: string;
+    /** Whether the set lists included (`optin`) or excluded (`optout`) wikis. */
+    type?: "optin" | "optout";
+    /**
+     * Wikis the set covers (for `optin`) or does not cover (for `optout`), `[]`
+     * when none. Present whenever `wsprop` includes it.
+     */
+    wikisincluded?: string[];
+    /**
+     * The complement of {@link ApiWikiSet.wikisincluded} against all known wikis,
+     * `[]` when none. Present whenever `wsprop` includes it.
+     */
+    wikisnotincluded?: string[];
+}
+/**
+ * Result of `action=globaluserrights` (userrights-token POST): global group
+ * memberships changed for one global account. Mirrors the core
+ * `action=userrights` result shape.
+ */
+export interface ApiGlobalUserRightsResult {
+    /** The affected global account name. */
+    user: string;
+    /** Global account id. */
+    userid: number;
+    /** Groups added by this call (empty when only removing). */
+    added: string[];
+    /** Groups removed by this call (empty when only adding). */
+    removed: string[];
+}
+/** Response of `action=globaluserrights`. Failures are standard top-level errors. */
+export interface ApiGlobalUserRightsResponse extends ApiEnvelope {
+    /** Result of `action=globaluserrights`. */
+    globaluserrights: ApiGlobalUserRightsResult;
+}
+/**
+ * The lock / hide state of a global account, written by
+ * `action=setglobalaccountstatus` on every outcome. The success response
+ * extends it with {@link ApiSetGlobalAccountStatusResult.reason}; a failed call
+ * reports only this state, alongside the in-band root `error` list.
+ */
+export interface ApiSetGlobalAccountStatusState {
+    /** The affected global account name. */
+    user: string;
+    /** Whether the account is locked after the call. */
+    locked: boolean;
+    /**
+     * Suppression level after the call: visible (`""`), hidden from lists, or
+     * fully suppressed.
+     */
+    hidden: "" | "lists" | "suppressed";
+}
+/**
+ * Result object of `action=setglobalaccountstatus` (its own token type POST):
+ * the new lock / hide state of a global account plus the reason echoed back.
+ */
+export interface ApiSetGlobalAccountStatusResult extends ApiSetGlobalAccountStatusState {
+    /** The reason passed to the call; `null` when none was given. */
+    reason: string | null;
+}
+/**
+ * Successful response of `action=setglobalaccountstatus`. A failed lock/hide
+ * returns the unchanged state (without `reason`) plus an in-band root `error`
+ * — see {@link ApiSetGlobalAccountStatusFailedResponse}.
+ */
+export interface ApiSetGlobalAccountStatusResponse extends ApiEnvelope {
+    /** Result of `action=setglobalaccountstatus`. */
+    setglobalaccountstatus: ApiSetGlobalAccountStatusResult;
+}
+/**
+ * In-band failure of `action=setglobalaccountstatus`: the unchanged state object
+ * is returned without `reason`, alongside the root `error` list as a nested
+ * {@link ApiSpecMessage} list rather than a standard `ApiErrorResponse`. Use
+ * `ApiResponseWith` to model either outcome.
+ */
+export interface ApiSetGlobalAccountStatusFailedResponse extends ApiEnvelope {
+    /** The unchanged lock / hide state after the failed call. */
+    setglobalaccountstatus: ApiSetGlobalAccountStatusState;
+    /** In-band failure messages. */
+    error: ApiSpecMessage[][];
+}
+/**
+ * Result of `action=deleteglobalaccount` (its own token type POST): the global
+ * account was unmerged (deleted).
+ */
+export interface ApiDeleteGlobalAccountResult {
+    /** The deleted global account name. */
+    user: string;
+    /** The reason passed to the call; `null` when none was given. */
+    reason: string | null;
+}
+/** Response of `action=deleteglobalaccount`. */
+export interface ApiDeleteGlobalAccountResponse extends ApiEnvelope {
+    /** Result of `action=deleteglobalaccount`. */
+    deleteglobalaccount: ApiDeleteGlobalAccountResult;
+}
+/**
+ * Result of `action=createlocalaccount` (CSRF-token POST, `centralauth-createlocal`
+ * right): a local account was force-created on this wiki for the global account.
+ *
+ * @since MediaWiki 1.36
+ */
+export interface ApiCreateLocalAccountResult {
+    /** The user name a local account was created for. */
+    username: string;
+    /** The reason passed to the call; `null` when none was given. */
+    reason: string | null;
+}
+/**
+ * Response of `action=createlocalaccount`. Unlike `setglobalaccountstatus`, a
+ * failure returns only the root `error` list and no result object.
+ *
+ * @since MediaWiki 1.36
+ */
+export interface ApiCreateLocalAccountResponse extends ApiEnvelope {
+    /** Result of `action=createlocalaccount`. */
+    createlocalaccount: ApiCreateLocalAccountResult;
+}
+/**
+ * Response of `action=centralauthtoken`: a token that authenticates the
+ * current CentralAuth session on another wiki of the farm (sent as the
+ * `centralauthtoken` parameter there). Requires a logged-in user attached to
+ * a global account whose session comes from the CentralAuth session provider;
+ * every other case is a standard top-level error (`notloggedin`, `badsession`,
+ * `notattached`).
+ */
+export interface ApiCentralAuthTokenResponse extends ApiEnvelope {
+    centralauthtoken: {
+        /** The cross-wiki authentication token. */
+        centralauthtoken: string;
+    };
+}
+/**
+ * In-band failure of `action=deleteglobalaccount` / `action=createlocalaccount`:
+ * the messages appear under the root `error` key as a list of per-status
+ * lists — not as a standard {@link ApiErrorResponse} — so `error` carries no
+ * `code`/`info` of its own.
+ */
+export interface ApiCentralAuthInBandErrorResponse extends ApiEnvelope {
+    error: ApiSpecMessage[][];
+}
+/**
+ * One `list=globalusers` entry for an existing global account. `gusprop`
+ * controls which fields beyond {@link ApiGlobalUserFound.centralid} /
+ * {@link ApiGlobalUserFound.name} appear. Results come back in request order;
+ * unknown names/ids get marker rows (see {@link ApiGlobalUserRow}).
+ */
+export interface ApiGlobalUserFound {
+    /** Global account id. */
+    centralid: number;
+    /** Global account name. */
+    name: string;
+    /**
+     * The account is hidden from public lists; a real `true`. Only observable to
+     * requesters with the `centralauth-suppress` right — for everyone else the
+     * row is replaced by a `missing` marker.
+     */
+    hidden?: true;
+    /**
+     * The account is fully suppressed; a real `true`. Same visibility rule as
+     * {@link ApiGlobalUserFound.hidden}.
+     */
+    suppressed?: true;
+    /** Whether the account is locked globally. `gusprop=locked`. */
+    locked?: boolean;
+    /**
+     * Log id of the most recent lock on the account (for a follow-up
+     * `list=logevents` on the central wiki); present only when locked.
+     */
+    locklogid?: number;
+    /** Global edit count. `gusprop=editcount`. */
+    editcount?: number;
+    /** When the global account was created. `gusprop=registration`. */
+    registration?: Timestamp;
+    /**
+     * Attachment status on the requesting wiki. `gusprop=localinfo`;
+     * {@link ApiGlobalUserLocalInfo.localid} /
+     * {@link ApiGlobalUserLocalInfo.timestamp} are only present when attached.
+     */
+    localinfo?: ApiGlobalUserLocalInfo;
+    /** Global groups of the account (active ones only). `gusprop=groups`. */
+    groups?: string[];
+    /**
+     * Global group memberships with expiry. `gusprop=groupmemberships`.
+     */
+    groupmemberships?: ApiGlobalGroupMembership[];
+    /** Permissions derived from the account's global groups. `gusprop=rights`. */
+    rights?: string[];
+}
+/** The `localinfo` object of a `list=globalusers` row. */
+export interface ApiGlobalUserLocalInfo {
+    /** The account has a local account on the requesting wiki. */
+    attached: boolean;
+    /** Local user id; `null` when recorded without one. Only when attached. */
+    localid?: number | null;
+    /** When the local account was attached. Only when attached. */
+    timestamp?: Timestamp | null;
+}
+/** One global group membership of a `list=globalusers` row. */
+export interface ApiGlobalGroupMembership {
+    /** Global group name. */
+    group: string;
+    /** Membership expiry, or `infinity`. */
+    expiry: Expiry;
+}
+/** A `list=globalusers` row for a requested name with no global account. */
+export interface ApiGlobalUserMissingName {
+    /** The requested name, echoed back. */
+    name: string;
+    /** Marker: no global account under this name. */
+    missing: true;
+}
+/** A `list=globalusers` row for a requested name that is not a valid username. */
+export interface ApiGlobalUserInvalidName {
+    /** The requested name, echoed back as given. */
+    name: string;
+    /** Marker: not a valid username. */
+    invalid: true;
+}
+/** A `list=globalusers` row for a requested global id with no global account. */
+export interface ApiGlobalUserMissingId {
+    /** The requested global id, echoed back. */
+    centralid: number;
+    /** Marker: no global account with this id. */
+    missing: true;
+}
+/**
+ * One `list=globalusers` row: either a found account
+ * ({@link ApiGlobalUserFound}) or a marker for a name/id that is unknown
+ * (`missing`), syntactically invalid (`invalid`), or hidden from the requester
+ * (`missing` again — hidden accounts are reported as absent).
+ */
+export type ApiGlobalUserRow = ApiGlobalUserFound | ApiGlobalUserMissingName | ApiGlobalUserInvalidName | ApiGlobalUserMissingId;
+declare module "types-mediawiki-response" {
+    interface ApiQueryResult {
+        /** All global accounts of the farm, name-ordered (`list=globalallusers`). */
+        globalallusers?: ApiGlobalCentralUser[];
+        /** Global groups defined on the farm (`list=globalgroups`). */
+        globalgroups?: ApiGlobalGroup[];
+        /** Per-name/per-id global account lookup (`list=globalusers`).
+         *
+         * @since MediaWiki 1.47
+         */
+        globalusers?: ApiGlobalUserRow[];
+        /** Wiki sets defined on the farm (`list=wikisets`). */
+        wikisets?: ApiWikiSet[];
+    }
+}

package/dist/extensions/checkuser.d.ts

@@ -1,5 +1,6 @@
 /**
- * Opt-in extension pack: **CheckUser** (`list=checkuser`, `list=checkuserlog`).
+ * Opt-in extension pack: **CheckUser** (`list=checkuser`, `list=checkuserlog`,
+ * `meta=checkuserformattedblockinfo`).
  *
  * Not in the default export: importing anything from this file — even just the
  * field-group type you are about to use — activates the augmentation shipped at
@@ -139,11 +140,28 @@ export interface ApiQueryCheckUserLogResult {
     /** Log entries, ordered per `culdir` (default newest first). */
     entries?: ApiCheckUserLogEntry[];
 }
+/**
+ * The `checkuserformattedblockinfo` object: the sitewide-block status of the
+ * requesting user, for clients that need to explain API failures caused by
+ * their own block.
+ *
+ * @since MediaWiki 1.44
+ */
+export interface ApiQueryCheckUserFormattedBlockInfoResult {
+    /**
+     * Rendered (HTML) block message explaining the sitewide block; `null` when
+     * the requesting user is not sitewide-blocked. Partial blocks and blocks on
+     * other users do not appear here.
+     */
+    details: string | null;
+}
 declare module "types-mediawiki-response" {
     interface ApiQueryResult {
         /** Result of the requested `curequest` mode (`list=checkuser`). */
         checkuser?: ApiQueryCheckUserResult;
         /** Entries from the CheckUser log (`list=checkuserlog`). */
         checkuserlog?: ApiQueryCheckUserLogResult;
+        /** Block status of the requesting user (`meta=checkuserformattedblockinfo`). */
+        checkuserformattedblockinfo?: ApiQueryCheckUserFormattedBlockInfoResult;
     }
 }

package/dist/extensions/readinglists.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Opt-in extension pack: **ReadingLists** (`meta=readinglists`,
+ * `list=readinglistentries`, `action=readinglists`).
+ *
+ * Not in the default export. Two shapes live here:
+ *
+ * - `meta=readinglists` / `list=readinglistentries` merge their result arrays
+ *   into `ApiQueryResult` automatically — importing anything from this file
+ *   activates the augmentation shipped at the bottom:
+ *
+ *   ```ts
+ *   import type {} from 'types-mediawiki-response/ext/readinglists';
+ *   ```
+ *
+ * - `action=readinglists` writes a root-level key named after the `command`
+ *   submodule (`create`, `update`, `setup`, …); import the matching response
+ *   type directly:
+ *
+ *   ```ts
+ *   import type { ApiReadingListsCreateResponse } from 'types-mediawiki-response/ext/readinglists';
+ *   ```
+ *
+ * Both modules require a logged-in user: the reads check the
+ * `viewmyprivateinfo` right and the writes `editmyprivateinfo`, so an anonymous
+ * request gets a top-level `notloggedin` error and lists are always the current
+ * user's own. The extension marks its API internal (`isInternal()`), so the
+ * modules are omitted from public listings but still callable.
+ *
+ * fv2 notes: an id is a `number` inside a list/entry record but a *string* at
+ * the root of a write response (`id` / `ids`) — those carry the raw database
+ * value, uncoupled from the cast record. `duplicate` appears only while a
+ * write's repository row is merge-flagged (the create commands), never on a
+ * plain read. `deleted` (`true`) appears only in `changedsince` mode; a deleted
+ * list is reported under a `deleted-<hash>` name. The read continuation cursor
+ * (`rlcontinue`) is the extension's own and is not merged into
+ * `ApiQueryContinue`.
+ *
+ * @see https://www.mediawiki.org/wiki/Extension:ReadingLists
+ */
+import type { Timestamp } from "../common";
+import type { ApiEnvelope } from "../envelope";
+/**
+ * One reading list (`meta=readinglists`, and the `list`/`lists` payload of the
+ * `create` / `update` / `setup` commands).
+ */
+export interface ApiReadingListItem {
+    /** List id. */
+    id: number;
+    /** List title as set by the owner. */
+    name: string;
+    /** Whether this is the user's catch-all default list. */
+    default: boolean;
+    /** Free-text description; `""` when none was set. */
+    description: string;
+    /** Creation time (ISO 8601). */
+    created: Timestamp;
+    /** Last update time (ISO 8601). */
+    updated: Timestamp;
+    /**
+     * Whether a list with the same name already existed, carried by the `create`
+     * command; absent on plain reads.
+     */
+    duplicate?: boolean;
+    /**
+     * `true` for a list soft-deleted within the retention window; appears only in
+     * `changedsince` mode, where the list is reported under a `deleted-<hash>`
+     * `name`.
+     */
+    deleted?: true;
+}
+/**
+ * One page saved in a reading list (`list=readinglistentries`, and the
+ * `entry`/`entries` payload of the `createentry` command).
+ */
+export interface ApiReadingListEntry {
+    /** Entry id. */
+    id: number;
+    /** Id of the list this entry belongs to. */
+    listId: number;
+    /**
+     * Canonical base URL of the wiki the entry points to (port omitted, e.g.
+     * `https://www.mediawiki.org`). Entries are cross-wiki; the `@local` project
+     * value resolves to the serving wiki's own URL here.
+     */
+    project: string;
+    /** Page title on {@link project}. */
+    title: string;
+    /** Creation time (ISO 8601). */
+    created: Timestamp;
+    /** Last update time (ISO 8601). */
+    updated: Timestamp;
+    /** Merge-detection flag of the `createentry` command; absent on plain reads. */
+    duplicate?: boolean;
+    /** `true` for an entry soft-deleted within the retention window; changes mode only. */
+    deleted?: true;
+}
+/** Response of `action=readinglists&command=setup` (no arguments). */
+export interface ApiReadingListsSetupResponse extends ApiEnvelope {
+    /** Result of the `setup` command. */
+    setup: {
+        /** The user's default list, created for them. */
+        list: ApiReadingListItem;
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+/**
+ * Response of `action=readinglists&command=create`. A single `name` returns
+ * `id` + `list`; a `batch` returns `ids` + `lists`.
+ */
+export interface ApiReadingListsCreateResponse extends ApiEnvelope {
+    /** Result of the `create` command. */
+    create: {
+        /** New list id (raw database value) for a single create. */
+        id?: string;
+        /** New list for a single create. */
+        list?: ApiReadingListItem;
+        /** New list ids for a batch create. */
+        ids?: string[];
+        /** New lists for a batch create. */
+        lists?: ApiReadingListItem[];
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+/**
+ * Response of `action=readinglists&command=update`. A single `list` returns
+ * `id` + `list`; a `batch` returns `ids` + `lists`.
+ */
+export interface ApiReadingListsUpdateResponse extends ApiEnvelope {
+    /** Result of the `update` command. */
+    update: {
+        /** Updated list id (raw database value) for a single update. */
+        id?: string;
+        /** Updated list for a single update. */
+        list?: ApiReadingListItem;
+        /** Updated list ids for a batch update. */
+        ids?: string[];
+        /** Updated lists for a batch update. */
+        lists?: ApiReadingListItem[];
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+/** Response of `action=readinglists&command=delete` (single `list` or `batch`). */
+export interface ApiReadingListsDeleteResponse extends ApiEnvelope {
+    /** Result of the `delete` command — a bare success sentinel. */
+    delete: {
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+/**
+ * Response of `action=readinglists&command=createentry`. A single `project` +
+ * `title` returns `id` + `entry`; a `batch` returns `ids` + `entries`.
+ */
+export interface ApiReadingListsCreateEntryResponse extends ApiEnvelope {
+    /** Result of the `createentry` command. */
+    createentry: {
+        /** New entry id (raw database value) for a single create. */
+        id?: string;
+        /** New entry for a single create. */
+        entry?: ApiReadingListEntry;
+        /** New entry ids for a batch create. */
+        ids?: string[];
+        /** New entries for a batch create. */
+        entries?: ApiReadingListEntry[];
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+/**
+ * Response of `action=readinglists&command=deleteentry` (single `entry` or
+ * `batch`).
+ */
+export interface ApiReadingListsDeleteEntryResponse extends ApiEnvelope {
+    /** Result of the `deleteentry` command — a bare success sentinel. */
+    deleteentry: {
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+/** Response of `action=readinglists&command=teardown` (no arguments). */
+export interface ApiReadingListsTeardownResponse extends ApiEnvelope {
+    /** Result of the `teardown` command — a bare success sentinel. */
+    teardown: {
+        /** Always `Success` on the success branch; failures are top-level errors. */
+        result: "Success";
+    };
+}
+declare module "types-mediawiki-response" {
+    interface ApiQueryResult {
+        /**
+         * The current user's reading lists. `meta=readinglists`.
+         */
+        readinglists?: ApiReadingListItem[];
+        /**
+         * A sync watermark: querying with this timestamp as `changedsince`
+         * guarantees no intervening change is skipped. Sibling of {@link readinglists},
+         * `meta=readinglists`; omitted on continuation requests.
+         */
+        "readinglists-synctimestamp"?: Timestamp;
+        /**
+         * Pages saved in the requested list(s). `list=readinglistentries` (or
+         * `generator=readinglistentries`, where the entries feed `pages` and this
+         * array comes back empty).
+         */
+        readinglistentries?: ApiReadingListEntry[];
+    }
+}