@doist/todoist-sdk 15.6.0 → 15.7.0

package/README.md

@@ -50,6 +50,16 @@ const api = new TodoistApi('YOURTOKEN', {
 })
 ```
 
+For values that change between requests, pass a function instead. The SDK calls it once per request, and a retried request reuses its result:
+
+```typescript
+import { randomUUID } from 'node:crypto'
+
+const api = new TodoistApi('YOURTOKEN', {
+    headers: () => ({ 'Doist-Platform': 'cli', 'Request-Id': randomUUID() }),
+})
+```
+
 These headers cannot replace `Authorization`, `X-Request-Id` or the multipart `Content-Type`; the SDK's own values always win. They are not sent on attachment downloads (`viewAttachment`), which redirect to a third-party CDN. The OAuth helpers (`getAuthToken`, `refreshAuthToken`, `revokeToken`, …) take their own options and do not send them.
 
 ## Custom HTTP Clients

package/dist/esm/clients/backup-client.js

@@ -1,7 +1,7 @@
 import { ENDPOINT_REST_BACKUPS, ENDPOINT_REST_BACKUPS_DOWNLOAD } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
 import { wrapAsFileResponse } from '../utils/file-response.js';
-import { mergeHeaders } from '../utils/headers.js';
+import { mergeHeaders, resolveCustomHeaders } from '../utils/headers.js';
 import { validateBackupArray } from '../utils/validators.js';
 import { BaseClient } from './base-client.js';
 /**
@@ -27,7 +27,7 @@ export class BackupClient extends BaseClient {
     async downloadBackup(args) {
         const url = `${this.syncApiBase}${ENDPOINT_REST_BACKUPS_DOWNLOAD}?file=${encodeURIComponent(args.file)}`;
         const fetchOptions = {
-            headers: mergeHeaders(this.customHeaders, {
+            headers: mergeHeaders(resolveCustomHeaders(this.customHeaders), {
                 Authorization: `Bearer ${this.authToken}`,
             }),
         };

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

@@ -3,7 +3,7 @@ import { API_BASE_URI } from '../consts/endpoints.js';
 import { TodoistRequestError } from '../types/errors.js';
 import { isHttpError, isNetworkError } from '../types/http.js';
 import { camelCaseKeys, snakeCaseKeys } from '../utils/case-conversion.js';
-import { mergeHeaders } from '../utils/headers.js';
+import { mergeHeaders, resolveCustomHeaders } from '../utils/headers.js';
 import { fetchWithRetry } from './fetch-with-retry.js';
 export function paramsSerializer(params) {
     const qs = new URLSearchParams();
@@ -61,7 +61,7 @@ function getRequestConfiguration(args) {
     const authHeader = apiToken ? { Authorization: getAuthHeader(apiToken) } : undefined;
     const requestIdHeader = requestId ? { 'X-Request-Id': requestId } : undefined;
     // Custom headers sit below auth and request id so they can never replace them.
-    const headers = mergeHeaders(defaultHeaders, customHeaders, authHeader, requestIdHeader);
+    const headers = mergeHeaders(defaultHeaders, resolveCustomHeaders(customHeaders), authHeader, requestIdHeader);
     return { baseURL, headers };
 }
 function getHttpClientConfig(args) {

package/dist/esm/utils/headers.js

@@ -33,3 +33,10 @@ export function mergeHeaders(...sources) {
     }
     return merged;
 }
+/**
+ * Turns the `headers` option into the record to send with one request, calling
+ * it when it is a function so per-request values are fresh.
+ */
+export function resolveCustomHeaders(headers) {
+    return typeof headers === 'function' ? headers() : headers;
+}

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

@@ -22,7 +22,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { fetchWithRetry } from '../transport/fetch-with-retry.js';
 import { toTodoistRequestError } from '../transport/http-client.js';
 import { camelCaseKeys } from './case-conversion.js';
-import { mergeHeaders } from './headers.js';
+import { mergeHeaders, resolveCustomHeaders } from './headers.js';
 /**
  * Helper function to determine content-type from filename extension.
  * @param fileName - The filename to analyze
@@ -247,7 +247,7 @@ export async function uploadMultipartFile(args) {
         additionalFields,
     });
     // Custom headers come first so they can never replace the SDK's own.
-    const headers = mergeHeaders(customHeaders, Object.assign(Object.assign({ Authorization: `Bearer ${authToken}` }, (requestId ? { 'X-Request-Id': requestId } : {})), { 
+    const headers = mergeHeaders(resolveCustomHeaders(customHeaders), Object.assign(Object.assign({ Authorization: `Bearer ${authToken}` }, (requestId ? { 'X-Request-Id': requestId } : {})), { 
         // The boundary is ours, so Content-Type has to be set explicitly —
         // `fetch` only fills it in for a `FormData` body.
         'Content-Type': multipart.contentType }));

package/dist/types/clients/base-client.d.ts

@@ -1,5 +1,5 @@
 import type { SyncRequestContext } from '../transport/sync-request.js';
-import type { CustomFetch } from '../types/http.js';
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
 /**
  * Internal base class for every domain sub-client (tasks, projects, …).
  *
@@ -17,7 +17,7 @@ export declare abstract class BaseClient {
     protected readonly syncApiBase: string;
     protected readonly apiRootBase: string;
     protected readonly customFetch?: CustomFetch;
-    protected readonly customHeaders?: Record<string, string>;
+    protected readonly customHeaders?: CustomHeaders;
     constructor(context: SyncRequestContext);
     protected get syncContext(): SyncRequestContext;
 }

package/dist/types/todoist-api.d.ts

@@ -6,7 +6,7 @@ import type { BillingPortalUrlResponse, CancelPlanArgs, CheckoutSessionResponse,
 import { Attachment, Comment, AddCommentArgs, UpdateCommentArgs, GetProjectCommentsArgs, GetTaskCommentsArgs, GetCommentsResponse } from './types/comments/index.js';
 import { GetOrCreateEmailArgs, GetOrCreateEmailResponse, DisableEmailArgs } from './types/emails/index.js';
 import { GetFoldersArgs, GetFoldersResponse, AddFolderArgs, UpdateFolderArgs } from './types/folders/index.js';
-import { CustomFetch, FileResponse } from './types/http.js';
+import { CustomFetch, CustomHeaders, FileResponse } from './types/http.js';
 import { IdMapping, MovedId, GetIdMappingsArgs, GetMovedIdsArgs } from './types/id-mappings/index.js';
 import { ProjectActivityStats, ProjectHealth, ProjectHealthContext, ProjectProgress, WorkspaceInsights, GetProjectActivityStatsArgs, GetWorkspaceInsightsArgs } from './types/insights/index.js';
 import { Label, AddLabelArgs, UpdateLabelArgs, GetLabelsArgs, SearchLabelsArgs, GetLabelsResponse, GetSharedLabelsArgs, GetSharedLabelsResponse, RenameSharedLabelArgs, RemoveSharedLabelArgs } from './types/labels/index.js';
@@ -57,10 +57,11 @@ export type TodoistApiOptions = {
     customFetch?: CustomFetch;
     /**
      * Optional headers sent with every API request, e.g. `{ 'Doist-Platform': 'cli' }` for client
-     * attribution. Cannot replace `Authorization` or `X-Request-Id`. Not sent on attachment
-     * downloads, which redirect to a third-party CDN.
+     * attribution. Pass a function instead to compute them per request, e.g. a fresh request ID;
+     * it is called once per request and retries reuse its result. Cannot replace `Authorization`
+     * or `X-Request-Id`. Not sent on attachment downloads, which redirect to a third-party CDN.
      */
-    headers?: Record<string, string>;
+    headers?: CustomHeaders;
 };
 export declare class TodoistApi {
     private authToken;

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

@@ -1,4 +1,4 @@
-import type { CustomFetch, HttpMethod, HttpResponse } from '../types/http.js';
+import type { CustomFetch, CustomHeaders, HttpMethod, HttpResponse } from '../types/http.js';
 type RequestArgs = {
     httpMethod: HttpMethod;
     baseUri: string;
@@ -7,7 +7,7 @@ type RequestArgs = {
     payload?: Record<string, unknown>;
     requestId?: string;
     hasSyncCommands?: boolean;
-    customHeaders?: Record<string, string>;
+    customHeaders?: CustomHeaders;
     customFetch?: CustomFetch;
 };
 export declare function paramsSerializer(params: Record<string, unknown>): string;

package/dist/types/transport/sync-request.d.ts

@@ -1,4 +1,4 @@
-import type { CustomFetch } from '../types/http.js';
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
 import { type SyncRequest, type SyncResponse } from '../types/sync/index.js';
 /**
  * Shared context needed to issue Sync API requests.
@@ -11,7 +11,7 @@ export type SyncRequestContext = {
     authToken: string;
     syncApiBase: string;
     customFetch?: CustomFetch;
-    customHeaders?: Record<string, string>;
+    customHeaders?: CustomHeaders;
 };
 /**
  * Makes a request to the Sync API and handles error checking.

package/dist/types/types/http.d.ts

@@ -83,6 +83,12 @@ export type CustomFetchResponse = {
     json(): Promise<unknown>;
     arrayBuffer?: () => Promise<ArrayBuffer>;
 };
+/**
+ * Extra headers sent with every API request: either a fixed record, or a function
+ * the SDK calls once per request (retries reuse its result) for values that change
+ * between requests, such as a per-request ID or the command currently running.
+ */
+export type CustomHeaders = Record<string, string> | (() => Record<string, string>);
 /**
  * Custom fetch function type for alternative HTTP clients
  */

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

@@ -1,3 +1,4 @@
+import type { CustomHeaders } from '../types/http.js';
 /**
  * Converts a native Fetch `Headers` object into a plain `Record<string, string>`.
  * Used when wrapping a native `fetch` response into the SDK's `FileResponse`
@@ -12,3 +13,8 @@ export declare function headersToRecord(headers: Headers): Record<string, string
  * SDK's `Authorization` and `fetch` would join the two into one value.
  */
 export declare function mergeHeaders(...sources: (Record<string, string> | undefined)[]): Record<string, string>;
+/**
+ * Turns the `headers` option into the record to send with one request, calling
+ * it when it is a function so per-request values are fresh.
+ */
+export declare function resolveCustomHeaders(headers: CustomHeaders | undefined): Record<string, string> | undefined;

package/dist/types/utils/multipart-upload.d.ts

@@ -1,4 +1,4 @@
-import type { CustomFetch } from '../types/http.js';
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
 type UploadMultipartFileArgs = {
     baseUrl: string;
     authToken: string;
@@ -8,7 +8,7 @@ type UploadMultipartFileArgs = {
     additionalFields: Record<string, string | number | boolean>;
     requestId?: string;
     /** Extra headers sent with the upload. Cannot replace `Authorization`, `X-Request-Id` or `Content-Type`. */
-    customHeaders?: Record<string, string>;
+    customHeaders?: CustomHeaders;
     customFetch?: CustomFetch;
 };
 /**

package/package.json

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