@heybox/hb-sdk-protocol 0.9.1-alpha.3 → 0.9.1-alpha.5

package/src/payloads.ts

@@ -1,1080 +0,0 @@
-/** 当前用户信息与登录能力支持的完整 scope 目录（canonical 顺序）。 */
-export const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile', 'steam_account'] as const;
-
-/** 用户信息授权 scope。 */
-export type UserInfoAuthorizationScope = (typeof USER_INFO_AUTHORIZATION_SCOPES)[number];
-
-/** 登录请求使用与用户信息授权相同的 canonical scope。 */
-export type LoginScope = UserInfoAuthorizationScope;
-export type LoginPayload = { scopes?: LoginScope[] } | undefined;
-export interface LoginResult {
-  code: string;
-  expiresIn: number;
-  scopes: LoginScope[];
-}
-
-/**
- * 单个用户信息 scope 对当前小程序的授权状态。
- *
- * @remarks
- * - `not_required`：Host 判定该 scope 无需单独征得用户同意。
- * - `not_requested`：当前授权上下文尚未申请或授予该 scope。
- * - `granted`：当前小程序可以读取该 scope 对应的资料。
- * - `denied`：用户拒绝过该 scope，或该 scope 已被撤销。
- *
- * 该状态描述用户授权，不代表 `package.json#heybox.permissions` 的声明或平台审批结果。
- * 当前 Runtime 成功执行 `user.getInfo()` 时会静默授予 `identity` 与 `profile`，因此两项均为
- * `granted`；支持 Steam 账号能力的 Host 还会授予 `steam_account`。其余状态仍保留在公共协议中，
- * 供兼容 Host 和授权状态事件使用。
- */
-export type UserInfoAuthorizationStatus = 'not_required' | 'not_requested' | 'granted' | 'denied';
-
-/**
- * 当前小程序对 canonical 用户信息 scope 的授权状态。
- *
- * @remarks
- * 该对象固定包含 `identity` 与 `profile`，新能力版本还可能包含可选的 `steam_account`。
- * `steam_account` 已授权不代表当前一定已绑定 Steam，只有
- * {@link AuthorizedUserInfo.steam_id} 存在才表示当前有主绑定。该对象只反映用户授权层；开发者仍需
- * 在 Manifest 中声明 `userInfo` / `steamLibrary`，两层门禁不能互相替代。
- */
-export interface UserInfoAuthorization {
-  /**
-   * 隔离身份授权状态；控制 `AuthorizedUserInfo.app_user_id` 是否可向当前小程序披露。
-   */
-  identity: UserInfoAuthorizationStatus;
-  /**
-   * 公开资料授权状态；控制 `AuthorizedUserInfo.profile` 中昵称和头像是否可披露。
-   */
-  profile: UserInfoAuthorizationStatus;
-  /** Steam 账号授权状态；legacy Runtime/Version 可能缺失该键。 */
-  steam_account?: UserInfoAuthorizationStatus;
-}
-
-/**
- * 已获准向当前小程序披露的用户资料。
- *
- * @remarks
- * 当前黑盒 APP 用户已登录时，Runtime 会隐式授予 `identity` 与 `profile`，静默建立或
- * 读取隔离身份，并由 `user.getInfo()` 返回该对象。此过程只要求 Manifest 声明
- * `userInfo`，不要求公开 `network` 权限，也不会返回授权码或创建开发者服务端会话。
- * 支持 Steam 账号能力的 Host 还会授予 `steam_account`；已授权且有主绑定时才包含 `steam_id`。
- *
- * 撤销授权后旧身份失效；调用方应停止使用旧值，并清理本地缓存与开发者服务端会话。
- * 再次调用 `user.getInfo()` 会按当前账号重新建立隔离身份，不能假定新旧 `app_user_id`
- * 相同。
- *
- * @see [auth.login](/reference/sdk/auth/login) 获取供开发者服务端换票的一次性授权码。
- * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization) 撤销当前小程序的用户授权。
- */
-export interface AuthorizedUserInfo {
-  /**
-   * 当前用户在当前小程序与当前授权有效期内稳定的隔离标识；不是黑盒用户 ID 或登录凭据。
-   *
-   * @remarks
-   * 该值在当前授权有效期内可作为“当前用户 × 当前小程序”的稳定关联键；同一用户在不同
-   * 小程序中的值不同，授权撤销后旧值失效。它不是黑盒用户 ID、登录凭据或主站私有接口凭据。
-   * 示例：
-   * `au_1_x7K9mQ2pL4vN8cR3tY6wB1zD5fH`。调用方必须把完整值视为不透明字符串，
-   * 不应解析格式、依赖固定长度或尝试跨小程序关联用户。
-   */
-  app_user_id: string;
-  /**
-   * `profile` 获准披露时返回公开资料：`nickname` 是展示昵称，`avatar` 是头像资源字符串；
-   * 未获准披露时为 `null`。
-   *
-   * @remarks
-   * 当前 Runtime 的静默读取会授予 `profile`；资料读取暂时失败时仍可能返回对象，但
-   * `nickname` 或 `avatar` 为空字符串。它们只适合展示，不应作为登录态、授权状态、
-   * 唯一用户标识或鉴权依据。
-   */
-  profile: {
-    /** 当前小黑盒账号的公开展示昵称；空字符串表示本次未取得可展示昵称。 */
-    nickname: string;
-    /** 当前小黑盒账号的公开头像资源字符串；空字符串表示本次未取得可展示头像。 */
-    avatar: string;
-  } | null;
-  /**
-   * `steam_account` 已授权且当前已绑定 Steam 时返回 canonical SteamID64。
-   *
-   * @remarks
-   * 始终表示为 string，禁止作为 JSON number 使用；未绑定时省略该字段，不返回空字符串或
-   * `null`。只返回主绑定 SteamID64，不包含 Steam 昵称、头像、好友码、公开状态或绑定来源。
-   */
-  steam_id?: string;
-}
-
-/**
- * 当前黑盒 APP 登录态、授权状态和已获准披露的用户资料。
- *
- * @remarks
- * 以 `isHeyboxAppLoggedIn` 作为判别字段处理返回值：
- *
- * - `false`：当前 Host 没有已登录的小黑盒账号，`authorization` 与 `userInfo` 固定为 `null`。
- *   这是正常业务分支，不会抛出登录错误。
- * - `true` 且 `userInfo` 非空：`authorization` 必含 `identity`、`profile`，支持时还包含 `steam_account`；
- *   `userInfo` 包含当前小程序隔离的 `app_user_id`，而 `profile` 仍需独立判空。
- * - `true` 且 `userInfo` 为 `null`：公共协议为兼容 Host 保留的“已登录但资料未披露/不可用”分支。
- *   当前 Runtime 成功读取隔离身份时返回非空对象，但调用方仍应按类型处理该分支。
- *
- * `user.getInfo()` 不返回 `code`、token、cookie 或黑盒用户 ID。需要建立开发者服务端会话时，
- * 应在可信用户操作中调用 `auth.login()`，再把一次性 `code` 交给开发者自己的服务端。
- *
- * @see [auth.login](/reference/sdk/auth/login)
- * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
- */
-export type MiniProgramUserInfoResult =
-  | {
-      /** `false` 是未登录分支的稳定判别值。 */
-      isHeyboxAppLoggedIn: false;
-      /** 未登录时没有当前小程序的用户授权上下文。 */
-      authorization: null;
-      /** 未登录时不会披露隔离身份或公开资料。 */
-      userInfo: null;
-    }
-  | {
-      /** `true` 表示 Host 当前有已登录的小黑盒账号，不等同于开发者服务端已建立会话。 */
-      isHeyboxAppLoggedIn: true;
-      /** 当前小程序的用户授权状态；与 Manifest 权限声明是两层独立门禁。 */
-      authorization: UserInfoAuthorization;
-      /** 已获准披露的隔离身份与公开资料；兼容 Host 可能返回 `null`。 */
-      userInfo: AuthorizedUserInfo | null;
-    };
-/** `user.getInfo` 不接收入参，也不能由页面指定小程序或用户身份。 */
-export type GetUserInfoPayload = void;
-/** `user.getInfo` 的判别联合返回值；先判断 `isHeyboxAppLoggedIn`，再判断 `userInfo`。 */
-export type GetUserInfoResult = MiniProgramUserInfoResult;
-/**
- * `user.revokeAuthorization` 不接受 wire payload。
- *
- * @remarks
- * 小程序 ID、当前小黑盒用户和可信手势状态由 Host 注入；发送任何非 `undefined` payload
- * 都会返回 `INVALID_PARAMS`。该 method 无需 Manifest 权限，但仍要求当前用户已登录且调用
- * 来自可信用户操作。
- *
- * @see [App-facing user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
- */
-export type RevokeAuthorizationPayload = void;
-/**
- * 撤销成功后的 wire 结果为 `undefined`。
- *
- * @remarks
- * 成功后 Runtime 会使缓存的用户授权和隔离身份失效，并发布
- * `user_info_authorization_change`；业务持久化数据和开发者服务端会话不在该结果的清理范围内。
- */
-export type RevokeAuthorizationResult = void;
-/**
- * Steam 游戏库排序维度：`weeks` 按最近两周时长，`all` 按累计时长，`achieved` 按成就数。
- */
-export type SteamGameListSort = 'weeks' | 'all' | 'achieved';
-/** `user.getSteamGameList` 的 wire 请求对象；字段校验和默认值由 Host Runtime 执行。 */
-interface GetSteamGameListRequest {
-  /** trim 后的非空 Steam ID；省略时使用当前用户的默认绑定账号。 */
-  steamId?: string;
-  /** 正整数页大小，默认 `20`，大于 `100` 时收窄为 `100`。 */
-  limit?: number;
-  /** 非负整数 offset，默认 `0`。 */
-  offset?: number;
-  /** 排序维度，默认 `weeks`。 */
-  sort?: SteamGameListSort;
-  /** trim 后最多保留前 100 个 UTF-16 code unit；空值会被省略。 */
-  q?: string;
-  /** 是否包含隐藏游戏，默认 `false`；仅接受 boolean。 */
-  includeHidden?: boolean;
-}
-/**
- * `user.getSteamGameList` 的可选 wire payload；`undefined` 使用全部默认查询值。
- *
- * @remarks
- * Host 会拒绝未知字段、数字字符串和用 `0` / `1` 代替 boolean 的值。该 method 要求
- * `steamLibrary` 权限，但不要求公开 `network` 权限或可信用户手势。
- *
- * @see [App-facing user.getSteamGameList](/reference/sdk/user/getSteamGameList)
- */
-export type GetSteamGameListPayload = GetSteamGameListRequest | undefined;
-/**
- * Steam 游戏价格 wire 结果。所有字段都可省略，且协议不携带币种或最小货币单位。
- */
-export type SteamGamePrice = {
-  /** 当前售价的非空展示文本。 */
-  current?: string;
-  /** 原价的非空展示文本。 */
-  initial?: string;
-  /** 服务端原始折扣数值；协议不承诺比例、百分比或取值范围。 */
-  discount?: number;
-  /** 服务端最低价数值；币种和缩放单位不属于本协议。 */
-  lowestPrice?: number;
-  /** 截止时间展示文本，不保证可解析为日期。 */
-  deadlineDate?: string;
-  /** 服务端原始折扣截止时间数值；协议不承诺单位或时钟来源。 */
-  deadlineTimestamp?: number;
-};
-/**
- * 经过 Host Runtime 规范化的 Steam 游戏条目；无效必填字段会导致整条记录被移除。
- */
-export interface SteamGameListItem {
-  /** 小黑盒游戏目录 ID。 */
-  appid: number;
-  /** Steam App ID；缺失时由 Host 回退为 `appid`。 */
-  steamAppid: number;
-  /** trim 后的非空名称。 */
-  name: string;
-  /** 非空封面或主图 URL 字符串。 */
-  image?: string;
-  /** 非空 Steam 图标 URL 字符串。 */
-  icon?: string;
-  /** Steam 游戏库接口返回的累计游玩时长，当前单位为秒；`0` 是有效值。 */
-  playtimeForever?: number;
-  /** Steam 游戏库接口返回的最近两周游玩时长，当前单位为秒；`0` 是有效值。 */
-  playtime2Weeks?: number;
-  /** 非空标签列表；没有有效标签时省略。 */
-  tags?: string[];
-  /** 至少有一个可用价格字段时存在。 */
-  price?: SteamGamePrice;
-}
-/** Steam 游戏库的 offset 分页结果。 */
-export interface SteamGameListData {
-  /** 当前页通过规范化校验的游戏条目。 */
-  gameList: SteamGameListItem[];
-  /** 服务端游戏总数；缺失或无效时省略。 */
-  total?: number;
-  /** 有 `total` 时按 `nextOffset < total` 计算，否则按本页是否达到有效 `limit` 推断。 */
-  hasMore: boolean;
-  /** `请求 offset + gameList.length`；下一页应直接复用该值。 */
-  nextOffset: number;
-  /** 服务端对结果是否属于当前用户本人的标记；不可识别时省略。 */
-  isMe?: boolean;
-}
-/**
- * `user.getSteamGameList` 的判别联合结果。
- *
- * @remarks
- * - `isLogin: false`：未登录，`isBound` 固定为 `false`，`data` 固定为 `null`。
- * - `isLogin: true, isBound: false`：已登录但未绑定 Steam，`data` 固定为 `null`。
- * - 两者均为 `true`：`data` 固定为 {@link SteamGameListData}，其中 `gameList` 可以为空。
- */
-export type GetSteamGameListResult =
-  | { isLogin: false; isBound: false; data: null }
-  | { isLogin: true; isBound: false; data: null }
-  | { isLogin: true; isBound: true; data: SteamGameListData };
-
-/** 公开分享渠道；Host 可以只支持其中一部分，值区分大小写。 */
-export type MiniProgramShareChannel = 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
-/** 社区发帖页的可编辑分区与话题预置。 */
-export interface MiniProgramSharePostOptions {
-  /** 正安全整数或 trim 后非空字符串；Runtime 转为字符串并去重。 */
-  topicIds?: (string | number)[];
-  /** trim 后非空且不以 `#` 开头或结尾的字符串；Runtime 去重。 */
-  topics?: string[];
-}
-export interface MiniProgramScreenshotRect {
-  left: number;
-  top: number;
-  width: number;
-  height: number;
-}
-/**
- * `share.showShareMenu` 的 wire payload；落地页由 Runtime 固定生成，不接受 `url` 字段。
- */
-export type ShowShareMenuPayload = {
-  /** trim 后必须非空；原字符串会交给 Host。 */
-  title: string;
-  /** trim 后必须非空；原字符串会交给 Host。 */
-  desc: string;
-  /** 经 Runtime 校验并编码到固定分享 URL 的 JSON-compatible 状态。 */
-  extra?: unknown;
-  /** 可解析的绝对 HTTP(S) 缩略图 URL。 */
-  imageUrl?: string;
-  /** 可选站外渠道；不能与有效社区 `post` 同时使用。 */
-  channel?: MiniProgramShareChannel;
-  /**
-   * 可编辑社区预置；`null` 等同省略。普通分享最多保留一个分区，开发态严格拒绝无效项，
-   * 生产态过滤无效项并在与 `channel` 冲突时省略 `post`。
-   */
-  post?: MiniProgramSharePostOptions | null;
-};
-/**
- * Host 分享面板返回的不透明值。
- *
- * @remarks 可能是 `undefined` 或任意对象；不能依赖结构或真假值判断用户分享结果。
- */
-export type ShowShareMenuResult = unknown;
-export type CopyLinkPayload = { extra?: unknown } | undefined;
-export type CopyLinkResult = string;
-export type ScreenshotPayload =
-  | {
-      rect?: MiniProgramScreenshotRect;
-      delay?: number;
-      saveToAlbum?: boolean;
-      post?: MiniProgramSharePostOptions | null;
-    }
-  | undefined;
-export type ScreenshotResult = unknown;
-
-/** 当前小程序实例的运行模式。 */
-export type MiniProgramRuntimeMode = 'production' | 'preview' | 'development' | 'unknown';
-
-/** Host 明确提供的操作系统名称。 */
-export type MiniProgramOperatingSystemName = 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown';
-
-/**
- * Runtime 在握手期间下发的环境快照。
- *
- * @remarks
- * 所有字段只用于界面适配、兼容降级和诊断，不能作为鉴权、权限控制或风控依据。
- * 版本字段均为不透明字符串，除缺失判断外不承诺格式或大小比较语义。
- */
-export interface MiniProgramRuntimeEnvironmentInfo {
-  readonly runtime: {
-    readonly mode: MiniProgramRuntimeMode;
-  };
-  readonly host: {
-    readonly appVersion: string | null;
-  };
-  readonly miniProgram: {
-    readonly id: string | null;
-    readonly version: string | null;
-  };
-  readonly operatingSystem: {
-    readonly name: MiniProgramOperatingSystemName;
-    readonly version: string | null;
-  };
-}
-
-export interface GetStoragePayload {
-  key: string;
-}
-export interface GetStorageResult<T = unknown> {
-  data: T | undefined;
-}
-export interface SetStoragePayload {
-  key: string;
-  data: unknown;
-}
-
-export interface MiniProgramSafeArea {
-  left: number;
-  right: number;
-  top: number;
-  bottom: number;
-  width: number;
-  height: number;
-}
-export interface MiniProgramWindowInfoResult {
-  pixelRatio: number;
-  screenWidth: number;
-  screenHeight: number;
-  windowWidth: number;
-  windowHeight: number;
-  statusBarHeight: number;
-  safeArea: MiniProgramSafeArea;
-  screenTop: number;
-}
-/** 小程序窗口方向。 */
-export type MiniProgramOrientationMode = 'portrait' | 'landscape';
-/** 宿主确认生效的小程序展示状态；不表示手机旋转传感器状态。 */
-export interface MiniProgramDisplayState {
-  /** 当前小程序锁定的窗口方向。 */
-  orientation: MiniProgramOrientationMode;
-  /** 是否同时收起胶囊和宿主额外顶部栏；横屏始终为 true。 */
-  fullscreen: boolean;
-}
-export interface SetDisplayPayload {
-  /** 锁定竖屏或横屏；省略保持当前目标方向，初始为 portrait。 */
-  orientation?: MiniProgramOrientationMode;
-  /** 同时收起胶囊和宿主额外顶部栏；省略保持当前目标值，初始为 false。合并后横屏强制 true；退出横屏全屏需同时设置 portrait 和 false。 */
-  fullscreen?: boolean;
-}
-/** 本次展示设置的原生支持结果；不支持时保留原生状态，宿主仍可尽力收起 H5 顶部栏。 */
-export type SetDisplayResult = {
-  /** true 表示原生方向与胶囊设置已完成；false 表示已按宿主可用能力降级。 */
-  supported: boolean;
-};
-
-export type GetWindowInfoPayload = void;
-export type GetWindowInfoResult = MiniProgramWindowInfoResult;
-export type MiniProgramNavigationBarForegroundStyle = 'light' | 'dark';
-export type SetNavigationBarStylePayload = { foregroundStyle: MiniProgramNavigationBarForegroundStyle };
-export type SetNavigationBarStyleResult = void;
-
-export type MiniProgramNetworkHeaders = Record<string, string>;
-export type MiniProgramNetworkParams = Record<string, unknown>;
-export type MiniProgramNetworkRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
-export interface NetworkRequestPayload {
-  url: string;
-  method?: MiniProgramNetworkRequestMethod;
-  params?: MiniProgramNetworkParams;
-  data?: unknown;
-  headers?: MiniProgramNetworkHeaders;
-  timeout?: number;
-}
-export interface NetworkResponsePayload<T = unknown> {
-  data: T;
-  status: number;
-  statusText?: string;
-  headers: MiniProgramNetworkHeaders;
-}
-
-export type MiniProgramFileMode = 'read' | 'readwrite';
-
-export interface MiniProgramSandboxRootRef {
-  kind: 'sandbox';
-}
-
-export interface MiniProgramDirectFileRef {
-  kind: 'file';
-  handleId: string;
-}
-
-export interface MiniProgramDirectDirectoryRef {
-  kind: 'directory';
-  handleId: string;
-}
-
-export type MiniProgramPathRootRef = MiniProgramSandboxRootRef | MiniProgramDirectDirectoryRef;
-
-export interface MiniProgramDerivedFileRef {
-  kind: 'file';
-  root: MiniProgramPathRootRef;
-  relativePath: string;
-}
-
-export interface MiniProgramDerivedDirectoryRef {
-  kind: 'directory';
-  root: MiniProgramPathRootRef;
-  relativePath: string;
-}
-
-export type MiniProgramFileRef = MiniProgramDirectFileRef | MiniProgramDerivedFileRef;
-export type MiniProgramDirectoryRef = MiniProgramDirectDirectoryRef | MiniProgramDerivedDirectoryRef;
-export type MiniProgramFileSystemEntityRef = MiniProgramFileRef | MiniProgramDirectoryRef;
-
-export interface MiniProgramFileDescriptor {
-  kind: 'file';
-  name: string;
-  mode: MiniProgramFileMode;
-  ref: MiniProgramFileRef;
-}
-
-export interface MiniProgramDirectoryDescriptor {
-  kind: 'directory';
-  name: string;
-  mode: MiniProgramFileMode;
-  ref: MiniProgramDirectoryRef;
-}
-
-export type MiniProgramFileSystemEntityDescriptor = MiniProgramFileDescriptor | MiniProgramDirectoryDescriptor;
-
-export interface MiniProgramCreateOptions {
-  recursive?: boolean;
-  exclusive?: boolean;
-}
-
-export interface MiniProgramFileStat {
-  kind: 'file';
-  size: number;
-  modifiedAt?: number;
-  createdAt?: number;
-}
-
-export type PickFilesPayload =
-  | {
-      mode?: MiniProgramFileMode;
-      accept?: string[];
-      multiple?: boolean;
-    }
-  | undefined;
-export type PickFilesResult = Array<MiniProgramFileDescriptor & { ref: MiniProgramDirectFileRef }>;
-
-export type PickDirectoryPayload = { mode?: MiniProgramFileMode } | undefined;
-export type PickDirectoryResult = MiniProgramDirectoryDescriptor & { ref: MiniProgramDirectDirectoryRef };
-
-export interface SaveFilePayload {
-  suggestedName: string;
-}
-export type SaveFileResult = MiniProgramFileDescriptor & { ref: MiniProgramDirectFileRef };
-
-export interface FileCreatePayload extends MiniProgramCreateOptions {
-  target: MiniProgramFileRef;
-}
-export type FileCreateResult = void;
-
-export interface FileRemovePayload {
-  target: MiniProgramFileRef;
-}
-export type FileRemoveResult = void;
-
-export interface FileExistsPayload {
-  target: MiniProgramFileRef;
-}
-export type FileExistsResult = boolean;
-
-export interface FileReadTextPayload {
-  target: MiniProgramFileRef;
-}
-export type FileReadTextResult = string;
-
-export interface FileWriteTextPayload {
-  target: MiniProgramFileRef;
-  content: string;
-}
-export type FileWriteTextResult = void;
-
-export interface FileReadBytesPayload {
-  target: MiniProgramFileRef;
-}
-export type FileReadBytesResult = Uint8Array;
-
-export interface FileWriteBytesPayload {
-  target: MiniProgramFileRef;
-  content: Uint8Array;
-}
-export type FileWriteBytesResult = void;
-
-export interface FileStatPayload {
-  target: MiniProgramFileRef;
-}
-export type FileStatResult = MiniProgramFileStat;
-
-export interface DirectoryCreatePayload extends MiniProgramCreateOptions {
-  target: MiniProgramDirectoryRef;
-}
-export type DirectoryCreateResult = void;
-
-export interface DirectoryRemovePayload {
-  target: MiniProgramDirectoryRef;
-  recursive?: boolean;
-}
-export type DirectoryRemoveResult = void;
-
-export interface DirectoryExistsPayload {
-  target: MiniProgramDirectoryRef;
-}
-export type DirectoryExistsResult = boolean;
-
-export interface DirectoryListPayload {
-  target: MiniProgramDirectoryRef;
-  limit?: number;
-}
-export type DirectoryListResult = MiniProgramFileSystemEntityDescriptor[];
-
-export interface DownloadProgressPayload {
-  loaded: number;
-  total?: number;
-  lengthComputable: boolean;
-}
-
-interface NetworkDownloadBasePayload {
-  url: string;
-  params?: MiniProgramNetworkParams;
-  headers?: MiniProgramNetworkHeaders;
-  timeout?: number;
-  maxBytes?: number;
-}
-
-export type NetworkDownloadPayload = NetworkDownloadBasePayload &
-  (
-    | {
-        to: MiniProgramFileRef;
-        suggestedName?: never;
-        overwrite?: never;
-      }
-    | {
-        to: MiniProgramDirectoryRef;
-        suggestedName?: string;
-        overwrite?: boolean;
-      }
-  );
-
-export type NetworkDownloadResult = MiniProgramFileDescriptor;
-
-export type MiniProgramToastStatus = 'success' | 'error';
-export interface ShowToastPayload {
-  message: string;
-  status?: MiniProgramToastStatus;
-}
-export type ShowToastResult = void;
-export interface ShowLoadingPayload {
-  dismissible?: boolean;
-}
-export type ShowLoadingResult = void;
-export type HideLoadingPayload = void;
-export type HideLoadingResult = void;
-export type MiniProgramVibrateIntensity = 'light' | 'medium' | 'heavy';
-export interface VibratePayload {
-  intensity?: MiniProgramVibrateIntensity;
-  delay?: number;
-}
-export type VibrateResult = void;
-export interface SetClipboardPayload {
-  text: string;
-}
-export type SetClipboardResult = void;
-
-/**
- * `navigation.close` 的无参 wire payload。
- *
- * @remarks
- * App-facing API 发送 `undefined`。Host Runtime 为兼容协议也接受空普通对象，但非空对象、
- * 数组或其他值会返回 `INVALID_PARAMS`；payload 不能携带强制关闭、原因或窗口标识。
- *
- * @see [App-facing navigation.close](/reference/sdk/navigation/close)
- */
-export type ClosePayload = void;
-/**
- * Host 接受关闭请求后的 wire 结果为 `undefined`。
- *
- * @remarks
- * 该结果不保证 iframe 在响应抵达后继续存活，也不包含最终关闭状态。Host 销毁环境时会尽力
- * 派发 `unload`；关键持久化不能依赖 Promise 后续语句或 `unload` 回调。
- */
-export type CloseResult = void;
-/**
- * `navigation.reload` 的无参 wire payload。
- *
- * @remarks
- * App-facing API 发送 `undefined`。Host Runtime 为兼容协议也接受空普通对象，但非空对象、
- * 数组或其他值会返回 `INVALID_PARAMS`；payload 不能指定缓存策略、目标 URL 或 reload 模式。
- *
- * @see [App-facing navigation.reload](/reference/sdk/navigation/reload)
- */
-export type ReloadPayload = void;
-/**
- * Host 接受 reload 请求后的 wire 结果为 `undefined`。
- *
- * @remarks
- * 该结果不包含新页面加载状态或新 SDK 实例。旧页面内存、监听和 pending 请求不会跨 reload
- * 保留；关键持久化不能依赖 Promise 后续语句或 `unload` 回调。
- */
-export type ReloadResult = void;
-/** 允许打开的 App 页面与公开小程序目标白名单；不包含任意 URL、scheme 或内部路由。 */
-export type MiniProgramAppPageTarget = 'game_detail' | 'user_detail' | 'post_detail' | 'mini_program';
-/** 游戏平台类型：PC、主机或移动游戏。 */
-export type MiniProgramGameDetailGameType = 'pc' | 'console' | 'mobile';
-/** 游戏详情首屏：详情主页或百科页。 */
-export type MiniProgramGameDetailPage = 'game' | 'wiki';
-/** 打开游戏详情页的规范化 wire payload。 */
-export type OpenGameDetailAppPagePayload = {
-  /** 固定判别值。 */
-  target: 'game_detail';
-  /** trim 后的非空游戏 app ID 字符串。 */
-  appId: string;
-  /** 只允许 `pc`、`console`、`mobile`。 */
-  gameType: MiniProgramGameDetailGameType;
-  /** 可选首屏，只允许 `game` 或 `wiki`。 */
-  page?: MiniProgramGameDetailPage;
-  /** trim 后的非空来源标识。 */
-  hSrc?: string;
-  /** trim 后的非空 SKU ID 字符串。 */
-  skuId?: string;
-};
-/** 打开用户详情页的规范化 wire payload。 */
-export type OpenUserDetailAppPagePayload = {
-  /** 固定判别值。 */
-  target: 'user_detail';
-  /** trim 后的非空 `heybox_id` 字符串。 */
-  userId: string;
-};
-/** 打开帖子详情页的规范化 wire payload。 */
-export type OpenPostDetailAppPagePayload = {
-  /** 固定判别值。 */
-  target: 'post_detail';
-  /** trim 后的非空帖子 ID 字符串。 */
-  linkId: string;
-  /** 可选的非空根评论 ID 字符串。 */
-  rootCommentId?: string;
-  /** 可选的非空目标评论 ID 字符串。 */
-  commentId?: string;
-};
-/** 打开另一个公开发布小程序的 wire payload；目标版本与访问性由 Host 决定。 */
-export type OpenMiniProgramAppPagePayload = {
-  /** 固定判别值。 */
-  target: 'mini_program';
-  /** trim 后的非空目标小程序 ID。 */
-  miniProgramId: string;
-  /** 可选 JSON-compatible 启动数据；Runtime 会按分享 `extra` 合同再次校验和编码。 */
-  extra?: unknown;
-};
-/**
- * `navigation.openAppPage` 的判别联合 wire payload。
- *
- * @remarks
- * Runtime 只读取上述白名单字段并构造固定 Host 路由；额外 URL、path、scheme 或窗口字段
- * 不会透传。移动端 Host 支持全部四类目标；当前 PC Host 支持 `game_detail` 与 `mini_program`，
- * 仍拒绝用户详情和帖子详情。
- *
- * @see [App-facing navigation.openAppPage](/reference/sdk/navigation/openAppPage)
- */
-export type OpenAppPagePayload =
-  | OpenGameDetailAppPagePayload
-  | OpenUserDetailAppPagePayload
-  | OpenPostDetailAppPagePayload
-  | OpenMiniProgramAppPagePayload;
-/**
- * Host 接收参数并发起受控路由后的结果为 `undefined`。
- *
- * @remarks 不表示目标页加载完成，也不返回目标页数据、关闭结果或回调值。
- */
-export type OpenAppPageResult = void;
-
-export type LeaderboardOrder = 'asc' | 'desc';
-export interface LeaderboardEntry {
-  rank: number;
-  ranked: boolean;
-  appUserId: string;
-  score: number;
-  extra: Record<string, unknown>;
-  createdAt: number;
-  updatedAt: number;
-}
-export interface SubmitLeaderboardEntryPayload {
-  key?: string;
-  score: number;
-  extra?: Record<string, unknown>;
-}
-export type SubmitLeaderboardEntryResult = LeaderboardEntry;
-export interface GetLeaderboardListPayload {
-  key?: string;
-  limit?: number;
-  cursor?: string;
-}
-export interface GetLeaderboardListResult {
-  entries: LeaderboardEntry[];
-  cursor?: string;
-  hasMore: boolean;
-}
-export interface GetCurrentUserLeaderboardEntryPayload {
-  key?: string;
-}
-export type GetCurrentUserLeaderboardEntryResult = LeaderboardEntry | undefined;
-export interface DeleteCurrentUserLeaderboardEntryPayload {
-  key?: string;
-}
-export interface DeleteCurrentUserLeaderboardEntryResult {
-  deleted: boolean;
-}
-export interface GetLeaderboardInfoPayload {
-  key?: string;
-}
-export interface GetLeaderboardInfoResult {
-  key: string;
-  order: LeaderboardOrder;
-  rankLimit: number;
-}
-
-/**
- * 当前 Companion 产物声明并由 Host 确认的可选能力。
- *
- * @remarks
- * - `stdio`：启动后的 Session 可以读写原始 stdin/stdout/stderr 字节流。
- * - `attachments`：Session 可以按 opaque ID 打开 Host 衰减为只读的受控附件。
- * - `notifications`：Session 可以请求 Host 展示固定类别的系统通知。
- *
- * 能力出现在 {@link CompanionInfo.capabilities} 只描述当前产物合同，不表示已经准备完成、
- * 已经启动或当前 Host 一定能成功执行每次操作。启动后仍应按 `CompanionSession` 对应可选
- * 属性是否存在进行分支。
- */
-export type CompanionCapability = 'stdio' | 'attachments' | 'notifications';
-
-/**
- * 当前 Host 为 Companion 选择的目标制品。
- *
- * @remarks
- * V1 仅支持 Windows x64 与 macOS arm64。该值是当前运行 Host 选中的一个 target，不是
- * Manifest 声明的全部 target 列表；当前平台没有匹配制品时 `companion.getInfo()` 会拒绝，
- * 不会返回猜测值。
- */
-export type CompanionTarget = 'windows-x64' | 'macos-arm64';
-
-/**
- * Host 对当前 Companion 制品给出的签名检查状态。
- *
- * @remarks
- * `unsigned` 表示未签名，`valid` 表示 Host 已确认签名有效，`invalid` 表示签名校验失败，
- * `unknown` 表示 Host 尚不能确认。该字段用于展示和诊断，不会替代准备完整性校验、Host
- * 授权或操作系统安全策略；本地开发制品可以是 `unsigned`。
- */
-export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unknown';
-
-/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
-export const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
-
-/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
-export const COMPANION_ERROR_CODES = [
-  'COMPANION_UNSUPPORTED',
-  'COMPANION_PREVIEW_UNSUPPORTED',
-  'COMPANION_NOT_DECLARED',
-  'COMPANION_TARGET_UNSUPPORTED',
-  'COMPANION_NOT_PREPARED',
-  'COMPANION_PREPARATION_CANCELLED',
-  'COMPANION_DOWNLOAD_FAILED',
-  'COMPANION_DESCRIPTOR_UNAVAILABLE',
-  'COMPANION_ARCHIVE_INVALID',
-  'COMPANION_INTEGRITY_FAILED',
-  'COMPANION_ENTRYPOINT_INVALID',
-  'COMPANION_USER_CANCELLED',
-  'COMPANION_ELEVATION_DENIED',
-  'COMPANION_OS_BLOCKED',
-  'COMPANION_LAUNCH_FAILED',
-  'COMPANION_SESSION_VERSION_MISMATCH',
-  'COMPANION_SESSION_OWNERSHIP_LOST',
-  'COMPANION_SESSION_EXITED',
-  'COMPANION_PIPE_CLOSED',
-  'COMPANION_OUTPUT_LIMIT',
-  'COMPANION_PROCESS_CRASHED',
-  'COMPANION_ATTACHMENT_NOT_FOUND',
-  'COMPANION_NOTIFICATION_UNAVAILABLE',
-  'COMPANION_TERMINATE_FAILED',
-] as const;
-export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
-
-/**
- * Host 针对当前小程序版本与当前平台确认的 Companion 描述快照。
- *
- * @remarks
- * Runtime 会校验字段、去重并冻结 `capabilities`，再返回冻结对象；页面不应修改或缓存为
- * 跨版本事实。该结构刻意不包含准备 `state`、进度、`preparedAt`、Session ID、PID、物理
- * 路径、下载 URL、SHA-256、entrypoint 或单独的 Companion 版本号。
- *
- * 准备状态通过 `companion.getPreparationStatus()` 查询。Companion 随当前小程序审核版本、
- * 精确预览版本或本地开发快照绑定；`source` 只说明来源类别，不提供版本号，也不能用于
- * 比较版本新旧。
- *
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/companion/getInfo.html | companion.getInfo}
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/companion/getPreparationStatus.html | companion.getPreparationStatus}
- */
-export interface CompanionInfo {
-  /**
-   * 规范 alias；必须与请求值及 `package.json#heybox.companions` 中的 key 完全一致。
-   */
-  alias: string;
-  /**
-   * Host 确认的用户可见名称，只用于展示；不要把它当作稳定标识、文件名或版本号。
-   */
-  displayName: string;
-  /** 当前 Host 选中的目标制品；不是项目声明的全部 target。 */
-  target: CompanionTarget;
-  /**
-   * 当前产物声明且 Host 确认的去重能力列表；可能为空，不代表产物已准备或已启动。
-   */
-  capabilities: readonly CompanionCapability[];
-  /** 当前压缩归档大小，单位字节；是大于等于 `0` 的安全整数，不是解压后磁盘占用。 */
-  archiveBytes: number;
-  /** Host 对当前制品给出的签名检查状态；不能替代完整性校验或系统安全判断。 */
-  signatureStatus: CompanionSignatureStatus;
-  /**
-   * Host 确认的产物来源。
-   *
-   * @remarks
-   * `local-dev` 是当前 `hb-sdk dev` 绑定的本地快照；`preview` 是精确审核前预览版本；
-   * `released` 是已发布版本。旧 Host 缺省时为 `undefined`，只表示来源未知，不应回退为
-   * `released`。不要根据 alias、displayName、签名状态或页面 URL 自行推断来源。
-   */
-  source?: 'local-dev' | 'preview' | 'released';
-}
-
-/**
- * Host 最近一次 Companion 准备失败的公开摘要。
- *
- * @remarks
- * Runtime 只保留稳定领域错误码、规范化文案和重试建议；原生路径、下载地址、堆栈和其他
- * Host 诊断信息不会下发。该摘要描述最近一次准备，不代表当前正在自动重试。
- */
-export interface CompanionErrorSummary {
-  /** 稳定的 Companion 领域错误码；业务分支应比较该字段，不要比较 `message`。 */
-  code: CompanionErrorCode;
-  /** Runtime 根据错误码生成的安全展示文案；不承诺保留 Host 原始 message。 */
-  message: string;
-  /**
-   * Host 对“以新的可信用户操作再次调用 `prepare()` 是否可能成功”的建议。
-   *
-   * `true` 不会触发自动重试，也不绕过权限、授权、完整性或手势要求；调用方仍应采用
-   * 有界重试。`false` 表示不应原样循环重试，通常需要修改产物、配置或环境。
-   */
-  retryable: boolean;
-}
-
-/**
- * Host 持有的 Companion 准备操作的最近进度快照。
- *
- * @remarks
- * 三个阶段的计数都是非负安全整数。Runtime 只保证同一进度对象内当前值不大于已知总量，
- * 不定义 verifying/extracting 与下载字节之间的换算，也不保证不同阶段的 total 相同；进度
- * 只能用于展示当前阶段，不能作为归档完整性证据。
- */
-export type CompanionPrepareProgress =
-  | {
-      /** 下载阶段判别值。 */
-      phase: 'downloading';
-      /** Host 已下载的非负安全整数计数。 */
-      loaded: number;
-      /** Host 已知总量；未知时省略，存在时为不小于 `loaded` 的非负安全整数。 */
-      total?: number;
-    }
-  | {
-      /** 校验阶段判别值。 */
-      phase: 'verifying';
-      /** Host 已校验的非负安全整数计数，且不大于 `total`。 */
-      processed: number;
-      /** 当前校验阶段的非负安全整数总量。 */
-      total: number;
-    }
-  | {
-      /** 解压阶段判别值。 */
-      phase: 'extracting';
-      /** Host 已处理的非负安全整数计数，且不大于 `total`。 */
-      processed: number;
-      /** 当前解压阶段的非负安全整数总量。 */
-      total: number;
-    };
-
-/**
- * 当前小程序版本、当前平台与指定 alias 对应的 Host 准备状态快照。
- *
- * @remarks
- * 这是以 `state` 为判别字段的四态联合，Runtime 会冻结返回对象及嵌套的 `progress` 或
- * `error`。它描述 Host 持久状态，不等同于某个页面中 `prepare()` Promise 的状态，也不会
- * 随后台操作自动变化；需要最新值时重新调用 `companion.getPreparationStatus()`。
- *
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/companion/getPreparationStatus.html | companion.getPreparationStatus}
- */
-export type CompanionPreparationStatus =
-  | {
-      /** 当前版本与 target 尚无已原子提交的本地产物，也没有在途准备。 */
-      state: 'not-prepared';
-    }
-  | {
-      /** Host 正在下载、校验或解压；页面 reload 或隐藏不会自动取消该操作。 */
-      state: 'preparing';
-      /** 查询时 Host 保存的最近进度；这是快照，不是持续订阅。 */
-      progress: CompanionPrepareProgress;
-    }
-  | {
-      /** 当前版本产物已原子提交，可以由新的可信用户操作调用 `launch()`。 */
-      state: 'ready';
-      /**
-       * Host 提供的非负安全整数准备完成时间戳。
-       *
-       * 协议不公开时钟来源、时区或过期语义；只适合展示和诊断，不应用于授权、版本比较
-       * 或判断产物仍然有效。
-       */
-      preparedAt: number;
-    }
-  | {
-      /** 最近一次准备已失败，当前没有可由该状态直接启动的新产物。 */
-      state: 'failed';
-      /** 经过 Runtime 脱敏和规范化的失败摘要。 */
-      error: CompanionErrorSummary;
-    };
-
-/**
- * Host 归一化后的 Companion 进程终止原因。
- *
- * @remarks
- * - `exited`：进程自行退出并提供 exit code；不表示 code 必然为 `0`。
- * - `terminated`：Host 报告进程已被显式终止。
- * - `crashed`：Host 把终态归类为异常崩溃。
- * - `host-shutdown`：Host 或其进程监管环境关闭。
- * - `permission-revoked`：Companion 权限撤销导致 Session 终止。
- * - `output-limit`：Host 的输出上限导致 Session 终止。
- *
- * 该枚举描述 Host 确认的终态，不包含 controller ownership 转移；后者不会结束进程。
- */
-export type CompanionExitReason = 'exited' | 'terminated' | 'crashed' | 'host-shutdown' | 'permission-revoked' | 'output-limit';
-
-/**
- * Companion Session 的一次性退出结果。
- *
- * @remarks
- * 这是以 `reason` 判别的只读语义结果。Runtime 只接受上方固定 reason，并要求所有出现的
- * `exitCode` 都是 safe integer；非法 Host 事件会被丢弃，不会进入 SDK Session。
- * `reason: 'exited'` 必须携带 `exitCode`，其余 Host 终止原因可携带或省略。exit code 的正负、
- * 具体编号和成功含义由 Companion 与目标操作系统决定，SDK 不把它转换为 HTTP 状态、信号或错误码。
- *
- * @see [CompanionSession.waitForExit()](/reference/symbols/root/interfaces/CompanionSession#waitforexit)
- * @see [CompanionSession.onExit()](/reference/symbols/root/interfaces/CompanionSession#onexit)
- */
-export type CompanionExit =
-  | {
-      /** 进程自行退出；该分支始终提供一个 safe-integer `exitCode`。 */
-      reason: 'exited';
-      /** Companion / 操作系统提供的进程退出码；调用方应按自己的进程合同解释。 */
-      exitCode: number;
-    }
-  | {
-      /** Host 确认的非普通退出原因；不会取值 `exited`。 */
-      reason: Exclude<CompanionExitReason, 'exited'>;
-      /** Host 可提供的 safe-integer 进程退出码；缺失时不要自行填充 `0` 或其他哨兵值。 */
-      exitCode?: number;
-    };
-
-/** 活动 Session 的 wire 快照；不包含路径、PID 或原生句柄。 */
-export interface CompanionSessionSnapshot {
-  id: string;
-  alias: string;
-  target: CompanionTarget;
-  capabilities: readonly CompanionCapability[];
-  state: 'running';
-  controllerGeneration: number;
-}
-
-export interface CompanionAliasPayload {
-  alias: string;
-}
-export type CompanionGetInfoPayload = CompanionAliasPayload;
-export type CompanionGetInfoResult = CompanionInfo;
-export type CompanionGetPreparationStatusPayload = CompanionAliasPayload;
-export type CompanionGetPreparationStatusResult = CompanionPreparationStatus;
-export type CompanionPreparePayload = CompanionAliasPayload;
-export type CompanionPrepareResult = CompanionInfo;
-export type CompanionCancelPreparationPayload = CompanionAliasPayload;
-export type CompanionCancelPreparationResult = void;
-export type CompanionGetActiveSessionPayload = CompanionAliasPayload;
-export type CompanionGetActiveSessionResult = CompanionSessionSnapshot | undefined;
-export type CompanionLaunchPayload = CompanionAliasPayload;
-export type CompanionLaunchResult = CompanionSessionSnapshot;
-
-export interface CompanionSessionControllerPayload {
-  sessionId: string;
-  controllerGeneration: number;
-}
-export interface CompanionSessionWritePayload extends CompanionSessionControllerPayload {
-  data: Uint8Array;
-}
-export type CompanionSessionWriteResult = void;
-export type CompanionSessionCloseStdinPayload = CompanionSessionControllerPayload;
-export type CompanionSessionCloseStdinResult = void;
-export type CompanionSessionTerminatePayload = CompanionSessionControllerPayload;
-export type CompanionSessionTerminateResult = void;
-export interface CompanionSessionAckOutputPayload extends CompanionSessionControllerPayload {
-  stream: 'stdout' | 'stderr';
-  sequence: number;
-}
-export type CompanionSessionAckOutputResult = void;
-export interface CompanionOpenAttachmentPayload extends CompanionSessionControllerPayload {
-  id: string;
-}
-export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
-/**
- * 桌面辅助应用通知的语义类别：`completed` 为完成，`failed` 为失败，`stopped` 为停止，
- * `attention` 为需要用户关注。它只选择通知类别，不会改变进程或 session 状态。
- */
-export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
-export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
-  category: CompanionNotificationCategory;
-}
-export type CompanionShowNotificationResult = void;
-
-export interface CompanionSessionOutputPayload extends CompanionSessionControllerPayload {
-  stream: 'stdout' | 'stderr';
-  sequence: number;
-  data: Uint8Array;
-}
-export interface CompanionSessionExitPayload {
-  sessionId: string;
-  exit: CompanionExit;
-}
-export interface CompanionSessionOwnershipLostPayload {
-  sessionId: string;
-  controllerGeneration: number;
-}