@heybox/hb-sdk-protocol 0.8.2-alpha.1 → 0.8.2-alpha.2

package/package.json

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

package/src/bridge.ts

@@ -68,14 +68,38 @@ export interface SDKCSPViolationPayload {
   sdkVersion: string;
   timestamp: number;
 }
+
+/**
+ * SDK 与 Host Runtime 跨 iframe 传输时共用的顶层 bridge envelope。
+ *
+ * @typeParam TPayload - 当前 method 对应的 payload 类型；未知或尚未按 method 收窄时默认为 `unknown`。
+ *
+ * @remarks
+ * 该类型刻意保留为宽 envelope，以同时表达 handshake、request、response、event 与 cancel。
+ * 字段组合的运行时约束由 {@link isMiniProgramBridgeMessage} 执行；v2 cancel 和 operation progress
+ * 可分别使用 {@link MiniProgramBridgeCancelMessage} 与 {@link MiniProgramBridgeProgressMessage}
+ * 获得更精确的静态类型。
+ *
+ * 类型匹配不建立信任边界。从 `postMessage` 接收数据时，先以 `unknown` 交给 guard，再独立校验
+ * `MessageEvent.source`、预期 nonce、握手状态，以及具体 method 的 payload；当 origin 可以固定且
+ * 当前协议模式要求时，再校验 `MessageEvent.origin`。
+ */
 export interface MiniProgramBridgeMessage<TPayload = unknown> {
+  /** 固定协议 namespace，用于从其他页面消息中识别候选 envelope。 */
   namespace: typeof MINI_PROGRAM_MESSAGE_NAMESPACE;
+  /** 当前消息采用的 wire 版本；新消息使用 v2，接收端为兼容握手接受 v1。 */
   version: 1 | 2;
+  /** Runtime 创建 iframe 时分配并由双方逐条回传的实例 nonce。 */
   nonce: string;
+  /** 决定 id、method、payload 与 error 组合规则的消息类别。 */
   type: MiniProgramBridgeMessageType;
+  /** 请求关联 ID；普通生命周期 event 可省略，request、response、handshake、cancel 与 progress 必须提供。 */
   id?: string;
+  /** capability 或事件名；response 可省略，cancel 禁止携带。 */
   method?: string;
+  /** method 对应的 wire payload；必须在按 method 分发后继续校验。 */
   payload?: TPayload;
+  /** 失败 response 的结构化错误；其他消息类型不得携带。 */
   error?: MiniProgramBridgeError;
 }
 

package/src/capabilities.ts

@@ -238,14 +238,33 @@ export type MiniProgramCapabilityModule =
   | 'companion';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 
+/** 单个公开 bridge method 的机器可读协议元数据。 */
 export interface MiniProgramCapabilityDefinition {
+  /** wire envelope 中使用的唯一 method 名。 */
   method: MiniProgramBridgeMethod;
+  /** 负责实现和分发该 method 的 capability module。 */
   module: MiniProgramCapabilityModule;
+  /** Runtime capability 开关使用的 key；当前公开协议中与 {@link method} 相同。 */
   capability: MiniProgramBridgeMethod;
+  /** Manifest 声明必须满足的权限组合；不替代权限状态、Host 支持或业务授权校验。 */
   requirement: MiniProgramPermissionRequirement;
+  /** 供审核、诊断和展示使用的静态风险分级；它本身不会执行安全策略。 */
   risk: MiniProgramCapabilityRisk;
 }
 
+/**
+ * 所有公开小程序 bridge method 的权威 method-level 目录。
+ *
+ * @remarks
+ * Host Runtime、文档生成器和一致性测试使用该目录判断 method 是否属于协议、由哪个 module
+ * 持有，以及调用前需要满足哪些声明权限。每个 {@link MiniProgramBridgeMethod} 必须且只能出现
+ * 一次；消费者不应另建 method、module、requirement 或 risk 的平行目录。
+ *
+ * 该目录只拥有 method metadata。精确 payload/result 类型分别由
+ * {@link MiniProgramCapabilityPayloadMap} 与 {@link MiniProgramCapabilityResultMap} 定义，权限的
+ * 展示名称、配置字段和平台审批属性由 `MINI_PROGRAM_PERMISSION_CATALOG` 定义。`kind: 'none'`
+ * 仅表示无需 Manifest 权限声明，不表示绕过参数校验、Host 能力、可信手势或业务策略。
+ */
 export const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
   {
     method: AUTH_LOGIN_METHOD,

package/src/constants.ts

@@ -1,6 +1,31 @@
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 export const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram' as const;
+
+/**
+ * 新消息默认发送的当前 bridge wire 版本。
+ *
+ * @remarks 接收 guard 为握手协商继续接受 v1 与 v2 envelope；cancel 与 operation progress 等 v2-only 消息仍必须使用 v2。
+ */
 export const MINI_PROGRAM_MESSAGE_VERSION = 2 as const;
+
+/**
+ * Runtime 在 iframe URL 中传递 bridge nonce 的 query 参数名。
+ *
+ * @remarks nonce 用于把消息关联到当前 iframe 实例，不是独立的身份认证凭据；接收方还必须校验 source，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 export const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce' as const;
+
+/**
+ * SDK 发起 bridge 握手时使用的保留 method。
+ *
+ * @remarks `type: 'handshake'` 的消息必须使用该 method；Runtime 的可选握手响应也可携带该 method 供 SDK 识别环境快照。
+ */
 export const SDK_HANDSHAKE_METHOD = 'sdk.handshake' as const;
 export const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe' as const;
 export const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report' as const;