@doist/todoist-sdk 14.0.2 → 14.2.0

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/index.js

@@ -2,4 +2,4 @@ export * from './todoist-api.js';
 export * from './authentication.js';
 export * from './types/index.js';
 export * from './utils/index.js';
-export { getDefaultDispatcher } from './transport/http-dispatcher.js';
+export { getDefaultDispatcher, getDefaultTransport } from './transport/http-dispatcher.js';

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/transport/http-dispatcher.js

@@ -10,6 +10,23 @@ let defaultTransportPromise;
  * The default dispatcher and its paired `fetch`, as a single value so the two
  * are always read consistently. Resolves to `undefined` outside Node (browser/
  * edge), where callers use the global `fetch` with no dispatcher.
+ *
+ * Use this when supplying a `customFetch` that should still honour the proxy
+ * environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) and decode
+ * compressed responses the way the SDK does by default.
+ *
+ * Both halves must be used together. `dispatcher` decompresses the response
+ * body itself, so a `fetch` from a different undici build will try to decode
+ * it a second time and the request fails mid-stream with `terminated`. A
+ * `fetch` of `undefined` means the runtime's global `fetch` is the correct
+ * partner for this dispatcher.
+ *
+ * @example
+ * ```ts
+ * const transport = await getDefaultTransport()
+ * const fetchImpl = transport?.fetch ?? fetch
+ * const response = await fetchImpl(url, { ...options, dispatcher: transport?.dispatcher })
+ * ```
  */
 export function getDefaultTransport() {
     if (!isNodeEnvironment()) {
@@ -29,6 +46,14 @@ export function getDefaultTransport() {
     }
     return defaultTransportPromise;
 }
+/**
+ * The default dispatcher on its own.
+ *
+ * @deprecated Use {@link getDefaultTransport} instead, which returns this
+ * dispatcher together with the `fetch` it must be used with. Attaching this
+ * dispatcher to the runtime's global `fetch` decodes compressed responses
+ * twice on Node 26 and the request fails with `terminated`.
+ */
 export async function getDefaultDispatcher() {
     var _a;
     return (_a = (await getDefaultTransport())) === null || _a === void 0 ? void 0 : _a.dispatcher;

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';