@heybox/hb-sdk 0.9.1-alpha.1 → 0.9.1-alpha.10

package/types/core/history-observer.d.ts

@@ -1,4 +0,0 @@
-type HistoryChangeListener = () => void;
-/** 共享同一个 History patch，并在最后一个订阅者退出时精确恢复原属性。 */
-export declare function subscribeHistoryChanges(history: History, listener: HistoryChangeListener): () => void;
-export {};

package/types/core/mini-dev-console.d.ts

@@ -1,36 +0,0 @@
-/**
- * iframe 与调试台页面的开发期 console 捕获转发。
- *
- * 双条件门控（iframe 转发）：
- * 1. 构建期：`hb-sdk dev`（vite serve）注入 `__HB_SDK_DEV_LOGGING__`；`hb-sdk build` /
- *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
- * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
- *    用户设备上的正式运行环境没有该标记。
- *
- * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
- * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
- * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
- *
- * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
- * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
- * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
- * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
- */
-export declare const MINI_DEV_IFRAME_WINDOW_NAME = "__hb_sdk_mini_dev__";
-export declare const MINI_DEV_CONSOLE_EVENT_TYPE = "hb-sdk:mini-dev-console";
-/** 对外契约：调试台监听该 postMessage 读取转发日志；message 结构必须稳定。 */
-export interface MiniDevConsoleMessage {
-    type: typeof MINI_DEV_CONSOLE_EVENT_TYPE;
-    detail: MiniDevConsoleEventDetail;
-}
-export type MiniDevConsoleLevel = 'log' | 'debug' | 'info' | 'warn' | 'error';
-export interface MiniDevConsoleEventDetail {
-    level: MiniDevConsoleLevel;
-    args: unknown[];
-    timestamp: number;
-}
-/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
-export declare const MINI_DEV_CONSOLE_INSTALL_FLAG = "__hb_sdk_mini_dev_console_installed__";
-/** 调试台页面（非 iframe）自捕获：runtime/host 侧 console 直接进「日志」页签。 */
-export declare function installMiniDevConsoleSelfCapture(onLog: (level: MiniDevConsoleLevel, args: unknown[]) => void, consoleRef?: Console): void;
-export declare function installMiniDevConsoleForwarding(consoleRef?: Console): void;

package/types/core/network-sanitize.d.ts

@@ -1,31 +0,0 @@
-/**
- * network.request 诊断日志的纯脱敏工具。
- *
- * @remarks
- * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
- * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
- *（devtools 不得直接 import runtime capability modules）。
- */
-export type MiniProgramNetworkHeadersLike = Record<string, string>;
-/**
- * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
- */
-export declare function sanitizeNetworkRequestUrl(url: string): string;
-/**
- * 脱敏请求/响应头；敏感名（含 heybox 前缀）替换为 `[redacted]`。
- */
-export declare function sanitizeNetworkHeaders(headers?: MiniProgramNetworkHeadersLike): MiniProgramNetworkHeadersLike;
-/**
- * 预览请求/响应 data：递归脱敏敏感字段，截断长文本与大数组。
- */
-export declare function previewNetworkData(data: unknown): unknown;
-/**
- * 递归脱敏日志对象（payload / result）：敏感 key、headers、url 字段统一处理。
- */
-export declare function redactNetworkLogValue(value: unknown): unknown;
-/**
- * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
- */
-export declare function sanitizeDiagnosticMessage(message: string): string;
-export declare function isSensitiveNetworkHeaderName(headerName: string): boolean;
-export declare function isSensitiveNetworkKey(key: string): boolean;

package/types/core/sdk.d.ts

@@ -1,104 +0,0 @@
-import { type MiniProgramSDKOptions } from './client';
-import { type MiniProgramAuthModule } from '../modules/auth';
-import { type MiniProgramCloudModule } from '../modules/cloud';
-import { type MiniProgramCompanionModule } from '../modules/companion';
-import { type MiniProgramShareModule } from '../modules/share';
-import { type MiniProgramStorageModule } from '../modules/storage';
-import { type MiniProgramNetworkModule } from '../modules/network';
-import { type FilesModule } from '../modules/files';
-import { type MiniProgramViewportModule } from '../modules/viewport';
-import { type MiniProgramUserModule } from '../modules/user';
-import { type MiniProgramUiModule } from '../modules/ui';
-import { type MiniProgramDeviceModule } from '../modules/device';
-import { type MiniProgramEnvironmentModule } from '../modules/environment';
-import { type MiniProgramNavigationModule } from '../modules/navigation';
-import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-/**
- * 外部小程序 SDK 实例。
- *
- * @remarks
- * 该实例负责组织授权、用户、分享、容器、存储与网络等开放能力，并维护
- * iframe 内小程序与父容器之间的 bridge 生命周期。
- *
- * 多数业务页直接使用默认单例即可；只有在测试、多实例或需要定制运行参数时，
- * 才建议显式创建独立实例。
- *
- * 能力调用会自动等待与父容器完成握手。
- */
-export declare class MiniProgramSDK {
-    private readonly client;
-    /** 授权相关开放能力。 */
-    readonly auth: MiniProgramAuthModule;
-    /** 用户资料相关开放能力。 */
-    readonly user: MiniProgramUserModule;
-    /** 分享相关开放能力。 */
-    readonly share: MiniProgramShareModule;
-    /** 视口相关开放能力。 */
-    readonly viewport: MiniProgramViewportModule;
-    /** Storage 相关开放能力。 */
-    readonly storage: MiniProgramStorageModule;
-    /** 网络请求相关开放能力。 */
-    readonly network: MiniProgramNetworkModule;
-    /** 受控文件与目录能力。 */
-    readonly files: FilesModule;
-    /** UI 交互相关开放能力。 */
-    readonly ui: MiniProgramUiModule;
-    /** 设备相关开放能力。 */
-    readonly device: MiniProgramDeviceModule;
-    /** 导航与容器控制相关开放能力。 */
-    readonly navigation: MiniProgramNavigationModule;
-    /** 云端数据相关开放能力。 */
-    readonly cloud: MiniProgramCloudModule;
-    /** 受管桌面程序能力。 */
-    readonly companion: MiniProgramCompanionModule;
-    /** 当前实例的环境信息。 */
-    readonly environment: MiniProgramEnvironmentModule;
-    constructor(options?: MiniProgramSDKOptions);
-    /** 获取当前握手状态。 */
-    getHandshakeState(): MiniProgramSDKHandshakeState;
-    /** 订阅握手状态，并立即接收当前状态。 */
-    onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
-    /**
-     * 注册小程序生命周期或业务事件。
-     *
-     * @param eventName - 要监听的事件名。
-     * @param handler - 事件处理函数。
-     * @returns 事件解绑函数。
-     */
-    on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-    /**
-     * 移除小程序生命周期或业务事件。
-     *
-     * @param eventName - 要移除的事件名。
-     * @param handler - 对应的事件处理函数。
-     */
-    off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-    /**
-     * 销毁 SDK 实例。
-     *
-     * @remarks
-     * 销毁后会移除 message 监听，并拒绝尚未完成的 bridge 请求。
-     * 已销毁实例不应继续复用。
-     */
-    destroy(): void;
-}
-/**
- * 创建独立 SDK 实例。
- *
- * @param options - SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
- * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
- *
- * @remarks
- * 适用于测试、多实例场景，或需要自定义 `timeout`、`targetWindow` 等运行参数的场景。
- *
- * @example
- * ```ts
- * import { createMiniProgramSDK } from '@heybox/hb-sdk'
- *
- * const sdk = createMiniProgramSDK({
- *   timeout: 15000,
- * })
- * ```
- */
-export declare function createMiniProgramSDK(options?: MiniProgramSDKOptions): MiniProgramSDK;

package/types/core/singleton.d.ts

@@ -1,372 +0,0 @@
-import type { MiniProgramAuthModule } from '../modules/auth';
-import type { MiniProgramCloudModule } from '../modules/cloud';
-import type { MiniProgramCompanionModule } from '../modules/companion';
-import type { MiniProgramShareModule } from '../modules/share';
-import type { MiniProgramStorageModule } from '../modules/storage';
-import type { MiniProgramNetworkModule } from '../modules/network';
-import type { FilesModule } from '../modules/files';
-import type { MiniProgramViewportModule } from '../modules/viewport';
-import type { MiniProgramUserModule } from '../modules/user';
-import type { MiniProgramUiModule } from '../modules/ui';
-import type { MiniProgramDeviceModule } from '../modules/device';
-import type { MiniProgramEnvironmentModule } from '../modules/environment';
-import type { MiniProgramNavigationModule } from '../modules/navigation';
-import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-/**
- * 获取默认 SDK 实例的当前握手状态。
- *
- * @returns 当前冻结的
- * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState)：
- * `connecting` 表示初始握手尚未落定，`ready` 表示握手成功；`failed` 表示握手失败，并通过
- * `error` 保留原始
- * [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。状态不变期间重复调用
- * 返回同一个对象引用，落定时只会替换一次。
- *
- * @remarks
- * 该函数不接收参数并同步返回当前快照，不等待 Promise、不轮询、不发送 bridge 请求，也不会因为
- * 握手失败而抛出 `failed.error`。读取状态无需在 `package.json#heybox.permissions` 中声明权限，
- * 不要求可信用户手势。根包导入时已经自动启动握手；普通异步能力调用也会自行等待，不需要用本
- * API 手动实现等待器。
- *
- * 状态 wrapper 已浅冻结。状态机只允许 `connecting -> ready` 或 `connecting -> failed` 一次迁移，
- * 终态不会回退或互相转换；`failed.error` 是握手 Promise 使用的同一个原始错误实例，可根据稳定的
- * `code` 分支处理。常见初始失败包括 `NOT_IN_IFRAME`、`MISSING_NONCE`、`READY_TIMEOUT`、
- * `HANDSHAKE_FAILED`、`RUNTIME_UNAVAILABLE` 或握手完成前的 `SDK_DESTROYED`。
- *
- * 需要让界面跟随状态变化时，使用
- * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)：它会在订阅期间同步回放
- * 当前值，再通知至多一次终态迁移。不要轮询本函数。对于必须保留原始可信用户手势的按钮，可用
- * 该持久状态提前控制 `disabled`，但不要在点击回调里等待握手。
- *
- * [on('ready')](/reference/sdk/lifecycle/on) 是握手成功瞬间的事件：不会向晚订阅者重放，Host 重复
- * 派发时也可能再次触发事件 handler；持久状态则只迁移一次并始终可查询。`ready` 只表示初始握手
- * 已成功，后续 `unload` 不会把状态改回 `failed`，因此不能把它当作 Runtime 持续存活检查。
- *
- * SDK 会在发布 `ready` 状态前缓存环境快照，所以 `status === 'ready'` 时可以立即调用
- * [environment.getInfoSync()](/reference/sdk/environment/getInfoSync)。`failed` 时该同步环境 API 会抛出
- * 同一个 `state.error`；不要求同步读取时，优先使用会自动等待的
- * [environment.getInfo()](/reference/sdk/environment/getInfo)。
- *
- * @example
- * ```ts
- * import hbSDK from '@heybox/hb-sdk'
- *
- * const state = hbSDK.getHandshakeState()
- *
- * switch (state.status) {
- *   case 'connecting':
- *     submitButton.disabled = true
- *     break
- *   case 'ready': {
- *     submitButton.disabled = false
- *     const environment = hbSDK.environment.getInfoSync()
- *     console.log(environment.runtime.mode)
- *     break
- *   }
- *   case 'failed':
- *     submitButton.disabled = true
- *     console.error('SDK 握手失败', state.error.code)
- *     break
- * }
- * ```
- *
- * @see [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState) 三种状态及冻结语义。
- * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 同步回放当前状态并订阅终态迁移。
- * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的生命周期边沿事件。
- * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` 后同步读取环境快照。
- *
- * @since 0.7.0-alpha.9
- * @hbPlatform android
- * @hbPlatform ios
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function getHandshakeState(): MiniProgramSDKHandshakeState;
-/**
- * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
- *
- * @param handler - 接收
- * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState) 的处理函数。
- * 注册期间会在本函数返回前同步调用一次：`connecting` 表示初始握手仍在进行，`ready` 表示成功，
- * `failed.error` 是原始
- * [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。
- * @returns 从默认 SDK 状态 store 移除当前 handler 的 unsubscribe。调用一次或多次都返回 `void` 且
- * 不会抛错；取消后不再接收未来迁移，但不会撤销已经同步回放的当前状态。
- *
- * @remarks
- * 订阅是纯本地同步操作，不发送 bridge 请求、不等待握手，也无需在
- * `package.json#heybox.permissions` 中声明权限或保留可信用户手势。根包导入时握手已经自动启动；
- * 本 API 用于观察状态，不用于主动发起或重试握手。
- *
- * handler 会在加入订阅集合后、unsubscribe 返回前立即同步收到当前冻结状态：
- *
- * - 当前为 `connecting`：先立即收到 `connecting`，随后至多再收到一次 `ready` 或 `failed`；
- * - 当前已是 `ready` 或 `failed`：立即收到该终态，之后不会再迁移；
- * - 在终态通知过程中新增订阅：通过即时回放收到一次终态，不会因同一迁移重复调用。
- *
- * 状态只允许 `connecting -> ready` 或 `connecting -> failed`，终态不回退。`failed.error` 是握手失败
- * 和同步环境读取使用的同一个原始错误实例，可按稳定的 `code` 分支处理。`ready` 只表示初始握手
- * 已成功；后续 `unload` 不会把状态改回 `failed`，因此它不是 Runtime 持续存活探针。
- *
- * SDK 会逐个捕获 handler 的同步异常：初次即时回放或终态通知中抛错，都不会从本函数传播、改变
- * 状态、阻断握手 Promise 或阻止其他订阅者收到通知。handler 返回值会被忽略，Promise 也不会被
- * 等待；异步 handler 应在自身内部捕获 rejected Promise，避免未处理拒绝。
- *
- * 每个 handler 以 Set 语义保存；同一函数引用重复订阅只有一个未来通知注册，但每次调用本函数仍会
- * 同步回放当前状态，任一 unsubscribe 都会移除该注册。应在页面、组件或业务模块销毁时调用
- * unsubscribe。SDK 内部销毁会清空全部状态订阅；若销毁发生在握手落定前，会先发布携带
- * `SDK_DESTROYED` 的 `failed`，再清空订阅。此后重复调用已经返回的 unsubscribe 仍是安全空操作。
- * `unload` 发生在握手前时则以 `RUNTIME_UNAVAILABLE` 落为 `failed`；发生在 `ready` 后不会产生
- * 第二次状态通知。
- *
- * 与 [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 相比，本 API 适合让 UI 自动跟随
- * 唯一一次迁移，且即时回放意味着通常不需要先额外读取一次状态。
- * [on('ready')](/reference/sdk/lifecycle/on) 则是不可重放、可能因 Host 重复事件再次触发的边沿通知，
- * 不应用于驱动晚挂载按钮的可用状态。
- *
- * SDK 会在发布 `ready` 状态前缓存环境快照，因此可以在 `ready` handler 中立即调用
- * [environment.getInfoSync()](/reference/sdk/environment/getInfoSync)。在 `failed` handler 中调用该
- * API 会抛出同一个 `state.error`；一般异步读取可使用
- * [environment.getInfo()](/reference/sdk/environment/getInfo) 自动等待。
- *
- * @example
- * ```ts
- * import hbSDK from '@heybox/hb-sdk'
- *
- * const stop = hbSDK.onHandshakeStateChange(state => {
- *   switch (state.status) {
- *     case 'connecting':
- *       submitButton.disabled = true
- *       statusText.textContent = '正在连接'
- *       break
- *     case 'ready':
- *       submitButton.disabled = false
- *       statusText.textContent = hbSDK.environment.getInfoSync().runtime.mode
- *       break
- *     case 'failed':
- *       submitButton.disabled = true
- *       statusText.textContent = `连接失败：${state.error.code}`
- *       break
- *   }
- * })
- *
- * // 页面或组件真正销毁时执行；重复取消也安全。
- * window.addEventListener('unload', () => {
- *   stop()
- *   stop()
- * }, { once: true })
- * ```
- *
- * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 一次性同步读取当前持久状态。
- * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的握手成功边沿事件。
- * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` handler 中同步读取环境。
- * @see [事件与生命周期](/guide/lifecycle) 握手与普通生命周期事件的使用建议。
- *
- * @since 0.7.0-alpha.9
- * @hbPlatform android
- * @hbPlatform ios
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
-/**
- * 注册默认 SDK 实例的事件监听。
- *
- * @param eventName - 要监听的
- * [MiniProgramEventName](/reference/symbols/root/types/MiniProgramEventName)。泛型 `T` 通常由该字符串
- * 字面量推断，并决定 handler 的 payload 类型。
- * @param handler - 与 `eventName` 对应的
- * [MiniProgramEventHandler](/reference/symbols/root/types/MiniProgramEventHandler)。payload 由
- * [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 精确映射。
- * @returns 只解绑当前 `eventName` / handler 组合的函数。调用一次或多次都返回 `void` 且不会抛错，
- * 不影响同一事件上的其他 handler。
- *
- * @remarks
- * 事件名决定 payload 字段：
- *
- * - `launch`：`{ timestamp, url? }`；`ready`：`{ timestamp }`；
- * - `show` / `hide`：`{ timestamp, source? }`；`unload`：`{ timestamp }`；
- * - `error`：
- *   [MiniProgramBridgeError](/reference/symbols/protocol/interfaces/MiniProgramBridgeError)，包含 `code`、
- *   `message` 与可选 `data`，不是 JavaScript `Error` 实例；
- * - `heybox_app_login_change`：`{ isHeyboxAppLoggedIn }`；
- * - `user_info_authorization_change`：
- *   [UserInfoAuthorization](/reference/symbols/root/interfaces/UserInfoAuthorization)，包含 `identity` 与
- *   `profile` 两项授权状态，支持 Steam 账号能力时还可能包含 `steam_account`；
- * - `companion.session.output`：`{ sessionId, controllerGeneration, stream, sequence, data }`；
- * - `companion.session.exit`：`{ sessionId, exit }`；
- * - `companion.session.ownershipLost`：`{ sessionId, controllerGeneration }`。
- *
- * `on()` 同步把 handler 加入默认 SDK 实例的本地 event bus，不等待握手、不发送 bridge 请求。
- * 注册本身无需在 `package.json#heybox.permissions` 中声明权限，不要求可信用户手势，也不会因当前
- * 握手处于 `connecting`、`ready` 或 `failed` 而抛出 SDK 错误。具体事件是否会产生，仍取决于 Host、
- * Runtime 生命周期和相关业务能力。
- *
- * event bus 使用 Set 保存每个事件的 handler。同一事件与同一函数引用重复注册只有一个有效监听；
- * 任一返回的 unsubscribe 或 [off()](/reference/sdk/lifecycle/off) 都会移除该唯一注册。不同函数引用
- * 不会去重，同一函数注册到不同事件也彼此独立。应保存 unsubscribe，并在页面、组件或业务模块销毁
- * 时调用；unsubscribe 可安全重复调用。
- *
- * handler 在事件派发时同步执行。SDK 不捕获普通事件 handler 的同步异常，也不等待其 Promise；某个
- * handler 抛错可能阻断同次派发中的后续 handler，异步拒绝也可能成为未处理 Promise。需要隔离时在
- * handler 内自行 `try/catch`，并显式处理异步任务的 rejected Promise。
- *
- * 所有生命周期与业务事件都不会重放：只派发给事件到达时已经注册的 handler，晚注册无法取回
- * `launch`、`ready` 或其他历史事件。`ready` 只是握手成功瞬间的边沿通知，Host 重复派发时 handler
- * 也可能再次执行；需要可查询、会向订阅者立即回放且只迁移一次的握手状态时，使用
- * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 和
- * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)。
- *
- * 收到 `unload` 后当前 Runtime 上下文不可恢复，在途请求会失败，也不应再依赖后续 bridge 事件；
- * SDK 内部销毁会移除底层 message listener。调用 unsubscribe 只清理该本地事件 handler，不取消
- * API 请求、业务任务、Companion 进程或握手状态订阅。
- *
- * @example
- * ```ts
- * import hbSDK from '@heybox/hb-sdk'
- *
- * const stopShow = hbSDK.on('show', ({ timestamp, source }) => {
- *   try {
- *     refreshVisibleData({ timestamp, source })
- *   } catch (error) {
- *     reportHandlerError(error)
- *   }
- * })
- *
- * const stopError = hbSDK.on('error', ({ code, message }) => {
- *   console.error(code, message)
- * })
- *
- * // 页面或组件销毁时；重复调用也安全。
- * stopShow()
- * stopShow()
- * stopError()
- * ```
- *
- * @see [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 所有事件与 payload 字段。
- * @see [off()](/reference/sdk/lifecycle/off) 使用事件名与 handler 引用精确移除监听。
- * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 同步读取持久握手状态。
- * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
- * @see [事件与生命周期](/guide/lifecycle) 生命周期时机与清理建议。
- *
- * @since 0.2.0-alpha.0
- * @hbPlatform android
- * @hbPlatform ios
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-/**
- * 移除默认 SDK 实例的事件监听。
- *
- * @param eventName - 注册 handler 时使用的同一个事件名。只检查该事件自己的监听集合，不影响
- * 其他事件上的注册。
- * @param handler - 传给 `on(eventName, handler)` 的同一个函数对象。签名或函数体相同的新函数不是
- * 同一引用，不能移除原监听。
- * @returns `void`。移除成功、目标从未注册或此前已经移除时都不返回状态。
- *
- * @remarks
- * 该函数同步修改默认 SDK 实例的本地 event bus，不等待握手、不发送 bridge 请求，也不会调用
- * handler。它无需在 `package.json#heybox.permissions` 中声明权限，不要求可信用户手势；握手处于
- * `connecting`、`ready` 或 `failed`，以及已经收到 `unload` 时，取消操作本身都不会产生 SDK 错误。
- *
- * 匹配规则是 `eventName` 与 handler 函数引用同时相等。匹配后只移除这一项，同一事件上的其他
- * handler、同一 handler 在其他事件上的注册均保留。event bus 对同一事件与同一函数引用使用集合
- * 语义，重复 `on()` 只有一个有效注册，一次 `off()` 即会移除；重复调用 `off()` 是幂等的，未知事件
- * 或未注册 handler 会被静默忽略。
- *
- * 大多数场景优先保存并调用 [on()](/reference/sdk/lifecycle/on) 返回的 unsubscribe：它已经闭包绑定
- * 正确的事件名和 handler，同样可以重复调用。只有调用方需要在另一处按具名 handler 精确移除时，
- * 才直接使用 `off()`。匿名函数必须先保存引用；重新创建一个内容相同的箭头函数无法取消旧监听。
- *
- * 生命周期与业务事件不会重放，只派发给事件到达时仍处于注册状态的 handler。`off()` 只阻止后续
- * 事件，不能撤销已经执行的 handler，也不能取回注册前错过的 `launch`、`ready`、`show`、`hide`、
- * `unload` 等事件。当前握手状态应通过
- * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 或
- * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 获取，不要通过重新注册
- * `ready` 事件补状态。
- *
- * Runtime `unload` 或 SDK 内部销毁后不会再有可依赖的未来 bridge 生命周期事件，但调用 unsubscribe
- * 或 `off()` 做本地清理仍可安全重复执行。取消监听不会取消已经开始的 API 请求、业务任务或
- * `onHandshakeStateChange()` 订阅；后者必须调用其自己返回的取消函数。
- *
- * @example
- * ```ts
- * import hbSDK from '@heybox/hb-sdk'
- *
- * const pauseOnHide = () => pausePolling()
- * const reportHide = () => reportVisibility('hidden')
- *
- * hbSDK.on('hide', pauseOnHide)
- * const stopReporting = hbSDK.on('hide', reportHide)
- *
- * hbSDK.off('hide', pauseOnHide) // 只移除 pauseOnHide
- * hbSDK.off('hide', pauseOnHide) // 已移除，仍然安全
- * stopReporting()                // 推荐：使用 on() 返回的取消函数
- * ```
- *
- * @see [on()](/reference/sdk/lifecycle/on) 注册事件并取得绑定好的取消函数。
- * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 同步读取持久握手状态。
- * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
- * @see [事件与生命周期](/guide/lifecycle) 生命周期事件列表与清理建议。
- *
- * @since 0.2.0-alpha.0
- * @hbPlatform android
- * @hbPlatform ios
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-/** 默认 SDK 实例的授权模块。 */
-export declare const auth: MiniProgramAuthModule;
-/** 默认 SDK 实例的用户资料模块。 */
-export declare const user: MiniProgramUserModule;
-/** 默认 SDK 实例的分享模块。 */
-export declare const share: MiniProgramShareModule;
-/** 默认 SDK 实例的 Viewport 模块。 */
-export declare const viewport: MiniProgramViewportModule;
-/** 默认 SDK 实例的 storage 模块。 */
-export declare const storage: MiniProgramStorageModule;
-/** 默认 SDK 实例的 network 模块。 */
-export declare const network: MiniProgramNetworkModule;
-/** 默认 SDK 实例的 files 模块。 */
-export declare const files: FilesModule;
-/** 默认 SDK 实例的 UI 模块。 */
-export declare const ui: MiniProgramUiModule;
-/** 默认 SDK 实例的 device 模块。 */
-export declare const device: MiniProgramDeviceModule;
-/** 默认 SDK 实例的 navigation 模块。 */
-export declare const navigation: MiniProgramNavigationModule;
-/** 默认 SDK 实例的 cloud 模块。 */
-export declare const cloud: MiniProgramCloudModule;
-/** 默认 SDK 实例的受管桌面程序模块。 */
-export declare const companion: MiniProgramCompanionModule;
-/** 默认 SDK 实例的 environment 模块。 */
-export declare const environment: MiniProgramEnvironmentModule;
-/** 重置默认 SDK 实例，仅用于测试。 */
-export declare function resetDefaultSDKForTest(): void;

package/types/core/utils.d.ts

@@ -1,10 +0,0 @@
-/** 获取浏览器全局 window。 */
-export declare function getGlobalWindow(): Window | undefined;
-/** 获取父窗口；非 iframe 环境返回 null。 */
-export declare function getParentWindow(currentWindow?: Window): Window | null;
-/** 尝试读取父窗口 origin；跨域读取失败时回退到 document.referrer。 */
-export declare function readParentOrigin(currentWindow?: Window): string;
-/** 从父容器注入到 URL 的 query 中读取 bridge nonce。 */
-export declare function readBridgeNonce(currentWindow?: Window): string;
-/** 创建请求 ID。 */
-export declare function createMessageId(): string;

package/types/core/version.d.ts

@@ -1,2 +0,0 @@
-/** 构建时替换为当前发布包的实际版本。 */
-export declare const HB_SDK_VERSION: string;

package/types/devtools/device-logs.d.ts

@@ -1,48 +0,0 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-export declare const DEVICE_LOG_PATH = "/__hb_sdk__/device-logs";
-export declare function registerDeviceLogs(port: number, store: DeviceLogStore): () => void;
-export declare function getDeviceLogs(appUrl: string): any;
-export declare class DeviceLogStore {
-    private sandboxRequests;
-    listSandbox(id: string, path: string): Promise<unknown>;
-    readonly uploadToken: string;
-    readonly epoch: `${string}-${string}-${string}-${string}-${string}`;
-    private readonly expiresAt;
-    private cursor;
-    private logs;
-    private devices;
-    query(params: URLSearchParams): {
-        schemaVersion: number;
-        epoch: `${string}-${string}-${string}-${string}-${string}`;
-        items: {
-            cursor: number;
-            deviceSessionId: string;
-            sequence: number;
-            timestamp: number;
-            receivedAt: number;
-            level: string;
-            source: string;
-            message: string;
-            truncated: boolean;
-            method?: string;
-            callId?: string;
-            outcome?: string;
-            errorCode?: string;
-            durationMs?: number;
-        }[];
-        nextCursor: number;
-        hasMore: boolean;
-        gap: boolean;
-        devices: {
-            id: string;
-            name: string;
-            platform: string;
-            connectedAt: number;
-            lastSeen: number;
-            online: boolean;
-        }[];
-    };
-    upload(req: IncomingMessage, res: ServerResponse): Promise<void>;
-}
-/** 同源开发页面使用有界批量回传；传输失败不会递归写入 console。 */
-export declare function deviceLogBootstrap(token: string): string;

package/types/miniapp-manifest/basic-info-browser.d.ts

@@ -1,37 +0,0 @@
-/**
- * 在浏览器中校验构建产物的展示资料图片，并创建预览 URL。
- *
- * @param manifest - 构建产物 Manifest，必须包含合法的 `sdkVersion`。
- * @param files - 构建文件列表；`relativePath` 必须精确匹配 Manifest 中的图片路径。
- * @returns 名称、图标 `icon_url` 和按原顺序排列的 `cover_image_urls`；允许缺失资料的历史产物返回 `undefined`。
- * @throws `Error` 资料非法、图片缺失/为空/超过 10 MiB、格式与扩展名不符、超过 4000 万像素、
- * icon 不是 200×200，或仍使用脚手架占位图片时拒绝；浏览器解码和摘要计算失败也会拒绝。
- * @remarks
- * 需要浏览器提供 `crypto.subtle`、`createImageBitmap` 和 object URL API；不生成或回写 Manifest。
- * 失败时会释放本次已创建的 URL；成功后所有 URL 由调用方在预览结束或替换时释放。
- * @example
- * ```ts
- * import { previewMiniappBasicInfo } from '@heybox/hb-sdk/miniapp-publish';
- *
- * const preview = await previewMiniappBasicInfo(manifest, files);
- * if (preview) {
- *   try {
- *     const image = new Image();
- *     image.src = preview.icon_url;
- *     await image.decode();
- *     document.body.append(image);
- *   } finally {
- *     // 已加载的图像可继续显示；不再需要从这些 URL 加载时释放。
- *     [preview.icon_url, ...preview.cover_image_urls].forEach(URL.revokeObjectURL);
- *   }
- * }
- * ```
- */
-export declare function previewMiniappBasicInfo(manifest: Record<string, unknown>, files: readonly {
-    relativePath: string;
-    file: Blob;
-}[]): Promise<{
-    name: string;
-    icon_url: string;
-    cover_image_urls: string[];
-} | undefined>;

package/types/miniapp-manifest/basic-info-image-header.d.ts

@@ -1,6 +0,0 @@
-/** 在浏览器解码前读取尺寸上限；真实可解码性仍必须由图片解码器验证。 */
-export declare function readBasicInfoImageHeader(bytes: Uint8Array): {
-    format: string;
-    width: number;
-    height: number;
-};