@todoist/sdk 0.0.1 → 19.0.0

package/dist/esm/utils/headers.js

@@ -0,0 +1,42 @@
+/**
+ * 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 function headersToRecord(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+/**
+ * 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 function mergeHeaders(...sources) {
+    const merged = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const [name, value] of Object.entries(source)) {
+            const lowerName = name.toLowerCase();
+            for (const existingName of Object.keys(merged)) {
+                if (existingName.toLowerCase() === lowerName)
+                    delete merged[existingName];
+            }
+            merged[name] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * 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 function resolveCustomHeaders(headers) {
+    return typeof headers === 'function' ? headers() : headers;
+}

package/dist/esm/utils/index.js

@@ -0,0 +1,11 @@
+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 { createCommand } from './sync-helpers.js';
+export * from './project-helpers.js';
+export * from './person-names.js';
+export { isDateDrivenQuery } from './filter-queries.js';
+export { FILTER_QUERY_LANGUAGES } from './filter-query-definitions.js';
+export * from './task-sorting.js';
+export * from './view-options.js';
+export { parseWebhookPayload, verifyWebhookSignature } from './webhook-parser.js';

package/dist/esm/utils/multipart-upload.js

@@ -0,0 +1,267 @@
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { v4 as uuidv4 } from 'uuid';
+import { fetchWithRetry } from '../transport/fetch-with-retry.js';
+import { toTodoistRequestError } from '../transport/http-client.js';
+import { camelCaseKeys } from './case-conversion.js';
+import { mergeHeaders, resolveCustomHeaders } from './headers.js';
+/**
+ * Helper function to determine content-type from filename extension.
+ * @param fileName - The filename to analyze
+ * @returns The appropriate MIME type
+ */
+function getContentTypeFromFileName(fileName) {
+    const extension = fileName.toLowerCase().split('.').pop();
+    switch (extension) {
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'gif':
+            return 'image/gif';
+        case 'webp':
+            return 'image/webp';
+        case 'svg':
+            return 'image/svg+xml';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/**
+ * Escapes a value for use inside a quoted `Content-Disposition` parameter,
+ * where a raw quote would end the value early and a raw CR or LF would end the
+ * header. Note that a lone CR needs escaping too, not just CRLF pairs.
+ *
+ * This is the same escaping the platform's own `FormData` encoder applies, so
+ * servers see exactly what they would from any browser or from undici.
+ */
+function escapeDispositionValue(value) {
+    return value.replace(/"/g, '%22').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+/**
+ * Lays out a `multipart/form-data` payload around a single file part, as the
+ * text that goes before and after the file content. Keeping the file content
+ * out of it lets the same layout serve both a `Blob` body and a streamed one.
+ */
+function layOutMultipart(args) {
+    const { fileName, fileContentType, additionalFields } = args;
+    const boundary = `----todoist-sdk-${uuidv4()}`;
+    const head = `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="file"; filename="${escapeDispositionValue(fileName)}"\r\n` +
+        `Content-Type: ${fileContentType}\r\n\r\n`;
+    let tail = '\r\n';
+    for (const [key, value] of Object.entries(additionalFields)) {
+        if (value !== undefined && value !== null) {
+            tail +=
+                `--${boundary}\r\n` +
+                    `Content-Disposition: form-data; name="${escapeDispositionValue(key)}"\r\n\r\n` +
+                    `${value.toString()}\r\n`;
+        }
+    }
+    tail += `--${boundary}--\r\n`;
+    return { boundary, head, tail };
+}
+/**
+ * Wraps a Node readable stream as a `multipart/form-data` request body.
+ *
+ * The result is a web `ReadableStream`, which both the runtime's `fetch` and
+ * undici's own accept — unlike a Node stream or a `FormData`, either of which
+ * only works with one particular client. The file is never buffered, so the
+ * request is sent with `Transfer-Encoding: chunked`.
+ */
+function streamMultipartBody(file, parts) {
+    const encoder = new TextEncoder();
+    function chunks() {
+        return __asyncGenerator(this, arguments, function* chunks_1() {
+            var _a, e_1, _b, _c;
+            yield yield __await(encoder.encode(parts.head));
+            try {
+                for (var _d = true, file_1 = __asyncValues(file), file_1_1; file_1_1 = yield __await(file_1.next()), _a = file_1_1.done, !_a; _d = true) {
+                    _c = file_1_1.value;
+                    _d = false;
+                    const chunk = _c;
+                    yield yield __await(typeof chunk === 'string' ? encoder.encode(chunk) : new Uint8Array(chunk));
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = file_1.return)) yield __await(_b.call(file_1));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            yield yield __await(encoder.encode(parts.tail));
+        });
+    }
+    const iterator = chunks();
+    // Driven by hand rather than with `ReadableStream.from`, which is absent
+    // from this project's DOM lib types and is still missing in some browsers,
+    // or `Readable.toWeb`, which would drag a Node-only import into a module
+    // that browsers also load.
+    return new ReadableStream({
+        async pull(controller) {
+            const { value, done } = await iterator.next();
+            if (done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue(value);
+        },
+        async cancel(reason) {
+            var _a;
+            await ((_a = iterator.return) === null || _a === void 0 ? void 0 : _a.call(iterator, reason));
+        },
+    });
+}
+/**
+ * Builds the request body for a multipart upload.
+ *
+ * Deliberately avoids `FormData`. A `FormData` body is only encoded by the
+ * `fetch` that owns that `FormData` class — undici brands its own — so a body
+ * built from the global `FormData` and sent through undici's `fetch`, or the
+ * reverse, is stringified to the literal `"[object FormData]"` and the upload
+ * silently carries no file. The `form-data` package fares worse: neither
+ * `fetch` accepts it as a body at all. `Blob` and `ReadableStream` carry no
+ * such brand and work with whichever `fetch` dispatches the request,
+ * including a caller-supplied `customFetch`.
+ */
+function buildMultipartBody(args) {
+    const { file, fileName, fileContentType, additionalFields } = args;
+    const parts = layOutMultipart({ fileName, fileContentType, additionalFields });
+    const contentType = `multipart/form-data; boundary=${parts.boundary}`;
+    if (file instanceof Blob) {
+        // A Blob keeps its length, so the request gets a Content-Length and
+        // stays replayable if it has to be retried. File-backed Blobs (from
+        // `fs.openAsBlob`) stay lazy here, so nothing is read into memory.
+        return { body: new Blob([parts.head, file, parts.tail]), contentType, isStreamed: false };
+    }
+    return { body: streamMultipartBody(file, parts), contentType, isStreamed: true };
+}
+/**
+ * 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 async function uploadMultipartFile(args) {
+    const { baseUrl, authToken, endpoint, file, fileName, additionalFields, requestId, customHeaders, customFetch, } = args;
+    // Capture original stack for better error reporting
+    const originalStack = new Error();
+    // Build the full URL
+    const url = `${baseUrl}${endpoint}`;
+    let body;
+    // Resolve the file to something every `fetch` accepts as a body part: a
+    // Blob where the size is known up front, or a Node stream that gets piped
+    // through untouched.
+    let filePart;
+    let resolvedFileName;
+    if (file instanceof Blob) {
+        filePart = file;
+        resolvedFileName = fileName || (file instanceof File ? file.name : undefined) || 'upload';
+    }
+    else if (typeof file === 'string') {
+        // File path: Node-only, so import lazily to keep browser bundles clean.
+        const [fsModule, pathModule] = await Promise.all([import('fs'), import('path')]);
+        resolvedFileName = fileName || pathModule.basename(file);
+        // `openAsBlob` reads the file lazily, so a large upload is not pulled
+        // into memory, and the resulting body still has a known length.
+        filePart = await fsModule.openAsBlob(file);
+    }
+    else if (Buffer.isBuffer(file)) {
+        if (!fileName) {
+            throw new Error('fileName is required when uploading from a Buffer');
+        }
+        resolvedFileName = fileName;
+        filePart = new Blob([
+            new Uint8Array(file.buffer, file.byteOffset, file.byteLength),
+        ]);
+    }
+    else {
+        if (!fileName) {
+            throw new Error('fileName is required when uploading from a stream');
+        }
+        resolvedFileName = fileName;
+        filePart = file;
+    }
+    const multipart = buildMultipartBody({
+        file: filePart,
+        fileName: resolvedFileName,
+        fileContentType: (filePart instanceof Blob ? filePart.type : undefined) ||
+            getContentTypeFromFileName(resolvedFileName),
+        additionalFields,
+    });
+    // Custom headers come first so they can never replace the SDK's own.
+    const headers = mergeHeaders(resolveCustomHeaders(customHeaders), Object.assign(Object.assign({ Authorization: `Bearer ${authToken}` }, (requestId ? { 'X-Request-Id': requestId } : {})), { 
+        // The boundary is ours, so Content-Type has to be set explicitly —
+        // `fetch` only fills it in for a `FormData` body.
+        'Content-Type': multipart.contentType }));
+    body = multipart.body;
+    // Make the request using fetch
+    let response;
+    try {
+        response = await fetchWithRetry(Object.assign(Object.assign({ url, options: Object.assign({ method: 'POST', body,
+                headers, timeout: 30000 }, (multipart.isStreamed ? { duplex: 'half' } : {})) }, (multipart.isStreamed ? { retryConfig: { retries: 0 } } : {})), { customFetch }));
+    }
+    catch (error) {
+        // `fetchWithRetry` throws a plain `Error` for non-2xx responses; convert
+        // it so callers get the same error type as every other API request.
+        throw toTodoistRequestError(error, originalStack);
+    }
+    return camelCaseKeys(response.data);
+}

package/dist/esm/utils/person-names.js

@@ -0,0 +1,61 @@
+import { getFirstName as sharedGetFirstName, getLastName as sharedGetLastName, getShortName as sharedGetShortName, } from '@doist/sdk-kmp/shared-universe-all';
+/**
+ * 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 function getFirstName(fullName) {
+    return sharedGetFirstName(fullName);
+}
+/**
+ * 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 function getLastName(fullName) {
+    return sharedGetLastName(fullName);
+}
+/**
+ * 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 function getShortName(fullName) {
+    return sharedGetShortName(fullName);
+}
+/**
+ * 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 function formatUserShortName(fullName) {
+    return getShortName(fullName);
+}

package/dist/esm/utils/processing-helpers.js

@@ -0,0 +1,12 @@
+import camelcase from 'camelcase';
+import emojiRegex from 'emoji-regex';
+function isEmojiKey(key) {
+    const regex = emojiRegex();
+    return regex.test(key);
+}
+export function customCamelCase(input) {
+    // If the value is a solitary emoji string, return the key as-is
+    if (isEmojiKey(input))
+        return input;
+    return camelcase(input);
+}

package/dist/esm/utils/project-helpers.js

@@ -0,0 +1,29 @@
+/**
+ * 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 function isWorkspaceProject(project) {
+    return 'workspaceId' in project;
+}
+/**
+ * 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 function isPersonalProject(project) {
+    return !isWorkspaceProject(project);
+}
+/**
+ * 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 function countsTowardsPersonalProjectLimit(project) {
+    return (isPersonalProject(project) &&
+        !project.inboxProject &&
+        !project.isArchived &&
+        !project.isDeleted);
+}

package/dist/esm/utils/request-helpers.js

@@ -0,0 +1,43 @@
+import { TodoistArgumentError } from '../types/errors.js';
+/**
+ * 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 function encodePathSegment(segment) {
+    if (segment === '' || segment === '.' || segment === '..') {
+        throw new TodoistArgumentError(`Invalid path segment: "${segment}"`);
+    }
+    return encodeURIComponent(segment).replace(/%2C/gi, ',');
+}
+/**
+ * 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 function generatePath(endpoint, ...segments) {
+    return [endpoint, ...segments.map(encodePathSegment)].join('/');
+}
+/**
+ * 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 function spreadIfDefined(value, fn) {
+    return value !== undefined ? fn(value) : {};
+}

package/dist/esm/utils/sanitization.js

@@ -0,0 +1,131 @@
+const BOLD_FORMAT = /(^|[\s!?,;>:]+)(?:\*\*|__|!!)(.+?)(\*\*|__|!!)(?=$|[\s!?,;><:]+)/gi;
+const ITALIC_FORMAT = /(^|[\s!?,;>:]+)(?:\*|_|!)(.+?)(\*|_|!)(?=$|[\s!?,;><:]+)/gi;
+const BOLD_ITALIC_FORMAT = /(^|[\s!?,;>:]+)(?:\*\*\*|___|!!!)(.+?)(\*\*\*|___|!!!)(?=$|[\s!?,;><:]+)/gi;
+const CODE_BLOCK_FORMAT = /```([\s\S]*?)```/gi;
+const CODE_INLINE_FORMAT = /`([^`]+)`/gi;
+const TODOIST_LINK = /((?:(?:onenote:)?[\w-]+):\/\/[^\s]+)\s+[[(]([^)]+)[\])]/gi;
+const MARKDOWN_LINK = /\[(.+?)\]\((.+?)\)/gi;
+const GMAIL_LINK = /\[\[gmail=(.+?),\s*(.+?)\]\]/gi;
+const OUTLOOK_LINK = /\[\[outlook=(.+?),\s*(.+?)\]\]/gi;
+const THUNDERBIRD_LINK = /\[\[thunderbird\n(.+)\n(.+)\n\s*\]\]/gi;
+const FAKE_SECTION_PREFIX = '* ';
+const FAKE_SECTION_SUFFIX = ':';
+function removeStyleFormatting(input) {
+    if (!input.includes('!') && !input.includes('*') && !input.includes('_')) {
+        return input;
+    }
+    function removeMarkdown(_match, prefix, text) {
+        return `${prefix}${text}`;
+    }
+    input = input.replace(BOLD_ITALIC_FORMAT, removeMarkdown);
+    input = input.replace(BOLD_FORMAT, removeMarkdown);
+    input = input.replace(ITALIC_FORMAT, removeMarkdown);
+    return input;
+}
+function removeCodeFormatting(input) {
+    function removeMarkdown(_match, text) {
+        return text;
+    }
+    input = input.replace(CODE_BLOCK_FORMAT, removeMarkdown);
+    input = input.replace(CODE_INLINE_FORMAT, removeMarkdown);
+    return input;
+}
+function removeFakeSectionFormatting(input) {
+    if (input.startsWith(FAKE_SECTION_PREFIX)) {
+        input = input.slice(FAKE_SECTION_PREFIX.length);
+    }
+    if (input.endsWith(FAKE_SECTION_SUFFIX)) {
+        input = input.slice(0, input.length - FAKE_SECTION_SUFFIX.length);
+    }
+    return input;
+}
+function removeMarkdownLinks(input) {
+    if (!input.includes('[') || !input.includes(']')) {
+        return input;
+    }
+    function removeMarkdown(_match, text) {
+        return text;
+    }
+    return input.replace(MARKDOWN_LINK, removeMarkdown);
+}
+function removeTodoistLinks(input) {
+    if (!input.includes('(') || !input.includes(')')) {
+        return input;
+    }
+    function removeMarkdown(_match, _url, text) {
+        return text;
+    }
+    return input.replace(TODOIST_LINK, removeMarkdown);
+}
+function removeAppLinks(input) {
+    if (input.includes('gmail')) {
+        input = input.replace(GMAIL_LINK, (_match, _id, text) => text);
+    }
+    if (input.includes('outlook')) {
+        input = input.replace(OUTLOOK_LINK, (_match, _id, text) => text);
+    }
+    if (input.includes('thunderbird')) {
+        input = input.replace(THUNDERBIRD_LINK, (_match, text) => text);
+    }
+    return input;
+}
+/**
+ * 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 function getSanitizedContent(input) {
+    input = removeStyleFormatting(input);
+    input = removeCodeFormatting(input);
+    input = removeFakeSectionFormatting(input);
+    input = removeMarkdownLinks(input);
+    input = removeTodoistLinks(input);
+    input = removeAppLinks(input);
+    return input;
+}
+/**
+ * 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 function getSanitizedTasks(tasks) {
+    return tasks.map((task) => (Object.assign(Object.assign({}, task), { sanitizedContent: getSanitizedContent(task.content) })));
+}
+/**
+ * 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 function escapeFilterToken(text) {
+    return text.replace(/[()|&!,\\]/g, '\\$&');
+}

package/dist/esm/utils/sync-helpers.js

@@ -0,0 +1,19 @@
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * 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 function createCommand(type, args, tempId) {
+    return Object.assign({ type, uuid: uuidv4(), args: args }, (tempId !== undefined ? { tempId } : {}));
+}