@heybox/hb-sdk 0.9.6-alpha.0 → 0.9.6-alpha.2

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-MBLQu8hw.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-JFfHePS2.js">
+    <script type="module" crossorigin src="/assets/index--xK6G3mS.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-DwX62DHx.js">
     <link rel="stylesheet" crossorigin href="/assets/index-DSTlrpnQ.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -424,6 +424,7 @@ const GAME_SAVES_READ_PARSED_DATA_METHOD = 'gameSaves.readParsedData';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
 const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
+const USER_SHOW_APPRECIATION_METHOD = 'user.showAppreciation';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
@@ -7508,7 +7509,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.6-alpha.0';
+    : '0.9.6-alpha.2';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -11388,13 +11389,18 @@ function getFollowStatus(requester) {
  *
  * @throws {@link HbMiniProgramSDKError} `userInfo` 未声明或不可用、握手失败、Host 不支持该能力、
  * 当前小程序身份缺失、账号/隔离身份读取失败、返回结构不合法、Runtime 终止，或请求期间
- * 账号与授权上下文变化时抛出。
+ * 账号与授权上下文变化时抛出。第三方联网小程序的身份读取返回 `SERVER_API_REQUIRED`。
  *
  * @remarks
+ * **网络权限决定用户信息的读取入口：`local` 模式使用本方法；联网的 `server` 模式
+ * 使用 `auth.login()` 与服务端换票，调用本方法读取身份会返回 `SERVER_API_REQUIRED`。**
+ *
  * 当前账号未登录属于正常返回分支，不抛错。账号已登录时，该能力不展示授权 UI，也不要求
  * 可信用户手势；Runtime 会静默建立或读取当前小程序的隔离 `app_user_id`，并授予
  * `identity` 与 `profile`。它只要求 Manifest 中声明 `userInfo`，不要求公开 `network`
- * 权限，也不返回可供服务端换票的授权码；开启网络权限后仍可调用。
+ * 权限，也不返回可供服务端换票的授权码。第三方小程序在启用网络权限的 `server` 模式下
+ * 会以 `SERVER_API_REQUIRED` 拒绝身份读取，应改用 `auth.login()` 并由开发者服务端换票；
+ * `local` 与兼容 `legacy` 模式保留直接读取能力。
  *
  * @example
  * ```ts
@@ -11446,6 +11452,7 @@ function createUserModule(requester) {
     return {
         requestFollowAuthor: () => requestFollowAuthor(requester),
         getFollowStatus: () => getFollowStatus(requester),
+        showAppreciation: () => requester.request(USER_SHOW_APPRECIATION_METHOD),
         getInfo: () => getInfo(requester),
         revokeAuthorization: () => revokeAuthorization(requester),
         getSteamGameList: (options) => getSteamGameList(requester, options),
@@ -12258,6 +12265,7 @@ const auth = {
 const user = {
     requestFollowAuthor: () => getDefaultSDK().user.requestFollowAuthor(),
     getFollowStatus: () => getDefaultSDK().user.getFollowStatus(),
+    showAppreciation: () => getDefaultSDK().user.showAppreciation(),
     getInfo: () => getDefaultSDK().user.getInfo(),
     revokeAuthorization: () => getDefaultSDK().user.revokeAuthorization(),
     getSteamGameList: (options) => getDefaultSDK().user.getSteamGameList(options),

package/dist/index.esm.js

@@ -420,6 +420,7 @@ const GAME_SAVES_READ_PARSED_DATA_METHOD = 'gameSaves.readParsedData';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
 const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
+const USER_SHOW_APPRECIATION_METHOD = 'user.showAppreciation';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
@@ -7504,7 +7505,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.6-alpha.0';
+    : '0.9.6-alpha.2';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -11384,13 +11385,18 @@ function getFollowStatus(requester) {
  *
  * @throws {@link HbMiniProgramSDKError} `userInfo` 未声明或不可用、握手失败、Host 不支持该能力、
  * 当前小程序身份缺失、账号/隔离身份读取失败、返回结构不合法、Runtime 终止，或请求期间
- * 账号与授权上下文变化时抛出。
+ * 账号与授权上下文变化时抛出。第三方联网小程序的身份读取返回 `SERVER_API_REQUIRED`。
  *
  * @remarks
+ * **网络权限决定用户信息的读取入口：`local` 模式使用本方法；联网的 `server` 模式
+ * 使用 `auth.login()` 与服务端换票，调用本方法读取身份会返回 `SERVER_API_REQUIRED`。**
+ *
  * 当前账号未登录属于正常返回分支，不抛错。账号已登录时，该能力不展示授权 UI，也不要求
  * 可信用户手势；Runtime 会静默建立或读取当前小程序的隔离 `app_user_id`，并授予
  * `identity` 与 `profile`。它只要求 Manifest 中声明 `userInfo`，不要求公开 `network`
- * 权限，也不返回可供服务端换票的授权码；开启网络权限后仍可调用。
+ * 权限，也不返回可供服务端换票的授权码。第三方小程序在启用网络权限的 `server` 模式下
+ * 会以 `SERVER_API_REQUIRED` 拒绝身份读取，应改用 `auth.login()` 并由开发者服务端换票；
+ * `local` 与兼容 `legacy` 模式保留直接读取能力。
  *
  * @example
  * ```ts
@@ -11442,6 +11448,7 @@ function createUserModule(requester) {
     return {
         requestFollowAuthor: () => requestFollowAuthor(requester),
         getFollowStatus: () => getFollowStatus(requester),
+        showAppreciation: () => requester.request(USER_SHOW_APPRECIATION_METHOD),
         getInfo: () => getInfo(requester),
         revokeAuthorization: () => revokeAuthorization(requester),
         getSteamGameList: (options) => getSteamGameList(requester, options),
@@ -12254,6 +12261,7 @@ const auth = {
 const user = {
     requestFollowAuthor: () => getDefaultSDK().user.requestFollowAuthor(),
     getFollowStatus: () => getDefaultSDK().user.getFollowStatus(),
+    showAppreciation: () => getDefaultSDK().user.showAppreciation(),
     getInfo: () => getDefaultSDK().user.getInfo(),
     revokeAuthorization: () => getDefaultSDK().user.revokeAuthorization(),
     getSteamGameList: (options) => getDefaultSDK().user.getSteamGameList(options),

package/dist/protocol.cjs.js

@@ -43,6 +43,7 @@ const GAME_SAVES_READ_PARSED_DATA_METHOD = 'gameSaves.readParsedData';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
 const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
+const USER_SHOW_APPRECIATION_METHOD = 'user.showAppreciation';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
@@ -177,6 +178,7 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['steamLibrary'] },
         risk: 'high',
     },
+    { method: USER_SHOW_APPRECIATION_METHOD, module: 'user', capability: USER_SHOW_APPRECIATION_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
     {
         method: SHARE_COPY_LINK_METHOD,
         module: 'share',

package/dist/protocol.esm.js

@@ -41,6 +41,7 @@ const GAME_SAVES_READ_PARSED_DATA_METHOD = 'gameSaves.readParsedData';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
 const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
+const USER_SHOW_APPRECIATION_METHOD = 'user.showAppreciation';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
@@ -175,6 +176,7 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['steamLibrary'] },
         risk: 'high',
     },
+    { method: USER_SHOW_APPRECIATION_METHOD, module: 'user', capability: USER_SHOW_APPRECIATION_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
     {
         method: SHARE_COPY_LINK_METHOD,
         module: 'share',

package/dist/vite.cjs.js

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

package/dist/vite.esm.js

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

package/docs/appreciation-code.md

@@ -0,0 +1,67 @@
+# 赞赏（实验性）
+
+`hbSDK.user.showAppreciation(): Promise<void>` 是**不稳定的实验性 API**，平台可随时调整、停用或下架，不承诺长期兼容。调用方必须捕获 SDK 错误，并在能力不可用时隐藏或降级赞赏入口。此标记不表示 API 已废弃。
+
+## 配置
+
+在开放平台“小程序管理 → 基础信息 → 微信赞赏码”中上传开发者微信导出的 JPG/PNG 原图（最大 2 MB，边长不超过 4096 像素），并打开“开启打赏”。图片复用现有上传服务，存放于当前小程序资源目录 `/u/<上传别名>/appreciation/<内容SHA256>.<jpg|png>`，上传成功后立即保存到平台。
+
+- 图片与开关分别保存：关闭开关不会删除图片，重新开启无需再次上传；开启且已上传图片时才对用户生效。
+- 图片上传和保存都成功才提示保存成功；保存失败可直接重试，不需要重新上传。
+- 更换图片时，原图在新图片保存成功前继续生效。
+- 刷新后台会读取已保存的图片和开关状态；读取失败时禁用编辑，点击“重新加载”后再操作。
+
+配置保存在平台的小程序资料中，**不写入 Manifest，不需要重新构建或发布小程序**，保存后对后续调用立即生效。沿用现有小程序管理权限，无需在 `permissions` 中声明，也不进入权限申请或审批。
+
+平台可停止展示赞赏码；停止期间开发者配置保留，恢复后无需重新上传。
+
+## 调用
+
+```ts
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+
+async function onSupportClick() {
+  try {
+    await hbSDK.user.showAppreciation()
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError &&
+        ['REQUEST_UNSUPPORTED', 'METHOD_NOT_FOUND'].includes(error.code)) {
+      hideSupportEntry()
+      return
+    }
+    // 请求失败时提示稍后重试；由用户再次点击，不自动循环重试。
+    showSupportError()
+  }
+}
+```
+
+方法不接收参数，不允许调用方指定图片 URL、收款人或金额。无需登录或 userInfo 权限，但必须由用户点击触发。宿主每次打开前都向平台重新查询赞赏码，不使用启动时的缓存；不支持、未配置、平台停用、请求失败或打开失败时抛 SDK 错误。
+
+**没有业务返回值。** Promise resolve 仅表示半弹窗已打开，不表示图片已保存，更不表示用户已付款。关闭弹窗不产生付款或取消付款结果。
+
+## 展示与保存
+
+标题为 `打赏「小程序名·开发者」`，名称取自平台已加载的小程序详情。说明为“金额随心，感谢你对开发者的支持”。半弹窗等比展示完整原图，主按钮为“查看并保存赞赏码”，引导用户打开客户端图片预览后长按保存，再前往微信识别。
+
+不改 Android/iOS，不新增原生保存、相册权限或设置接口，不自动拉起微信。宿主在打开前校验图片地址；Web 处理图片加载失败、打开预览失败、重复点击和关闭后的迟到结果，不伪造“保存成功”。未接入该半弹窗的宿主报能力不可用。
+
+## 埋点
+
+复用宿主 telemetry：`open`、`image_error`、`preview_click`、`preview_opened`、`preview_error`、`close`。只上报当前小程序 ID 和必要错误码，不上报赞赏码地址、图片内容或支付信息。这些事件均不能作为保存成功、支付成功或收入数据。
+
+本能力只提供赞赏码配置和展示，不涉及支付订单、钱包、结算、退款或到账通知。
+
+## 错误处理
+
+失败时 Promise reject `HbMiniProgramSDKError`，通过 `code` 分支处理，不依赖提示文案。底层请求失败也通过此类返回，不使用 `HbMiniProgramNetworkError`。
+
+| code | 含义与处理 |
+| --- | --- |
+| `REQUEST_UNSUPPORTED` | 宿主不支持、未开启、未配置图片或平台停用；隐藏或降级入口。 |
+| `METHOD_NOT_FOUND` | 旧 Runtime 尚未接入；隐藏或降级入口。 |
+| `REQUEST_FAILED` | 获取赞赏码失败；提示稍后重试，不永久隐藏入口。 |
+| `INVALID_STATE` | 缺少平台加载的小程序身份、名称或开发者信息；检查宿主接入。 |
+| `USER_GESTURE_REQUIRED` | 必须从真实点击事件直接调用。 |
+| `INVALID_PARAMS` | 此方法不接受任何参数。 |
+
+取消、上下文变化、宿主销毁与限流保留原错误码。弹窗打开后发生的图片加载或预览失败由弹窗反馈，并记录相应埋点，不会改变已经 resolve 的调用结果。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.6-alpha.0",
+  "version": "0.9.6-alpha.2",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -52,6 +52,7 @@
     "README.md",
     "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md",
+    "docs/appreciation-code.md",
     "docs/device-logs.md",
     "docs/runtime-host-migration.md",
     "bin",
@@ -76,7 +77,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.6-alpha.0"
+    "@heybox/hb-sdk-protocol": "0.9.6-alpha.2"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -128,13 +129,13 @@
     "vitest": "^3.2.4",
     "@ai-desktop/view-contract": "file:../hb-sdk-protocol/vendor/view-contract-2.2.2-6ac49bbf6410.tgz",
     "rollup-plugin-dts": "6.4.0",
-    "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.9.6-alpha.0",
+    "@heybox/hb-api": "~1.28.20",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-api": "~1.28.19",
+    "@heybox/hb-sdk-runtime": "~0.9.6-alpha.2",
+    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox/runtime-policy": "~0.2.1",
-    "@heybox/runtime": "~0.2.1",
-    "@heybox/runtime-transport-fetch": "~0.2.1"
+    "@heybox/runtime-transport-fetch": "~0.2.1",
+    "@heybox/runtime": "~0.2.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.6-alpha.0+skill.fe3b525ecac8",
+  "skillVersion": "0.9.6-alpha.2+skill.fe3b525ecac8",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.6-alpha.0",
-    "compatibility": "0.9.6-alpha.0"
+    "version": "0.9.6-alpha.2",
+    "compatibility": "0.9.6-alpha.2"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.6-alpha.0",
+    "version": "0.9.6-alpha.2",
     "path": "skill"
   },
   "integrity": "sha256-fe3b525ecac8431e1774ee453864cf9ba58ff6897272e2356ceb17b621c8c427"

package/types/index.d.ts

@@ -2844,6 +2844,24 @@ interface MiniProgramUserModule {
      * @hbPlatform macos
      */
     getFollowStatus(): Promise<GetFollowStatusResult>;
+    /**
+     * 赞赏：打开当前小程序配置的开发者赞赏码半弹窗。
+     * @returns 弹窗打开后以 void resolve，不提供图片保存或付款结果。
+     * @throws {@link HbMiniProgramSDKError} `REQUEST_UNSUPPORTED` 表示宿主不支持、未配置或平台停用；
+     * `REQUEST_FAILED` 表示获取赞赏码失败；`INVALID_STATE` 表示缺少宿主小程序信息；
+     * `USER_GESTURE_REQUIRED` 表示缺少用户点击；`INVALID_PARAMS` 表示传入了参数。
+     * 旧 Runtime 可能返回 `METHOD_NOT_FOUND`；取消、上下文变化、销毁和限流保留对应错误码。
+     * @remarks 需要用户点击；无需 userInfo 权限和登录，不接受图片 URL、收款人或金额参数。
+     * 用户通过现有客户端图片预览长按保存，不自动打开微信。
+     * 此 API 不稳定，不承诺长期兼容；平台可随时调整、停用或下架。调用方必须捕获错误，并隐藏或降级赞赏入口。
+     * @since 0.9.6
+     * @experimental
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbClient android none
+     * @hbClient ios none
+     */
+    showAppreciation(): Promise<void>;
     /**
      * 获取当前黑盒 APP 登录态、授权状态和已获准披露的资料。
      *
@@ -2857,6 +2875,8 @@ interface MiniProgramUserModule {
      *
      * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED` 表示
      * 当前运行快照缺少或未启用 `userInfo` 权限；`INVALID_STATE` 表示缺少 canonical 小程序身份；
+     * `SERVER_API_REQUIRED` 表示第三方小程序处于联网的 `server` 模式，应使用 `auth.login()`
+     * 并由开发者服务端换票读取身份；
      * `REQUEST_FAILED` / `REQUEST_UNSUPPORTED` / `INVALID_RESPONSE` 表示 Host 或资料读取失败；
      * `HEYBOX_APP_LOGIN_REQUIRED` 表示初次登录态检查后，Host 会话在隔离身份读取期间失效；
      * `AUTHORIZATION_CONTEXT_CHANGED` 表示请求期间发生账号切换或授权撤销；
@@ -2869,9 +2889,14 @@ interface MiniProgramUserModule {
      * 两种情况调用方都应停止立即重试，避免把用户 IP 打成被封。
      *
      * @remarks
+     * **无网络的 `local` 模式使用本方法；有网络的 `server` 模式使用
+     * `auth.login()` 与服务端换票，调用本方法读取身份会返回 `SERVER_API_REQUIRED`。**
+     * 本地扫码调试的临时网络批准同样会影响身份模式。
+     *
      * 该读取不展示授权 UI，也不要求可信用户手势。Manifest 中必须声明 `userInfo`，但不需要
      * 公开 `network` 权限；Manifest 权限与 `authorization.identity/profile` 表示的用户授权是
-     * 两层独立门禁。开启网络权限后仍可调用本方法。
+     * 两层独立门禁。第三方小程序进入联网的 `server` 模式后不能调用本方法获取身份；
+     * 应使用 `auth.login()` 并由开发者服务端换票。`local` 与兼容 `legacy` 模式保留直接读取能力。
      *
      * 当前账号未登录是正常返回分支，不是 `HEYBOX_APP_LOGIN_REQUIRED` 错误。已登录时 Runtime
      * 会静默建立或读取本小程序隔离身份，并授予 `identity` 与 `profile`。`app_user_id` 只在