@doist/comms-sdk 0.6.1 → 0.7.1

package/dist/cjs/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.closeDefaultDispatcher = exports.CommsApi = exports.WorkspacesClient = exports.WorkspaceUsersClient = exports.UsersClient = exports.ThreadsClient = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.HooksClient = exports.GroupsClient = exports.ConversationsClient = exports.ConversationMessagesClient = exports.CommentsClient = exports.ChannelsClient = exports.AttachmentsClient = void 0;
 __exportStar(require("./authentication"), exports);
+__exportStar(require("./migration"), exports);
 var attachments_client_1 = require("./clients/attachments-client");
 Object.defineProperty(exports, "AttachmentsClient", { enumerable: true, get: function () { return attachments_client_1.AttachmentsClient; } });
 var channels_client_1 = require("./clients/channels-client");

package/dist/cjs/migration.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchNewCommsUrl = fetchNewCommsUrl;
+exports.fetchNewCommsUrls = fetchNewCommsUrls;
+const http_client_1 = require("./transport/http-client");
+const errors_1 = require("./types/errors");
+/**
+ * Default origin of the Twist migration backend.
+ *
+ * The `fetch_new_url` endpoint lives on Twist (`twist.com`) and authenticates
+ * with a **Twist** token, not a Comms one. This is why the migration helpers are
+ * standalone functions rather than methods on {@link CommsApi} (which is
+ * constructed with a Comms token).
+ */
+const DEFAULT_TWIST_BASE_URL = 'https://twist.com';
+function getTwistMigrationUrl(baseUrl) {
+    const base = baseUrl ?? DEFAULT_TWIST_BASE_URL;
+    const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
+    return `${trimmed}/api/comms_migration/fetch_new_url`;
+}
+/**
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
+ * `comms_migration/fetch_new_url` endpoint.
+ *
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
+ * standalone helper rather than a method on {@link CommsApi}.
+ *
+ * @example
+ * ```typescript
+ * const newUrl = await fetchNewCommsUrl({
+ *   oldUrl: 'https://twist.com/a/123/ch/456/t/789',
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * ```
+ *
+ * @returns The equivalent Comms URL.
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
+ */
+async function fetchNewCommsUrl(args, options) {
+    const response = await (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: getTwistMigrationUrl(options?.baseUrl),
+        relativePath: '',
+        apiToken: args.twistToken,
+        payload: { oldUrl: args.oldUrl },
+        customFetch: options?.customFetch,
+    });
+    const newUrl = response.data?.newUrl;
+    if (!newUrl) {
+        throw new errors_1.CommsRequestError('Migration response did not contain a new URL.', response.status, response.data);
+    }
+    return newUrl;
+}
+/**
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
+ *
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
+ * migration endpoint. A failure on one URL does not abort the run: each result
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
+ * same order as the input.
+ *
+ * @example
+ * ```typescript
+ * const results = await fetchNewCommsUrls({
+ *   oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * for (const result of results) {
+ *   if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
+ *   else console.warn(`${result.oldUrl} failed`, result.error)
+ * }
+ * ```
+ *
+ * @returns One {@link MigrationResult} per input URL, in input order.
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
+ */
+async function fetchNewCommsUrls(args, options) {
+    const results = [];
+    for (const oldUrl of args.oldUrls) {
+        try {
+            const newUrl = await fetchNewCommsUrl({ oldUrl, twistToken: args.twistToken }, options);
+            results.push({ oldUrl, newUrl });
+        }
+        catch (error) {
+            if (error instanceof errors_1.CommsRequestError) {
+                results.push({ oldUrl, error });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return results;
+}

package/dist/cjs/testUtils/msw-setup.js

@@ -3,6 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.server = void 0;
 const node_1 = require("msw/node");
 const vitest_1 = require("vitest");
+// In production the transport uses undici's own `fetch` (paired with the
+// dispatcher) so the request client and dispatcher stay on one undici version.
+// MSW intercepts the *global* `fetch`, not that separate undici instance, so
+// force the transport onto the global `fetch` for every test in the suite;
+// MSW then intercepts requests as usual. The real undici transport is covered
+// directly by `http-dispatcher.test.ts` and `fetch-with-retry.test.ts`, which
+// opt out of this seam.
+vitest_1.vi.mock('../transport/http-dispatcher', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        getDefaultTransport: vitest_1.vi.fn(async () => undefined),
+    };
+});
 // Create MSW server instance
 exports.server = (0, node_1.setupServer)();
 // Start server before all tests

package/dist/cjs/transport/fetch-with-retry.js

@@ -62,15 +62,25 @@ async function fetchWithRetry(url, options, maxRetries = 3, customFetch) {
     throw new errors_1.CommsRequestError(lastError?.message ?? 'Request failed');
 }
 async function fetchWithDefaultTransport(url, options, signal) {
-    const dispatcher = await (0, http_dispatcher_1.getDefaultDispatcher)();
-    const response = dispatcher
-        ? await fetch(url, {
+    // Read the dispatcher and its paired `fetch` as one value so they can never
+    // be mismatched. On Node, `fetch` is undici's own — paired with the
+    // dispatcher — so the request client and dispatcher stay on one undici
+    // version; otherwise the `decompress` interceptor terminates gzip responses
+    // when the global `fetch`'s bundled undici differs. Browser/edge (and Bun)
+    // have no paired `fetch` and fall back to the global one.
+    const transport = await (0, http_dispatcher_1.getDefaultTransport)();
+    // undici's `fetch` and the global `fetch` are the same function at runtime
+    // but carry different (undici vs DOM) `RequestInit`/`Response` types. Call
+    // through the global signature, which matches the global-typed `options`.
+    const fetchImpl = (transport?.fetch ?? fetch);
+    const response = transport?.dispatcher
+        ? await fetchImpl(url, {
             ...options,
             signal,
             // @ts-expect-error - dispatcher is valid for Node.js fetch but not in TS types
-            dispatcher,
+            dispatcher: transport.dispatcher,
         })
-        : await fetch(url, {
+        : await fetchImpl(url, {
             ...options,
             signal,
         });

package/dist/cjs/transport/http-dispatcher.js

@@ -33,29 +33,39 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultTransport = getDefaultTransport;
 exports.getDefaultDispatcher = getDefaultDispatcher;
 exports.closeDefaultDispatcher = closeDefaultDispatcher;
 exports.resetDefaultDispatcherForTests = resetDefaultDispatcherForTests;
+exports.getDefaultFetch = getDefaultFetch;
 exports.suppressExperimentalWarningsSync = suppressExperimentalWarningsSync;
-let defaultDispatcher;
-let defaultDispatcherPromise;
-async function getDefaultDispatcher() {
-    if (defaultDispatcher) {
-        return defaultDispatcher;
+let defaultTransport;
+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.
+ */
+async function getDefaultTransport() {
+    if (defaultTransport) {
+        return defaultTransport;
     }
-    if (!defaultDispatcherPromise) {
-        defaultDispatcherPromise = createDefaultDispatcher()
-            .then((dispatcher) => {
-            defaultDispatcher = dispatcher;
-            return dispatcher;
+    if (!defaultTransportPromise) {
+        defaultTransportPromise = createDefaultTransport()
+            .then((transport) => {
+            defaultTransport = transport;
+            return transport;
         })
             .catch((error) => {
-            defaultDispatcher = undefined;
-            defaultDispatcherPromise = undefined;
+            defaultTransport = undefined;
+            defaultTransportPromise = undefined;
             throw error;
         });
     }
-    return defaultDispatcherPromise;
+    return defaultTransportPromise;
+}
+async function getDefaultDispatcher() {
+    return (await getDefaultTransport())?.dispatcher;
 }
 /**
  * Drains the default dispatcher's connection pool. CLIs and scripts should
@@ -64,17 +74,17 @@ async function getDefaultDispatcher() {
  */
 async function closeDefaultDispatcher() {
     // Clear the singleton *before* awaiting init, so any concurrent
-    // `getDefaultDispatcher()` after this point creates a fresh dispatcher
+    // `getDefaultTransport()` after this point creates a fresh dispatcher
     // instead of receiving a reference to the one we're about to close.
-    const initPromise = defaultDispatcherPromise;
-    defaultDispatcher = undefined;
-    defaultDispatcherPromise = undefined;
+    const initPromise = defaultTransportPromise;
+    defaultTransport = undefined;
+    defaultTransportPromise = undefined;
     if (!initPromise)
         return;
     try {
-        const dispatcher = await initPromise;
-        if (dispatcher) {
-            await dispatcher.close();
+        const transport = await initPromise;
+        if (transport) {
+            await transport.dispatcher.close();
         }
     }
     catch {
@@ -82,20 +92,39 @@ async function closeDefaultDispatcher() {
     }
 }
 function resetDefaultDispatcherForTests() {
-    defaultDispatcher = undefined;
-    defaultDispatcherPromise = undefined;
+    defaultTransport = undefined;
+    defaultTransportPromise = undefined;
+}
+/**
+ * The `fetch` implementation that must be used with the default dispatcher.
+ * Returns undici's own `fetch` on the full-undici Node path, or `undefined`
+ * (meaning: use the global `fetch`) in the browser/edge/Bun paths.
+ *
+ * Node's global `fetch` is backed by whatever undici version ships inside that
+ * Node release (6.x on Node 22 … 8.x on Node 26). Our dispatcher — and its
+ * `decompress` interceptor — comes from the npm `undici` package, which is a
+ * different version. Handing an npm-undici dispatcher to a mismatched built-in
+ * client makes gzip responses fail mid-stream with `terminated`. Sourcing
+ * `fetch` from the same npm `undici` keeps the whole request path on one
+ * version and removes the split.
+ *
+ * Only meaningful after {@link getDefaultTransport} has resolved, which is the
+ * one place that populates it.
+ */
+function getDefaultFetch() {
+    return defaultTransport?.fetch;
 }
 function isNodeEnvironment() {
     return typeof process !== 'undefined' && typeof process.versions?.node === 'string';
 }
-async function createDefaultDispatcher() {
+async function createDefaultTransport() {
     if (!isNodeEnvironment()) {
         return undefined;
     }
     // Dynamic import so non-Node consumers (browser, edge runtimes) don't pull
     // undici into their bundle. `isNodeEnvironment()` above already gated this
     // branch, so undici is safe to load when we get here.
-    const { EnvHttpProxyAgent, interceptors } = await Promise.resolve().then(() => __importStar(require('undici')));
+    const { EnvHttpProxyAgent, interceptors, fetch: undiciFetch } = await Promise.resolve().then(() => __importStar(require('undici')));
     // `EnvHttpProxyAgent` (with `allowH2`) and `interceptors.decompress()` both
     // emit an ExperimentalWarning on first use, so build the whole dispatcher
     // inside the suppression block.
@@ -112,14 +141,21 @@ async function createDefaultDispatcher() {
         // crashing on the missing API. Optional chaining also guards a runtime
         // that omits the `interceptors` export entirely.
         if (typeof interceptors?.decompress !== 'function') {
-            return agent;
+            // Bun: pair the agent with the global `fetch` (undefined), which
+            // decompresses natively.
+            return { dispatcher: agent, fetch: undefined };
         }
         // `interceptors.decompress()` decodes gzip/deflate/br/zstd bodies. On
         // Node 24+, attaching any custom dispatcher to global `fetch` strips
         // `content-encoding` without actually decompressing the body.
         // See https://github.com/Doist/todoist-cli/issues/318.
         const decompress = interceptors.decompress();
-        return agent.compose(decompress);
+        // Pair undici's own `fetch` with this dispatcher so the request client
+        // and the dispatcher stay on one undici version (see `getDefaultFetch`).
+        // The global `fetch` is backed by a different, Node-bundled undici;
+        // mixing the two makes the decompress interceptor terminate gzip
+        // responses on some Node versions.
+        return { dispatcher: agent.compose(decompress), fetch: undiciFetch };
     });
 }
 // `suppressExperimentalWarningsSync` is exported for direct unit testing —

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 export * from './authentication.js';
+export * from './migration.js';
 export { AttachmentsClient } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';

package/dist/esm/migration.js

@@ -0,0 +1,92 @@
+import { request } from './transport/http-client.js';
+import { CommsRequestError } from './types/errors.js';
+/**
+ * Default origin of the Twist migration backend.
+ *
+ * The `fetch_new_url` endpoint lives on Twist (`twist.com`) and authenticates
+ * with a **Twist** token, not a Comms one. This is why the migration helpers are
+ * standalone functions rather than methods on {@link CommsApi} (which is
+ * constructed with a Comms token).
+ */
+const DEFAULT_TWIST_BASE_URL = 'https://twist.com';
+function getTwistMigrationUrl(baseUrl) {
+    const base = baseUrl ?? DEFAULT_TWIST_BASE_URL;
+    const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
+    return `${trimmed}/api/comms_migration/fetch_new_url`;
+}
+/**
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
+ * `comms_migration/fetch_new_url` endpoint.
+ *
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
+ * standalone helper rather than a method on {@link CommsApi}.
+ *
+ * @example
+ * ```typescript
+ * const newUrl = await fetchNewCommsUrl({
+ *   oldUrl: 'https://twist.com/a/123/ch/456/t/789',
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * ```
+ *
+ * @returns The equivalent Comms URL.
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
+ */
+export async function fetchNewCommsUrl(args, options) {
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: getTwistMigrationUrl(options?.baseUrl),
+        relativePath: '',
+        apiToken: args.twistToken,
+        payload: { oldUrl: args.oldUrl },
+        customFetch: options?.customFetch,
+    });
+    const newUrl = response.data?.newUrl;
+    if (!newUrl) {
+        throw new CommsRequestError('Migration response did not contain a new URL.', response.status, response.data);
+    }
+    return newUrl;
+}
+/**
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
+ *
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
+ * migration endpoint. A failure on one URL does not abort the run: each result
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
+ * same order as the input.
+ *
+ * @example
+ * ```typescript
+ * const results = await fetchNewCommsUrls({
+ *   oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * for (const result of results) {
+ *   if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
+ *   else console.warn(`${result.oldUrl} failed`, result.error)
+ * }
+ * ```
+ *
+ * @returns One {@link MigrationResult} per input URL, in input order.
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
+ */
+export async function fetchNewCommsUrls(args, options) {
+    const results = [];
+    for (const oldUrl of args.oldUrls) {
+        try {
+            const newUrl = await fetchNewCommsUrl({ oldUrl, twistToken: args.twistToken }, options);
+            results.push({ oldUrl, newUrl });
+        }
+        catch (error) {
+            if (error instanceof CommsRequestError) {
+                results.push({ oldUrl, error });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return results;
+}

package/dist/esm/testUtils/msw-setup.js

@@ -1,5 +1,19 @@
 import { setupServer } from 'msw/node';
-import { afterAll, afterEach, beforeAll } from 'vitest';
+import { afterAll, afterEach, beforeAll, vi } from 'vitest';
+// In production the transport uses undici's own `fetch` (paired with the
+// dispatcher) so the request client and dispatcher stay on one undici version.
+// MSW intercepts the *global* `fetch`, not that separate undici instance, so
+// force the transport onto the global `fetch` for every test in the suite;
+// MSW then intercepts requests as usual. The real undici transport is covered
+// directly by `http-dispatcher.test.ts` and `fetch-with-retry.test.ts`, which
+// opt out of this seam.
+vi.mock('../transport/http-dispatcher', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        getDefaultTransport: vi.fn(async () => undefined),
+    };
+});
 // Create MSW server instance
 export const server = setupServer();
 // Start server before all tests

package/dist/esm/transport/fetch-with-retry.js

@@ -1,7 +1,7 @@
 import { CommsRequestError } from '../types/errors.js';
 import { camelCaseKeys } from '../utils/case-conversion.js';
 import { transformTimestamps } from '../utils/timestamp-conversion.js';
-import { getDefaultDispatcher } from './http-dispatcher.js';
+import { getDefaultTransport } from './http-dispatcher.js';
 export async function fetchWithRetry(url, options, maxRetries = 3, customFetch) {
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -59,15 +59,25 @@ export async function fetchWithRetry(url, options, maxRetries = 3, customFetch)
     throw new CommsRequestError(lastError?.message ?? 'Request failed');
 }
 async function fetchWithDefaultTransport(url, options, signal) {
-    const dispatcher = await getDefaultDispatcher();
-    const response = dispatcher
-        ? await fetch(url, {
+    // Read the dispatcher and its paired `fetch` as one value so they can never
+    // be mismatched. On Node, `fetch` is undici's own — paired with the
+    // dispatcher — so the request client and dispatcher stay on one undici
+    // version; otherwise the `decompress` interceptor terminates gzip responses
+    // when the global `fetch`'s bundled undici differs. Browser/edge (and Bun)
+    // have no paired `fetch` and fall back to the global one.
+    const transport = await getDefaultTransport();
+    // undici's `fetch` and the global `fetch` are the same function at runtime
+    // but carry different (undici vs DOM) `RequestInit`/`Response` types. Call
+    // through the global signature, which matches the global-typed `options`.
+    const fetchImpl = (transport?.fetch ?? fetch);
+    const response = transport?.dispatcher
+        ? await fetchImpl(url, {
             ...options,
             signal,
             // @ts-expect-error - dispatcher is valid for Node.js fetch but not in TS types
-            dispatcher,
+            dispatcher: transport.dispatcher,
         })
-        : await fetch(url, {
+        : await fetchImpl(url, {
             ...options,
             signal,
         });

package/dist/esm/transport/http-dispatcher.js

@@ -1,22 +1,30 @@
-let defaultDispatcher;
-let defaultDispatcherPromise;
-export async function getDefaultDispatcher() {
-    if (defaultDispatcher) {
-        return defaultDispatcher;
+let defaultTransport;
+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.
+ */
+export async function getDefaultTransport() {
+    if (defaultTransport) {
+        return defaultTransport;
     }
-    if (!defaultDispatcherPromise) {
-        defaultDispatcherPromise = createDefaultDispatcher()
-            .then((dispatcher) => {
-            defaultDispatcher = dispatcher;
-            return dispatcher;
+    if (!defaultTransportPromise) {
+        defaultTransportPromise = createDefaultTransport()
+            .then((transport) => {
+            defaultTransport = transport;
+            return transport;
         })
             .catch((error) => {
-            defaultDispatcher = undefined;
-            defaultDispatcherPromise = undefined;
+            defaultTransport = undefined;
+            defaultTransportPromise = undefined;
             throw error;
         });
     }
-    return defaultDispatcherPromise;
+    return defaultTransportPromise;
+}
+export async function getDefaultDispatcher() {
+    return (await getDefaultTransport())?.dispatcher;
 }
 /**
  * Drains the default dispatcher's connection pool. CLIs and scripts should
@@ -25,17 +33,17 @@ export async function getDefaultDispatcher() {
  */
 export async function closeDefaultDispatcher() {
     // Clear the singleton *before* awaiting init, so any concurrent
-    // `getDefaultDispatcher()` after this point creates a fresh dispatcher
+    // `getDefaultTransport()` after this point creates a fresh dispatcher
     // instead of receiving a reference to the one we're about to close.
-    const initPromise = defaultDispatcherPromise;
-    defaultDispatcher = undefined;
-    defaultDispatcherPromise = undefined;
+    const initPromise = defaultTransportPromise;
+    defaultTransport = undefined;
+    defaultTransportPromise = undefined;
     if (!initPromise)
         return;
     try {
-        const dispatcher = await initPromise;
-        if (dispatcher) {
-            await dispatcher.close();
+        const transport = await initPromise;
+        if (transport) {
+            await transport.dispatcher.close();
         }
     }
     catch {
@@ -43,20 +51,39 @@ export async function closeDefaultDispatcher() {
     }
 }
 export function resetDefaultDispatcherForTests() {
-    defaultDispatcher = undefined;
-    defaultDispatcherPromise = undefined;
+    defaultTransport = undefined;
+    defaultTransportPromise = undefined;
+}
+/**
+ * The `fetch` implementation that must be used with the default dispatcher.
+ * Returns undici's own `fetch` on the full-undici Node path, or `undefined`
+ * (meaning: use the global `fetch`) in the browser/edge/Bun paths.
+ *
+ * Node's global `fetch` is backed by whatever undici version ships inside that
+ * Node release (6.x on Node 22 … 8.x on Node 26). Our dispatcher — and its
+ * `decompress` interceptor — comes from the npm `undici` package, which is a
+ * different version. Handing an npm-undici dispatcher to a mismatched built-in
+ * client makes gzip responses fail mid-stream with `terminated`. Sourcing
+ * `fetch` from the same npm `undici` keeps the whole request path on one
+ * version and removes the split.
+ *
+ * Only meaningful after {@link getDefaultTransport} has resolved, which is the
+ * one place that populates it.
+ */
+export function getDefaultFetch() {
+    return defaultTransport?.fetch;
 }
 function isNodeEnvironment() {
     return typeof process !== 'undefined' && typeof process.versions?.node === 'string';
 }
-async function createDefaultDispatcher() {
+async function createDefaultTransport() {
     if (!isNodeEnvironment()) {
         return undefined;
     }
     // Dynamic import so non-Node consumers (browser, edge runtimes) don't pull
     // undici into their bundle. `isNodeEnvironment()` above already gated this
     // branch, so undici is safe to load when we get here.
-    const { EnvHttpProxyAgent, interceptors } = await import('undici');
+    const { EnvHttpProxyAgent, interceptors, fetch: undiciFetch } = await import('undici');
     // `EnvHttpProxyAgent` (with `allowH2`) and `interceptors.decompress()` both
     // emit an ExperimentalWarning on first use, so build the whole dispatcher
     // inside the suppression block.
@@ -73,14 +100,21 @@ async function createDefaultDispatcher() {
         // crashing on the missing API. Optional chaining also guards a runtime
         // that omits the `interceptors` export entirely.
         if (typeof interceptors?.decompress !== 'function') {
-            return agent;
+            // Bun: pair the agent with the global `fetch` (undefined), which
+            // decompresses natively.
+            return { dispatcher: agent, fetch: undefined };
         }
         // `interceptors.decompress()` decodes gzip/deflate/br/zstd bodies. On
         // Node 24+, attaching any custom dispatcher to global `fetch` strips
         // `content-encoding` without actually decompressing the body.
         // See https://github.com/Doist/todoist-cli/issues/318.
         const decompress = interceptors.decompress();
-        return agent.compose(decompress);
+        // Pair undici's own `fetch` with this dispatcher so the request client
+        // and the dispatcher stay on one undici version (see `getDefaultFetch`).
+        // The global `fetch` is backed by a different, Node-bundled undici;
+        // mixing the two makes the decompress interceptor terminate gzip
+        // responses on some Node versions.
+        return { dispatcher: agent.compose(decompress), fetch: undiciFetch };
     });
 }
 // `suppressExperimentalWarningsSync` is exported for direct unit testing —

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './authentication.js';
+export * from './migration.js';
 export { AttachmentsClient } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';

package/dist/types/migration.d.ts

@@ -0,0 +1,78 @@
+import { CommsRequestError } from './types/errors.js';
+import type { CustomFetch } from './types/http.js';
+export type MigrationOptions = {
+    /** Optional custom base URL for the Twist migration endpoint (testing/self-host). */
+    baseUrl?: string;
+    /** Optional custom fetch implementation for cross-platform compatibility. */
+    customFetch?: CustomFetch;
+};
+export type FetchNewCommsUrlArgs = {
+    /** A `twist.com` URL to translate to its Comms equivalent. */
+    oldUrl: string;
+    /** A Twist (not Comms) auth token. */
+    twistToken: string;
+};
+export type FetchNewCommsUrlsArgs = {
+    /** The `twist.com` URLs to translate to their Comms equivalents. */
+    oldUrls: string[];
+    /** A Twist (not Comms) auth token. */
+    twistToken: string;
+};
+/**
+ * Result of translating a single URL in a batch migration. Discriminated by the
+ * presence of `newUrl` (success) or `error` (failure).
+ */
+export type MigrationResult = {
+    oldUrl: string;
+    newUrl: string;
+    error?: undefined;
+} | {
+    oldUrl: string;
+    newUrl?: undefined;
+    error: CommsRequestError;
+};
+/**
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
+ * `comms_migration/fetch_new_url` endpoint.
+ *
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
+ * standalone helper rather than a method on {@link CommsApi}.
+ *
+ * @example
+ * ```typescript
+ * const newUrl = await fetchNewCommsUrl({
+ *   oldUrl: 'https://twist.com/a/123/ch/456/t/789',
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * ```
+ *
+ * @returns The equivalent Comms URL.
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
+ */
+export declare function fetchNewCommsUrl(args: FetchNewCommsUrlArgs, options?: MigrationOptions): Promise<string>;
+/**
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
+ *
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
+ * migration endpoint. A failure on one URL does not abort the run: each result
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
+ * same order as the input.
+ *
+ * @example
+ * ```typescript
+ * const results = await fetchNewCommsUrls({
+ *   oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * for (const result of results) {
+ *   if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
+ *   else console.warn(`${result.oldUrl} failed`, result.error)
+ * }
+ * ```
+ *
+ * @returns One {@link MigrationResult} per input URL, in input order.
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
+ */
+export declare function fetchNewCommsUrls(args: FetchNewCommsUrlsArgs, options?: MigrationOptions): Promise<MigrationResult[]>;

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

@@ -1,4 +1,22 @@
 import type { Dispatcher } from 'undici';
+type UndiciFetch = typeof import('undici').fetch;
+/**
+ * A dispatcher and the `fetch` that must be used with it. `fetch` is undici's
+ * own `fetch` on the full-undici Node path, or `undefined` (meaning: use the
+ * global `fetch`) on the Bun path. The two are cached together so callers can
+ * never observe a dispatcher paired with a mismatched `fetch` — see
+ * {@link getDefaultFetch} for why the pairing matters.
+ */
+type DefaultTransport = {
+    dispatcher: Dispatcher;
+    fetch: UndiciFetch | undefined;
+};
+/**
+ * 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.
+ */
+export declare function getDefaultTransport(): Promise<DefaultTransport | undefined>;
 export declare function getDefaultDispatcher(): Promise<Dispatcher | undefined>;
 /**
  * Drains the default dispatcher's connection pool. CLIs and scripts should
@@ -7,4 +25,22 @@ export declare function getDefaultDispatcher(): Promise<Dispatcher | undefined>;
  */
 export declare function closeDefaultDispatcher(): Promise<void>;
 export declare function resetDefaultDispatcherForTests(): void;
+/**
+ * The `fetch` implementation that must be used with the default dispatcher.
+ * Returns undici's own `fetch` on the full-undici Node path, or `undefined`
+ * (meaning: use the global `fetch`) in the browser/edge/Bun paths.
+ *
+ * Node's global `fetch` is backed by whatever undici version ships inside that
+ * Node release (6.x on Node 22 … 8.x on Node 26). Our dispatcher — and its
+ * `decompress` interceptor — comes from the npm `undici` package, which is a
+ * different version. Handing an npm-undici dispatcher to a mismatched built-in
+ * client makes gzip responses fail mid-stream with `terminated`. Sourcing
+ * `fetch` from the same npm `undici` keeps the whole request path on one
+ * version and removes the split.
+ *
+ * Only meaningful after {@link getDefaultTransport} has resolved, which is the
+ * one place that populates it.
+ */
+export declare function getDefaultFetch(): UndiciFetch | undefined;
 export declare function suppressExperimentalWarningsSync<T>(fn: () => T): T;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "0.6.1",
+    "version": "0.7.1",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",