@doist/todoist-sdk 14.0.2 → 14.1.0

package/dist/cjs/clients/view-options-client.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewOptionsClient = void 0;
+const sync_request_1 = require("../transport/sync-request");
+const sync_helpers_1 = require("../utils/sync-helpers");
+const view_options_1 = require("../utils/view-options");
+const base_client_1 = require("./base-client");
+/** Internal sub-client for saved view-option reads and writes. */
+class ViewOptionsClient extends base_client_1.BaseClient {
+    async getViewOptions() {
+        var _a;
+        const response = await (0, sync_request_1.performSyncRequest)(this.syncContext, {
+            resourceTypes: ['view_options'],
+            syncToken: '*',
+        });
+        return ((_a = response.viewOptions) !== null && _a !== void 0 ? _a : []).filter(view_options_1.isActiveViewOption);
+    }
+    async setViewOptions(args, requestId) {
+        await (0, sync_request_1.performSyncRequest)(this.syncContext, { commands: [(0, sync_helpers_1.createCommand)('view_options_set', args)] }, { requestId, hasSyncCommands: true });
+    }
+    async deleteViewOptions(args, requestId) {
+        await (0, sync_request_1.performSyncRequest)(this.syncContext, { commands: [(0, sync_helpers_1.createCommand)('view_options_delete', args)] }, { requestId, hasSyncCommands: true });
+    }
+}
+exports.ViewOptionsClient = ViewOptionsClient;

package/dist/cjs/todoist-api.js

@@ -19,6 +19,7 @@ const task_client_1 = require("./clients/task-client");
 const template_client_1 = require("./clients/template-client");
 const ui_extension_client_1 = require("./clients/ui-extension-client");
 const upload_client_1 = require("./clients/upload-client");
+const view_options_client_1 = require("./clients/view-options-client");
 const workspace_client_1 = require("./clients/workspace-client");
 const endpoints_1 = require("./consts/endpoints");
 const http_client_1 = require("./transport/http-client");
@@ -65,6 +66,7 @@ class TodoistApi {
         this.billingClient = new billing_client_1.BillingClient(clientDeps);
         this.appClient = new app_client_1.AppClient(clientDeps);
         this.uiExtensionClient = new ui_extension_client_1.UiExtensionClient(clientDeps);
+        this.viewOptionsClient = new view_options_client_1.ViewOptionsClient(clientDeps);
     }
     /**
      * Executes a raw Sync API request.
@@ -98,6 +100,34 @@ class TodoistApi {
             customFetch: this.customFetch,
         }, syncRequest, { requestId, hasSyncCommands: Boolean((_a = syncRequest.commands) === null || _a === void 0 ? void 0 : _a.length) });
     }
+    /**
+     * Retrieves the authenticated user's active saved view options.
+     *
+     * @returns A promise that resolves to the active saved view options.
+     */
+    async getViewOptions() {
+        return this.viewOptionsClient.getViewOptions();
+    }
+    /**
+     * Sets saved options for a view.
+     *
+     * @param args - The saved view options to set.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves when the view options are saved.
+     */
+    async setViewOptions(args, requestId) {
+        return this.viewOptionsClient.setViewOptions(args, requestId);
+    }
+    /**
+     * Deletes the saved options for a view.
+     *
+     * @param args - The view whose saved options to delete.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves when the view options are deleted.
+     */
+    async deleteViewOptions(args, requestId) {
+        return this.viewOptionsClient.deleteViewOptions(args, requestId);
+    }
     /**
      * Retrieves information about the authenticated user.
      *

package/dist/cjs/types/sync/resources/view-options.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProjectViewOptionsDefaultsSchema = exports.ViewOptionsSchema = exports.CalendarSettingsSchema = exports.CALENDAR_LAYOUTS = exports.SortOrderSchema = exports.SORT_ORDERS = exports.SortedBySchema = exports.SORTED_BY_OPTIONS = exports.GroupedBySchema = exports.GROUPED_BY_OPTIONS = exports.ViewModeSchema = exports.VIEW_MODES = exports.ViewTypeSchema = exports.VIEW_TYPES = void 0;
+exports.ProjectViewOptionsDefaultsSchema = exports.ViewOptionsSchema = exports.CalendarSettingsSchema = exports.CALENDAR_COLORS = exports.CALENDAR_LAYOUTS = exports.SortOrderSchema = exports.SORT_ORDERS = exports.SortedBySchema = exports.SORTED_BY_OPTIONS = exports.GroupedBySchema = exports.GROUPED_BY_OPTIONS = exports.ViewModeSchema = exports.VIEW_MODES = exports.ViewTypeSchema = exports.VIEW_TYPES = void 0;
 const zod_1 = require("zod");
 /** Available view types. */
 exports.VIEW_TYPES = [
@@ -52,18 +52,27 @@ exports.SORT_ORDERS = ['ASC', 'DESC'];
 exports.SortOrderSchema = zod_1.z.enum(exports.SORT_ORDERS).nullable();
 /** Available calendar layout modes. */
 exports.CALENDAR_LAYOUTS = ['WEEK', 'MONTH'];
+/** Available task color sources for calendar views. */
+exports.CALENDAR_COLORS = ['PRIORITY', 'LABEL', 'PROJECT'];
 exports.CalendarSettingsSchema = zod_1.z.looseObject({
-    layout: zod_1.z.enum(exports.CALENDAR_LAYOUTS).optional(),
+    layout: zod_1.z.enum(exports.CALENDAR_LAYOUTS).nullable().optional(),
+    visibleDayCount: zod_1.z
+        .union([zod_1.z.literal(1), zod_1.z.literal(3), zod_1.z.literal(7)])
+        .nullable()
+        .optional(),
+    color: zod_1.z.enum(exports.CALENDAR_COLORS).nullable().optional(),
 });
 exports.ViewOptionsSchema = zod_1.z.looseObject({
     viewType: exports.ViewTypeSchema,
-    objectId: zod_1.z.string().optional(),
+    objectId: zod_1.z.string().nullable().optional(),
     groupedBy: exports.GroupedBySchema.optional(),
     filteredBy: zod_1.z.string().nullable().optional(),
-    viewMode: exports.ViewModeSchema.optional(),
+    viewMode: exports.ViewModeSchema.nullable().optional(),
     showCompletedTasks: zod_1.z.boolean().optional(),
     sortedBy: exports.SortedBySchema.optional(),
     sortOrder: exports.SortOrderSchema.optional(),
+    calendarSettings: exports.CalendarSettingsSchema.nullable().optional(),
+    isDeleted: zod_1.z.boolean().optional(),
 });
 exports.ProjectViewOptionsDefaultsSchema = zod_1.z.looseObject({
     projectId: zod_1.z.string(),

package/dist/cjs/utils/index.js

@@ -24,6 +24,8 @@ Object.defineProperty(exports, "getSectionUrl", { enumerable: true, get: functio
 var sync_helpers_1 = require("./sync-helpers");
 Object.defineProperty(exports, "createCommand", { enumerable: true, get: function () { return sync_helpers_1.createCommand; } });
 __exportStar(require("./project-helpers"), exports);
+__exportStar(require("./task-sorting"), exports);
+__exportStar(require("./view-options"), exports);
 var webhook_parser_1 = require("./webhook-parser");
 Object.defineProperty(exports, "parseWebhookPayload", { enumerable: true, get: function () { return webhook_parser_1.parseWebhookPayload; } });
 Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_parser_1.verifyWebhookSignature; } });

package/dist/cjs/utils/task-sorting.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TASK_ORDERS = void 0;
+exports.sortTasks = sortTasks;
+/** Todoist's default task-ordering hierarchies. */
+exports.DEFAULT_TASK_ORDERS = ['PRIORITY_FIRST', 'DATE_FIRST'];
+const DEFAULT_TIMEZONE = 'UTC';
+const DEFAULT_LOCALE = 'en';
+const DATE_ONLY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?$/;
+const EXPLICIT_TIMEZONE_PATTERN = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+const DATE_TIME_FORMATTERS = new Map();
+function compareNumber(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+function isValidDateParts(year, month, day) {
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month - 1, day);
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day);
+}
+function dateSortValue({ year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0, isAllDay = false, }) {
+    if (!isValidDateParts(year, month, day) ||
+        hour < 0 ||
+        hour > 23 ||
+        minute < 0 ||
+        minute > 59 ||
+        second < 0 ||
+        second > 59 ||
+        millisecond < 0 ||
+        millisecond > 999) {
+        return null;
+    }
+    return {
+        day: year * 10000 + month * 100 + day,
+        kind: isAllDay ? 0 : 1,
+        time: ((hour * 60 + minute) * 60 + second) * 1000 + millisecond,
+    };
+}
+function parseDateOnly(value) {
+    const match = DATE_ONLY_PATTERN.exec(value);
+    if (!match)
+        return null;
+    return dateSortValue({
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        isAllDay: true,
+    });
+}
+function parseDateTimeComponents(value) {
+    var _a, _b;
+    const match = DATE_TIME_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const milliseconds = Number(((_a = match[7]) !== null && _a !== void 0 ? _a : '').padEnd(3, '0').slice(0, 3));
+    const components = {
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        hour: Number(match[4]),
+        minute: Number(match[5]),
+        second: Number((_b = match[6]) !== null && _b !== void 0 ? _b : 0),
+        millisecond: milliseconds,
+    };
+    return dateSortValue(components) === null ? null : components;
+}
+function createDateTimeFormatter(timezone, fallback) {
+    const cached = DATE_TIME_FORMATTERS.get(timezone);
+    if (cached)
+        return cached;
+    try {
+        const formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            calendar: 'iso8601',
+            numberingSystem: 'latn',
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hourCycle: 'h23',
+        });
+        DATE_TIME_FORMATTERS.set(timezone, formatter);
+        return formatter;
+    }
+    catch (_a) {
+        return fallback !== null && fallback !== void 0 ? fallback : createDateTimeFormatter(DEFAULT_TIMEZONE);
+    }
+}
+function componentsAt(timestamp, formatter) {
+    const parts = formatter.formatToParts(new Date(timestamp));
+    function part(type) {
+        var _a;
+        return Number((_a = parts.find((entry) => entry.type === type)) === null || _a === void 0 ? void 0 : _a.value);
+    }
+    return {
+        year: part('year'),
+        month: part('month'),
+        day: part('day'),
+        hour: part('hour'),
+        minute: part('minute'),
+        second: part('second'),
+        millisecond: new Date(timestamp).getUTCMilliseconds(),
+    };
+}
+function componentsAsUtcTimestamp({ year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0, }) {
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, millisecond);
+    return date.getTime();
+}
+/** Resolves a zoned wall clock to an instant, including daylight-saving offsets. */
+function timestampForWallClock(components, formatter) {
+    const target = componentsAsUtcTimestamp(components);
+    let timestamp = target;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const adjustment = target - componentsAsUtcTimestamp(componentsAt(timestamp, formatter));
+        if (adjustment === 0)
+            return timestamp;
+        timestamp += adjustment;
+    }
+    return null;
+}
+function dateSortValueAt(timestamp, formatter) {
+    const value = dateSortValue(componentsAt(timestamp, formatter));
+    return value ? Object.assign(Object.assign({}, value), { time: timestamp }) : null;
+}
+function parseFixedDateTime(value, formatter) {
+    if (parseDateTimeComponents(value.replace(EXPLICIT_TIMEZONE_PATTERN, '')) === null)
+        return null;
+    const timestamp = Date.parse(value);
+    return Number.isNaN(timestamp) ? null : dateSortValueAt(timestamp, formatter);
+}
+function parseZonedFloatingDateTime(value, sourceFormatter, accountFormatter) {
+    const components = parseDateTimeComponents(value);
+    if (!components)
+        return null;
+    const timestamp = timestampForWallClock(components, sourceFormatter);
+    return timestamp === null ? null : dateSortValueAt(timestamp, accountFormatter);
+}
+function parseTaskDate(value, formatter, timezone) {
+    var _a;
+    return ((_a = parseDateOnly(value)) !== null && _a !== void 0 ? _a : (EXPLICIT_TIMEZONE_PATTERN.test(value)
+        ? parseFixedDateTime(value, formatter)
+        : parseZonedFloatingDateTime(value, timezone ? createDateTimeFormatter(timezone, formatter) : formatter, formatter)));
+}
+function compareNullable(a, b, compare) {
+    if (a === null || b === null) {
+        if (a === b)
+            return 0;
+        return a === null ? 1 : -1;
+    }
+    return compare(a, b);
+}
+function compareDateValues(left, right) {
+    return (compareNumber(left.day, right.day) ||
+        compareNumber(left.kind, right.kind) ||
+        compareNumber(left.time, right.time));
+}
+function compareDate(a, b) {
+    return compareNullable(a, b, compareDateValues);
+}
+function compareOptionalNumber(a, b) {
+    return compareNullable(a, b, compareNumber);
+}
+function compareOptionalText(a, b, collator) {
+    return compareNullable(a, b, (left, right) => collator.compare(left, right));
+}
+function prepareTasks(tasks, context, { formatter, resolveAssignee }) {
+    return tasks.map((task, index) => {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const due = task.due
+            ? parseTaskDate((_a = task.due.datetime) !== null && _a !== void 0 ? _a : task.due.date, formatter, task.due.timezone)
+            : null;
+        const deadline = task.deadline ? parseTaskDate(task.deadline.date, formatter) : null;
+        return {
+            task,
+            index,
+            due,
+            deadline,
+            schedule: due !== null && due !== void 0 ? due : deadline,
+            added: task.addedAt && !Number.isNaN(task.addedAt.getTime())
+                ? task.addedAt.getTime()
+                : null,
+            project: (_c = (_b = context.projectOrder) === null || _b === void 0 ? void 0 : _b.get(task.projectId)) !== null && _c !== void 0 ? _c : null,
+            workspace: (_e = (_d = context.workspaceOrder) === null || _d === void 0 ? void 0 : _d.get(task.projectId)) !== null && _e !== void 0 ? _e : null,
+            assignee: resolveAssignee ? ((_g = (_f = context.assigneeName) === null || _f === void 0 ? void 0 : _f.call(context, task)) !== null && _g !== void 0 ? _g : null) : null,
+        };
+    });
+}
+function comparePriorityFirst(a, b) {
+    const common = compareNumber(b.task.priority, a.task.priority) ||
+        compareDate(a.due, b.due) ||
+        compareDate(a.deadline, b.deadline);
+    if (common !== 0)
+        return common;
+    const project = compareOptionalNumber(a.project, b.project);
+    if (project !== 0)
+        return project;
+    if (a.task.projectId === b.task.projectId) {
+        return compareNumber(a.task.childOrder, b.task.childOrder);
+    }
+    return 0;
+}
+function compareDateFirst(a, b) {
+    return (compareDate(a.schedule, b.schedule) ||
+        compareNumber(b.task.priority, a.task.priority) ||
+        compareDate(a.deadline, b.deadline) ||
+        compareNumber(a.task.dayOrder, b.task.dayOrder) ||
+        compareOptionalNumber(a.added, b.added));
+}
+function compareDefault(a, b, defaultOrder) {
+    return defaultOrder === 'DATE_FIRST' ? compareDateFirst(a, b) : comparePriorityFirst(a, b);
+}
+function comparePrimary({ sortedBy, a, b, collator, }) {
+    switch (sortedBy) {
+        case 'ALPHABETICALLY':
+            return collator.compare(a.task.content, b.task.content);
+        case 'ASSIGNEE':
+            return compareOptionalText(a.assignee, b.assignee, collator);
+        case 'DUE_DATE':
+            return compareDate(a.due, b.due);
+        case 'DEADLINE':
+            return compareDate(a.deadline, b.deadline);
+        case 'ADDED_DATE':
+            return compareOptionalNumber(a.added, b.added);
+        case 'PRIORITY':
+            return compareNumber(a.task.priority, b.task.priority);
+        case 'PROJECT':
+            return compareOptionalNumber(a.project, b.project);
+        case 'WORKSPACE':
+            return compareOptionalNumber(a.workspace, b.workspace);
+        case 'MANUAL':
+            return 0;
+    }
+}
+function defaultSortOrder(sortedBy) {
+    return sortedBy === 'PRIORITY' ? 'DESC' : 'ASC';
+}
+/**
+ * Sorts the supplied tasks using Todoist view-ordering rules.
+ *
+ * The function performs no I/O and always returns a new array. Exact project,
+ * workspace, assignee, localized text, and due-time ordering requires the
+ * corresponding context. Callers must sort each independent view section or
+ * group separately and preserve any subtask structure they render.
+ *
+ * This function sorts only the tasks supplied to it. Fetch every page first
+ * when globally correct ordering is required for a paginated query.
+ */
+function sortTasks(tasks, options, context = {}) {
+    var _a, _b, _c;
+    const locale = Array.isArray(context.locale)
+        ? [...context.locale]
+        : ((_a = context.locale) !== null && _a !== void 0 ? _a : DEFAULT_LOCALE);
+    const collator = new Intl.Collator(locale, { sensitivity: 'base', numeric: true });
+    const formatter = createDateTimeFormatter((_b = context.timezone) !== null && _b !== void 0 ? _b : DEFAULT_TIMEZONE);
+    const sortedBy = options.sortedBy;
+    const prepared = prepareTasks(tasks, context, {
+        formatter,
+        resolveAssignee: sortedBy === 'ASSIGNEE',
+    });
+    const direction = sortedBy && sortedBy !== 'MANUAL' ? ((_c = options.sortOrder) !== null && _c !== void 0 ? _c : defaultSortOrder(sortedBy)) : null;
+    const directionMultiplier = direction === 'DESC' ? -1 : 1;
+    return prepared
+        .sort((a, b) => {
+        if (sortedBy && sortedBy !== 'MANUAL') {
+            const primary = comparePrimary({ sortedBy, a, b, collator }) * directionMultiplier;
+            if (primary !== 0)
+                return primary;
+        }
+        return compareDefault(a, b, options.defaultOrder) || compareNumber(a.index, b.index);
+    })
+        .map(({ task }) => task);
+}

package/dist/cjs/utils/view-options.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isActiveViewOption = isActiveViewOption;
+exports.findViewOptions = findViewOptions;
+/** Returns whether saved view options are active rather than a deletion tombstone. */
+function isActiveViewOption(options) {
+    return options.isDeleted !== true;
+}
+/** Finds the active saved options for one logical view. */
+function findViewOptions(options, args) {
+    var _a;
+    const targetObjectId = (_a = args.objectId) !== null && _a !== void 0 ? _a : null;
+    return options.find((entry) => {
+        var _a;
+        return isActiveViewOption(entry) &&
+            ((_a = entry.objectId) !== null && _a !== void 0 ? _a : null) === targetObjectId &&
+            args.viewTypes.includes(entry.viewType);
+    });
+}

package/dist/esm/clients/view-options-client.js

@@ -0,0 +1,21 @@
+import { performSyncRequest } from '../transport/sync-request.js';
+import { createCommand } from '../utils/sync-helpers.js';
+import { isActiveViewOption } from '../utils/view-options.js';
+import { BaseClient } from './base-client.js';
+/** Internal sub-client for saved view-option reads and writes. */
+export class ViewOptionsClient extends BaseClient {
+    async getViewOptions() {
+        var _a;
+        const response = await performSyncRequest(this.syncContext, {
+            resourceTypes: ['view_options'],
+            syncToken: '*',
+        });
+        return ((_a = response.viewOptions) !== null && _a !== void 0 ? _a : []).filter(isActiveViewOption);
+    }
+    async setViewOptions(args, requestId) {
+        await performSyncRequest(this.syncContext, { commands: [createCommand('view_options_set', args)] }, { requestId, hasSyncCommands: true });
+    }
+    async deleteViewOptions(args, requestId) {
+        await performSyncRequest(this.syncContext, { commands: [createCommand('view_options_delete', args)] }, { requestId, hasSyncCommands: true });
+    }
+}

package/dist/esm/todoist-api.js

@@ -16,6 +16,7 @@ import { TaskClient } from './clients/task-client.js';
 import { TemplateClient } from './clients/template-client.js';
 import { UiExtensionClient } from './clients/ui-extension-client.js';
 import { UploadClient } from './clients/upload-client.js';
+import { ViewOptionsClient } from './clients/view-options-client.js';
 import { WorkspaceClient } from './clients/workspace-client.js';
 import { ENDPOINT_REST_USER, getSyncBaseUri } from './consts/endpoints.js';
 import { request } from './transport/http-client.js';
@@ -62,6 +63,7 @@ export class TodoistApi {
         this.billingClient = new BillingClient(clientDeps);
         this.appClient = new AppClient(clientDeps);
         this.uiExtensionClient = new UiExtensionClient(clientDeps);
+        this.viewOptionsClient = new ViewOptionsClient(clientDeps);
     }
     /**
      * Executes a raw Sync API request.
@@ -95,6 +97,34 @@ export class TodoistApi {
             customFetch: this.customFetch,
         }, syncRequest, { requestId, hasSyncCommands: Boolean((_a = syncRequest.commands) === null || _a === void 0 ? void 0 : _a.length) });
     }
+    /**
+     * Retrieves the authenticated user's active saved view options.
+     *
+     * @returns A promise that resolves to the active saved view options.
+     */
+    async getViewOptions() {
+        return this.viewOptionsClient.getViewOptions();
+    }
+    /**
+     * Sets saved options for a view.
+     *
+     * @param args - The saved view options to set.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves when the view options are saved.
+     */
+    async setViewOptions(args, requestId) {
+        return this.viewOptionsClient.setViewOptions(args, requestId);
+    }
+    /**
+     * Deletes the saved options for a view.
+     *
+     * @param args - The view whose saved options to delete.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves when the view options are deleted.
+     */
+    async deleteViewOptions(args, requestId) {
+        return this.viewOptionsClient.deleteViewOptions(args, requestId);
+    }
     /**
      * Retrieves information about the authenticated user.
      *

package/dist/esm/types/sync/resources/view-options.js

@@ -49,18 +49,27 @@ export const SORT_ORDERS = ['ASC', 'DESC'];
 export const SortOrderSchema = z.enum(SORT_ORDERS).nullable();
 /** Available calendar layout modes. */
 export const CALENDAR_LAYOUTS = ['WEEK', 'MONTH'];
+/** Available task color sources for calendar views. */
+export const CALENDAR_COLORS = ['PRIORITY', 'LABEL', 'PROJECT'];
 export const CalendarSettingsSchema = z.looseObject({
-    layout: z.enum(CALENDAR_LAYOUTS).optional(),
+    layout: z.enum(CALENDAR_LAYOUTS).nullable().optional(),
+    visibleDayCount: z
+        .union([z.literal(1), z.literal(3), z.literal(7)])
+        .nullable()
+        .optional(),
+    color: z.enum(CALENDAR_COLORS).nullable().optional(),
 });
 export const ViewOptionsSchema = z.looseObject({
     viewType: ViewTypeSchema,
-    objectId: z.string().optional(),
+    objectId: z.string().nullable().optional(),
     groupedBy: GroupedBySchema.optional(),
     filteredBy: z.string().nullable().optional(),
-    viewMode: ViewModeSchema.optional(),
+    viewMode: ViewModeSchema.nullable().optional(),
     showCompletedTasks: z.boolean().optional(),
     sortedBy: SortedBySchema.optional(),
     sortOrder: SortOrderSchema.optional(),
+    calendarSettings: CalendarSettingsSchema.nullable().optional(),
+    isDeleted: z.boolean().optional(),
 });
 export const ProjectViewOptionsDefaultsSchema = z.looseObject({
     projectId: z.string(),

package/dist/esm/utils/index.js

@@ -3,4 +3,6 @@ export * from './sanitization.js';
 export { getTaskUrl, getProjectUrl, getSectionUrl } from './url-helpers.js';
 export { createCommand } from './sync-helpers.js';
 export * from './project-helpers.js';
+export * from './task-sorting.js';
+export * from './view-options.js';
 export { parseWebhookPayload, verifyWebhookSignature } from './webhook-parser.js';

package/dist/esm/utils/task-sorting.js

@@ -0,0 +1,277 @@
+/** Todoist's default task-ordering hierarchies. */
+export const DEFAULT_TASK_ORDERS = ['PRIORITY_FIRST', 'DATE_FIRST'];
+const DEFAULT_TIMEZONE = 'UTC';
+const DEFAULT_LOCALE = 'en';
+const DATE_ONLY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?$/;
+const EXPLICIT_TIMEZONE_PATTERN = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+const DATE_TIME_FORMATTERS = new Map();
+function compareNumber(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+function isValidDateParts(year, month, day) {
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month - 1, day);
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day);
+}
+function dateSortValue({ year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0, isAllDay = false, }) {
+    if (!isValidDateParts(year, month, day) ||
+        hour < 0 ||
+        hour > 23 ||
+        minute < 0 ||
+        minute > 59 ||
+        second < 0 ||
+        second > 59 ||
+        millisecond < 0 ||
+        millisecond > 999) {
+        return null;
+    }
+    return {
+        day: year * 10000 + month * 100 + day,
+        kind: isAllDay ? 0 : 1,
+        time: ((hour * 60 + minute) * 60 + second) * 1000 + millisecond,
+    };
+}
+function parseDateOnly(value) {
+    const match = DATE_ONLY_PATTERN.exec(value);
+    if (!match)
+        return null;
+    return dateSortValue({
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        isAllDay: true,
+    });
+}
+function parseDateTimeComponents(value) {
+    var _a, _b;
+    const match = DATE_TIME_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const milliseconds = Number(((_a = match[7]) !== null && _a !== void 0 ? _a : '').padEnd(3, '0').slice(0, 3));
+    const components = {
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        hour: Number(match[4]),
+        minute: Number(match[5]),
+        second: Number((_b = match[6]) !== null && _b !== void 0 ? _b : 0),
+        millisecond: milliseconds,
+    };
+    return dateSortValue(components) === null ? null : components;
+}
+function createDateTimeFormatter(timezone, fallback) {
+    const cached = DATE_TIME_FORMATTERS.get(timezone);
+    if (cached)
+        return cached;
+    try {
+        const formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            calendar: 'iso8601',
+            numberingSystem: 'latn',
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hourCycle: 'h23',
+        });
+        DATE_TIME_FORMATTERS.set(timezone, formatter);
+        return formatter;
+    }
+    catch (_a) {
+        return fallback !== null && fallback !== void 0 ? fallback : createDateTimeFormatter(DEFAULT_TIMEZONE);
+    }
+}
+function componentsAt(timestamp, formatter) {
+    const parts = formatter.formatToParts(new Date(timestamp));
+    function part(type) {
+        var _a;
+        return Number((_a = parts.find((entry) => entry.type === type)) === null || _a === void 0 ? void 0 : _a.value);
+    }
+    return {
+        year: part('year'),
+        month: part('month'),
+        day: part('day'),
+        hour: part('hour'),
+        minute: part('minute'),
+        second: part('second'),
+        millisecond: new Date(timestamp).getUTCMilliseconds(),
+    };
+}
+function componentsAsUtcTimestamp({ year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0, }) {
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, millisecond);
+    return date.getTime();
+}
+/** Resolves a zoned wall clock to an instant, including daylight-saving offsets. */
+function timestampForWallClock(components, formatter) {
+    const target = componentsAsUtcTimestamp(components);
+    let timestamp = target;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const adjustment = target - componentsAsUtcTimestamp(componentsAt(timestamp, formatter));
+        if (adjustment === 0)
+            return timestamp;
+        timestamp += adjustment;
+    }
+    return null;
+}
+function dateSortValueAt(timestamp, formatter) {
+    const value = dateSortValue(componentsAt(timestamp, formatter));
+    return value ? Object.assign(Object.assign({}, value), { time: timestamp }) : null;
+}
+function parseFixedDateTime(value, formatter) {
+    if (parseDateTimeComponents(value.replace(EXPLICIT_TIMEZONE_PATTERN, '')) === null)
+        return null;
+    const timestamp = Date.parse(value);
+    return Number.isNaN(timestamp) ? null : dateSortValueAt(timestamp, formatter);
+}
+function parseZonedFloatingDateTime(value, sourceFormatter, accountFormatter) {
+    const components = parseDateTimeComponents(value);
+    if (!components)
+        return null;
+    const timestamp = timestampForWallClock(components, sourceFormatter);
+    return timestamp === null ? null : dateSortValueAt(timestamp, accountFormatter);
+}
+function parseTaskDate(value, formatter, timezone) {
+    var _a;
+    return ((_a = parseDateOnly(value)) !== null && _a !== void 0 ? _a : (EXPLICIT_TIMEZONE_PATTERN.test(value)
+        ? parseFixedDateTime(value, formatter)
+        : parseZonedFloatingDateTime(value, timezone ? createDateTimeFormatter(timezone, formatter) : formatter, formatter)));
+}
+function compareNullable(a, b, compare) {
+    if (a === null || b === null) {
+        if (a === b)
+            return 0;
+        return a === null ? 1 : -1;
+    }
+    return compare(a, b);
+}
+function compareDateValues(left, right) {
+    return (compareNumber(left.day, right.day) ||
+        compareNumber(left.kind, right.kind) ||
+        compareNumber(left.time, right.time));
+}
+function compareDate(a, b) {
+    return compareNullable(a, b, compareDateValues);
+}
+function compareOptionalNumber(a, b) {
+    return compareNullable(a, b, compareNumber);
+}
+function compareOptionalText(a, b, collator) {
+    return compareNullable(a, b, (left, right) => collator.compare(left, right));
+}
+function prepareTasks(tasks, context, { formatter, resolveAssignee }) {
+    return tasks.map((task, index) => {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const due = task.due
+            ? parseTaskDate((_a = task.due.datetime) !== null && _a !== void 0 ? _a : task.due.date, formatter, task.due.timezone)
+            : null;
+        const deadline = task.deadline ? parseTaskDate(task.deadline.date, formatter) : null;
+        return {
+            task,
+            index,
+            due,
+            deadline,
+            schedule: due !== null && due !== void 0 ? due : deadline,
+            added: task.addedAt && !Number.isNaN(task.addedAt.getTime())
+                ? task.addedAt.getTime()
+                : null,
+            project: (_c = (_b = context.projectOrder) === null || _b === void 0 ? void 0 : _b.get(task.projectId)) !== null && _c !== void 0 ? _c : null,
+            workspace: (_e = (_d = context.workspaceOrder) === null || _d === void 0 ? void 0 : _d.get(task.projectId)) !== null && _e !== void 0 ? _e : null,
+            assignee: resolveAssignee ? ((_g = (_f = context.assigneeName) === null || _f === void 0 ? void 0 : _f.call(context, task)) !== null && _g !== void 0 ? _g : null) : null,
+        };
+    });
+}
+function comparePriorityFirst(a, b) {
+    const common = compareNumber(b.task.priority, a.task.priority) ||
+        compareDate(a.due, b.due) ||
+        compareDate(a.deadline, b.deadline);
+    if (common !== 0)
+        return common;
+    const project = compareOptionalNumber(a.project, b.project);
+    if (project !== 0)
+        return project;
+    if (a.task.projectId === b.task.projectId) {
+        return compareNumber(a.task.childOrder, b.task.childOrder);
+    }
+    return 0;
+}
+function compareDateFirst(a, b) {
+    return (compareDate(a.schedule, b.schedule) ||
+        compareNumber(b.task.priority, a.task.priority) ||
+        compareDate(a.deadline, b.deadline) ||
+        compareNumber(a.task.dayOrder, b.task.dayOrder) ||
+        compareOptionalNumber(a.added, b.added));
+}
+function compareDefault(a, b, defaultOrder) {
+    return defaultOrder === 'DATE_FIRST' ? compareDateFirst(a, b) : comparePriorityFirst(a, b);
+}
+function comparePrimary({ sortedBy, a, b, collator, }) {
+    switch (sortedBy) {
+        case 'ALPHABETICALLY':
+            return collator.compare(a.task.content, b.task.content);
+        case 'ASSIGNEE':
+            return compareOptionalText(a.assignee, b.assignee, collator);
+        case 'DUE_DATE':
+            return compareDate(a.due, b.due);
+        case 'DEADLINE':
+            return compareDate(a.deadline, b.deadline);
+        case 'ADDED_DATE':
+            return compareOptionalNumber(a.added, b.added);
+        case 'PRIORITY':
+            return compareNumber(a.task.priority, b.task.priority);
+        case 'PROJECT':
+            return compareOptionalNumber(a.project, b.project);
+        case 'WORKSPACE':
+            return compareOptionalNumber(a.workspace, b.workspace);
+        case 'MANUAL':
+            return 0;
+    }
+}
+function defaultSortOrder(sortedBy) {
+    return sortedBy === 'PRIORITY' ? 'DESC' : 'ASC';
+}
+/**
+ * Sorts the supplied tasks using Todoist view-ordering rules.
+ *
+ * The function performs no I/O and always returns a new array. Exact project,
+ * workspace, assignee, localized text, and due-time ordering requires the
+ * corresponding context. Callers must sort each independent view section or
+ * group separately and preserve any subtask structure they render.
+ *
+ * This function sorts only the tasks supplied to it. Fetch every page first
+ * when globally correct ordering is required for a paginated query.
+ */
+export function sortTasks(tasks, options, context = {}) {
+    var _a, _b, _c;
+    const locale = Array.isArray(context.locale)
+        ? [...context.locale]
+        : ((_a = context.locale) !== null && _a !== void 0 ? _a : DEFAULT_LOCALE);
+    const collator = new Intl.Collator(locale, { sensitivity: 'base', numeric: true });
+    const formatter = createDateTimeFormatter((_b = context.timezone) !== null && _b !== void 0 ? _b : DEFAULT_TIMEZONE);
+    const sortedBy = options.sortedBy;
+    const prepared = prepareTasks(tasks, context, {
+        formatter,
+        resolveAssignee: sortedBy === 'ASSIGNEE',
+    });
+    const direction = sortedBy && sortedBy !== 'MANUAL' ? ((_c = options.sortOrder) !== null && _c !== void 0 ? _c : defaultSortOrder(sortedBy)) : null;
+    const directionMultiplier = direction === 'DESC' ? -1 : 1;
+    return prepared
+        .sort((a, b) => {
+        if (sortedBy && sortedBy !== 'MANUAL') {
+            const primary = comparePrimary({ sortedBy, a, b, collator }) * directionMultiplier;
+            if (primary !== 0)
+                return primary;
+        }
+        return compareDefault(a, b, options.defaultOrder) || compareNumber(a.index, b.index);
+    })
+        .map(({ task }) => task);
+}

package/dist/esm/utils/view-options.js

@@ -0,0 +1,15 @@
+/** Returns whether saved view options are active rather than a deletion tombstone. */
+export function isActiveViewOption(options) {
+    return options.isDeleted !== true;
+}
+/** Finds the active saved options for one logical view. */
+export function findViewOptions(options, args) {
+    var _a;
+    const targetObjectId = (_a = args.objectId) !== null && _a !== void 0 ? _a : null;
+    return options.find((entry) => {
+        var _a;
+        return isActiveViewOption(entry) &&
+            ((_a = entry.objectId) !== null && _a !== void 0 ? _a : null) === targetObjectId &&
+            args.viewTypes.includes(entry.viewType);
+    });
+}

package/dist/types/clients/view-options-client.d.ts

@@ -0,0 +1,8 @@
+import type { ViewOptions, ViewOptionsDeleteArgs, ViewOptionsSetArgs } from '../types/sync/index.js';
+import { BaseClient } from './base-client.js';
+/** Internal sub-client for saved view-option reads and writes. */
+export declare class ViewOptionsClient extends BaseClient {
+    getViewOptions(): Promise<ViewOptions[]>;
+    setViewOptions(args: ViewOptionsSetArgs, requestId?: string): Promise<void>;
+    deleteViewOptions(args: ViewOptionsDeleteArgs, requestId?: string): Promise<void>;
+}

package/dist/types/todoist-api.d.ts

@@ -14,6 +14,7 @@ import { ProductivityStats } from './types/productivity/index.js';
 import { PersonalProject, WorkspaceProject, AddProjectArgs, UpdateProjectArgs, GetProjectsArgs, SearchProjectsArgs, GetProjectCollaboratorsArgs, GetProjectsResponse, GetProjectCollaboratorsResponse, GetArchivedProjectsArgs, GetArchivedProjectsResponse, MoveProjectToWorkspaceArgs, MoveProjectToPersonalArgs, GetArchivedProjectsCountArgs, GetArchivedProjectsCountResponse, GetProjectPermissionsResponse, GetFullProjectArgs, GetFullProjectResponse, JoinProjectResponse } from './types/projects/index.js';
 import { AddReminderArgs, UpdateReminderArgs, AddLocationReminderArgs, UpdateLocationReminderArgs, GetRemindersArgs, GetRemindersResponse, GetLocationRemindersArgs, GetLocationRemindersResponse } from './types/reminders/index.js';
 import { Section, AddSectionArgs, UpdateSectionArgs, GetSectionsArgs, SearchSectionsArgs, GetSectionsResponse } from './types/sections/index.js';
+import type { SyncRequest, SyncResponse, ViewOptions, ViewOptionsDeleteArgs, ViewOptionsSetArgs } from './types/sync/index.js';
 import type { Folder } from './types/sync/resources/folders.js';
 import { Task, AddTaskArgs, GetTasksArgs, GetTasksByFilterArgs, UpdateTaskArgs, QuickAddTaskArgs, type MoveTaskArgs, GetCompletedTasksByCompletionDateArgs, GetCompletedTasksByDueDateArgs, GetCompletedTasksResponse, SearchCompletedTasksArgs, GetTasksResponse, GetAllCompletedTasksArgs, GetAllCompletedTasksResponse } from './types/tasks/index.js';
 import { ExportTemplateFileArgs, ExportTemplateUrlArgs, ExportTemplateUrlResponse, CreateProjectFromTemplateArgs, CreateProjectFromTemplateResponse, ImportTemplateIntoProjectArgs, ImportTemplateFromIdArgs, ImportTemplateResponse } from './types/templates/index.js';
@@ -21,7 +22,6 @@ import type { AddUiExtensionArgs, UiExtension, UpdateUiExtensionArgs, UploadUiEx
 import { UploadFileArgs, DeleteUploadArgs } from './types/uploads/index.js';
 import { CurrentUser } from './types/users/index.js';
 import { WorkspaceInvitation, WorkspacePlanDetails, JoinWorkspaceResult, Workspace, AddWorkspaceArgs, UpdateWorkspaceArgs, GetWorkspaceMembersActivityArgs, GetWorkspaceMembersActivityResponse, GetWorkspaceUserTasksArgs, GetWorkspaceUserTasksResponse, InviteWorkspaceUsersArgs, InviteWorkspaceUsersResponse, UpdateWorkspaceUserArgs, RemoveWorkspaceUserArgs, GetWorkspaceInvitationsArgs, DeleteWorkspaceInvitationArgs, WorkspaceInvitationActionArgs, JoinWorkspaceArgs, WorkspaceLogoArgs, GetWorkspacePlanDetailsArgs, GetWorkspaceUsersArgs, GetWorkspaceUsersResponse, GetWorkspaceProjectsArgs, WorkspaceInvitationsResponse, AllWorkspaceInvitationsResponse, WorkspaceLogoResponse } from './types/workspaces/index.js';
-import { type SyncResponse, type SyncRequest } from './types/sync/index.js';
 /**
  * A client for interacting with the Todoist API v1.
  * This class provides methods to manage tasks, projects, sections, labels, and comments in Todoist.
@@ -79,6 +79,7 @@ export declare class TodoistApi {
     private readonly billingClient;
     private readonly appClient;
     private readonly uiExtensionClient;
+    private readonly viewOptionsClient;
     constructor(
     /**
      * Your Todoist API token.
@@ -113,6 +114,28 @@ export declare class TodoistApi {
      * ```
      */
     sync(syncRequest: SyncRequest, requestId?: string): Promise<SyncResponse>;
+    /**
+     * Retrieves the authenticated user's active saved view options.
+     *
+     * @returns A promise that resolves to the active saved view options.
+     */
+    getViewOptions(): Promise<ViewOptions[]>;
+    /**
+     * Sets saved options for a view.
+     *
+     * @param args - The saved view options to set.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves when the view options are saved.
+     */
+    setViewOptions(args: ViewOptionsSetArgs, requestId?: string): Promise<void>;
+    /**
+     * Deletes the saved options for a view.
+     *
+     * @param args - The view whose saved options to delete.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves when the view options are deleted.
+     */
+    deleteViewOptions(args: ViewOptionsDeleteArgs, requestId?: string): Promise<void>;
     /**
      * Retrieves information about the authenticated user.
      *

package/dist/types/types/sync/commands/project-view-options.d.ts

@@ -1,7 +1,4 @@
-import type { ViewMode, GroupedBy, SortedBy, SortOrder, CalendarLayout } from '../resources/view-options.js';
-export type CalendarSettings = {
-    layout?: CalendarLayout;
-};
+import type { CalendarSettings, ViewMode, GroupedBy, SortedBy, SortOrder } from '../resources/view-options.js';
 export type ProjectViewOptionsDefaultsSetArgs = {
     projectId: string;
     viewMode?: ViewMode | null;

package/dist/types/types/sync/commands/view-options.d.ts

@@ -1,4 +1,4 @@
-import type { ViewType, ViewMode, GroupedBy, SortedBy, SortOrder } from '../resources/view-options.js';
+import type { CalendarSettings, GroupedBy, SortedBy, SortOrder, ViewMode, ViewType } from '../resources/view-options.js';
 export type ViewOptionsSetArgs = {
     viewType: ViewType;
     objectId?: string;
@@ -8,6 +8,7 @@ export type ViewOptionsSetArgs = {
     showCompletedTasks?: boolean;
     sortedBy?: SortedBy | null;
     sortOrder?: SortOrder | null;
+    calendarSettings?: CalendarSettings | null;
 };
 export type ViewOptionsDeleteArgs = {
     viewType: ViewType;

package/dist/types/types/sync/resources/view-options.d.ts

@@ -68,12 +68,23 @@ export declare const SortOrderSchema: z.ZodNullable<z.ZodEnum<{
 export declare const CALENDAR_LAYOUTS: readonly ["WEEK", "MONTH"];
 /** Calendar layout mode. */
 export type CalendarLayout = (typeof CALENDAR_LAYOUTS)[number];
+/** Available task color sources for calendar views. */
+export declare const CALENDAR_COLORS: readonly ["PRIORITY", "LABEL", "PROJECT"];
+/** Task color source for a calendar view. */
+export type CalendarColor = (typeof CALENDAR_COLORS)[number];
 export declare const CalendarSettingsSchema: z.ZodObject<{
-    layout: z.ZodOptional<z.ZodEnum<{
+    layout: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         WEEK: "WEEK";
         MONTH: "MONTH";
-    }>>;
+    }>>>;
+    visibleDayCount: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<3>, z.ZodLiteral<7>]>>>;
+    color: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        PROJECT: "PROJECT";
+        LABEL: "LABEL";
+        PRIORITY: "PRIORITY";
+    }>>>;
 }, z.core.$loose>;
+export type CalendarSettings = z.infer<typeof CalendarSettingsSchema>;
 export declare const ViewOptionsSchema: z.ZodObject<{
     viewType: z.ZodEnum<{
         PROJECT: "PROJECT";
@@ -90,7 +101,7 @@ export declare const ViewOptionsSchema: z.ZodObject<{
         OVERDUE: "OVERDUE";
         WORKSPACE_OVERVIEW: "WORKSPACE_OVERVIEW";
     }>;
-    objectId: z.ZodOptional<z.ZodString>;
+    objectId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     groupedBy: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         PROJECT: "PROJECT";
         LABEL: "LABEL";
@@ -102,11 +113,11 @@ export declare const ViewOptionsSchema: z.ZodObject<{
         WORKSPACE: "WORKSPACE";
     }>>>;
     filteredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    viewMode: z.ZodOptional<z.ZodEnum<{
+    viewMode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         LIST: "LIST";
         BOARD: "BOARD";
         CALENDAR: "CALENDAR";
-    }>>;
+    }>>>;
     showCompletedTasks: z.ZodOptional<z.ZodBoolean>;
     sortedBy: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         PROJECT: "PROJECT";
@@ -123,6 +134,19 @@ export declare const ViewOptionsSchema: z.ZodObject<{
         ASC: "ASC";
         DESC: "DESC";
     }>>>;
+    calendarSettings: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        layout: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            WEEK: "WEEK";
+            MONTH: "MONTH";
+        }>>>;
+        visibleDayCount: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<3>, z.ZodLiteral<7>]>>>;
+        color: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            PROJECT: "PROJECT";
+            LABEL: "LABEL";
+            PRIORITY: "PRIORITY";
+        }>>>;
+    }, z.core.$loose>>>;
+    isDeleted: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export type ViewOptions = z.infer<typeof ViewOptionsSchema>;
 export declare const ProjectViewOptionsDefaultsSchema: z.ZodObject<{
@@ -160,10 +184,16 @@ export declare const ProjectViewOptionsDefaultsSchema: z.ZodObject<{
     showCompletedTasks: z.ZodOptional<z.ZodBoolean>;
     filteredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     calendarSettings: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-        layout: z.ZodOptional<z.ZodEnum<{
+        layout: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             WEEK: "WEEK";
             MONTH: "MONTH";
-        }>>;
+        }>>>;
+        visibleDayCount: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<3>, z.ZodLiteral<7>]>>>;
+        color: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            PROJECT: "PROJECT";
+            LABEL: "LABEL";
+            PRIORITY: "PRIORITY";
+        }>>>;
     }, z.core.$loose>>>;
 }, z.core.$loose>;
 export type ProjectViewOptionsDefaults = z.infer<typeof ProjectViewOptionsDefaultsSchema>;

package/dist/types/types/sync/response.d.ts

@@ -751,7 +751,7 @@ export declare const SyncResponseSchema: z.ZodObject<{
             OVERDUE: "OVERDUE";
             WORKSPACE_OVERVIEW: "WORKSPACE_OVERVIEW";
         }>;
-        objectId: z.ZodOptional<z.ZodString>;
+        objectId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         groupedBy: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             PROJECT: "PROJECT";
             LABEL: "LABEL";
@@ -763,11 +763,11 @@ export declare const SyncResponseSchema: z.ZodObject<{
             WORKSPACE: "WORKSPACE";
         }>>>;
         filteredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        viewMode: z.ZodOptional<z.ZodEnum<{
+        viewMode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             LIST: "LIST";
             BOARD: "BOARD";
             CALENDAR: "CALENDAR";
-        }>>;
+        }>>>;
         showCompletedTasks: z.ZodOptional<z.ZodBoolean>;
         sortedBy: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             PROJECT: "PROJECT";
@@ -784,6 +784,19 @@ export declare const SyncResponseSchema: z.ZodObject<{
             ASC: "ASC";
             DESC: "DESC";
         }>>>;
+        calendarSettings: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            layout: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                WEEK: "WEEK";
+                MONTH: "MONTH";
+            }>>>;
+            visibleDayCount: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<3>, z.ZodLiteral<7>]>>>;
+            color: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                PROJECT: "PROJECT";
+                LABEL: "LABEL";
+                PRIORITY: "PRIORITY";
+            }>>>;
+        }, z.core.$loose>>>;
+        isDeleted: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>>;
     projectViewOptionsDefaults: z.ZodOptional<z.ZodArray<z.ZodObject<{
         projectId: z.ZodString;
@@ -820,10 +833,16 @@ export declare const SyncResponseSchema: z.ZodObject<{
         showCompletedTasks: z.ZodOptional<z.ZodBoolean>;
         filteredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         calendarSettings: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-            layout: z.ZodOptional<z.ZodEnum<{
+            layout: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 WEEK: "WEEK";
                 MONTH: "MONTH";
-            }>>;
+            }>>>;
+            visibleDayCount: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<3>, z.ZodLiteral<7>]>>>;
+            color: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                PROJECT: "PROJECT";
+                LABEL: "LABEL";
+                PRIORITY: "PRIORITY";
+            }>>>;
         }, z.core.$loose>>>;
     }, z.core.$loose>>>;
     roleActions: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;

package/dist/types/utils/index.d.ts

@@ -3,5 +3,7 @@ export * from './sanitization.js';
 export { getTaskUrl, getProjectUrl, getSectionUrl } from './url-helpers.js';
 export { createCommand } from './sync-helpers.js';
 export * from './project-helpers.js';
+export * from './task-sorting.js';
+export * from './view-options.js';
 export { parseWebhookPayload, verifyWebhookSignature } from './webhook-parser.js';
 export type { VerifyWebhookSignatureArgs } from './webhook-parser.js';

package/dist/types/utils/task-sorting.d.ts

@@ -0,0 +1,38 @@
+import type { SortOrder, SortedBy } from '../types/sync/index.js';
+import type { Task } from '../types/tasks/index.js';
+/** Todoist's default task-ordering hierarchies. */
+export declare const DEFAULT_TASK_ORDERS: readonly ["PRIORITY_FIRST", "DATE_FIRST"];
+/** Default hierarchy used when a view has no named sorting. */
+export type DefaultTaskOrder = (typeof DEFAULT_TASK_ORDERS)[number];
+export type TaskSortOptions = {
+    /** Saved or requested sort field. Null and MANUAL use defaultOrder. */
+    sortedBy?: SortedBy | null;
+    /** Saved or requested direction. Defaults by field when absent. */
+    sortOrder?: SortOrder | null;
+    /** Default hierarchy for this view or filter query. */
+    defaultOrder: DefaultTaskOrder;
+};
+export type TaskSortContext = {
+    /** Project ID to its visible order. */
+    projectOrder?: ReadonlyMap<string, number>;
+    /** Project ID to the visible order of its workspace bucket. */
+    workspaceOrder?: ReadonlyMap<string, number>;
+    /** Resolves the display name used for assignee sorting. */
+    assigneeName?: (task: Task) => string | null | undefined;
+    /** Account IANA timezone. Defaults to UTC for deterministic behavior. */
+    timezone?: string;
+    /** Locale used for text comparisons. Defaults to English. */
+    locale?: string | readonly string[];
+};
+/**
+ * Sorts the supplied tasks using Todoist view-ordering rules.
+ *
+ * The function performs no I/O and always returns a new array. Exact project,
+ * workspace, assignee, localized text, and due-time ordering requires the
+ * corresponding context. Callers must sort each independent view section or
+ * group separately and preserve any subtask structure they render.
+ *
+ * This function sorts only the tasks supplied to it. Fetch every page first
+ * when globally correct ordering is required for a paginated query.
+ */
+export declare function sortTasks(tasks: readonly Task[], options: TaskSortOptions, context?: TaskSortContext): Task[];

package/dist/types/utils/validators.d.ts

@@ -1153,23 +1153,37 @@ export declare const validateCompletedInfo: (input: unknown) => {
 export declare const validateViewOptions: (input: unknown) => {
     [x: string]: unknown;
     viewType: "PROJECT" | "TODAY" | "UPCOMING" | "LABEL" | "FILTER" | "WORKSPACE_FILTER" | "SEARCH" | "TEMPLATE_PREVIEW" | "TASK_DETAIL" | "AUTOMATION" | "ASSIGNED" | "OVERDUE" | "WORKSPACE_OVERVIEW";
-    objectId?: string | undefined;
+    objectId?: string | null | undefined;
     groupedBy?: "PROJECT" | "LABEL" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | null | undefined;
     filteredBy?: string | null | undefined;
-    viewMode?: "LIST" | "BOARD" | "CALENDAR" | undefined;
+    viewMode?: "LIST" | "BOARD" | "CALENDAR" | null | undefined;
     showCompletedTasks?: boolean | undefined;
     sortedBy?: "PROJECT" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | "MANUAL" | "ALPHABETICALLY" | null | undefined;
     sortOrder?: "ASC" | "DESC" | null | undefined;
+    calendarSettings?: {
+        [x: string]: unknown;
+        layout?: "WEEK" | "MONTH" | null | undefined;
+        visibleDayCount?: 3 | 1 | 7 | null | undefined;
+        color?: "PROJECT" | "LABEL" | "PRIORITY" | null | undefined;
+    } | null | undefined;
+    isDeleted?: boolean | undefined;
 }, validateViewOptionsArray: (input: unknown) => {
     [x: string]: unknown;
     viewType: "PROJECT" | "TODAY" | "UPCOMING" | "LABEL" | "FILTER" | "WORKSPACE_FILTER" | "SEARCH" | "TEMPLATE_PREVIEW" | "TASK_DETAIL" | "AUTOMATION" | "ASSIGNED" | "OVERDUE" | "WORKSPACE_OVERVIEW";
-    objectId?: string | undefined;
+    objectId?: string | null | undefined;
     groupedBy?: "PROJECT" | "LABEL" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | null | undefined;
     filteredBy?: string | null | undefined;
-    viewMode?: "LIST" | "BOARD" | "CALENDAR" | undefined;
+    viewMode?: "LIST" | "BOARD" | "CALENDAR" | null | undefined;
     showCompletedTasks?: boolean | undefined;
     sortedBy?: "PROJECT" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | "MANUAL" | "ALPHABETICALLY" | null | undefined;
     sortOrder?: "ASC" | "DESC" | null | undefined;
+    calendarSettings?: {
+        [x: string]: unknown;
+        layout?: "WEEK" | "MONTH" | null | undefined;
+        visibleDayCount?: 3 | 1 | 7 | null | undefined;
+        color?: "PROJECT" | "LABEL" | "PRIORITY" | null | undefined;
+    } | null | undefined;
+    isDeleted?: boolean | undefined;
 }[];
 export declare const validateProjectViewOptionsDefaults: (input: unknown) => {
     [x: string]: unknown;
@@ -1182,7 +1196,9 @@ export declare const validateProjectViewOptionsDefaults: (input: unknown) => {
     filteredBy?: string | null | undefined;
     calendarSettings?: {
         [x: string]: unknown;
-        layout?: "WEEK" | "MONTH" | undefined;
+        layout?: "WEEK" | "MONTH" | null | undefined;
+        visibleDayCount?: 3 | 1 | 7 | null | undefined;
+        color?: "PROJECT" | "LABEL" | "PRIORITY" | null | undefined;
     } | null | undefined;
 }, validateProjectViewOptionsDefaultsArray: (input: unknown) => {
     [x: string]: unknown;
@@ -1195,7 +1211,9 @@ export declare const validateProjectViewOptionsDefaults: (input: unknown) => {
     filteredBy?: string | null | undefined;
     calendarSettings?: {
         [x: string]: unknown;
-        layout?: "WEEK" | "MONTH" | undefined;
+        layout?: "WEEK" | "MONTH" | null | undefined;
+        visibleDayCount?: 3 | 1 | 7 | null | undefined;
+        color?: "PROJECT" | "LABEL" | "PRIORITY" | null | undefined;
     } | null | undefined;
 }[];
 export declare const validateUserPlanLimits: (input: unknown) => {

package/dist/types/utils/view-options.d.ts

@@ -0,0 +1,11 @@
+import type { ViewOptions, ViewType } from '../types/sync/index.js';
+export type FindViewOptionsArgs = {
+    /** View types that identify the logical view. */
+    viewTypes: readonly ViewType[];
+    /** Object ID for object-backed views. Omit for singleton views. */
+    objectId?: string | null;
+};
+/** Returns whether saved view options are active rather than a deletion tombstone. */
+export declare function isActiveViewOption(options: ViewOptions): boolean;
+/** Finds the active saved options for one logical view. */
+export declare function findViewOptions(options: readonly ViewOptions[], args: FindViewOptionsArgs): ViewOptions | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/todoist-sdk",
-    "version": "14.0.2",
+    "version": "14.1.0",
     "description": "The official TypeScript SDK for the Todoist REST API.",
     "author": "Doist developers",
     "repository": "https://github.com/Doist/todoist-sdk-typescript",