@doist/comms-sdk 0.1.0-alpha.1

package/dist/cjs/utils/timestamp-conversion.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timestampToDate = timestampToDate;
+exports.transformTimestamps = transformTimestamps;
+/**
+ * Converts a Unix timestamp (in seconds) to a Date object.
+ * @param timestamp - Unix timestamp in seconds
+ * @returns Date object
+ */
+function timestampToDate(timestamp) {
+    return new Date(timestamp * 1000);
+}
+/**
+ * Recursively transforms all timestamp fields (ending in 'Ts') in an object to Date objects.
+ * Also renames the fields by removing the 'Ts' suffix.
+ * @param obj - The object to transform
+ * @returns The transformed object with Date fields
+ */
+function transformTimestamps(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => transformTimestamps(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // Check if the key ends with 'Ts' and the value is a number
+            if (key.endsWith('Ts') && typeof value === 'number') {
+                // Remove 'Ts' suffix and convert to Date
+                const newKey = key.slice(0, -2);
+                // If the base key already exists in the original object, use *Date suffix
+                // to avoid overwriting it (e.g. pinned + pinnedTs → pinned + pinnedDate)
+                const targetKey = newKey in obj ? `${newKey}Date` : newKey;
+                result[targetKey] = timestampToDate(value);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                // Recursively transform nested objects
+                result[key] = transformTimestamps(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    return obj;
+}

package/dist/cjs/utils/url-helpers.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Helper functions for creating Comms permalinks (`https://comms.todoist.com/a/...`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommsURL = getCommsURL;
+exports.getFullCommsURL = getFullCommsURL;
+exports.getThreadURL = getThreadURL;
+exports.getChannelURL = getChannelURL;
+exports.getConversationURL = getConversationURL;
+exports.getMessageURL = getMessageURL;
+exports.getCommentURL = getCommentURL;
+exports.getThreadsRootURL = getThreadsRootURL;
+exports.getInboxURL = getInboxURL;
+exports.getMessagesRootURL = getMessagesRootURL;
+exports.getUserProfileURL = getUserProfileURL;
+exports.getSavedThreadsRootURL = getSavedThreadsRootURL;
+exports.getSavedThreadURL = getSavedThreadURL;
+exports.getSearchRootURL = getSearchRootURL;
+exports.getSearchQueryURL = getSearchQueryURL;
+exports.getSettingsURL = getSettingsURL;
+exports.getTeamMembersRootURL = getTeamMembersRootURL;
+const COMMS_BASE_URL = 'https://comms.todoist.com';
+/**
+ * Builds a relative Comms URL based on the provided parameters
+ * @param params - URL parameters including workspace, channel, conversation, thread, etc.
+ * @returns A relative URL path
+ * @example
+ * getCommsURL({ workspaceId: 1, channelId: '7Yp...', threadId: '7Yq...' })
+ * // returns '/a/1/ch/7Yp.../t/7Yq.../'
+ */
+function getCommsURL(params) {
+    const { workspaceId, channelId, conversationId, threadId, commentId, messageId, userId } = params;
+    let url = `/a/${workspaceId}/`;
+    if (channelId) {
+        url += `ch/${channelId}/`;
+        if (threadId) {
+            url += `t/${threadId}/`;
+            if (commentId) {
+                url += `c/${commentId}`;
+            }
+        }
+    }
+    else if (threadId) {
+        url += `inbox/t/${threadId}/`;
+        if (commentId) {
+            url += `c/${commentId}`;
+        }
+    }
+    else if (conversationId) {
+        url += `msg/${conversationId}/`;
+        if (messageId) {
+            url += `m/${messageId}`;
+        }
+    }
+    else if (userId) {
+        url += `people/u/${userId}`;
+    }
+    return url;
+}
+/**
+ * Builds a full Comms URL (with protocol and hostname) based on the provided parameters
+ * @param params - URL parameters including workspace, channel, conversation, thread, etc.
+ * @param baseUrl - Optional base URL (defaults to 'https://comms.todoist.com')
+ */
+function getFullCommsURL(params, baseUrl = COMMS_BASE_URL) {
+    return `${baseUrl}${getCommsURL(params)}`;
+}
+/** Returns the URL for a thread in a channel. */
+function getThreadURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a channel. */
+function getChannelURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a conversation. */
+function getConversationURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a specific message in a conversation. */
+function getMessageURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a comment in a thread. */
+function getCommentURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for the threads root (channels view). */
+function getThreadsRootURL(workspaceId) {
+    return `/a/${workspaceId}/ch`;
+}
+/** Returns the URL for the inbox. */
+function getInboxURL(workspaceId, tab) {
+    const tabParam = tab ? `/${tab}` : '';
+    return `/a/${workspaceId}/inbox${tabParam}`;
+}
+/** Returns the URL for the messages/conversations root. */
+function getMessagesRootURL(workspaceId) {
+    return `/a/${workspaceId}/msg`;
+}
+/** Returns the URL for a user profile. */
+function getUserProfileURL(params) {
+    return `/a/${params.workspaceId}/people/u/${params.userId}`;
+}
+/** Returns the URL for the saved threads view. */
+function getSavedThreadsRootURL(workspaceId) {
+    return `/a/${workspaceId}/saved`;
+}
+/** Returns the URL for a saved thread. */
+function getSavedThreadURL(params) {
+    return `/a/${params.workspaceId}/saved/t/${params.threadId}`;
+}
+/** Returns the URL for the search root. */
+function getSearchRootURL(workspaceId) {
+    return `/a/${workspaceId}/search`;
+}
+/** Returns the URL for a search with a query. */
+function getSearchQueryURL(params) {
+    return `/a/${params.workspaceId}/search?q=${decodeURIComponent(params.query)}`;
+}
+/** Returns the URL for settings. */
+function getSettingsURL(params) {
+    return params.initialLocation
+        ? `/a/${params.workspaceId}/settings/${params.initialLocation}`
+        : `/a/${params.workspaceId}/settings`;
+}
+/** Returns the URL for the team members root. */
+function getTeamMembersRootURL(workspaceId) {
+    return `/a/${workspaceId}/people/u`;
+}

package/dist/cjs/utils/uuidv7.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UuidV7Error = void 0;
+exports.encodeUuidToBase58 = encodeUuidToBase58;
+exports.decodeBase58ToUuidBytes = decodeBase58ToUuidBytes;
+exports.generateId = generateId;
+exports.resolveCreateId = resolveCreateId;
+exports.isValidUuidV7Base58 = isValidUuidV7Base58;
+exports.base58FromUuidString = base58FromUuidString;
+exports.uuidStringFromBase58 = uuidStringFromBase58;
+const uuid_1 = require("uuid");
+/**
+ * ID utilities for entities that use opaque string identifiers (channels,
+ * threads, comments, conversations, messages, groups).
+ *
+ * Use {@link generateId} to mint a new ID locally and pass it to a creation
+ * endpoint. {@link encodeUuidToBase58} / {@link decodeBase58ToUuidBytes}
+ * expose the underlying encoding for callers that need to round-trip raw
+ * UUID bytes themselves.
+ */
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const BASE58_MAP = (() => {
+    const map = {};
+    for (let i = 0; i < BASE58_ALPHABET.length; i++) {
+        map[BASE58_ALPHABET[i]] = i;
+    }
+    return map;
+})();
+const UUID_BYTES_LEN = 16;
+const UUID_BASE58_MAX_LEN = 22;
+const HEX_RE = /^[0-9a-f]+$/;
+class UuidV7Error extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UuidV7Error';
+    }
+}
+exports.UuidV7Error = UuidV7Error;
+/** Encode a 16-byte UUID as a base58 string. */
+function encodeUuidToBase58(bytes) {
+    if (bytes.length !== UUID_BYTES_LEN) {
+        throw new UuidV7Error(`id must be ${UUID_BYTES_LEN} bytes`);
+    }
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0) {
+        zeros++;
+    }
+    let n = 0n;
+    for (const b of bytes) {
+        n = (n << 8n) | BigInt(b);
+    }
+    let out = '';
+    while (n > 0n) {
+        const rem = Number(n % 58n);
+        out = BASE58_ALPHABET[rem] + out;
+        n /= 58n;
+    }
+    return '1'.repeat(zeros) + out;
+}
+/**
+ * Decode a base58 string back into 16 UUID bytes. Throws {@link UuidV7Error}
+ * if the input is malformed or doesn't decode to exactly 16 bytes.
+ */
+function decodeBase58ToUuidBytes(value) {
+    if (typeof value !== 'string') {
+        throw new UuidV7Error('id must be a base58 string');
+    }
+    if (value.length === 0) {
+        throw new UuidV7Error('id is empty');
+    }
+    if (value.length > UUID_BASE58_MAX_LEN) {
+        throw new UuidV7Error('id is too long');
+    }
+    let zeros = 0;
+    while (zeros < value.length && value[zeros] === '1') {
+        zeros++;
+    }
+    let n = 0n;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        const v = BASE58_MAP[ch];
+        if (v === undefined) {
+            throw new UuidV7Error(`invalid base58 character: '${ch}'`);
+        }
+        n = n * 58n + BigInt(v);
+    }
+    const raw = [];
+    while (n > 0n) {
+        raw.unshift(Number(n & 0xffn));
+        n >>= 8n;
+    }
+    const padded = new Uint8Array(zeros + raw.length);
+    padded.set(raw, zeros);
+    if (padded.length !== UUID_BYTES_LEN) {
+        throw new UuidV7Error(`id must decode to ${UUID_BYTES_LEN} bytes`);
+    }
+    return padded;
+}
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * Mint a fresh ID. Callers should generate one of these locally when
+ * creating a new channel / thread / comment / conversation / message /
+ * group — the backend requires the client to supply the ID on create.
+ */
+function generateId() {
+    const hex = (0, uuid_1.v7)().replace(/-/g, '');
+    return encodeUuidToBase58(hexToBytes(hex));
+}
+/**
+ * Resolve the `id` for a create-style API call: validate the caller-supplied
+ * value (throwing {@link UuidV7Error} before the request leaves the SDK) or
+ * mint a fresh one via {@link generateId}.
+ */
+function resolveCreateId(id) {
+    if (id === undefined)
+        return generateId();
+    if (!isValidUuidV7Base58(id)) {
+        throw new UuidV7Error(`invalid id ${JSON.stringify(id)} — use generateId() or omit \`id\` and let the SDK mint one.`);
+    }
+    return id;
+}
+/**
+ * Validate that a value matches the expected ID format (the decoded bytes
+ * have the v7 version nibble + RFC 4122/9562 variant bits). Does NOT
+ * validate the embedded timestamp — the backend may still reject a value
+ * that is too far in the future or past.
+ */
+function isValidUuidV7Base58(value) {
+    if (typeof value !== 'string')
+        return false;
+    let bytes;
+    try {
+        bytes = decodeBase58ToUuidBytes(value);
+    }
+    catch {
+        return false;
+    }
+    const versionNibble = bytes[6] & 0xf0;
+    const variantBits = bytes[8] & 0xc0;
+    return versionNibble === 0x70 && variantBits === 0x80;
+}
+/**
+ * Encode a canonical UUID string (hyphenated or not, any case) as a
+ * wire-format ID. Useful when interoperating with systems that hand you
+ * UUIDs in canonical form.
+ */
+function base58FromUuidString(uuid) {
+    const stripped = uuid.replace(/-/g, '').toLowerCase();
+    if (stripped.length !== 32 || !HEX_RE.test(stripped)) {
+        throw new UuidV7Error('not a valid UUID string');
+    }
+    return encodeUuidToBase58(hexToBytes(stripped));
+}
+/**
+ * Inverse of {@link base58FromUuidString}: takes a wire-format ID and
+ * returns the canonical hyphenated UUID string.
+ */
+function uuidStringFromBase58(value) {
+    const bytes = decodeBase58ToUuidBytes(value);
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join('-');
+}

package/dist/esm/authentication.js

@@ -0,0 +1,203 @@
+import { v4 as uuid } from 'uuid';
+import { isSuccess, request } from './transport/http-client.js';
+import { CommsRequestError } from './types/errors.js';
+/**
+ * OAuth scopes for the Comms API.
+ *
+ * @remarks
+ * Request only the scopes your application needs:
+ *
+ * **User Scopes:**
+ * - `user:read` - Access user's personal settings
+ * - `user:write` - Access and update user's personal settings
+ *
+ * **Workspace Scopes:**
+ * - `workspaces:read` - Access teams the user is part of
+ * - `workspaces:write` - Access and update teams the user is part of
+ *
+ * **Channel Scopes:**
+ * - `channels:read` - Access channels
+ * - `channels:write` - Access and update channels
+ * - `channels:remove` - Access, update, and delete channels
+ *
+ * **Thread Scopes:**
+ * - `threads:read` - Access threads
+ * - `threads:write` - Access and update threads
+ * - `threads:remove` - Access, update, and delete threads
+ *
+ * **Comment Scopes:**
+ * - `comments:read` - Access comments
+ * - `comments:write` - Access and update comments
+ * - `comments:remove` - Access, update, and delete comments
+ *
+ * **Group Scopes:**
+ * - `groups:read` - Access groups
+ * - `groups:write` - Access and update groups
+ * - `groups:remove` - Access, update, and delete groups
+ *
+ * **Message Scopes:**
+ * - `messages:read` - Access messages
+ * - `messages:write` - Access and update messages
+ * - `messages:remove` - Access, update, and delete messages
+ *
+ * **Reaction Scopes:**
+ * - `reactions:read` - Access reactions
+ * - `reactions:write` - Access and update reactions
+ * - `reactions:remove` - Access, update, and delete reactions
+ *
+ * **Search Scopes:**
+ * - `search:read` - Search
+ *
+ * **Attachment Scopes:**
+ * - `attachments:read` - Access attachments
+ * - `attachments:write` - Access and update attachments
+ *
+ * **Notification Scopes:**
+ * - `notifications:read` - Read user's notifications settings
+ * - `notifications:write` - Read and update user's notifications settings
+ */
+export const COMMS_SCOPES = [
+    'user:read',
+    'user:write',
+    'workspaces:read',
+    'workspaces:write',
+    'channels:read',
+    'channels:write',
+    'channels:remove',
+    'threads:read',
+    'threads:write',
+    'threads:remove',
+    'comments:read',
+    'comments:write',
+    'comments:remove',
+    'groups:read',
+    'groups:write',
+    'groups:remove',
+    'messages:read',
+    'messages:write',
+    'messages:remove',
+    'reactions:read',
+    'reactions:write',
+    'reactions:remove',
+    'search:read',
+    'attachments:read',
+    'attachments:write',
+    'notifications:read',
+    'notifications:write',
+];
+/** Supported token endpoint authentication methods for dynamic client registration. */
+export const TOKEN_ENDPOINT_AUTH_METHODS = [
+    'client_secret_post',
+    'client_secret_basic',
+    'none',
+];
+export function getAuthStateParameter() {
+    return uuid();
+}
+/**
+ * Generates the authorization URL for the OAuth2 flow.
+ *
+ * The `clientId` can be either a traditional client ID string (e.g. from
+ * {@link registerClient}) or an HTTPS URL pointing to a client metadata document,
+ * as defined in {@link https://drafts.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/ RFC draft-ietf-oauth-client-id-metadata-document}.
+ */
+export function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUrl) {
+    if (!scopes?.length) {
+        throw new Error('At least one scope value is required.');
+    }
+    const authBaseUrl = baseUrl ? `${baseUrl}/oauth` : 'https://comms.todoist.com/oauth';
+    const scope = scopes.join(' ');
+    const params = new URLSearchParams({
+        client_id: clientId,
+        response_type: 'code',
+        scope,
+        state,
+    });
+    if (redirectUri) {
+        params.append('redirect_uri', redirectUri);
+    }
+    return `${authBaseUrl}/authorize?${params.toString()}`;
+}
+export async function getAuthToken(args, options) {
+    const tokenUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/token`
+        : 'https://comms.todoist.com/oauth/token';
+    const payload = {
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        code: args.code,
+        grantType: 'authorization_code',
+        ...(args.redirectUri && { redirectUri: args.redirectUri }),
+    };
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: tokenUrl,
+        relativePath: '',
+        payload,
+        customFetch: options?.customFetch,
+    });
+    if (!isSuccess(response) || !response.data?.accessToken) {
+        throw new CommsRequestError('Authentication token exchange failed.', response.status, response.data);
+    }
+    return response.data;
+}
+export async function revokeAuthToken(args, options) {
+    const revokeUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/revoke`
+        : 'https://comms.todoist.com/oauth/revoke';
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: revokeUrl,
+        relativePath: '',
+        payload: {
+            clientId: args.clientId,
+            clientSecret: args.clientSecret,
+            token: args.accessToken,
+        },
+        customFetch: options?.customFetch,
+    });
+    return isSuccess(response);
+}
+/**
+ * Registers a new OAuth client via Dynamic Client Registration (RFC 7591).
+ *
+ * @example
+ * ```typescript
+ * const client = await registerClient({
+ *   redirectUris: ['https://example.com/callback'],
+ *   clientName: 'My App',
+ *   scope: ['user:read', 'channels:read'],
+ * })
+ * // Use client.clientId and client.clientSecret for OAuth flows
+ * ```
+ *
+ * @returns The registered client details
+ * @throws {@link CommsRequestError} If the registration fails
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591 RFC 7591}
+ */
+export async function registerClient(args, options) {
+    const registerUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/register`
+        : 'https://comms.todoist.com/oauth/register';
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: registerUrl,
+        relativePath: '',
+        payload: { ...args, scope: args.scope?.join(' ') },
+        customFetch: options?.customFetch,
+    });
+    if (!isSuccess(response) || !response.data?.clientId) {
+        throw new CommsRequestError('Dynamic client registration failed.', response.status, response.data);
+    }
+    const { clientIdIssuedAt, clientSecretExpiresAt, scope, ...rest } = response.data;
+    return {
+        ...rest,
+        scope: scope ? scope.split(' ') : undefined,
+        clientIdIssuedAt: clientIdIssuedAt !== undefined ? new Date(clientIdIssuedAt * 1000) : undefined,
+        clientSecretExpiresAt: clientSecretExpiresAt === undefined
+            ? undefined
+            : clientSecretExpiresAt === 0
+                ? null
+                : new Date(clientSecretExpiresAt * 1000),
+    };
+}

package/dist/esm/clients/add-comment-helper.js

@@ -0,0 +1,50 @@
+import { ENDPOINT_COMMENTS } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
+import { CommentSchema } from '../types/entities.js';
+import { NOTIFY_AUDIENCE_GROUP_IDS, NOTIFY_AUDIENCES } from '../types/enums.js';
+import { resolveCreateId } from '../utils/uuidv7.js';
+const SENTINEL_GROUP_IDS = new Set(Object.values(NOTIFY_AUDIENCE_GROUP_IDS));
+function isNotifyAudience(value) {
+    return typeof value === 'string' && NOTIFY_AUDIENCES.includes(value);
+}
+function collectMarkerOffenses(field, values) {
+    if (!values)
+        return null;
+    const offending = values.filter((id) => SENTINEL_GROUP_IDS.has(id));
+    return offending.length > 0 ? { field, offending } : null;
+}
+function applyNotifyAudience(params) {
+    const offenses = [
+        collectMarkerOffenses('groups', params.groups ?? undefined),
+        collectMarkerOffenses('directGroupMentions', params.directGroupMentions ?? undefined),
+    ].filter((o) => o !== null);
+    if (offenses.length > 0) {
+        const details = offenses
+            .map(({ field, offending }) => `\`${field}\` contains ${offending.join(', ')}`)
+            .join('; ');
+        throw new Error(`Reserved broadcast marker IDs found: ${details}. Pass these via \`notifyAudience\` on createComment / closeThread / reopenThread (e.g. \`notifyAudience: 'channel'\` for EVERYONE) instead of populating \`groups\` / \`directGroupMentions\` directly.`);
+    }
+    if (params.notifyAudience == null)
+        return params;
+    if (!isNotifyAudience(params.notifyAudience)) {
+        throw new Error(`Invalid \`notifyAudience\` value "${String(params.notifyAudience)}". Expected one of: ${NOTIFY_AUDIENCES.join(', ')}.`);
+    }
+    const sentinel = NOTIFY_AUDIENCE_GROUP_IDS[params.notifyAudience];
+    const { notifyAudience: _stripped, groups, ...rest } = params;
+    return { ...rest, groups: [...(groups ?? []), sentinel] };
+}
+export function addCommentRequest(context, params, options) {
+    const normalized = applyNotifyAudience(params);
+    const withId = { ...normalized, id: resolveCreateId(normalized.id) };
+    const payload = options?.threadAction
+        ? { ...withId, threadAction: options.threadAction }
+        : withId;
+    return request({
+        httpMethod: 'POST',
+        baseUri: context.baseUri,
+        relativePath: `${ENDPOINT_COMMENTS}/add`,
+        apiToken: context.apiToken,
+        payload,
+        customFetch: context.customFetch,
+    }).then((response) => CommentSchema.parse(response.data));
+}

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

@@ -0,0 +1,23 @@
+import { getCommsBaseUri } from '../consts/endpoints.js';
+/**
+ * Base class for every Comms API client. Centralizes URL handling and
+ * config so individual clients stay focused on their endpoints.
+ */
+export class BaseClient {
+    constructor(config) {
+        this.apiToken = config.apiToken;
+        this.baseUrl = config.baseUrl;
+        this.customFetch = config.customFetch;
+    }
+    /**
+     * Returns the base URI for an API request, with a guaranteed trailing
+     * slash so relative paths resolve cleanly through `URL`.
+     */
+    getBaseUri() {
+        if (this.baseUrl) {
+            const normalizedBaseUrl = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`;
+            return `${normalizedBaseUrl}api/v1/`;
+        }
+        return getCommsBaseUri();
+    }
+}