@heybox/hb-sdk 0.1.2

package/README.md

@@ -0,0 +1,463 @@
+# @heybox/hb-sdk
+
+面向黑盒外部小程序 iframe 沙盒的前端 SDK。它负责与父容器完成握手、收发 bridge 消息，并以受控模块的形式向外部小程序开放用户、分享、系统信息和隔离 storage 能力。
+
+## 为什么需要它
+
+外部小程序运行在父容器创建的 iframe 沙盒中，业务页面不能直接读取主站登录态，也不应该关心底层 `postMessage` 协议、nonce 校验、请求响应关联、超时清理、客户端协议参数过滤等细节。
+
+`@heybox/hb-sdk` 将这些通信细节封装为稳定接口，让小程序只通过被允许的能力访问父容器。父容器仍负责调用黑盒客户端协议，并在运行时过滤不适合开放给外部小程序的内部参数。
+
+## 当前对外导出
+
+> 以 `src/index.ts` 为准；历史目录、旧示例或构建产物若与当前入口不一致，以当前源码导出能力为准。
+
+- 默认导出 `hbSDK`：包含 `ready`、`on`、`off`、`user`、`share`、`system`。
+- 命名导出 `ready` / `on` / `off` / `user` / `share` / `system`：默认 SDK 单例能力。
+- `createMiniProgramSDK` / `MiniProgramSDK`：创建独立 SDK 实例，适合测试、多实例或显式生命周期管理场景。
+- `HbMiniProgramSDKError`：SDK 对外抛出的标准错误类型。
+- `MiniProgramRequester` / `MiniProgramSDKOptions`：底层请求与 SDK 初始化配置类型。
+- bridge 协议常量、类型与守卫：`MINI_PROGRAM_MESSAGE_NAMESPACE`、`MINI_PROGRAM_MESSAGE_VERSION`、`MINI_PROGRAM_BRIDGE_NONCE_PARAM`、`SDK_HANDSHAKE_METHOD`、`isMiniProgramBridgeMessage` 等。
+- 模块类型与方法常量：`MiniProgramUserModule`、`MiniProgramShareModule`、`MiniProgramSystemModule` 以及各模块 method 常量。
+
+## 快速开始
+
+最小示例：
+
+```ts
+import hbSDK from '@heybox/hb-sdk';
+
+await hbSDK.ready();
+
+const result = await hbSDK.user.getInfo();
+
+if (result.isLogin) {
+  console.log(result.userInfo.nickname);
+}
+```
+
+按需导入：
+
+```ts
+import { on, ready, user } from '@heybox/hb-sdk';
+
+const unsubscribe = on('show', (payload) => {
+  console.log('小程序展示', payload.timestamp, payload.source);
+});
+
+await ready();
+
+const currentUser = await user.getInfo();
+
+unsubscribe();
+```
+
+分享与 storage：
+
+```ts
+import { share, system } from '@heybox/hb-sdk';
+
+await share.showShareMenu({
+  title: '分享标题',
+  desc: '分享描述',
+  url: 'https://web.xiaoheihe.cn/tools/demo',
+  imageUrl: 'https://imgheybox.max-c.com/demo.png',
+});
+
+await system.setStorage({
+  key: 'settings',
+  data: {
+    theme: 'dark',
+  },
+});
+
+const { data } = await system.getStorage<{ theme: string }>({
+  key: 'settings',
+});
+```
+
+## 核心概念
+
+### 默认单例
+
+普通小程序页面优先使用默认导出的 `hbSDK`，或直接按需导入 `ready`、`on`、`off`、`user`、`share`、`system`。默认单例会在首次调用时懒创建，业务不需要手动初始化。
+
+```ts
+import { ready, system } from '@heybox/hb-sdk';
+
+await ready();
+const windowInfo = await system.getWindowInfo();
+```
+
+### 独立实例
+
+需要显式控制生命周期、注入测试环境 window、调整超时时间，或同页存在多套沙盒通信上下文时，可以使用 `createMiniProgramSDK`。
+
+```ts
+import { createMiniProgramSDK } from '@heybox/hb-sdk';
+
+const sdk = createMiniProgramSDK({
+  timeout: 5000,
+});
+
+await sdk.ready();
+
+const loginResult = await sdk.user.login();
+
+sdk.destroy();
+```
+
+### bridge 通信
+
+SDK 与父容器之间通过 `postMessage` 通信，消息会带上固定命名空间、协议版本与 iframe 实例 nonce。SDK 内部负责：
+
+- 从 URL query 读取 `hb_mini_bridge_nonce`，也支持通过 `MiniProgramSDKOptions.nonce` 显式传入。
+- 向父容器发送 `sdk.handshake` 握手消息，并等待 `ready` 事件。
+- 为每次能力调用生成请求 ID，匹配父容器返回的 response。
+- 过滤非小程序消息、非当前 nonce 消息以及非目标父窗口消息。
+- 处理请求超时、握手超时和销毁后的未完成请求。
+
+### 标准错误
+
+请求失败和 SDK 内部错误会统一包装为 `HbMiniProgramSDKError`，包含稳定的 `code`、面向开发者的 `message` 和可选 `data`。
+
+```ts
+import { HbMiniProgramSDKError, user } from '@heybox/hb-sdk';
+
+try {
+  await user.login();
+} catch (error) {
+  if (error instanceof HbMiniProgramSDKError) {
+    console.log(error.code, error.message, error.data);
+  }
+}
+```
+
+## 模块说明
+
+### Core
+
+核心模块位于 `src/core`，负责 SDK 实例、默认单例、bridge client、事件总线、错误和工具函数。
+
+| 模块 | 作用 | 代表导出 |
+| --- | --- | --- |
+| `core/sdk` | SDK 实例封装 | `MiniProgramSDK`、`createMiniProgramSDK` |
+| `core/singleton` | 默认单例入口 | `ready`、`on`、`off`、`user`、`share`、`system` |
+| `core/client` | bridge 握手、请求响应、事件分发 | `MiniProgramSDKOptions`、`MiniProgramRequester` |
+| `core/errors` | 标准错误类型 | `HbMiniProgramSDKError` |
+
+### User
+
+用户模块位于 `src/modules/user`，只暴露允许小程序访问的公开用户能力。
+
+| API | 说明 |
+| --- | --- |
+| `user.getInfo()` | 获取当前用户登录态与公开基础资料。未登录时不会触发登录流程。 |
+| `user.login()` | 唤起黑盒登录流程，并返回登录后的最新用户公开资料。 |
+
+用户信息只包含允许暴露给外部小程序的公开字段：
+
+```ts
+interface MiniProgramUserInfo {
+  heybox_id: string;
+  nickname: string;
+  avatar: string;
+}
+
+interface MiniProgramUserInfoResult {
+  isLogin: boolean;
+  userInfo: MiniProgramUserInfo | null;
+}
+```
+
+SDK 不会向小程序暴露 token、cookie、手机号或任何可用于直接调用主站私有接口的凭据。
+
+### Share
+
+分享模块位于 `src/modules/share`，对外提供简洁配置，父容器侧再映射到黑盒客户端协议。
+
+| API | 对应父容器能力 | 说明 |
+| --- | --- | --- |
+| `share.showShareMenu(options)` | `share.showShareMenu` -> `share` 协议 | 展示基础分享面板。 |
+| `share.screenshot(options?)` | `share.screenshot` -> `screenShotShareV2` 协议 | 截图并唤起分享。 |
+
+基础分享参数：
+
+```ts
+interface MiniProgramShowShareMenuOptions {
+  title: string;
+  desc: string;
+  url: string;
+  imageUrl?: string;
+  channel?: 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
+}
+```
+
+截图分享参数：
+
+```ts
+interface MiniProgramScreenshotOptions {
+  rect?: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  };
+  delay?: number;
+  saveToAlbum?: boolean;
+}
+```
+
+为了保持外部 API 稳定，`share` 模块不开放 raw protocol、JS callback、活动上报、发帖、自定义按钮、upload-only 等内部能力。
+
+### System
+
+系统模块位于 `src/modules/system`，当前提供窗口信息与隔离 storage 能力。
+
+| API | 对应父容器能力 | 说明 |
+| --- | --- | --- |
+| `system.getWindowInfo()` | `system.getWindowInfo` | 获取窗口、屏幕、安全区域等信息。 |
+| `system.getStorage(options)` | `system.getStorage` -> `getStorage` 协议 | 读取小程序隔离 storage。 |
+| `system.setStorage(options)` | `system.setStorage` -> `setStorage` 协议 | 写入小程序隔离 storage。 |
+
+`getWindowInfo()` 返回字段对齐微信小程序 `wx.getWindowInfo` 的常用字段：
+
+```ts
+interface MiniProgramWindowInfoResult {
+  pixelRatio: number;
+  screenWidth: number;
+  screenHeight: number;
+  windowWidth: number;
+  windowHeight: number;
+  statusBarHeight: number;
+  safeArea: {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    width: number;
+    height: number;
+  };
+  screenTop: number;
+}
+```
+
+storage API：
+
+```ts
+await system.setStorage({
+  key: 'settings',
+  data: {
+    enabled: true,
+  },
+});
+
+const result = await system.getStorage<{ enabled: boolean }>({
+  key: 'settings',
+});
+```
+
+storage 只开放 `get` / `set`，不开放 `removeStorage`、`clearStorage`、`getStorageInfo`、`getStorageV2`。父容器会强制加小程序级命名空间，外部小程序不能读写黑盒客户端全局 storage key。用户传入的 `key` 只允许 1-128 位字母、数字、下划线和连字符。
+
+### Protocol
+
+协议模块位于 `src/protocol`，定义父容器与 iframe SDK 之间的消息格式、事件名、事件 payload 映射、协议常量和消息守卫。
+
+当前支持的小程序事件：
+
+- `launch`：小程序首次完成握手并启动。
+- `ready`：SDK 已可安全调用开放能力。
+- `show`：小程序页面展示。
+- `hide`：小程序页面隐藏。
+- `unload`：小程序页面即将卸载。
+- `error`：父容器或开放能力运行异常。
+- `authChange`：登录状态发生变化后的最新用户信息。
+
+## 常见场景示例
+
+### 场景 1：进入页面后获取用户信息
+
+```ts
+import { ready, user } from '@heybox/hb-sdk';
+
+await ready();
+
+const result = await user.getInfo();
+
+if (!result.isLogin) {
+  // 可按业务需要展示登录按钮，不会在 getInfo 阶段自动唤起登录。
+  return;
+}
+
+renderUser(result.userInfo);
+```
+
+### 场景 2：点击按钮唤起登录
+
+```ts
+import { user } from '@heybox/hb-sdk';
+
+async function handleLoginClick() {
+  const result = await user.login();
+
+  if (result.isLogin) {
+    renderUser(result.userInfo);
+  }
+}
+```
+
+### 场景 3：展示分享面板
+
+```ts
+import { share } from '@heybox/hb-sdk';
+
+async function handleShareClick() {
+  await share.showShareMenu({
+    title: '我的小程序页面',
+    desc: '来自黑盒小程序的分享',
+    url: location.href,
+    imageUrl: 'https://imgheybox.max-c.com/demo.png',
+    channel: 'wechatSession',
+  });
+}
+```
+
+### 场景 4：截图分享当前页面
+
+```ts
+import { share } from '@heybox/hb-sdk';
+
+async function handleScreenshotShare() {
+  await share.screenshot({
+    delay: 100,
+    saveToAlbum: true,
+  });
+}
+```
+
+也可以指定截图区域：
+
+```ts
+await share.screenshot({
+  rect: {
+    left: 0,
+    top: 0,
+    width: 375,
+    height: 667,
+  },
+});
+```
+
+### 场景 5：读取窗口信息
+
+```ts
+import { system } from '@heybox/hb-sdk';
+
+const windowInfo = await system.getWindowInfo();
+
+console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
+```
+
+### 场景 6：使用隔离 storage
+
+```ts
+import { system } from '@heybox/hb-sdk';
+
+await system.setStorage({
+  key: 'card_mode',
+  data: {
+    enabled: true,
+  },
+});
+
+const { data } = await system.getStorage<{ enabled: boolean }>({
+  key: 'card_mode',
+});
+
+if (data?.enabled) {
+  enableCardMode();
+}
+```
+
+### 场景 7：监听生命周期与登录态变化
+
+```ts
+import { off, on } from '@heybox/hb-sdk';
+
+const handleShow = (payload) => {
+  console.log('页面展示', payload.timestamp);
+};
+
+const handleAuthChange = (payload) => {
+  console.log('登录态变化', payload.isLogin, payload.userInfo);
+};
+
+on('show', handleShow);
+on('authChange', handleAuthChange);
+
+// 页面销毁时移除监听
+off('show', handleShow);
+off('authChange', handleAuthChange);
+```
+
+也可以使用 `on` 返回的取消函数：
+
+```ts
+const unsubscribe = on('hide', (payload) => {
+  console.log('页面隐藏', payload.timestamp);
+});
+
+unsubscribe();
+```
+
+### 场景 8：测试中注入通信环境
+
+```ts
+import { createMiniProgramSDK } from '@heybox/hb-sdk';
+
+const sdk = createMiniProgramSDK({
+  nonce: 'test_nonce',
+  selfWindow: window,
+  targetWindow: parentWindow,
+  timeout: 100,
+});
+
+await sdk.ready();
+sdk.destroy();
+```
+
+## 能力边界与注意事项
+
+- SDK 只能在父容器创建的小程序 iframe 沙盒中正常完成握手；非 iframe 环境会抛出 `NOT_IN_IFRAME`。
+- 父容器必须在小程序 URL 上注入 `hb_mini_bridge_nonce`，否则会抛出 `MISSING_NONCE`。
+- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
+- `user.getInfo()` 只查询登录态，不会主动唤起登录。
+- `user.login()` 只返回公开用户资料，不返回 token、cookie 或私有凭据。
+- `share.showShareMenu()` 只开放基础分享字段，不开放活动任务上报、发帖、自定义按钮等内部协议参数。
+- `share.screenshot()` 只做截图并分享，不开放 upload-only 和客户端 JS callback。
+- `system.getWindowInfo()` 的 `statusBarHeight`、`screenTop`、`safeArea.top` 在黑盒容器内按顶部可用偏移处理。
+- `system.getStorage()` / `system.setStorage()` 只访问小程序隔离 storage；业务 key 必须符合 `/^[A-Za-z0-9_-]{1,128}$/`。
+- `on()` 会返回取消监听函数；页面卸载或组件销毁时应及时取消监听。
+- 独立实例不再使用时应调用 `destroy()`，以移除 message 监听并拒绝未完成请求。
+
+## 开发命令
+
+优先使用仓库统一的 `hbexec` 入口：
+
+```bash
+# 运行单元测试
+pnpm exec hbexec test unit @heybox/hb-sdk
+
+# 构建产物与类型声明
+pnpm exec hbexec build package -d packages/hb-sdk
+```
+
+也可以直接运行包内脚本：
+
+```bash
+# 运行单元测试
+pnpm --filter @heybox/hb-sdk run test:unit
+
+# 运行单元测试并生成覆盖率
+pnpm --filter @heybox/hb-sdk run test:unit:coverage
+```