@heybox/hb-sdk-protocol 0.9.0-alpha.4 → 0.9.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk-protocol",
-  "version": "0.9.0-alpha.4",
+  "version": "0.9.0-alpha.6",
   "description": "Heybox mini-program iframe bridge wire contracts.",
   "sideEffects": false,
   "exports": {

package/src/bridge.ts

@@ -16,6 +16,14 @@ import type {
 import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
+/**
+ * 小程序可订阅的生命周期、展示状态及业务事件名。
+ *
+ * @remarks
+ * 每个事件的载荷见 {@link MiniProgramEventPayloadMap}。事件不会向晚订阅者重放；`ready`
+ * 是握手成功通知，不是可查询的持久状态，也不保证只收到一次。具体事件能否产生取决于
+ * Host 的能力与生命周期，不能仅凭事件名称推导状态去重或投递保证。
+ */
 export type MiniProgramEventName =
   | 'launch'
   | 'viewport_change'
@@ -124,22 +132,65 @@ export interface MiniProgramBridgeProgressMessage<
   payload: MiniProgramCapabilityProgress<TMethod>;
   error?: never;
 }
+/**
+ * 公开事件名与对应载荷的映射，供 SDK 的类型化事件监听使用。
+ *
+ * @remarks
+ * 生命周期 `timestamp` 是 Runtime 发出通知时的 Unix 毫秒时间，不是 iframe 收到事件的
+ * 时间或单调时钟。事件只通知已注册的监听器；业务需要当前状态时应使用相应读取 API。
+ */
 export interface MiniProgramEventPayloadMap {
   /** 展示状态实际变化后通知；不回放初始状态，不支持或失败时不通知。 */
   display_change: import('./payloads').MiniProgramDisplayState & {
     /** api 为开发者调用；user 为用户点击宿主退出全屏按钮。同目标合并时保留首次发起来源。旧宿主可能不提供。 */
     source?: 'api' | 'user';
   };
+  /** 窗口信息变化通知；载荷与 `viewport.getWindowInfo()` 的结果结构一致。 */
   viewport_change: import('./payloads').MiniProgramWindowInfoResult;
-  launch: { timestamp: number; url?: string };
-  ready: { timestamp: number };
-  show: { timestamp: number; source?: string };
-  hide: { timestamp: number; source?: string };
-  unload: { timestamp: number };
+  /** 初次握手时的启动通知；晚订阅不能补收。 */
+  launch: {
+    /** Runtime 发出通知时的 Unix 毫秒时间。 */
+    timestamp: number;
+    /** Host 加载 iframe 时的启动 URL；可缺失，不代表页面当前导航地址。 */
+    url?: string;
+  };
+  /** 握手成功通知；重复握手可再次产生，应查询持久握手状态驱动 UI。 */
+  ready: {
+    /** Runtime 发出通知时的 Unix 毫秒时间。 */
+    timestamp: number;
+  };
+  /** Host 通知小程序进入展示状态。 */
+  show: {
+    /** Runtime 发出通知时的 Unix 毫秒时间。 */
+    timestamp: number;
+    /** Host 可选提供的来源描述；不保证存在或采用固定枚举。 */
+    source?: string;
+  };
+  /** Host 通知小程序进入隐藏状态。 */
+  hide: {
+    /** Runtime 发出通知时的 Unix 毫秒时间。 */
+    timestamp: number;
+    /** Host 可选提供的来源描述；不保证存在或采用固定枚举。 */
+    source?: string;
+  };
+  /** Runtime 卸载的尽力通知；不能保证页面销毁前一定收到。 */
+  unload: {
+    /** Runtime 发出通知时的 Unix 毫秒时间。 */
+    timestamp: number;
+  };
+  /** 结构化 Runtime 错误通知；载荷不是 JavaScript `Error` 实例。 */
   error: MiniProgramBridgeError;
-  heybox_app_login_change: { isHeyboxAppLoggedIn: boolean };
+  /** Host 当前登录状态通知；相同状态可能重复出现，不能仅凭事件判断账号身份是否变化。 */
+  heybox_app_login_change: {
+    /** Host 当前是否有已登录的小黑盒账号，不表示开发者服务端会话状态。 */
+    isHeyboxAppLoggedIn: boolean;
+  };
+  /** 当前用户授权状态通知；可包含可选 `steam_account`，不是 Manifest 权限状态。 */
   user_info_authorization_change: UserInfoAuthorization;
+  /** 当前 Companion controller 收到的输出片段；去重与确认依据见载荷中的 sequence。 */
   [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
+  /** Companion session 的进程退出通知。 */
   [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
+  /** 当前 controller 失去 Companion session 控制权的通知。 */
   [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
 }

package/src/payloads.ts

@@ -24,7 +24,8 @@ export interface LoginResult {
  *
  * 该状态描述用户授权，不代表 `package.json#heybox.permissions` 的声明或平台审批结果。
  * 当前 Runtime 成功执行 `user.getInfo()` 时会静默授予 `identity` 与 `profile`，因此两项均为
- * `granted`；其余状态仍保留在公共协议中，供兼容 Host 和授权状态事件使用。
+ * `granted`；支持 Steam 账号能力的 Host 还会授予 `steam_account`。其余状态仍保留在公共协议中，
+ * 供兼容 Host 和授权状态事件使用。
  */
 export type UserInfoAuthorizationStatus = 'not_required' | 'not_requested' | 'granted' | 'denied';
 
@@ -57,6 +58,7 @@ export interface UserInfoAuthorization {
  * 当前黑盒 APP 用户已登录时，Runtime 会隐式授予 `identity` 与 `profile`，静默建立或
  * 读取隔离身份，并由 `user.getInfo()` 返回该对象。此过程只要求 Manifest 声明
  * `userInfo`，不要求公开 `network` 权限，也不会返回授权码或创建开发者服务端会话。
+ * 支持 Steam 账号能力的 Host 还会授予 `steam_account`；已授权且有主绑定时才包含 `steam_id`。
  *
  * 撤销授权后旧身份失效；调用方应停止使用旧值，并清理本地缓存与开发者服务端会话。
  * 再次调用 `user.getInfo()` 会按当前账号重新建立隔离身份，不能假定新旧 `app_user_id`
@@ -110,7 +112,7 @@ export interface AuthorizedUserInfo {
  *
  * - `false`：当前 Host 没有已登录的小黑盒账号，`authorization` 与 `userInfo` 固定为 `null`。
  *   这是正常业务分支，不会抛出登录错误。
- * - `true` 且 `userInfo` 非空：`authorization` 固定包含 `identity`、`profile` 两项状态；
+ * - `true` 且 `userInfo` 非空：`authorization` 必含 `identity`、`profile`，支持时还包含 `steam_account`；
  *   `userInfo` 包含当前小程序隔离的 `app_user_id`，而 `profile` 仍需独立判空。
  * - `true` 且 `userInfo` 为 `null`：公共协议为兼容 Host 保留的“已登录但资料未披露/不可用”分支。
  *   当前 Runtime 成功读取隔离身份时返回非空对象，但调用方仍应按类型处理该分支。
@@ -221,9 +223,9 @@ export interface SteamGameListItem {
   image?: string;
   /** 非空 Steam 图标 URL 字符串。 */
   icon?: string;
-  /** 服务端原始累计游玩时长数值；协议不承诺单位。 */
+  /** Steam 游戏库接口返回的累计游玩时长，当前单位为秒；`0` 是有效值。 */
   playtimeForever?: number;
-  /** 服务端原始最近游玩时长数值；协议不承诺单位。 */
+  /** Steam 游戏库接口返回的最近两周游玩时长，当前单位为秒；`0` 是有效值。 */
   playtime2Weeks?: number;
   /** 非空标签列表；没有有效标签时省略。 */
   tags?: string[];
@@ -1053,6 +1055,10 @@ export interface CompanionOpenAttachmentPayload extends CompanionSessionControll
   id: string;
 }
 export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
+/**
+ * 桌面辅助应用通知的语义类别：`completed` 为完成，`failed` 为失败，`stopped` 为停止，
+ * `attention` 为需要用户关注。它只选择通知类别，不会改变进程或 session 状态。
+ */
 export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
 export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
   category: CompanionNotificationCategory;

package/types/bridge.d.ts

@@ -2,6 +2,14 @@ import { COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION
 import type { CompanionSessionExitPayload, CompanionSessionOutputPayload, CompanionSessionOwnershipLostPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
 import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
+/**
+ * 小程序可订阅的生命周期、展示状态及业务事件名。
+ *
+ * @remarks
+ * 每个事件的载荷见 {@link MiniProgramEventPayloadMap}。事件不会向晚订阅者重放；`ready`
+ * 是握手成功通知，不是可查询的持久状态，也不保证只收到一次。具体事件能否产生取决于
+ * Host 的能力与生命周期，不能仅凭事件名称推导状态去重或投递保证。
+ */
 export type MiniProgramEventName = 'launch' | 'viewport_change' | 'display_change' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change' | typeof COMPANION_SESSION_OUTPUT_EVENT | typeof COMPANION_SESSION_EXIT_EVENT | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
 export interface MiniProgramBridgeError {
     code: string;
@@ -91,37 +99,65 @@ export interface MiniProgramBridgeProgressMessage<TMethod extends MiniProgramPro
     payload: MiniProgramCapabilityProgress<TMethod>;
     error?: never;
 }
+/**
+ * 公开事件名与对应载荷的映射，供 SDK 的类型化事件监听使用。
+ *
+ * @remarks
+ * 生命周期 `timestamp` 是 Runtime 发出通知时的 Unix 毫秒时间，不是 iframe 收到事件的
+ * 时间或单调时钟。事件只通知已注册的监听器；业务需要当前状态时应使用相应读取 API。
+ */
 export interface MiniProgramEventPayloadMap {
     /** 展示状态实际变化后通知；不回放初始状态，不支持或失败时不通知。 */
     display_change: import('./payloads').MiniProgramDisplayState & {
         /** api 为开发者调用；user 为用户点击宿主退出全屏按钮。同目标合并时保留首次发起来源。旧宿主可能不提供。 */
         source?: 'api' | 'user';
     };
+    /** 窗口信息变化通知；载荷与 `viewport.getWindowInfo()` 的结果结构一致。 */
     viewport_change: import('./payloads').MiniProgramWindowInfoResult;
+    /** 初次握手时的启动通知；晚订阅不能补收。 */
     launch: {
+        /** Runtime 发出通知时的 Unix 毫秒时间。 */
         timestamp: number;
+        /** Host 加载 iframe 时的启动 URL；可缺失，不代表页面当前导航地址。 */
         url?: string;
     };
+    /** 握手成功通知；重复握手可再次产生，应查询持久握手状态驱动 UI。 */
     ready: {
+        /** Runtime 发出通知时的 Unix 毫秒时间。 */
         timestamp: number;
     };
+    /** Host 通知小程序进入展示状态。 */
     show: {
+        /** Runtime 发出通知时的 Unix 毫秒时间。 */
         timestamp: number;
+        /** Host 可选提供的来源描述；不保证存在或采用固定枚举。 */
         source?: string;
     };
+    /** Host 通知小程序进入隐藏状态。 */
     hide: {
+        /** Runtime 发出通知时的 Unix 毫秒时间。 */
         timestamp: number;
+        /** Host 可选提供的来源描述；不保证存在或采用固定枚举。 */
         source?: string;
     };
+    /** Runtime 卸载的尽力通知；不能保证页面销毁前一定收到。 */
     unload: {
+        /** Runtime 发出通知时的 Unix 毫秒时间。 */
         timestamp: number;
     };
+    /** 结构化 Runtime 错误通知；载荷不是 JavaScript `Error` 实例。 */
     error: MiniProgramBridgeError;
+    /** Host 当前登录状态通知；相同状态可能重复出现，不能仅凭事件判断账号身份是否变化。 */
     heybox_app_login_change: {
+        /** Host 当前是否有已登录的小黑盒账号，不表示开发者服务端会话状态。 */
         isHeyboxAppLoggedIn: boolean;
     };
+    /** 当前用户授权状态通知；可包含可选 `steam_account`，不是 Manifest 权限状态。 */
     user_info_authorization_change: UserInfoAuthorization;
+    /** 当前 Companion controller 收到的输出片段；去重与确认依据见载荷中的 sequence。 */
     [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
+    /** Companion session 的进程退出通知。 */
     [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
+    /** 当前 controller 失去 Companion session 控制权的通知。 */
     [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
 }

package/types/payloads.d.ts

@@ -23,7 +23,8 @@ export interface LoginResult {
  *
  * 该状态描述用户授权，不代表 `package.json#heybox.permissions` 的声明或平台审批结果。
  * 当前 Runtime 成功执行 `user.getInfo()` 时会静默授予 `identity` 与 `profile`，因此两项均为
- * `granted`；其余状态仍保留在公共协议中，供兼容 Host 和授权状态事件使用。
+ * `granted`；支持 Steam 账号能力的 Host 还会授予 `steam_account`。其余状态仍保留在公共协议中，
+ * 供兼容 Host 和授权状态事件使用。
  */
 export type UserInfoAuthorizationStatus = 'not_required' | 'not_requested' | 'granted' | 'denied';
 /**
@@ -54,6 +55,7 @@ export interface UserInfoAuthorization {
  * 当前黑盒 APP 用户已登录时，Runtime 会隐式授予 `identity` 与 `profile`，静默建立或
  * 读取隔离身份，并由 `user.getInfo()` 返回该对象。此过程只要求 Manifest 声明
  * `userInfo`，不要求公开 `network` 权限，也不会返回授权码或创建开发者服务端会话。
+ * 支持 Steam 账号能力的 Host 还会授予 `steam_account`；已授权且有主绑定时才包含 `steam_id`。
  *
  * 撤销授权后旧身份失效；调用方应停止使用旧值，并清理本地缓存与开发者服务端会话。
  * 再次调用 `user.getInfo()` 会按当前账号重新建立隔离身份，不能假定新旧 `app_user_id`
@@ -106,7 +108,7 @@ export interface AuthorizedUserInfo {
  *
  * - `false`：当前 Host 没有已登录的小黑盒账号，`authorization` 与 `userInfo` 固定为 `null`。
  *   这是正常业务分支，不会抛出登录错误。
- * - `true` 且 `userInfo` 非空：`authorization` 固定包含 `identity`、`profile` 两项状态；
+ * - `true` 且 `userInfo` 非空：`authorization` 必含 `identity`、`profile`，支持时还包含 `steam_account`；
  *   `userInfo` 包含当前小程序隔离的 `app_user_id`，而 `profile` 仍需独立判空。
  * - `true` 且 `userInfo` 为 `null`：公共协议为兼容 Host 保留的“已登录但资料未披露/不可用”分支。
  *   当前 Runtime 成功读取隔离身份时返回非空对象，但调用方仍应按类型处理该分支。
@@ -215,9 +217,9 @@ export interface SteamGameListItem {
     image?: string;
     /** 非空 Steam 图标 URL 字符串。 */
     icon?: string;
-    /** 服务端原始累计游玩时长数值；协议不承诺单位。 */
+    /** Steam 游戏库接口返回的累计游玩时长，当前单位为秒；`0` 是有效值。 */
     playtimeForever?: number;
-    /** 服务端原始最近游玩时长数值；协议不承诺单位。 */
+    /** Steam 游戏库接口返回的最近两周游玩时长，当前单位为秒；`0` 是有效值。 */
     playtime2Weeks?: number;
     /** 非空标签列表；没有有效标签时省略。 */
     tags?: string[];
@@ -965,6 +967,10 @@ export interface CompanionOpenAttachmentPayload extends CompanionSessionControll
     id: string;
 }
 export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
+/**
+ * 桌面辅助应用通知的语义类别：`completed` 为完成，`failed` 为失败，`stopped` 为停止，
+ * `attention` 为需要用户关注。它只选择通知类别，不会改变进程或 session 状态。
+ */
 export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
 export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
     category: CompanionNotificationCategory;