@tbox-claw/bridge-sdk

TboxClaw 桌面端嵌入页面开发 SDK

本包为嵌入在 TboxClaw 桌面应用中的三方页面提供 TypeScript 类型定义 和 运行时工具函数。三方页面通过 window.tboxClawBridge 与客户端进行安全通信。

安装

npm install @tbox-claw/bridge-sdk
# 或
pnpm add @tbox-claw/bridge-sdk
# 或
yarn add @tbox-claw/bridge-sdk

快速开始

import { getBridge, isTboxClawEnv } from '@tbox-claw/bridge-sdk';

if (isTboxClawEnv()) {
  const bridge = getBridge();

  // 获取当前用户信息
  const userResult = await bridge.getUserInfo();
  if (userResult.ok) {
    console.log('你好，', userResult.data.name);
  }

  // 获取客户端信息
  const clientResult = await bridge.getClientInfo();
  if (clientResult.ok) {
    console.log('操作系统：', clientResult.data.platform);
    console.log('客户端版本：', clientResult.data.clientVersion);
  }
}

Bridge API

所有 Bridge API 返回统一的 BridgeResponse<T> 格式：

interface BridgeResponse<T = unknown> {
  ok: boolean;    // 调用是否成功
  data?: T;       // 响应数据（ok=true 时存在）
  error?: string; // 错误信息（ok=false 时存在）
}

权限模型：每个嵌入页面在服务端配置了允许调用的 API 白名单（bridge.allowedApis）。调用白名单之外的 API 会返回 { ok: false, error: 'API "xxx" not allowed for page "yyy"' }。

用户信息

| API | 说明 | 最小客户端版本 | |-----|------|:--------------:| | getUserInfo() | 获取当前登录用户信息（已脱敏） | 1.2.1 |

应用设置

| API | 说明 | 最小客户端版本 | |-----|------|:--------------:| | getSettings(keys) | 读取应用设置（支持 theme、language） | 1.2.1 |

客户端环境

| API | 说明 | 最小客户端版本 | |-----|------|:--------------:| | getClientInfo() | 获取操作系统、系统版本、客户端版本等环境信息 | 1.2.1 |

系统通知

| API | 说明 | 最小客户端版本 | |-----|------|:--------------:| | sendNotification(options) | 通过主应用发送系统通知 | 1.2.1 |

对话消息

| API | 说明 | 最小客户端版本 | |-----|------|:--------------:| | sendChatMessage(options) | 发送对话消息，等同于在 Chat 页面发送 | 1.2.1 | | getChatHistory(options?) | 查询对话历史记录 | 1.2.1 |

网关状态

| API | 说明 | 最小客户端版本 | |-----|------|:--------------:| | getGatewayStatus() | 查询 Gateway 运行状态，判断对话类 API 是否可用 | 1.2.1 |

自定义登录

| API | 说明 | 最小客户端版本 | |-----|------|:-------:| | loginSuccess(params) | 三方登录页面调用，将 OAuth 授权码传给桌面端完成登录 | 1.2.5 |

工具函数

SDK 提供以下工具函数，用于环境检测和安全调用，不依赖客户端版本。

isTboxClawEnv(): boolean

判断当前页面是否运行在 TboxClaw 桌面端中（即 window.tboxClawBridge 是否可用）。

import { isTboxClawEnv } from '@tbox-claw/bridge-sdk';

if (isTboxClawEnv()) {
  // 在 TboxClaw 中运行，Bridge API 可用
} else {
  // 独立运行，使用降级逻辑
}

getBridge(): TboxClawBridge

获取 window.tboxClawBridge 实例。如果不在 TboxClaw 环境中会抛出异常。

import { getBridge } from '@tbox-claw/bridge-sdk';

const bridge = getBridge();
const user = await bridge.getUserInfo();

safeBridgeCall<T>(apiFn, fallback): Promise<T>

安全调用 Bridge API。如果不在 TboxClaw 环境中或调用出错，返回 fallback 值。适用于需要同时支持独立运行和嵌入运行的页面。

import { safeBridgeCall } from '@tbox-claw/bridge-sdk';

const user = await safeBridgeCall(
  (bridge) => bridge.getUserInfo(),
  { ok: false, error: '不在 TboxClaw 环境中' },
);

双模式页面（独立运行 + 嵌入运行）

如果你的页面需要同时支持作为独立 Web 应用和嵌入页面运行，推荐使用 safeBridgeCall 模式：

import { safeBridgeCall, isTboxClawEnv } from '@tbox-claw/bridge-sdk';

// 获取用户信息 — 在 TboxClaw 外自动降级
const userResult = await safeBridgeCall(
  (bridge) => bridge.getUserInfo(),
  { ok: false, error: '非嵌入环境' },
);

if (userResult.ok) {
  renderUserProfile(userResult.data);
} else {
  renderLoginForm();
}

// 按需渲染 TboxClaw 专属功能
if (isTboxClawEnv()) {
  showClientInfoPanel();
}

TypeScript 支持

SDK 内置完整的 TypeScript 类型声明。安装后 window.tboxClawBridge 会自动获得类型提示：

// 无需额外配置 — window.tboxClawBridge 已自动声明类型
const bridge = window.tboxClawBridge;
const user = await bridge.getUserInfo(); // 完整类型推导

导出的类型

import type {
  TboxClawBridge,            // Bridge 接口定义
  BridgeResponse,            // { ok, data?, error? }
  UserInfo,                  // { userId, name, avatar, loginType?, extra? }
  ClientInfo,                // { platform, osVersion, clientVersion }
  SendNotificationOptions,   // { title, body, silent? }
  SendChatMessageOptions,    // { message, sessionKey? }
  GetChatHistoryOptions,     // { sessionKey?, limit? }
  ChatMessage,               // { role, content, timestamp?, id? }
  GatewayStatusInfo,         // { state, ready }
  LoginSuccessParams,        // { authCode }
} from '@tbox-claw/bridge-sdk';

License

MIT