@doist/comms-sdk 0.1.0-alpha.1

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createObsidianFetchAdapter = createObsidianFetchAdapter;
+/**
+ * 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'
+ *
+ * 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
+ */
+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/cjs/testUtils/test-defaults.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockWorkspaceUser = exports.mockComment = exports.mockConversation = exports.mockGroup = exports.mockThread = exports.mockChannel = exports.mockWorkspace = exports.mockUser = exports.TEST_GROUP_ID = exports.TEST_MESSAGE_ID = exports.TEST_CONVERSATION_ID = exports.TEST_COMMENT_ID = exports.TEST_THREAD_ID = exports.TEST_CHANNEL_ID = exports.TEST_API_TOKEN = void 0;
+exports.TEST_API_TOKEN = 'test-api-token';
+// Canonical test IDs — shaped so they pass SDK-side validation.
+exports.TEST_CHANNEL_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3y';
+exports.TEST_THREAD_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3z';
+exports.TEST_COMMENT_ID = '7YpL3oZ4kZ9vP7Q1tR2sX41';
+exports.TEST_CONVERSATION_ID = '7YpL3oZ4kZ9vP7Q1tR2sX42';
+exports.TEST_MESSAGE_ID = '7YpL3oZ4kZ9vP7Q1tR2sX43';
+exports.TEST_GROUP_ID = '7YpL3oZ4kZ9vP7Q1tR2sX44';
+exports.mockUser = {
+    id: 1,
+    email: 'test@example.com',
+    fullName: 'Test User',
+    shortName: 'TU',
+    timezone: 'America/New_York',
+    removed: false,
+    lang: 'en',
+};
+exports.mockWorkspace = {
+    id: 1,
+    name: 'Test Workspace',
+    creator: 1,
+    created: new Date('2021-01-01T00:00:00Z'),
+};
+exports.mockChannel = {
+    id: exports.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/${exports.TEST_CHANNEL_ID}/`,
+};
+exports.mockThread = {
+    id: exports.TEST_THREAD_ID,
+    title: 'Test Thread',
+    content: 'This is a test thread',
+    creator: 1,
+    channelId: exports.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/${exports.TEST_CHANNEL_ID}/t/${exports.TEST_THREAD_ID}/`,
+};
+exports.mockGroup = {
+    id: exports.TEST_GROUP_ID,
+    name: 'Test Group',
+    workspaceId: 1,
+    userIds: [1, 2, 3],
+    version: 0,
+};
+exports.mockConversation = {
+    id: exports.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/${exports.TEST_CONVERSATION_ID}/`,
+};
+exports.mockComment = {
+    id: exports.TEST_COMMENT_ID,
+    content: 'This is a comment',
+    creator: 1,
+    threadId: exports.TEST_THREAD_ID,
+    workspaceId: 1,
+    channelId: exports.TEST_CHANNEL_ID,
+    posted: new Date('2021-01-01T00:00:00Z'),
+    url: `https://comms.todoist.com/a/1/ch/${exports.TEST_CHANNEL_ID}/t/${exports.TEST_THREAD_ID}/c/${exports.TEST_COMMENT_ID}`,
+};
+exports.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/cjs/transport/fetch-with-retry.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithRetry = fetchWithRetry;
+const errors_1 = require("../types/errors");
+const case_conversion_1 = require("../utils/case-conversion");
+const timestamp_conversion_1 = require("../utils/timestamp-conversion");
+const http_dispatcher_1 = require("./http-dispatcher");
+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 errors_1.CommsRequestError(`Request failed with status ${response.status}`, response.status, responseData);
+            }
+            const camelCased = (0, case_conversion_1.camelCaseKeys)(responseData);
+            const transformed = (0, timestamp_conversion_1.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 errors_1.CommsRequestError) {
+        throw lastError;
+    }
+    throw new errors_1.CommsRequestError(lastError?.message ?? 'Request failed');
+}
+async function fetchWithDefaultTransport(url, options, signal) {
+    const dispatcher = await (0, http_dispatcher_1.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/cjs/transport/http-client.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paramsSerializer = paramsSerializer;
+exports.request = request;
+exports.isSuccess = isSuccess;
+const case_conversion_1 = require("../utils/case-conversion");
+const fetch_with_retry_1 = require("./fetch-with-retry");
+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 };
+}
+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((0, case_conversion_1.snakeCaseKeys)(payload));
+        const urlWithParams = searchParams ? `${url}?${searchParams}` : url;
+        return (0, fetch_with_retry_1.fetchWithRetry)(urlWithParams, options, 3, customFetch);
+    }
+    if (payload && httpMethod !== 'GET') {
+        options.body = JSON.stringify((0, case_conversion_1.snakeCaseKeys)(payload));
+    }
+    return (0, fetch_with_retry_1.fetchWithRetry)(url, options, 3, customFetch);
+}
+function isSuccess(response) {
+    return response.status >= 200 && response.status < 300;
+}

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

@@ -0,0 +1,143 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultDispatcher = getDefaultDispatcher;
+exports.closeDefaultDispatcher = closeDefaultDispatcher;
+exports.resetDefaultDispatcherForTests = resetDefaultDispatcherForTests;
+exports.suppressExperimentalWarningsSync = suppressExperimentalWarningsSync;
+let defaultDispatcher;
+let defaultDispatcherPromise;
+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.
+ */
+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
+    }
+}
+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 Promise.resolve().then(() => __importStar(require('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.
+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;
+    }
+}