@heybox/hb-sdk 0.1.2

package/dist/index.cjs.js

@@ -0,0 +1,500 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/** SDK 对外抛出的标准错误类型。 */
+class HbMiniProgramSDKError extends Error {
+    /** 稳定错误码。 */
+    code;
+    /** 可选调试数据。 */
+    data;
+    constructor(error) {
+        super(error.message);
+        this.name = 'HbMiniProgramSDKError';
+        this.code = error.code;
+        this.data = error.data;
+    }
+}
+/** 创建 SDK 标准错误。 */
+function createSDKError(code, message, data) {
+    return new HbMiniProgramSDKError({
+        code,
+        message,
+        data,
+    });
+}
+
+/** SDK 内部事件总线，负责管理沙盒生命周期与业务事件监听。 */
+class MiniProgramEventBus {
+    eventHandlers = new Map();
+    /** 注册事件监听，并返回取消监听函数。 */
+    on(eventName, handler) {
+        const handlers = this.eventHandlers.get(eventName) || new Set();
+        handlers.add(handler);
+        this.eventHandlers.set(eventName, handlers);
+        return () => this.off(eventName, handler);
+    }
+    /** 移除事件监听。 */
+    off(eventName, handler) {
+        const handlers = this.eventHandlers.get(eventName);
+        if (!handlers) {
+            return;
+        }
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+            this.eventHandlers.delete(eventName);
+        }
+    }
+    /** 派发事件。 */
+    emit(eventName, payload) {
+        const handlers = this.eventHandlers.get(eventName);
+        if (!handlers) {
+            return;
+        }
+        handlers.forEach((handler) => {
+            handler(payload);
+        });
+    }
+}
+
+/** 小程序沙盒通信命名空间，父容器与 iframe 内 SDK 必须保持一致。 */
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/** 小程序沙盒通信协议版本。 */
+const MINI_PROGRAM_MESSAGE_VERSION = 1;
+/** 父容器注入到小程序 URL 上的通信 nonce 参数名。 */
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+/** SDK 初始化时发给父容器的握手方法名。 */
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+
+/** 获取浏览器全局 window。 */
+function getGlobalWindow() {
+    return typeof window === 'undefined' ? undefined : window;
+}
+/** 获取父窗口；非 iframe 环境返回 null。 */
+function getParentWindow(currentWindow) {
+    if (!currentWindow || currentWindow.parent === currentWindow) {
+        return null;
+    }
+    return currentWindow.parent;
+}
+/** 从父容器注入到 URL 的 query 中读取 bridge nonce。 */
+function readBridgeNonce(currentWindow) {
+    const href = currentWindow?.location?.href;
+    if (!href) {
+        return '';
+    }
+    try {
+        return new URL(href).searchParams.get(MINI_PROGRAM_BRIDGE_NONCE_PARAM) || '';
+    }
+    catch {
+        return '';
+    }
+}
+/** 创建请求 ID。 */
+function createMessageId() {
+    const cryptoApi = getGlobalWindow()?.crypto;
+    if (cryptoApi?.randomUUID) {
+        return cryptoApi.randomUUID();
+    }
+    return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+
+/** 判断未知数据是否符合小程序 bridge 消息信封。 */
+function isMiniProgramBridgeMessage(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const message = value;
+    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
+        message.version === MINI_PROGRAM_MESSAGE_VERSION &&
+        typeof message.nonce === 'string' &&
+        typeof message.type === 'string');
+}
+
+const DEFAULT_TIMEOUT = 10000;
+/** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
+class MiniProgramBridgeClient {
+    timeout;
+    selfWindow;
+    targetWindow;
+    nonce;
+    pendingRequests = new Map();
+    eventBus = new MiniProgramEventBus();
+    handleMessage;
+    started = false;
+    readySettled = false;
+    readyPromise;
+    resolveReady;
+    rejectReady;
+    readyTimer;
+    constructor(options = {}) {
+        this.timeout = options.timeout || DEFAULT_TIMEOUT;
+        this.selfWindow = options.selfWindow || getGlobalWindow();
+        this.targetWindow =
+            options.targetWindow === undefined ? getParentWindow(this.selfWindow) : options.targetWindow;
+        this.nonce = options.nonce || readBridgeNonce(this.selfWindow);
+        this.handleMessage = this.onMessage.bind(this);
+        this.readyPromise = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+        });
+        this.readyPromise.catch(() => undefined);
+    }
+    /** 等待父容器握手完成。 */
+    ready() {
+        this.ensureStarted();
+        return this.readyPromise;
+    }
+    /** 注册小程序事件监听。 */
+    on(eventName, handler) {
+        this.ensureStarted();
+        return this.eventBus.on(eventName, handler);
+    }
+    /** 移除小程序事件监听。 */
+    off(eventName, handler) {
+        this.eventBus.off(eventName, handler);
+    }
+    /** 调用父容器开放能力。 */
+    async request(method, payload) {
+        await this.ready();
+        const id = createMessageId();
+        const message = {
+            namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
+            version: MINI_PROGRAM_MESSAGE_VERSION,
+            nonce: this.nonce,
+            type: 'request',
+            id,
+            method,
+            payload,
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(createSDKError('REQUEST_TIMEOUT', `${method} 调用超时`));
+            }, this.timeout);
+            this.pendingRequests.set(id, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            try {
+                this.postMessage(message);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pendingRequests.delete(id);
+                reject(error);
+            }
+        });
+    }
+    /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
+    destroy() {
+        this.selfWindow?.removeEventListener('message', this.handleMessage);
+        this.clearReadyTimer();
+        this.rejectAllPending(createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁'));
+    }
+    ensureStarted() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        if (!this.selfWindow || !this.targetWindow) {
+            this.failReady(createSDKError('NOT_IN_IFRAME', '当前页面不在小程序沙盒 iframe 中'));
+            return;
+        }
+        if (!this.nonce) {
+            this.failReady(createSDKError('MISSING_NONCE', '缺少小程序沙盒通信标识'));
+            return;
+        }
+        this.selfWindow.addEventListener('message', this.handleMessage);
+        this.readyTimer = setTimeout(() => {
+            this.failReady(createSDKError('READY_TIMEOUT', '小程序沙盒握手超时'));
+        }, this.timeout);
+        this.postMessage({
+            namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
+            version: MINI_PROGRAM_MESSAGE_VERSION,
+            nonce: this.nonce,
+            type: 'handshake',
+            id: createMessageId(),
+            method: SDK_HANDSHAKE_METHOD,
+            payload: {
+                href: this.selfWindow.location.href,
+                userAgent: this.selfWindow.navigator.userAgent,
+            },
+        });
+    }
+    onMessage(event) {
+        if (event.source && event.source !== this.targetWindow) {
+            return;
+        }
+        if (!isMiniProgramBridgeMessage(event.data) || event.data.nonce !== this.nonce) {
+            return;
+        }
+        if (event.data.type === 'event') {
+            this.handleEvent(event.data);
+            return;
+        }
+        if (event.data.type === 'response') {
+            this.handleResponse(event.data);
+        }
+    }
+    handleEvent(message) {
+        const eventName = message.method;
+        if (eventName === 'ready') {
+            this.resolveReadyOnce();
+        }
+        this.eventBus.emit(eventName, message.payload);
+    }
+    handleResponse(message) {
+        if (!message.id) {
+            return;
+        }
+        const pending = this.pendingRequests.get(message.id);
+        if (!pending) {
+            return;
+        }
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(message.id);
+        if (message.error) {
+            pending.reject(new HbMiniProgramSDKError(message.error));
+            return;
+        }
+        pending.resolve(message.payload);
+    }
+    postMessage(message) {
+        if (!this.targetWindow) {
+            throw createSDKError('NOT_IN_IFRAME', '当前页面不在小程序沙盒 iframe 中');
+        }
+        this.targetWindow.postMessage(message, '*');
+    }
+    resolveReadyOnce() {
+        if (this.readySettled) {
+            return;
+        }
+        this.readySettled = true;
+        this.clearReadyTimer();
+        this.resolveReady();
+    }
+    failReady(error) {
+        if (this.readySettled) {
+            return;
+        }
+        this.readySettled = true;
+        this.clearReadyTimer();
+        this.rejectReady(error);
+    }
+    clearReadyTimer() {
+        if (!this.readyTimer) {
+            return;
+        }
+        clearTimeout(this.readyTimer);
+        this.readyTimer = undefined;
+    }
+    rejectAllPending(error) {
+        this.pendingRequests.forEach((pending) => {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        });
+        this.pendingRequests.clear();
+    }
+}
+
+/** 截图分享能力方法名。 */
+const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+/** 截图并唤起分享。 */
+function screenshot(requester, options) {
+    return requester.request(SHARE_SCREENSHOT_METHOD, options);
+}
+
+/** 展示分享面板能力方法名。 */
+const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
+/** 展示基础分享面板。 */
+function showShareMenu(requester, options) {
+    return requester.request(SHARE_SHOW_SHARE_MENU_METHOD, options);
+}
+
+/** 创建分享模块。 */
+function createShareModule(requester) {
+    return {
+        showShareMenu: options => showShareMenu(requester, options),
+        screenshot: options => screenshot(requester, options),
+    };
+}
+
+/** 用户信息能力方法名。 */
+const USER_GET_INFO_METHOD = 'user.getInfo';
+/**
+ * 获取当前访问小程序用户的公开基础资料。
+ *
+ * 该能力只返回 `heybox_id`、`nickname`、`avatar` 三个公开字段。
+ * 未登录时不会触发登录流程，直接返回 `{ isLogin: false, userInfo: null }`。
+ */
+function getInfo(requester) {
+    return requester.request(USER_GET_INFO_METHOD);
+}
+
+/** 用户登录能力方法名。 */
+const USER_LOGIN_METHOD = 'user.login';
+/**
+ * 唤起黑盒登录流程，并在流程返回后刷新用户公开基础资料。
+ *
+ * 该能力不会向小程序暴露 token、cookie 或任何登录凭据。
+ */
+function login(requester) {
+    return requester.request(USER_LOGIN_METHOD);
+}
+
+/** 创建用户模块。 */
+function createUserModule(requester) {
+    return {
+        getInfo: () => getInfo(requester),
+        login: () => login(requester),
+    };
+}
+
+/** 系统窗口信息能力方法名。 */
+const SYSTEM_GET_WINDOW_INFO_METHOD = 'system.getWindowInfo';
+/**
+ * 获取当前小程序窗口信息。
+ */
+function getWindowInfo(requester) {
+    return requester.request(SYSTEM_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);
+}
+
+/** 写入小程序隔离 storage 能力方法名。 */
+const SYSTEM_SET_STORAGE_METHOD = 'system.setStorage';
+/** 写入小程序隔离 storage。 */
+function setStorage(requester, options) {
+    return requester.request(SYSTEM_SET_STORAGE_METHOD, options);
+}
+
+/** 创建系统模块。 */
+function createSystemModule(requester) {
+    return {
+        getWindowInfo: () => getWindowInfo(requester),
+        getStorage: options => getStorage(requester, options),
+        setStorage: options => setStorage(requester, options),
+    };
+}
+
+/** 外部小程序 SDK 实例。 */
+class MiniProgramSDK {
+    client;
+    /** 用户相关开放能力。 */
+    user;
+    /** 分享相关开放能力。 */
+    share;
+    /** 系统相关开放能力。 */
+    system;
+    constructor(options) {
+        this.client = new MiniProgramBridgeClient(options);
+        this.user = createUserModule(this.client);
+        this.share = createShareModule(this.client);
+        this.system = createSystemModule(this.client);
+    }
+    /** 等待 SDK 与父容器完成握手。 */
+    ready() {
+        return this.client.ready();
+    }
+    /** 注册小程序生命周期或业务事件。 */
+    on(eventName, handler) {
+        return this.client.on(eventName, handler);
+    }
+    /** 移除小程序生命周期或业务事件。 */
+    off(eventName, handler) {
+        this.client.off(eventName, handler);
+    }
+    /** 销毁 SDK 实例。 */
+    destroy() {
+        this.client.destroy();
+    }
+}
+/** 创建独立 SDK 实例，主要用于测试或多实例场景。 */
+function createMiniProgramSDK(options) {
+    return new MiniProgramSDK(options);
+}
+
+let defaultSDK = null;
+function getDefaultSDK() {
+    if (!defaultSDK) {
+        defaultSDK = createMiniProgramSDK();
+    }
+    return defaultSDK;
+}
+/** 等待默认 SDK 实例与父容器完成握手。 */
+function ready() {
+    return getDefaultSDK().ready();
+}
+/** 注册默认 SDK 实例的事件监听。 */
+function on(eventName, handler) {
+    return getDefaultSDK().on(eventName, handler);
+}
+/** 移除默认 SDK 实例的事件监听。 */
+function off(eventName, handler) {
+    getDefaultSDK().off(eventName, handler);
+}
+/** 默认 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),
+};
+
+const hbSDK = {
+    ready,
+    on,
+    off,
+    user,
+    share,
+    system,
+};
+
+exports.HbMiniProgramSDKError = HbMiniProgramSDKError;
+exports.MINI_PROGRAM_BRIDGE_NONCE_PARAM = MINI_PROGRAM_BRIDGE_NONCE_PARAM;
+exports.MINI_PROGRAM_MESSAGE_NAMESPACE = MINI_PROGRAM_MESSAGE_NAMESPACE;
+exports.MINI_PROGRAM_MESSAGE_VERSION = MINI_PROGRAM_MESSAGE_VERSION;
+exports.MiniProgramSDK = MiniProgramSDK;
+exports.SDK_HANDSHAKE_METHOD = SDK_HANDSHAKE_METHOD;
+exports.SHARE_SCREENSHOT_METHOD = SHARE_SCREENSHOT_METHOD;
+exports.SHARE_SHOW_SHARE_MENU_METHOD = SHARE_SHOW_SHARE_MENU_METHOD;
+exports.SYSTEM_GET_STORAGE_METHOD = SYSTEM_GET_STORAGE_METHOD;
+exports.SYSTEM_GET_WINDOW_INFO_METHOD = SYSTEM_GET_WINDOW_INFO_METHOD;
+exports.SYSTEM_SET_STORAGE_METHOD = SYSTEM_SET_STORAGE_METHOD;
+exports.USER_GET_INFO_METHOD = USER_GET_INFO_METHOD;
+exports.USER_LOGIN_METHOD = USER_LOGIN_METHOD;
+exports.createMiniProgramSDK = createMiniProgramSDK;
+exports.createShareModule = createShareModule;
+exports.createSystemModule = createSystemModule;
+exports.createUserModule = createUserModule;
+exports.default = hbSDK;
+exports.getInfo = getInfo;
+exports.getStorage = getStorage;
+exports.getWindowInfo = getWindowInfo;
+exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
+exports.login = login;
+exports.off = off;
+exports.on = on;
+exports.ready = ready;
+exports.screenshot = screenshot;
+exports.setStorage = setStorage;
+exports.share = share;
+exports.showShareMenu = showShareMenu;
+exports.system = system;
+exports.user = user;