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

package/skill/references/recipes.md

@@ -0,0 +1,374 @@
+# Recipes
+
+> 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
+
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md
+
+## Contents
+
+- [Quick start](#quick-start)
+- [User and login](#user-and-login)
+- [Lifecycle events](#lifecycle-events)
+- [Error handling](#error-handling)
+- [Login gate recipe](#login-gate-recipe)
+- [Custom instance recipe](#custom-instance-recipe)
+## Quick start
+
+
+# 快速开始
+
+如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
+
+```ts
+import hbSDK from '@heybox/hb-sdk'
+
+async function bootstrap() {
+  await hbSDK.ready()
+
+  const result = await hbSDK.user.getInfo()
+  if (result.isLogin && result.userInfo) {
+    console.log(result.userInfo.nickname)
+    return
+  }
+
+  console.log('当前用户未登录')
+}
+
+bootstrap()
+```
+
+## 推荐业务写法
+
+业务页通常还需要监听登录态变化：
+
+```ts
+import hbSDK from '@heybox/hb-sdk'
+
+const stopAuthChange = hbSDK.on('authChange', result => {
+  if (result.isLogin) {
+    console.log('用户已登录', result.userInfo?.heybox_id)
+  }
+})
+
+await hbSDK.ready()
+
+const result = await hbSDK.user.getInfo()
+if (!result.isLogin) {
+  await hbSDK.auth.login()
+}
+
+// 页面卸载时清理监听
+stopAuthChange()
+```
+
+## ready 的含义
+
+`ready()` 表示 SDK 已完成与父容器的握手，可以安全调用开放能力。SDK 在收到 `ready` 前会自动重试握手；如果超过总超时时间仍未成功，会抛出 `READY_TIMEOUT`。它不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
+
+## 默认单例适合什么场景
+
+默认单例适合一个页面只有一个 SDK 上下文的情况。大多数小程序页面都应该使用默认单例，因为它可以避免重复握手和重复维护事件监听。
+
+需要控制 `timeout`、注入测试 window 或隔离多个上下文时，再使用 [独立实例](../recipes/custom-instance.md)。
+
+## User and login
+
+
+# 用户与登录
+
+用户与授权模块当前分工：
+
+- `user.getInfo()`：静默读取当前登录态与公开基础资料。
+- `auth.login()`：唤起黑盒登录流程，并返回登录后的最新公开用户资料。
+
+## 静默读取用户信息
+
+`getInfo` 不会触发登录流程。用户未登录时，返回 `isLogin: false` 和 `userInfo: null`。
+
+```ts
+import { ready, user } from '@heybox/hb-sdk'
+
+await ready()
+
+const result = await user.getInfo()
+if (result.isLogin) {
+  console.log(result.userInfo?.nickname)
+}
+```
+
+## 主动唤起登录
+
+当业务动作必须登录才能继续时，再调用 `login`。
+
+```ts
+import hbSDK from '@heybox/hb-sdk'
+
+async function ensureLogin() {
+  await hbSDK.ready()
+
+  const current = await hbSDK.user.getInfo()
+  if (current.isLogin) {
+    return current.userInfo
+  }
+
+  const next = await hbSDK.auth.login()
+  return next.userInfo
+}
+```
+
+## 暴露字段
+
+SDK 只暴露允许给外部小程序读取的公开字段：
+
+| 字段        | 类型     | 说明         |
+| ----------- | -------- | ------------ |
+| `heybox_id` | `string` | 黑盒用户 ID  |
+| `nickname`  | `string` | 用户昵称     |
+| `avatar`    | `string` | 用户头像 URL |
+
+不会暴露 token、cookie、手机号或任何可用于调用主站私有接口的凭据。
+
+## 监听登录态变化
+
+如果页面上同时存在登录按钮、权限态 UI 和业务数据，建议监听 `authChange`。
+
+```ts
+import { on } from '@heybox/hb-sdk'
+
+const stop = on('authChange', result => {
+  if (result.isLogin) {
+    console.log('登录态更新', result.userInfo?.heybox_id)
+  }
+})
+```
+
+## Lifecycle events
+
+
+# 事件与生命周期
+
+SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
+
+```ts
+import { on, off } from '@heybox/hb-sdk'
+
+function handleShow(payload: { timestamp: number; source?: string }) {
+  console.log('show from', payload.source)
+}
+
+on('show', handleShow)
+off('show', handleShow)
+```
+
+`on` 也会返回取消监听函数，推荐在组件卸载时调用：
+
+```ts
+import { on } from '@heybox/hb-sdk'
+
+const stop = on('hide', () => {
+  console.log('小程序页面隐藏')
+})
+
+stop()
+```
+
+## 事件列表
+
+| 事件         | 触发时机                 | 典型用途           |
+| ------------ | ------------------------ | ------------------ |
+| `launch`     | 小程序首次完成握手并启动 | 初始化一次性数据   |
+| `ready`      | SDK 可安全调用开放能力   | 标记 bridge 可用   |
+| `show`       | 小程序页面展示           | 刷新可见态数据     |
+| `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
+| `unload`     | 小程序页面即将卸载       | 清理资源           |
+| `error`      | 父容器或开放能力运行异常 | 统一错误上报       |
+| `authChange` | 登录状态变化             | 刷新用户信息和权限 |
+
+完整载荷与事件名见：
+
+- [MiniProgramEventPayloadMap](../reference/protocol/interfaces/MiniProgramEventPayloadMap.md)
+- [MiniProgramEventName](../reference/protocol/types/README.md#miniprogrameventname)
+
+## 生命周期建议
+
+- 初始化开放能力前先 `await ready()`。
+- UI 可见性相关逻辑放在 `show`、`hide`。
+- 用户状态不要只在页面加载时读一次，登录入口附近要监听 `authChange`。
+- 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
+
+## Error handling
+
+
+# 错误处理
+
+SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
+
+```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)
+  }
+}
+```
+
+## SDK 内置错误
+
+| code              | 场景                              | 建议处理                           |
+| ----------------- | --------------------------------- | ---------------------------------- |
+| `NOT_IN_IFRAME`   | 当前页面不在小程序沙盒 iframe 中  | 提示运行环境错误，检查父容器接入   |
+| `MISSING_NONCE`   | URL 中缺少 `hb_mini_bridge_nonce` | 检查父容器 URL 注入逻辑            |
+| `READY_TIMEOUT`   | SDK 握手超时                      | 检查父容器是否幂等响应重试的 `sdk.handshake` |
+| `REQUEST_TIMEOUT` | 开放能力调用超时                  | 提示重试，并上报 method            |
+| `SDK_DESTROYED`   | SDK 已销毁但仍有请求未完成        | 检查销毁时机和并发请求             |
+
+父容器返回失败响应时，SDK 也会包装成 `HbMiniProgramSDKError`，此时 `code` 由父容器开放能力定义。
+
+## 业务层建议
+
+```ts
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+
+async function loadUser() {
+  try {
+    await hbSDK.ready()
+    return await hbSDK.user.getInfo()
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError) {
+      reportSDKError(error.code, error.message, error.data)
+      return { isLogin: false, userInfo: null }
+    }
+
+    throw error
+  }
+}
+
+function reportSDKError(code: string, message: string, data?: unknown) {
+  console.log('[hb-sdk]', code, message, data)
+}
+```
+
+## 超时时间
+
+默认超时时间是 10000ms。需要调整时，使用独立实例：
+
+```ts
+import { createMiniProgramSDK } from '@heybox/hb-sdk'
+
+const sdk = createMiniProgramSDK({
+  timeout: 15000,
+})
+```
+
+## Login gate recipe
+
+
+# 登录门禁
+
+当业务动作必须登录后才能继续时，可以把登录态判断收敛成 `ensureLogin`。
+
+```ts
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+import type { MiniProgramUserInfo } from '@heybox/hb-sdk'
+
+export async function ensureLogin(): Promise<MiniProgramUserInfo | null> {
+  try {
+    await hbSDK.ready()
+
+    const current = await hbSDK.user.getInfo()
+    if (current.isLogin) {
+      return current.userInfo
+    }
+
+    const next = await hbSDK.auth.login()
+    return next.userInfo
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError) {
+      console.log('[hb-sdk]', error.code, error.message)
+      return null
+    }
+
+    throw error
+  }
+}
+```
+
+业务按钮里使用：
+
+```ts
+async function handleSubmit() {
+  const userInfo = await ensureLogin()
+  if (!userInfo) {
+    return
+  }
+
+  // 继续执行需要登录的业务动作
+}
+```
+
+## 注意事项
+
+- 进入页面时可以用 `getInfo` 静默初始化 UI。
+- 用户主动点击登录、提交、收藏等动作时，再调用 `login`。
+- 登录态变化后，父容器应派发 `authChange`，页面可据此刷新用户相关 UI。
+
+## Custom instance recipe
+
+
+# 独立 SDK 实例
+
+大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。
+
+## 自定义 timeout
+
+```ts
+import { createMiniProgramSDK } from '@heybox/hb-sdk'
+
+const sdk = createMiniProgramSDK({
+  timeout: 15000,
+})
+
+await sdk.ready()
+```
+
+## 测试环境注入 window
+
+单元测试可以注入 `selfWindow`、`targetWindow` 和 `nonce`，避免依赖真实 iframe。
+
+```ts
+import { createMiniProgramSDK } from '@heybox/hb-sdk'
+
+const sdk = createMiniProgramSDK({
+  nonce: 'test_nonce',
+  selfWindow: window,
+  targetWindow: null,
+})
+
+sdk.destroy()
+```
+
+## 清理实例
+
+独立实例不再使用时调用 `destroy`。
+
+```ts
+const sdk = createMiniProgramSDK()
+
+try {
+  await sdk.ready()
+} finally {
+  sdk.destroy()
+}
+```
+
+`destroy` 会移除 message 监听，并拒绝尚未完成的请求。销毁后不要继续复用该实例。

package/skill/references/safety-boundaries.md

@@ -0,0 +1,28 @@
+# Safety boundaries
+
+> 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/README.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md
+## Required boundaries
+
+## 能力边界
+
+- 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
+- `user.getInfo()` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
+- 分享、截图、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
+- `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
+- `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
+- 使用 `createMiniProgramSDK()` 创建独立实例后，不再需要时应调用 `destroy()`。
+
+## Agent rules
+
+- Do not instruct mini-program code to read, extract, forward, store, or depend on token, cookie, phone number, or private credentials.
+- Negative safety statements that explain the SDK does not expose token/cookie/private credentials are correct and should be preserved.
+- Do not use raw share protocol fields, JS callbacks, activity reporting, post publishing, custom buttons, or upload-only flows.
+- Do not use storage delete, clear, info listing, V2, or global Heybox client storage access.
+- Do not pass host-only protocol fields through `network.request`.
+- Do not build raw `postMessage` bridge flows in iframe business code.
+- Do not import from internal hb-sdk implementation paths; only use documented package entrypoints.

package/skill/references/smoke-evaluation.md

@@ -0,0 +1,24 @@
+# hb-sdk Skill Smoke Evaluation Template
+
+Use this template when evaluating whether an agent followed the hb-sdk skill.
+
+## Prompt
+
+<copy the tested user prompt>
+
+## Expected evidence
+
+- [ ] Uses `@heybox/hb-sdk` root imports for iframe business code.
+- [ ] Uses `@heybox/hb-sdk/protocol` only for host/runtime/protocol tasks.
+- [ ] Uses `hb-sdk create`, `hb-sdk dev`, or `hb-sdk login` correctly for CLI tasks.
+- [ ] Calls or relies on `ready()` before capability calls.
+- [ ] Handles login, null user, and SDK errors safely.
+- [ ] Keeps CLI login cache separate from iframe SDK login state.
+- [ ] Avoids deep imports, token/cookie access, raw bridge mutation, second mock runtimes, and unsupported capabilities.
+
+## Verdict
+
+- Pass/Fail:
+- Missing evidence:
+- Unsafe output:
+- Suggested skill improvement:

package/skill/scripts/check-references.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+
+const scriptPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'sync-references.mjs');
+const result = spawnSync(process.execPath, [scriptPath, '--check'], {
+  cwd: process.cwd(),
+  encoding: 'utf8',
+  stdio: 'inherit',
+});
+
+process.exit(result.status ?? 1);

package/skill/scripts/package-skill.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { HB_SDK_SKILL_NAME } from './skill-metadata.mjs';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const skillDir = path.resolve(scriptDir, '..');
+const packageRoot = path.resolve(skillDir, '..');
+const skillName = HB_SDK_SKILL_NAME;
+const repoRoot = findRepoRoot(process.cwd()) ?? packageRoot;
+const zipPath = path.join(packageRoot, `${skillName}.zip`);
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    if (existsSync(path.join(dir, 'package.json')) && existsSync(path.join(dir, 'packages/hb-sdk/package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+if (!existsSync(path.join(skillDir, 'SKILL.md'))) {
+  console.error(`Missing ${path.relative(repoRoot, path.join(skillDir, 'SKILL.md'))}.`);
+  process.exit(1);
+}
+
+if (existsSync(zipPath)) rmSync(zipPath);
+
+const tempRoot = mkdtempSync(path.join(tmpdir(), 'hb-sdk-skill-'));
+const packagedSkillRoot = path.join(tempRoot, skillName);
+
+try {
+  cpSync(skillDir, packagedSkillRoot, { recursive: true });
+
+  const result = spawnSync(
+    'zip',
+    ['-r', zipPath, skillName, '-x', `${skillName}/README.md`, '-x', `${skillName}/**/.DS_Store`],
+    {
+      cwd: tempRoot,
+      encoding: 'utf8',
+    },
+  );
+
+  if (result.status !== 0) {
+    process.stderr.write(result.stderr || result.stdout);
+    process.exit(result.status ?? 1);
+  }
+
+  console.error(result.stdout.trim());
+  console.log(JSON.stringify({ ok: true, zip: path.relative(repoRoot, zipPath).split(path.sep).join('/') }));
+} finally {
+  rmSync(tempRoot, { recursive: true, force: true });
+}

package/skill/scripts/package-skill.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "Packaging hb-sdk skill" >&2
+node "$SCRIPT_DIR/package-skill.mjs"

package/skill/scripts/skill-metadata.mjs

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+
+export const HB_SDK_SKILL_NAME = 'hb-sdk';
+export const HB_SDK_PACKAGE_NAME = '@heybox/hb-sdk';
+export const HB_SDK_SKILL_SOURCE = 'https://open.xiaoheihe.cn/agent-skills/hb-sdk';
+
+export function createSkillContentHash(fileEntries) {
+  const hash = createHash('sha256');
+
+  for (const entry of [...fileEntries].sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(entry.path);
+    hash.update('\0');
+    hash.update(entry.content);
+    hash.update('\0');
+  }
+
+  return {
+    hex: hash.digest('hex'),
+  };
+}
+
+export function createSkillManifest({ contentHash, sdkVersion }) {
+  const shortHash = contentHash.hex.slice(0, 12);
+
+  return {
+    name: HB_SDK_SKILL_NAME,
+    skillVersion: `${sdkVersion}+skill.${shortHash}`,
+    sdk: {
+      package: HB_SDK_PACKAGE_NAME,
+      version: sdkVersion,
+      compatibility: sdkVersion,
+    },
+    source: HB_SDK_SKILL_SOURCE,
+    integrity: `sha256-${contentHash.hex}`,
+  };
+}
+
+export function validateSkillManifest({ manifest, sdkVersion }) {
+  const errors = [];
+
+  if (manifest?.name !== HB_SDK_SKILL_NAME) {
+    errors.push(`skill.json name must be \`${HB_SDK_SKILL_NAME}\`.`);
+  }
+
+  if (manifest?.sdk?.package !== HB_SDK_PACKAGE_NAME) {
+    errors.push(`skill.json sdk.package must be \`${HB_SDK_PACKAGE_NAME}\`.`);
+  }
+
+  if (manifest?.sdk?.version !== sdkVersion) {
+    errors.push('skill.json sdk.version must match packages/hb-sdk/package.json version.');
+  }
+
+  if (manifest?.sdk?.compatibility !== sdkVersion) {
+    errors.push('skill.json sdk.compatibility must match packages/hb-sdk/package.json version.');
+  }
+
+  if (typeof manifest?.skillVersion !== 'string' || !manifest.skillVersion.startsWith(`${sdkVersion}+skill.`)) {
+    errors.push('skill.json skillVersion must be derived from the current SDK version.');
+  }
+
+  if (manifest?.source !== HB_SDK_SKILL_SOURCE) {
+    errors.push('skill.json source must be the public hb-sdk skill URL.');
+  }
+
+  if (typeof manifest?.integrity !== 'string' || !/^sha256-[0-9a-f]{64}$/.test(manifest.integrity)) {
+    errors.push('skill.json integrity must be a sha256 hex digest.');
+  }
+
+  return errors;
+}
+
+export function normalizeSkillManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}