@doist/todoist-sdk 10.4.1 → 10.5.1

package/README.md

@@ -104,6 +104,27 @@ await revokeToken(args, {
 const { accessToken } = await getAuthToken(args, baseUrl)
 ```
 
+When the authorization server issues a `refreshToken`, use `refreshAuthToken`
+to obtain a new access token once the current one expires, without sending the
+user back through the authorization flow:
+
+```typescript
+const refreshed = await refreshAuthToken({
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    refreshToken: storedRefreshToken,
+})
+
+// The server may rotate the refresh token — persist refreshed.refreshToken
+// when present, otherwise keep using the previous one.
+```
+
+> **Note:** Refresh tokens are only issued to OAuth apps that have them enabled
+> (the default for new apps). Apps without them receive a long-lived access
+> token, so `getAuthToken` returns no `refreshToken` and there is nothing to
+> refresh. For public clients (`tokenEndpointAuthMethod: 'none'`), omit
+> `clientSecret` when calling `refreshAuthToken`.
+
 ### Important Notes
 
 - All existing transforms (snake_case ↔ camelCase) work automatically with custom fetch

package/dist/cjs/authentication.js

@@ -15,6 +15,7 @@ exports.TOKEN_ENDPOINT_AUTH_METHODS = exports.PERMISSIONS = void 0;
 exports.getAuthStateParameter = getAuthStateParameter;
 exports.getAuthorizationUrl = getAuthorizationUrl;
 exports.getAuthToken = getAuthToken;
+exports.refreshAuthToken = refreshAuthToken;
 exports.revokeToken = revokeToken;
 exports.migratePersonalToken = migratePersonalToken;
 exports.registerClient = registerClient;
@@ -108,32 +109,74 @@ function getAuthorizationUrl({ clientId, permissions, state, baseUrl, }) {
  * @returns The access token response
  * @throws {@link TodoistRequestError} If the token exchange fails
  */
-async function getAuthToken(args, options) {
+/**
+ * Posts a payload to the OAuth token endpoint and returns the token response,
+ * mapping any failure to a {@link TodoistRequestError} with `errorMessage`.
+ * Shared by {@link getAuthToken} and {@link refreshAuthToken}.
+ */
+async function requestAuthToken(payload, errorMessage, options) {
     var _a;
-    if (typeof options === 'string') {
-        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
-    }
-    const baseUrl = options === null || options === void 0 ? void 0 : options.baseUrl;
-    const customFetch = options === null || options === void 0 ? void 0 : options.customFetch;
     try {
         const response = await (0, http_client_1.request)({
             httpMethod: 'POST',
-            baseUri: (0, endpoints_1.getAuthBaseUri)(baseUrl),
+            baseUri: (0, endpoints_1.getAuthBaseUri)(options === null || options === void 0 ? void 0 : options.baseUrl),
             relativePath: endpoints_1.ENDPOINT_GET_TOKEN,
             apiToken: undefined,
-            payload: args,
-            customFetch,
+            payload,
+            customFetch: options === null || options === void 0 ? void 0 : options.customFetch,
         });
         if (response.status !== 200 || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
-            throw new types_1.TodoistRequestError('Authentication token exchange failed.', response.status, response.data);
+            throw new types_1.TodoistRequestError(errorMessage, response.status, response.data);
         }
         return response.data;
     }
     catch (error) {
         // Re-throw with custom message for authentication failures
         const err = error;
-        throw new types_1.TodoistRequestError('Authentication token exchange failed.', err.httpStatusCode, err.responseData);
+        throw new types_1.TodoistRequestError(errorMessage, err.httpStatusCode, err.responseData);
+    }
+}
+async function getAuthToken(args, options) {
+    if (typeof options === 'string') {
+        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
+    }
+    return requestAuthToken(Object.assign({}, args), 'Authentication token exchange failed.', options);
+}
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * Only relevant for OAuth apps that have refresh tokens enabled (the default for
+ * new apps). Apps without them never receive a `refreshToken` from
+ * {@link getAuthToken}, so they have nothing to pass here — their access tokens
+ * are long-lived instead.
+ *
+ * Omit `clientSecret` for public clients registered with
+ * `tokenEndpointAuthMethod: 'none'`.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The server rotates the refresh token, so the
+ * response carries a new `refreshToken` — persist it in place of the old one.
+ * @throws {@link TodoistRequestError} If the refresh fails
+ */
+async function refreshAuthToken(args, options) {
+    const payload = {
+        clientId: args.clientId,
+        refreshToken: args.refreshToken,
+        grantType: 'refresh_token',
+    };
+    if (args.clientSecret !== undefined) {
+        payload.clientSecret = args.clientSecret;
     }
+    return requestAuthToken(payload, 'Authentication token refresh failed.', options);
 }
 /**
  * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.

package/dist/cjs/test-utils/transport-seam.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 with `vi.unmock('./http-dispatcher')`.
+//
+// This lives in its own setup file (not `msw-setup.ts`) because a hoisted
+// `vi.mock` in a module that also re-exports values corrupts those exports.
+vitest_1.vi.mock('../transport/http-dispatcher', async (importOriginal) => {
+    const actual = await importOriginal();
+    return Object.assign(Object.assign({}, actual), { getDefaultTransport: vitest_1.vi.fn(async () => undefined) });
+});

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

@@ -99,6 +99,7 @@ function convertResponseToCustomFetch(response) {
  * Performs a fetch request with retry logic and timeout support
  */
 async function fetchWithRetry(args) {
+    var _a;
     const { url, options = {}, retryConfig = {}, customFetch } = args;
     const config = Object.assign(Object.assign({}, DEFAULT_RETRY_CONFIG), retryConfig);
     const { timeout, signal: userSignal } = options, fetchOptions = __rest(options, ["timeout", "signal"]);
@@ -120,13 +121,24 @@ async function fetchWithRetry(args) {
                 fetchResponse = await customFetch(url, Object.assign(Object.assign({}, fetchOptions), { signal: requestSignal, timeout }));
             }
             else {
-                const dispatcher = await (0, http_dispatcher_1.getDefaultDispatcher)();
+                // 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)();
                 const nativeFetchOptions = Object.assign(Object.assign({}, fetchOptions), { signal: requestSignal });
-                if (dispatcher !== undefined) {
+                if ((transport === null || transport === void 0 ? void 0 : transport.dispatcher) !== undefined) {
                     // @ts-expect-error - dispatcher is a valid option for Node.js fetch but not in the TS types
-                    nativeFetchOptions.dispatcher = dispatcher;
+                    nativeFetchOptions.dispatcher = transport.dispatcher;
                 }
-                const nativeResponse = await fetch(url, nativeFetchOptions);
+                // undici's `fetch` and the global `fetch` are the same function
+                // at runtime but carry different (undici vs DOM) types. Call
+                // through the global signature, which matches the options above.
+                const fetchImpl = ((_a = transport === null || transport === void 0 ? void 0 : transport.fetch) !== null && _a !== void 0 ? _a : fetch);
+                const nativeResponse = await fetchImpl(url, nativeFetchOptions);
                 fetchResponse = convertResponseToCustomFetch(nativeResponse);
             }
             // Check if the response is successful
@@ -148,13 +160,13 @@ async function fetchWithRetry(args) {
                     try {
                         responseData = responseText ? JSON.parse(responseText) : undefined;
                     }
-                    catch (_a) {
+                    catch (_b) {
                         responseData = responseText;
                     }
                     error.data = responseData;
                     error.response.data = responseData;
                 }
-                catch (_b) {
+                catch (_c) {
                     // If we can't read the response body, that's OK
                 }
                 throw error;
@@ -165,7 +177,7 @@ async function fetchWithRetry(args) {
             try {
                 data = responseText ? JSON.parse(responseText) : undefined;
             }
-            catch (_c) {
+            catch (_d) {
                 // If JSON parsing fails, return the raw text
                 data = responseText;
             }

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

@@ -33,7 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultTransport = getDefaultTransport;
 exports.getDefaultDispatcher = getDefaultDispatcher;
+exports.getDefaultFetch = getDefaultFetch;
 exports.resetDefaultDispatcherForTests = resetDefaultDispatcherForTests;
 exports.suppressExperimentalWarningsSync = suppressExperimentalWarningsSync;
 // Use effectively-disabled keep-alive so short-lived CLI processes do not stay
@@ -42,32 +44,68 @@ const KEEP_ALIVE_OPTIONS = {
     keepAliveTimeout: 1,
     keepAliveMaxTimeout: 1,
 };
-let defaultDispatcherPromise;
-function getDefaultDispatcher() {
+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.
+ */
+function getDefaultTransport() {
     if (!isNodeEnvironment()) {
         return Promise.resolve(undefined);
     }
-    if (!defaultDispatcherPromise) {
-        defaultDispatcherPromise = createDefaultDispatcher().catch((error) => {
-            defaultDispatcherPromise = undefined;
+    if (!defaultTransportPromise) {
+        defaultTransportPromise = createDefaultTransport()
+            .then((transport) => {
+            defaultTransport = transport;
+            return transport;
+        })
+            .catch((error) => {
+            defaultTransport = undefined;
+            defaultTransportPromise = undefined;
             throw error;
         });
     }
-    return defaultDispatcherPromise;
+    return defaultTransportPromise;
+}
+async function getDefaultDispatcher() {
+    var _a;
+    return (_a = (await getDefaultTransport())) === null || _a === void 0 ? void 0 : _a.dispatcher;
+}
+/**
+ * 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 === null || defaultTransport === void 0 ? void 0 : defaultTransport.fetch;
 }
 async function resetDefaultDispatcherForTests() {
-    if (!defaultDispatcherPromise) {
+    if (!defaultTransportPromise) {
         return;
     }
-    const dispatcherPromise = defaultDispatcherPromise;
-    defaultDispatcherPromise = undefined;
-    await dispatcherPromise.then((dispatcher) => dispatcher.close(), () => undefined);
+    const transportPromise = defaultTransportPromise;
+    defaultTransport = undefined;
+    defaultTransportPromise = undefined;
+    await transportPromise.then((transport) => transport.dispatcher.close(), () => undefined);
 }
-async function createDefaultDispatcher() {
+async function createDefaultTransport() {
     // Dynamic import so non-Node consumers (browser, edge runtimes) don't pull
-    // undici into their bundle. `getDefaultDispatcher` already short-circuits
+    // undici into their bundle. `getDefaultTransport` already short-circuits
     // outside Node, so this branch only runs when undici is safe to load.
-    const { EnvHttpProxyAgent, interceptors } = await Promise.resolve().then(() => __importStar(require('undici')));
+    const { EnvHttpProxyAgent, interceptors, fetch: undiciFetch } = await Promise.resolve().then(() => __importStar(require('undici')));
     const agent = new EnvHttpProxyAgent(KEEP_ALIVE_OPTIONS);
     // Some runtimes report `process.versions.node` (so `isNodeEnvironment()`
     // passes) but ship only a partial undici: `interceptors.decompress` is
@@ -76,7 +114,9 @@ async function createDefaultDispatcher() {
     // gzip/deflate/br/zstd natively — so skip the interceptor instead of
     // crashing on the missing API.
     if (typeof interceptors.decompress !== 'function') {
-        return agent;
+        // Bun: pair the agent with the global `fetch` (undefined), which
+        // decompresses natively.
+        return { dispatcher: agent, fetch: undefined };
     }
     // Compose the response-decompression interceptor so gzip/deflate/br/zstd
     // bodies are decoded before consumers parse them. Required on Node 24+:
@@ -85,7 +125,12 @@ async function createDefaultDispatcher() {
     // so callers receive raw gzipped bytes and `JSON.parse` fails.
     // See https://github.com/Doist/todoist-cli/issues/318.
     const decompress = suppressExperimentalWarningsSync(() => 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 };
 }
 // undici emits an `ExperimentalWarning` the first time `interceptors.decompress()`
 // runs. The interceptor is stable for our gzipped-JSON-over-HTTPS use case;

package/dist/esm/authentication.js

@@ -99,32 +99,74 @@ export function getAuthorizationUrl({ clientId, permissions, state, baseUrl, })
  * @returns The access token response
  * @throws {@link TodoistRequestError} If the token exchange fails
  */
-export async function getAuthToken(args, options) {
+/**
+ * Posts a payload to the OAuth token endpoint and returns the token response,
+ * mapping any failure to a {@link TodoistRequestError} with `errorMessage`.
+ * Shared by {@link getAuthToken} and {@link refreshAuthToken}.
+ */
+async function requestAuthToken(payload, errorMessage, options) {
     var _a;
-    if (typeof options === 'string') {
-        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
-    }
-    const baseUrl = options === null || options === void 0 ? void 0 : options.baseUrl;
-    const customFetch = options === null || options === void 0 ? void 0 : options.customFetch;
     try {
         const response = await request({
             httpMethod: 'POST',
-            baseUri: getAuthBaseUri(baseUrl),
+            baseUri: getAuthBaseUri(options === null || options === void 0 ? void 0 : options.baseUrl),
             relativePath: ENDPOINT_GET_TOKEN,
             apiToken: undefined,
-            payload: args,
-            customFetch,
+            payload,
+            customFetch: options === null || options === void 0 ? void 0 : options.customFetch,
         });
         if (response.status !== 200 || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
-            throw new TodoistRequestError('Authentication token exchange failed.', response.status, response.data);
+            throw new TodoistRequestError(errorMessage, response.status, response.data);
         }
         return response.data;
     }
     catch (error) {
         // Re-throw with custom message for authentication failures
         const err = error;
-        throw new TodoistRequestError('Authentication token exchange failed.', err.httpStatusCode, err.responseData);
+        throw new TodoistRequestError(errorMessage, err.httpStatusCode, err.responseData);
+    }
+}
+export async function getAuthToken(args, options) {
+    if (typeof options === 'string') {
+        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
+    }
+    return requestAuthToken(Object.assign({}, args), 'Authentication token exchange failed.', options);
+}
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * Only relevant for OAuth apps that have refresh tokens enabled (the default for
+ * new apps). Apps without them never receive a `refreshToken` from
+ * {@link getAuthToken}, so they have nothing to pass here — their access tokens
+ * are long-lived instead.
+ *
+ * Omit `clientSecret` for public clients registered with
+ * `tokenEndpointAuthMethod: 'none'`.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The server rotates the refresh token, so the
+ * response carries a new `refreshToken` — persist it in place of the old one.
+ * @throws {@link TodoistRequestError} If the refresh fails
+ */
+export async function refreshAuthToken(args, options) {
+    const payload = {
+        clientId: args.clientId,
+        refreshToken: args.refreshToken,
+        grantType: 'refresh_token',
+    };
+    if (args.clientSecret !== undefined) {
+        payload.clientSecret = args.clientSecret;
     }
+    return requestAuthToken(payload, 'Authentication token refresh failed.', options);
 }
 /**
  * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.

package/dist/esm/test-utils/transport-seam.js

@@ -0,0 +1,15 @@
+import { 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 with `vi.unmock('./http-dispatcher')`.
+//
+// This lives in its own setup file (not `msw-setup.ts`) because a hoisted
+// `vi.mock` in a module that also re-exports values corrupts those exports.
+vi.mock('../transport/http-dispatcher', async (importOriginal) => {
+    const actual = await importOriginal();
+    return Object.assign(Object.assign({}, actual), { getDefaultTransport: vi.fn(async () => undefined) });
+});

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

@@ -10,7 +10,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 import { isNetworkError } from '../types/http.js';
-import { getDefaultDispatcher } from './http-dispatcher.js';
+import { getDefaultTransport } from './http-dispatcher.js';
 /**
  * Default retry configuration matching the original axios-retry behavior
  */
@@ -96,6 +96,7 @@ function convertResponseToCustomFetch(response) {
  * Performs a fetch request with retry logic and timeout support
  */
 export async function fetchWithRetry(args) {
+    var _a;
     const { url, options = {}, retryConfig = {}, customFetch } = args;
     const config = Object.assign(Object.assign({}, DEFAULT_RETRY_CONFIG), retryConfig);
     const { timeout, signal: userSignal } = options, fetchOptions = __rest(options, ["timeout", "signal"]);
@@ -117,13 +118,24 @@ export async function fetchWithRetry(args) {
                 fetchResponse = await customFetch(url, Object.assign(Object.assign({}, fetchOptions), { signal: requestSignal, timeout }));
             }
             else {
-                const dispatcher = await getDefaultDispatcher();
+                // 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();
                 const nativeFetchOptions = Object.assign(Object.assign({}, fetchOptions), { signal: requestSignal });
-                if (dispatcher !== undefined) {
+                if ((transport === null || transport === void 0 ? void 0 : transport.dispatcher) !== undefined) {
                     // @ts-expect-error - dispatcher is a valid option for Node.js fetch but not in the TS types
-                    nativeFetchOptions.dispatcher = dispatcher;
+                    nativeFetchOptions.dispatcher = transport.dispatcher;
                 }
-                const nativeResponse = await fetch(url, nativeFetchOptions);
+                // undici's `fetch` and the global `fetch` are the same function
+                // at runtime but carry different (undici vs DOM) types. Call
+                // through the global signature, which matches the options above.
+                const fetchImpl = ((_a = transport === null || transport === void 0 ? void 0 : transport.fetch) !== null && _a !== void 0 ? _a : fetch);
+                const nativeResponse = await fetchImpl(url, nativeFetchOptions);
                 fetchResponse = convertResponseToCustomFetch(nativeResponse);
             }
             // Check if the response is successful
@@ -145,13 +157,13 @@ export async function fetchWithRetry(args) {
                     try {
                         responseData = responseText ? JSON.parse(responseText) : undefined;
                     }
-                    catch (_a) {
+                    catch (_b) {
                         responseData = responseText;
                     }
                     error.data = responseData;
                     error.response.data = responseData;
                 }
-                catch (_b) {
+                catch (_c) {
                     // If we can't read the response body, that's OK
                 }
                 throw error;
@@ -162,7 +174,7 @@ export async function fetchWithRetry(args) {
             try {
                 data = responseText ? JSON.parse(responseText) : undefined;
             }
-            catch (_c) {
+            catch (_d) {
                 // If JSON parsing fails, return the raw text
                 data = responseText;
             }

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

@@ -4,32 +4,68 @@ const KEEP_ALIVE_OPTIONS = {
     keepAliveTimeout: 1,
     keepAliveMaxTimeout: 1,
 };
-let defaultDispatcherPromise;
-export function getDefaultDispatcher() {
+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 function getDefaultTransport() {
     if (!isNodeEnvironment()) {
         return Promise.resolve(undefined);
     }
-    if (!defaultDispatcherPromise) {
-        defaultDispatcherPromise = createDefaultDispatcher().catch((error) => {
-            defaultDispatcherPromise = undefined;
+    if (!defaultTransportPromise) {
+        defaultTransportPromise = createDefaultTransport()
+            .then((transport) => {
+            defaultTransport = transport;
+            return transport;
+        })
+            .catch((error) => {
+            defaultTransport = undefined;
+            defaultTransportPromise = undefined;
             throw error;
         });
     }
-    return defaultDispatcherPromise;
+    return defaultTransportPromise;
+}
+export async function getDefaultDispatcher() {
+    var _a;
+    return (_a = (await getDefaultTransport())) === null || _a === void 0 ? void 0 : _a.dispatcher;
+}
+/**
+ * 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 === null || defaultTransport === void 0 ? void 0 : defaultTransport.fetch;
 }
 export async function resetDefaultDispatcherForTests() {
-    if (!defaultDispatcherPromise) {
+    if (!defaultTransportPromise) {
         return;
     }
-    const dispatcherPromise = defaultDispatcherPromise;
-    defaultDispatcherPromise = undefined;
-    await dispatcherPromise.then((dispatcher) => dispatcher.close(), () => undefined);
+    const transportPromise = defaultTransportPromise;
+    defaultTransport = undefined;
+    defaultTransportPromise = undefined;
+    await transportPromise.then((transport) => transport.dispatcher.close(), () => undefined);
 }
-async function createDefaultDispatcher() {
+async function createDefaultTransport() {
     // Dynamic import so non-Node consumers (browser, edge runtimes) don't pull
-    // undici into their bundle. `getDefaultDispatcher` already short-circuits
+    // undici into their bundle. `getDefaultTransport` already short-circuits
     // outside Node, so this branch only runs when undici is safe to load.
-    const { EnvHttpProxyAgent, interceptors } = await import('undici');
+    const { EnvHttpProxyAgent, interceptors, fetch: undiciFetch } = await import('undici');
     const agent = new EnvHttpProxyAgent(KEEP_ALIVE_OPTIONS);
     // Some runtimes report `process.versions.node` (so `isNodeEnvironment()`
     // passes) but ship only a partial undici: `interceptors.decompress` is
@@ -38,7 +74,9 @@ async function createDefaultDispatcher() {
     // gzip/deflate/br/zstd natively — so skip the interceptor instead of
     // crashing on the missing API.
     if (typeof interceptors.decompress !== 'function') {
-        return agent;
+        // Bun: pair the agent with the global `fetch` (undefined), which
+        // decompresses natively.
+        return { dispatcher: agent, fetch: undefined };
     }
     // Compose the response-decompression interceptor so gzip/deflate/br/zstd
     // bodies are decoded before consumers parse them. Required on Node 24+:
@@ -47,7 +85,12 @@ async function createDefaultDispatcher() {
     // so callers receive raw gzipped bytes and `JSON.parse` fails.
     // See https://github.com/Doist/todoist-cli/issues/318.
     const decompress = suppressExperimentalWarningsSync(() => 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 };
 }
 // undici emits an `ExperimentalWarning` the first time `interceptors.decompress()`
 // runs. The interceptor is stable for our gzipped-JSON-over-HTTPS use case;

package/dist/types/authentication.d.ts

@@ -74,6 +74,31 @@ export type AuthTokenRequestArgs = {
 export type AuthTokenResponse = {
     accessToken: string;
     tokenType: string;
+    /**
+     * Refresh token for use with {@link refreshAuthToken}.
+     *
+     * Only present when the OAuth app has refresh tokens enabled — the default
+     * for new apps, and immutable once on. Apps without it receive a long-lived
+     * access token and no refresh token.
+     */
+    refreshToken?: string;
+    /** Access token lifetime in seconds. */
+    expiresIn?: number;
+    /** Space-separated granted scopes, when returned. */
+    scope?: string;
+};
+/**
+ * Parameters required to exchange a refresh token for a new access token.
+ * @see https://developer.todoist.com/api/v1/#tag/Authorization/OAuth
+ */
+export type RefreshTokenRequestArgs = {
+    clientId: string;
+    /**
+     * Client secret. Required for confidential clients; omit for public clients
+     * registered with `tokenEndpointAuthMethod: 'none'`.
+     */
+    clientSecret?: string;
+    refreshToken: string;
 };
 /**
  * Parameters required to revoke a token using RFC 7009 compliant endpoint.
@@ -148,22 +173,33 @@ export declare function getAuthorizationUrl({ clientId, permissions, state, base
     state: string;
     baseUrl?: string;
 }): string;
+export declare function getAuthToken(args: AuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
 /**
- * Exchanges an authorization code for an access token.
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * Only relevant for OAuth apps that have refresh tokens enabled (the default for
+ * new apps). Apps without them never receive a `refreshToken` from
+ * {@link getAuthToken}, so they have nothing to pass here — their access tokens
+ * are long-lived instead.
+ *
+ * Omit `clientSecret` for public clients registered with
+ * `tokenEndpointAuthMethod: 'none'`.
  *
  * @example
  * ```typescript
- * const { accessToken } = await getAuthToken({
+ * const { accessToken, refreshToken } = await refreshAuthToken({
  *   clientId: 'your-client-id',
  *   clientSecret: 'your-client-secret',
- *   code: authCode
+ *   refreshToken: storedRefreshToken,
  * })
  * ```
  *
- * @returns The access token response
- * @throws {@link TodoistRequestError} If the token exchange fails
+ * @returns The refreshed token. The server rotates the refresh token, so the
+ * response carries a new `refreshToken` — persist it in place of the old one.
+ * @throws {@link TodoistRequestError} If the refresh fails
  */
-export declare function getAuthToken(args: AuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
+export declare function refreshAuthToken(args: RefreshTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
 /**
  * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.
  *

package/dist/types/test-utils/transport-seam.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -1,4 +1,40 @@
 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>;
+/**
+ * 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 resetDefaultDispatcherForTests(): Promise<void>;
 export declare function suppressExperimentalWarningsSync<T>(fn: () => T): T;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/todoist-sdk",
-    "version": "10.4.1",
+    "version": "10.5.1",
     "description": "The official TypeScript SDK for the Todoist REST API.",
     "author": "Doist developers",
     "repository": "https://github.com/Doist/todoist-sdk-typescript",