@doist/comms-sdk 0.1.0-alpha.1

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

@@ -0,0 +1,45 @@
+import { HttpResponse, http } from 'msw';
+const BASE_URL = 'https://comms.todoist.com';
+/**
+ * Creates a successful API response with the given data
+ */
+export function createSuccessResponse(data) {
+    return HttpResponse.json(data, { status: 200 });
+}
+/**
+ * Creates an error API response
+ */
+export function createErrorResponse(errorCode, errorMessage, status = 400) {
+    return HttpResponse.json({
+        error_code: errorCode,
+        error_string: errorMessage,
+    }, { status });
+}
+/**
+ * Helper to create API endpoint URL
+ */
+export function apiUrl(path) {
+    // Remove leading slash if present
+    const cleanPath = path.startsWith('/') ? path.slice(1) : path;
+    return `${BASE_URL}/${cleanPath}`;
+}
+/**
+ * Creates a handler for a GET endpoint
+ */
+export function createGetHandler(endpoint, responseData) {
+    return http.get(apiUrl(endpoint), () => {
+        return createSuccessResponse(responseData);
+    });
+}
+/**
+ * Creates a handler for a POST endpoint
+ */
+export function createPostHandler(endpoint, responseData) {
+    return http.post(apiUrl(endpoint), () => {
+        return createSuccessResponse(responseData);
+    });
+}
+/**
+ * Export http from msw for custom handlers
+ */
+export { http, HttpResponse };

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

@@ -0,0 +1,18 @@
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+// Create MSW server instance
+export const server = setupServer();
+// Start server before all tests
+beforeAll(() => {
+    // Only warn on unhandled requests instead of error, since transport/http-client.test.ts
+    // uses direct fetch mocking which bypasses MSW
+    server.listen({ onUnhandledRequest: 'warn' });
+});
+// Reset handlers after each test
+afterEach(() => {
+    server.resetHandlers();
+});
+// Clean up after all tests
+afterAll(() => {
+    server.close();
+});

package/dist/esm/testUtils/obsidian-fetch-adapter.js

@@ -0,0 +1,50 @@
+/**
+ * Creates a CustomFetch adapter for Obsidian's requestUrl API.
+ *
+ * This adapter bridges the gap between Obsidian's requestUrl interface and the
+ * standard fetch-like interface expected by the Comms API SDK.
+ *
+ * Key differences handled by this adapter:
+ * - Obsidian returns response data as properties (response.json, response.text)
+ *   while the SDK expects methods (response.json(), response.text())
+ * - Obsidian's requestUrl bypasses CORS restrictions that would block standard fetch
+ * - Obsidian throws on HTTP errors by default; we set throw: false to handle manually
+ * - Obsidian doesn't provide statusText; we default to empty string
+ *
+ * @example
+ * ```typescript
+ * import { requestUrl } from 'obsidian'
+ * import { createObsidianFetchAdapter } from './obsidian-fetch-adapter.js'
+ *
+ * const api = new CommsApi('your-token', {
+ *   customFetch: createObsidianFetchAdapter(requestUrl)
+ * })
+ * ```
+ *
+ * @param requestUrl - The Obsidian requestUrl function
+ * @returns A CustomFetch function compatible with the Comms API SDK
+ */
+export function createObsidianFetchAdapter(requestUrl) {
+    return async (url, options) => {
+        // Build the request parameters in Obsidian's format
+        const requestParams = {
+            url,
+            method: options?.method || 'GET',
+            headers: options?.headers,
+            body: options?.body,
+            throw: false, // Don't throw on HTTP errors; let the SDK handle status codes
+        };
+        // Make the request using Obsidian's requestUrl
+        const response = await requestUrl(requestParams);
+        // Transform Obsidian's response format to match CustomFetchResponse interface
+        return {
+            ok: response.status >= 200 && response.status < 300,
+            status: response.status,
+            statusText: '', // Obsidian doesn't provide statusText
+            headers: response.headers,
+            // Wrap Obsidian's direct properties as methods returning promises
+            text: () => Promise.resolve(response.text),
+            json: () => Promise.resolve(response.json),
+        };
+    };
+}

package/dist/esm/testUtils/test-defaults.js

@@ -0,0 +1,99 @@
+export const TEST_API_TOKEN = 'test-api-token';
+// Canonical test IDs — shaped so they pass SDK-side validation.
+export const TEST_CHANNEL_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3y';
+export const TEST_THREAD_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3z';
+export const TEST_COMMENT_ID = '7YpL3oZ4kZ9vP7Q1tR2sX41';
+export const TEST_CONVERSATION_ID = '7YpL3oZ4kZ9vP7Q1tR2sX42';
+export const TEST_MESSAGE_ID = '7YpL3oZ4kZ9vP7Q1tR2sX43';
+export const TEST_GROUP_ID = '7YpL3oZ4kZ9vP7Q1tR2sX44';
+export const mockUser = {
+    id: 1,
+    email: 'test@example.com',
+    fullName: 'Test User',
+    shortName: 'TU',
+    timezone: 'America/New_York',
+    removed: false,
+    lang: 'en',
+};
+export const mockWorkspace = {
+    id: 1,
+    name: 'Test Workspace',
+    creator: 1,
+    created: new Date('2021-01-01T00:00:00Z'),
+};
+export const mockChannel = {
+    id: TEST_CHANNEL_ID,
+    name: 'general',
+    creator: 1,
+    public: true,
+    workspaceId: 1,
+    archived: false,
+    created: new Date('2021-01-01T00:00:00Z'),
+    version: 0,
+    url: `https://comms.todoist.com/a/1/ch/${TEST_CHANNEL_ID}/`,
+};
+export const mockThread = {
+    id: TEST_THREAD_ID,
+    title: 'Test Thread',
+    content: 'This is a test thread',
+    creator: 1,
+    channelId: TEST_CHANNEL_ID,
+    workspaceId: 1,
+    commentCount: 0,
+    lastUpdated: new Date('2021-01-01T00:00:00Z'),
+    pinned: false,
+    posted: new Date('2021-01-01T00:00:00Z'),
+    snippet: 'This is a test thread',
+    snippetCreator: 1,
+    isArchived: false,
+    url: `https://comms.todoist.com/a/1/ch/${TEST_CHANNEL_ID}/t/${TEST_THREAD_ID}/`,
+};
+export const mockGroup = {
+    id: TEST_GROUP_ID,
+    name: 'Test Group',
+    workspaceId: 1,
+    userIds: [1, 2, 3],
+    version: 0,
+};
+export const mockConversation = {
+    id: TEST_CONVERSATION_ID,
+    workspaceId: 1,
+    userIds: [1, 2],
+    messageCount: 1,
+    lastObjIndex: 0,
+    snippet: 'Hello there',
+    snippetCreators: [1],
+    lastActive: new Date('2021-01-01T00:00:00Z'),
+    archived: false,
+    created: new Date('2021-01-01T00:00:00Z'),
+    creator: 1,
+    url: `https://comms.todoist.com/a/1/msg/${TEST_CONVERSATION_ID}/`,
+};
+export const mockComment = {
+    id: TEST_COMMENT_ID,
+    content: 'This is a comment',
+    creator: 1,
+    threadId: TEST_THREAD_ID,
+    workspaceId: 1,
+    channelId: TEST_CHANNEL_ID,
+    posted: new Date('2021-01-01T00:00:00Z'),
+    url: `https://comms.todoist.com/a/1/ch/${TEST_CHANNEL_ID}/t/${TEST_THREAD_ID}/c/${TEST_COMMENT_ID}`,
+};
+export const mockWorkspaceUser = {
+    id: 1,
+    fullName: 'Test User',
+    email: 'test@example.com',
+    userType: 'USER',
+    shortName: 'TU',
+    firstName: 'Test',
+    imageId: null,
+    avatarUrls: null,
+    dateFormat: null,
+    removed: false,
+    restricted: null,
+    setupPending: null,
+    theme: null,
+    timeFormat: null,
+    timezone: 'America/New_York',
+    version: 1,
+};

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

@@ -0,0 +1,133 @@
+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';
+export async function fetchWithRetry(url, options, maxRetries = 3, customFetch) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        let clearTimeoutFn;
+        try {
+            let requestSignal = options.signal || undefined;
+            if (options.timeout && options.timeout > 0) {
+                const timeoutResult = createTimeoutSignal(options.timeout, requestSignal);
+                requestSignal = timeoutResult.signal;
+                clearTimeoutFn = timeoutResult.clear;
+            }
+            const response = customFetch
+                ? await customFetch(url, options)
+                : await fetchWithDefaultTransport(url, options, requestSignal);
+            const responseText = await response.text();
+            let responseData;
+            try {
+                responseData = responseText ? JSON.parse(responseText) : undefined;
+            }
+            catch {
+                responseData = responseText;
+            }
+            if (!response.ok) {
+                throw new CommsRequestError(`Request failed with status ${response.status}`, response.status, responseData);
+            }
+            const camelCased = camelCaseKeys(responseData);
+            const transformed = transformTimestamps(camelCased);
+            if (clearTimeoutFn) {
+                clearTimeoutFn();
+            }
+            return {
+                data: transformed,
+                status: response.status,
+                headers: response.headers,
+            };
+        }
+        catch (error) {
+            if (clearTimeoutFn) {
+                clearTimeoutFn();
+            }
+            lastError = error instanceof Error ? error : new Error('Unknown error');
+            if (attempt < maxRetries && isNetworkError(lastError)) {
+                const delay = getRetryDelay(attempt + 1);
+                if (delay > 0) {
+                    await sleep(delay);
+                }
+                continue;
+            }
+            break;
+        }
+    }
+    if (lastError instanceof CommsRequestError) {
+        throw lastError;
+    }
+    throw new CommsRequestError(lastError?.message ?? 'Request failed');
+}
+async function fetchWithDefaultTransport(url, options, signal) {
+    const dispatcher = await getDefaultDispatcher();
+    const response = dispatcher
+        ? await fetch(url, {
+            ...options,
+            signal,
+            // @ts-expect-error - dispatcher is valid for Node.js fetch but not in TS types
+            dispatcher,
+        })
+        : await fetch(url, {
+            ...options,
+            signal,
+        });
+    return convertResponseToCustomFetch(response);
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const timeoutErrorName = 'TimeoutError';
+function createTimeoutError(timeoutMs) {
+    const error = new Error(`Request timeout after ${timeoutMs}ms`);
+    error.name = timeoutErrorName;
+    return error;
+}
+function isNetworkError(error) {
+    return (error.name === 'TypeError' ||
+        error.name === timeoutErrorName ||
+        error.message.toLowerCase().includes('network'));
+}
+function getRetryDelay(retryCount) {
+    return retryCount === 1 ? 0 : 500;
+}
+function createTimeoutSignal(timeoutMs, existingSignal) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+        controller.abort(createTimeoutError(timeoutMs));
+    }, timeoutMs);
+    let abortHandler;
+    function clear() {
+        clearTimeout(timeoutId);
+        if (existingSignal && abortHandler) {
+            existingSignal.removeEventListener('abort', abortHandler);
+        }
+    }
+    if (existingSignal) {
+        if (existingSignal.aborted) {
+            clearTimeout(timeoutId);
+            controller.abort(existingSignal.reason);
+        }
+        else {
+            abortHandler = () => {
+                clearTimeout(timeoutId);
+                controller.abort(existingSignal.reason);
+            };
+            existingSignal.addEventListener('abort', abortHandler, { once: true });
+        }
+    }
+    return { signal: controller.signal, clear };
+}
+function convertResponseToCustomFetch(response) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    return {
+        ok: response.ok,
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        text: () => response.clone().text(),
+        json: () => response.json(),
+    };
+}

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

@@ -0,0 +1,51 @@
+import { snakeCaseKeys } from '../utils/case-conversion.js';
+import { fetchWithRetry } from './fetch-with-retry.js';
+export function paramsSerializer(params) {
+    const qs = new URLSearchParams();
+    Object.keys(params).forEach((key) => {
+        const value = params[key];
+        if (value != null) {
+            if (Array.isArray(value)) {
+                qs.append(key, value.join(','));
+            }
+            else {
+                qs.append(key, String(value));
+            }
+        }
+    });
+    return qs.toString();
+}
+const defaultHeaders = {
+    'Content-Type': 'application/json',
+};
+function getAuthHeader(apiToken) {
+    return `Bearer ${apiToken}`;
+}
+function getRequestConfiguration(baseURL, apiToken, requestId) {
+    const authHeader = apiToken ? { Authorization: getAuthHeader(apiToken) } : undefined;
+    const requestIdHeader = requestId ? { 'X-Request-Id': requestId } : undefined;
+    const headers = { ...defaultHeaders, ...authHeader, ...requestIdHeader };
+    return { baseURL, headers, timeout: 30000 };
+}
+export async function request(args) {
+    const { httpMethod, baseUri, relativePath, apiToken, payload, requestId, customFetch } = args;
+    const config = getRequestConfiguration(baseUri, apiToken, requestId);
+    const url = new URL(relativePath, config.baseURL).toString();
+    const options = {
+        method: httpMethod,
+        headers: config.headers,
+        timeout: config.timeout,
+    };
+    if (httpMethod === 'GET' && payload) {
+        const searchParams = paramsSerializer(snakeCaseKeys(payload));
+        const urlWithParams = searchParams ? `${url}?${searchParams}` : url;
+        return fetchWithRetry(urlWithParams, options, 3, customFetch);
+    }
+    if (payload && httpMethod !== 'GET') {
+        options.body = JSON.stringify(snakeCaseKeys(payload));
+    }
+    return fetchWithRetry(url, options, 3, customFetch);
+}
+export function isSuccess(response) {
+    return response.status >= 200 && response.status < 300;
+}

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

@@ -0,0 +1,104 @@
+let defaultDispatcher;
+let defaultDispatcherPromise;
+export async function getDefaultDispatcher() {
+    if (defaultDispatcher) {
+        return defaultDispatcher;
+    }
+    if (!defaultDispatcherPromise) {
+        defaultDispatcherPromise = createDefaultDispatcher()
+            .then((dispatcher) => {
+            defaultDispatcher = dispatcher;
+            return dispatcher;
+        })
+            .catch((error) => {
+            defaultDispatcher = undefined;
+            defaultDispatcherPromise = undefined;
+            throw error;
+        });
+    }
+    return defaultDispatcherPromise;
+}
+/**
+ * Drains the default dispatcher's connection pool. CLIs and scripts should
+ * `await` this before exit so Node's event loop empties immediately instead
+ * of waiting ~4s on keep-alive. No-op in the browser branch.
+ */
+export async function closeDefaultDispatcher() {
+    // Clear the singleton *before* awaiting init, so any concurrent
+    // `getDefaultDispatcher()` 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;
+    if (!initPromise)
+        return;
+    try {
+        const dispatcher = await initPromise;
+        if (dispatcher) {
+            await dispatcher.close();
+        }
+    }
+    catch {
+        // init failed; nothing to close
+    }
+}
+export function resetDefaultDispatcherForTests() {
+    defaultDispatcher = undefined;
+    defaultDispatcherPromise = undefined;
+}
+function isNodeEnvironment() {
+    return typeof process !== 'undefined' && typeof process.versions?.node === 'string';
+}
+async function createDefaultDispatcher() {
+    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');
+    // `allowH2: true` opts into HTTP/2 via ALPN; undici falls back to h1.1
+    // when the server doesn't negotiate h2. Without this flag undici
+    // defaults to h1.1 even when the server supports h2.
+    //
+    // `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.
+    //
+    // Both emit ExperimentalWarning on first use; suppressed during init.
+    return suppressExperimentalWarningsSync(() => {
+        const decompress = interceptors.decompress();
+        return new EnvHttpProxyAgent({ allowH2: true }).compose(decompress);
+    });
+}
+// `suppressExperimentalWarningsSync` is exported for direct unit testing —
+// the integration path through `getDefaultDispatcher()` can't reliably
+// exercise it because both the dispatcher singleton and undici's internal
+// `warningEmitted` flag are once-per-process.
+//
+// `fn` must be synchronous so the override covers a single critical section
+// (microseconds) — no unrelated `ExperimentalWarning` from elsewhere can
+// interleave and be lost. We suppress every `ExperimentalWarning` rather than
+// pattern-matching the message text: the message wording is an undici
+// implementation detail (not a stable API), and the suppression window is
+// narrow enough that a coarse type filter is safe.
+export function suppressExperimentalWarningsSync(fn) {
+    const originalEmit = process.emitWarning;
+    process.emitWarning = ((warning, typeOrOptions, ...rest) => {
+        const type = typeof typeOrOptions === 'string'
+            ? typeOrOptions
+            : typeof typeOrOptions === 'object' && typeOrOptions !== null
+                ? typeOrOptions.type
+                : undefined;
+        if (type === 'ExperimentalWarning')
+            return;
+        originalEmit.call(process, warning, typeOrOptions, ...rest);
+    });
+    try {
+        return fn();
+    }
+    finally {
+        process.emitWarning = originalEmit;
+    }
+}