@heybox/hb-sdk 0.9.1-alpha.4 → 0.9.1-alpha.6

package/types/core/client.d.ts

@@ -1,108 +0,0 @@
-import { type MiniProgramSDKHandshakeState, type MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-import { type MiniProgramEnvironmentInfo, type MiniProgramEnvironmentReader } from '../modules/environment';
-import type { MiniProgramBridgeMethod, MiniProgramCapabilityPayload, MiniProgramCapabilityResult } from '../protocol/capabilities';
-import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-/**
- * 创建 SDK bridge client 的配置项。
- *
- * @remarks
- * 该配置主要用于独立实例、自定义宿主环境注入和测试场景。
- */
-export interface MiniProgramSDKOptions {
-    /** 请求与握手超时时间，单位毫秒。 */
-    timeout?: number;
-    /** 父容器注入的 bridge nonce；默认从 URL query 读取。 */
-    nonce?: string;
-    /** 当前 iframe 内的 window，测试环境可注入。 */
-    selfWindow?: Window;
-    /** 父窗口，测试环境可注入；显式传 null 可模拟非 iframe 环境。 */
-    targetWindow?: Window | null;
-    /** 精准 postMessage 目标 origin；未传时尝试推断，失败则回退为 `*`。 */
-    targetOrigin?: string;
-}
-type MiniProgramRequesterArgs<Method extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayload<Method> extends void ? [payload?: MiniProgramCapabilityPayload<Method>] : undefined extends MiniProgramCapabilityPayload<Method> ? [payload?: MiniProgramCapabilityPayload<Method>] : [payload: MiniProgramCapabilityPayload<Method>];
-/** 模块 API 发起请求所需的最小能力。 */
-export interface MiniProgramRequester {
-    /** 向父容器调用指定开放能力。 */
-    request<Method extends MiniProgramBridgeMethod>(method: Method, ...args: MiniProgramRequesterArgs<Method>): Promise<MiniProgramCapabilityResult<Method>>;
-}
-/** 长操作使用的本地 observer 与取消配置，不进入 bridge payload。 */
-export interface MiniProgramOperationOptions<TProgress = unknown> {
-    signal?: AbortSignal;
-    onProgress?: (progress: TProgress) => void;
-    createAbortError?: () => unknown;
-    /** Long Host operations can survive observer teardown. */
-    cancelOnAbort?: boolean;
-}
-/** 支持 request-scoped progress/cancel 的 bridge requester。 */
-export interface MiniProgramOperationRequester extends MiniProgramRequester {
-    requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
-}
-/** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
-export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester, MiniProgramEnvironmentReader {
-    private readonly timeout;
-    private readonly selfWindow?;
-    private readonly targetWindow;
-    private readonly targetOrigin;
-    private readonly nonce;
-    private readonly pendingRequests;
-    private readonly eventBus;
-    private readonly handleMessage;
-    private readonly handlePopState;
-    private readonly handleHashChange;
-    private readonly handlePageShow;
-    private readonly handleSecurityPolicyViolation;
-    private unsubscribeHistoryChanges?;
-    private started;
-    private readonly handshakeState;
-    private handshakeSettled;
-    private handshakePromise;
-    private resolveHandshake;
-    private rejectHandshake;
-    private handshakeTimer?;
-    private handshakeRetryTimer?;
-    private destroyed;
-    private runtimeUnavailable;
-    private runtimeUnavailableError?;
-    private environmentInfo?;
-    constructor(options?: MiniProgramSDKOptions);
-    /** 等待父容器握手完成。 */
-    waitForHandshake(): Promise<void>;
-    /** 获取当前握手状态。 */
-    getHandshakeState(): MiniProgramSDKHandshakeState;
-    /** 订阅握手状态，并立即接收当前状态。 */
-    onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
-    /** 等待握手后读取当前实例的环境快照。 */
-    getEnvironmentInfo(): Promise<MiniProgramEnvironmentInfo>;
-    /** 同步读取握手期间缓存的环境快照。 */
-    getEnvironmentInfoSync(): MiniProgramEnvironmentInfo;
-    /** 注册小程序事件监听。 */
-    on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-    /** 移除小程序事件监听。 */
-    off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-    /** 调用父容器开放能力。 */
-    request<Method extends MiniProgramBridgeMethod>(method: Method, ...args: MiniProgramRequesterArgs<Method>): Promise<MiniProgramCapabilityResult<Method>>;
-    /** 发起不使用固定总时长 timer 的长操作。 */
-    requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
-    private performRequest;
-    /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
-    destroy(): void;
-    private ensureStarted;
-    private postHandshake;
-    private onMessage;
-    private postLocationReport;
-    private postCSPViolation;
-    private handleEvent;
-    private handleResponse;
-    private handleOperationProgress;
-    private sendCancel;
-    private cleanupPending;
-    private postMessage;
-    private resolveHandshakeOnce;
-    private failHandshake;
-    private clearHandshakeTimers;
-    private markRuntimeUnavailable;
-    private getRuntimeUnavailableError;
-    private rejectAllPending;
-}
-export {};

package/types/core/csp-violation.d.ts

@@ -1,5 +0,0 @@
-import type { SDKCSPViolationPayload } from '../protocol/types';
-type CSPViolationLike = Pick<SecurityPolicyViolationEvent, 'blockedURI' | 'disposition' | 'effectiveDirective' | 'violatedDirective'>;
-/** 将浏览器 CSP 事件转换为不包含原始 URL 敏感部分的 bridge 载荷。 */
-export declare function createCSPViolationPayload(event: CSPViolationLike, baseHref: string, sdkVersion: string, cryptoImplementation: Crypto): Promise<SDKCSPViolationPayload>;
-export {};

package/types/core/errors.d.ts

@@ -1,78 +0,0 @@
-import type { MiniProgramBridgeError } from '../protocol/types';
-import type { MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse } from '../modules/network';
-/**
- * SDK 对外抛出的标准 bridge / runtime 错误类型。
- *
- * @remarks
- * 该错误用于表示握手失败、bridge 调用失败、父容器运行时错误等
- * 非 HTTP 结果错误。其 `code` 字段可用于业务分支处理，
- * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
- * `message` 只用于日志和开发者提示，不应作为机器判断条件。
- *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
- * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
- *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
- * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
- * 不要把所有错误都当作可重试错误，也不要把 `data` 当成稳定的序列化协议。
- *
-   * @example
-   * ```ts
-   * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
-   *
-   * try {
-   *   await hbSDK.auth.login({ scopes: ['profile'] })
- * } catch (error) {
- *   if (error instanceof HbMiniProgramSDKError && error.code === 'USER_GESTURE_REQUIRED') {
- *     showRetryButton()
- *     return
- *   }
- *   throw error
- * }
- * ```
- */
-export declare class HbMiniProgramSDKError extends Error {
-    /** 稳定错误码；业务分支应比较该字段，不要比较 `message`。 */
-    code: string;
-    /** 可选调试数据；结构由具体错误码决定，可能随 Host 版本变化。 */
-    data?: unknown;
-    constructor(error: MiniProgramBridgeError);
-}
-/**
- * 创建 SDK 标准错误。
- *
- * @param code - 稳定错误码。
- * @param message - 面向开发者的错误说明。
- * @param data - 可选调试数据。
- * @returns 标准化 `HbMiniProgramSDKError` 实例。
- *
- * @remarks
- * 仅供 SDK 内部或同仓运行时层统一构造 bridge / runtime 错误。
- */
-export declare function createSDKError(code: string, message: string, data?: unknown): HbMiniProgramSDKError;
-/**
- * SDK 对外抛出的 HTTP 错误类型。
- *
- * @remarks
- * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
- * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。网络请求没有收到
- * 可判定的 HTTP 响应时，SDK 会抛出 `HbMiniProgramSDKError` 或原始 transport 错误，
- * 不应把本类当作网络不可达的统一错误类型。
- *
- * @typeParam T - 标准化响应数据的类型。
- */
-export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
-    /** HTTP 状态码；由 `validateStatus` 判定为失败的响应状态。 */
-    status: number;
-    /** 标准化响应数据；类型由 `network.request<T>()` 的泛型参数决定。 */
-    data: T;
-    /** 标准化响应头；敏感响应头会在进入错误对象前被脱敏或移除。 */
-    headers: Record<string, string>;
-    /** SDK 公共请求配置快照；可能含原始 URL、请求头或请求数据，记录日志前必须自行脱敏。 */
-    config: MiniProgramNetworkRequestConfig;
-    /** 完整标准化响应，包含状态、头、数据和请求配置。 */
-    response: MiniProgramNetworkResponse<T>;
-    /**
-     * @param response - 已完成请求的标准化网络响应。
-     */
-    constructor(response: MiniProgramNetworkResponse<T>);
-}

package/types/core/event-bus.d.ts

@@ -1,11 +0,0 @@
-import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-/** SDK 内部事件总线，负责管理沙盒生命周期与业务事件监听。 */
-export declare class MiniProgramEventBus {
-    private readonly eventHandlers;
-    /** 注册事件监听，并返回取消监听函数。 */
-    on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-    /** 移除事件监听。 */
-    off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-    /** 派发事件。 */
-    emit(eventName: MiniProgramEventName, payload: unknown): void;
-}

package/types/core/handshake-state.d.ts

@@ -1,54 +0,0 @@
-import type { HbMiniProgramSDKError } from './errors';
-/**
- * SDK 与 Host 握手的持久状态。
- *
- * @remarks
- * 状态是按 `status` 判别的只读联合类型：
- *
- * - `connecting`：默认 SDK 已开始初始握手但尚未落定；
- * - `ready`：初始握手已成功；
- * - `failed`：初始握手已失败，`error` 是导致失败的原始
- *   [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。
- *
- * 新实例只会从 `connecting` 迁移一次到 `ready` 或 `failed`，终态不会回退或互相转换；重复的
- * `ready` 事件也不会建立第二次状态迁移。每个状态 wrapper 都经过 `Object.freeze()`，调用方不能
- * 替换 `status` 或 `failed.error`；冻结是浅层的，`error` 保留原始实例而不是克隆或冻结副本。
- *
- * `ready` 只记录初始握手已经成功，不是 Runtime 的持续存活探针；后续收到 `unload` 或销毁实例时
- * 仍不会回退。该持久状态适合驱动交互控件；生命周期 `ready` 事件只是一条不会向晚订阅者重放的
- * 边沿通知，不能替代当前状态。
- */
-export type MiniProgramSDKHandshakeState = {
-    readonly status: 'connecting';
-} | {
-    readonly status: 'ready';
-} | {
-    readonly status: 'failed';
-    readonly error: HbMiniProgramSDKError;
-};
-/**
- * SDK 握手状态变化处理函数。
- *
- * @param state - 当前冻结的
- * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState)：
- * `connecting` 表示尚未落定，`ready` 表示初始握手成功，`failed.error` 保留原始握手错误。
- *
- * @remarks
- * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 会在注册过程中同步调用
- * handler 一次；若当前为 `connecting`，状态落定时至多再同步调用一次。SDK 会隔离 handler 的同步
- * 异常，使其不阻断状态落定或其他订阅者；返回值会被忽略且 Promise 不会被等待，因此异步 handler
- * 必须自行处理 rejected Promise。
- */
-export type MiniProgramSDKHandshakeStateHandler = (state: MiniProgramSDKHandshakeState) => void;
-/** 保存握手终态，并向订阅者同步派发唯一一次状态迁移。 */
-export declare class MiniProgramSDKHandshakeStateStore {
-    private state;
-    private readonly handlers;
-    getState(): MiniProgramSDKHandshakeState;
-    subscribe(handler: MiniProgramSDKHandshakeStateHandler): () => void;
-    clear(): void;
-    settle(state: Extract<MiniProgramSDKHandshakeState, {
-        status: 'ready' | 'failed';
-    }>): void;
-    private notify;
-}

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;