@heybox/hb-sdk 0.1.2 → 0.2.0-alpha.0

package/dist/index.esm.js

@@ -1,4 +1,11 @@
-/** SDK 对外抛出的标准错误类型。 */
+/**
+ * SDK 对外抛出的标准 bridge / runtime 错误类型。
+ *
+ * @remarks
+ * 该错误用于表示握手失败、bridge 调用失败、父容器运行时错误等
+ * 非 HTTP 结果错误。其 `code` 字段可用于业务分支处理，
+ * `data` 仅作为可选调试信息，不保证结构稳定。
+ */
 class HbMiniProgramSDKError extends Error {
     /** 稳定错误码。 */
     code;
@@ -11,7 +18,17 @@ class HbMiniProgramSDKError extends Error {
         this.data = error.data;
     }
 }
-/** 创建 SDK 标准错误。 */
+/**
+ * 创建 SDK 标准错误。
+ *
+ * @param code 稳定错误码。
+ * @param message 面向开发者的错误说明。
+ * @param data 可选调试数据。
+ * @returns 标准化 `HbMiniProgramSDKError` 实例。
+ *
+ * @remarks
+ * 仅供 SDK 内部或同仓运行时层统一构造 bridge / runtime 错误。
+ */
 function createSDKError(code, message, data) {
     return new HbMiniProgramSDKError({
         code,
@@ -19,6 +36,39 @@ function createSDKError(code, message, data) {
         data,
     });
 }
+/**
+ * SDK 对外抛出的 HTTP 错误类型。
+ *
+ * @remarks
+ * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
+ * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
+ *
+ * @typeParam T 标准化响应数据的类型。
+ */
+class HbMiniProgramNetworkError extends Error {
+    /** HTTP 状态码。 */
+    status;
+    /** 标准化响应数据。 */
+    data;
+    /** 标准化响应头。 */
+    headers;
+    /** SDK 公共请求配置快照。 */
+    config;
+    /** 完整标准化响应。 */
+    response;
+    /**
+     * @param response 已完成请求的标准化网络响应。
+     */
+    constructor(response) {
+        super(`network.request failed with status ${response.status}`);
+        this.name = 'HbMiniProgramNetworkError';
+        this.status = response.status;
+        this.data = response.data;
+        this.headers = response.headers;
+        this.config = response.config;
+        this.response = response;
+    }
+}
 
 /** SDK 内部事件总线，负责管理沙盒生命周期与业务事件监听。 */
 class MiniProgramEventBus {
@@ -73,6 +123,31 @@ function getParentWindow(currentWindow) {
     }
     return currentWindow.parent;
 }
+/** 尝试读取父窗口 origin；跨域读取失败时回退到 document.referrer。 */
+function readParentOrigin(currentWindow) {
+    const parentWindow = getParentWindow(currentWindow);
+    if (parentWindow) {
+        try {
+            const origin = parentWindow.location?.origin;
+            if (origin && origin !== 'null') {
+                return origin;
+            }
+        }
+        catch {
+            // ignore cross-origin parent access and fall back to referrer
+        }
+    }
+    const referrer = currentWindow?.document?.referrer;
+    if (!referrer) {
+        return '';
+    }
+    try {
+        return new URL(referrer).origin;
+    }
+    catch {
+        return '';
+    }
+}
 /** 从父容器注入到 URL 的 query 中读取 bridge nonce。 */
 function readBridgeNonce(currentWindow) {
     const href = currentWindow?.location?.href;
@@ -95,7 +170,12 @@ function createMessageId() {
     return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
 }
 
-/** 判断未知数据是否符合小程序 bridge 消息信封。 */
+/**
+ * 判断未知数据是否符合小程序 bridge 消息信封。
+ *
+ * @param value 待判断的未知数据。
+ * @returns 当数据满足小程序 bridge 消息基础结构时返回 `true`。
+ */
 function isMiniProgramBridgeMessage(value) {
     if (!value || typeof value !== 'object') {
         return false;
@@ -108,11 +188,13 @@ function isMiniProgramBridgeMessage(value) {
 }
 
 const DEFAULT_TIMEOUT = 10000;
+const HANDSHAKE_RETRY_INTERVAL = 250;
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
 class MiniProgramBridgeClient {
     timeout;
     selfWindow;
     targetWindow;
+    targetOrigin;
     nonce;
     pendingRequests = new Map();
     eventBus = new MiniProgramEventBus();
@@ -123,11 +205,14 @@ class MiniProgramBridgeClient {
     resolveReady;
     rejectReady;
     readyTimer;
+    handshakeRetryTimer;
+    destroyed = false;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
         this.targetWindow =
             options.targetWindow === undefined ? getParentWindow(this.selfWindow) : options.targetWindow;
+        this.targetOrigin = options.targetOrigin || readParentOrigin(this.selfWindow) || '*';
         this.nonce = options.nonce || readBridgeNonce(this.selfWindow);
         this.handleMessage = this.onMessage.bind(this);
         this.readyPromise = new Promise((resolve, reject) => {
@@ -185,11 +270,17 @@ class MiniProgramBridgeClient {
     }
     /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
     destroy() {
+        this.destroyed = true;
         this.selfWindow?.removeEventListener('message', this.handleMessage);
-        this.clearReadyTimer();
-        this.rejectAllPending(createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁'));
+        const error = createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
+        this.failReady(error);
+        this.rejectAllPending(error);
     }
     ensureStarted() {
+        if (this.destroyed) {
+            this.failReady(createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁'));
+            return;
+        }
         if (this.started) {
             return;
         }
@@ -206,6 +297,22 @@ class MiniProgramBridgeClient {
         this.readyTimer = setTimeout(() => {
             this.failReady(createSDKError('READY_TIMEOUT', '小程序沙盒握手超时'));
         }, this.timeout);
+        try {
+            this.postHandshake();
+            this.handshakeRetryTimer = setInterval(() => {
+                this.postHandshake();
+            }, HANDSHAKE_RETRY_INTERVAL);
+        }
+        catch (error) {
+            this.failReady(error instanceof HbMiniProgramSDKError
+                ? error
+                : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
+        }
+    }
+    postHandshake() {
+        if (!this.selfWindow) {
+            throw createSDKError('NOT_IN_IFRAME', '当前页面不在小程序沙盒 iframe 中');
+        }
         this.postMessage({
             namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
             version: MINI_PROGRAM_MESSAGE_VERSION,
@@ -261,14 +368,14 @@ class MiniProgramBridgeClient {
         if (!this.targetWindow) {
             throw createSDKError('NOT_IN_IFRAME', '当前页面不在小程序沙盒 iframe 中');
         }
-        this.targetWindow.postMessage(message, '*');
+        this.targetWindow.postMessage(message, this.targetOrigin);
     }
     resolveReadyOnce() {
         if (this.readySettled) {
             return;
         }
         this.readySettled = true;
-        this.clearReadyTimer();
+        this.clearReadyTimers();
         this.resolveReady();
     }
     failReady(error) {
@@ -276,18 +383,21 @@ class MiniProgramBridgeClient {
             return;
         }
         this.readySettled = true;
-        this.clearReadyTimer();
+        this.clearReadyTimers();
         this.rejectReady(error);
     }
-    clearReadyTimer() {
-        if (!this.readyTimer) {
-            return;
+    clearReadyTimers() {
+        if (this.readyTimer) {
+            clearTimeout(this.readyTimer);
+            this.readyTimer = undefined;
+        }
+        if (this.handshakeRetryTimer) {
+            clearInterval(this.handshakeRetryTimer);
+            this.handshakeRetryTimer = undefined;
         }
-        clearTimeout(this.readyTimer);
-        this.readyTimer = undefined;
     }
     rejectAllPending(error) {
-        this.pendingRequests.forEach((pending) => {
+        this.pendingRequests.forEach(pending => {
             clearTimeout(pending.timer);
             pending.reject(error);
         });
@@ -295,21 +405,82 @@ class MiniProgramBridgeClient {
     }
 }
 
-/** 截图分享能力方法名。 */
+/**
+ * 登录授权能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const AUTH_LOGIN_METHOD = 'auth.login';
+/**
+ * 唤起登录授权，并在流程返回后刷新用户公开基础资料。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 登录流程完成后的最新用户登录态与公开资料。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主运行时调用失败时抛出。
+ *
+ * @remarks
+ * 该能力不会向小程序暴露 token、cookie 或其他登录凭据。
+ */
+function login(requester) {
+    return requester.request(AUTH_LOGIN_METHOD);
+}
+/**
+ * 创建授权模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的授权模块对象。
+ */
+function createAuthModule(requester) {
+    return {
+        login: () => login(requester),
+    };
+}
+
+/**
+ * 截图分享能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
-/** 截图并唤起分享。 */
+/**
+ * 截图并唤起分享。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 截图区域、延迟与保存相册等配置。
+ * @returns 由宿主客户端协议决定的结果。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
 function screenshot(requester, options) {
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
 }
 
-/** 展示分享面板能力方法名。 */
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
-/** 展示基础分享面板。 */
+/**
+ * 展示基础分享面板。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 基础分享参数。
+ * @returns 由宿主客户端协议决定的结果。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
 function showShareMenu(requester, options) {
     return requester.request(SHARE_SHOW_SHARE_MENU_METHOD, options);
 }
 
-/** 创建分享模块。 */
+/**
+ * 创建分享模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的分享模块对象。
+ */
 function createShareModule(requester) {
     return {
         showShareMenu: options => showShareMenu(requester, options),
@@ -317,102 +488,322 @@ function createShareModule(requester) {
     };
 }
 
-/** 用户信息能力方法名。 */
-const USER_GET_INFO_METHOD = 'user.getInfo';
 /**
- * 获取当前访问小程序用户的公开基础资料。
+ * 读取小程序隔离 storage 能力方法名。
  *
- * 该能力只返回 `heybox_id`、`nickname`、`avatar` 三个公开字段。
- * 未登录时不会触发登录流程，直接返回 `{ isLogin: false, userInfo: null }`。
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
  */
-function getInfo(requester) {
-    return requester.request(USER_GET_INFO_METHOD);
+const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
+/**
+ * 写入小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
+/**
+ * 获取小程序隔离 storage。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 读取的 storage key。
+ * @returns 对应 key 的标准化读取结果。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
+function getStorage(requester, options) {
+    return requester.request(STORAGE_GET_STORAGE_METHOD, options);
 }
-
-/** 用户登录能力方法名。 */
-const USER_LOGIN_METHOD = 'user.login';
 /**
- * 唤起黑盒登录流程，并在流程返回后刷新用户公开基础资料。
+ * 写入小程序隔离 storage。
  *
- * 该能力不会向小程序暴露 token、cookie 或任何登录凭据。
+ * @param requester 底层 bridge 请求能力。
+ * @param options 要写入的 storage key 与数据。
+ * @returns 当写入完成后 resolve。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
-function login(requester) {
-    return requester.request(USER_LOGIN_METHOD);
+function setStorage(requester, options) {
+    return requester.request(STORAGE_SET_STORAGE_METHOD, options);
+}
+/**
+ * 创建 storage 模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的 storage 模块对象。
+ */
+function createStorageModule(requester) {
+    return {
+        getStorage: options => getStorage(requester, options),
+        setStorage: options => setStorage(requester, options),
+    };
 }
 
-/** 创建用户模块。 */
-function createUserModule(requester) {
+/**
+ * 发起网络请求能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const NETWORK_REQUEST_METHOD = 'network.request';
+const DEFAULT_VALIDATE_STATUS = status => status >= 200 && status < 300;
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+function clonePublicValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => clonePublicValue(item));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clonePublicValue(item)]));
+    }
+    return value;
+}
+function snapshotRequestConfig(config) {
     return {
-        getInfo: () => getInfo(requester),
-        login: () => login(requester),
+        url: config.url,
+        ...(config.method === undefined ? {} : { method: config.method }),
+        ...(config.params === undefined ? {} : { params: clonePublicValue(config.params) }),
+        ...(config.data === undefined ? {} : { data: clonePublicValue(config.data) }),
+        ...(config.headers === undefined ? {} : { headers: clonePublicValue(config.headers) }),
+        ...(config.timeout === undefined ? {} : { timeout: config.timeout }),
+        ...(config.withCredentials === undefined ? {} : { withCredentials: config.withCredentials }),
+        ...(config.validateStatus === undefined ? {} : { validateStatus: config.validateStatus }),
+    };
+}
+function toRequestPayload(config) {
+    return {
+        url: config.url,
+        ...(config.method === undefined ? {} : { method: config.method }),
+        ...(config.params === undefined ? {} : { params: clonePublicValue(config.params) }),
+        ...(config.data === undefined ? {} : { data: clonePublicValue(config.data) }),
+        ...(config.headers === undefined ? {} : { headers: clonePublicValue(config.headers) }),
+        ...(config.timeout === undefined ? {} : { timeout: config.timeout }),
+        ...(config.withCredentials === undefined ? {} : { withCredentials: config.withCredentials }),
+    };
+}
+function normalizeHeaders(headers) {
+    if (!isPlainObject(headers)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(headers).flatMap(([key, value]) => (typeof value === 'string' ? [[key, value]] : [])));
+}
+function toNetworkResponse(payload, config) {
+    if (typeof payload.status !== 'number' || Number.isNaN(payload.status)) {
+        throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的 status', payload);
+    }
+    return {
+        data: payload.data,
+        status: payload.status,
+        ...(typeof payload.statusText === 'string' ? { statusText: payload.statusText } : {}),
+        headers: normalizeHeaders(payload.headers),
+        config: snapshotRequestConfig(config),
+    };
+}
+/**
+ * 发起网络请求并返回标准化响应。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param config 面向业务层的网络请求配置。
+ * @returns 标准化网络响应。HTTP 2xx 默认返回 resolve。
+ * @throws {HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
+ * @throws {HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
+ *
+ * @remarks
+ * `validateStatus` 仅在 SDK 侧执行，不会跨 bridge 传输函数值。
+ * 公开配置与返回结构都保持 axios-like 的窄接口，不暴露宿主原始协议字段。
+ *
+ * @example
+ * ```ts
+ * const result = await request(requester, {
+ *   url: 'https://api.xiaoheihe.cn/demo',
+ *   method: 'GET',
+ * })
+ * ```
+ */
+async function request(requester, config) {
+    const validateStatus = config.validateStatus || DEFAULT_VALIDATE_STATUS;
+    const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
+    const response = toNetworkResponse(responsePayload, config);
+    if (!validateStatus(response.status)) {
+        throw new HbMiniProgramNetworkError(response);
+    }
+    return response;
+}
+/**
+ * 创建 network 模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的网络模块对象。
+ */
+function createNetworkModule(requester) {
+    return {
+        request: config => request(requester, config),
     };
 }
 
-/** 系统窗口信息能力方法名。 */
-const SYSTEM_GET_WINDOW_INFO_METHOD = 'system.getWindowInfo';
+/**
+ * 视口窗口信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
 /**
  * 获取当前小程序窗口信息。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 当前小程序可用窗口信息。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function getWindowInfo(requester) {
-    return requester.request(SYSTEM_GET_WINDOW_INFO_METHOD);
+    return requester.request(VIEWPORT_GET_WINDOW_INFO_METHOD);
 }
-
-/** 获取小程序隔离 storage 能力方法名。 */
-const SYSTEM_GET_STORAGE_METHOD = 'system.getStorage';
-/** 获取小程序隔离 storage。 */
-function getStorage(requester, options) {
-    return requester.request(SYSTEM_GET_STORAGE_METHOD, options);
+/**
+ * 创建 Viewport 模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的 Viewport 模块对象。
+ */
+function createViewportModule(requester) {
+    return {
+        getWindowInfo: () => getWindowInfo(requester),
+    };
 }
 
-/** 写入小程序隔离 storage 能力方法名。 */
-const SYSTEM_SET_STORAGE_METHOD = 'system.setStorage';
-/** 写入小程序隔离 storage。 */
-function setStorage(requester, options) {
-    return requester.request(SYSTEM_SET_STORAGE_METHOD, options);
+/**
+ * 用户信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const USER_GET_INFO_METHOD = 'user.getInfo';
+/**
+ * 获取当前访问小程序用户的公开基础资料。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 当前用户的登录态与公开基础资料。
+ *
+ * 该能力只返回 `heybox_id`、`nickname`、`avatar` 三个公开字段。
+ * 未登录时不会触发登录流程，直接返回 `{ isLogin: false, userInfo: null }`。
+ *
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主运行时调用失败时抛出。
+ */
+function getInfo(requester) {
+    return requester.request(USER_GET_INFO_METHOD);
 }
 
-/** 创建系统模块。 */
-function createSystemModule(requester) {
+/**
+ * 创建用户模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的用户模块对象。
+ */
+function createUserModule(requester) {
     return {
-        getWindowInfo: () => getWindowInfo(requester),
-        getStorage: options => getStorage(requester, options),
-        setStorage: options => setStorage(requester, options),
+        getInfo: () => getInfo(requester),
     };
 }
 
-/** 外部小程序 SDK 实例。 */
+/**
+ * 外部小程序 SDK 实例。
+ *
+ * @remarks
+ * 该实例负责组织授权、用户、分享、容器、存储与网络等开放能力，并维护
+ * iframe 内小程序与父容器之间的 bridge 生命周期。
+ *
+ * 多数业务页直接使用默认单例即可；只有在测试、多实例或需要定制运行参数时，
+ * 才建议显式创建独立实例。
+ *
+ * @example
+ * ```ts
+ * import { createMiniProgramSDK } from '@heybox/hb-sdk'
+ *
+ * const sdk = createMiniProgramSDK({
+ *   timeout: 15000,
+ * })
+ *
+ * await sdk.ready()
+ * ```
+ */
 class MiniProgramSDK {
     client;
-    /** 用户相关开放能力。 */
+    /** 授权相关开放能力。 */
+    auth;
+    /** 用户资料相关开放能力。 */
     user;
     /** 分享相关开放能力。 */
     share;
-    /** 系统相关开放能力。 */
-    system;
+    /** 视口相关开放能力。 */
+    viewport;
+    /** Storage 相关开放能力。 */
+    storage;
+    /** 网络请求相关开放能力。 */
+    network;
     constructor(options) {
         this.client = new MiniProgramBridgeClient(options);
+        this.auth = createAuthModule(this.client);
         this.user = createUserModule(this.client);
         this.share = createShareModule(this.client);
-        this.system = createSystemModule(this.client);
+        this.viewport = createViewportModule(this.client);
+        this.storage = createStorageModule(this.client);
+        this.network = createNetworkModule(this.client);
     }
-    /** 等待 SDK 与父容器完成握手。 */
+    /**
+     * 等待 SDK 与父容器完成握手。
+     *
+     * @returns 当 bridge 握手成功后 resolve。
+     * @throws {HbMiniProgramSDKError} 当当前页面不在 iframe 中、缺少 nonce 或握手超时时抛出。
+     */
     ready() {
         return this.client.ready();
     }
-    /** 注册小程序生命周期或业务事件。 */
+    /**
+     * 注册小程序生命周期或业务事件。
+     *
+     * @param eventName 要监听的事件名。
+     * @param handler 事件处理函数。
+     * @returns 事件解绑函数。
+     */
     on(eventName, handler) {
         return this.client.on(eventName, handler);
     }
-    /** 移除小程序生命周期或业务事件。 */
+    /**
+     * 移除小程序生命周期或业务事件。
+     *
+     * @param eventName 要移除的事件名。
+     * @param handler 对应的事件处理函数。
+     */
     off(eventName, handler) {
         this.client.off(eventName, handler);
     }
-    /** 销毁 SDK 实例。 */
+    /**
+     * 销毁 SDK 实例。
+     *
+     * @remarks
+     * 销毁后会移除 message 监听，并拒绝尚未完成的 bridge 请求。
+     * 已销毁实例不应继续复用。
+     */
     destroy() {
         this.client.destroy();
     }
 }
-/** 创建独立 SDK 实例，主要用于测试或多实例场景。 */
+/**
+ * 创建独立 SDK 实例。
+ *
+ * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
+ *
+ * @remarks
+ * 适用于测试、多实例场景，或需要自定义 `timeout`、`targetWindow` 等运行参数的场景。
+ *
+ * @example
+ * ```ts
+ * import { createMiniProgramSDK } from '@heybox/hb-sdk'
+ *
+ * const sdk = createMiniProgramSDK({
+ *   timeout: 15000,
+ * })
+ * ```
+ */
 function createMiniProgramSDK(options) {
     return new MiniProgramSDK(options);
 }
@@ -424,42 +815,72 @@ function getDefaultSDK() {
     }
     return defaultSDK;
 }
-/** 等待默认 SDK 实例与父容器完成握手。 */
+/**
+ * 等待默认 SDK 实例与父容器完成握手。
+ *
+ * @returns 当默认 SDK 单例与父容器握手成功后 resolve。
+ * @throws {HbMiniProgramSDKError} 当当前页面不在 iframe 中、缺少 nonce 或握手超时时抛出。
+ */
 function ready() {
     return getDefaultSDK().ready();
 }
-/** 注册默认 SDK 实例的事件监听。 */
+/**
+ * 注册默认 SDK 实例的事件监听。
+ *
+ * @param eventName 要监听的事件名。
+ * @param handler 事件处理函数。
+ * @returns 事件解绑函数。
+ */
 function on(eventName, handler) {
     return getDefaultSDK().on(eventName, handler);
 }
-/** 移除默认 SDK 实例的事件监听。 */
+/**
+ * 移除默认 SDK 实例的事件监听。
+ *
+ * @param eventName 要移除的事件名。
+ * @param handler 对应的事件处理函数。
+ * @returns 无返回值。
+ */
 function off(eventName, handler) {
     getDefaultSDK().off(eventName, handler);
 }
-/** 默认 SDK 实例的用户模块。 */
+/** 默认 SDK 实例的授权模块。 */
+const auth = {
+    login: () => getDefaultSDK().auth.login(),
+};
+/** 默认 SDK 实例的用户资料模块。 */
 const user = {
     getInfo: () => getDefaultSDK().user.getInfo(),
-    login: () => getDefaultSDK().user.login(),
 };
 /** 默认 SDK 实例的分享模块。 */
 const share = {
     showShareMenu: options => getDefaultSDK().share.showShareMenu(options),
     screenshot: options => getDefaultSDK().share.screenshot(options),
 };
-/** 默认 SDK 实例的系统模块。 */
-const system = {
-    getWindowInfo: () => getDefaultSDK().system.getWindowInfo(),
-    getStorage: options => getDefaultSDK().system.getStorage(options),
-    setStorage: options => getDefaultSDK().system.setStorage(options),
+/** 默认 SDK 实例的 Viewport 模块。 */
+const viewport = {
+    getWindowInfo: () => getDefaultSDK().viewport.getWindowInfo(),
+};
+/** 默认 SDK 实例的 storage 模块。 */
+const storage = {
+    getStorage: options => getDefaultSDK().storage.getStorage(options),
+    setStorage: options => getDefaultSDK().storage.setStorage(options),
+};
+/** 默认 SDK 实例的 network 模块。 */
+const network = {
+    request: config => getDefaultSDK().network.request(config),
 };
 
 const hbSDK = {
     ready,
     on,
     off,
+    auth,
     user,
     share,
-    system,
+    viewport,
+    storage,
+    network,
 };
 
-export { HbMiniProgramSDKError, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MiniProgramSDK, SDK_HANDSHAKE_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, SYSTEM_GET_STORAGE_METHOD, SYSTEM_GET_WINDOW_INFO_METHOD, SYSTEM_SET_STORAGE_METHOD, USER_GET_INFO_METHOD, USER_LOGIN_METHOD, createMiniProgramSDK, createShareModule, createSystemModule, createUserModule, hbSDK as default, getInfo, getStorage, getWindowInfo, isMiniProgramBridgeMessage, login, off, on, ready, screenshot, setStorage, share, showShareMenu, system, user };
+export { AUTH_LOGIN_METHOD, HbMiniProgramNetworkError, HbMiniProgramSDKError, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MiniProgramSDK, NETWORK_REQUEST_METHOD, SDK_HANDSHAKE_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, USER_GET_INFO_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, auth, createAuthModule, createMiniProgramSDK, createNetworkModule, createShareModule, createStorageModule, createUserModule, createViewportModule, hbSDK as default, getInfo, getStorage, getWindowInfo, isMiniProgramBridgeMessage, login, network, off, on, ready, request, screenshot, setStorage, share, showShareMenu, storage, user, viewport };