@ikenxuan/amagi 7.0.0-beta.5 → 7.0.0-beta.7

package/dist/api-BWAjDuTS.d.ts

@@ -0,0 +1,802 @@
+import zod from "zod";
+import { AxiosRequestConfig } from "axios";
+//#region src/contracts/request.d.ts
+/**
+ * 请求 / 响应契约。
+ *
+ * `RequestConfig` 在本文件定义并对外导出。
+ *
+ * `contracts/` 是零依赖叶子层：本文件只 type-import 外部包 `axios`，
+ * 不 import 仓库内任何其他模块。
+ */
+/** HTTP 方法 */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * 调用方可传的请求配置。
+ *
+ * 形状即 `Omit<AxiosRequestConfig, 'url' | 'method' | 'data'>`，
+ * `amagi({ request: { timeout: 8000, proxy } })` 这类写法直接可用。
+ */
+type RequestConfig = Omit<AxiosRequestConfig, 'url' | 'method' | 'data'>;
+/** 可以用来初始化或合并 {@link AmagiHeaders} 的输入 */
+type HeadersInput = AmagiHeaders | Record<string, string | number | undefined | null> | undefined | null;
+/**
+ * 大小写不敏感的 header 容器。
+ *
+ * HTTP header 名本身大小写不敏感，用普通对象装就会出现「写了 `Cookie` 却读
+ * `cookie` 读不到」这类静默失配。本类把「大小写」这个变量彻底消掉。
+ *
+ * 语义：
+ * - 查找、判断、删除全部大小写不敏感。
+ * - 写入是「后写覆盖」：值覆盖，**显示用的大小写也跟着最后一次写入**，
+ *   所以 `set('User-Agent', a)` 之后 `set('user-agent', b)` 只会留下一个
+ *   `user-agent: b`，不可能出现两条同名 header。
+ * - `undefined` / `null` 的值视为「不写这个 header」，方便直接摊入可选字段。
+ */
+declare class AmagiHeaders {
+  /** key 是小写化的 header 名，value 保留最后一次写入的原始大小写与值 */
+  private readonly entries;
+  /**
+   * @param init - 初始 header，可以是另一个 `AmagiHeaders` 或普通对象
+   */
+  constructor(init?: HeadersInput);
+  /**
+   * 读取 header 值，大小写不敏感
+   * @param name - header 名，任意大小写
+   * @returns 值，不存在时返回 `undefined`
+   */
+  get(name: string): string | undefined;
+  /**
+   * 判断 header 是否存在，大小写不敏感
+   * @param name - header 名，任意大小写
+   * @returns 存在则返回 `true`
+   */
+  has(name: string): boolean;
+  /**
+   * 写入 header。同名（忽略大小写）时覆盖值与显示大小写
+   * @param name - header 名
+   * @param value - 值。`undefined` / `null` 表示不写入
+   * @returns 自身，便于链式调用
+   */
+  set(name: string, value: string | number | undefined | null): this;
+  /**
+   * 删除 header，大小写不敏感
+   * @param name - header 名
+   * @returns 原本存在则返回 `true`
+   */
+  delete(name: string): boolean;
+  /**
+   * 合并另一组 header，后来者覆盖
+   * @param input - 待合并的 header
+   * @returns 自身，便于链式调用
+   */
+  merge(input?: HeadersInput): this;
+  /** header 条数 */
+  get size(): number;
+  /**
+   * 全部 header 名，保留最后一次写入的大小写
+   * @returns header 名数组
+   */
+  keys(): string[];
+  /**
+   * 全部 `[名, 值]` 对，名保留最后一次写入的大小写
+   * @returns 键值对数组
+   */
+  toEntries(): [string, string][];
+  /**
+   * 转成普通对象，用于交给 axios
+   * @returns 普通 header 对象，键保留最后一次写入的大小写
+   */
+  toJSON(): Record<string, string>;
+  /**
+   * 深拷贝一份，避免下游改写上游的 header
+   * @returns 新的 `AmagiHeaders` 实例
+   */
+  clone(): AmagiHeaders;
+}
+/**
+ * 一次底层 HTTP 请求的完整描述。
+ *
+ * 由端点的 `build` 产出，经 `sign` 加工，最后交给 transport 发送。
+ * 端点声明里返回数组即表示多请求聚合 / 分段并发。
+ */
+interface RequestSpec {
+  /** HTTP 方法 */
+  method: HttpMethod;
+  /** 完整 URL（含 query） */
+  url: string;
+  /** 请求头。缺省时由平台 `config.ts` 的基线补齐 */
+  headers?: HeadersInput;
+  /**
+   * 要从合并结果里**删掉**的头名（大小写不敏感），在所有 merge 之后执行。
+   *
+   * `headers` 只能覆盖同名头，给不出「这个端点不该发某个基线头」。快手 H5 端点
+   * 需要它：平台基线是照桌面 Chrome 攒的（`origin` / `sec-ch-ua*` / `sec-fetch-*`），
+   * 而 H5 端点用移动 UA，两者拼在一起是个自相矛盾的请求。
+   * 清单见 `platforms/kuaishou/config.ts` 的 `KUAISHOU_H5_DROP_HEADERS`。
+   *
+   * 删除发生在最后一步，所以**同时出现在 `headers` 与这里的头会被删掉** ——
+   * 端点自己要发的头别写进这个清单。
+   */
+  dropHeaders?: readonly string[];
+  /** 请求体，`method === 'POST'` 时使用 */
+  body?: unknown;
+  /** 期望的响应形态。protobuf 端点用 `'arraybuffer'`，反爬页用 `'text'` */
+  responseType?: 'json' | 'text' | 'arraybuffer';
+  /** 签名器需要的接口路径（小红书 `x-s`、快手 hxfalcon 都要它，与 `url` 不同） */
+  signPath?: string;
+  /** 多请求聚合 / 分段并发时标识这一条是哪个部分，会进 trace */
+  tag?: string;
+  /** 端点自定义的附加信息，透传给 `sign` / `decode` */
+  extra?: Record<string, unknown>;
+}
+/**
+ * transport 发出一次请求后拿到的原始响应。
+ *
+ * 放在 contracts 而不是 transport，是因为端点声明的 `decode(raw, res)` 需要它，
+ * 而依赖方向是 `contracts ← transport ← platforms`，contracts 不能反向依赖。
+ */
+interface RawResponse {
+  /** 平台返回的 HTTP 状态码。**原样带出，不再用 `validateStatus: () => true` 抹平** */
+  status: number;
+  /** 状态文案 */
+  statusText?: string;
+  /** 响应头，大小写不敏感 */
+  headers: AmagiHeaders;
+  /**
+   * 原始 `Set-Cookie` 头数组（一个响应里可能有多条）。
+   *
+   * `headers` 里的 `set-cookie` 是 join 成一条的字符串（多值会被 `'; '` 合并），
+   * 而 guest cookie 换身份、B站会话登录都需要**逐条**处理 Set-Cookie ——
+   * join 后无法还原成数组。所以这里单独保留原始数组。
+   */
+  setCookie?: string[];
+  /** 未经端点 `decode` 的响应体：已解析的 JSON / 字符串 / `ArrayBuffer` */
+  body: unknown;
+  /** 这一次请求本身的耗时 */
+  durationMs: number;
+  /** 实际请求的最终 URL（含签名参数、跟随重定向后的地址） */
+  url: string;
+}
+//#endregion
+//#region src/contracts/error.d.ts
+/**
+ * 错误契约。
+ *
+ * 全仓唯一的错误载体：调用方写一段跨平台通用的错误处理代码，只需要认
+ * `AmagiError` 一种形状。
+ *
+ * `contracts/` 是零依赖叶子层，本文件不 import 仓库内任何其他模块。
+ */
+/**
+ * 跨平台统一的错误大类，也是调用方唯一需要 `switch` 的判别键。
+ *
+ * 粗粒度归因用 `kind`，细粒度归因用 {@link AmagiErrorCode}。
+ */
+type ErrorKind =
+/** 入参不合法，本地就能判定，没有发出请求 */
+'validation' |
+/** 需要登录 / cookie 失效 / 身份不足 */
+'auth' |
+/** 限频，退避后可重试 */
+'rate_limit' |
+/** 风控、验证码、需要人工介入 */
+'risk' |
+/** 资源不存在、已删除、已下架 */
+'not_found' |
+/** 有身份但无权限：地区限制、付费内容、隐私设置 */
+'forbidden' |
+/** 平台侧不可用：5xx、维护、过载 */
+'unavailable' |
+/** 传输层失败：连接重置、DNS、代理 */
+'network' |
+/** 超时 */
+'timeout' |
+/** 响应拿到了但解析不了：非 JSON、protobuf 损坏、反爬 HTML */
+'parse' |
+/** amagi 自身的 bug */
+'internal' |
+/** 平台返回了没见过的错误码 */
+'unknown';
+/**
+ * 稳定的字符串错误码，可用于 `switch` 与埋点。
+ *
+ * 用字符串字面量联合而不是 `enum`：`enum` 的 `Object.values()` 会带出反向映射键，
+ * 且拿平台返回的数字码去比时容易出现 `'-101'` 与 `-101` 对不上的静默错配。
+ */
+type AmagiErrorCode = 'PARAM_INVALID' | 'PARAM_MISSING' | 'COOKIE_MISSING' | 'COOKIE_EXPIRED' | 'LOGIN_REQUIRED' | 'RATE_LIMITED' | 'RISK_CONTROL' | 'CAPTCHA_REQUIRED' | 'NOT_FOUND' | 'DELETED' | 'PRIVATE' | 'GEO_RESTRICTED' | 'PAID_CONTENT' | 'PLATFORM_ERROR' | 'PLATFORM_UNAVAILABLE' | 'NETWORK_ERROR' | 'TIMEOUT' | 'EMPTY_RESPONSE' | 'DECODE_FAILED' | 'ANTIBOT_PAGE' | 'INTERNAL_ERROR' | 'UNKNOWN_ERROR';
+/** `kind === 'validation'` 时的字段级错误 */
+interface ValidationIssue {
+  /** 点号路径，如 `'verify.stdParams.token'` */
+  path: string;
+  /** 面向人的说明 */
+  message: string;
+  /** 收到的值，用于排查 */
+  received?: unknown;
+}
+/** 失败信封里唯一的错误载体，永不为 `undefined` */
+interface AmagiError {
+  /** 判别键，跨平台统一的错误大类 */
+  kind: ErrorKind;
+  /** 稳定的字符串错误码，可用于 switch 与埋点 */
+  code: AmagiErrorCode;
+  /** 面向人的说明，取平台原文优先 */
+  message: string;
+  /** 是否值得重试。调用方据此决定退避还是放弃 */
+  retryable: boolean;
+  /** 平台原始错误码与文案，一个字都不丢 */
+  platform?: {
+    code: string | number;
+    message?: string;
+  };
+  /** 真实发生的 HTTP 状态（有请求才有） */
+  http?: {
+    status: number;
+    statusText?: string;
+  };
+  /** `kind === 'validation'` 时的字段级错误 */
+  issues?: ValidationIssue[];
+  /**
+   * 原始响应体。默认**连键都没有**，`createClient({ debug: true })` 且这次
+   * 确实**拿到了响应**时才填（网络中断 / 超时那类失败没有响应体可放）。
+   */
+  raw?: unknown;
+  /**
+   * 风控挑战（验证页地址 + 票据）。`kind === 'risk'` 且平台认得出这份响应时才有。
+   *
+   * **不受 `debug` 开关影响** —— 它是「怎么过去」这条必要信息，见
+   * {@link RiskChallenge}。
+   */
+  challenge?: RiskChallenge;
+  /** 底层 Error 对象，仅用于日志 */
+  cause?: unknown;
+}
+/** 平台判定的结论 */
+interface JudgeVerdict {
+  /** 是否视为成功 */
+  ok: boolean;
+  /** 失败时的错误大类 */
+  kind?: ErrorKind;
+  /** 失败时的细粒度错误码 */
+  code?: AmagiErrorCode;
+  /** 覆盖 {@link isRetryableKind} 的默认推导 */
+  retryable?: boolean;
+}
+/**
+ * 平台响应判定函数。
+ *
+ * 每个平台一份纯函数，把原始响应映射为「成功」或一个错误分类。
+ * **这是全仓唯一判定成败的地方** —— 平台差异只体现在这一份实现里。
+ */
+type Judge = (raw: unknown, http: {
+  status: number;
+}) => JudgeVerdict;
+/**
+ * 风控挑战：撞验证页时交给调用方的「怎么过去」。
+ *
+ * 为什么不塞进 {@link JudgeVerdict}：judge 只管**分类**，四个槽位装不下一个
+ * URL。但 `kind: 'risk'` 光有分类是条死路 —— `CAPTCHA_REQUIRED` 只告诉调用方
+ * 「你被拦了」，不给出路。以前地址只能从 `error.raw` 里自己捞，而 `raw` 只在
+ * `createClient({ debug: true })` 时才有、HTTP 路由那一面**结构上拿不到**
+ * （`createXxxRoutes` 不接 `debug`）——最需要滑块地址的入口恰好是唯一产不出它的
+ * 入口。所以这一份**不受 `debug` 管**，只要 judge 判成 `risk` 就填。
+ *
+ * 只放地址与票据，不放原始响应体：它是「必要信息」而不是「排障明细」，
+ * 也没有大对象与凭证字段的顾虑。
+ *
+ * **只做中转，不做绕过** —— amagi 不引入任何识别、轨迹模拟或自动过验证的代码。
+ */
+interface RiskChallenge {
+  /** 验证页地址（已补协议） */
+  url: string;
+  /** 前端验证 SDK 地址（已补协议），自建验证页时要它 */
+  jsSdkUrl?: string;
+  /** 验证会话票据 */
+  session?: string;
+  /** 风控业务名 */
+  bizName?: string;
+  /** 平台命中的业务码 */
+  result?: string | number;
+}
+//#endregion
+//#region src/contracts/platform.d.ts
+/**
+ * 平台契约。
+ *
+ * `contracts/` 是零依赖叶子层：本目录下的模块不 import 仓库内任何其他模块，
+ * 所以任何层都可以依赖它而不引入 import 环。
+ */
+/**
+ * amagi 支持的平台清单。
+ *
+ * `Platform` 联合类型由这个数组推导而来，两者不可能漂移 ——
+ * 新增平台只需在这里加一项。数组顺序即对外文档与遍历顺序。
+ */
+declare const PLATFORMS: readonly ['douyin', 'bilibili', 'kuaishou', 'xiaohongshu'];
+/** amagi 支持的平台 */
+type Platform = (typeof PLATFORMS)[number];
+//#endregion
+//#region src/contracts/meta.d.ts
+/**
+ * 可观测性契约。
+ *
+ * `AmagiMeta` 挂在每一个信封上（成功与失败都有），同时进事件负载。
+ * 它把几件「看不见」的事变成肉眼可见的数字：
+ * - `attempts`：一次调用实际打了多少个请求，含重试与分页的叠乘。
+ * - `requestId` / `clientId`：多实例并发时可归因。
+ * - 前置请求（换 guest cookie、取 wbi key）以 `reason: 'prepare'` 进 trace。
+ */
+/**
+ * 一次底层请求的发起原因。
+ *
+ * 区分「端点内重试」与「传输层重试」、「翻页」与「分段并发」，
+ * 是排查请求数叠乘的入口。
+ */
+type TraceReason =
+/** 首次请求 */
+'initial' |
+/** 传输层或 `retryOn` 触发的重试 */
+'retry' |
+/** 声明式翻页的第 n 页 */
+'page' |
+/** 多请求聚合 / 分段并发里的一段 */
+'segment' |
+/** `prepare` 阶段的前置请求：换 guest cookie、取 wbi key */
+'prepare';
+/** 单次底层 HTTP 请求的明细 */
+interface RequestTrace {
+  /** 实际请求的 URL（含签名参数） */
+  url: string;
+  /** HTTP 方法 */
+  method: string;
+  /** 平台返回的状态码，请求未发出（如 DNS 失败）时缺失 */
+  status?: number;
+  /** 这一次请求本身的耗时 */
+  durationMs: number;
+  /** 这次请求为什么会发出 */
+  reason: TraceReason;
+  /** `reason === 'retry'` 时，被重试的那次失败的错误码 */
+  retryOf?: AmagiErrorCode;
+}
+/** 挂在每个信封上的元信息 */
+interface AmagiMeta {
+  /** 每次逻辑调用一个 id，贯穿事件、日志、trace */
+  requestId: string;
+  /** 发起调用的 client 实例 id；静态 fetcher 用 `'static'` */
+  clientId: string;
+  /** 平台 */
+  platform: Platform;
+  /** 端点全名，如 `'douyin.videoWork'` */
+  endpoint: string;
+  /** 从进入 fetcher 到返回信封的总耗时 */
+  durationMs: number;
+  /** 实际发出的 HTTP 请求数，含重试与分页。分页 3 页 + 1 次重试 = 4 */
+  attempts: number;
+  /**
+   * 每次底层请求的明细，按发出顺序。
+   *
+   * 默认不带：`createClient({ debug: true })` 时才填（同一个开关也给失败信封
+   * 填 `error.raw`，没有单独的 trace 开关）。不开时信封上**没有 `trace`
+   * 这个键**，而 `attempts` 照样准确 —— 计数始终发生，只有明细受开关控制。
+   *
+   * 静态 fetcher（`amagi.douyinFetcher.*`）与 HTTP 服务的平台路由没有这个开关。
+   * 要不受开关影响地逐条观测请求，监听 `http:request` / `http:response`
+   * 事件：它们的负载恒带 `trace`。URL 含签名参数，别在生产里无条件打印。
+   */
+  trace?: RequestTrace[];
+}
+//#endregion
+//#region src/contracts/endpoint.d.ts
+/**
+ * 端点声明契约。
+ *
+ * 核心：**一个端点一份声明，其余全部派生。** 参数类型、运行时校验、
+ * HTTP 路由、fetcher 方法、bound fetcher、方法名映射、文档与测试清单
+ * 全部从这份声明推出来，不再散在十几个文件里靠人工同步。
+ *
+ * `contracts/` 是零依赖叶子层：本文件只 type-import 外部包 `zod` 与同目录契约。
+ * 端点的钩子需要「发请求」的能力，但 contracts 不能反向依赖 transport，
+ * 所以 {@link EndpointCtx} 只声明 `send` 的**形状**，由 transport 去实现。
+ */
+/**
+ * 只携带类型、不携带值的令牌。
+ *
+ * 用来把响应类型写进声明而不产生任何运行时开销：
+ * `response: type<DouyinReturnTypeMap['videoWork']>()`。
+ *
+ * `T` 取平台返回数据的实测快照类型（`XxxReturnTypeMap` 的键与端点短名
+ * 一一对应），快照自带的索引签名让「平台加字段」不算 breaking。
+ */
+interface TypeToken<T> {
+  /** 幻影字段，运行时永远是 `undefined`，只为让 TS 能推出 `T` */
+  readonly __type?: T;
+}
+/** 端点全名，形如 `'douyin.videoWork'` */
+type EndpointName = `${Platform}.${string}`;
+/**
+ * 端点钩子拿到的执行上下文。
+ *
+ * `send` 是依赖倒置点：contracts 只声明「能发一次请求并拿到 {@link RawResponse}」
+ * 这个形状，transport 提供实现。这样 `prepare` 里换 guest cookie、取 wbi key
+ * 都必须走 transport，用户配的 proxy / agent / 超时才对它生效。
+ */
+interface EndpointCtx {
+  /** 发起调用的 client 实例 id；静态 fetcher 用 `'static'` */
+  clientId: string;
+  /** 平台 */
+  platform: Platform;
+  /** 本次调用使用的 cookie */
+  cookie: string;
+  /** 本次调用使用的 User-Agent */
+  userAgent: string;
+  /** 调用方传入的请求配置 */
+  requestConfig: RequestConfig;
+  /**
+   * 发一次底层请求。由 transport 注入
+   * @param spec - 请求描述
+   * @param reason - 这次请求的来源，决定它在 trace 里的 `reason`
+   * @param requestConfig - 单次调用的请求配置（合并进本次请求）。缺省时
+   *   由 execute 把 ctx.requestConfig 当作默认值补上 —— 管线内任何内部请求
+   *   （prepare 换 guest cookie、取 wbi key）都与主请求用同一份配置
+   * @returns 原始响应
+   */
+  send: (spec: RequestSpec, reason?: TraceReason, requestConfig?: RequestConfig) => Promise<RawResponse>;
+}
+/** 自定义签名器：拿到请求描述与上下文，返回签好名的请求描述 */
+type SignFn = (spec: RequestSpec, ctx: EndpointCtx) => RequestSpec | Promise<RequestSpec>;
+/**
+ * 签名阶段：决定一个端点内多个反爬参数（{@link SignStep}）的执行先后。
+ *
+ * 端点作者只声明「要哪些参数」，不用手排顺序 —— runtime 按本枚举的固定次序排好再执行。
+ * 抖音那条链是活例：`webid → msToken → a_bogus/x_bogus → secsdk`，颠倒任意一步签名就
+ * 不成立，所以把「顺序」这个不变量收进机制层，而不是交给每个端点声明处去保证。
+ *
+ * - `prepare`：签名前的补参（如按 cookie 补 webid）。
+ * - `token`：本地随机令牌（如抖音 `msToken`），必须先于主签名进 URL。
+ * - `sign`：主签名（`a_bogus` / `x_bogus` / `wbi` / `x-s` / `hxfalcon` 等）。
+ * - `finalize`：收尾（如抖音 `secsdk` 重写整条 URL、小红书追加 `x-b3-traceid`）。
+ */
+type SignPhase = 'prepare' | 'token' | 'sign' | 'finalize';
+/**
+ * 一个原子反爬参数。
+ *
+ * `apply` 复用 {@link SignFn}：「这个参数写进 query / header / 还是重写整条 URL」是它的
+ * 内部实现，端点作者不感知。`phase` 是唯一的顺序语义，同 phase 内按数组出现顺序执行。
+ *
+ * 端点用 `sign: [msToken(184), aBogus(), secsdk()]` 直接列出要哪些参数；增删数组元素
+ * 即可，不必为「要参数1不要参数2」另注册签名器名。
+ */
+interface SignStep {
+  /** 执行阶段，决定与同端点其他步骤的先后 */
+  phase: SignPhase;
+  /** 把这个反爬参数盖到请求上 */
+  apply: SignFn;
+}
+/**
+ * 签名声明。
+ *
+ * - {@link SignStep} / `SignStep[]`：**推荐**。原子反爬参数清单，runtime 按 {@link SignPhase}
+ *   排序后依次 `apply`；单个步骤可省数组（`sign: hxfalcon()`）。
+ * - 字符串：平台签名器表里的名字（如 `'a_bogus'` / `'xhs-post'`）。默认宽 `string`，
+ *   平台可以再包一层 `defineEndpoint`（传 `TSign` 为自己的签名器名联合）把它收窄。
+ *   与 SignStep 清单渐进共存，全平台迁移完成后再定去留。
+ * - `false`：显式声明这个端点不签名（抖音搜索、表情包接口）。
+ * - 函数：一次性的自定义签名。
+ */
+type SignDecl<TSign extends string = string> = TSign | false | SignFn | SignStep | SignStep[];
+/** 多请求聚合 / 分段并发时，部分失败怎么处理 */
+type PartialPolicy =
+/** 缺失的部分留空，整体仍算成功 */
+'tolerate' |
+/** 任一部分失败即整体失败 */
+'fail';
+/**
+ * 一页 / 一段的默认类型，取最终返回 `TData`（一页 / 一段与返回同形）。
+ * `TData` 是 `unknown` / `any` / `never` 时退成 `Record<string, any>`（随便点，但挡住把它当函数调）。
+ */
+type PageOf<TData> = [TData] extends [never] ? Record<string, any> : unknown extends TData ? Record<string, any> : TData;
+/**
+ * 翻页跑完交给 `merge` 的值。`lastPage` 恒有值（空跑由 {@link PaginateOutcome} 单独承载），
+ * 所以端点能直接 `...lastPage`。不保留每页完整体、只留累积条目，避免内存峰值。
+ */
+interface PaginatedValue<TPage = unknown, TItem = unknown> {
+  /** 最后一页 decode 之后的值 */
+  lastPage: TPage;
+  /** 按目标条数截断后的累积条目 */
+  items: TItem[];
+}
+/**
+ * 声明式翻页：一页页往后翻，每页都走 ③build→④sign→⑤send→⑥decode→⑦judge，最后 `merge` 收尾。
+ * 页类型 `TPage` 缺省取 `PageOf<TData>`（一页与返回同形），所以 `items` / `hasMore` / `nextParams`
+ * 自动拿到 `response` 的形状、不必断言。详细机制见开发文档「翻页与会话」。
+ */
+interface PaginateDef<TParams, TData = unknown, TPage = unknown, TItem = unknown> {
+  /** 单页最多取多少条，用来把目标条数切成几次请求 */
+  maxPageSize: number;
+  /** 目标条数取自哪个参数，默认 `'number'`；该参数为 0 时一个请求都不发 */
+  limitParam?: keyof TParams & string;
+  /** 每页条数写回哪个参数，默认与 `limitParam` 相同 */
+  countParam?: keyof TParams & string;
+  /** 页形状与最终返回不同形时才写（覆盖 `TPage`）；缺省取 `PageOf<TData>` */
+  page?: TypeToken<TPage>;
+  /** 从一页里取出本页条目（`page` 已是 `TPage`）；返回空数组表示到底了 */
+  items: (page: TPage) => TItem[];
+  /** 还有没有下一页；返回 `false` 立刻停 */
+  hasMore: (page: TPage) => boolean;
+  /** 根据这一页产出下一次请求的参数（游标怎么带端点自己定） */
+  nextParams: (params: TParams, page: TPage) => TParams;
+  /** 把跨页累积的条目收成最终 data（可选）：`value.lastPage` 恒有值、`value.items` 是累积条目 */
+  merge?: (value: PaginatedValue<TPage, TItem>, params: TParams) => NoInfer<TData>;
+}
+/**
+ * 「同构分段并发」跑完交给 {@link EndpointDef.aggregate} 的值（与 {@link PaginatedValue} 一个套路）。
+ * `head` 恒有值（全失败时 execute 不进 aggregate），所以端点能直接 `...head`。段类型 `TPage`
+ * 缺省取 `PageOf<TData>`（段与返回同形），与 paginate 的 page 共用。详见「端点注册表」。
+ */
+interface AggregatedValue<TPage = unknown> {
+  /** 各段 decode 之后的值，顺序同 build 的分段；失败段（`partial: 'tolerate'`）为 undefined */
+  parts: ReadonlyArray<TPage | undefined>;
+  /** 第一段成功段（恒有值）：元信息从它取，可直接 `...head` */
+  head: TPage;
+}
+/**
+ * 端点的文档元数据 —— OpenAPI 规范里「面向人的那部分」的唯一出处。
+ *
+ * 规范从注册表派生，所以描述文案也只能长在声明里：写进文档站的 Markdown
+ * 就成了「手写第二遍」，必然漂移。
+ *
+ * `tags` 故意不在这里：**平台就是 tag**，由生成器从 {@link EndpointDef.name}
+ * 的平台段派生，同一个事实不写两遍。
+ */
+interface EndpointDoc {
+  /**
+   * OpenAPI 的 `summary`：一句话说清这个端点返回什么。
+   *
+   * 写法约定：**中文名词短语、不带句号、不超过 40 字**，例如 `'视频作品详细信息'`。
+   * 它会出现在 API 参考的端点卡片标题与侧边栏条目上，写成整句或超长都会被截断。
+   */
+  summary: string;
+  /**
+   * OpenAPI 的 `description`：一句话讲不完的部分 —— 参数之间的约束、平台侧限制、
+   * 与相近端点的区别。支持 Markdown、可多行。没有要补充的就别写。
+   */
+  description?: string;
+  /** 标为废弃：生成的 operation 带 `deprecated: true`，文档站会画删除线 */
+  deprecated?: boolean;
+  /** 指向平台官方文档（或仓库内的说明页） */
+  externalDocs?: {
+    /** 文档地址 */
+    url: string;
+    /** 链接文案，缺省由文档站决定 */
+    description?: string;
+  };
+}
+/**
+ * 一个端点的完整声明。**声明一份，其余（方法 / 路由 / 类型 / 文档）全部派生。**
+ *
+ * 下面的字段大多对应「调一次接口」的流程步骤，注释里用 ①~⑧ 标出顺序：
+ * ① 校验参数 → ② prepare → ③ build → ④ sign → ⑤ 发请求 → ⑥ decode → ⑦ judge → ⑧ 整形。
+ * 完整字段清单、派生关系与设计取舍见开发文档「端点注册表」与「契约与信封」。
+ */
+interface EndpointDef<TParams extends zod.ZodType, TData, TSign extends string = string, TPage = PageOf<TData>, TItem = unknown> {
+  /** 端点全名，形如 `'douyin.videoWork'`（声明信息） */
+  name: EndpointName;
+  /** HTTP 路由路径，同平台内必须唯一（声明信息） */
+  route: string;
+  /** ① 参数 schema（zod）：校验、类型推导、文档参数表都从它派生 */
+  params: TParams;
+  /** 文档元数据：`summary` 必填（API 参考的标题来源），`description` 可选 */
+  doc?: EndpointDoc;
+  /** ② 发请求前的准备（可选）：换游客 cookie、取密钥等；返回的字段并入上下文 */
+  prepare?: (ctx: EndpointCtx) => Promise<Partial<EndpointCtx>>;
+  /** ③ 拼请求。返回数组 = 多个请求并发（分段并发 / 多请求聚合） */
+  build?: (params: zod.infer<TParams>, ctx: EndpointCtx) => RequestSpec | RequestSpec[];
+  /** ④ 签名（可选）：{@link SignStep} 清单（推荐，可直接列出要哪些反爬参数）/ 签名器名字 / `false`（不签）/ 一次性函数 */
+  sign?: SignDecl<TSign>;
+  /** ⑥ 解码响应（可选，⑤ 是发请求）：默认按 JSON；protobuf / 多段 JSON / HTML 在这里处理 */
+  decode?: (raw: unknown, res: RawResponse) => unknown;
+  /** 翻页（可选）：把 ③~⑦ 包成一页页翻的循环，详见「端点注册表」 */
+  paginate?: PaginateDef<zod.infer<TParams>, TData, TPage, TItem>;
+  /** 多个请求时的部分失败策略：`'tolerate'`（缺的留空）/ `'fail'`（默认，一个失败即整体失败） */
+  partial?: PartialPolicy;
+  /** ⑦ 判定成功 / 失败（可选）：缺省用所在平台的默认判定 */
+  judge?: Judge;
+  /**
+   * ⑧ 把响应整理成最终 data（可选）。`decoded` 是解码后的响应、什么形状都可能，所以类型是 unknown。
+   * 分段并发改用 {@link EndpointDef.aggregate}、翻页改用 {@link PaginateDef.merge}（都带类型、更好写）。
+   * 为什么是 unknown、`NoInfer` 的作用见「契约与信封」。
+   */
+  normalize?: (decoded: unknown, params: zod.infer<TParams>) => NoInfer<TData>;
+  /**
+   * ⑧ 整理「同构分段并发」结果（可选，`normalize` 的带类型版本）：`value.parts` 是各段结果、
+   * `value.head` 是第一段成功段（恒有值，可直接 `...head`）。声明了它就别再写 `normalize`（会被忽略）。
+   * 只适用各段同形；异构聚合（快手 `userProfile`）仍用 `normalize`。详见「端点注册表」。
+   */
+  aggregate?: (value: AggregatedValue<TPage>, params: zod.infer<TParams>) => NoInfer<TData>;
+  /** 纯本地计算、不发请求（可选）：声明了它就跳过 ②~⑧，直接算出 data（如 AV/BV 互转） */
+  compute?: (params: zod.infer<TParams>) => TData;
+  /** 响应类型令牌 `type<T>()`：**data 的类型只从这里来**。详见「契约与信封」 */
+  response?: TypeToken<TData>;
+  /** 命中这些错误码时端点级重试（如 B站 `-412`）。详见「端点注册表」 */
+  retryOn?: AmagiErrorCode[];
+  /** 重试时重新 build + 重新签名（而非原样重放）；抖音 Argus 需要它。详见「端点注册表」 */
+  retryFresh?: boolean;
+  /** 预留槽位，当前恒为 `undefined`（跨平台统一视图，将来才用） */
+  toCanonical?: undefined;
+}
+/**
+ * 任意端点声明。
+ *
+ * `TParams` 出现在 `build` / `normalize` / `compute` 的形参位置，`TPage` / `TItem` 出现在
+ * `paginate.items` 等形参位置（都逆变），所以这里必须用 `any` 才能让具体端点赋值进来 ——
+ * 换成 `unknown` 会让 `EndpointDef<具体 schema, …>` 不可赋值给它。
+ */
+type AnyEndpointDef = EndpointDef<any, any, any, any, any>;
+/** 一个平台的端点注册表：端点短名 → 声明 */
+type Registry = Record<string, AnyEndpointDef>;
+/** 取端点的参数 schema 类型 */
+type ParamsSchemaOf<D> = D extends EndpointDef<infer P, unknown, any, any, any> ? P : never;
+/** 取端点「校验后的参数」类型（对应 `zod.infer`）——build / merge / nextParams 取它 */
+type ParsedOf<D> = D extends EndpointDef<infer P, unknown, any, any, any> ? zod.infer<P> : never;
+/** 内部参数的 phantom 品牌键。只存在于类型里；运行时由 `.meta()` 携带同一标记 */
+declare const InternalBrand: unique symbol;
+/**
+ * 内部参数的 schema 类型：`internalParam()` 的返回。
+ *
+ * 交叉出来的品牌是 phantom —— schema 的运行时行为不变，`zod.infer` 读到的
+ * `output` / `input` 也不受影响（品牌键上没有这些属性，TS 从 S 侧解析）。
+ */
+type InternalParam<S extends zod.ZodType> = S & {
+  readonly [InternalBrand]: true;
+};
+/** 从 params schema 的 shape 里筛出内部参数的键名（类型层，读 phantom 品牌） */
+type InternalKeysOf<S> = S extends zod.ZodObject<infer Shape> ? { [K in keyof Shape]-?: Shape[K] extends {
+  readonly [InternalBrand]: true;
+} ? K : never; }[keyof Shape] : never;
+/**
+ * 调用方能传的参数：校验后的形状挖掉内部参数。
+ *
+ * fetcher / 静态 fetcher 的 options 取它。`ParsedOf` 仍归 build / merge / nextParams
+ * —— 它们要读写内部参数（翻页游标这类），URL 构造器同样取完整形状。
+ */
+type PublicParamsOf<D> = Omit<ParsedOf<D>, InternalKeysOf<ParamsSchemaOf<D>>>;
+/** 取端点的响应数据类型 */
+type DataOf<D> = D extends EndpointDef<any, infer T, any, any, any> ? T : never;
+//#endregion
+//#region src/platforms/kuaishou/api.d.ts
+/**
+ * 快手 URL 构造（请求描述）。
+ *
+ * 参数类型在本文件本地定义，只负责返回请求描述对象，不发起网络请求。
+ *
+ * `videoWork` / `comments` 两条走 H5 命名空间 —— 见 {@link KUAISHOU_H5_HOST}。
+ *
+ * ## 几条**没有**实现的接口
+ *
+ * - **搜索 / 创作者搜索 / 热榜**（`/rest/v/search`、`/rest/v/feed/hot` 一类）：
+ *   这三个要「浏览器激活过的真实 did」。真实 did 得先在浏览器里走
+ *   `gdfp.gifshow.com/s/w/c` 完成设备指纹注册，**服务端有账本**，本地造不出来。
+ *   实测过 5 种组合（随机 did + 借来的完整风控指纹、服务端刚下发的新 did、
+ *   新 did 先走 `system/startup` 预热、Node 侧裸打 `gdfp` 注册……）全部被拒。
+ *   amagi 的 did 是内部生成的，所以这条**绕不过去**。
+ * - **音乐标签页**：可用做法是抓分享页 HTML 解 `INIT_STATE`，而不是打 `tag/music/*`
+ *   接口。抓 HTML 解全局变量不属于「接口库」该干的事，不实现。
+ * - **相关推荐 `/rest/wd/ugH5App/slide/feed`、搜索热词 `/rest/wd/ugH5App/search/guess`**：
+ *   两条都免签、都能做，只是当前没有下游需要，按需再加。
+ *
+ * 上述实测结论来自 @OduckO 的 kuaishou-parser（GPL-3.0-only）：
+ * https://github.com/OduckO
+ */
+/** `videoWork` 参数 */
+interface VideoInfoParams {
+  /** 作品 ID */
+  photoId: string;
+  /** 业务标识，H5 分享页恒为 `NEBULA` */
+  kpn?: string;
+  /** 子业务，空串即可 */
+  subBiz?: string;
+  /** 以下 8 个 share 字段来自短链展开后的 URL query；直接用 photoId 调用时全传空串 */
+  fid?: string;
+  efid?: string;
+  shareToken?: string;
+  shareObjectId?: string;
+  shareMethod?: string;
+  shareId?: string;
+  shareResourceType?: string;
+  /** 分享渠道，取短链 query 里的 `cc` */
+  shareChannel?: string;
+  /** 分享页域名，恒为 `c.kuaishou.com` */
+  h5Domain?: string;
+  /** 是否长视频 */
+  isLongVideo?: boolean;
+}
+/** `comments` 参数 */
+interface CommentParams {
+  /** 作品 ID */
+  photoId: string;
+  /** 分页游标；为空时请求首屏评论 */
+  pcursor?: string;
+}
+/** `userProfile` / `liveRoomInfo` 参数 */
+interface UserProfileParams {
+  /** 用户主页 principalId，可直接取 profile 页 URL 末段 */
+  principalId: string;
+}
+/** `userWorkList` 参数 */
+interface UserWorkListParams {
+  /** 用户主页 principalId */
+  principalId: string;
+  /** 分页游标；为空时请求首屏作品列表 */
+  pcursor?: string;
+  /** 每页数量，默认 12 */
+  count?: number;
+}
+/** `liveRoomInfo` 参数 */
+interface LiveRoomInfoParams {
+  /** 直播间 principalId，可直接取 /u/{principalId} URL 末段 */
+  principalId: string;
+}
+/** `danmaku` 参数 */
+interface DanmakuParams {
+  /** 作品 ID */
+  photoId: string;
+  /** 窗口起点（毫秒，**含**） */
+  positionFromInclude: number;
+  /**
+   * 窗口终点（毫秒，**排他**）。
+   *
+   * 与起点的差**必须 < 60000** —— 达到 60000 时接口回 `result: 1` 但
+   * `danmakus: []`，不报错、静默给空数组。窗口的收窄由端点负责，这里只描述请求。
+   */
+  positionToExclude: number;
+  /** 分页游标。弹幕不靠游标翻页（实测恒回 `no_more`），传空串即可 */
+  pcursor?: string;
+  /** 请求时间戳，前端传 `Date.now()`；不传由构造器补 */
+  timestamp?: number;
+}
+type KuaishouBaseApiRequest = {
+  type: string;
+  url: string;
+};
+/**
+ * 快手 `live_api` 请求描述对象。
+ *
+ * 除了最终请求地址外，还可以携带 `signPath`，用于声明
+ * `__NS_hxfalcon` 实际参与签名的规范路径。
+ */
+type KuaishouLiveApiRequest = KuaishouBaseApiRequest & {
+  method: 'GET' | 'POST';
+  requiresSign?: boolean;
+  signPath?: string;
+  body?: Record<string, unknown>;
+};
+/**
+ * 快手 GraphQL 请求描述对象。
+ *
+ * 该结构只负责描述请求，不负责执行网络请求。
+ */
+type KuaishouGraphqlRequest = KuaishouBaseApiRequest & {
+  body: {
+    operationName: string;
+    variables: Record<string, unknown>;
+    query: string;
+  };
+};
+/**
+ * 快手 H5 请求描述对象。
+ *
+ * 与 `live_api` 的差别：H5 接口一律 POST + JSON body，参数**必须在 body 里**
+ * （放 query 会拿到 `result=1` 但 0 条数据），且 body 参与签名。
+ */
+type KuaishouH5Request = KuaishouBaseApiRequest & {
+  method: 'POST';
+  /** 是否需要 `__NS_hxfalcon`。`ugH5App/*` 那几个免签 */
+  requiresSign: boolean;
+  /** 规范签名路径（H5 接口与公开路径一致，显式给出便于端点直接透传） */
+  signPath: string;
+  body: Record<string, unknown>;
+  /** 分享页 Referer。H5 接口按分享页来源校验，桌面的 `/new-reco` 不适用 */
+  referer: string;
+};
+//#endregion
+export { RawResponse as A, TraceReason as C, ErrorKind as D, AmagiErrorCode as E, RequestSpec as M, RiskChallenge as O, RequestTrace as S, AmagiError as T, SignDecl as _, KuaishouLiveApiRequest as a, SignStep as b, UserWorkListParams as c, DataOf as d, EndpointDef as f, Registry as g, PublicParamsOf as h, KuaishouH5Request as i, RequestConfig as j, ValidationIssue as k, VideoInfoParams as l, ParsedOf as m, DanmakuParams as n, LiveRoomInfoParams as o, InternalParam as p, KuaishouGraphqlRequest as r, UserProfileParams as s, CommentParams as t, AnyEndpointDef as u, SignFn as v, Platform as w, AmagiMeta as x, SignPhase as y };