托多主义 SDK
官方TypeScript SDK为托多主义者REST API.
安装
要求节点20.18.1+.
npm install @doist/todoist-sdk
使用量
初始化 API 客户端并获取用户任务的例子 :
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 文档。 。 。 .
移徙指南
若从更古老版本的托多主义API(v9)迁移,请参见: 官方移徙指南 用于详细了解变化和中断更新.
V1中的关键变化包括:
- 更新的终点结构
- 新的标记系统
- 统一错误反应格式
- 对象重命名( 如项目 ) —— 任务, 注释 —— 注释 )
- URL 重命名和端点签名更改
自定义信头
过 headers 以发送每个 API 请求的额外信头, 例如告诉后端客户端正在呼叫 :
const api = new TodoistApi('YOURTOKEN', {
headers: { 'Doist-Platform': 'cli' },
})
对于在请求之间变化的值,通过一个函数。 SDK每请求一次调用一次,再审请求重复使用其结果:
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层传递的请求
- 原生反应 - 不同的网络堆栈
- 企业环境 - 代理配置、自定义标题或证书处理
基本用途
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')
自定义获取接口
您的自定义抓取功能必须执行此接口 :
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通过选项对象支持自定义获取:
// 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
当当前访问符到期时, 无需发送
用户通过授权流返回 :
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数字 :
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上——两次解码身体,请求在中游失败 terminatedA级 fetch 联 合 国 undefined 指全球 fetch 是正确的伴侣;整个值是 undefined 在节点之外,没有调度器.
重要说明
- 所有已有的变换( snake case QQ cameasCase) 自动与自定义抓取一起工作
- 重试逻辑和错误处理保存
- 文件上传工作与自定义获取执行
- 文件上传正文为 a
Blob,或一个ReadableStream当从溪流上传时——自定义抓取必须不加修改地通过它们 - 超时参数是可选的, 直至您的自定义执行
过滤查询
使用 escapeFilterToken 用于用户提供的搜索文本,处理代码中的校验和校正。 直接传递完整的过滤查询到 getTasksByFilter。 。 。 .
await api.getTasksByFilter({
query: `search: ${escapeFilterToken(searchText)}`,
})
开发和测试
我们没有在存储器中设置一个实例应用程序来协助开发和测试,而是列入了 ts-节点 是一个非常依赖。 这使得我们可以在本地拥有一个抓取文件,可以导入和使用API,同时开发或审查拉取请求而无需管理单独的应用项目.
npm install- 添加名为的文件
scratch.ts输入src文件夹. - 配置您的 IDE 以运行抓取文件
ts-node(指示: 虚拟系统, (中文(简体) ), 网络结构),或者您可以选择使用指令在终端中运行 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 校验,您可以用本地符号运行原始请求 :
- 复制
.env.example改为.env。 。 。 . - 设定
TODOIST_API_TOKEN内.env。 。 。 . - 以
npm run api:request -- ...。 。 。 . - 可选: 设置
TODOIST_API_BASE_URL内.env(违约)https://api.todoist.com) (中文(简体) ).
实例:
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}'
查看所有选项 :
npm run api:request -- --help
释放
这个项目使用 释放请 自动释放。 自动创建基于 常规武器委员会。 。 。 .
贡献者
更改时, 使用常规承诺消息 :
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
维护者
发布过程完全自动化:
-
自动创建 PR: 当承诺合并为
main,发布请以 :- 更新版本为
package.json - 更新
CHANGELOG.md - 自上次发布以来的合计变化
- 更新版本为
-
审查和合并:审查发行的PR,以确保版本的凸起和更改日志正确,然后合并.
-
自动释放: 合并释放的PR时:
- 用新版本标签自动创建 GitHub 发布
- 这个
publish.yml工作流程由标签触发 - 该软件包自动发布给国家预防机制
API 客户端的用户可以在其中更新新版本 package.json。 。 。 .
反馈
任何反馈,如错误、问题、评论等,均可报告为 问题 由我们托多伊斯特公司处理.
捐款
我们还希望以下列形式作出贡献: 调取请求 在此仓库中.