@doist/comms-sdk 3.6.0 → 3.7.0

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

@@ -1,4 +1,5 @@
 import { 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();
@@ -25,7 +26,7 @@ function getRequestConfiguration(baseURL, apiToken, requestId, customHeaders) {
     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 clobber them.
-    const headers = { ...defaultHeaders, ...customHeaders, ...authHeader, ...requestIdHeader };
+    const headers = mergeHeaders(defaultHeaders, resolveCustomHeaders(customHeaders), authHeader, requestIdHeader);
     return { baseURL, headers, timeout: 30000 };
 }
 export async function request(args) {

package/dist/esm/utils/headers.js

@@ -0,0 +1,29 @@
+/**
+ * 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

@@ -1,5 +1,6 @@
 import { v4 as uuid } from 'uuid';
 import { fetchWithRetry } from '../transport/fetch-with-retry.js';
+import { mergeHeaders, resolveCustomHeaders } from './headers.js';
 /**
  * Determine a content-type from a filename extension. Falls back to
  * `application/octet-stream` for unknown extensions.
@@ -178,16 +179,14 @@ export async function uploadMultipartFile(args) {
         contentType: resolvedType,
         fields,
     });
-    const headers = {
-        ...customHeaders,
+    // Custom headers come first so they can never replace the SDK's own.
+    const headers = mergeHeaders(resolveCustomHeaders(customHeaders), {
         Authorization: `Bearer ${authToken}`,
         // The boundary is ours, so this has to be declared explicitly — `fetch`
         // only fills it in for a `FormData` body.
         'Content-Type': multipart.contentType,
-    };
-    if (requestId) {
-        headers['X-Request-Id'] = requestId;
-    }
+        ...(requestId ? { 'X-Request-Id': requestId } : {}),
+    });
     const url = new URL(endpoint, baseUrl).toString();
     const response = await fetchWithRetry(url, {
         method: 'POST',

package/dist/types/clients/add-comment-helper.d.ts

@@ -1,11 +1,11 @@
 import { type Comment, type createCommentSchema } from '../types/entities.js';
-import type { CustomFetch } from '../types/http.js';
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
 import type { CreateCommentArgs, ThreadAction } from '../types/requests.js';
 type ClientContext = {
     baseUri: string;
     apiToken: string;
     customFetch?: CustomFetch;
-    headers?: Record<string, string>;
+    headers?: CustomHeaders;
     /** Per-client Comment schema, base-bound for the returned comment's web `url`. */
     schema: ReturnType<typeof createCommentSchema>;
 };

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

@@ -1,5 +1,5 @@
 import type { ApiVersion } from '../types/api-version.js';
-import type { CustomFetch } from '../types/http.js';
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
 export type ClientConfig = {
     /** API token for authentication */
     apiToken: string;
@@ -9,8 +9,8 @@ export type ClientConfig = {
     version?: ApiVersion;
     /** Optional custom fetch implementation for cross-platform compatibility */
     customFetch?: CustomFetch;
-    /** Optional headers sent with every request */
-    headers?: Record<string, string>;
+    /** Optional headers sent with every request, or a function called once per request */
+    headers?: CustomHeaders;
 };
 /**
  * Base class for every Comms API client. Centralizes URL handling and
@@ -21,7 +21,7 @@ export declare class BaseClient {
     protected readonly baseUrl?: string;
     protected readonly defaultVersion: ApiVersion;
     protected readonly customFetch?: CustomFetch;
-    protected readonly headers?: Record<string, string>;
+    protected readonly headers?: CustomHeaders;
     constructor(config: ClientConfig);
     /**
      * Returns the base URI for an API request, with a guaranteed trailing

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

@@ -13,7 +13,7 @@ import { UsersClient } from './clients/users-client.js';
 import { WorkspaceUsersClient } from './clients/workspace-users-client.js';
 import { WorkspacesClient } from './clients/workspaces-client.js';
 import type { ApiVersion } from './types/api-version.js';
-import type { CustomFetch } from './types/http.js';
+import type { CustomFetch, CustomHeaders } from './types/http.js';
 export type CommsApiOptions = {
     /** Optional custom API base URL. If not provided, defaults to Comms' standard API endpoint. */
     baseUrl?: string;
@@ -21,8 +21,13 @@ export type CommsApiOptions = {
     version?: ApiVersion;
     /** Optional custom fetch implementation for cross-platform compatibility (e.g., Obsidian, React Native, Electron). */
     customFetch?: CustomFetch;
-    /** Optional headers sent with every request, e.g. `{ 'Doist-Platform': 'cli' }` for client attribution. Cannot override `Authorization` or `X-Request-Id`. */
-    headers?: Record<string, string>;
+    /**
+     * Optional headers sent with every 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 override `Authorization`
+     * or `X-Request-Id`.
+     */
+    headers?: CustomHeaders;
 };
 /**
  * The main API client for interacting with the Comms REST API.

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';
 export declare function paramsSerializer(params: Record<string, unknown>): string;
 export type RequestArgs = {
     httpMethod: HttpMethod;
@@ -7,7 +7,7 @@ export type RequestArgs = {
     apiToken?: string;
     payload?: Record<string, unknown>;
     requestId?: string;
-    headers?: Record<string, string>;
+    headers?: CustomHeaders;
     customFetch?: CustomFetch;
 };
 export declare function request<T>(args: RequestArgs): Promise<HttpResponse<T>>;

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

@@ -5,6 +5,12 @@ export type HttpResponse<T = unknown> = {
     status: number;
     headers: Record<string, string>;
 };
+/**
+ * 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>);
 export type RequestConfig = {
     baseURL?: string;
     headers?: Record<string, string>;

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

@@ -0,0 +1,13 @@
+import type { CustomHeaders } from '../types/http.js';
+/**
+ * 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';
 /**
  * File content accepted by the upload helpers.
  *
@@ -33,8 +33,8 @@ type UploadMultipartFileArgs = {
     maxRetries?: number;
     /** Optional request ID for tracing. */
     requestId?: string;
-    /** Optional headers sent with the request. Cannot override `Authorization` or `Content-Type`. */
-    headers?: Record<string, string>;
+    /** Optional headers sent with the request. Cannot override `Authorization`, `X-Request-Id` or `Content-Type`. */
+    headers?: CustomHeaders;
     /** Optional custom fetch implementation. */
     customFetch?: CustomFetch;
 };

package/package.json

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