@heybox/hb-sdk-protocol 0.9.1-alpha.1 → 0.9.1-alpha.11

package/src/permission-catalog.ts

@@ -1,193 +0,0 @@
-import type { MiniProgramBridgeMethod, MiniProgramCapabilityRisk } from './capabilities';
-
-export const MINI_PROGRAM_PERMISSION_KEYS = [
-  'userInfo',
-  'steamLibrary',
-  'share',
-  'storage',
-  'filesystem',
-  'clipboard',
-  'leaderboard',
-  'network',
-  'companion',
-] as const;
-
-export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
-export type MiniProgramPermissionRequirement =
-  | { readonly kind: 'none' }
-  | { readonly kind: 'all'; readonly permissions: readonly MiniProgramPermissionKey[] };
-export type MiniProgramPermissionAccess = 'declaration' | 'platform-approval';
-
-export interface MiniProgramPermissionConfigFieldDefinition {
-  readonly type: 'boolean';
-  readonly required: boolean;
-  readonly default: boolean;
-  readonly description: string;
-}
-
-export interface MiniProgramPermissionDefinition {
-  readonly key: MiniProgramPermissionKey;
-  readonly name: string;
-  readonly description: string;
-  readonly access: MiniProgramPermissionAccess;
-  readonly risk: MiniProgramCapabilityRisk;
-  readonly config: Readonly<Record<string, MiniProgramPermissionConfigFieldDefinition>>;
-  readonly methods: readonly MiniProgramBridgeMethod[];
-  readonly conditions: readonly string[];
-}
-
-export const MINI_PROGRAM_PERMISSION_CATALOG = [
-  {
-    key: 'userInfo',
-    name: '用户信息',
-    description: '登录小程序并读取当前用户的授权信息。',
-    access: 'declaration',
-    risk: 'medium',
-    config: {},
-    methods: ['auth.login', 'user.getInfo'],
-    conditions: ['继续执行黑盒登录、用户授权和可信手势规则。'],
-  },
-  {
-    key: 'steamLibrary',
-    name: 'Steam 游戏库',
-    description: '读取当前用户授权的 Steam 游戏库。',
-    access: 'declaration',
-    risk: 'high',
-    config: {},
-    methods: ['user.getSteamGameList'],
-    conditions: ['继续执行账号绑定和数据可用性规则。'],
-  },
-  {
-    key: 'share',
-    name: '分享',
-    description: '使用小程序分享、分享菜单和截图能力。',
-    access: 'declaration',
-    risk: 'medium',
-    config: {},
-    methods: ['share.copyLink', 'share.showShareMenu', 'share.screenshot'],
-    conditions: ['继续执行分享参数校验和 Host 支持检查。'],
-  },
-  {
-    key: 'storage',
-    name: '键值存储',
-    description: '读写按小程序隔离的简单键值数据。',
-    access: 'declaration',
-    risk: 'medium',
-    config: {},
-    methods: ['storage.getStorage', 'storage.setStorage'],
-    conditions: ['仅用于简单键值存储，不包含文件系统。'],
-  },
-  {
-    key: 'filesystem',
-    name: '文件系统',
-    description: '访问小程序沙盒文件和用户选择的外部文件。',
-    access: 'declaration',
-    risk: 'high',
-    config: {},
-    methods: [
-      'network.download',
-      'files.pickFiles',
-      'files.pickDirectory',
-      'files.saveFile',
-      'file.create',
-      'file.remove',
-      'file.exists',
-      'file.readText',
-      'file.writeText',
-      'file.readBytes',
-      'file.writeBytes',
-      'file.stat',
-      'directory.create',
-      'directory.remove',
-      'directory.exists',
-      'directory.list',
-    ],
-    conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
-  },
-  {
-    key: 'clipboard',
-    name: '剪贴板',
-    description: '向系统剪贴板写入文本。',
-    access: 'declaration',
-    risk: 'medium',
-    config: {},
-    methods: ['device.setClipboard'],
-    conditions: ['继续执行文本长度和 Host 支持限制。'],
-  },
-  {
-    key: 'leaderboard',
-    name: '排行榜',
-    description: '读写小程序云排行榜。',
-    access: 'declaration',
-    risk: 'medium',
-    config: {},
-    methods: [
-      'cloud.leaderboard.submit',
-      'cloud.leaderboard.getList',
-      'cloud.leaderboard.getCurrentUserEntry',
-      'cloud.leaderboard.deleteCurrentUserEntry',
-      'cloud.leaderboard.getInfo',
-    ],
-    conditions: ['排行榜必须已创建，用户和资源规则保持不变。'],
-  },
-  {
-    key: 'network',
-    name: '网络',
-    description: '通过 network 模块请求或下载外部资源。',
-    access: 'platform-approval',
-    risk: 'high',
-    config: {
-      useOfficialDomain: {
-        type: 'boolean',
-        required: false,
-        default: false,
-        description: '是否申请访问小黑盒官方域名。',
-      },
-    },
-    methods: ['network.request', 'network.download'],
-    conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
-  },
-  {
-    key: 'companion',
-    name: '桌面辅助应用',
-    description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
-    access: 'platform-approval',
-    risk: 'high',
-    config: {},
-    methods: [
-      'companion.getInfo',
-      'companion.getPreparationStatus',
-      'companion.prepare',
-      'companion.cancelPreparation',
-      'companion.getActiveSession',
-      'companion.launch',
-      'companion.session.write',
-      'companion.session.closeStdin',
-      'companion.session.terminate',
-      'companion.session.ackOutput',
-      'companion.openAttachment',
-      'companion.showNotification',
-    ],
-    conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
-  },
-] as const satisfies readonly MiniProgramPermissionDefinition[];
-
-export const MINI_PROGRAM_NO_DECLARATION_METHODS = [
-  'user.revokeAuthorization',
-  'ui.showToast',
-  'ui.showLoading',
-  'ui.hideLoading',
-  'viewport.getWindowInfo',
-  'viewport.setNavigationBarStyle',
-  'viewport.setDisplay',
-  'device.vibrate',
-  'navigation.close',
-  'navigation.reload',
-  'navigation.openAppPage',
-] as const satisfies readonly MiniProgramBridgeMethod[];
-
-const PERMISSION_KEY_SET = new Set<string>(MINI_PROGRAM_PERMISSION_KEYS);
-
-export function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey {
-  return PERMISSION_KEY_SET.has(key);
-}

package/src/permissions.ts

@@ -1,216 +0,0 @@
-import { MINI_PROGRAM_PERMISSION_KEYS, type MiniProgramPermissionKey } from './permission-catalog';
-
-const MANAGED_RUNTIME_PERMISSION_KEYS = new Set<string>(MINI_PROGRAM_PERMISSION_KEYS);
-
-/**
- * 判断字符串是否是当前协议目录管理的 canonical runtime permission key。
- *
- * @param key - 已确认类型为 `string` 的候选权限 key；若输入来自 `unknown` 边界，调用方须先完成字符串检查。
- * @returns 与 `MINI_PROGRAM_PERMISSION_KEYS` 中某项精确相等时返回 `true`，并将 TypeScript 类型收窄为
- * `MiniProgramPermissionKey`；未知、历史或格式不同的字符串返回 `false`。
- *
- * @remarks
- * 当前 canonical key 集合固定为：
- *
- * - `userInfo`
- * - `steamLibrary`
- * - `share`
- * - `storage`
- * - `filesystem`
- * - `clipboard`
- * - `leaderboard`
- * - `network`
- * - `companion`
- *
- * 匹配大小写敏感且按原字符串执行。该 guard 不 trim，因此 `' network '` 返回 `false`；历史权限 key
- * `network.request` 也返回 `false`，即使同名 capability method 仍是公开 method。消费完整 schema v1 权限快照时
- * 应使用 {@link parseMiniProgramRuntimePermissions}，由解析边界统一 trim，并把历史 `network.request` 归一为
- * canonical `network`。未知的 future key 同样返回 `false`；本 guard 不负责 parser 的前向兼容忽略策略。
- *
- * 类型谓词只把字符串收窄为 `MiniProgramPermissionKey` union，不读取权限 entry、status 或 config，也不检查
- * Manifest。返回 `true` 不表示权限已声明、平台已批准、Runtime snapshot 中存在、status 为 `enabled`、Host 支持，
- * 或当前 capability 已获准执行。尤其 `network` 与 `companion` 还需要平台批准；其他 declaration 权限也继续受
- * 各自适用的 Host、用户授权、可信手势、参数与业务策略约束。
- *
- * `MINI_PROGRAM_PERMISSION_CATALOG` 提供每个 key 的展示信息、access、风险、配置字段和 method 集合；具体 bridge
- * method 是否要求某项权限应以 {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES} 的 `requirement` 为准。`kind: 'none'`
- * 的 method 不会因为某个 key 被本 guard 识别而新增权限要求。
- *
- * @example
- * ```ts
- * import { isManagedMiniProgramRuntimePermissionKey } from '@heybox/hb-sdk/protocol';
- *
- * function acceptPermissionKey(candidate: unknown) {
- *   if (typeof candidate !== 'string') return undefined;
- *   return isManagedMiniProgramRuntimePermissionKey(candidate) ? candidate : undefined;
- * }
- *
- * acceptPermissionKey('filesystem'); // 'filesystem'
- * acceptPermissionKey('network'); // 'network'
- * acceptPermissionKey(' network '); // undefined：guard 不 trim
- * acceptPermissionKey('network.request'); // undefined：legacy key 只由 snapshot parser 归一化
- * ```
- *
- * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 完整 snapshot 的 trim、legacy 归一化与 config 校验。
- * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) method 到 permission requirement 的权威映射。
- * @see [权限声明](/guide/permissions) Manifest 声明、平台批准与 Runtime 状态的完整流程。
- */
-export function isManagedMiniProgramRuntimePermissionKey(key: string): key is MiniProgramPermissionKey {
-  return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
-}
-export type MiniProgramRuntimePermissionStatus = 'enabled' | 'disabled';
-export interface MiniProgramRuntimePermissionEntry {
-  key: MiniProgramPermissionKey;
-  status: MiniProgramRuntimePermissionStatus;
-  config: Record<string, unknown>;
-}
-export interface MiniProgramRuntimePermissionsSnapshot {
-  schema_version: 1;
-  revision?: number;
-  entries: MiniProgramRuntimePermissionEntry[];
-}
-/**
- * `parseMiniProgramRuntimePermissions()` 返回的独立 canonical 视图。
- *
- * @remarks
- * 结果不保留输入 snapshot、entries 或 config 的对象引用，也不包含 `schema_version`、`revision`
- * 和未知权限。该对象不是授权决定；Runtime 还必须按 capability requirement、entry status、Host
- * 能力和后续 policy 判断是否允许调用。
- */
-export interface ParsedMiniProgramRuntimePermissions {
-  /**
-   * 整个 schema v1 snapshot 是否通过结构、重复 key 与已知 config 校验。`true` 不表示存在任何
-   * permission、任何 entry 为 `enabled`，也不表示 capability 已获授权。
-   */
-  valid: boolean;
-  /**
-   * 仅包含当前协议认识的 canonical key。缺失 key 表示 snapshot 未声明该权限；`disabled` entry
-   * 仍会保留。`valid: false` 时该映射必为空，解析器不会暴露部分成功结果。
-   */
-  permissions: Partial<Record<MiniProgramPermissionKey, MiniProgramRuntimePermissionEntry>>;
-}
-
-/**
- * 将不可信的 schema v1 runtime permission snapshot 解析为独立的 canonical 权限映射。
- *
- * @param snapshot - Host、服务端、dev context 或持久化边界提供的普通反序列化数据；调用方不需要先做
- * 类型断言。Proxy trap 或 getter 自身抛出的异常会原样传播。
- * @returns {@link ParsedMiniProgramRuntimePermissions}。完整 snapshot 合法时返回
- * `{ valid: true, permissions }`；顶层、entry、状态、重复 key 或已知 config 任一校验失败时统一
- * 返回 `{ valid: false, permissions: {} }`，不会保留部分权限。
- *
- * @remarks
- * 顶层必须是对象，`schema_version` 必须严格等于数字 `1`，`entries` 必须是数组。`revision`
- * 可省略；存在时必须是大于或等于 `0` 的整数。revision 只参与输入校验，不会复制到返回值。
- * 顶层与 entry 的其他字段会被忽略，以便 schema v1 内前向扩展。
- *
- * 每个 entry 必须是对象，`key` 必须是 trim 后非空的字符串，`status` 必须严格为
- * `'enabled'` 或 `'disabled'`。解析器先 trim key，再把唯一的历史别名 `network.request`
- * 归一为 canonical `network`；大小写不会转换。重复检查基于归一化后的所有 key，因此
- * `network` 与 ` network.request ` 冲突，两个相同未知 future key 也会让整个 snapshot fail
- * closed。
- *
- * 是否属于当前受管 key 由 {@link isManagedMiniProgramRuntimePermissionKey} 与权限目录决定。
- * 为兼容较新服务端，非空、状态合法且不重复的未知 key 会被忽略；其 `config` 可以缺失、为
- * `null`、数组或任意未来结构，均不会使已认识的权限失效。未知 entry 不会出现在返回映射中。
- *
- * 已知权限严格执行当前 schema：`network` 必须提供对象 config，且
- * `useOfficialDomain` 必须是 boolean；其他额外 network config 字段会丢弃，返回值只复制该
- * boolean。其余当前权限是无配置项权限，输入 config 可以缺失、为 `null` 或 `{}`，并统一输出
- * `{}`；非空对象、数组或其他值会使整个 snapshot 无效。Runtime snapshot 必须显式包含
- * network 的有效 boolean，即使 Manifest 目录把省略 `useOfficialDomain` 的开发者默认值定义为
- * `false`。
- *
- * 返回的 canonical entry/config 都是新对象；修改原 snapshot、entry 或嵌套 network config
- * 不会改变解析结果。`permissions` 是 Partial map：合法空 entries、只包含未知权限，或没有某个
- * canonical key 时，解析仍可 `valid: true`，对应属性保持缺失。
- *
- * `valid: true` 只表示 snapshot 可安全消费，不代表 entry 已启用，更不代表某个 capability 已获
- * 授权。Runtime consumer 应先查 {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES} 中目标 method 的
- * `requirement`：`kind: 'none'` 不读取权限；`kind: 'all'` 要求列出的每个 canonical entry 都存在
- * 且 `status === 'enabled'`。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
- * policy。当前 Runtime 对 `valid: false` 按空权限表 fail closed，受保护 method 会得到
- * `PERMISSION_NOT_DECLARED`，而不是沿用输入中的部分 enabled entry。
- *
- * @example
- * ```ts
- * import { parseMiniProgramRuntimePermissions } from '@heybox/hb-sdk/protocol';
- *
- * const parsed = parseMiniProgramRuntimePermissions({
- *   schema_version: 1,
- *   revision: 4,
- *   entries: [
- *     {
- *       key: ' network.request ',
- *       status: 'enabled',
- *       config: { useOfficialDomain: false, futureField: 'discarded' },
- *     },
- *     { key: 'future.permission', status: 'disabled', config: null },
- *   ],
- * });
- *
- * // legacy key 已归一化；未知 future key 被忽略。
- * if (parsed.valid && parsed.permissions.network?.status === 'enabled') {
- *   console.log(parsed.permissions.network.config.useOfficialDomain); // false
- *   // 继续执行 capability requirement、Host 与业务 policy 校验。
- * }
- * ```
- *
- * @see {@link ParsedMiniProgramRuntimePermissions}
- * @see {@link MiniProgramRuntimePermissionsSnapshot}
- * @see {@link isManagedMiniProgramRuntimePermissionKey}
- * @see {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES}
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
- */
-export function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMiniProgramRuntimePermissions {
-  if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
-    return { valid: false, permissions: {} };
-  }
-  if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
-    return { valid: false, permissions: {} };
-  }
-
-  const seenKeys = new Set<string>();
-  const permissions: Partial<Record<MiniProgramPermissionKey, MiniProgramRuntimePermissionEntry>> = {};
-  for (const rawEntry of snapshot.entries) {
-    if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
-      return { valid: false, permissions: {} };
-    }
-    const inputKey = rawEntry.key.trim();
-    const key = inputKey === 'network.request' ? 'network' : inputKey;
-    if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled')) {
-      return { valid: false, permissions: {} };
-    }
-    seenKeys.add(key);
-    if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-      // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
-      // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
-      continue;
-    }
-    if (key === 'network') {
-      const config = rawEntry.config;
-      if (!isRecord(config) || typeof config.useOfficialDomain !== 'boolean') {
-        return { valid: false, permissions: {} };
-      }
-      permissions[key] = {
-        key,
-        status: rawEntry.status,
-        config: { useOfficialDomain: config.useOfficialDomain },
-      };
-      continue;
-    }
-    if (rawEntry.config !== null && rawEntry.config !== undefined && (!isRecord(rawEntry.config) || Object.keys(rawEntry.config).length > 0)) {
-      return { valid: false, permissions: {} };
-    }
-    permissions[key] = {
-      key,
-      status: rawEntry.status,
-      config: {},
-    };
-  }
-  return { valid: true, permissions };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}

package/types/bridge.d.ts

@@ -1,163 +0,0 @@
-import { COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { CompanionSessionExitPayload, CompanionSessionOutputPayload, CompanionSessionOwnershipLostPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
-import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
-export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
-/**
- * 小程序可订阅的生命周期、展示状态及业务事件名。
- *
- * @remarks
- * 每个事件的载荷见 {@link MiniProgramEventPayloadMap}。事件不会向晚订阅者重放；`ready`
- * 是握手成功通知，不是可查询的持久状态，也不保证只收到一次。具体事件能否产生取决于
- * Host 的能力与生命周期，不能仅凭事件名称推导状态去重或投递保证。
- */
-export type MiniProgramEventName = 'launch' | 'viewport_change' | 'display_change' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change' | typeof COMPANION_SESSION_OUTPUT_EVENT | typeof COMPANION_SESSION_EXIT_EVENT | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
-export interface MiniProgramBridgeError {
-    code: string;
-    message: string;
-    data?: unknown;
-}
-export interface SDKHandshakePayload {
-    href: string;
-    userAgent: string;
-    sdkVersion: string;
-}
-/** Runtime 对 SDK 握手的可选扩展响应。 */
-export interface SDKHandshakeResult {
-    /** Host 与 Runtime 归一化后的环境快照。 */
-    environment: MiniProgramRuntimeEnvironmentInfo;
-}
-export interface RuntimeLocationProbePayload {
-    probeId: string;
-    timestamp: number;
-}
-export type SDKLocationReportTrigger = 'probe' | 'history' | 'popstate' | 'hashchange' | 'pageshow' | 'resume';
-export interface SDKLocationReportPayload {
-    probeId?: string;
-    href: string;
-    sdkVersion: string;
-    trigger: SDKLocationReportTrigger;
-    timestamp: number;
-}
-export type SDKCSPBlockedResourceType = 'url' | 'inline' | 'eval' | 'unknown';
-export interface SDKCSPViolationPayload {
-    effectiveDirective: string;
-    violatedDirective: string;
-    disposition: string;
-    blockedResourceType: SDKCSPBlockedResourceType;
-    blockedOrigin?: string;
-    redactedPathname?: string;
-    sanitizedPathnameHash?: string;
-    sdkVersion: string;
-    timestamp: number;
-}
-/**
- * SDK 与 Host Runtime 跨 iframe 传输时共用的顶层 bridge envelope。
- *
- * @typeParam TPayload - 当前 method 对应的 payload 类型；未知或尚未按 method 收窄时默认为 `unknown`。
- *
- * @remarks
- * 该类型刻意保留为宽 envelope，以同时表达 handshake、request、response、event 与 cancel。
- * 字段组合的运行时约束由 {@link isMiniProgramBridgeMessage} 执行；v2 cancel 和 operation progress
- * 可分别使用 {@link MiniProgramBridgeCancelMessage} 与 {@link MiniProgramBridgeProgressMessage}
- * 获得更精确的静态类型。
- *
- * 类型匹配不建立信任边界。从 `postMessage` 接收数据时，先以 `unknown` 交给 guard，再独立校验
- * `MessageEvent.source`、预期 nonce、握手状态，以及具体 method 的 payload；当 origin 可以固定且
- * 当前协议模式要求时，再校验 `MessageEvent.origin`。
- */
-export interface MiniProgramBridgeMessage<TPayload = unknown> {
-    /** 固定协议 namespace，用于从其他页面消息中识别候选 envelope。 */
-    namespace: typeof MINI_PROGRAM_MESSAGE_NAMESPACE;
-    /** 当前消息采用的 wire 版本；新消息使用 v2，接收端为兼容握手接受 v1。 */
-    version: 1 | 2;
-    /** Runtime 创建 iframe 时分配并由双方逐条回传的实例 nonce。 */
-    nonce: string;
-    /** 决定 id、method、payload 与 error 组合规则的消息类别。 */
-    type: MiniProgramBridgeMessageType;
-    /** 请求关联 ID；普通生命周期 event 可省略，request、response、handshake、cancel 与 progress 必须提供。 */
-    id?: string;
-    /** capability 或事件名；response 可省略，cancel 禁止携带。 */
-    method?: string;
-    /** method 对应的 wire payload；必须在按 method 分发后继续校验。 */
-    payload?: TPayload;
-    /** 失败 response 的结构化错误；其他消息类型不得携带。 */
-    error?: MiniProgramBridgeError;
-}
-export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage<never> {
-    version: 2;
-    type: 'cancel';
-    id: string;
-    method?: never;
-    payload?: never;
-    error?: never;
-}
-export interface MiniProgramBridgeProgressMessage<TMethod extends MiniProgramProgressMethod = MiniProgramProgressMethod> extends MiniProgramBridgeMessage<MiniProgramCapabilityProgress<TMethod>> {
-    version: 2;
-    type: 'event';
-    id: string;
-    method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
-    payload: MiniProgramCapabilityProgress<TMethod>;
-    error?: never;
-}
-/**
- * 公开事件名与对应载荷的映射，供 SDK 的类型化事件监听使用。
- *
- * @remarks
- * 生命周期 `timestamp` 是 Runtime 发出通知时的 Unix 毫秒时间，不是 iframe 收到事件的
- * 时间或单调时钟。事件只通知已注册的监听器；业务需要当前状态时应使用相应读取 API。
- */
-export interface MiniProgramEventPayloadMap {
-    /** 展示状态实际变化后通知；不回放初始状态，不支持或失败时不通知。 */
-    display_change: import('./payloads').MiniProgramDisplayState & {
-        /** api 为开发者调用；user 为用户点击宿主退出全屏按钮。同目标合并时保留首次发起来源。旧宿主可能不提供。 */
-        source?: 'api' | 'user';
-    };
-    /** 窗口信息变化通知；载荷与 `viewport.getWindowInfo()` 的结果结构一致。 */
-    viewport_change: import('./payloads').MiniProgramWindowInfoResult;
-    /** 初次握手时的启动通知；晚订阅不能补收。 */
-    launch: {
-        /** Runtime 发出通知时的 Unix 毫秒时间。 */
-        timestamp: number;
-        /** Host 加载 iframe 时的启动 URL；可缺失，不代表页面当前导航地址。 */
-        url?: string;
-    };
-    /** 握手成功通知；重复握手可再次产生，应查询持久握手状态驱动 UI。 */
-    ready: {
-        /** Runtime 发出通知时的 Unix 毫秒时间。 */
-        timestamp: number;
-    };
-    /** Host 通知小程序进入展示状态。 */
-    show: {
-        /** Runtime 发出通知时的 Unix 毫秒时间。 */
-        timestamp: number;
-        /** Host 可选提供的来源描述；不保证存在或采用固定枚举。 */
-        source?: string;
-    };
-    /** Host 通知小程序进入隐藏状态。 */
-    hide: {
-        /** Runtime 发出通知时的 Unix 毫秒时间。 */
-        timestamp: number;
-        /** Host 可选提供的来源描述；不保证存在或采用固定枚举。 */
-        source?: string;
-    };
-    /** Runtime 卸载的尽力通知；不能保证页面销毁前一定收到。 */
-    unload: {
-        /** Runtime 发出通知时的 Unix 毫秒时间。 */
-        timestamp: number;
-    };
-    /** 结构化 Runtime 错误通知；载荷不是 JavaScript `Error` 实例。 */
-    error: MiniProgramBridgeError;
-    /** Host 当前登录状态通知；相同状态可能重复出现，不能仅凭事件判断账号身份是否变化。 */
-    heybox_app_login_change: {
-        /** Host 当前是否有已登录的小黑盒账号，不表示开发者服务端会话状态。 */
-        isHeyboxAppLoggedIn: boolean;
-    };
-    /** 当前用户授权状态通知；可包含可选 `steam_account`，不是 Manifest 权限状态。 */
-    user_info_authorization_change: UserInfoAuthorization;
-    /** 当前 Companion controller 收到的输出片段；去重与确认依据见载荷中的 sequence。 */
-    [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
-    /** Companion session 的进程退出通知。 */
-    [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
-    /** 当前 controller 失去 Companion session 控制权的通知。 */
-    [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
-}