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

package/dist/protocol.cjs.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/** 小程序沙盒通信命名空间，父容器与 iframe 内 SDK 必须保持一致。 */
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/** 小程序沙盒通信协议版本。 */
+const MINI_PROGRAM_MESSAGE_VERSION = 1;
+/** 父容器注入到小程序 URL 上的通信 nonce 参数名。 */
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+/** SDK 初始化时发给父容器的握手方法名。 */
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+
+/**
+ * 判断未知数据是否符合小程序 bridge 消息信封。
+ *
+ * @param value 待判断的未知数据。
+ * @returns 当数据满足小程序 bridge 消息基础结构时返回 `true`。
+ */
+function isMiniProgramBridgeMessage(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const message = value;
+    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
+        message.version === MINI_PROGRAM_MESSAGE_VERSION &&
+        typeof message.nonce === 'string' &&
+        typeof message.type === 'string');
+}
+
+/**
+ * 登录授权能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const AUTH_LOGIN_METHOD = 'auth.login';
+/**
+ * 用户信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const USER_GET_INFO_METHOD = 'user.getInfo';
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
+/**
+ * 截图分享能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+/**
+ * 视口窗口信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
+/**
+ * 读取小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
+/**
+ * 写入小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
+/**
+ * 发起网络请求能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const NETWORK_REQUEST_METHOD = 'network.request';
+/**
+ * 小程序开放能力目录。
+ *
+ * @remarks
+ * 新增 bridge method 时应先更新这里，再分别补齐 SDK 模块、runtime handler 与测试。
+ */
+const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
+    {
+        method: AUTH_LOGIN_METHOD,
+        module: 'auth',
+        capability: AUTH_LOGIN_METHOD,
+        permission: 'auth.login',
+        risk: 'medium',
+    },
+    {
+        method: USER_GET_INFO_METHOD,
+        module: 'user',
+        capability: USER_GET_INFO_METHOD,
+        permission: 'user.getInfo',
+        risk: 'medium',
+    },
+    {
+        method: SHARE_SHOW_SHARE_MENU_METHOD,
+        module: 'share',
+        capability: SHARE_SHOW_SHARE_MENU_METHOD,
+        permission: 'share.basic',
+        risk: 'low',
+    },
+    {
+        method: SHARE_SCREENSHOT_METHOD,
+        module: 'share',
+        capability: SHARE_SCREENSHOT_METHOD,
+        permission: 'share.screenshot',
+        risk: 'medium',
+    },
+    {
+        method: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        permission: 'viewport.windowInfo',
+        risk: 'low',
+    },
+    {
+        method: STORAGE_GET_STORAGE_METHOD,
+        module: 'storage',
+        capability: STORAGE_GET_STORAGE_METHOD,
+        permission: 'storage.read',
+        risk: 'low',
+    },
+    {
+        method: STORAGE_SET_STORAGE_METHOD,
+        module: 'storage',
+        capability: STORAGE_SET_STORAGE_METHOD,
+        permission: 'storage.write',
+        risk: 'medium',
+    },
+    {
+        method: NETWORK_REQUEST_METHOD,
+        module: 'network',
+        capability: NETWORK_REQUEST_METHOD,
+        permission: 'network.request',
+        risk: 'high',
+    },
+];
+
+exports.AUTH_LOGIN_METHOD = AUTH_LOGIN_METHOD;
+exports.MINI_PROGRAM_BRIDGE_NONCE_PARAM = MINI_PROGRAM_BRIDGE_NONCE_PARAM;
+exports.MINI_PROGRAM_MESSAGE_NAMESPACE = MINI_PROGRAM_MESSAGE_NAMESPACE;
+exports.MINI_PROGRAM_MESSAGE_VERSION = MINI_PROGRAM_MESSAGE_VERSION;
+exports.MINI_PROGRAM_PROTOCOL_CAPABILITIES = MINI_PROGRAM_PROTOCOL_CAPABILITIES;
+exports.NETWORK_REQUEST_METHOD = NETWORK_REQUEST_METHOD;
+exports.SDK_HANDSHAKE_METHOD = SDK_HANDSHAKE_METHOD;
+exports.SHARE_SCREENSHOT_METHOD = SHARE_SCREENSHOT_METHOD;
+exports.SHARE_SHOW_SHARE_MENU_METHOD = SHARE_SHOW_SHARE_MENU_METHOD;
+exports.STORAGE_GET_STORAGE_METHOD = STORAGE_GET_STORAGE_METHOD;
+exports.STORAGE_SET_STORAGE_METHOD = STORAGE_SET_STORAGE_METHOD;
+exports.USER_GET_INFO_METHOD = USER_GET_INFO_METHOD;
+exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
+exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;

package/dist/protocol.esm.js

@@ -0,0 +1,148 @@
+/** 小程序沙盒通信命名空间，父容器与 iframe 内 SDK 必须保持一致。 */
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/** 小程序沙盒通信协议版本。 */
+const MINI_PROGRAM_MESSAGE_VERSION = 1;
+/** 父容器注入到小程序 URL 上的通信 nonce 参数名。 */
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+/** SDK 初始化时发给父容器的握手方法名。 */
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+
+/**
+ * 判断未知数据是否符合小程序 bridge 消息信封。
+ *
+ * @param value 待判断的未知数据。
+ * @returns 当数据满足小程序 bridge 消息基础结构时返回 `true`。
+ */
+function isMiniProgramBridgeMessage(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const message = value;
+    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
+        message.version === MINI_PROGRAM_MESSAGE_VERSION &&
+        typeof message.nonce === 'string' &&
+        typeof message.type === 'string');
+}
+
+/**
+ * 登录授权能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const AUTH_LOGIN_METHOD = 'auth.login';
+/**
+ * 用户信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const USER_GET_INFO_METHOD = 'user.getInfo';
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
+/**
+ * 截图分享能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+/**
+ * 视口窗口信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
+/**
+ * 读取小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
+/**
+ * 写入小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
+/**
+ * 发起网络请求能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+const NETWORK_REQUEST_METHOD = 'network.request';
+/**
+ * 小程序开放能力目录。
+ *
+ * @remarks
+ * 新增 bridge method 时应先更新这里，再分别补齐 SDK 模块、runtime handler 与测试。
+ */
+const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
+    {
+        method: AUTH_LOGIN_METHOD,
+        module: 'auth',
+        capability: AUTH_LOGIN_METHOD,
+        permission: 'auth.login',
+        risk: 'medium',
+    },
+    {
+        method: USER_GET_INFO_METHOD,
+        module: 'user',
+        capability: USER_GET_INFO_METHOD,
+        permission: 'user.getInfo',
+        risk: 'medium',
+    },
+    {
+        method: SHARE_SHOW_SHARE_MENU_METHOD,
+        module: 'share',
+        capability: SHARE_SHOW_SHARE_MENU_METHOD,
+        permission: 'share.basic',
+        risk: 'low',
+    },
+    {
+        method: SHARE_SCREENSHOT_METHOD,
+        module: 'share',
+        capability: SHARE_SCREENSHOT_METHOD,
+        permission: 'share.screenshot',
+        risk: 'medium',
+    },
+    {
+        method: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        permission: 'viewport.windowInfo',
+        risk: 'low',
+    },
+    {
+        method: STORAGE_GET_STORAGE_METHOD,
+        module: 'storage',
+        capability: STORAGE_GET_STORAGE_METHOD,
+        permission: 'storage.read',
+        risk: 'low',
+    },
+    {
+        method: STORAGE_SET_STORAGE_METHOD,
+        module: 'storage',
+        capability: STORAGE_SET_STORAGE_METHOD,
+        permission: 'storage.write',
+        risk: 'medium',
+    },
+    {
+        method: NETWORK_REQUEST_METHOD,
+        module: 'network',
+        capability: NETWORK_REQUEST_METHOD,
+        permission: 'network.request',
+        risk: 'high',
+    },
+];
+
+export { AUTH_LOGIN_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NETWORK_REQUEST_METHOD, SDK_HANDSHAKE_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, isMiniProgramBridgeMessage };

package/dist/templates/vue3-vite-ts/.gitignore.ejs

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+*.local
+.DS_Store

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -0,0 +1,42 @@
+# <%= projectName %>
+
+这是通过 `hb-sdk create` 生成的黑盒外部小程序开发模板。项目使用 Vue 3、Vite、TypeScript 和 `@heybox/hb-sdk`。
+
+## 使用命令
+
+```bash
+npm install
+npm run dev
+npm run typecheck
+npm run test:unit
+npm run build
+```
+
+## 开发模式
+
+- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+- `npm run build`：先执行 TypeScript 检查，再构建生产产物。
+
+## 更多能力
+
+模板页面只保留最小接入示例。其他常用能力可以直接从 `@heybox/hb-sdk` 调用：
+
+```ts
+import hbSDK from '@heybox/hb-sdk';
+
+await hbSDK.share.showShareMenu({
+  title: '<%= projectName %>',
+  desc: '分享描述',
+  url: window.location.href,
+});
+
+await hbSDK.storage.setStorage({
+  key: 'settings',
+  data: { theme: 'dark' },
+});
+
+const response = await hbSDK.network.request({
+  method: 'GET',
+  url: 'https://jsonplaceholder.typicode.com/todos/1',
+});
+```

package/dist/templates/vue3-vite-ts/index.html.ejs

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/dist/templates/vue3-vite-ts/package.json.ejs

@@ -0,0 +1,28 @@
+{
+  "name": "<%= packageName %>",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "hb-sdk dev",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "vue-tsc --noEmit",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
+  "dependencies": {
+    "@heybox/hb-sdk": "^<%= sdkVersion %>",
+    "vue": "^3.5.34"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "@vitejs/plugin-vue": "^6.0.6",
+    "@vue/test-utils": "^2.4.10",
+    "happy-dom": "^20.9.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.12",
+    "vitest": "^4.1.6",
+    "vue-tsc": "^3.2.9"
+  }
+}

package/dist/templates/vue3-vite-ts/src/App.vue

@@ -0,0 +1,63 @@
+<template>
+  <main class="page">
+    <section class="card">
+      <p class="eyebrow">Heybox Mini Program</p>
+      <h1><%= projectName %></h1>
+      <p class="intro">
+        这个模板只保留最小接入示例：等待 SDK ready、读取用户信息，并在需要时唤起登录。
+      </p>
+
+      <p class="status" data-testid="status">{{ status }}</p>
+
+      <button type="button" :disabled="loading" data-testid="login" @click="login">
+        登录并刷新用户信息
+      </button>
+
+      <pre data-testid="output">{{ output }}</pre>
+    </section>
+  </main>
+</template>
+
+<script setup lang="ts">
+import hbSDK from '@heybox/hb-sdk';
+import { onMounted, ref } from 'vue';
+
+const loading = ref(false);
+const status = ref('正在连接 SDK...');
+const output = ref('等待 user.getInfo 返回结果。');
+
+onMounted(() => {
+  void loadUserInfo();
+});
+
+async function loadUserInfo() {
+  await runSdkAction('user.getInfo', async () => {
+    await hbSDK.ready();
+    return hbSDK.user.getInfo();
+  });
+}
+
+async function login() {
+  await runSdkAction('auth.login', () => hbSDK.auth.login());
+}
+
+async function runSdkAction(label: string, action: () => Promise<unknown>) {
+  loading.value = true;
+  status.value = `${label} 调用中...`;
+
+  try {
+    const result = await action();
+    status.value = `${label} 调用成功`;
+    output.value = JSON.stringify(result, null, 2);
+  } catch (error) {
+    status.value = `${label} 调用失败`;
+    output.value = readErrorMessage(error);
+  } finally {
+    loading.value = false;
+  }
+}
+
+function readErrorMessage(error: unknown) {
+  return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+</script>

package/dist/templates/vue3-vite-ts/src/__tests__/App.spec.ts

@@ -0,0 +1,67 @@
+import { flushPromises, mount } from '@vue/test-utils';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import App from '../App.vue';
+
+const sdkMock = vi.hoisted(() => ({
+  authLogin: vi.fn(),
+  ready: vi.fn(),
+  userGetInfo: vi.fn(),
+}));
+
+vi.mock('@heybox/hb-sdk', () => ({
+  default: {
+    auth: {
+      login: sdkMock.authLogin,
+    },
+    ready: sdkMock.ready,
+    user: {
+      getInfo: sdkMock.userGetInfo,
+    },
+  },
+}));
+
+describe('App', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    sdkMock.ready.mockResolvedValue(undefined);
+    sdkMock.userGetInfo.mockResolvedValue({
+      isLogin: true,
+      userInfo: {
+        avatar: '',
+        heybox_id: '10001',
+        nickname: '模板用户',
+      },
+    });
+    sdkMock.authLogin.mockResolvedValue({
+      isLogin: true,
+      userInfo: {
+        avatar: '',
+        heybox_id: '10002',
+        nickname: '登录用户',
+      },
+    });
+  });
+
+  it('connects to hb-sdk and renders user info', async () => {
+    const wrapper = mount(App);
+    await flushPromises();
+
+    expect(sdkMock.ready).toHaveBeenCalledTimes(1);
+    expect(sdkMock.userGetInfo).toHaveBeenCalledTimes(1);
+    expect(wrapper.get('[data-testid="status"]').text()).toBe('user.getInfo 调用成功');
+    expect(wrapper.get('[data-testid="output"]').text()).toContain('模板用户');
+  });
+
+  it('logs in and refreshes the output', async () => {
+    const wrapper = mount(App);
+    await flushPromises();
+
+    await wrapper.get('[data-testid="login"]').trigger('click');
+    await flushPromises();
+
+    expect(sdkMock.authLogin).toHaveBeenCalledTimes(1);
+    expect(wrapper.get('[data-testid="status"]').text()).toBe('auth.login 调用成功');
+    expect(wrapper.get('[data-testid="output"]').text()).toContain('登录用户');
+  });
+});

package/dist/templates/vue3-vite-ts/src/main.ts

@@ -0,0 +1,5 @@
+import { createApp } from 'vue';
+import App from './App.vue';
+import './styles.css';
+
+createApp(App).mount('#app');

package/dist/templates/vue3-vite-ts/src/styles.css

@@ -0,0 +1,60 @@
+:root {
+  color: #1f2933;
+  background: #f4f6f8;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  line-height: 1.5;
+}
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0; min-width: 320px;
+}
+.page {
+  width: min(100%, 720px);
+  margin: 0 auto;
+  padding: 40px 20px;
+}
+.card {
+  border: 1px solid #d8dee6;
+  border-radius: 8px;
+  background: #fff;
+  padding: 24px;
+}
+.eyebrow {
+  margin: 0 0 8px;
+  color: #287a4b;
+  font-size: 13px;
+  font-weight: 800;
+}
+h1 {
+  margin: 0; font-size: 36px; line-height: 1.1;
+}
+.intro,
+.status {
+  color: #52616f;
+}
+button {
+  width: 100%;
+  min-height: 42px;
+  border: 0;
+  border-radius: 6px;
+  background: #1f2933;
+  color: #fff;
+  cursor: pointer;
+  font: inherit;
+  font-weight: 700;
+}
+button:disabled {
+  cursor: not-allowed; opacity: 0.6;
+}
+pre {
+  margin: 16px 0 0;
+  overflow: auto;
+  border-radius: 6px;
+  background: #101820;
+  color: #f7fbff;
+  padding: 14px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}

package/dist/templates/vue3-vite-ts/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/dist/templates/vue3-vite-ts/tsconfig.app.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
+}

package/dist/templates/vue3-vite-ts/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.node.json"
+    }
+  ]
+}

package/dist/templates/vue3-vite-ts/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["vite.config.ts", "vitest.config.ts"]
+}

package/dist/templates/vue3-vite-ts/vite.config.ts

@@ -0,0 +1,6 @@
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [vue()],
+});

package/dist/templates/vue3-vite-ts/vitest.config.ts

@@ -0,0 +1,10 @@
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'happy-dom',
+    include: ['src/**/*.spec.ts'],
+  },
+});