@heybox/hb-sdk 0.1.3 → 0.2.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.1.3",
+  "version": "0.2.0-alpha.1",
   "description": "",
   "exports": {
     ".": {
@@ -9,25 +9,46 @@
       "node": "./dist/index.cjs.js",
       "browser": "./dist/index.esm.js",
       "default": "./dist/index.esm.js"
+    },
+    "./protocol": {
+      "types": "./types/protocol.d.ts",
+      "heybox": "./src/protocol.ts",
+      "node": "./dist/protocol.cjs.js",
+      "browser": "./dist/protocol.esm.js",
+      "default": "./dist/protocol.esm.js"
     }
   },
+  "bin": {
+    "hb-sdk": "./bin/hb-sdk.cjs"
+  },
   "files": [
+    "bin",
     "dist",
+    "skill",
     "types"
   ],
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "dependencies": {
-    "@heybox/utils": "^2.1.1"
-  },
   "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
     "@heybox/hb-types": "^1.0.1",
     "@vitejs/plugin-vue2": "^2.3.3",
     "@rollup/plugin-typescript": "^11.1.6",
+    "@types/ejs": "^3.1.5",
+    "@types/fs-extra": "^11.0.4",
     "@types/node": "24.10.1",
     "@vitest/coverage-v8": "^3.2.4",
+    "commander": "^12.1.0",
+    "ejs": "^3.1.10",
+    "env-paths": "^2.2.1",
+    "fs-extra": "^11.3.0",
+    "get-port": "^7.1.0",
     "happy-dom": "^19.0.2",
+    "open": "^10.2.0",
+    "picocolors": "^1.1.1",
     "rimraf": "^5.0.5",
     "rollup": "^4.52.4",
     "typescript": "^5.9.3",
@@ -57,10 +78,14 @@
   },
   "scripts": {
     "dev": "vite",
-    "build:package": "nx exec -- sh -c \"pnpm run clean && pnpm run build:lib && pnpm run build:types\"",
+    "build:package": "nx exec -- sh -c \"pnpm run clean && pnpm run build:lib && pnpm run build:cli && pnpm run build:mock-host && pnpm run build:templates && pnpm run build:types\"",
     "build:watch": "pnpm run build:lib -w & pnpm run build:types -w",
     "build:lib": "rollup -c rollup.config.ts  --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
+    "build:cli": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
+    "build:mock-host": "node scripts/copy-mock-host.cjs",
+    "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",
+    "check:boundary": "node scripts/check-boundary.cjs",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",

package/skill/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: hb-sdk
+description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, and host/runtime protocol integration. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
+---
+
+# hb-sdk Agent Procedure
+
+Apply these instructions when writing, reviewing, or debugging code that consumes `@heybox/hb-sdk` or uses the companion `hb-sdk` CLI.
+
+## Step 1: Classify the task
+
+1. If the task is iframe mini-program business code, use the root package import path `@heybox/hb-sdk`.
+2. If the task is parent-container runtime, bridge-server, protocol contract, or `@heybox/hb-sdk-runtime` work, use `@heybox/hb-sdk/protocol` only for shared constants and types.
+3. If the task is project scaffolding, local Vite startup, browser mock runtime, CLI login cache, Agent Skill version diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
+4. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
+5. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, or protocol contracts, do not apply this skill.
+
+## Step 2: Load only the needed reference
+
+1. For root SDK imports, singleton usage, modules, and errors, read `references/api-root.md`.
+2. For host/runtime protocol contracts only, read `references/api-protocol.md`. Do not use this reference to build iframe business-code bridge messages.
+3. For common business flows, read `references/recipes.md`.
+4. For CLI commands, local mock runtime, generated templates, CLI login cache, Agent Skill doctor, and update reminders, read `references/cli.md`.
+5. For allowed/forbidden capabilities and security boundaries, read `references/safety-boundaries.md`.
+6. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
+7. For smoke-test expectations, positive examples, and anti-examples, read `references/examples.md`.
+8. For evaluating whether another agent followed this skill, read `references/smoke-evaluation.md`.
+
+## Step 3: Follow import rules
+
+1. Import app-facing SDK APIs from `@heybox/hb-sdk`.
+2. Import protocol contracts from `@heybox/hb-sdk/protocol` only in host/runtime/protocol-maintenance code.
+3. Never import from internal hb-sdk implementation paths; only use the documented package entrypoints.
+4. Prefer named imports for focused code and the default `hbSDK` singleton for compact page-level examples.
+
+## Step 4: Implement iframe mini-program code
+
+1. Call `await ready()` or `await hbSDK.ready()` near page startup when the page uses SDK capabilities.
+2. Use `user.getInfo()` to read current login state without triggering login.
+3. Use `auth.login()` only when the user action requires login.
+4. Handle `HbMiniProgramSDKError` for bridge/runtime/protocol failures.
+5. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
+6. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
+7. Call `destroy()` on independent instances created by `createMiniProgramSDK()` when they are no longer needed.
+
+## Step 5: Use CLI workflows
+
+1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
+2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host.
+3. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
+4. Use `--port`, `--mock-port`, `--host`, and `--no-open` when the default Vite/mock ports, host, or browser opening behavior need to be controlled.
+5. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache.
+6. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+7. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
+8. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+9. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
+10. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+
+## Step 6: Preserve capability boundaries
+
+For iframe mini-program business code:
+
+1. Do not read or request tokens, cookies, phone numbers, or private credentials from the SDK.
+2. Do not expose raw share protocol fields, JS callbacks, activity reporting, custom buttons, post publishing, or upload-only flows.
+3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
+4. Do not pass raw host protocol fields through `network.request`; use only the public axios-like request config.
+5. Do not construct bridge envelopes, nonce logic, or raw `postMessage` calls.
+
+For CLI and local development:
+
+1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
+2. Do not use `hb-sdk login` as a workaround for iframe SDK authentication.
+3. Do not bypass `hb-sdk dev` by adding a second browser mock host.
+
+For host/runtime/protocol-maintenance code:
+
+1. Use `@heybox/hb-sdk/protocol` for shared constants and type contracts.
+2. Keep raw protocol details inside the host/runtime boundary; do not leak them into app-facing SDK examples or iframe business code.
+3. Keep bridge handshake and nonce behavior idempotent and compatible with existing SDK clients.
+
+## Step 7: Validate changes
+
+1. Run the nearest package tests and builds with repo-native commands when editing this repository.
+2. When modifying this repo's source skill at `packages/hb-sdk/skill`, run:
+   - `node packages/hb-sdk/skill/scripts/check-references.mjs`
+   - `node packages/hb-sdk/skill/scripts/validate-skill.mjs`
+   - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
+3. When modifying CLI, mock runtime, package exports, or package dependency direction, also run:
+   - `pnpm --filter @heybox/hb-sdk run check:boundary`
+   - `pnpm --filter @heybox/hb-sdk run test:unit`
+4. Inspect the generated zip before distribution:
+   - `unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'`
+5. Verify public payload sync before publishing:
+   - `pnpm --filter @heybox-spa/open run sync:agent-skills`
+   - `pnpm --filter @heybox-spa/open run check:agent-skills`

package/skill/references/api-protocol.md

@@ -0,0 +1,135 @@
+# Protocol API reference
+
+> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+
+## Sources
+
+- packages/hb-sdk/src/protocol.ts
+- packages/hb-sdk/README.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md
+
+## Contents
+
+- [Host/runtime-only warning](#hostruntime-only-warning)
+- [Public protocol entrypoint](#public-protocol-entrypoint)
+- [Protocol context](#protocol-context)
+- [Generated reference index](#generated-reference-index)
+## Host/runtime-only warning
+
+Use `@heybox/hb-sdk/protocol` only for parent-container runtime, bridge-server, protocol-contract, or `@heybox/hb-sdk-runtime` integration tasks. Iframe mini-program business code must use root SDK APIs and must not construct bridge envelopes, nonce handling, or raw `postMessage` flows.
+
+## Public protocol entrypoint
+
+```ts
+export {
+  MINI_PROGRAM_BRIDGE_NONCE_PARAM,
+  MINI_PROGRAM_MESSAGE_NAMESPACE,
+  MINI_PROGRAM_MESSAGE_VERSION,
+  SDK_HANDSHAKE_METHOD,
+} from './protocol/constants';
+export { isMiniProgramBridgeMessage } from './protocol/guards';
+export type {
+  MiniProgramBridgeError,
+  MiniProgramBridgeMessage,
+  MiniProgramBridgeMessageType,
+  MiniProgramEventHandler,
+  MiniProgramEventName,
+  MiniProgramEventPayloadMap,
+} from './protocol/types';
+export {
+  AUTH_LOGIN_METHOD,
+  MINI_PROGRAM_PROTOCOL_CAPABILITIES,
+  NETWORK_REQUEST_METHOD,
+  SHARE_SCREENSHOT_METHOD,
+  SHARE_SHOW_SHARE_MENU_METHOD,
+  STORAGE_GET_STORAGE_METHOD,
+  STORAGE_SET_STORAGE_METHOD,
+  USER_GET_INFO_METHOD,
+  VIEWPORT_GET_WINDOW_INFO_METHOD,
+} from './protocol/capabilities';
+export type {
+  MiniProgramAuthMethod,
+  MiniProgramBridgeMethod,
+  MiniProgramCapabilityDefinition,
+  MiniProgramCapabilityModule,
+  MiniProgramCapabilityPayload,
+  MiniProgramCapabilityPayloadMap,
+  MiniProgramCapabilityResult,
+  MiniProgramCapabilityResultMap,
+  MiniProgramCapabilityRisk,
+  MiniProgramNetworkMethod,
+  MiniProgramShareMethod,
+  MiniProgramStorageMethod,
+  MiniProgramUserMethod,
+  MiniProgramViewportMethod,
+} from './protocol/capabilities';
+export type { LoginPayload, LoginResult } from './modules/auth';
+export type {
+  GetUserInfoPayload,
+  GetUserInfoResult,
+  MiniProgramUserInfo,
+  MiniProgramUserInfoResult,
+} from './modules/user';
+export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
+export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';
+export type {
+  MiniProgramScreenshotOptions,
+  MiniProgramScreenshotRect,
+  MiniProgramShareChannel,
+  MiniProgramShowShareMenuOptions,
+} from './modules/share';
+export type {
+  GetStoragePayload,
+  GetStorageResult,
+  SetStoragePayload,
+} from './modules/storage';
+export type {
+  GetWindowInfoPayload,
+  GetWindowInfoResult,
+  MiniProgramSafeArea,
+  MiniProgramWindowInfoResult,
+} from './modules/viewport';
+export type {
+  MiniProgramNetworkHeaders,
+  MiniProgramNetworkParams,
+  MiniProgramNetworkRequestConfig,
+  MiniProgramNetworkRequestMethod,
+  MiniProgramNetworkResponse,
+  MiniProgramNetworkValidateStatus,
+  NetworkRequestPayload,
+  NetworkResponsePayload,
+} from './modules/network';
+```
+
+## Protocol context
+
+## SDK 与 Runtime
+
+`@heybox/hb-sdk` 跑在 iframe 内部，由外部小程序业务页面使用。`@heybox/hb-sdk-runtime` 跑在 iframe 外部，由黑盒宿主壳层使用，负责启动 iframe、注入 nonce、维护 bridge server、注册能力 handler、转发宿主生命周期与登录态变化。
+
+两者共享同一套 bridge 协议。协议字段、事件名或能力 payload 发生变化时，应按同一批次联动升级 SDK 与 runtime；不要只升级其中一侧后假定另一侧自动兼容。
+
+## Generated reference index
+
+
+# Reference
+
+Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
+
+| 导出面 | 说明 |
+| --- | --- |
+| [Root API](./root/README.md) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
+| [Protocol API](./protocol/README.md) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
+
+## 查询建议
+
+- 想查业务接入路径：先看 [Guide](../guide/README.md)。
+- 想查导出符号：从 Root API 或 Protocol API 进入对应分类页。
+- 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
+
+## 统计
+
+| 导出面 | Classes | Functions | Interfaces | Types | Constants |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Root API | 3 | 5 | 28 | 29 | 12 |
+| Protocol API | 0 | 1 | 20 | 29 | 13 |

package/skill/references/api-root.md

@@ -0,0 +1,346 @@
+# Root API reference
+
+> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+
+## Sources
+
+- packages/hb-sdk/package.json
+- packages/hb-sdk/src/index.ts
+- packages/hb-sdk/README.md
+
+## Contents
+
+- [Package metadata](#package-metadata)
+- [Public root entrypoint](#public-root-entrypoint)
+- [App-facing concepts](#app-facing-concepts)
+- [Public modules](#public-modules)
+## Package metadata
+
+- Package: `@heybox/hb-sdk`
+- Version at generation time: `0.2.0-alpha.1`
+- Public root export: `@heybox/hb-sdk`
+- Protocol export: `@heybox/hb-sdk/protocol`
+
+## Public root entrypoint
+
+```ts
+export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
+export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
+export type { MiniProgramRequester, MiniProgramSDKOptions } from './core/client';
+export { ready, on, off, auth, user, share, viewport, storage, network } from './core/singleton';
+export {
+  MINI_PROGRAM_BRIDGE_NONCE_PARAM,
+  MINI_PROGRAM_MESSAGE_NAMESPACE,
+  MINI_PROGRAM_MESSAGE_VERSION,
+  SDK_HANDSHAKE_METHOD,
+} from './protocol/constants';
+export { isMiniProgramBridgeMessage } from './protocol/guards';
+export type {
+  MiniProgramBridgeError,
+  MiniProgramBridgeMessage,
+  MiniProgramBridgeMessageType,
+  MiniProgramEventHandler,
+  MiniProgramEventName,
+  MiniProgramEventPayloadMap,
+} from './protocol/types';
+export {
+  AUTH_LOGIN_METHOD,
+  NETWORK_REQUEST_METHOD,
+  SHARE_SCREENSHOT_METHOD,
+  SHARE_SHOW_SHARE_MENU_METHOD,
+  STORAGE_GET_STORAGE_METHOD,
+  STORAGE_SET_STORAGE_METHOD,
+  USER_GET_INFO_METHOD,
+  VIEWPORT_GET_WINDOW_INFO_METHOD,
+} from './protocol/capabilities';
+export type {
+  MiniProgramAuthMethod,
+  MiniProgramBridgeMethod,
+  MiniProgramCapabilityDefinition,
+  MiniProgramCapabilityModule,
+  MiniProgramCapabilityPayload,
+  MiniProgramCapabilityPayloadMap,
+  MiniProgramCapabilityResult,
+  MiniProgramCapabilityResultMap,
+  MiniProgramCapabilityRisk,
+  MiniProgramNetworkMethod,
+  MiniProgramShareMethod,
+  MiniProgramStorageMethod,
+  MiniProgramUserMethod,
+  MiniProgramViewportMethod,
+} from './protocol/capabilities';
+export type { LoginPayload, LoginResult, MiniProgramAuthModule } from './modules/auth';
+export type {
+  GetUserInfoPayload,
+  GetUserInfoResult,
+  MiniProgramUserInfo,
+  MiniProgramUserInfoResult,
+  MiniProgramUserModule,
+} from './modules/user';
+export type {
+  MiniProgramScreenshotOptions,
+  MiniProgramScreenshotRect,
+  MiniProgramShareChannel,
+  MiniProgramShareModule,
+  MiniProgramShowShareMenuOptions,
+  ScreenshotPayload,
+  ScreenshotResult,
+  ShowShareMenuPayload,
+  ShowShareMenuResult,
+} from './modules/share';
+export type {
+  GetWindowInfoPayload,
+  GetWindowInfoResult,
+  MiniProgramSafeArea,
+  MiniProgramViewportModule,
+  MiniProgramWindowInfoResult,
+} from './modules/viewport';
+export type {
+  GetStoragePayload,
+  GetStorageResult,
+  MiniProgramStorageModule,
+  SetStoragePayload,
+} from './modules/storage';
+export type {
+  MiniProgramNetworkHeaders,
+  MiniProgramNetworkModule,
+  MiniProgramNetworkParams,
+  MiniProgramNetworkRequestConfig,
+  MiniProgramNetworkRequestMethod,
+  MiniProgramNetworkResponse,
+  MiniProgramNetworkValidateStatus,
+  NetworkRequestPayload,
+  NetworkResponsePayload,
+} from './modules/network';
+
+import { auth, network, off, on, ready, share, storage, viewport, user } from './core/singleton';
+
+const hbSDK = {
+  ready,
+  on,
+  off,
+  auth,
+  user,
+  share,
+  viewport,
+  storage,
+  network,
+};
+
+export default hbSDK;
+```
+
+## App-facing concepts
+
+## 快速开始
+
+创建一个新的外部小程序项目：
+
+```bash
+npx @heybox/hb-sdk create my-miniapp
+cd my-miniapp
+npm install
+npm run dev
+```
+
+模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+
+在已有项目中安装：
+
+```bash
+npm install @heybox/hb-sdk
+```
+
+然后在页面入口等待父容器 ready：
+
+```ts
+import hbSDK from '@heybox/hb-sdk';
+
+await hbSDK.ready();
+
+const user = await hbSDK.user.getInfo();
+
+if (user.isLogin) {
+  console.log(user.userInfo.nickname);
+}
+```
+
+也可以按需导入：
+
+```ts
+import { auth, ready, user } from '@heybox/hb-sdk';
+
+await ready();
+
+const currentUser = await user.getInfo();
+
+if (!currentUser.isLogin) {
+  await auth.login();
+}
+```
+
+## 运行环境
+
+SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注入 bridge nonce，并通过 `postMessage` 与 SDK 通信。普通浏览器直接打开小程序页面时通常无法完成握手；本地开发请优先使用：
+
+```bash
+npm run dev
+```
+
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。
+
+在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
+
+```json
+{
+  "scripts": {
+    "dev": "hb-sdk dev"
+  }
+}
+```
+
+## 错误处理
+
+bridge、父容器运行时、协议校验或能力调用失败时会抛出 `HbMiniProgramSDKError`，其中包含稳定的 `code`、开发者可读的 `message` 和可选 `data`。
+
+```ts
+import { HbMiniProgramSDKError, ready } from '@heybox/hb-sdk';
+
+try {
+  await ready();
+} catch (error) {
+  if (error instanceof HbMiniProgramSDKError) {
+    console.log(error.code, error.message, error.data);
+  }
+}
+```
+
+网络请求已完成但 HTTP 状态不满足 `validateStatus` 时会抛出 `HbMiniProgramNetworkError`，其 `response` 字段包含标准化后的 `status`、`headers`、`data` 和原始公共请求配置快照。
+
+## Public modules
+
+## 常用能力
+
+### 用户与登录
+
+`user.getInfo()` 只读取当前登录态，不会主动唤起登录。需要用户操作时再调用 `auth.login()`。
+
+```ts
+import { auth, user } from '@heybox/hb-sdk';
+
+const result = await user.getInfo();
+
+if (!result.isLogin) {
+  const loginResult = await auth.login();
+  console.log(loginResult.userInfo);
+}
+```
+
+SDK 只返回允许暴露给外部小程序的公开资料，不会返回 token、cookie、手机号或其他私有凭据。
+
+### 分享
+
+```ts
+import { share } from '@heybox/hb-sdk';
+
+await share.showShareMenu({
+  title: '我的小程序页面',
+  desc: '来自黑盒小程序的分享',
+  url: window.location.href,
+  imageUrl: 'https://imgheybox.max-c.com/demo.png',
+});
+```
+
+截图分享：
+
+```ts
+await share.screenshot({
+  delay: 100,
+  saveToAlbum: true,
+});
+```
+
+### 窗口信息
+
+```ts
+import { viewport } from '@heybox/hb-sdk';
+
+const windowInfo = await viewport.getWindowInfo();
+
+console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
+```
+
+### 隔离 Storage
+
+```ts
+import { storage } from '@heybox/hb-sdk';
+
+await storage.setStorage({
+  key: 'settings',
+  data: {
+    theme: 'dark',
+  },
+});
+
+const { data } = await storage.getStorage<{ theme: string }>({
+  key: 'settings',
+});
+```
+
+storage key 只允许 1-128 位字母、数字、下划线和连字符。父容器会按小程序维度隔离 key，外部小程序不能读写黑盒客户端全局 storage。
+
+### 网络请求
+
+`network.request()` 提供窄化的 axios-like 接口。SDK 只接受公开请求字段，真实请求由父容器运行时映射到宿主网络能力。
+
+```ts
+import { HbMiniProgramNetworkError, network } from '@heybox/hb-sdk';
+
+try {
+  const response = await network.request<{ ok: boolean }>({
+    url: 'https://api.example.com/demo',
+    method: 'GET',
+    headers: {
+      accept: 'application/json',
+    },
+  });
+
+  console.log(response.status, response.data.ok);
+} catch (error) {
+  if (error instanceof HbMiniProgramNetworkError) {
+    console.log(error.response.status, error.response.data);
+  }
+}
+```
+
+默认只有 `2xx` 会 resolve；`4xx/5xx` 这类已完成 HTTP 响应会抛出 `HbMiniProgramNetworkError`。可以用 `validateStatus` 调整 SDK 本地判定逻辑，函数不会跨 bridge 传给父容器。
+
+```ts
+await network.request({
+  url: 'https://api.example.com/demo',
+  validateStatus: status => status < 500,
+});
+```
+
+支持的 HTTP method 为 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`。
+
+## 生命周期事件
+
+使用 `on()` 监听父容器派发的小程序事件。`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+
+```ts
+import { on } from '@heybox/hb-sdk';
+
+const unsubscribeShow = on('show', payload => {
+  console.log('页面展示', payload.timestamp, payload.source);
+});
+
+const unsubscribeAuth = on('authChange', payload => {
+  console.log('登录态变化', payload.isLogin, payload.userInfo);
+});
+
+unsubscribeShow();
+unsubscribeAuth();
+```
+
+当前可监听事件包括 `launch`、`ready`、`show`、`hide`、`unload`、`error`、`authChange`。