@doist/todoist-sdk 15.5.0 → 15.7.0

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

@@ -3,6 +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, resolveCustomHeaders } from '../utils/headers.js';
 import { fetchWithRetry } from './fetch-with-retry.js';
 export function paramsSerializer(params) {
     const qs = new URLSearchParams();
@@ -59,7 +60,8 @@ function getRequestConfiguration(args) {
     const { baseURL, apiToken, requestId, customHeaders } = args;
     const authHeader = apiToken ? { Authorization: getAuthHeader(apiToken) } : undefined;
     const requestIdHeader = requestId ? { 'X-Request-Id': requestId } : undefined;
-    const headers = Object.assign(Object.assign(Object.assign(Object.assign({}, defaultHeaders), authHeader), requestIdHeader), customHeaders);
+    // Custom headers sit below auth and request id so they can never replace them.
+    const headers = mergeHeaders(defaultHeaders, resolveCustomHeaders(customHeaders), authHeader, requestIdHeader);
     return { baseURL, headers };
 }
 function getHttpClientConfig(args) {

package/dist/esm/transport/sync-request.js

@@ -62,7 +62,7 @@ function preprocessSyncCommands(commands) {
 /**
  * Makes a request to the Sync API and handles error checking.
  *
- * @param ctx - HTTP identity (auth token, sync API base URI, optional custom fetch).
+ * @param ctx - HTTP identity (auth token, sync API base URI, optional custom fetch and headers).
  * @param syncRequest - The sync request payload.
  * @param options - Optional request identifier and commands flag.
  * @returns The sync response data.
@@ -79,6 +79,7 @@ export async function performSyncRequest(ctx, syncRequest, options = {}) {
         relativePath: ENDPOINT_SYNC,
         apiToken: ctx.authToken,
         customFetch: ctx.customFetch,
+        customHeaders: ctx.customHeaders,
         payload: processedRequest,
         requestId: requestId,
         hasSyncCommands: hasSyncCommands,

package/dist/esm/utils/colors.js

@@ -101,8 +101,7 @@ export const taupe = {
 };
 /**
  * Every color, in the order the apps show them. The keys mirror `TodoistColor` from
- * `@doist/sdk-kmp/shared-todoist-all`, which a test checks; the display names and hex values are
- * the SDK's own.
+ * `@doist/sdk-kmp/shared-todoist-all`; the display names and hex values are the SDK's own.
  */
 export const colors = [
     berryRed,

package/dist/esm/utils/headers.js

@@ -11,3 +11,32 @@ export function headersToRecord(headers) {
     });
     return result;
 }
+/**
+ * Merges header records left to right. HTTP header names are case-insensitive,
+ * so a later record replaces any earlier header with the same name whatever
+ * its case. Without this, a caller's `authorization` would sit alongside the
+ * SDK's `Authorization` and `fetch` would join the two into one value.
+ */
+export function mergeHeaders(...sources) {
+    const merged = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const [name, value] of Object.entries(source)) {
+            const lowerName = name.toLowerCase();
+            for (const existingName of Object.keys(merged)) {
+                if (existingName.toLowerCase() === lowerName)
+                    delete merged[existingName];
+            }
+            merged[name] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * Turns the `headers` option into the record to send with one request, calling
+ * it when it is a function so per-request values are fresh.
+ */
+export function resolveCustomHeaders(headers) {
+    return typeof headers === 'function' ? headers() : headers;
+}

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

@@ -22,6 +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, resolveCustomHeaders } from './headers.js';
 /**
  * Helper function to determine content-type from filename extension.
  * @param fileName - The filename to analyze
@@ -199,18 +200,12 @@ function buildMultipartBody(args) {
  * ```
  */
 export async function uploadMultipartFile(args) {
-    const { baseUrl, authToken, endpoint, file, fileName, additionalFields, requestId, customFetch, } = args;
+    const { baseUrl, authToken, endpoint, file, fileName, additionalFields, requestId, customHeaders, customFetch, } = args;
     // Capture original stack for better error reporting
     const originalStack = new Error();
     // Build the full URL
     const url = `${baseUrl}${endpoint}`;
     let body;
-    const headers = {
-        Authorization: `Bearer ${authToken}`,
-    };
-    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.
@@ -251,9 +246,11 @@ export async function uploadMultipartFile(args) {
             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;
+    // Custom headers come first so they can never replace the SDK's own.
+    const headers = mergeHeaders(resolveCustomHeaders(customHeaders), Object.assign(Object.assign({ Authorization: `Bearer ${authToken}` }, (requestId ? { 'X-Request-Id': requestId } : {})), { 
+        // The boundary is ours, so Content-Type has to be set explicitly —
+        // `fetch` only fills it in for a `FormData` body.
+        'Content-Type': multipart.contentType }));
     body = multipart.body;
     // Make the request using fetch
     let response;

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

@@ -1,10 +1,10 @@
 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, …).
  *
  * Not exported from the package — sub-clients are an implementation detail
- * of `TodoistApi`. Holds the three pieces of HTTP identity every sub-client
+ * of `TodoistApi`. Holds the pieces of HTTP identity every sub-client
  * needs and exposes a typed accessor to feed the Sync API helper.
  *
  * The constructor takes a {@link SyncRequestContext} — the same record
@@ -17,6 +17,7 @@ export declare abstract class BaseClient {
     protected readonly syncApiBase: string;
     protected readonly apiRootBase: string;
     protected readonly customFetch?: CustomFetch;
+    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';
@@ -55,11 +55,19 @@ export type TodoistApiOptions = {
      * Optional custom fetch function for alternative HTTP clients (e.g., Obsidian's requestUrl, React Native fetch)
      */
     customFetch?: CustomFetch;
+    /**
+     * Optional headers sent with every API request, e.g. `{ 'Doist-Platform': 'cli' }` for client
+     * 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?: CustomHeaders;
 };
 export declare class TodoistApi {
     private authToken;
     private syncApiBase;
     private customFetch?;
+    private customHeaders?;
     private readonly taskClient;
     private readonly projectClient;
     private readonly sectionClient;

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,11 +11,12 @@ export type SyncRequestContext = {
     authToken: string;
     syncApiBase: string;
     customFetch?: CustomFetch;
+    customHeaders?: CustomHeaders;
 };
 /**
  * Makes a request to the Sync API and handles error checking.
  *
- * @param ctx - HTTP identity (auth token, sync API base URI, optional custom fetch).
+ * @param ctx - HTTP identity (auth token, sync API base URI, optional custom fetch and headers).
  * @param syncRequest - The sync request payload.
  * @param options - Optional request identifier and commands flag.
  * @returns The sync response data.

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/colors.d.ts

@@ -101,8 +101,7 @@ export declare const taupe: {
 };
 /**
  * Every color, in the order the apps show them. The keys mirror `TodoistColor` from
- * `@doist/sdk-kmp/shared-todoist-all`, which a test checks; the display names and hex values are
- * the SDK's own.
+ * `@doist/sdk-kmp/shared-todoist-all`; the display names and hex values are the SDK's own.
  */
 export declare const colors: readonly [{
     readonly key: "berry_red";

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`
@@ -5,3 +6,15 @@
  * `CustomFetchResponse`).
  */
 export declare function headersToRecord(headers: Headers): Record<string, string>;
+/**
+ * Merges header records left to right. HTTP header names are case-insensitive,
+ * so a later record replaces any earlier header with the same name whatever
+ * its case. Without this, a caller's `authorization` would sit alongside the
+ * SDK's `Authorization` and `fetch` would join the two into one value.
+ */
+export 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;
@@ -7,6 +7,8 @@ type UploadMultipartFileArgs = {
     fileName?: string;
     additionalFields: Record<string, string | number | boolean>;
     requestId?: string;
+    /** Extra headers sent with the upload. Cannot replace `Authorization`, `X-Request-Id` or `Content-Type`. */
+    customHeaders?: CustomHeaders;
     customFetch?: CustomFetch;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/todoist-sdk",
-    "version": "15.5.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",
@@ -65,7 +65,7 @@
         "msw": "2.13.2",
         "npm-run-all2": "8.0.4",
         "obsidian": "^1.10.2-1",
-        "oxfmt": "0.43.0",
+        "oxfmt": "0.73.0",
         "oxlint": "1.57.0",
         "rimraf": "6.1.3",
         "semantic-release": "25.0.3",