{"id":20589983,"url":"https://github.com/Doist/todoist-sdk-typescript","last_synced_at":"2026-04-02T12:07:52.748Z","repository":{"id":36978400,"uuid":"428678731","full_name":"Doist/todoist-api-typescript","owner":"Doist","description":"A TypeScript wrapper for the Todoist REST API.","archived":false,"fork":false,"pushed_at":"2025-05-09T09:13:20.000Z","size":2649,"stargazers_count":87,"open_issues_count":9,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-09T10:24:23.326Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://doist.github.io/todoist-api-typescript/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Doist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-16T14:03:09.000Z","updated_at":"2025-05-08T12:57:56.000Z","dependencies_parsed_at":"2023-11-12T22:26:09.183Z","dependency_job_id":"cbeb9344-1003-4b8a-89e4-35a4c62af061","html_url":"https://github.com/Doist/todoist-api-typescript","commit_stats":{"total_commits":385,"total_committers":15,"mean_commits":"25.666666666666668","dds":0.7116883116883117,"last_synced_commit":"1d8af8189d80d1b7fe5851b56642f74a5fae92dd"},"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-api-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-api-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-api-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-api-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Doist","download_url":"https://codeload.github.com/Doist/todoist-api-typescript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535829,"owners_count":22087399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T07:33:19.282Z","updated_at":"2026-04-02T12:07:52.740Z","avatar_url":"https://github.com/Doist.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Todoist SDK\n\nThe official TypeScript SDK for the Todoist REST API.\n\n## Installation\n\nRequires Node 20.18.1+.\n\n```\nnpm install @doist/todoist-sdk\n```\n\n### Usage\n\nAn example of initializing the API client and fetching a user's tasks:\n\n```typescript\nimport { TodoistApi } from '@doist/todoist-sdk'\n\nconst api = new TodoistApi('YOURTOKEN')\n\napi.getTasks()\n    .then((tasks) =\u003e console.log(tasks))\n    .catch((error) =\u003e console.log(error))\n```\n\n### Documentation\n\nFor more detailed reference documentation, have a look at the [Todoist API v1 Documentation](https://todoist.com/api/v1/docs).\n\n### Migration Guide\n\nIf you're migrating from an older version of the Todoist API (v9), please refer to the [official migration guide](https://todoist.com/api/v1/docs#tag/Migrating-from-v9) for detailed information about the changes and breaking updates.\n\nKey changes in v1 include:\n\n- Updated endpoint structure\n- New pagination system\n- Unified error response format\n- Object renames (e.g., items → tasks, notes → comments)\n- URL renames and endpoint signature changes\n\n## Custom HTTP Clients\n\nThe Todoist API client supports custom HTTP implementations to enable usage in environments with specific networking requirements, such as:\n\n- **Obsidian plugins** - Desktop app with strict CORS policies\n- **Browser extensions** - Custom HTTP APIs with different security models\n- **Electron apps** - Requests routed through IPC layer\n- **React Native** - Different networking stack\n- **Enterprise environments** - Proxy configuration, custom headers, or certificate handling\n\n### Basic Usage\n\n```typescript\nimport { TodoistApi } from '@doist/todoist-sdk'\n\n// Using the new options-based constructor\nconst api = new TodoistApi('YOURTOKEN', {\n    baseUrl: 'https://custom-api.example.com', // optional\n    customFetch: myCustomFetch, // your custom fetch implementation\n})\n\n// Legacy constructor (deprecated but supported)\nconst apiLegacy = new TodoistApi('YOURTOKEN', 'https://custom-api.example.com')\n```\n\n### Custom Fetch Interface\n\nYour custom fetch function must implement this interface:\n\n```typescript\ntype CustomFetch = (\n    url: string,\n    options?: RequestInit \u0026 { timeout?: number },\n) =\u003e Promise\u003cCustomFetchResponse\u003e\n\ntype CustomFetchResponse = {\n    ok: boolean\n    status: number\n    statusText: string\n    headers: Record\u003cstring, string\u003e\n    text(): Promise\u003cstring\u003e\n    json(): Promise\u003cunknown\u003e\n}\n```\n\n### OAuth with Custom Fetch\n\nOAuth authentication functions (`getAuthToken`, `revokeAuthToken`, `revokeToken`) support custom fetch through an options object:\n\n```typescript\n// New options-based usage\nconst { accessToken } = await getAuthToken(args, {\n    baseUrl: 'https://custom-auth.example.com',\n    customFetch: myCustomFetch,\n})\n\nawait revokeToken(args, {\n    customFetch: myCustomFetch,\n})\n\n// Legacy usage (deprecated)\nconst { accessToken } = await getAuthToken(args, baseUrl)\n```\n\n### Important Notes\n\n- All existing transforms (snake_case ↔ camelCase) work automatically with custom fetch\n- Retry logic and error handling are preserved\n- File uploads work with custom fetch implementations\n- The custom fetch function should handle FormData for multipart uploads\n- Timeout parameter is optional and up to your custom implementation\n\n## Development and Testing\n\nInstead of having an example app in the repository to assist development and testing, we have included [ts-node](https://github.com/TypeStrong/ts-node) as a dev dependency. This allows us to have a scratch file locally that can import and utilize the API while developing or reviewing pull requests without having to manage a separate app project.\n\n- `npm install`\n- Add a file named `scratch.ts` in the `src` folder.\n- Configure your IDE to run the scratch file with `ts-node` (instructions for [VSCode](https://medium.com/@dupski/debug-typescript-in-vs-code-without-compiling-using-ts-node-9d1f4f9a94a), [WebStorm](https://www.jetbrains.com/help/webstorm/running-and-debugging-typescript.html#ws_ts_run_debug_server_side_ts_node)), or you can optionally run ts-node in a terminal using instructions [here](https://github.com/TypeStrong/ts-node) (`npx ts-node ./src/scratch.ts` should be enough).\n- Import and call the relevant modules and run the scratch file.\n\nExample scratch.ts file:\n\n```\n/* eslint-disable no-console */\nimport { TodoistApi } from './todoist-api'\n\nconst token = 'YOURTOKEN'\nconst api = new TodoistApi(token)\n\napi.getProjects()\n    .then((projects) =\u003e {\n        console.log(projects)\n    })\n    .catch((error) =\u003e console.error(error))\n```\n\n### Local API Requests With .env\n\nFor live API verification, you can run raw requests with a local token:\n\n1. Copy `.env.example` to `.env`.\n2. Set `TODOIST_API_TOKEN` in `.env`.\n3. Run requests with `npm run api:request -- ...`.\n4. Optional: set `TODOIST_API_BASE_URL` in `.env` (defaults to `https://api.todoist.com`).\n\nExamples:\n\n```bash\nnpm run api:request -- --path /api/v1/tasks\nnpm run api:request -- --method POST --path /api/v1/tasks --body '{\"content\":\"API smoke test\"}'\nnpm run api:request -- --method POST --path /api/v1/tasks/123 --body '{\"due_string\":\"no date\"}'\nnpm run api:request -- --path /api/v1/tasks --query '{\"project_id\":\"123\",\"limit\":10}'\n```\n\nTo see all options:\n\n```bash\nnpm run api:request -- --help\n```\n\n## Releases\n\nThis project uses [Release Please](https://github.com/googleapis/release-please) to automate releases. Releases are created automatically based on [Conventional Commits](https://www.conventionalcommits.org/).\n\n### For Contributors\n\nWhen making changes, use conventional commit messages:\n\n- `feat:` - New features (triggers a minor version bump)\n- `fix:` - Bug fixes (triggers a patch version bump)\n- `feat!:` or `BREAKING CHANGE:` - Breaking changes (triggers a major version bump)\n- `chore:`, `docs:`, `refactor:`, `perf:` - Other changes (included in changelog)\n\nExample:\n\n```\nfeat: add support for recurring tasks\nfix: resolve issue with date parsing\nfeat!: remove deprecated getTask method\n```\n\n### For Maintainers\n\nThe release process is fully automated:\n\n1. **Automatic PR Creation**: When commits are merged to `main`, Release Please automatically creates or updates a release PR with:\n    - Updated version in `package.json`\n    - Updated `CHANGELOG.md`\n    - Aggregated changes since the last release\n\n2. **Review and Merge**: Review the release PR to ensure the version bump and changelog are correct, then merge it.\n\n3. **Automatic Release**: Upon merging the release PR:\n    - A GitHub release is automatically created with the new version tag\n    - The `publish.yml` workflow is triggered by the tag\n    - The package is automatically published to NPM\n\nUsers of the API client can then update to the new version in their `package.json`.\n\n### Feedback\n\nAny feedback, such as bugs, questions, comments, etc. can be reported as _Issues_ in this repository, and will be handled by us in Todoist.\n\n### Contributions\n\nWe would also love contributions in the form of _Pull requests_ in this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDoist%2Ftodoist-sdk-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDoist%2Ftodoist-sdk-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDoist%2Ftodoist-sdk-typescript/lists"}