@doist/todoist-sdk 14.1.0 → 15.0.0

package/README.md

@@ -125,12 +125,57 @@ const refreshed = await refreshAuthToken({
 > refresh. For public clients (`tokenEndpointAuthMethod: 'none'`), omit
 > `clientSecret` when calling `refreshAuthToken`.
 
+### Keeping Proxy Support and Response Decompression
+
+On Node, the SDK's default transport reads the proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) and decodes compressed response bodies. Supplying a `customFetch` replaces that transport, so a custom implementation that still wants both can borrow it with `getDefaultTransport`:
+
+```typescript
+import { type CustomFetch, getDefaultTransport, TodoistApi } from '@doist/todoist-sdk'
+
+const customFetch: CustomFetch = async (url, options) => {
+    const transport = await getDefaultTransport()
+    // undici's `fetch` and the global one are the same call at runtime but
+    // carry different types, so settle on one signature.
+    const fetchImpl = (transport?.fetch ?? fetch) as typeof fetch
+
+    const response = await fetchImpl(url, {
+        ...options,
+        headers: {
+            ...(options?.headers as Record<string, string> | undefined),
+            'x-my-header': 'value',
+        },
+        // `dispatcher` is a Node fetch option that the DOM types don't declare.
+        dispatcher: transport?.dispatcher,
+    } as RequestInit)
+
+    // `CustomFetchResponse` wants plain-object headers, not a `Headers`.
+    const headers: Record<string, string> = {}
+    response.headers.forEach((value, key) => {
+        headers[key] = value
+    })
+
+    return {
+        ok: response.ok,
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        text: () => response.text(),
+        json: () => response.json(),
+        arrayBuffer: () => response.arrayBuffer(),
+    }
+}
+
+const api = new TodoistApi('YOURTOKEN', { customFetch })
+```
+
+`getDefaultTransport` returns the dispatcher and the `fetch` it must be used with as a single value, and both halves have to be used together. The dispatcher decompresses the response body itself, so pairing it with a `fetch` from a different undici build — including the runtime's global `fetch` on Node 26 — decodes the body twice and the request fails mid-stream with `terminated`. A `fetch` of `undefined` means the global `fetch` is the correct partner; the whole value is `undefined` outside Node, where no dispatcher applies.
+
 ### Important Notes
 
 - All existing transforms (snake_case ↔ camelCase) work automatically with custom fetch
 - Retry logic and error handling are preserved
 - File uploads work with custom fetch implementations
-- The custom fetch function should handle FormData for multipart uploads
+- File upload bodies are a `Blob`, or a `ReadableStream` when uploading from a stream — a custom fetch must pass them through unchanged
 - Timeout parameter is optional and up to your custom implementation
 
 ## Development and Testing

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

@@ -1,6 +1,6 @@
 export * from './colors.js';
 export * from './sanitization.js';
-export { getTaskUrl, getProjectUrl, getSectionUrl } from './url-helpers.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 './task-sorting.js';

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

@@ -1,3 +1,24 @@
+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 { camelCaseKeys } from './case-conversion.js';
 /**
@@ -23,6 +44,116 @@ function getContentTypeFromFileName(fileName) {
             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.
  *
@@ -75,69 +206,52 @@ export async function uploadMultipartFile(args) {
     if (requestId) {
         headers['X-Request-Id'] = requestId;
     }
+    // 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) {
-        // Browser path: use native FormData
-        const form = new globalThis.FormData();
-        const resolvedFileName = fileName || (file instanceof File ? file.name : undefined) || 'upload';
-        form.append('file', file, resolvedFileName);
-        for (const [key, value] of Object.entries(additionalFields)) {
-            if (value !== undefined && value !== null) {
-                form.append(key, value.toString());
-            }
+        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');
         }
-        // Don't set Content-Type — let fetch set it with the correct multipart boundary
-        body = form;
+        resolvedFileName = fileName;
+        filePart = new Blob([
+            new Uint8Array(file.buffer, file.byteOffset, file.byteLength),
+        ]);
     }
     else {
-        // Node path: dynamically import Node-only modules
-        const [FormDataModule, fsModule, pathModule] = await Promise.all([
-            import('form-data'),
-            import('fs'),
-            import('path'),
-        ]);
-        const FormData = FormDataModule.default;
-        const form = new FormData();
-        if (typeof file === 'string') {
-            // File path - create read stream
-            const resolvedFileName = fileName || pathModule.basename(file);
-            form.append('file', fsModule.createReadStream(file), resolvedFileName);
-        }
-        else if (Buffer.isBuffer(file)) {
-            // Buffer - require fileName
-            if (!fileName) {
-                throw new Error('fileName is required when uploading from a Buffer');
-            }
-            const contentType = getContentTypeFromFileName(fileName);
-            form.append('file', file, {
-                filename: fileName,
-                contentType: contentType,
-            });
-        }
-        else {
-            // Stream - require fileName
-            if (!fileName) {
-                throw new Error('fileName is required when uploading from a stream');
-            }
-            form.append('file', file, fileName);
+        if (!fileName) {
+            throw new Error('fileName is required when uploading from a stream');
         }
-        for (const [key, value] of Object.entries(additionalFields)) {
-            if (value !== undefined && value !== null) {
-                form.append(key, value.toString());
-            }
-        }
-        Object.assign(headers, form.getHeaders());
-        body = form;
+        resolvedFileName = fileName;
+        filePart = file;
     }
-    // Make the request using fetch
-    const response = await fetchWithRetry({
-        url,
-        options: {
-            method: 'POST',
-            body,
-            headers,
-            timeout: 30000, // 30 second timeout for file uploads
-        },
-        customFetch,
+    const multipart = buildMultipartBody({
+        file: filePart,
+        fileName: resolvedFileName,
+        fileContentType: (filePart instanceof Blob ? filePart.type : undefined) ||
+            getContentTypeFromFileName(resolvedFileName),
+        additionalFields,
     });
+    // The boundary is ours, so Content-Type has to be set explicitly — `fetch`
+    // only fills it in for a `FormData` body.
+    headers['Content-Type'] = multipart.contentType;
+    body = multipart.body;
+    // Make the request using fetch
+    const 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 }));
     return camelCaseKeys(response.data);
 }

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

@@ -1,3 +1,5 @@
+import { LinkEnvironment } from '@doist/sdk-kmp/common';
+import { parseTodoistLink, todoistFilterUrl, todoistLabelUrl, todoistProjectCommentsUrl, todoistProjectCommentUrl, todoistProjectUrl, todoistSectionUrl, todoistTaskCommentsUrl, todoistTaskCommentUrl, todoistTaskUrl, todoistWorkspaceFilterUrl, todoistWorkspaceUrl, } from '@doist/sdk-kmp/todoist';
 import { TODOIST_WEB_URI } from '../consts/endpoints.js';
 /**
  * Formats a Date object to YYYY-MM-DD string format.
@@ -12,6 +14,23 @@ export function formatDateToYYYYMMDD(date) {
     const day = String(date.getDate()).padStart(2, '0');
     return `${year}-${month}-${day}`;
 }
+/**
+ * Builds a URL, falling back to a bare-id URL when the link builder rejects the
+ * given id. These helpers are called while parsing API responses, so generating
+ * a URL must never fail the parse.
+ *
+ * @param build Builds the URL.
+ * @param fallbackPath The path to fall back to, relative to the Todoist web app.
+ * @returns The built URL, or a bare-id URL if the id was rejected.
+ */
+function buildUrl(build, fallbackPath) {
+    try {
+        return build();
+    }
+    catch (_a) {
+        return `${TODOIST_WEB_URI}/${fallbackPath}`;
+    }
+}
 /**
  * Generate the URL for a given task.
  *
@@ -20,9 +39,7 @@ export function formatDateToYYYYMMDD(date) {
  * @returns The URL string for the task view.
  */
 export function getTaskUrl(taskId, content) {
-    const slug = content ? slugify(content) : undefined;
-    const path = slug ? `${slug}-${taskId}` : taskId;
-    return `${TODOIST_WEB_URI}/task/${path}`;
+    return buildUrl(() => todoistTaskUrl(taskId, content !== null && content !== void 0 ? content : '', LinkEnvironment.Production), `task/${taskId}`);
 }
 /**
  * Generate the URL for a given project.
@@ -32,9 +49,7 @@ export function getTaskUrl(taskId, content) {
  * @returns The URL string for the project view.
  */
 export function getProjectUrl(projectId, name) {
-    const slug = name ? slugify(name) : undefined;
-    const path = slug ? `${slug}-${projectId}` : projectId;
-    return `${TODOIST_WEB_URI}/project/${path}`;
+    return buildUrl(() => todoistProjectUrl(projectId, name !== null && name !== void 0 ? name : '', LinkEnvironment.Production), `project/${projectId}`);
 }
 /**
  * Generate the URL for a given section.
@@ -44,25 +59,138 @@ export function getProjectUrl(projectId, name) {
  * @returns The URL string for the section view.
  */
 export function getSectionUrl(sectionId, name) {
-    const slug = name ? slugify(name) : undefined;
-    const path = slug ? `${slug}-${sectionId}` : sectionId;
-    return `${TODOIST_WEB_URI}/section/${path}`;
+    return buildUrl(() => todoistSectionUrl(sectionId, name !== null && name !== void 0 ? name : '', LinkEnvironment.Production), `section/${sectionId}`);
+}
+/**
+ * Generate the URL for a given label.
+ *
+ * @param labelId The ID of the label.
+ * @param name The name of the label.
+ * @returns The URL string for the label view.
+ */
+export function getLabelUrl(labelId, name) {
+    return buildUrl(() => todoistLabelUrl(labelId, name !== null && name !== void 0 ? name : '', LinkEnvironment.Production), `label/${labelId}`);
+}
+/**
+ * Generate the URL for a given filter.
+ *
+ * @param filterId The ID of the filter.
+ * @param name The name of the filter.
+ * @returns The URL string for the filter view.
+ */
+export function getFilterUrl(filterId, name) {
+    return buildUrl(() => todoistFilterUrl(filterId, name !== null && name !== void 0 ? name : '', LinkEnvironment.Production), `filter/${filterId}`);
+}
+/**
+ * Generate the URL for a filter belonging to a workspace.
+ *
+ * @param workspaceId The ID of the workspace the filter belongs to.
+ * @param filterId The ID of the filter.
+ * @param name The name of the filter.
+ * @returns The URL string for the workspace filter view.
+ */
+export function getWorkspaceFilterUrl(workspaceId, filterId, name) {
+    return buildUrl(() => todoistWorkspaceFilterUrl(workspaceId, filterId, name !== null && name !== void 0 ? name : '', LinkEnvironment.Production), `${workspaceId}/filter/${filterId}`);
+}
+/**
+ * Generate the URL for a given workspace.
+ *
+ * @param workspaceId The ID of the workspace.
+ * @returns The URL string for the workspace view.
+ */
+export function getWorkspaceUrl(workspaceId) {
+    return buildUrl(() => todoistWorkspaceUrl(workspaceId, LinkEnvironment.Production), workspaceId);
+}
+/**
+ * Generate the URL for the comments on a given task.
+ *
+ * @param taskId The ID of the task.
+ * @param content The content of the task.
+ * @returns The URL string for the task's comments.
+ */
+export function getTaskCommentsUrl(taskId, content) {
+    return buildUrl(() => todoistTaskCommentsUrl(taskId, content !== null && content !== void 0 ? content : '', LinkEnvironment.Production), `task/${taskId}/comments`);
+}
+/**
+ * Generate the URL for the comments on a given project.
+ *
+ * @param projectId The ID of the project.
+ * @param name The name of the project.
+ * @returns The URL string for the project's comments.
+ */
+export function getProjectCommentsUrl(projectId, name) {
+    return buildUrl(() => todoistProjectCommentsUrl(projectId, name !== null && name !== void 0 ? name : '', LinkEnvironment.Production), `project/${projectId}/comments`);
 }
 /**
- * Slugify function borrowed from Django.
+ * Generate the URL for a single comment on a given task.
+ *
+ * @param taskId The ID of the task.
+ * @param commentId The ID of the comment.
+ * @param content The content of the task.
+ * @returns The URL string for the comment.
+ */
+export function getTaskCommentUrl(taskId, commentId, content) {
+    return buildUrl(() => todoistTaskCommentUrl(taskId, content !== null && content !== void 0 ? content : '', commentId, LinkEnvironment.Production), `task/${taskId}#comment-${commentId}`);
+}
+/**
+ * Generate the URL for a single comment on a given project.
+ *
+ * @param projectId The ID of the project.
+ * @param commentId The ID of the comment.
+ * @param name The name of the project.
+ * @returns The URL string for the comment.
+ */
+export function getProjectCommentUrl(projectId, commentId, name) {
+    return buildUrl(() => todoistProjectCommentUrl(projectId, name !== null && name !== void 0 ? name : '', commentId, LinkEnvironment.Production), `project/${projectId}#comment-${commentId}`);
+}
+/** The kinds of Todoist entity a URL can point at. */
+export const TODOIST_LINK_TYPES = [
+    'task',
+    'project',
+    'filter',
+    'label',
+    'section',
+    'workspace',
+    'template',
+    'comment',
+    'label_by_name',
+];
+/**
+ * Maps the link parser's type names onto the types this SDK exposes. A name
+ * that is missing here is one this SDK does not know about, and is treated as
+ * an unrecognised URL rather than surfaced as a value outside the union.
+ */
+const LINK_TYPE_BY_PARSED_NAME = {
+    Task: 'task',
+    Project: 'project',
+    Filter: 'filter',
+    Label: 'label',
+    Section: 'section',
+    Workspace: 'workspace',
+    Template: 'template',
+    Comment: 'comment',
+    LabelByName: 'label_by_name',
+};
+/**
+ * Parse a Todoist URL into the entity it points at.
  *
- * @param value The string to slugify.
- * @returns The slugified string.
+ * @param url The URL to parse.
+ * @returns The entity the URL points at, or `null` if it is not a Todoist URL.
  */
-function slugify(value) {
-    // Convert to ASCII
-    let result = value.normalize('NFKD').replace(/[\u0300-\u036f]/g, '');
-    // Remove non-ASCII characters
-    result = result.replace(/[^\x20-\x7E]/g, '');
-    // Convert to lowercase and replace non-alphanumeric characters with dashes
-    result = result.toLowerCase().replace(/[^\w\s-]/g, '');
-    // Replace spaces and repeated dashes with single dashes
-    result = result.replace(/[-\s]+/g, '-');
-    // Strip dashes from the beginning and end
-    return result.replace(/^-+|-+$/g, '');
+export function parseTodoistUrl(url) {
+    var _a, _b;
+    const link = parseTodoistLink(url);
+    if (!link) {
+        return null;
+    }
+    const type = LINK_TYPE_BY_PARSED_NAME[link.type.name];
+    if (!type) {
+        return null;
+    }
+    return {
+        type,
+        id: link.id,
+        workspaceId: (_a = link.workspaceId) !== null && _a !== void 0 ? _a : null,
+        commentId: (_b = link.commentId) !== null && _b !== void 0 ? _b : null,
+    };
 }

package/dist/types/index.d.ts

@@ -2,4 +2,5 @@ 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';
+export type { DefaultTransport } from './transport/http-dispatcher.js';

package/dist/types/transport/http-dispatcher.d.ts

@@ -7,7 +7,7 @@ type UndiciFetch = typeof import('undici').fetch;
  * never observe a dispatcher paired with a mismatched `fetch` — see
  * {@link getDefaultFetch} for why the pairing matters.
  */
-type DefaultTransport = {
+export type DefaultTransport = {
     dispatcher: Dispatcher;
     fetch: UndiciFetch | undefined;
 };
@@ -15,8 +15,33 @@ type DefaultTransport = {
  * 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 declare function getDefaultTransport(): Promise<DefaultTransport | undefined>;
+/**
+ * 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 declare function getDefaultDispatcher(): Promise<Dispatcher | undefined>;
 /**
  * The `fetch` implementation that must be used with the default dispatcher.

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

@@ -1,6 +1,7 @@
 export * from './colors.js';
 export * from './sanitization.js';
-export { getTaskUrl, getProjectUrl, getSectionUrl } from './url-helpers.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 './task-sorting.js';