@heybox/hb-sdk 0.8.4-alpha.0 → 0.8.5

package/dist/devtools/browser-dev-host/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-Bw1Bky5v.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-BSLoUst-.js">
+    <script type="module" crossorigin src="/assets/index-CS-AbGTE.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-BcQjavzW.js">
     <link rel="stylesheet" crossorigin href="/assets/index-0Ac39Njs.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -1342,7 +1342,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.4-alpha.0';
+    : '0.8.5';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/index.esm.js

@@ -1338,7 +1338,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.4-alpha.0';
+    : '0.8.5';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/vite.cjs.js

@@ -2948,7 +2948,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.4-alpha.0';
+    : '0.8.5';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/dist/vite.esm.js

@@ -2945,7 +2945,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.4-alpha.0';
+    : '0.8.5';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.4-alpha.0",
+  "version": "0.8.5",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -65,7 +65,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.8.4-alpha.0"
+    "@heybox/hb-sdk-protocol": "0.8.5"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -116,13 +116,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox/hb-api": "~1.28.9",
-    "@heybox/hb-sdk-runtime": "~0.8.4-alpha.0",
-    "@heybox/runtime-policy": "~0.2.0",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.8.5",
     "@heybox/runtime": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0"
+    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/runtime-policy": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.4-alpha.0+skill.aa24d6656331",
+  "skillVersion": "0.8.5+skill.aa24d6656331",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.4-alpha.0",
-    "compatibility": "0.8.4-alpha.0"
+    "version": "0.8.5",
+    "compatibility": "0.8.5"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.4-alpha.0",
+    "version": "0.8.5",
     "path": "skill"
   },
   "integrity": "sha256-aa24d6656331cbad8f6aae7735258a49d7f1a82f6e900415de53a1b93a30ddb8"

package/types/modules/auth/index.d.ts

@@ -108,6 +108,10 @@ export interface MiniProgramAuthModule {
      * @throws {@link HbMiniProgramSDKError} `REQUEST_FAILED`、`REQUEST_UNSUPPORTED`、
      * `INVALID_RESPONSE`、`INVALID_STATE`、`METHOD_FORBIDDEN` 或 `RUNTIME_DESTROYED`：Host
      * 请求、响应、身份上下文、能力支持或 Runtime 生命周期不满足调用要求。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED`：登录或授权上下文请求遇到上游 403/429，
+     * 或该 endpoint 处于 Runtime 熔断窗口；`error.data.retryAfterMs`（可能缺失）给出建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME`：Runtime 本地配额或循环检测
+     * 拒绝，请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。两者都应停止立即重试。
      * @throws {@link HbMiniProgramSDKError} SDK 握手、bridge 请求超时或 SDK 销毁时，抛出对应
      * 初始化/transport 错误；业务应根据稳定的 `error.code` 分支，不比较 `message`。
      *

package/types/modules/cloud/index.d.ts

@@ -280,6 +280,11 @@ export interface MiniProgramCloudLeaderboardModule {
      * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
      * `REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：返回记录字段不符合公开合同。
      * 其他 bridge 超时与 SDK 状态错误会保留对应错误码。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED`：上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.status` 为上游状态码，`error.data.retryAfterMs`（可能缺失）给出
+     * 建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME`：Runtime 本地配额或循环检测
+     * 拒绝，请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。两者都应停止立即重试。
      * @throws `DOMException` extra 含函数、Symbol 等不可 structured-clone 的内容时，浏览器可能
      * 在请求发送前抛出 `DataCloneError`。
      *
@@ -359,6 +364,11 @@ export interface MiniProgramCloudLeaderboardModule {
      * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需受信网络能力；
      * `REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：entries、cursor、hasMore 或任一记录
      * 字段不符合公开合同。其他 bridge 超时与 SDK 状态错误会保留对应错误码。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED`：上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.status` 为上游状态码，`error.data.retryAfterMs`（可能缺失）给出
+     * 建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME`：Runtime 本地配额或循环检测
+     * 拒绝，请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。两者都应停止立即重试。
      *
      * @remarks
      * 该查询不要求 Host 登录、用户授权或可信用户手势。它需要声明 `leaderboard`，但不需要
@@ -439,6 +449,11 @@ export interface MiniProgramCloudLeaderboardModule {
      * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
      * 其他网络失败、响应字段不合法和 bridge 超时分别保留对应 `REQUEST_FAILED`、
      * `INVALID_RESPONSE` 或 SDK 错误码。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED`：上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.status` 为上游状态码，`error.data.retryAfterMs`（可能缺失）给出
+     * 建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME`：Runtime 本地配额或循环检测
+     * 拒绝，请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。两者都应停止立即重试。
      *
      * @remarks
      * 当前用户不来自参数。Runtime 每次调用都会先向 Host 校验当前登录账号，再用 Host 持有的
@@ -520,6 +535,11 @@ export interface MiniProgramCloudLeaderboardModule {
      * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
      * 其他网络失败、响应不合法和 bridge 超时分别保留对应 `REQUEST_FAILED`、
      * `INVALID_RESPONSE` 或 SDK 错误码。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED`：上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.status` 为上游状态码，`error.data.retryAfterMs`（可能缺失）给出
+     * 建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME`：Runtime 本地配额或循环检测
+     * 拒绝，请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。两者都应停止立即重试。
      *
      * @remarks
      * 当前用户不来自参数。Runtime 先向 Host 读取当前登录状态，再用 Host 持有的受信会话调用
@@ -587,6 +607,11 @@ export interface MiniProgramCloudLeaderboardModule {
      * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需受信网络能力；
      * `REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：返回 key、order 或 rankLimit
      * 不符合公开合同。其他 bridge 超时与 SDK 状态错误会保留对应错误码。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED`：上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.status` 为上游状态码，`error.data.retryAfterMs`（可能缺失）给出
+     * 建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME`：Runtime 本地配额或循环检测
+     * 拒绝，请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。两者都应停止立即重试。
      *
      * @remarks
      * 该查询不读取当前用户，也不要求 Host 登录、用户授权或可信用户手势。它需要声明

package/types/modules/user/index.d.ts

@@ -23,6 +23,12 @@ export interface MiniProgramUserModule {
      * `HEYBOX_APP_LOGIN_REQUIRED` 表示初次登录态检查后，Host 会话在隔离身份读取期间失效；
      * `AUTHORIZATION_CONTEXT_CHANGED` 表示请求期间发生账号切换或授权撤销；
      * `RUNTIME_DESTROYED` 表示 Runtime 已终止。握手失败也会以该错误类型拒绝调用。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED` 表示上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.status` 为上游状态码，`error.data.retryAfterMs`（可能缺失）给出
+     * 建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME` 表示 Runtime 本地拒绝（每 session
+     * 配额或同 endpoint 循环检测），请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。
+     * 两种情况调用方都应停止立即重试，避免把用户 IP 打成被封。
      *
      * @remarks
      * 该读取不展示授权 UI，也不要求可信用户手势。Manifest 中必须声明 `userInfo`，但不需要
@@ -89,6 +95,11 @@ export interface MiniProgramUserModule {
      * @throws {@link HbMiniProgramSDKError} `REQUEST_UNSUPPORTED` / `REQUEST_FAILED` /
      * `INVALID_RESPONSE` 表示 Host 请求能力、撤销请求或响应失败；`AUTHORIZATION_CONTEXT_CHANGED`
      * 表示请求期间切换了账号或授权上下文已变化。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED` 表示上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.retryAfterMs`（可能缺失）给出建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME` 表示 Runtime 本地拒绝（每 session
+     * 配额或同 endpoint 循环检测），请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。
+     * 两种情况调用方都应停止立即重试。
      * @throws {@link HbMiniProgramSDKError} `RUNTIME_DESTROYED` / `SDK_DESTROYED` 表示 Runtime 或 SDK
      * 已终止。SDK 握手失败或超过调用超时时间时，还会返回对应握手错误码或 `REQUEST_TIMEOUT`。
      * @remarks
@@ -157,6 +168,11 @@ export interface MiniProgramUserModule {
      * @throws {@link HbMiniProgramSDKError} `AUTHORIZATION_CONTEXT_CHANGED` 表示请求期间切换账号
      * 或撤销授权；`RUNTIME_DESTROYED` / `SDK_DESTROYED` 表示 Runtime 或 SDK 已终止。SDK 握手失败
      * 或超过调用超时时间时，还会返回对应的握手错误码或 `REQUEST_TIMEOUT`。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED` 表示上游返回 403/429，或该 endpoint 处于
+     * Runtime 熔断窗口；`error.data.retryAfterMs`（可能缺失）给出建议退避时长。
+     * @throws {@link HbMiniProgramSDKError} `RATE_LIMITED_BY_RUNTIME` 表示 Runtime 本地拒绝（每 session
+     * 配额或同 endpoint 循环检测），请求没有到达上游；`error.data.origin` 为 `'budget'` 或 `'loop'`。
+     * 两种情况调用方都应停止立即重试。
      * @remarks
      * 项目必须在 `package.json#heybox.permissions` 声明 `steamLibrary`。该能力通过 Host 的受信
      * 请求读取当前账号数据，不要求公开 `network` 权限，也不展示授权 UI 或要求可信用户手势。

package/types/protocol/dev-session.d.ts

@@ -1,5 +1,21 @@
 import type { MiniProgramRuntimePermissionsSnapshot } from './runtime-permissions';
 import type { MiniProgramLocalDevGrant, MiniProgramLocalDevPermissionDeclarations } from '@heybox/hb-sdk-protocol';
+/**
+ * 网关限流状态。
+ *
+ * 加性、向后兼容字段：老宿主页或老 Runtime 忽略即可。CLI 收到 403/429 后把状态透出给
+ * 调试页与宿主页，让手机端停止「重连 → 打接口 → 被拒 → 再重连」的自激循环。
+ */
+export interface MiniProgramDevRateLimitState {
+    /** 是否处于限流中；仅在限流时下发，取值为 true。 */
+    limited: boolean;
+    /** 网关建议的等待时长（毫秒）。 */
+    retryAfterMs?: number;
+    /** 限流预计解除的绝对时间（Unix 毫秒）。 */
+    untilTs?: number;
+    /** 网关原文摘要，仅用于展示。 */
+    message?: string;
+}
 export interface MiniProgramLocalDevContextFields {
     local_dev_grant?: MiniProgramLocalDevGrant;
     context_revision?: number;
@@ -9,6 +25,8 @@ export interface MiniProgramLocalDevContextFields {
     local_dev_launch_token?: string;
     mini_program_id?: string;
     companion_manifest_sha256?: string;
+    /** 限流状态；正常时不下发该字段。 */
+    rate_limit?: MiniProgramDevRateLimitState | null;
 }
 /** Dev Shell 读取局域网 Dev Session endpoint 的 query 参数。 */
 export declare const MINI_PROGRAM_DEV_CONTEXT_QUERY_PARAM = "dev_context_url";