@doist/comms-sdk 0.1.0-alpha.1

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

@@ -0,0 +1,112 @@
+/**
+ * Helper functions for creating Comms permalinks (`https://comms.todoist.com/a/...`).
+ */
+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.../'
+ */
+export 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')
+ */
+export function getFullCommsURL(params, baseUrl = COMMS_BASE_URL) {
+    return `${baseUrl}${getCommsURL(params)}`;
+}
+/** Returns the URL for a thread in a channel. */
+export function getThreadURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a channel. */
+export function getChannelURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a conversation. */
+export function getConversationURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a specific message in a conversation. */
+export function getMessageURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for a comment in a thread. */
+export function getCommentURL(params) {
+    return getCommsURL(params);
+}
+/** Returns the URL for the threads root (channels view). */
+export function getThreadsRootURL(workspaceId) {
+    return `/a/${workspaceId}/ch`;
+}
+/** Returns the URL for the inbox. */
+export function getInboxURL(workspaceId, tab) {
+    const tabParam = tab ? `/${tab}` : '';
+    return `/a/${workspaceId}/inbox${tabParam}`;
+}
+/** Returns the URL for the messages/conversations root. */
+export function getMessagesRootURL(workspaceId) {
+    return `/a/${workspaceId}/msg`;
+}
+/** Returns the URL for a user profile. */
+export function getUserProfileURL(params) {
+    return `/a/${params.workspaceId}/people/u/${params.userId}`;
+}
+/** Returns the URL for the saved threads view. */
+export function getSavedThreadsRootURL(workspaceId) {
+    return `/a/${workspaceId}/saved`;
+}
+/** Returns the URL for a saved thread. */
+export function getSavedThreadURL(params) {
+    return `/a/${params.workspaceId}/saved/t/${params.threadId}`;
+}
+/** Returns the URL for the search root. */
+export function getSearchRootURL(workspaceId) {
+    return `/a/${workspaceId}/search`;
+}
+/** Returns the URL for a search with a query. */
+export function getSearchQueryURL(params) {
+    return `/a/${params.workspaceId}/search?q=${decodeURIComponent(params.query)}`;
+}
+/** Returns the URL for settings. */
+export function getSettingsURL(params) {
+    return params.initialLocation
+        ? `/a/${params.workspaceId}/settings/${params.initialLocation}`
+        : `/a/${params.workspaceId}/settings`;
+}
+/** Returns the URL for the team members root. */
+export function getTeamMembersRootURL(workspaceId) {
+    return `/a/${workspaceId}/people/u`;
+}

package/dist/esm/utils/uuidv7.js

@@ -0,0 +1,163 @@
+import { v7 as uuidv7 } from '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]+$/;
+export class UuidV7Error extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UuidV7Error';
+    }
+}
+/** Encode a 16-byte UUID as a base58 string. */
+export 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.
+ */
+export 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.
+ */
+export function generateId() {
+    const hex = uuidv7().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}.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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/types/authentication.d.ts

@@ -0,0 +1,160 @@
+import type { CustomFetch } from './types/http.js';
+export type AuthOptions = {
+    /** Optional custom base URL for OAuth endpoints */
+    baseUrl?: string;
+    /** Optional custom fetch implementation for cross-platform compatibility */
+    customFetch?: CustomFetch;
+};
+/**
+ * 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 declare const COMMS_SCOPES: readonly ["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"];
+/**
+ * Scopes determine what access a token has to the Comms API.
+ */
+export type CommsScope = (typeof COMMS_SCOPES)[number];
+export type AuthTokenRequestArgs = {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri?: string;
+};
+export type AuthTokenResponse = {
+    accessToken: string;
+    tokenType: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    scope?: string;
+};
+export type RevokeAuthTokenRequestArgs = {
+    clientId: string;
+    clientSecret: string;
+    accessToken: string;
+};
+/** Supported token endpoint authentication methods for dynamic client registration. */
+export declare const TOKEN_ENDPOINT_AUTH_METHODS: readonly ["client_secret_post", "client_secret_basic", "none"];
+/**
+ * Authentication method used at the token endpoint.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591#section-2 RFC 7591 Section 2}
+ */
+export type TokenEndpointAuthMethod = (typeof TOKEN_ENDPOINT_AUTH_METHODS)[number];
+/**
+ * Parameters for registering a new OAuth client via Dynamic Client Registration.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591 RFC 7591}
+ */
+export type ClientRegistrationRequest = {
+    redirectUris: string[];
+    clientName?: string;
+    clientUri?: string;
+    logoUri?: string;
+    scope?: readonly CommsScope[];
+    grantTypes?: string[];
+    responseTypes?: string[];
+    tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+};
+type RawClientRegistrationResponse = {
+    clientId: string;
+    clientSecret?: string;
+    clientName: string;
+    redirectUris: string[];
+    scope?: string;
+    grantTypes: string[];
+    responseTypes: string[];
+    tokenEndpointAuthMethod: string;
+    clientIdIssuedAt?: number;
+    clientSecretExpiresAt?: number;
+    clientUri?: string;
+    logoUri?: string;
+};
+/**
+ * Response from a successful dynamic client registration.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.1 RFC 7591 Section 3.2.1}
+ */
+export type ClientRegistrationResponse = Omit<RawClientRegistrationResponse, 'clientIdIssuedAt' | 'clientSecretExpiresAt' | 'scope'> & {
+    scope?: CommsScope[];
+    clientIdIssuedAt?: Date;
+    /** `null` indicates the client secret never expires. Absent when no secret is issued. */
+    clientSecretExpiresAt?: Date | null;
+};
+export declare function getAuthStateParameter(): string;
+/**
+ * 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 declare function getAuthorizationUrl(clientId: string, scopes: CommsScope[], state: string, redirectUri?: string, baseUrl?: string): string;
+export declare function getAuthToken(args: AuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
+export declare function revokeAuthToken(args: RevokeAuthTokenRequestArgs, options?: AuthOptions): Promise<boolean>;
+/**
+ * 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 declare function registerClient(args: ClientRegistrationRequest, options?: AuthOptions): Promise<ClientRegistrationResponse>;
+export {};

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

@@ -0,0 +1,12 @@
+import { type Comment } from '../types/entities.js';
+import type { CustomFetch } from '../types/http.js';
+import type { CreateCommentArgs, ThreadAction } from '../types/requests.js';
+type ClientContext = {
+    baseUri: string;
+    apiToken: string;
+    customFetch?: CustomFetch;
+};
+export declare function addCommentRequest(context: ClientContext, params: CreateCommentArgs, options?: {
+    threadAction?: ThreadAction;
+}): Promise<Comment>;
+export {};

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

@@ -0,0 +1,24 @@
+import type { CustomFetch } from '../types/http.js';
+export type ClientConfig = {
+    /** API token for authentication */
+    apiToken: string;
+    /** Optional custom base URL. If not provided, uses the default Comms API URL */
+    baseUrl?: string;
+    /** Optional custom fetch implementation for cross-platform compatibility */
+    customFetch?: CustomFetch;
+};
+/**
+ * Base class for every Comms API client. Centralizes URL handling and
+ * config so individual clients stay focused on their endpoints.
+ */
+export declare class BaseClient {
+    protected readonly apiToken: string;
+    protected readonly baseUrl?: string;
+    protected readonly customFetch?: CustomFetch;
+    constructor(config: ClientConfig);
+    /**
+     * Returns the base URI for an API request, with a guaranteed trailing
+     * slash so relative paths resolve cleanly through `URL`.
+     */
+    protected getBaseUri(): string;
+}

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

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { type Channel, type StatusOk } from '../types/entities.js';
+import type { AddChannelUserArgs, AddChannelUsersArgs, CreateChannelArgs, GetChannelsArgs, RemoveChannelUserArgs, RemoveChannelUsersArgs, UpdateChannelArgs } from '../types/requests.js';
+import { BaseClient } from './base-client.js';
+export declare const ChannelListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    creator: z.ZodNumber;
+    userIds: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
+    color: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    public: z.ZodBoolean;
+    workspaceId: z.ZodNumber;
+    archived: z.ZodBoolean;
+    created: z.ZodDate;
+    useDefaultRecipients: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    defaultGroups: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    defaultRecipients: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
+    isFavorited: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    version: z.ZodNumber;
+    filters: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strip>, z.ZodTransform<{
+    url: string;
+    id: string;
+    name: string;
+    creator: number;
+    public: boolean;
+    workspaceId: number;
+    archived: boolean;
+    created: Date;
+    version: number;
+    description?: string | null | undefined;
+    userIds?: number[] | null | undefined;
+    color?: number | null | undefined;
+    useDefaultRecipients?: boolean | null | undefined;
+    defaultGroups?: string[] | null | undefined;
+    defaultRecipients?: number[] | null | undefined;
+    isFavorited?: boolean | null | undefined;
+    icon?: number | null | undefined;
+    filters?: Record<string, string> | null | undefined;
+}, {
+    id: string;
+    name: string;
+    creator: number;
+    public: boolean;
+    workspaceId: number;
+    archived: boolean;
+    created: Date;
+    version: number;
+    description?: string | null | undefined;
+    userIds?: number[] | null | undefined;
+    color?: number | null | undefined;
+    useDefaultRecipients?: boolean | null | undefined;
+    defaultGroups?: string[] | null | undefined;
+    defaultRecipients?: number[] | null | undefined;
+    isFavorited?: boolean | null | undefined;
+    icon?: number | null | undefined;
+    filters?: Record<string, string> | null | undefined;
+}>>>;
+/**
+ * Client for `/api/v1/channels/`. The SDK auto-generates an `id` on
+ * `createChannel` when the caller doesn't supply one — pass your own `id`
+ * to keep an optimistic-UI ID stable through the round-trip.
+ */
+export declare class ChannelsClient extends BaseClient {
+    /** Lists channels in a workspace. */
+    getChannels(args: GetChannelsArgs): Promise<Channel[]>;
+    /** Fetches a single channel by ID. */
+    getChannel(id: string): Promise<Channel>;
+    /** Creates a new channel. `id` is auto-generated if not supplied. */
+    createChannel(args: CreateChannelArgs): Promise<Channel>;
+    /** Partial update of an existing channel. */
+    updateChannel(args: UpdateChannelArgs): Promise<Channel>;
+    /** Updates the channel's view filter (`only_open` / `all` / `only_closed`). */
+    updateFilters(args: {
+        id: string;
+        filterClosed: 'only_open' | 'all' | 'only_closed';
+    }): Promise<StatusOk>;
+    /** Permanently deletes a channel. */
+    deleteChannel(id: string): Promise<StatusOk>;
+    archiveChannel(id: string): Promise<StatusOk>;
+    unarchiveChannel(id: string): Promise<StatusOk>;
+    favoriteChannel(id: string): Promise<StatusOk>;
+    unfavoriteChannel(id: string): Promise<StatusOk>;
+    addUser(args: AddChannelUserArgs): Promise<Channel>;
+    addUsers(args: AddChannelUsersArgs): Promise<Channel>;
+    removeUser(args: RemoveChannelUserArgs): Promise<Channel>;
+    removeUsers(args: RemoveChannelUsersArgs): Promise<Channel>;
+    private simple;
+}