@qihoo/tuitui-bot-sdk

面向浏览器和 Node.js 的推推机器人 SDK。源码使用 TypeScript，发布产物为 JavaScript 和类型声明。

安装

npm install @qihoo/tuitui-bot-sdk

只发送消息

事件订阅完全可选。只发送消息、上传文件或调用团队 API 时，不需要调用 client.event.subscribe()。

import { TuituiBotClient, toAccount } from "@qihoo/tuitui-bot-sdk";

const client = new TuituiBotClient("your-app-id", "your-app-secret");

await client.im.sendMessage({
  to: toAccount("user-account"),
  message: {
    type: "text",
    text: "**你好**，这是一条 `Markdown` 消息。",
  },
});

client.im 使用统一的 ChatTarget 发送单聊和群聊消息。通过 toAccount()、toUid()、toGroupId()、toAccounts() 或 toUids() 创建目标，频道和帖子能力位于 client.teams。

接收消息

只有需要接收推推事件时才建立长连接：

import {
  TuituiBotClient,
  parseTuituiEvent,
  tuitui_event,
} from "@qihoo/tuitui-bot-sdk";

const client = new TuituiBotClient("...", "...");

const subscription = client.event.subscribe({
  onRawEvent(raw) {
    // 原始 JSON 始终可用
    console.log(raw);
  },
  onEvent(event) {
    // 使用推推开放平台定义的原始事件名
    if (event.event === tuitui_event.single_chat && "data" in event) {
      console.log("收到单聊消息", client.event.renderMessageBody(event.data));
    }
  },
  onError(error) {
    console.error(error);
  },
});

// 不再接收事件时，清理连接和重连定时器。
subscription.unsubscribe();

// 解析器也可以完全独立使用。
const parsed = parseTuituiEvent(rawJson);

解析结果保留推推原始 event 和 data 字段，并按单聊、群聊、团队帖子等事件分别提供类型。SDK 不会将它们归一化为通用消息类型，也不会隐式渲染消息文本。需要文本时由调用者显式调用 client.event.renderMessageBody(data)。

订阅层会自动 ACK、过滤 keepalive、按 event_id 去重、检测心跳超时并断线重连。主动 unsubscribe() 后不会再重连。

API

所有文本发送与编辑 API 的 text 字段都支持 Markdown 格式。

• ChatTarget：统一的单聊和群聊目标结构。
• toAccount()、toUid()、toGroupId()：创建单个账号、UID 或群聊目标。
• toAccounts()、toUids()：创建小众场景使用的批量账号或 UID 目标。
• client.im.sendMessage()：通过 ChatTarget 发送文本、图文混排、page、link、媒体和交互卡片；同类目标支持批量发送。
• 群聊消息的 at 支持域账号或姓名。
• client.im.editMessage()、modifyInteractive()、emojiReaction()：通过结构化目标编辑消息、更新卡片和添加表情回复。
• client.im.getHistory()：读取账号单聊或群聊历史。
• 图文混排消息的文字项为纯文本，不支持 Markdown，图片项会自动上传。
• client.teams.sendPost()、editPost()、sendMedia()、emojiReaction()：发送、编辑帖子以及发送媒体和添加表情回复。
• client.teams：还提供频道信息、标签、公告、成员、帖子链、频道帖子和主题列表。帖子 API 使用 teamId、channelId，当前仅支持单个 tag。
• client.file：上传图片或附件，以及文件空间节点、目录和文件 API。
• client.event：可选的 WebSocket 事件订阅。只有调用 client.event.subscribe() 才会建立长连接。
• client.info()：获取当前机器人的显示名、UID 和账号。
• client.request()：调用尚未封装或未来新增的推推机器人 API；GET 请求使用 client.request(path, undefined, { method: "GET" })。

上传支持 Blob、File、ArrayBuffer、Uint8Array、data URL、HTTP URL；Node.js 中还支持本地文件路径。默认大小限制为 10MB，可通过 maxBytes 调整。

卡片工具

SDK 提供确认、选择、多输入和表单卡片模板，以及交互动作解析和状态卡片构建工具：

import {
  buildConfirmCard,
  buildTuituiInteractiveMessage,
  toAccount,
} from "@qihoo/tuitui-bot-sdk";

const interactive = buildTuituiInteractiveMessage(
  buildConfirmCard({ title: "确认发布", content: "是否继续？", doubleCheck: true }),
);

await client.im.sendMessage({
  to: toAccount("alice"),
  message: { type: "interactive", interactive },
});

默认地址与自定义请求

SDK 默认使用推推生产环境的 HTTP 和 WebSocket 地址，正常接入无需配置 apiBaseUrl 或 websocketBaseUrl。需要使用代理或 mock 时，可以覆盖地址，并通过 fetch、logger 注入自定义运行时能力。

真实环境示例

测试统一使用 Vitest：test/mock 是默认运行的无网络测试，test/e2e 包含普通 API、交互卡片和双 Bot 长连接自动收发的真实环境测试。配置字段及运行方式见 test/e2e/README.md。