feat(view-options): add saved view options API

[gnapse]

Summary

• Complete the saved view-options schemas, including valid singleton IDs, tombstones, and calendar settings.
• Add typed get, set, and delete methods to TodoistApi.
• Add reusable helpers for finding active view options.

Example

import { TodoistApi, findViewOptions } from "@doist/todoist-sdk"

const api = new TodoistApi(token)
const options = await api.getViewOptions()
const savedOptions = findViewOptions(options, {
    viewTypes: ["FILTER", "WORKSPACE_FILTER"],
    objectId: filterId,
})

await api.setViewOptions({
    viewType: "FILTER",
    objectId: filterId,
    sortedBy: "DUE_DATE",
    sortOrder: "ASC",
})

Validation

• Used scripts against a live Todoist test account to create a project and round-trip saved options through the local SDK: set, get, lookup, delete, verify absence, and restore. The Todoist UI reflected the restored grouping and sorting.
• Adapted todoist-cli#463 locally to use TodoistApi.setViewOptions() from a packed local SDK build. Its full test and check suites passed.
• The SDK test suite (52 files, 667 tests), build, and package API checks passed.

Context

This is the first PR in the stack. It lets SDK consumers use saved view options without parsing raw Sync responses.

Related CLI work:

• Issue: feat: expose view options (board/list, group by, sort) — SDK supports view_options_set but the CLI never calls it todoist-cli#462
• PRs that can use this API:
  • feat(filter): expose view options (board/list, group by, sort) todoist-cli#463
  • feat(sort): add task ordering that matches the Todoist apps todoist-cli#480

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[doistbot]

This PR adds a clean saved view-options API surface — a new sub-client, public TodoistApi methods (get/set/delete), expanded Zod schemas, and a findViewOptions helper — that follows the existing sub-client and Sync request conventions nicely.

Few things worth tightening:

• ViewOptionsSetArgs types deadline and calendarSettings as non-null, but the response schema marks both as nullable and the sibling ProjectViewOptionsDefaultsSetArgs already accepts | null. This means callers can't send { deadline: null } or { calendarSettings: null } to clear an existing saved value — add | null to both fields.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (3)

• src/utils/view-options.ts:19: The "active view option" check (isDeleted !== true) is now duplicated in ViewOptionsClient.getViewOptions (src/clients/view-options-client.ts:14) and here in findViewOptions, both added in this PR. Extract a shared helper (e.g. isActiveViewOption) so the definition of "active" lives in one place and can't drift between the two.
• src/todoist-api.view-options.test.ts:133: findViewOptions is a utility in src/utils/view-options.ts, but its tests are embedded in the TodoistApi view-options test file. Every other utility in this repo has a matching src/utils/<name>.test.ts. Move this describe block into src/utils/view-options.test.ts to keep the test layout consistent and the utility testable independently of the API surface.
• src/todoist-api.ts:362: These three public methods only have one-line summaries, while every other method on TodoistApi documents @param and @returns. Add the matching JSDoc (e.g. @param args, @param requestId, @returns) so IDE hints and generated docs stay consistent for this public SDK surface.

_{Share Feedback • Review Logs}

[doistbot]

This PR adds a clean saved view-options API surface — sub-client, public TodoistApi methods, expanded Zod schemas, and reusable helpers — that follows existing Sync conventions.

Few things worth tightening:

• ViewOptionsSetArgs.viewMode is still typed as non-null ViewMode, but the response schema now allows null and the sibling ProjectViewOptionsDefaultsSetArgs.viewMode already accepts ViewMode | null. Add | null so callers can clear a saved view mode via { viewMode: null }, matching every other nullable field in the set args.

I also left one optional follow-up note in the details below.

Optional follow-up note (1)

• src/utils/view-options.test.ts:31: The test title claims objectId is matched both when null and when omitted, but only the omitted case is exercised. FindViewOptionsArgs.objectId explicitly accepts string | null, and findViewOptions normalizes both via ?? null — pass objectId: null in this assertion too (or narrow the title) so the null path is covered and the name matches what's actually tested.

_{Share Feedback • Review Logs}

[craigcarlyle]

✅

[doist-release-bot]

🎉 This PR is included in version 14.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀