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

package/README.md

@@ -43,6 +43,12 @@ import { MINI_PROGRAM_PROTOCOL_CAPABILITIES, type MiniProgramBridgeMessage } fro
 
 协议包不决定业务授权。`auth.login()` 的 UI、账号会话、授权码签发和 OpenAPI 都由 Host/服务端负责；协议层只传递经过约束的 request/response 数据。
 
+## 握手环境快照
+
+Runtime 可以在握手 response 中附带 `MiniProgramRuntimeEnvironmentInfo`。该快照只包含运行模式、Host App 版本、canonical 小程序 ID/版本和标准化操作系统信息，不包含账号、设备唯一标识、UA 或凭据。字段缺失和旧 Host 通过固定的 `null` / `'unknown'` 语义兼容；客户端 SDK 会在对外派发 `ready` 事件前缓存快照，业务代码通过根包的 `environment` 模块读取。
+
+该 response 是 v2 envelope 上的向后兼容扩展，不新增 capability method 或权限，也不提升 `MINI_PROGRAM_MESSAGE_VERSION`。旧 SDK 没有对应 pending request，会忽略该 response；新 SDK 遇到旧 Host 时生成未知值快照。
+
 ## 公开入口
 
 - `@heybox/hb-sdk-protocol`：本包唯一入口，适合 Host、Runtime 和协议维护代码。

package/package.json

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

package/src/bridge.ts

@@ -1,5 +1,5 @@
 import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { DownloadProgressPayload, UserInfoAuthorization } from './payloads';
+import type { DownloadProgressPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
 
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName =
@@ -22,6 +22,11 @@ export interface SDKHandshakePayload {
   userAgent: string;
   sdkVersion: string;
 }
+/** Runtime 对 SDK 握手的可选扩展响应。 */
+export interface SDKHandshakeResult {
+  /** Host 与 Runtime 归一化后的环境快照。 */
+  environment: MiniProgramRuntimeEnvironmentInfo;
+}
 export interface RuntimeLocationProbePayload {
   probeId: string;
   timestamp: number;

package/src/payloads.ts

@@ -134,6 +134,36 @@ export type ScreenshotPayload =
   | undefined;
 export type ScreenshotResult = unknown;
 
+/** 当前小程序实例的运行模式。 */
+export type MiniProgramRuntimeMode = 'production' | 'preview' | 'development' | 'unknown';
+
+/** Host 明确提供的操作系统名称。 */
+export type MiniProgramOperatingSystemName = 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown';
+
+/**
+ * Runtime 在握手期间下发的环境快照。
+ *
+ * @remarks
+ * 所有字段只用于界面适配、兼容降级和诊断，不能作为鉴权、权限控制或风控依据。
+ * 版本字段均为不透明字符串，除缺失判断外不承诺格式或大小比较语义。
+ */
+export interface MiniProgramRuntimeEnvironmentInfo {
+  readonly runtime: {
+    readonly mode: MiniProgramRuntimeMode;
+  };
+  readonly host: {
+    readonly appVersion: string | null;
+  };
+  readonly miniProgram: {
+    readonly id: string | null;
+    readonly version: string | null;
+  };
+  readonly operatingSystem: {
+    readonly name: MiniProgramOperatingSystemName;
+    readonly version: string | null;
+  };
+}
+
 export interface GetStoragePayload {
   key: string;
 }

package/types/bridge.d.ts

@@ -1,5 +1,5 @@
 import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { DownloadProgressPayload, UserInfoAuthorization } from './payloads';
+import type { DownloadProgressPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change';
 export interface MiniProgramBridgeError {
@@ -12,6 +12,11 @@ export interface SDKHandshakePayload {
     userAgent: string;
     sdkVersion: string;
 }
+/** Runtime 对 SDK 握手的可选扩展响应。 */
+export interface SDKHandshakeResult {
+    /** Host 与 Runtime 归一化后的环境快照。 */
+    environment: MiniProgramRuntimeEnvironmentInfo;
+}
 export interface RuntimeLocationProbePayload {
     probeId: string;
     timestamp: number;

package/types/payloads.d.ts

@@ -146,6 +146,33 @@ export type ScreenshotPayload = {
     post?: MiniProgramSharePostOptions | null;
 } | undefined;
 export type ScreenshotResult = unknown;
+/** 当前小程序实例的运行模式。 */
+export type MiniProgramRuntimeMode = 'production' | 'preview' | 'development' | 'unknown';
+/** Host 明确提供的操作系统名称。 */
+export type MiniProgramOperatingSystemName = 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown';
+/**
+ * Runtime 在握手期间下发的环境快照。
+ *
+ * @remarks
+ * 所有字段只用于界面适配、兼容降级和诊断，不能作为鉴权、权限控制或风控依据。
+ * 版本字段均为不透明字符串，除缺失判断外不承诺格式或大小比较语义。
+ */
+export interface MiniProgramRuntimeEnvironmentInfo {
+    readonly runtime: {
+        readonly mode: MiniProgramRuntimeMode;
+    };
+    readonly host: {
+        readonly appVersion: string | null;
+    };
+    readonly miniProgram: {
+        readonly id: string | null;
+        readonly version: string | null;
+    };
+    readonly operatingSystem: {
+        readonly name: MiniProgramOperatingSystemName;
+        readonly version: string | null;
+    };
+}
 export interface GetStoragePayload {
     key: string;
 }