# @doist/comms-sdk 中文文档

规范地址：https://npmcn.com/package/%40doist/comms-sdk/

版本：4\.0\.1
npm 元数据更新时间：2026-11-11T13:44:16.499Z
中文译文更新时间：2026-11-12T15:18:05.157Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40doist/comms-sdk
原文对照：https://npmcn.com/package/%40doist/comms-sdk/?lang=original
项目主页：https://doist.github.io/comms-sdk-typescript/
源码仓库：https://github.com/todoist/comms-sdk-typescript

弃用说明：Moved to @todoist/comms-sdk\. Replace @doist/comms-sdk with @todoist/comms-sdk in your dependencies and imports\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：565 kB，93 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：6 个
- 首次发布：2026-05-21T11:33:06.830Z
- 最新版本发布：2026-11-11T11:33:47.078Z
- 近 30 天下载量：4515（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

用于 Commes REST API 的 TypeScript 包装器.

## 安装

```sh
npm install @doist/comms-sdk
```

也可以使用：`pnpm add @doist/comms-sdk`、`yarn add @doist/comms-sdk`、`bun add @doist/comms-sdk`

## README

# 通讯SDK 类型脚本

官方TypeScript SDK为Comps REST API提供.

## 安装

```bash
npm install @doist/comms-sdk
```

## 使用量

```typescript
import { CommsApi } from '@doist/comms-sdk'

const api = new CommsApi('YOUR_API_TOKEN')

api.users
    .getSessionUser()
    .then((user) => console.log(user))
    .catch((error) => console.log(error))
```

默认情况下, SDK 目标生产时间为 `https://comms.todoist.com`。 。 。 . 传出 a `baseUrl` 选择指向不同的部署——中转 生活状况 `https://comms.staging.todoist.com`数字 :

```typescript
const api = new CommsApi('YOUR_API_TOKEN', {
    baseUrl: 'https://comms.staging.todoist.com',
})
```

### 创建实体

频道 / 线程 / 注释 / 对话 / 消息 / 组ID 是 不透明的基础58-编码的UUIDv7字符串; `workspaceId` 财务报告和审定财务报表 `userId` 为: 数相.

创建终点( E)`createChannel`, (中文(简体) ), `createThread`, (中文(简体) ), `createComment`, (中文(简体) ), `getOrCreateConversation`, (中文(简体) ), `createMessage`, (中文(简体) ), `createGroup`接受 选项 `id`。 。 。 . **来电供应 `id` 必须是基础58编码 UUIDv7 (美国英语)** 任何其它的都快失败了 `UuidV7Error` 之前 请求离开SDK。 要么用你的薄荷薄荷 `generateId()` (手脚) 表示乐观的UI——ID在往返旅行中存活不变)或省略 `id` 让SDK薄荷一:

```typescript
import { CommsApi, generateId } from '@doist/comms-sdk'

const api = new CommsApi('YOUR_API_TOKEN')

// Option 1: let the SDK mint an ID
const channel = await api.channels.createChannel({
    workspaceId: 1,
    name: 'Engineering',
})

// Option 2: mint the ID yourself (must be a base58 UUIDv7 from generateId)
const id = generateId()
const sameChannel = await api.channels.createChannel({
    workspaceId: 1,
    name: 'Engineering',
    id,
})
```

### 广播组标记

使用字符串常数 `EVERYONE` 编号 : `EVERYONE_IN_THREAD` 何时 输入 `groups[]` 编号 : `directGroupMentions[]` 直接或通过 `notifyAudience` 改为 `createComment` 编号 : `closeThread` 编号 : `reopenThread` 让SDK给你编码

```typescript
await api.comments.createComment({
    threadId,
    content: 'Heads up everyone',
    notifyAudience: 'channel', // encoded as EVERYONE
})
```

### OAuth 2.0 数据

```typescript
import { getAuthorizationUrl, getAuthToken, CommsApi } from '@doist/comms-sdk'

const authUrl = getAuthorizationUrl(
    'your-client-id',
    ['user:read', 'channels:read'],
    'state-parameter',
    'https://yourapp.com/callback',
)

const tokenResponse = await getAuthToken({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    code: 'authorization-code',
    redirectUri: 'https://yourapp.com/callback',
})

const api = new CommsApi(tokenResponse.accessToken)
const user = await api.users.getSessionUser()
```

访问符过期( 见 `tokenResponse.expiresIn`) (中文(简体) ). 当他们这样做,使用 `refreshToken` 从原始交换方式获取新交换方式而不发送 用户通过授权流返回 :

```typescript
import { refreshAuthToken } from '@doist/comms-sdk'

const refreshed = await refreshAuthToken({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    refreshToken: tokenResponse.refreshToken,
})

// The server may rotate the refresh token — persist refreshed.refreshToken
// when present, otherwise keep using the previous one.
const api = new CommsApi(refreshed.accessToken)
```

### REST 钩子

REST钩子需要托多主义OAuth与托多主义Commist的观众的连接符. 订阅 hTTPS 目标 URL 最多可达 150 个字符并导出其中之一 `HOOK_EVENTS`;后端将 POST Webhook 有效载荷到该 URL 当 匹配事件发生 :

```typescript
import { CommsApi, HOOK_EVENTS } from '@doist/comms-sdk'

const api = new CommsApi('TODOIST_OAUTH_ACCESS_TOKEN')

const subscription = await api.hooks.subscribe({
    targetUrl: 'https://example.com/comms-hook',
    event: 'thread_added',
    workspaceId: 1,
})

console.log(subscription.id, HOOK_EVENTS)

await api.hooks.unsubscribe({
    targetUrl: 'https://example.com/comms-hook',
})
```

### 短寿命过程( CLI, 脚本)

在节点上,SDK在请求间保持连接池活性,所以HTTP/ 2个 多功能和TLS再利用实际有效. 长期运行的过程不会 需要考虑一下. **短期进程应 `await api.close()` 退出前**,否则节点事件循环等待~4秒闲置 超时套接字 :

```typescript
const api = new CommsApi('YOUR_API_TOKEN')
try {
    await api.users.getSessionUser()
} finally {
    await api.close()
}
```

`api.close()` 排出过程- 全球集合, 因此它也覆盖代码 仅使用独立的 OAuth 助手的路径( E)`getAuthToken`, (中文(简体) ), `refreshAuthToken`, (中文(简体) ), `revokeAuthToken`, (中文(简体) ), `registerClient`) (中文(简体) ). 这些流动也可以进口 `closeDefaultDispatcher` 直接说.

## 发展

-   `npm install`
-   `npm test` - 维特
-   `npm run type-check` — 类型脚本
-   `npm run check` ——克克林特+克克夫克特
-   `npm run build` ——发布CJS+无害环境管理+d.ts

## 释放

软件包遵循语义化版本;通过 GitHub工作流程.

## 反馈

公开会议 [https://github.com/todoist/comms-sdk-typescription 页面存档备份,存于互联网档案馆](https://github.com/todoist/comms-sdk-typescript)。 。 。 .

## 常见问题

### @doist/comms-sdk 是什么？

用于 Commes REST API 的 TypeScript 包装器\.注意：该包已被作者标记为弃用——Moved to @todoist/comms-sdk\. Replace @doist/comms-sdk with @todoist/comms-sdk in your dependencies and imports\.

### 如何安装 @doist/comms-sdk？

在项目目录运行 npm install @doist/comms-sdk，或使用 pnpm add / yarn add / bun add。

### @doist/comms-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @doist/comms-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @doist/comms-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @doist/comms-sdk 可以商用吗？

@doist/comms-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @doist/comms-sdk 的下载量有多少？

根据 npm 官方下载统计，@doist/comms-sdk 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,515 次，日均约 151 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @doist/comms-sdk 还在维护吗？

最新版本 4\.0\.1 发布于 2026/11/11（2 天前）；至今共发布 49 个版本，其中过去 12 个月发布了 49 个；首次发布于 2026/05/21。作者已将其标记为弃用，新项目建议寻找替代方案。