@todoist/sdk 0.0.0-stage → 18.0.0

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

@@ -0,0 +1,201 @@
+import type { Color } from '../types/productivity/types.js';
+export declare const berryRed: {
+    readonly key: "berry_red";
+    readonly displayName: "Berry Red";
+    readonly hexValue: "#b8255f";
+};
+export declare const red: {
+    readonly key: "red";
+    readonly displayName: "Red";
+    readonly hexValue: "#db4035";
+};
+export declare const orange: {
+    readonly key: "orange";
+    readonly displayName: "Orange";
+    readonly hexValue: "#ff9933";
+};
+export declare const yellow: {
+    readonly key: "yellow";
+    readonly displayName: "Yellow";
+    readonly hexValue: "#fad000";
+};
+export declare const oliveGreen: {
+    readonly key: "olive_green";
+    readonly displayName: "Olive Green";
+    readonly hexValue: "#afb83b";
+};
+export declare const limeGreen: {
+    readonly key: "lime_green";
+    readonly displayName: "Lime Green";
+    readonly hexValue: "#7ecc49";
+};
+export declare const green: {
+    readonly key: "green";
+    readonly displayName: "Green";
+    readonly hexValue: "#299438";
+};
+export declare const mintGreen: {
+    readonly key: "mint_green";
+    readonly displayName: "Mint Green";
+    readonly hexValue: "#6accbc";
+};
+export declare const teal: {
+    readonly key: "teal";
+    readonly displayName: "Teal";
+    readonly hexValue: "#158fad";
+};
+export declare const skyBlue: {
+    readonly key: "sky_blue";
+    readonly displayName: "Sky Blue";
+    readonly hexValue: "#14aaf5";
+};
+export declare const lightBlue: {
+    readonly key: "light_blue";
+    readonly displayName: "Light Blue";
+    readonly hexValue: "#96c3eb";
+};
+export declare const blue: {
+    readonly key: "blue";
+    readonly displayName: "Blue";
+    readonly hexValue: "#4073ff";
+};
+export declare const grape: {
+    readonly key: "grape";
+    readonly displayName: "Grape";
+    readonly hexValue: "#884dff";
+};
+export declare const violet: {
+    readonly key: "violet";
+    readonly displayName: "Violet";
+    readonly hexValue: "#af38eb";
+};
+export declare const lavender: {
+    readonly key: "lavender";
+    readonly displayName: "Lavender";
+    readonly hexValue: "#eb96eb";
+};
+export declare const magenta: {
+    readonly key: "magenta";
+    readonly displayName: "Magenta";
+    readonly hexValue: "#e05194";
+};
+export declare const salmon: {
+    readonly key: "salmon";
+    readonly displayName: "Salmon";
+    readonly hexValue: "#ff8d85";
+};
+export declare const charcoal: {
+    readonly key: "charcoal";
+    readonly displayName: "Charcoal";
+    readonly hexValue: "#808080";
+};
+export declare const grey: {
+    readonly key: "grey";
+    readonly displayName: "Grey";
+    readonly hexValue: "#b8b8b8";
+};
+export declare const taupe: {
+    readonly key: "taupe";
+    readonly displayName: "Taupe";
+    readonly hexValue: "#ccac93";
+};
+/**
+ * Every color, in the order the apps show them. The keys mirror `TodoistColor` from
+ * `@doist/sdk-kmp/shared-todoist-all`; the display names and hex values are the SDK's own.
+ */
+export declare const colors: readonly [{
+    readonly key: "berry_red";
+    readonly displayName: "Berry Red";
+    readonly hexValue: "#b8255f";
+}, {
+    readonly key: "red";
+    readonly displayName: "Red";
+    readonly hexValue: "#db4035";
+}, {
+    readonly key: "orange";
+    readonly displayName: "Orange";
+    readonly hexValue: "#ff9933";
+}, {
+    readonly key: "yellow";
+    readonly displayName: "Yellow";
+    readonly hexValue: "#fad000";
+}, {
+    readonly key: "olive_green";
+    readonly displayName: "Olive Green";
+    readonly hexValue: "#afb83b";
+}, {
+    readonly key: "lime_green";
+    readonly displayName: "Lime Green";
+    readonly hexValue: "#7ecc49";
+}, {
+    readonly key: "green";
+    readonly displayName: "Green";
+    readonly hexValue: "#299438";
+}, {
+    readonly key: "mint_green";
+    readonly displayName: "Mint Green";
+    readonly hexValue: "#6accbc";
+}, {
+    readonly key: "teal";
+    readonly displayName: "Teal";
+    readonly hexValue: "#158fad";
+}, {
+    readonly key: "sky_blue";
+    readonly displayName: "Sky Blue";
+    readonly hexValue: "#14aaf5";
+}, {
+    readonly key: "light_blue";
+    readonly displayName: "Light Blue";
+    readonly hexValue: "#96c3eb";
+}, {
+    readonly key: "blue";
+    readonly displayName: "Blue";
+    readonly hexValue: "#4073ff";
+}, {
+    readonly key: "grape";
+    readonly displayName: "Grape";
+    readonly hexValue: "#884dff";
+}, {
+    readonly key: "violet";
+    readonly displayName: "Violet";
+    readonly hexValue: "#af38eb";
+}, {
+    readonly key: "lavender";
+    readonly displayName: "Lavender";
+    readonly hexValue: "#eb96eb";
+}, {
+    readonly key: "magenta";
+    readonly displayName: "Magenta";
+    readonly hexValue: "#e05194";
+}, {
+    readonly key: "salmon";
+    readonly displayName: "Salmon";
+    readonly hexValue: "#ff8d85";
+}, {
+    readonly key: "charcoal";
+    readonly displayName: "Charcoal";
+    readonly hexValue: "#808080";
+}, {
+    readonly key: "grey";
+    readonly displayName: "Grey";
+    readonly hexValue: "#b8b8b8";
+}, {
+    readonly key: "taupe";
+    readonly displayName: "Taupe";
+    readonly hexValue: "#ccac93";
+}];
+export type ColorKey = (typeof colors)[number]['key'];
+export declare const defaultColor: Color;
+/**
+ * Retrieves a {@link Color} object by its key identifier.
+ *
+ * @param colorKey - The unique key identifier of the color to find (e.g., 'berry_red', 'sky_blue')
+ * @returns The matching Color object if found, otherwise returns the default color (charcoal)
+ *
+ * @example
+ * ```typescript
+ * const color = getColorByKey('berry_red');
+ * console.log(color.hexValue); // '#b8255f'
+ * ```
+ */
+export declare function getColorByKey(colorKey: string): Color;

package/dist/types/utils/file-response.d.ts

@@ -0,0 +1,15 @@
+import type { CustomFetchResponse, FileResponse } from '../types/http.js';
+type AnyResponse = CustomFetchResponse | Response;
+/**
+ * Wraps either a native `Response` or a `CustomFetchResponse` into the SDK's
+ * `FileResponse` shape (binary endpoints: `viewAttachment`, `downloadBackup`).
+ *
+ * `arrayBuffer()` is resolved lazily. A customFetch implementation that omits
+ * `arrayBuffer()` is still valid for callers that only read `text()`/`json()`;
+ * the descriptive error is thrown only if the caller actually requests binary
+ * bytes. This avoids the lossy `text()` → `TextEncoder` round-trip that
+ * corrupts non-UTF-8 bytes (every `0x80`-`0xFF` byte not part of a valid UTF-8
+ * sequence is replaced with `U+FFFD`).
+ */
+export declare function wrapAsFileResponse(response: AnyResponse, context: 'viewAttachment' | 'downloadBackup'): FileResponse;
+export {};

package/dist/types/utils/filter-queries.d.ts

@@ -0,0 +1,42 @@
+export type IsDateDrivenQueryOptions = {
+    /**
+     * Language the query is written in, as the account's `lang`. Unknown codes
+     * and regional variants fall back to their base language, then to English.
+     */
+    lang?: string | null;
+};
+/**
+ * Returns whether a filter query leads with dates rather than with priority.
+ *
+ * Todoist gives every filter one of two default hierarchies, and a query that
+ * mentions dates gets the date-first one. Pass the answer to {@link sortTasks}
+ * as its `defaultOrder`:
+ *
+ * ```ts
+ * sortTasks(tasks, {
+ *     sortedBy: savedOptions?.sortedBy,
+ *     sortOrder: savedOptions?.sortOrder,
+ *     defaultOrder: isDateDrivenQuery(query, { lang }) ? 'DATE_FIRST' : 'PRIORITY_FIRST',
+ * })
+ * ```
+ *
+ * The query is read in `lang`, the account language `getUser` returns, the way
+ * the API reads it. English keywords parse under every language, so `lang` only
+ * matters for a query written in the account's own: `sin fecha` is a keyword
+ * under `es` and an unreadable phrase under `en`.
+ *
+ * Commas divide a filter into subqueries and Todoist draws each one as its own
+ * list, with its own hierarchy. Classify them one at a time for exact results;
+ * a whole query answers true only when every subquery is date-driven.
+ *
+ * Two kinds of unreadable query part company here. One that breaks the grammar,
+ * such as `(today`, returns false. One that only breaks the vocabulary, such as
+ * `sin fecha` under `en`, returns true, because a word this package doesn't
+ * recognize is treated as a bare date. Pass the account's own `lang` and the
+ * question doesn't arise; get it wrong and a keyword can read as a date.
+ *
+ * The function performs no I/O.
+ *
+ * @see sortTasks
+ */
+export declare function isDateDrivenQuery(query: string, options?: IsDateDrivenQueryOptions): boolean;

package/dist/types/utils/filter-query-definitions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Languages the Todoist filter parser reads queries in.
+ *
+ * English keywords parse under every one of them, so only a query written in
+ * the account's own language needs the matching code.
+ */
+export declare const FILTER_QUERY_LANGUAGES: readonly ["cs", "da", "de", "en", "es", "fi", "fr", "it", "ja", "ko", "nb", "nl", "pl", "pt", "ru", "sv", "tr", "zh_cn", "zh_tw"];
+/** A language the Todoist filter parser reads queries in. */
+export type FilterQueryLanguage = (typeof FILTER_QUERY_LANGUAGES)[number];
+/** Token kinds the Todoist filter lexer recognizes, in the order it tries them. */
+export declare const FILTER_QUERY_TOKENS: readonly ["LEFT", "RIGHT", "NOT", "AND", "OR", "PRIORITY", "NO_PRIORITY", "PROJECT", "SECTION", "PROJECT_SINGLE", "LABEL", "NO_LABELS", "DUE", "DUE_BEFORE", "DUE_AFTER", "DEADLINE", "DEADLINE_BEFORE", "DEADLINE_AFTER", "DATE", "DATE_BEFORE", "DATE_AFTER", "DUE_RECURRING", "OVERDUE", "WITHIN_DAYS", "NO_DUE_DATE", "NO_DEADLINE", "NO_DATE", "NO_TIME", "CREATED", "CREATED_BEFORE", "CREATED_AFTER", "ADDED_BY", "SHARED", "ASSIGNED", "TO_ME", "TO_OTHERS", "ASSIGNED_TO", "ASSIGNED_BY", "SUBTASK", "VIEW_ALL", "ALL", "SEARCH", "WORKSPACE_SINGLE", "UNCOMPLETABLE"];
+/** A token kind the Todoist filter lexer recognizes. */
+export type FilterQueryToken = (typeof FILTER_QUERY_TOKENS)[number];
+/**
+ * Tokens that make a subquery date-driven, from FilteristKt's `Grouper`.
+ *
+ * `recurring`, `no date` and `created:` are absent there too. Each says
+ * something about dates without giving the list one to lead with.
+ */
+export declare const FILTER_QUERY_DATE_TOKENS: readonly ["DUE", "DUE_BEFORE", "DUE_AFTER", "DEADLINE", "DEADLINE_BEFORE", "DEADLINE_AFTER", "DATE", "DATE_BEFORE", "DATE_AFTER", "OVERDUE", "WITHIN_DAYS"];
+/** Tokens that join or negate operands rather than standing as one. */
+export declare const FILTER_QUERY_OPERATOR_TOKENS: readonly ["LEFT", "RIGHT", "NOT", "AND", "OR"];
+/**
+ * Localized patterns per token, each one the body of `^\s*<pattern>\s*` and
+ * matched case-insensitively at the cursor.
+ */
+export declare const FILTER_QUERY_PATTERNS: Record<FilterQueryLanguage, Record<FilterQueryToken, readonly string[]>>;

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

@@ -0,0 +1,20 @@
+import type { CustomHeaders } from '../types/http.js';
+/**
+ * Converts a native Fetch `Headers` object into a plain `Record<string, string>`.
+ * Used when wrapping a native `fetch` response into the SDK's `FileResponse`
+ * shape (which expects headers as a plain record for symmetry with
+ * `CustomFetchResponse`).
+ */
+export declare function headersToRecord(headers: Headers): Record<string, string>;
+/**
+ * Merges header records left to right. HTTP header names are case-insensitive,
+ * so a later record replaces any earlier header with the same name whatever
+ * its case. Without this, a caller's `authorization` would sit alongside the
+ * SDK's `Authorization` and `fetch` would join the two into one value.
+ */
+export declare function mergeHeaders(...sources: (Record<string, string> | undefined)[]): Record<string, string>;
+/**
+ * Turns the `headers` option into the record to send with one request, calling
+ * it when it is a function so per-request values are fresh.
+ */
+export declare function resolveCustomHeaders(headers: CustomHeaders | undefined): Record<string, string> | undefined;

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

@@ -0,0 +1,15 @@
+export * from './colors.js';
+export * from './sanitization.js';
+export { getTaskUrl, getProjectUrl, getSectionUrl, getLabelUrl, getFilterUrl, getWorkspaceFilterUrl, getWorkspaceUrl, getTaskCommentsUrl, getProjectCommentsUrl, getTaskCommentUrl, getProjectCommentUrl, parseTodoistUrl, TODOIST_LINK_TYPES, } from './url-helpers.js';
+export type { TodoistLinkType, TodoistUrlInfo } from './url-helpers.js';
+export { createCommand } from './sync-helpers.js';
+export * from './project-helpers.js';
+export * from './person-names.js';
+export { isDateDrivenQuery } from './filter-queries.js';
+export type { IsDateDrivenQueryOptions } from './filter-queries.js';
+export { FILTER_QUERY_LANGUAGES } from './filter-query-definitions.js';
+export type { FilterQueryLanguage } from './filter-query-definitions.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/multipart-upload.d.ts

@@ -0,0 +1,58 @@
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
+type UploadMultipartFileArgs = {
+    baseUrl: string;
+    authToken: string;
+    endpoint: string;
+    file: Buffer | NodeJS.ReadableStream | string | Blob;
+    fileName?: string;
+    additionalFields: Record<string, string | number | boolean>;
+    requestId?: string;
+    /** Extra headers sent with the upload. Cannot replace `Authorization`, `X-Request-Id` or `Content-Type`. */
+    customHeaders?: CustomHeaders;
+    customFetch?: CustomFetch;
+};
+/**
+ * Uploads a file using multipart/form-data.
+ *
+ * This is a shared utility for uploading files to Todoist endpoints that require
+ * multipart/form-data content type (e.g., file uploads, workspace logo uploads).
+ *
+ * Supports both browser (Blob/File) and Node.js (Buffer/ReadableStream/path) environments.
+ *
+ * @param baseUrl - The base API URL (e.g., https://api.todoist.com/api/v1/)
+ * @param authToken - The authentication token
+ * @param endpoint - The relative endpoint path (e.g., 'uploads', 'workspaces/logo')
+ * @param file - The file content (Blob/File for browser, or Buffer/ReadableStream/path for Node)
+ * @param fileName - Optional file name (required for Buffer/Stream, optional for paths and File objects)
+ * @param additionalFields - Additional form fields to include (e.g., project_id, workspace_id)
+ * @param requestId - Optional request ID for idempotency
+ * @returns The response data from the server
+ * @throws TodoistRequestError if the upload fails, carrying the HTTP status and
+ * the server's error body like any other API request.
+ *
+ * @example
+ * ```typescript
+ * // Upload from a file path
+ * const result = await uploadMultipartFile(
+ *   'https://api.todoist.com/api/v1/',
+ *   'my-token',
+ *   'uploads',
+ *   '/path/to/file.pdf',
+ *   undefined,
+ *   { project_id: '12345' }
+ * )
+ *
+ * // Upload from a Buffer
+ * const buffer = Buffer.from('file content')
+ * const result = await uploadMultipartFile(
+ *   'https://api.todoist.com/api/v1/',
+ *   'my-token',
+ *   'uploads',
+ *   buffer,
+ *   'document.pdf',
+ *   { project_id: '12345' }
+ * )
+ * ```
+ */
+export declare function uploadMultipartFile(args: UploadMultipartFileArgs): Promise<unknown>;
+export {};

package/dist/types/utils/person-names.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Returns the first word of a person's name, or an empty string if the name is blank.
+ *
+ * Status text people add to their display name isn't part of the name. Anything after a `|`, `@`
+ * or dash with spaces around it is left out, as is a trailing `OOO` or note in parentheses, so
+ * `Ada Lovelace (OOO Friday)` and `Ada Lovelace @ Paternity Leave` both read as `Ada Lovelace`.
+ *
+ * @param fullName - The person's full name, such as a user's `name` or `fullName`
+ * @returns The first name, or an empty string for a blank name
+ */
+export declare function getFirstName(fullName: string): string;
+/**
+ * Returns the last word of a person's name, or an empty string if the name is blank. A one-word
+ * name is its own last name.
+ *
+ * Status text is left out as it is for {@link getFirstName}, so `Ada Lovelace (OOO Friday)` gives
+ * `Lovelace`. A trailing emoji still counts as a word here, so `Ana Silva 🌴` gives `🌴`, while
+ * {@link getShortName} skips it when picking the initial.
+ *
+ * @param fullName - The person's full name, such as a user's `name` or `fullName`
+ * @returns The last name, or an empty string for a blank name
+ */
+export declare function getLastName(fullName: string): string;
+/**
+ * Returns a person's first name and the initial of their last name, such as `Richard A.` for
+ * `Richard Dean Anderson`.
+ *
+ * - Status text is left out as it is for {@link getFirstName}, so `Ada Lovelace (OOO Friday)`
+ *   gives `Ada L.`, not `Ada F.`.
+ * - The initial comes from the last word rather than the second, because in a name of three or
+ *   more words the last one is usually the family name.
+ * - The initial is a whole character as the reader sees it, so an accent or an Indic conjunct
+ *   stays with its letter: `Shreya श्रीवास्तव` gives `Shreya श्री.`.
+ * - A word that doesn't start with a letter, such as a trailing emoji, is skipped, so
+ *   `Ana Silva 🌴` gives `Ana S.`. When no word after the first starts with a letter, as in
+ *   `Robot 🤖` or a one-word name, the first name is returned alone.
+ *
+ * @param fullName - The person's full name, such as a user's `name` or `fullName`
+ * @returns The first name and last initial, the first name alone when there's no initial, or an
+ * empty string for a blank name
+ */
+export declare function getShortName(fullName: string): string;
+/**
+ * Returns a person's first name and the initial of their last name.
+ *
+ * @deprecated Use {@link getShortName} instead, which this calls. It used to take the initial
+ * from the second word, which no longer matches the Todoist apps.
+ *
+ * @param fullName - The person's full name, such as a user's `name` or `fullName`
+ * @returns The same as {@link getShortName}
+ */
+export declare function formatUserShortName(fullName: string): string;

package/dist/types/utils/processing-helpers.d.ts

@@ -0,0 +1 @@
+export declare function customCamelCase(input: string): string;

package/dist/types/utils/project-helpers.d.ts

@@ -0,0 +1,21 @@
+import type { PersonalProject, WorkspaceProject } from '../types/projects/types.js';
+/**
+ * Type guard to check if a project is a workspace project.
+ * @param project The project to check
+ * @returns True if the project is a workspace project
+ */
+export declare function isWorkspaceProject(project: PersonalProject | WorkspaceProject): project is WorkspaceProject;
+/**
+ * Type guard to check if a project is a personal project.
+ * @param project The project to check
+ * @returns True if the project is a personal project
+ */
+export declare function isPersonalProject(project: PersonalProject | WorkspaceProject): project is PersonalProject;
+/**
+ * Whether a project counts towards the plan's limit on active personal projects:
+ * an active personal project other than the Inbox. Shared projects and sub-projects
+ * count; workspace projects do not.
+ * @param project The project to check
+ * @returns True if the project counts towards the limit
+ */
+export declare function countsTowardsPersonalProjectLimit(project: PersonalProject | WorkspaceProject): boolean;

package/dist/types/utils/request-helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Encodes a caller-supplied value (an ID, a name) for use as one URL path segment.
+ *
+ * Without this, a value such as `../projects/123` would be joined into the path
+ * as-is and the URL would resolve to a different endpoint. `encodeURIComponent`
+ * escapes `/`, `?`, `#` and `%`, but leaves `.` alone, so the dot segments `.`
+ * and `..` (and the empty segment) are rejected outright. `,` is kept literal,
+ * as it is a valid path character and joins lists of IDs.
+ *
+ * @param segment The value to encode.
+ * @returns The encoded segment.
+ * @throws {TodoistArgumentError} When the value is empty, `.` or `..`.
+ */
+export declare function encodePathSegment(segment: string): string;
+/**
+ * Joins an endpoint with path segments using `/` separator.
+ *
+ * The endpoint is used as-is (it may contain `/`); every following segment is
+ * encoded with {@link encodePathSegment}, so an ID can never address another
+ * resource.
+ *
+ * @param endpoint The base endpoint, e.g. `tasks`.
+ * @param segments Path segments to append, e.g. an ID and an action.
+ * @returns A joined path.
+ */
+export declare function generatePath(endpoint: string, ...segments: string[]): string;
+/**
+ * Returns `fn(value)` spread into an object if `value` is defined, otherwise an empty object.
+ *
+ * Used to conditionally include a property on a payload object without
+ * resorting to mutation or ternary-built object literals.
+ */
+export declare function spreadIfDefined<T, V extends Record<string, unknown>>(value: T | undefined, fn: (v: T) => V): V | Record<string, never>;

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

@@ -0,0 +1,52 @@
+import { Task } from '../types/index.js';
+export type TaskWithSanitizedContent = Task & {
+    sanitizedContent: string;
+};
+/**
+ * Sanitizes a string by removing Todoist's formatting syntax (e.g. bold, italic, code blocks, links).
+ *
+ * @example
+ * // Removes bold/italic formatting
+ * getSanitizedContent('Some **bold** and *italic*') // 'Some bold and italic'
+ *
+ * // Removes markdown links
+ * getSanitizedContent('A [markdown](http://url.com) link') // 'A markdown link'
+ *
+ * // Removes app-specific links
+ * getSanitizedContent('A [[gmail=id, link from gmail]]') // 'A link from gmail'
+ *
+ * @param input - The string to sanitize
+ * @returns The sanitized string with all formatting removed
+ */
+export declare function getSanitizedContent(input: string): string;
+/**
+ * Takes an array of tasks and returns a new array with sanitized content
+ * added as 'sanitizedContent' property to each task.
+ *
+ * @see {@link getSanitizedContent}
+ *
+ * @example
+ * const tasks = [{ content: '**Bold** task', ... }]
+ * getSanitizedTasks(tasks) // [{ content: '**Bold** task', sanitizedContent: 'Bold task', ... }]
+ *
+ * @param tasks - Array of Task objects to sanitize
+ * @returns Array of tasks with added sanitizedContent property
+ */
+export declare function getSanitizedTasks(tasks: Task[]): TaskWithSanitizedContent[];
+/**
+ * Escapes text for use as a token in a Todoist filter query.
+ *
+ * Prefixes parentheses, pipes, ampersands, exclamation marks, commas, and
+ * backslashes with a backslash. Quotes and asterisks are left unchanged.
+ * Whitespace validation and trimming are the caller's responsibility.
+ * Pass unescaped text to this function once, before inserting it into a query.
+ *
+ * @example
+ * const tasks = await api.getTasksByFilter({
+ *     query: `search: ${escapeFilterToken(searchText)}`,
+ * })
+ *
+ * @param text - The text to escape, not a complete filter query
+ * @returns The escaped text, with whitespace preserved
+ */
+export declare function escapeFilterToken(text: string): string;

package/dist/types/utils/sync-helpers.d.ts

@@ -0,0 +1,17 @@
+import type { SyncCommandType, SyncCommandsMap, SyncCommand } from '../types/sync/commands/index.js';
+/**
+ * Creates a strongly-typed Sync API command with an auto-generated UUID.
+ *
+ * @param type - The command type (e.g. `'item_add'`, `'project_update'`).
+ * @param args - The command arguments, constrained by the command type.
+ * @param tempId - Optional temporary ID for referencing the created resource in subsequent commands.
+ * @returns A fully formed `SyncCommand` ready to include in a sync request.
+ *
+ * @example
+ * ```typescript
+ * const cmd = createCommand('item_add', { content: 'Buy milk', priority: 2 })
+ * // cmd.type === 'item_add'
+ * // cmd.args is typed as TaskAddArgs
+ * ```
+ */
+export declare function createCommand<T extends SyncCommandType>(type: T, args: SyncCommandsMap[T], tempId?: string): SyncCommand<T>;

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

@@ -0,0 +1,46 @@
+import type { ViewOptions } 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, MANUAL, and fields this SDK can't sort by
+     * (such as LABEL) use defaultOrder.
+     */
+    sortedBy?: ViewOptions['sortedBy'];
+    /** Saved or requested direction. Defaults by field when absent. */
+    sortOrder?: ViewOptions['sortOrder'];
+    /**
+     * Default hierarchy for this view or filter query. Today and Upcoming are
+     * date-first; for a filter, {@link isDateDrivenQuery} reads it off the 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.
+ *
+ * @see isDateDrivenQuery
+ */
+export declare function sortTasks(tasks: readonly Task[], options: TaskSortOptions, context?: TaskSortContext): Task[];

package/dist/types/utils/uncompletable-helpers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Adds the uncompletable prefix (* ) to task content if not already present
+ * @param content - The task content
+ * @returns Content with uncompletable prefix added
+ */
+export declare function addUncompletablePrefix(content: string): string;
+/**
+ * Removes the uncompletable prefix (* ) from task content if present
+ * @param content - The task content
+ * @returns Content with uncompletable prefix removed
+ */
+export declare function removeUncompletablePrefix(content: string): string;
+/**
+ * Checks if task content has the uncompletable prefix (* )
+ * @param content - The task content
+ * @returns True if content starts with uncompletable prefix
+ */
+export declare function hasUncompletablePrefix(content: string): boolean;
+/**
+ * Processes task content based on isUncompletable flag, with content prefix taking precedence
+ * @param content - The original task content
+ * @param isUncompletable - Optional flag to make task uncompletable
+ * @returns Processed content
+ *
+ * Logic:
+ * - If content already has * prefix, task is uncompletable regardless of flag
+ * - If content doesn't have * prefix and isUncompletable is true, add the prefix
+ * - If isUncompletable is undefined or false (and no prefix), leave content unchanged
+ */
+export declare function processTaskContent(content: string, isUncompletable?: boolean): string;