@doist/comms-sdk 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Doist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,143 @@
-# @doist/comms-sdk
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@doist/comms-sdk`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+# Comms SDK TypeScript
+
+The official TypeScript SDK for the Comms REST API.
+
+## Installation
+
+```bash
+npm install @doist/comms-sdk
+```
+
+## Usage
+
+```typescript
+import { CommsApi } from '@doist/comms-sdk'
+
+const api = new CommsApi('YOUR_API_TOKEN')
+
+api.users
+    .getSessionUser()
+    .then((user) => console.log(user))
+    .catch((error) => console.log(error))
+```
+
+By default the SDK targets production at `https://comms.todoist.com`.
+Pass a `baseUrl` option to point at a different deployment — staging
+lives at `https://comms.staging.todoist.com`:
+
+```typescript
+const api = new CommsApi('YOUR_API_TOKEN', {
+    baseUrl: 'https://comms.staging.todoist.com',
+})
+```
+
+### Creating entities
+
+Channel / thread / comment / conversation / message / group IDs are
+opaque base58-encoded UUIDv7 strings; `workspaceId` and `userId` are
+numeric.
+
+Creation endpoints (`createChannel`, `createThread`, `createComment`,
+`getOrCreateConversation`, `createMessage`, `createGroup`) accept an
+optional `id`. **A caller-supplied `id` must be a base58-encoded
+UUIDv7** — anything else fails fast with a `UuidV7Error` before the
+request leaves the SDK. Either mint your own with `generateId()` (handy
+for optimistic UI — the ID survives the round-trip unchanged) or omit
+`id` and let the SDK mint one:
+
+```typescript
+import { CommsApi, generateId } from '@doist/comms-sdk'
+
+const api = new CommsApi('YOUR_API_TOKEN')
+
+// Option 1: let the SDK mint an ID
+const channel = await api.channels.createChannel({
+    workspaceId: 1,
+    name: 'Engineering',
+})
+
+// Option 2: mint the ID yourself (must be a base58 UUIDv7 from generateId)
+const id = generateId()
+const sameChannel = await api.channels.createChannel({
+    workspaceId: 1,
+    name: 'Engineering',
+    id,
+})
+```
+
+### Broadcast group markers
+
+Use the string constants `EVERYONE` / `EVERYONE_IN_THREAD` when
+populating `groups[]` / `directGroupMentions[]` directly, or pass
+`notifyAudience` to `createComment` / `closeThread` / `reopenThread`
+and let the SDK encode it for you:
+
+```typescript
+await api.comments.createComment({
+    threadId,
+    content: 'Heads up everyone',
+    notifyAudience: 'channel', // encoded as EVERYONE
+})
+```
+
+### OAuth 2.0
+
+```typescript
+import { getAuthorizationUrl, getAuthToken, CommsApi } from '@doist/comms-sdk'
+
+const authUrl = getAuthorizationUrl(
+    'your-client-id',
+    ['user:read', 'channels:read'],
+    'state-parameter',
+    'https://yourapp.com/callback',
+)
+
+const tokenResponse = await getAuthToken({
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    code: 'authorization-code',
+    redirectUri: 'https://yourapp.com/callback',
+})
+
+const api = new CommsApi(tokenResponse.accessToken)
+const user = await api.users.getSessionUser()
+```
+
+### Short-lived processes (CLIs, scripts)
+
+On Node, the SDK keeps a connection pool alive across requests so HTTP/2
+multiplexing and TLS reuse actually work. Long-running processes don't
+need to think about it. **Short-lived processes should `await api.close()`
+before exit**, otherwise Node's event loop waits ~4 seconds for idle
+sockets to time out:
+
+```typescript
+const api = new CommsApi('YOUR_API_TOKEN')
+try {
+    await api.users.getSessionUser()
+} finally {
+    await api.close()
+}
+```
+
+`api.close()` drains the process-global pool, so it also covers code
+paths that only use the standalone OAuth helpers (`getAuthToken`,
+`revokeAuthToken`, `registerClient`). Those flows can also import
+`closeDefaultDispatcher` directly.
+
+## Development
+
+- `npm install`
+- `npm test` — Vitest
+- `npm run type-check` — TypeScript
+- `npm run check` — oxlint + oxfmt
+- `npm run build` — emit CJS + ESM + d.ts
+
+## Releases
+
+The package follows semantic versioning; releases publish to npm via the
+GitHub workflow.
+
+## Feedback
+
+Open issues at https://github.com/Doist/comms-sdk-typescript.

package/dist/cjs/authentication.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_ENDPOINT_AUTH_METHODS = exports.COMMS_SCOPES = void 0;
+exports.getAuthStateParameter = getAuthStateParameter;
+exports.getAuthorizationUrl = getAuthorizationUrl;
+exports.getAuthToken = getAuthToken;
+exports.revokeAuthToken = revokeAuthToken;
+exports.registerClient = registerClient;
+const uuid_1 = require("uuid");
+const http_client_1 = require("./transport/http-client");
+const errors_1 = require("./types/errors");
+/**
+ * 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
+ */
+exports.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. */
+exports.TOKEN_ENDPOINT_AUTH_METHODS = [
+    'client_secret_post',
+    'client_secret_basic',
+    'none',
+];
+function getAuthStateParameter() {
+    return (0, uuid_1.v4)();
+}
+/**
+ * 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}.
+ */
+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()}`;
+}
+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 (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: tokenUrl,
+        relativePath: '',
+        payload,
+        customFetch: options?.customFetch,
+    });
+    if (!(0, http_client_1.isSuccess)(response) || !response.data?.accessToken) {
+        throw new errors_1.CommsRequestError('Authentication token exchange failed.', response.status, response.data);
+    }
+    return response.data;
+}
+async function revokeAuthToken(args, options) {
+    const revokeUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/revoke`
+        : 'https://comms.todoist.com/oauth/revoke';
+    const response = await (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: revokeUrl,
+        relativePath: '',
+        payload: {
+            clientId: args.clientId,
+            clientSecret: args.clientSecret,
+            token: args.accessToken,
+        },
+        customFetch: options?.customFetch,
+    });
+    return (0, http_client_1.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}
+ */
+async function registerClient(args, options) {
+    const registerUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/register`
+        : 'https://comms.todoist.com/oauth/register';
+    const response = await (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: registerUrl,
+        relativePath: '',
+        payload: { ...args, scope: args.scope?.join(' ') },
+        customFetch: options?.customFetch,
+    });
+    if (!(0, http_client_1.isSuccess)(response) || !response.data?.clientId) {
+        throw new errors_1.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/cjs/clients/add-comment-helper.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addCommentRequest = addCommentRequest;
+const endpoints_1 = require("../consts/endpoints");
+const http_client_1 = require("../transport/http-client");
+const entities_1 = require("../types/entities");
+const enums_1 = require("../types/enums");
+const uuidv7_1 = require("../utils/uuidv7");
+const SENTINEL_GROUP_IDS = new Set(Object.values(enums_1.NOTIFY_AUDIENCE_GROUP_IDS));
+function isNotifyAudience(value) {
+    return typeof value === 'string' && enums_1.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: ${enums_1.NOTIFY_AUDIENCES.join(', ')}.`);
+    }
+    const sentinel = enums_1.NOTIFY_AUDIENCE_GROUP_IDS[params.notifyAudience];
+    const { notifyAudience: _stripped, groups, ...rest } = params;
+    return { ...rest, groups: [...(groups ?? []), sentinel] };
+}
+/**
+ * Internal helper that powers `comments.createComment`,
+ * `threads.closeThread`, and `threads.reopenThread`.
+ *
+ * Normalizes the `notifyAudience` flag into a sentinel `groups` entry,
+ * rejects sentinel IDs passed via `groups` / `directGroupMentions`, mints a
+ * UUIDv7 `id` when the caller omits one, and posts to `/comments/add`. When
+ * `threadAction` is set (`'close'` / `'reopen'`), it is forwarded on the
+ * wire so the same request both adds the comment and transitions the
+ * parent thread.
+ *
+ * @param context - Per-call client context (base URI, API token, optional `customFetch`).
+ * @param params - The comment payload (`{@link CreateCommentArgs}`).
+ * @param options - Optional configuration.
+ * @param options.threadAction - When set, also transitions the parent thread (`'close'` or `'reopen'`).
+ * @returns The parsed {@link Comment} returned by the API.
+ */
+function addCommentRequest(context, params, options) {
+    const normalized = applyNotifyAudience(params);
+    const withId = { ...normalized, id: (0, uuidv7_1.resolveCreateId)(normalized.id) };
+    const payload = options?.threadAction
+        ? { ...withId, threadAction: options.threadAction }
+        : withId;
+    return (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: context.baseUri,
+        relativePath: `${endpoints_1.ENDPOINT_COMMENTS}/add`,
+        apiToken: context.apiToken,
+        payload,
+        customFetch: context.customFetch,
+    }).then((response) => entities_1.CommentSchema.parse(response.data));
+}

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseClient = void 0;
+const endpoints_1 = require("../consts/endpoints");
+const api_version_1 = require("../types/api-version");
+/**
+ * Base class for every Comms API client. Centralizes URL handling and
+ * config so individual clients stay focused on their endpoints.
+ */
+class BaseClient {
+    constructor(config) {
+        this.apiToken = config.apiToken;
+        this.baseUrl = config.baseUrl;
+        this.defaultVersion = config.version || api_version_1.DEFAULT_API_VERSION;
+        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() {
+        return (0, endpoints_1.getCommsBaseUri)(this.defaultVersion, this.baseUrl);
+    }
+}
+exports.BaseClient = BaseClient;