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

package/skill/references/api-root.md

@@ -0,0 +1,474 @@
+# 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/src/vite/index.ts
+- packages/hb-sdk/README.md
+
+## Contents
+
+- [Package metadata](#package-metadata)
+- [Public root entrypoint](#public-root-entrypoint)
+- [Vite plugin export](#vite-plugin-export)
+- [App-facing concepts](#app-facing-concepts)
+- [Public modules](#public-modules)
+## Package metadata
+
+- Package: `@heybox/hb-sdk`
+- Version at generation time: `0.2.0-alpha.2`
+- Public root export: `@heybox/hb-sdk`
+- Protocol export: `@heybox/hb-sdk/protocol`
+- Vite plugin export: `@heybox/hb-sdk/vite`
+
+## 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;
+```
+
+## Vite plugin export
+
+Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe mini-program business code.
+
+```ts
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const TEMPLATE_VERSION = '0.0.0';
+const SEMVER_LIKE_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const TEMPLATE_VERSION_ERROR = '@heybox/hb-sdk 提示：请把 package.json.version 从模板默认的 0.0.0 改成实际版本号再发布';
+
+type MiniappManifestPlugin = {
+  name: string;
+  apply: 'build';
+  configResolved: (resolved: MiniappManifestResolvedConfig) => void;
+  writeBundle: (this: MiniappManifestPluginContext) => void;
+};
+
+interface MiniappManifestPluginContext {
+  warn: (message: string) => void;
+}
+
+interface MiniappManifestResolvedConfig {
+  root: string;
+  build: {
+    outDir: string;
+  };
+}
+
+export function miniappManifest(): MiniappManifestPlugin {
+  let root = process.cwd();
+  let outDir = 'dist';
+
+  return {
+    name: 'heybox-miniapp-manifest',
+    apply: 'build',
+    configResolved(resolved) {
+      root = resolved.root;
+      outDir = resolved.build.outDir;
+    },
+    writeBundle() {
+      const version = readMiniappVersion(root);
+
+      if (!SEMVER_LIKE_RE.test(version)) {
+        this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+      }
+
+      const manifestPath = path.resolve(root, outDir, 'manifest.json');
+      mkdirSync(path.dirname(manifestPath), { recursive: true });
+      writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+    },
+  };
+}
+
+function readMiniappVersion(root: string): string {
+  const packageJsonPath = path.join(root, 'package.json');
+  let content: string;
+
+  try {
+    content = readFileSync(packageJsonPath, 'utf8');
+  } catch (error) {
+    throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+  }
+
+  let packageJson: { version?: unknown };
+
+  try {
+    packageJson = JSON.parse(content) as { version?: unknown };
+  } catch (error) {
+    throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
+  }
+
+  if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+    throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
+  }
+
+  const version = packageJson.version.trim();
+
+  if (version === TEMPLATE_VERSION) {
+    throw new Error(TEMPLATE_VERSION_ERROR);
+  }
+
+  return version;
+}
+
+function formatReason(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return String(error);
+}
+```
+
+## Manifest
+
+`@heybox/hb-sdk/vite` 提供构建时插件 `miniappManifest()`。Vite 项目完成 `vite build` 后，会在输出目录写入 `manifest.json`：
+
+```json
+{
+  "version": "1.2.3"
+}
+```
+
+`version` 来自小程序项目自身的 `package.json.version`。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
+
+```ts
+import { miniappManifest } from '@heybox/hb-sdk/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [miniappManifest()],
+});
+```
+
+失败与警告语义：
+
+- 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
+- `package.json.version` 不是非空字符串：`vite build` 直接失败。
+- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 直接失败，并提示把模板默认版本改成实际版本号再发布。
+- 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
+
+`manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
+
+## 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`。