# @doist/todoist-sdk 中文文档

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

版本：17\.0\.1
npm 元数据更新时间：2026-11-11T13:44:16.263Z
中文译文更新时间：2026-11-12T14:52:28.279Z
软件包许可：MIT

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

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

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

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

- 包体积（解压后）：1.3 MB，335 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：7 个
- peer 依赖：type-fest ^4\.12\.0 \|\| ^5\.5\.0
- 首次发布：2026-03-31T15:31:15.776Z
- 最新版本发布：2026-11-11T11:32:18.823Z
- 近 30 天下载量：71271（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 83 个）

## 中文简介

官方TypeScript SDK为托多主义者REST API.

## 安装

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

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

## README

# 托多主义 SDK

官方TypeScript SDK为托多主义者REST API.

## 安装

要求节点20.18.1+.

```
npm install @doist/todoist-sdk
```

### 使用量

初始化 API 客户端并获取用户任务的例子 :

```typescript
import { TodoistApi } from '@doist/todoist-sdk'

const api = new TodoistApi('YOURTOKEN')

api.getTasks()
    .then((tasks) => console.log(tasks))
    .catch((error) => console.log(error))
```

### 文档

关于更详细的参考文件,请查看 [Todoist API v1 文档](https://todoist.com/api/v1/docs)。 。 。 .

### 移徙指南

若从更古老版本的托多主义API(v9)迁移,请参见: [官方移徙指南](https://todoist.com/api/v1/docs#tag/Migrating-from-v9) 用于详细了解变化和中断更新.

V1中的关键变化包括:

-   更新的终点结构
-   新的标记系统
-   统一错误反应格式
-   对象重命名( 如项目 ) —— 任务, 注释 —— 注释 )
-   URL 重命名和端点签名更改

## 自定义信头

过 `headers` 以发送每个 API 请求的额外信头, 例如告诉后端客户端正在呼叫 :

```typescript
const api = new TodoistApi('YOURTOKEN', {
    headers: { 'Doist-Platform': 'cli' },
})
```

对于在请求之间变化的值,通过一个函数。 SDK每请求一次调用一次,再审请求重复使用其结果:

```typescript
import { randomUUID } from 'node:crypto'

const api = new TodoistApi('YOURTOKEN', {
    headers: () => ({ 'Doist-Platform': 'cli', 'Request-Id': randomUUID() }),
})
```

这些信头无法替换 `Authorization`, (中文(简体) ), `X-Request-Id` 或多块 `Content-Type`;SDK自己的价值观总是会取胜. 它们不以附件下载方式发送(`viewAttachment`重新定向到第三方CDN。 OAuth 帮助者`getAuthToken`, (中文(简体) ), `refreshAuthToken`, (中文(简体) ), `revokeToken`,.)自己选择,不发送.

## 自定义 HTTP 客户端

Todoist API客户端支持自定义的 HTTP 执行,以便在有特定网络要求的环境中使用,例如:

-   **斜边插件** - 台式应用程序,有严格的CORS政策
-   **浏览器扩展** - 具有不同安全模型的自定义HTTP API
-   **电子软件** - 通过IPC层传递的请求
-   **原生反应** - 不同的网络堆栈
-   **企业环境** - 代理配置、自定义标题或证书处理

### 基本用途

```typescript
import { TodoistApi } from '@doist/todoist-sdk'

// Using the new options-based constructor
const api = new TodoistApi('YOURTOKEN', {
    baseUrl: 'https://custom-api.example.com', // optional
    customFetch: myCustomFetch, // your custom fetch implementation
})

// Legacy constructor (deprecated but supported)
const apiLegacy = new TodoistApi('YOURTOKEN', 'https://custom-api.example.com')
```

### 自定义获取接口

您的自定义抓取功能必须执行此接口 :

```typescript
type CustomFetch = (
    url: string,
    options?: RequestInit & { timeout?: number },
) => Promise<CustomFetchResponse>

type CustomFetchResponse = {
    ok: boolean
    status: number
    statusText: string
    headers: Record<string, string>
    text(): Promise<string>
    json(): Promise<unknown>
}
```

### 带有自定义获取的 OAuth

OAuth 认证功能 (`getAuthToken`, (中文(简体) ), `revokeAuthToken`, (中文(简体) ), `revokeToken`通过选项对象支持自定义获取:

```typescript
// New options-based usage
const { accessToken } = await getAuthToken(args, {
    baseUrl: 'https://custom-auth.example.com',
    customFetch: myCustomFetch,
})

await revokeToken(args, {
    customFetch: myCustomFetch,
})

// Legacy usage (deprecated)
const { accessToken } = await getAuthToken(args, baseUrl)
```

当授权服务器发布 a `refreshToken`,使用时 `refreshAuthToken` 当当前访问符到期时, 无需发送 用户通过授权流返回 :

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

// The server may rotate the refresh token — persist refreshed.refreshToken
// when present, otherwise keep using the previous one.
```

> **说明:** 刷新令牌只发放给已启用的 OAuth apps (新应用程序的默认值). 没有他们的 Apps 得到一个长寿的访问 标志,所以 `getAuthToken` 返回无 `refreshToken` 没有什么 刷新点 公共客户(`tokenEndpointAuthMethod: 'none'`,省略 `clientSecret` 调用时 `refreshAuthToken`。 。 。 .

### 保持代理支持和响应解压

在节点上,SDK的默认传输读取了代理环境变量(`HTTP_PROXY`, (中文(简体) ), `HTTPS_PROXY`, (中文(简体) ), `NO_PROXY`)并解码压缩响应机构. 供应a `customFetch` 替换该运算,所以一个仍然想要的自定义执行可以借给 `getDefaultTransport`数字 :

```typescript
import { type CustomFetch, getDefaultTransport, TodoistApi } from '@doist/todoist-sdk'

const customFetch: CustomFetch = async (url, options) => {
    const transport = await getDefaultTransport()
    // undici's `fetch` and the global one are the same call at runtime but
    // carry different types, so settle on one signature.
    const fetchImpl = (transport?.fetch ?? fetch) as typeof fetch

    const response = await fetchImpl(url, {
        ...options,
        headers: {
            ...(options?.headers as Record<string, string> | undefined),
            'x-my-header': 'value',
        },
        // `dispatcher` is a Node fetch option that the DOM types don't declare.
        dispatcher: transport?.dispatcher,
    } as RequestInit)

    // `CustomFetchResponse` wants plain-object headers, not a `Headers`.
    const headers: Record<string, string> = {}
    response.headers.forEach((value, key) => {
        headers[key] = value
    })

    return {
        ok: response.ok,
        status: response.status,
        statusText: response.statusText,
        headers,
        text: () => response.text(),
        json: () => response.json(),
        arrayBuffer: () => response.arrayBuffer(),
    }
}

const api = new TodoistApi('YOURTOKEN', { customFetch })
```

`getDefaultTransport` 返回调度器和 `fetch` 它必须作为单一值使用,两者必须一起使用。 调度员对反应机体本身进行解压,使其与一个 `fetch` 包括运行时间的全局 `fetch` 在节点26上——两次解码身体,请求在中游失败 `terminated`A级 `fetch` 联 合 国 `undefined` 指全球 `fetch` 是正确的伴侣;整个值是 `undefined` 在节点之外,没有调度器.

### 重要说明

-   所有已有的变换( snake case QQ cameasCase) 自动与自定义抓取一起工作
-   重试逻辑和错误处理保存
-   文件上传工作与自定义获取执行
-   文件上传正文为 a `Blob`,或一个 `ReadableStream` 当从溪流上传时——自定义抓取必须不加修改地通过它们
-   超时参数是可选的, 直至您的自定义执行

## 过滤查询

使用 `escapeFilterToken` 用于用户提供的搜索文本,处理代码中的校验和校正。 直接传递完整的过滤查询到 `getTasksByFilter`。 。 。 .

```typescript
await api.getTasksByFilter({
    query: `search: ${escapeFilterToken(searchText)}`,
})
```

## 开发和测试

我们没有在存储器中设置一个实例应用程序来协助开发和测试,而是列入了 [ts-节点](https://github.com/TypeStrong/ts-node) 是一个非常依赖。 这使得我们可以在本地拥有一个抓取文件,可以导入和使用API,同时开发或审查拉取请求而无需管理单独的应用项目.

-   `npm install`
-   添加名为的文件 `scratch.ts` 输入 `src` 文件夹.
-   配置您的 IDE 以运行抓取文件 `ts-node` (指示: [虚拟系统](https://medium.com/@dupski/debug-typescript-in-vs-code-without-compiling-using-ts-node-9d1f4f9a94a), (中文(简体) ), [网络结构](https://www.jetbrains.com/help/webstorm/running-and-debugging-typescript.html#ws_ts_run_debug_server_side_ts_node)),或者您可以选择使用指令在终端中运行 ts-node [这里](https://github.com/TypeStrong/ts-node) (单位:千美元)`npx ts-node ./src/scratch.ts` 应该足够).
-   导入并调用相关模块并运行抓取文件.

示例抓取.ts 文件 :

```
/* eslint-disable no-console */
import { TodoistApi } from './todoist-api'

const token = 'YOURTOKEN'
const api = new TodoistApi(token)

api.getProjects()
    .then((projects) => {
        console.log(projects)
    })
    .catch((error) => console.error(error))
```

### 本地 API 请求使用 .env

对于活的 API 校验,您可以用本地符号运行原始请求 :

1.  复制 `.env.example` 改为 `.env`。 。 。 .
2.  设定 `TODOIST_API_TOKEN` 内 `.env`。 。 。 .
3.  以 `npm run api:request -- ...`。 。 。 .
4.  可选: 设置 `TODOIST_API_BASE_URL` 内 `.env` (违约) `https://api.todoist.com`) (中文(简体) ).

实例:

```bash
npm run api:request -- --path /api/v1/tasks
npm run api:request -- --method POST --path /api/v1/tasks --body '{"content":"API smoke test"}'
npm run api:request -- --method POST --path /api/v1/tasks/123 --body '{"due_string":"no date"}'
npm run api:request -- --path /api/v1/tasks --query '{"project_id":"123","limit":10}'
```

查看所有选项 :

```bash
npm run api:request -- --help
```

## 释放

这个项目使用 [释放请](https://github.com/googleapis/release-please) 自动释放。 自动创建基于 [常规武器委员会](https://www.conventionalcommits.org/)。 。 。 .

### 贡献者

更改时, 使用常规承诺消息 :

-   `feat:` - 新功能(触发一个小版本起伏)
-   `fix:` - 错误修正(触发补丁版本出错)
-   `feat!:` 或者说 `BREAKING CHANGE:` - 突破变化(触发一个主要版本起伏)
-   `chore:`, (中文(简体) ), `docs:`, (中文(简体) ), `refactor:`, (中文(简体) ), `perf:` - 其他变动(列入变更日志)

示例

```
feat: add support for recurring tasks
fix: resolve issue with date parsing
feat!: remove deprecated getTask method
```

### 维护者

发布过程完全自动化:

1.  **自动创建 PR**: 当承诺合并为 `main`,发布请以 :
    
    -   更新版本为 `package.json`
    -   更新 `CHANGELOG.md`
    -   自上次发布以来的合计变化
2.  **审查和合并**:审查发行的PR,以确保版本的凸起和更改日志正确,然后合并.
    
3.  **自动释放**: 合并释放的PR时:
    
    -   用新版本标签自动创建 GitHub 发布
    -   这个 `publish.yml` 工作流程由标签触发
    -   该软件包自动发布给国家预防机制

API 客户端的用户可以在其中更新新版本 `package.json`。 。 。 .

### 反馈

任何反馈,如错误、问题、评论等,均可报告为 _问题_ 由我们托多伊斯特公司处理.

### 捐款

我们还希望以下列形式作出贡献: _调取请求_ 在此仓库中.

## 常见问题

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

官方TypeScript SDK为托多主义者REST API\.注意：该包已被作者标记为弃用——Moved to @todoist/sdk\. Replace @doist/todoist-sdk with @todoist/sdk in your dependencies and imports\.

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

在项目目录运行 npm install @doist/todoist-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：type-fest（^4\.12\.0 \|\| ^5\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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

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

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