@heybox/hb-sdk 0.1.2 → 0.2.0-alpha.0

package/README.md

@@ -1,24 +1,27 @@
 # @heybox/hb-sdk
 
-面向黑盒外部小程序 iframe 沙盒的前端 SDK。它负责与父容器完成握手、收发 bridge 消息，并以受控模块的形式向外部小程序开放用户、分享、系统信息和隔离 storage 能力。
+面向黑盒外部小程序 iframe 沙盒的前端 SDK。它负责与父容器完成握手、收发 bridge 消息，并以受控模块的形式向外部小程序开放授权、用户、分享、视口、隔离 storage 与网络请求能力。
 
 ## 为什么需要它
 
 外部小程序运行在父容器创建的 iframe 沙盒中，业务页面不能直接读取主站登录态，也不应该关心底层 `postMessage` 协议、nonce 校验、请求响应关联、超时清理、客户端协议参数过滤等细节。
 
-`@heybox/hb-sdk` 将这些通信细节封装为稳定接口，让小程序只通过被允许的能力访问父容器。父容器仍负责调用黑盒客户端协议，并在运行时过滤不适合开放给外部小程序的内部参数。
+`@heybox/hb-sdk` 将这些通信细节封装为稳定接口，让小程序只通过被允许的能力访问父容器。父容器仍负责调用黑盒客户端协议，并在运行时过滤不适合开放给外部小程序的内部参数。网络请求能力同样遵循这个边界：SDK 提供 axios-like 的窄接口，运行时负责协议映射。
 
 ## 当前对外导出
 
 > 以 `src/index.ts` 为准；历史目录、旧示例或构建产物若与当前入口不一致，以当前源码导出能力为准。
 
-- 默认导出 `hbSDK`：包含 `ready`、`on`、`off`、`user`、`share`、`system`。
-- 命名导出 `ready` / `on` / `off` / `user` / `share` / `system`：默认 SDK 单例能力。
+- 默认导出 `hbSDK`：包含 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`、`network`。
+- 命名导出 `ready` / `on` / `off` / `auth` / `user` / `share` / `viewport` / `storage` / `network`：默认 SDK 单例能力。
 - `createMiniProgramSDK` / `MiniProgramSDK`：创建独立 SDK 实例，适合测试、多实例或显式生命周期管理场景。
-- `HbMiniProgramSDKError`：SDK 对外抛出的标准错误类型。
+- `HbMiniProgramSDKError`：bridge / 运行时 / 协议失败时的标准错误类型。
+- `HbMiniProgramNetworkError`：HTTP 已完成但未通过 SDK `validateStatus` 校验时的网络错误类型。
 - `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 常量。
+- bridge 协议常量、类型与守卫：根入口保留导出；运行时等宿主侧包应优先从 `@heybox/hb-sdk/protocol` 子入口导入，避免误依赖 SDK core / singleton。
+- 模块类型与方法常量：`MiniProgramAuthModule`、`MiniProgramUserModule`、`MiniProgramShareModule`、`MiniProgramViewportModule`、`MiniProgramStorageModule`、`MiniProgramNetworkModule` 以及各模块 method 常量。
+
+> 本版本为破坏性模块重排：登录归属 `auth`，窗口归属 `viewport`，存储归属 `storage`；旧的 `user.login()` 与 `system.*` 入口已移除。
 
 ## 快速开始
 
@@ -52,10 +55,18 @@ const currentUser = await user.getInfo();
 unsubscribe();
 ```
 
-分享与 storage：
+分享、storage 与 network：
 
 ```ts
-import { share, system } from '@heybox/hb-sdk';
+import { network, share, storage } from '@heybox/hb-sdk';
+
+const response = await network.request<{ ok: boolean }>({
+  url: 'https://api.example.com/demo',
+  method: 'GET',
+});
+
+console.log(response.status, response.data.ok);
+
 
 await share.showShareMenu({
   title: '分享标题',
@@ -64,29 +75,31 @@ await share.showShareMenu({
   imageUrl: 'https://imgheybox.max-c.com/demo.png',
 });
 
-await system.setStorage({
+await storage.setStorage({
   key: 'settings',
   data: {
     theme: 'dark',
   },
 });
 
-const { data } = await system.getStorage<{ theme: string }>({
+const { data } = await storage.getStorage<{ theme: string }>({
   key: 'settings',
 });
 ```
 
+网络请求默认只把 `2xx` 视为成功；`4xx/5xx` 这类已完成 HTTP 响应会在 SDK 模块层抛出 `HbMiniProgramNetworkError`，而 bridge / 运行时 / 协议失败仍然抛出 `HbMiniProgramSDKError`。`validateStatus` 仅在 SDK 本地执行，不会把函数值透传给父容器。
+
 ## 核心概念
 
 ### 默认单例
 
-普通小程序页面优先使用默认导出的 `hbSDK`，或直接按需导入 `ready`、`on`、`off`、`user`、`share`、`system`。默认单例会在首次调用时懒创建，业务不需要手动初始化。
+普通小程序页面优先使用默认导出的 `hbSDK`，或直接按需导入 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`。默认单例会在首次调用时懒创建，业务不需要手动初始化。
 
 ```ts
-import { ready, system } from '@heybox/hb-sdk';
+import { ready, viewport } from '@heybox/hb-sdk';
 
 await ready();
-const windowInfo = await system.getWindowInfo();
+const windowInfo = await viewport.getWindowInfo();
 ```
 
 ### 独立实例
@@ -102,7 +115,7 @@ const sdk = createMiniProgramSDK({
 
 await sdk.ready();
 
-const loginResult = await sdk.user.login();
+const loginResult = await sdk.auth.login();
 
 sdk.destroy();
 ```
@@ -112,20 +125,23 @@ sdk.destroy();
 SDK 与父容器之间通过 `postMessage` 通信，消息会带上固定命名空间、协议版本与 iframe 实例 nonce。SDK 内部负责：
 
 - 从 URL query 读取 `hb_mini_bridge_nonce`，也支持通过 `MiniProgramSDKOptions.nonce` 显式传入。
-- 向父容器发送 `sdk.handshake` 握手消息，并等待 `ready` 事件。
+- 支持通过 `MiniProgramSDKOptions.targetOrigin` 显式指定发往父容器的 `postMessage targetOrigin`；未传时会尝试推断父容器 origin，失败则兼容回退为 `*`。
+- 向父容器发送 `sdk.handshake` 握手消息；如果还没有收到 `ready` 事件，会在总超时窗口内短间隔重试。
 - 为每次能力调用生成请求 ID，匹配父容器返回的 response。
 - 过滤非小程序消息、非当前 nonce 消息以及非目标父窗口消息。
-- 处理请求超时、握手超时和销毁后的未完成请求。
+- 处理请求超时、握手总超时和销毁后的未完成请求。
+
+父容器应幂等响应握手：重复 `sdk.handshake` 只代表 SDK 在补偿早期消息丢失，父容器可以重复派发 `ready`，但不应重复执行一次性启动副作用。
 
 ### 标准错误
 
 请求失败和 SDK 内部错误会统一包装为 `HbMiniProgramSDKError`，包含稳定的 `code`、面向开发者的 `message` 和可选 `data`。
 
 ```ts
-import { HbMiniProgramSDKError, user } from '@heybox/hb-sdk';
+import { HbMiniProgramSDKError, auth } from '@heybox/hb-sdk';
 
 try {
-  await user.login();
+  await auth.login();
 } catch (error) {
   if (error instanceof HbMiniProgramSDKError) {
     console.log(error.code, error.message, error.data);
@@ -142,18 +158,25 @@ try {
 | 模块 | 作用 | 代表导出 |
 | --- | --- | --- |
 | `core/sdk` | SDK 实例封装 | `MiniProgramSDK`、`createMiniProgramSDK` |
-| `core/singleton` | 默认单例入口 | `ready`、`on`、`off`、`user`、`share`、`system` |
+| `core/singleton` | 默认单例入口 | `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage` |
 | `core/client` | bridge 握手、请求响应、事件分发 | `MiniProgramSDKOptions`、`MiniProgramRequester` |
 | `core/errors` | 标准错误类型 | `HbMiniProgramSDKError` |
 
+### Auth
+
+授权模块位于 `src/modules/auth`，承载登录授权类能力。
+
+| API | 对应父容器能力 | 说明 |
+| --- | --- | --- |
+| `auth.login()` | `auth.login` | 唤起黑盒登录流程，并返回登录后的最新用户公开资料。 |
+
 ### User
 
-用户模块位于 `src/modules/user`，只暴露允许小程序访问的公开用户能力。
+用户模块位于 `src/modules/user`，只暴露允许小程序访问的公开用户资料能力。
 
 | API | 说明 |
 | --- | --- |
 | `user.getInfo()` | 获取当前用户登录态与公开基础资料。未登录时不会触发登录流程。 |
-| `user.login()` | 唤起黑盒登录流程，并返回登录后的最新用户公开资料。 |
 
 用户信息只包含允许暴露给外部小程序的公开字段：
 
@@ -172,6 +195,42 @@ interface MiniProgramUserInfoResult {
 
 SDK 不会向小程序暴露 token、cookie、手机号或任何可用于直接调用主站私有接口的凭据。
 
+### Network
+
+网络模块位于 `src/modules/network`，提供一个窄化的 axios-like `network.request()` 接口。SDK 只暴露公共请求字段，父容器运行时负责把这些字段映射到实际协议。
+
+| API | 对应父容器能力 | 说明 |
+| --- | --- | --- |
+| `network.request(config)` | `network.request` | 发起网络请求；默认仅 `2xx` 视为成功。 |
+
+```ts
+interface MiniProgramNetworkRequestConfig {
+  url: string;
+  method?: string;
+  params?: Record<string, unknown>;
+  data?: unknown;
+  headers?: Record<string, string>;
+  timeout?: number;
+  withCredentials?: boolean;
+  validateStatus?: (status: number) => boolean;
+}
+
+interface MiniProgramNetworkResponse<T = unknown> {
+  data: T;
+  status: number;
+  statusText?: string;
+  headers: Record<string, string>;
+  config: MiniProgramNetworkRequestConfig;
+}
+```
+
+约束说明：
+
+- `validateStatus` 只在 SDK 本地执行，不会跨 bridge 传输函数。
+- `config` 是 SDK 公共请求配置快照，不包含任何原始 `sendRequestV2` 字段。
+- 公开响应头为 `Record<string, string>`；无法可靠解析时应视为 `{}`。
+- v1 不提供原始协议字段、回调函数、拦截器或上传下载进度等高级能力。
+
 ### Share
 
 分享模块位于 `src/modules/share`，对外提供简洁配置，父容器侧再映射到黑盒客户端协议。
@@ -210,15 +269,13 @@ interface MiniProgramScreenshotOptions {
 
 为了保持外部 API 稳定，`share` 模块不开放 raw protocol、JS callback、活动上报、发帖、自定义按钮、upload-only 等内部能力。
 
-### System
+### Viewport
 
-系统模块位于 `src/modules/system`，当前提供窗口信息与隔离 storage 能力。
+Viewport 模块位于 `src/modules/viewport`，承载窗口、视口和安全区域相关能力。
 
 | API | 对应父容器能力 | 说明 |
 | --- | --- | --- |
-| `system.getWindowInfo()` | `system.getWindowInfo` | 获取窗口、屏幕、安全区域等信息。 |
-| `system.getStorage(options)` | `system.getStorage` -> `getStorage` 协议 | 读取小程序隔离 storage。 |
-| `system.setStorage(options)` | `system.setStorage` -> `setStorage` 协议 | 写入小程序隔离 storage。 |
+| `viewport.getWindowInfo()` | `viewport.getWindowInfo` | 获取窗口、屏幕、安全区域等信息。 |
 
 `getWindowInfo()` 返回字段对齐微信小程序 `wx.getWindowInfo` 的常用字段：
 
@@ -242,17 +299,26 @@ interface MiniProgramWindowInfoResult {
 }
 ```
 
+### Storage
+
+Storage 模块位于 `src/modules/storage`，承载小程序隔离存储能力。
+
+| API | 对应父容器能力 | 说明 |
+| --- | --- | --- |
+| `storage.getStorage(options)` | `storage.getStorage` -> `getStorage` 协议 | 读取小程序隔离 storage。 |
+| `storage.setStorage(options)` | `storage.setStorage` -> `setStorage` 协议 | 写入小程序隔离 storage。 |
+
 storage API：
 
 ```ts
-await system.setStorage({
+await storage.setStorage({
   key: 'settings',
   data: {
     enabled: true,
   },
 });
 
-const result = await system.getStorage<{ enabled: boolean }>({
+const result = await storage.getStorage<{ enabled: boolean }>({
   key: 'settings',
 });
 ```
@@ -295,10 +361,10 @@ renderUser(result.userInfo);
 ### 场景 2：点击按钮唤起登录
 
 ```ts
-import { user } from '@heybox/hb-sdk';
+import { auth } from '@heybox/hb-sdk';
 
 async function handleLoginClick() {
-  const result = await user.login();
+  const result = await auth.login();
 
   if (result.isLogin) {
     renderUser(result.userInfo);
@@ -351,9 +417,9 @@ await share.screenshot({
 ### 场景 5：读取窗口信息
 
 ```ts
-import { system } from '@heybox/hb-sdk';
+import { viewport } from '@heybox/hb-sdk';
 
-const windowInfo = await system.getWindowInfo();
+const windowInfo = await viewport.getWindowInfo();
 
 console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
 ```
@@ -361,16 +427,16 @@ console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea
 ### 场景 6：使用隔离 storage
 
 ```ts
-import { system } from '@heybox/hb-sdk';
+import { storage } from '@heybox/hb-sdk';
 
-await system.setStorage({
+await storage.setStorage({
   key: 'card_mode',
   data: {
     enabled: true,
   },
 });
 
-const { data } = await system.getStorage<{ enabled: boolean }>({
+const { data } = await storage.getStorage<{ enabled: boolean }>({
   key: 'card_mode',
 });
 
@@ -426,20 +492,87 @@ await sdk.ready();
 sdk.destroy();
 ```
 
+## 与 `@heybox/hb-sdk-runtime` 的关系与兼容矩阵
+
+`@heybox/hb-sdk` 是 iframe 内部使用的客户端 SDK，`@heybox/hb-sdk-runtime` 是 iframe 外部宿主壳层使用的运行时实现。当前仓库选择将 **协议 / 契约相关内容继续维护在 `@heybox/hb-sdk` 内部**，而不是额外拆出一个 contract 包，以减少包数量、发布面和维护成本。
+
+约定如下：
+
+- `@heybox/hb-sdk-runtime` 可以依赖 `@heybox/hb-sdk` 中的 **协议常量、类型、消息守卫** 等契约层内容。
+- `@heybox/hb-sdk-runtime` **不应依赖** `@heybox/hb-sdk` 的 `core/*`、默认单例、客户端请求实现等客户端运行时逻辑。
+- 协议变更时，`@heybox/hb-sdk` 与 `@heybox/hb-sdk-runtime` 应按一组联动能力来评审和发布，而不是分别独立演进。
+
+### 兼容矩阵（当前约定）
+
+| `@heybox/hb-sdk` | `@heybox/hb-sdk-runtime` | 说明 |
+| --- | --- | --- |
+| 同一仓库主线版本 | 同一仓库主线版本 | 默认开发模式，按同一批次代码联动验证 |
+| 仅补丁级变更 | 仅补丁级变更 | 允许，但必须保持协议常量、消息结构、事件名和 payload 兼容 |
+| 协议字段 / 方法名 / 事件名变更 | 需要同步升级 | 不允许单边发布后假定另一侧自动兼容 |
+
+### 后续 CI 兼容性检查（待补）
+
+后续补 CI 时，至少应增加以下检查：
+
+1. **依赖边界检查**
+   - 禁止 `@heybox/hb-sdk-runtime` 引用 `@heybox/hb-sdk/core/*`、默认单例或客户端实现层。
+   - 只允许引用协议 / 契约层入口（例如 `@heybox/hb-sdk/protocol`）。
+2. **协议兼容性检查**
+   - 当 `MINI_PROGRAM_MESSAGE_*` 常量、事件名、方法名、payload 类型变更时，要求 `hb-sdk` 与 `hb-sdk-runtime` 相关测试同时通过。
+3. **联动验证检查**
+   - 至少跑一组 `hb-sdk` 单测 + `hb-sdk-runtime` 单测，确保客户端与宿主运行时没有单边漂移。
+4. **导出面检查**
+   - 若协议层导出发生调整，CI 需提醒评审同步检查 runtime 使用面，而不是默认为向后兼容。
+
 ## 能力边界与注意事项
 
 - SDK 只能在父容器创建的小程序 iframe 沙盒中正常完成握手；非 iframe 环境会抛出 `NOT_IN_IFRAME`。
 - 父容器必须在小程序 URL 上注入 `hb_mini_bridge_nonce`，否则会抛出 `MISSING_NONCE`。
+- 父容器需要幂等响应 `sdk.handshake`；SDK 会在收到 `ready` 前自动重试握手，不引用 SDK 的普通页面不会触发握手。
 - 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()` 只查询登录态，不会主动唤起登录。
-- `user.login()` 只返回公开用户资料，不返回 token、cookie 或私有凭据。
+- `auth.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}$/`。
+- `viewport.getWindowInfo()` 的 `statusBarHeight`、`screenTop`、`safeArea.top` 在黑盒容器内按顶部可用偏移处理。
+- `storage.getStorage()` / `storage.setStorage()` 只访问小程序隔离 storage；业务 key 必须符合 `/^[A-Za-z0-9_-]{1,128}$/`。
 - `on()` 会返回取消监听函数；页面卸载或组件销毁时应及时取消监听。
 - 独立实例不再使用时应调用 `destroy()`，以移除 message 监听并拒绝未完成请求。
 
+## CLI 创建外部小程序模板
+
+`hb-sdk create <project-name>` 会生成一个外部独立小程序开发模板，默认使用 Vue 3、Vite、TypeScript 和 npm。
+
+```bash
+hb-sdk create my-miniapp
+cd my-miniapp
+npm install
+npm run dev:mock
+```
+
+生成规则：
+
+- `project-name` 同时作为项目目录名和 `package.json` 的 `name`，必须是合法的非 scoped npm 包名，例如 `my-miniapp`。
+- 目标目录不存在时会自动创建；目标目录已存在但非空时会拒绝覆盖。
+- CLI 只生成文件，不会自动安装依赖、初始化 git 或打开编辑器。
+- 模板内置轻量 SDK 能力演示页和 Vitest 单测配置；`npm run dev:mock` 会启动本地 Vite 服务和 hb-sdk mock runtime host。
+
+## CLI 登录态
+
+`hb-sdk` CLI 内置 Heybox 浏览器登录流，登录态只保存在 `hb-sdk` 自己的本地缓存命名空间里，供 `hb-sdk` CLI 命令内部调用 Heybox 接口时复用。
+
+```bash
+hb-sdk login
+hb-sdk login status
+hb-sdk login clear
+```
+
+- `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
+- `hb-sdk login status` 只展示脱敏状态、`heyboxId`、登录时间和 cache 路径，不输出 `pkey`、cookie 或完整请求头。
+- `hb-sdk login clear` 只清理 `hb-sdk` 自己命名空间中的 Heybox 登录态。
+
+这份 CLI 登录态不会注入 iframe SDK，也不会改变 `hb-sdk dev --mock` 的 mock 用户、`auth.login()`、`user.getInfo()` 或 `network.request()` 行为。
+
 ## 开发命令
 
 优先使用仓库统一的 `hbexec` 入口：

package/bin/hb-sdk.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli.cjs');