@doist/todoist-sdk 14.0.1 → 14.1.0

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/live-notifications.d.ts

@@ -10,19 +10,19 @@ import { z } from 'zod';
 export declare const LiveNotificationSchema: z.ZodObject<{
     id: z.ZodString;
     createdAt: z.ZodCoercedDate<unknown>;
-    fromUid: z.ZodString;
+    fromUid: z.ZodOptional<z.ZodString>;
     notificationType: z.ZodString;
     isUnread: z.ZodBoolean;
     projectId: z.ZodOptional<z.ZodString>;
     invitationId: z.ZodOptional<z.ZodString>;
     itemId: z.ZodOptional<z.ZodString>;
     itemContent: z.ZodOptional<z.ZodString>;
-    responsibleUid: z.ZodOptional<z.ZodString>;
-    assignedByUid: z.ZodOptional<z.ZodString>;
+    responsibleUid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    assignedByUid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     fromUser: z.ZodOptional<z.ZodObject<{
         email: z.ZodString;
         fullName: z.ZodString;
-        id: z.ZodString;
+        id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
         imageId: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
     projectName: z.ZodOptional<z.ZodString>;

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

@@ -465,19 +465,19 @@ export declare const SyncResponseSchema: z.ZodObject<{
     liveNotifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         createdAt: z.ZodCoercedDate<unknown>;
-        fromUid: z.ZodString;
+        fromUid: z.ZodOptional<z.ZodString>;
         notificationType: z.ZodString;
         isUnread: z.ZodBoolean;
         projectId: z.ZodOptional<z.ZodString>;
         invitationId: z.ZodOptional<z.ZodString>;
         itemId: z.ZodOptional<z.ZodString>;
         itemContent: z.ZodOptional<z.ZodString>;
-        responsibleUid: z.ZodOptional<z.ZodString>;
-        assignedByUid: z.ZodOptional<z.ZodString>;
+        responsibleUid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assignedByUid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         fromUser: z.ZodOptional<z.ZodObject<{
             email: z.ZodString;
             fullName: z.ZodString;
-            id: z.ZodString;
+            id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
             imageId: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>>;
         projectName: z.ZodOptional<z.ZodString>;
@@ -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[];