types-mediawiki-response 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # types-mediawiki-response
 
-English | [简体中文](https://github.com/BearBin1215/types-mediawiki-response/blob/main/README.zh.md) | [Document](https://bearbin1215.github.io/types-mediawiki-response/)
+English | [简体中文](https://github.com/BearBin1215/types-mediawiki-response/blob/main/README.zh.md) | [Document](https://types-mediawiki-response.pages.dev/)
 
 Reusable typings for MediaWiki Action API responses.
 
@@ -30,9 +30,9 @@ const res = (await api.get({
 })) as ApiQueryResponse;
 ```
 
-Wrap with `ApiResponseWith<T>` to get the full error response type — see the [envelope and error handling guide](https://bearbin1215.github.io/types-mediawiki-response/guide/errors.html).
+Wrap with `ApiResponseWith<T>` to get the full error response type — see the [envelope and error handling guide](https://types-mediawiki-response.pages.dev/guide/errors).
 
-When using `ApiQueryResponse`, `query.pages[]` in the response is the union of every covered `prop=` field; project it with `QueryPage<K>` to scope a page to the props you requested — see the [query responses guide](https://bearbin1215.github.io/types-mediawiki-response/guide/query.html).
+When using `ApiQueryResponse`, `query.pages[]` in the response is the union of every covered `prop=` field; project it with `QueryPage<K>` to scope a page to the props you requested — see the [query responses guide](https://types-mediawiki-response.pages.dev/guide/query).
 
 ## Extensions
 
@@ -54,4 +54,4 @@ import type { ApiThankResponse } from "types-mediawiki-response/ext/thanks";
 const res = (await api.post({ action: "thank", rev })) as ApiThankResponse;
 ```
 
-Bundled packs are listed in the [extension packs guide](https://bearbin1215.github.io/types-mediawiki-response/guide/ext-packs.html). Extensions this package does not cover can be augmented the same way with a hand-written `declare module 'types-mediawiki-response' { … }`.
+Bundled packs are listed in the [extension packs guide](https://types-mediawiki-response.pages.dev/guide/ext-packs). Extensions this package does not cover can be augmented the same way with a hand-written `declare module 'types-mediawiki-response' { … }`.

package/README.zh.md

@@ -1,6 +1,6 @@
 # types-mediawiki-response
 
-[English](https://github.com/BearBin1215/types-mediawiki-response/blob/main/README.md) | 简体中文 | [在线文档](https://bearbin1215.github.io/types-mediawiki-response/zh/)
+[English](https://github.com/BearBin1215/types-mediawiki-response/blob/main/README.md) | 简体中文 | [在线文档](https://types-mediawiki-response.pages.dev/zh/)
 
 为 MediaWiki Action API 响应提供可复用类型。
 
@@ -30,9 +30,9 @@ const res = (await api.get({
 })) as ApiQueryResponse;
 ```
 
-可用 `ApiResponseWith<T>` 包装以获得含错误结果的响应类型，见文档[信封与错误处理指南](https://bearbin1215.github.io/types-mediawiki-response/zh/guide/errors.html)。
+可用 `ApiResponseWith<T>` 包装以获得含错误结果的响应类型，见文档[信封与错误处理指南](https://types-mediawiki-response.pages.dev/zh/guide/errors)。
 
-使用 `ApiQueryResponse` 的情况下，响应里的 `query.pages[]` 类型是所有已覆盖 `prop=` 字段的并集，可用 `QueryPage<K>` 收窄到本次请求的 prop，见文档[query 响应指南](https://bearbin1215.github.io/types-mediawiki-response/zh/guide/query.html)。
+使用 `ApiQueryResponse` 的情况下，响应里的 `query.pages[]` 类型是所有已覆盖 `prop=` 字段的并集，可用 `QueryPage<K>` 收窄到本次请求的 prop，见文档[query 响应指南](https://types-mediawiki-response.pages.dev/zh/guide/query)。
 
 ## 扩展
 
@@ -54,4 +54,4 @@ import type { ApiThankResponse } from "types-mediawiki-response/ext/thanks";
 const res = (await api.post({ action: "thank", rev })) as ApiThankResponse;
 ```
 
-内置包清单见文档站的[扩展包指南](https://bearbin1215.github.io/types-mediawiki-response/zh/guide/ext-packs.html)。本包未覆盖的扩展，手写 `declare module 'types-mediawiki-response' { … }` 走同一接缝增广。
+内置包清单见文档站的[扩展包指南](https://types-mediawiki-response.pages.dev/zh/guide/ext-packs)。本包未覆盖的扩展，手写 `declare module 'types-mediawiki-response' { … }` 走同一接缝增广。

package/dist/core/query/index.d.ts

@@ -448,6 +448,7 @@ export interface ApiQueryResponse extends ApiEnvelope {
     "query-noncontinue"?: Record<string, Record<string, string | number>>;
 }
 export * from "./shared";
+export * from "./logparams";
 export * from "./info";
 export * from "./categories";
 export * from "./revisions";

package/dist/core/query/logevents.d.ts

@@ -9,6 +9,7 @@
  */
 import type { Flag, NamespaceIndex, Timestamp } from "../../common";
 import type { ApiHiddenFlags } from "./shared";
+import type { ApiLogEventParams } from "./logparams";
 /** One log event. `leprop` controls which fields appear. */
 export interface ApiLogEvent extends ApiHiddenFlags {
     /** Log record id. `leprop=ids`. */
@@ -31,8 +32,11 @@ export interface ApiLogEvent extends ApiHiddenFlags {
     type?: string;
     /** Log action, e.g. `create`, `delete`. `leprop=type`. */
     action?: string;
-    /** Structured log details; shape varies by `type`/`action`. `leprop=details`. */
-    params?: Record<string, unknown>;
+    /**
+     * Structured log details; shape varies by `type`/`action` — see
+     * {@link ApiLogEventParams}. `leprop=details`.
+     */
+    params?: ApiLogEventParams;
     /** Performing user name (or IP). `leprop=user`. */
     user?: string;
     /** Performing user id. `leprop=userid`. */

package/dist/core/query/logparams.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Structured details of log events, shared by `logevents.params`,
+ * `recentchanges.logparams` and `watchlist.logparams`.
+ */
+import type { ContentModel, Expiry, Timestamp } from "../../common";
+/**
+ * Structured log details — the `params` object of a log event (`leprop=details`
+ * on `list=logevents`, `logparams` under the log-info fields of
+ * `list=recentchanges` / `list=watchlist`).
+ *
+ * Each log action writes its own key set, which the server normalizes for the
+ * API. The keys below are the ones MediaWiki core itself writes; which of
+ * them a row carries depends on its `type`/`action`.
+ *
+ * The key space is open: extensions and site configuration can register
+ * further log actions, and rows written by older MediaWiki versions keep
+ * their historical key forms. Unknown keys therefore fall back to `unknown`
+ * instead of erroring. Consumers targeting one specific log action — or a
+ * site-custom one — can add its keys through interface merging:
+ *
+ * @example
+ * declare module "types-mediawiki-response" {
+ *   interface ApiLogEventParams {
+ *     // a site-custom log action, or a legacy key form still in the data
+ *     "4::target"?: string;
+ *   }
+ * }
+ */
+export interface ApiLogEventParams {
+    /**
+     * Block duration as configured: `'infinity'` or the raw specifier
+     * (`'2 weeks'`, …), on `block/block`, `block/reblock`, `suppress/block` and
+     * `suppress/reblock` rows. Older rows without one are normalized to
+     * `'infinity'`.
+     */
+    duration?: string;
+    /**
+     * Options in force on the block. Rows written by very old MediaWiki
+     * versions may carry the legacy values `autoblock` or `angry-autoblock`
+     * instead of the current flag set. An array (`[]` when none).
+     */
+    flags?: Array<"anononly" | "nocreate" | "noautoblock" | "noemail" | "nousertalk" | "hiddenname" | "autoblock" | "angry-autoblock">;
+    /**
+     * Absolute expiry of the block (ISO 8601), on rows with a finite duration.
+     */
+    expiry?: Timestamp;
+    /** Whether the block covers the whole site (`false` for a partial block). */
+    sitewide?: boolean;
+    /** Scope of a partial block; absent for sitewide blocks. */
+    restrictions?: ApiLogBlockRestrictions;
+    /**
+     * Id of the block the row created or changed.
+     *
+     * @since MediaWiki 1.44
+     */
+    blockId?: number;
+    /**
+     * Localized duration text (e.g. `'14 days'`, `'infinite'`), in the
+     * requesting user's language.
+     *
+     * @since MediaWiki 1.44
+     */
+    "duration-l10n"?: string;
+    /** Namespace of the move destination (on `move/move` and `move/move_redir` rows). */
+    target_ns?: number;
+    /** Title of the move destination. */
+    target_title?: string;
+    /** Whether the move left no redirect behind. */
+    suppressredirect?: boolean;
+    /**
+     * Content-language protection summary (e.g. `'[edit=autoconfirmed]
+     * (indefinite)'`), aimed at machine feeds; the structured data lives in
+     * {@link details}.
+     */
+    description?: string;
+    /** Whether cascading protection was requested. */
+    cascade?: boolean;
+    /** Protection restrictions in force. */
+    details?: ApiLogProtectDetail[];
+    /** Namespace of the title the protection moved away from. */
+    oldtitle_ns?: number;
+    /** Title the protection moved away from. */
+    oldtitle_title?: string;
+    /**
+     * How many revisions and archived file versions the undeletion restored
+     * (`delete/restore`), how many revisions an import created
+     * (`import/upload`, `import/interwiki`), or how many uses a managed tag
+     * had (`managetags/activate|deactivate|delete`).
+     */
+    count?: {
+        revisions: number;
+        files: number;
+    } | number;
+    /**
+     * What the visibility change targeted: `'revision'`, `'archive'`,
+     * `'oldimage'` or `'filearchive'` on `…/revision` rows; `'logging'` on
+     * `…/event` rows.
+     */
+    type?: "revision" | "archive" | "oldimage" | "filearchive" | "logging";
+    /**
+     * Ids of the targeted revisions, file versions or log entries — numbers on
+     * current rows, strings on legacy ones.
+     */
+    ids?: Array<number | string>;
+    /** Visibility state before the change. */
+    old?: ApiLogRevDelVisibility;
+    /** Visibility state after the change. */
+    new?: ApiLogRevDelVisibility;
+    /**
+     * Id of the account the row reports (on `newusers/create`, `newusers/create2`
+     * and `newusers/autocreate` rows).
+     */
+    userid?: number;
+    /**
+     * Groups the target user belonged to before the change (on `rights/rights`
+     * and `rights/autopromote` rows).
+     */
+    oldgroups?: string[];
+    /** Groups after the change. */
+    newgroups?: string[];
+    /**
+     * Per-group membership expiry, parallel to {@link oldgroups}; `[]` when the
+     * memberships were all permanent. Absent on `rights/autopromote` rows.
+     */
+    oldmetadata?: ApiLogGroupMetadata[];
+    /**
+     * Per-group membership expiry, parallel to {@link newgroups}; `[]` when
+     * permanent. Absent on `rights/autopromote` rows.
+     */
+    newmetadata?: ApiLogGroupMetadata[];
+    /**
+     * Content model before the change (on `contentmodel/change` and
+     * `contentmodel/new` rows).
+     */
+    oldmodel?: ContentModel;
+    /** Content model after the change. */
+    newmodel?: ContentModel;
+    /** Namespace of the page the history was merged into. */
+    dest_ns?: number;
+    /** Title of the page the history was merged into. */
+    dest_title?: string;
+    /**
+     * Namespace of the page whose history was merged in (`merge/merge-into` row
+     * filed on the destination page).
+     *
+     * @since MediaWiki 1.45
+     */
+    src_ns?: number;
+    /**
+     * Title of the page whose history was merged in (`merge/merge-into`).
+     *
+     * @since MediaWiki 1.45
+     */
+    src_title?: string;
+    /**
+     * Revision the histories were interleaved at (ISO 8601), on `merge/merge`
+     * and `merge/merge-into` rows.
+     */
+    mergepoint?: Timestamp;
+    /**
+     * Boundary revision id the merge stopped at; stored raw, so it appears as
+     * a number or its decimal string.
+     *
+     * @since MediaWiki 1.42
+     */
+    mergerevid?: number | string;
+    /**
+     * Timestamp of the first revision kept out of the merge, when a start
+     * boundary was used (ISO 8601); the id of that revision is
+     * {@link mergestartid}. Only `merge/merge` rows carry it — `merge/merge-into`
+     * rows do not report the start boundary at all.
+     *
+     * @since MediaWiki 1.45
+     */
+    mergestart?: Timestamp;
+    /**
+     * First revision id kept out of the merge; stored raw like
+     * {@link mergerevid}.
+     *
+     * @since MediaWiki 1.45
+     */
+    mergestartid?: number | string;
+    /** Namespace of the source page on the foreign wiki (`import/interwiki`). */
+    interwiki_ns?: number;
+    /** Source page on the foreign wiki, with its interwiki prefix (`import/interwiki`). */
+    interwiki_title?: string;
+    /**
+     * SHA-1 of the uploaded file (base36), on `upload/upload`, `upload/overwrite`
+     * and `upload/revert` rows.
+     */
+    img_sha1?: string;
+    /** File timestamp (ISO 8601), which can differ from the row's timestamp. */
+    img_timestamp?: Timestamp;
+    /** Revision id that was marked patrolled, on `patrol/patrol` rows. */
+    curid?: number;
+    /** Revision id the patrolled one followed. */
+    previd?: number;
+    /** Always `false`: automatic patrols are not logged. */
+    auto?: boolean;
+    /**
+     * Revision the tags were applied to (`tag/update` rows); a raw value from
+     * the tagging caller, so forms vary (a number, its decimal string, or
+     * `false` when the update targeted a log entry).
+     */
+    revid?: number | string | false;
+    /**
+     * Log entry the tags were applied to, on rows that targeted one; a raw
+     * value like {@link revid} — `false` when the update targeted a revision.
+     */
+    logid?: number | string | false;
+    /** Tags the update added. */
+    tagsAdded?: string[];
+    /** How many tags {@link tagsAdded} holds. */
+    tagsAddedCount?: number;
+    /** Tags the update removed. */
+    tagsRemoved?: string[];
+    /** How many tags {@link tagsRemoved} holds. */
+    tagsRemovedCount?: number;
+    /** Tags the target carried before the update. */
+    initialTags?: string[];
+    /** Name of the managed tag (`managetags/create|activate|deactivate|delete`). */
+    tag?: string;
+    /**
+     * Page language before the change, on `pagelang/pagelang` rows; the wiki's
+     * default language carries a `[def]` suffix (e.g. `'en[def]'`).
+     */
+    oldlanguage?: string;
+    /** Page language after the change; also `[def]`-suffixed when set to default. */
+    newlanguage?: string;
+    /**
+     * Any other parameter a log action attaches — a log action registered by an
+     * extension or site configuration, or a legacy key form on rows written by
+     * an older MediaWiki version.
+     */
+    [key: string]: unknown;
+}
+/** One page a partial block is restricted to (`restrictions.pages` entry). */
+export interface ApiLogPageRef {
+    /** Namespace index. */
+    page_ns: number;
+    /** Full page title. */
+    page_title: string;
+}
+/** Scope of a partial block (`restrictions`). */
+export interface ApiLogBlockRestrictions {
+    /** Pages the block is restricted to. */
+    pages?: ApiLogPageRef[];
+    /** Namespace indexes the block is restricted to. */
+    namespaces?: number[];
+    /** Action names the block is restricted to (e.g. `'edit'`). */
+    actions?: string[];
+}
+/** One protection restriction (`details` entry on `protect/protect`, `protect/modify`). */
+export interface ApiLogProtectDetail {
+    /** Action being restricted (e.g. `'edit'`); `'create'` for title protection. */
+    type: string;
+    /** Protection level (e.g. `'autoconfirmed'`, `'sysop'`). */
+    level: string;
+    /** When the protection lapses (ISO 8601), or `'infinite'`. */
+    expiry: Timestamp | "infinite";
+    /** Whether this restriction cascades; absent on `'create'` entries. */
+    cascade?: boolean;
+}
+/** One visibility state (`old`/`new` on a RevisionDelete row). */
+export interface ApiLogRevDelVisibility {
+    /** Raw visibility bitfield. */
+    bitmask: number;
+    /** Whether the content is hidden. */
+    content: boolean;
+    /** Whether the edit summary is hidden. */
+    comment: boolean;
+    /** Whether the performer is hidden. */
+    user: boolean;
+    /** Whether only suppressors can unhide. */
+    restricted: boolean;
+}
+/** One group-membership change with its expiry (`oldmetadata`/`newmetadata` entry). */
+export interface ApiLogGroupMetadata {
+    /** Group name. */
+    group: string;
+    /** When the membership lapses. */
+    expiry: Expiry;
+}

package/dist/core/query/recentchanges.d.ts

@@ -9,6 +9,7 @@
  */
 import type { Flag, NamespaceIndex, Timestamp } from "../../common";
 import type { ApiHiddenFlags } from "./shared";
+import type { ApiLogEventParams } from "./logparams";
 /** Change type (`rctype`). Open union for forward compatibility. */
 export type RecentChangeType = "edit" | "new" | "log" | "categorize" | "external" | (string & {});
 /** One recent-changes entry. `rcprop` controls which fields appear. */
@@ -83,8 +84,11 @@ export interface ApiRecentChange extends ApiHiddenFlags {
     logtype?: string;
     /** Log action, e.g. `create`. `rcprop=loginfo`. */
     logaction?: string;
-    /** Structured log parameters. `rcprop=loginfo`. */
-    logparams?: Record<string, unknown>;
+    /**
+     * Structured log details — see {@link ApiLogEventParams}. `rcprop=loginfo`
+     * (only for `type=log`).
+     */
+    logparams?: ApiLogEventParams;
 }
 declare module "./index" {
     interface ApiQueryResult {

package/dist/core/query/watchlist.d.ts

@@ -13,6 +13,7 @@
 import type { ApiWatchlistLabel, Flag, NamespaceIndex, Timestamp } from "../../common";
 import type { ApiHiddenFlags } from "./shared";
 import type { RecentChangeType } from "./recentchanges";
+import type { ApiLogEventParams } from "./logparams";
 /** One watchlist entry. `wlprop` controls which fields appear. */
 export interface ApiWatchlistEntry extends ApiHiddenFlags {
     /** Change type. */
@@ -33,8 +34,11 @@ export interface ApiWatchlistEntry extends ApiHiddenFlags {
     logtype?: string;
     /** Log action. `wlprop=loginfo` (only for `type=log`). */
     logaction?: string;
-    /** Structured log parameters. `wlprop=loginfo` (only for `type=log`). */
-    logparams?: Record<string, unknown>;
+    /**
+     * Structured log details — see {@link ApiLogEventParams}. `wlprop=loginfo`
+     * (only for `type=log`).
+     */
+    logparams?: ApiLogEventParams;
     /**
      * Localized log action text, e.g. `changed protection settings`.
      * `wlprop=loginfo` (only for `type=log`).

package/dist/extensions/betafeatures.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Opt-in extension pack: **BetaFeatures** (`list=betafeatures`).
+ *
+ * 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/betafeatures';
+ * ```
+ *
+ * The result is a flat map keyed by feature id — one entry per feature
+ * registered through `$wgBetaFeatures` or the
+ * `GetBetaFeaturePreferences` hook, so the key set is site-configured and open.
+ * A wiki with no beta features omits the whole `betafeatures` bucket.
+ *
+ * @see https://www.mediawiki.org/wiki/Extension:BetaFeatures
+ */
+/**
+ * One `list=betafeatures` entry: a feature id with its user count.
+ */
+export interface ApiBetaFeature {
+    /** The feature id, e.g. `mw-vector-2022-default-title`. */
+    name: string;
+    /**
+     * Number of users who enabled the feature; `0` unless `bfcounts` was
+     * requested.
+     */
+    count: number;
+}
+declare module "types-mediawiki-response" {
+    interface ApiQueryResult {
+        /**
+         * Beta features registered on this wiki, keyed by feature id
+         * (`list=betafeatures`). Absent when no features are registered.
+         */
+        betafeatures?: Record<string, ApiBetaFeature>;
+    }
+}