@heybox/hb-sdk 0.1.2 → 0.1.3

package/README.md

@@ -112,10 +112,12 @@ sdk.destroy();
 SDK 与父容器之间通过 `postMessage` 通信，消息会带上固定命名空间、协议版本与 iframe 实例 nonce。SDK 内部负责：
 
 - 从 URL query 读取 `hb_mini_bridge_nonce`，也支持通过 `MiniProgramSDKOptions.nonce` 显式传入。
-- 向父容器发送 `sdk.handshake` 握手消息，并等待 `ready` 事件。
+- 向父容器发送 `sdk.handshake` 握手消息；如果还没有收到 `ready` 事件，会在总超时窗口内短间隔重试。
 - 为每次能力调用生成请求 ID，匹配父容器返回的 response。
 - 过滤非小程序消息、非当前 nonce 消息以及非目标父窗口消息。
-- 处理请求超时、握手超时和销毁后的未完成请求。
+- 处理请求超时、握手总超时和销毁后的未完成请求。
+
+父容器应幂等响应握手：重复 `sdk.handshake` 只代表 SDK 在补偿早期消息丢失，父容器可以重复派发 `ready`，但不应重复执行一次性启动副作用。
 
 ### 标准错误
 
@@ -430,6 +432,7 @@ sdk.destroy();
 
 - SDK 只能在父容器创建的小程序 iframe 沙盒中正常完成握手；非 iframe 环境会抛出 `NOT_IN_IFRAME`。
 - 父容器必须在小程序 URL 上注入 `hb_mini_bridge_nonce`，否则会抛出 `MISSING_NONCE`。
+- 父容器需要幂等响应 `sdk.handshake`；SDK 会在收到 `ready` 前自动重试握手，不引用 SDK 的普通页面不会触发握手。
 - 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()` 只查询登录态，不会主动唤起登录。
 - `user.login()` 只返回公开用户资料，不返回 token、cookie 或私有凭据。

package/dist/index.cjs.js

@@ -112,6 +112,7 @@ function isMiniProgramBridgeMessage(value) {
 }
 
 const DEFAULT_TIMEOUT = 10000;
+const HANDSHAKE_RETRY_INTERVAL = 250;
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
 class MiniProgramBridgeClient {
     timeout;
@@ -127,6 +128,8 @@ class MiniProgramBridgeClient {
     resolveReady;
     rejectReady;
     readyTimer;
+    handshakeRetryTimer;
+    destroyed = false;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -189,11 +192,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;
         }
@@ -210,6 +219,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,
@@ -272,7 +297,7 @@ class MiniProgramBridgeClient {
             return;
         }
         this.readySettled = true;
-        this.clearReadyTimer();
+        this.clearReadyTimers();
         this.resolveReady();
     }
     failReady(error) {
@@ -280,15 +305,18 @@ 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) => {

package/dist/index.esm.js

@@ -108,6 +108,7 @@ function isMiniProgramBridgeMessage(value) {
 }
 
 const DEFAULT_TIMEOUT = 10000;
+const HANDSHAKE_RETRY_INTERVAL = 250;
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
 class MiniProgramBridgeClient {
     timeout;
@@ -123,6 +124,8 @@ class MiniProgramBridgeClient {
     resolveReady;
     rejectReady;
     readyTimer;
+    handshakeRetryTimer;
+    destroyed = false;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -185,11 +188,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 +215,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,
@@ -268,7 +293,7 @@ class MiniProgramBridgeClient {
             return;
         }
         this.readySettled = true;
-        this.clearReadyTimer();
+        this.clearReadyTimers();
         this.resolveReady();
     }
     failReady(error) {
@@ -276,15 +301,18 @@ 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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "",
   "exports": {
     ".": {

package/types/core/client.d.ts

@@ -30,6 +30,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private resolveReady;
     private rejectReady;
     private readyTimer?;
+    private handshakeRetryTimer?;
+    private destroyed;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     ready(): Promise<void>;
@@ -42,12 +44,13 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
     destroy(): void;
     private ensureStarted;
+    private postHandshake;
     private onMessage;
     private handleEvent;
     private handleResponse;
     private postMessage;
     private resolveReadyOnce;
     private failReady;
-    private clearReadyTimer;
+    private clearReadyTimers;
     private rejectAllPending;
 }