@ccw-api/teamwork-socket

CCW Teamwork 多人协作 WebSocket SDK。封装请求-回复队列、超时拒绝、ping/pong 心跳，适用于浏览器端。

功能

• 请求-回复语义：sendRequest 返回 Promise，自动匹配服务端回复
• 按 type 串行队列：同 type 请求 FIFO 排队，前一条处理完再发下一条
• 超时自动拒绝：超时后 reject 并清理，不阻塞后续队列
• 发送失败快速跳过：socket 异常时立即 reject，防止队列卡死
• 内置 ping/pong 心跳
• 资源清理：dispose() 关闭连接清空队列
• 零第三方依赖，TypeScript 原生支持（ESM + CJS 双构建）

安装

npm install @ccw-api/teamwork-socket

快速开始

import { TeamworkSocket, getRandomClientId } from "@ccw-api/teamwork-socket";

const sock = new TeamworkSocket(
  "project-oid",
  "user-123",
  "ticket-abc",
  getRandomClientId(),
  "Alice",
  "https://example.com/avatar.png",
  15_000, // 超时 ms，默认 30_000
);

await sock.connect();

// 请求-回复
const result = await sock.sendRequest("user.list", { page: 1 });

// 单向广播
sock.sendBroadcast("chat.message", { text: "hello" });

// 释放
sock.dispose();

API

构造函数

new TeamworkSocket(
  projectOid: string,
  userId: string,
  ticket: string,
  clientId?: string,   // 默认随机生成
  name?: string,       // 默认 "BOT"
  avatar?: string,
  timeout?: number,    // 默认 30000ms，<=0 关闭超时
)

方法

| 方法 | 返回 | 说明 | | --------------------------- | ----------------- | ------------------------------------------------ | | connect() | Promise<object> | 握手（open 时自动调用） | | sendRequest(type, data) | Promise<object> | 发送请求，回复时 resolve；超时/发送失败时 reject | | sendBroadcast(type, data) | void | 单向广播，发后即忘 | | dispose() | void | 关闭连接、清空队列 |

错误

• Request timeout: {type} — 超时未收到回复，可重试
• Failed to send: {type} — socket 未 OPEN 或 send 抛异常，需重连

开发

npm install
npm run dev      # 监听开发
npm run build    # 构建 ESM + CJS + d.ts
npm publish      # 发布前自动构建

构建配置见 tsup.config.ts。

License

MIT © MengFuzi