@doist/comms-sdk 0.1.0-alpha.1 → 0.2.1

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { ENDPOINT_THREADS } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { StatusOkSchema, ThreadSchema, UnreadThreadSchema, } from '../types/entities.js';
+import { CommentSchema, createCommentSchema, createThreadSchema, StatusOkSchema, ThreadSchema, UnreadThreadSchema, } from '../types/entities.js';
 import { resolveCreateId } from '../utils/uuidv7.js';
 import { addCommentRequest } from './add-comment-helper.js';
 import { BaseClient } from './base-client.js';
@@ -16,20 +16,55 @@ const GetUnreadResponseSchema = z.object({
  * `createThread` when the caller doesn't supply one.
  */
 export class ThreadsClient extends BaseClient {
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.threadSchema = this.linkBaseUrl
+            ? createThreadSchema(this.linkBaseUrl)
+            : ThreadSchema;
+        this.threadListSchema = this.linkBaseUrl
+            ? z.array(this.threadSchema)
+            : ThreadListSchema;
+        this.commentSchema = this.linkBaseUrl
+            ? createCommentSchema(this.linkBaseUrl)
+            : CommentSchema;
+    }
     /**
-     * Lists threads. At least one of `channelId` / `workspaceId` is required.
+     * Gets threads. At least one of `channelId` / `workspaceId` is required.
      * `newerThan` / `olderThan` (`Date`) are converted to the
      * `newer_than_ts` / `older_than_ts` epoch-second params on the wire.
+     *
+     * @param args - The arguments for getting threads.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.channelId - Optional channel ID to narrow to a single channel.
+     * @param args.archived - Optional flag to include archived threads.
+     * @param args.newerThan - Optional date to get threads newer than.
+     * @param args.olderThan - Optional date to get threads older than.
+     * @param args.limit - Optional limit on number of threads returned.
+     * @returns An array of thread objects.
+     *
+     * @example
+     * ```typescript
+     * const threads = await api.threads.getThreads({
+     *   workspaceId: 123,
+     *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
+     * })
+     * threads.forEach(t => console.log(t.title))
+     * ```
      */
     getThreads(args) {
-        const { newerThan, olderThan, newer_than_ts, older_than_ts, ...rest } = args;
-        const resolvedNewerThan = newerThan ? Math.floor(newerThan.getTime() / 1000) : newer_than_ts;
-        const resolvedOlderThan = olderThan ? Math.floor(olderThan.getTime() / 1000) : older_than_ts;
-        const params = {
-            ...rest,
-            ...(resolvedNewerThan != null ? { newer_than_ts: resolvedNewerThan } : {}),
-            ...(resolvedOlderThan != null ? { older_than_ts: resolvedOlderThan } : {}),
-        };
+        const params = { workspaceId: args.workspaceId };
+        if (args.channelId != null)
+            params.channelId = args.channelId;
+        if (args.archived != null)
+            params.archived = args.archived;
+        if (args.limit != null)
+            params.limit = args.limit;
+        if (args.newerThan)
+            params.newer_than_ts = Math.floor(args.newerThan.getTime() / 1000);
+        if (args.olderThan)
+            params.older_than_ts = Math.floor(args.olderThan.getTime() / 1000);
         return request({
             httpMethod: 'GET',
             baseUri: this.getBaseUri(),
@@ -37,54 +72,149 @@ export class ThreadsClient extends BaseClient {
             apiToken: this.apiToken,
             payload: params,
             customFetch: this.customFetch,
-        }).then((response) => ThreadListSchema.parse(response.data));
+        }).then((response) => this.threadListSchema.parse(response.data));
     }
-    /** Fetches a single thread by ID. */
+    /**
+     * Gets a single thread object by id.
+     *
+     * @param id - The thread ID.
+     * @returns The thread object.
+     */
     getThread(id) {
-        return this.simple('GET', 'getone', { id }, ThreadSchema);
+        return this.simple('GET', 'getone', { id }, this.threadSchema);
     }
-    /** Creates a new thread. `id` is auto-generated if not supplied. */
+    /**
+     * Creates a new thread in a channel. `id` is auto-generated if not supplied.
+     *
+     * @param args - The arguments for creating a thread.
+     * @param args.channelId - The channel ID.
+     * @param args.title - Optional thread title.
+     * @param args.content - The thread content.
+     * @param args.recipients - Optional array of user IDs to notify.
+     * @param args.groups - Optional array of custom group IDs to notify.
+     * @returns The created thread object.
+     *
+     * @example
+     * ```typescript
+     * const thread = await api.threads.createThread({
+     *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
+     *   title: 'New Feature Discussion',
+     *   content: 'Let\'s discuss the new feature...',
+     * })
+     * ```
+     */
     createThread(args) {
-        return this.simple('POST', 'add', { ...args, id: resolveCreateId(args.id) }, ThreadSchema);
+        return this.simple('POST', 'add', { ...args, id: resolveCreateId(args.id) }, this.threadSchema);
     }
-    /** Partial update of an existing thread. */
+    /**
+     * Partial update of an existing thread.
+     *
+     * @param args - The arguments for updating a thread.
+     * @param args.id - The thread ID.
+     * @param args.title - Optional new thread title.
+     * @param args.content - Optional new thread content.
+     * @returns The updated thread object.
+     */
     updateThread(args) {
-        return this.simple('POST', 'update', { ...args }, ThreadSchema);
+        return this.simple('POST', 'update', { ...args }, this.threadSchema);
     }
-    /** Permanently deletes a thread. */
+    /**
+     * Permanently deletes a thread.
+     *
+     * @param id - The thread ID.
+     */
     deleteThread(id) {
         return this.simple('POST', 'remove', { id }, StatusOkSchema);
     }
-    /** Saves a thread (formerly "star"). */
+    /**
+     * Saves a thread (formerly "star").
+     *
+     * @param id - The thread ID.
+     */
     saveThread(id) {
         return this.simple('GET', 'save', { id }, StatusOkSchema);
     }
-    /** Unsaves a thread (formerly "unstar"). */
+    /**
+     * Unsaves a thread (formerly "unstar").
+     *
+     * @param id - The thread ID.
+     */
     unsaveThread(id) {
         return this.simple('GET', 'unsave', { id }, StatusOkSchema);
     }
+    /**
+     * Pins a thread.
+     *
+     * @param id - The thread ID.
+     */
     pinThread(id) {
         return this.simple('GET', 'pin', { id }, StatusOkSchema);
     }
+    /**
+     * Unpins a thread.
+     *
+     * @param id - The thread ID.
+     */
     unpinThread(id) {
         return this.simple('GET', 'unpin', { id }, StatusOkSchema);
     }
-    /** Moves a thread to another channel. */
+    /**
+     * Moves a thread to another channel.
+     *
+     * @param args - The arguments for moving a thread.
+     * @param args.id - The thread ID.
+     * @param args.toChannel - The target channel ID.
+     * @returns The updated thread object.
+     */
     moveToChannel(args) {
-        return this.simple('GET', 'move_to_channel', { ...args }, ThreadSchema);
+        return this.simple('GET', 'move_to_channel', { ...args }, this.threadSchema);
     }
+    /**
+     * Marks a thread as read.
+     *
+     * @param args - The arguments for marking a thread as read.
+     * @param args.id - The thread ID.
+     * @param args.objIndex - The index of the last known read message.
+     */
     markRead(args) {
         return this.simple('POST', 'mark_read', { ...args }, StatusOkSchema);
     }
+    /**
+     * Marks a thread as unread.
+     *
+     * @param args - The arguments for marking a thread as unread.
+     * @param args.id - The thread ID.
+     * @param args.objIndex - The index of the last unread message. Use -1 to mark the whole thread as unread.
+     */
     markUnread(args) {
         return this.simple('POST', 'mark_unread', { ...args }, StatusOkSchema);
     }
+    /**
+     * Marks a thread as unread for others. Useful to notify others about thread changes.
+     *
+     * @param args - The arguments for marking a thread as unread for others.
+     * @param args.id - The thread ID.
+     * @param args.objIndex - The index of the last unread message. Use -1 to mark the whole thread as unread.
+     */
     markUnreadForOthers(args) {
         return this.simple('POST', 'mark_unread_for_others', { ...args }, StatusOkSchema);
     }
     /**
      * Marks every thread in a workspace or channel as read. Exactly one of
      * `workspaceId` / `channelId` should be set.
+     *
+     * @param args - Either workspaceId or channelId (one is required).
+     * @param args.workspaceId - The workspace ID.
+     * @param args.channelId - The channel ID.
+     *
+     * @example
+     * ```typescript
+     * // Mark all in workspace
+     * await api.threads.markAllRead({ workspaceId: 123 })
+     *
+     * // Mark all in channel
+     * await api.threads.markAllRead({ channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44' })
+     * ```
      */
     markAllRead(args) {
         if (!args.workspaceId && !args.channelId) {
@@ -92,31 +222,115 @@ export class ThreadsClient extends BaseClient {
         }
         return this.simple('POST', 'mark_all_read', { ...args }, StatusOkSchema);
     }
+    /**
+     * Clears unread threads in a workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     */
     clearUnread(workspaceId) {
         return this.simple('GET', 'clear_unread', { workspaceId }, StatusOkSchema);
     }
     /**
      * Returns unread threads for a workspace, paired with the unread version
      * counter and (optionally) the inbox unread count.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns Object containing the array of unread thread references, a version counter, and optionally the inbox unread count.
      */
     getUnread(workspaceId) {
         return this.simple('GET', 'get_unread', { workspaceId }, GetUnreadResponseSchema);
     }
+    /**
+     * Mutes a thread for a specified number of minutes.
+     * When muted, you will not get notified in your inbox about new comments.
+     *
+     * @param args - The arguments for muting a thread.
+     * @param args.id - The thread ID.
+     * @param args.minutes - Number of minutes to mute the thread.
+     * @returns The updated thread object.
+     *
+     * @example
+     * ```typescript
+     * const thread = await api.threads.muteThread({ id: '7YpL3oZ4kZ9vP7Q1tR2sX3z', minutes: 30 })
+     * ```
+     */
     muteThread(args) {
-        return this.simple('GET', 'mute', { ...args }, ThreadSchema);
+        return this.simple('GET', 'mute', { ...args }, this.threadSchema);
     }
+    /**
+     * Unmutes a thread.
+     * You will start to see notifications in your inbox again when new comments are added.
+     *
+     * @param id - The thread ID.
+     * @returns The updated thread object.
+     */
     unmuteThread(id) {
-        return this.simple('GET', 'unmute', { id }, ThreadSchema);
+        return this.simple('GET', 'unmute', { id }, this.threadSchema);
     }
+    /**
+     * Closes a thread by adding a comment with a close action.
+     *
+     * @param args - The arguments for closing a thread.
+     * @param args.id - The thread ID.
+     * @param args.content - The comment content.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @param args.actions - Optional array of action objects.
+     * @param args.recipients - Optional array of user IDs to notify directly.
+     * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.directMentions - Optional array of user IDs that were @-mentioned in
+     *   `content`.
+     * @param args.notifyAudience - Optional broader audience to notify in addition to
+     *   `recipients` and `groups`. `'channel'` notifies everyone in the channel;
+     *   `'thread'` notifies everyone who has interacted with the thread.
+     * @returns The created comment object.
+     *
+     * @example
+     * ```typescript
+     * const comment = await api.threads.closeThread({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'Closing this thread — resolved.',
+     * })
+     * ```
+     */
     closeThread(args) {
         return this.addCommentWithAction(args, 'close');
     }
+    /**
+     * Reopens a thread by adding a comment with a reopen action.
+     *
+     * @param args - The arguments for reopening a thread.
+     * @param args.id - The thread ID.
+     * @param args.content - The comment content.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @param args.actions - Optional array of action objects.
+     * @param args.recipients - Optional array of user IDs to notify directly.
+     * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.directMentions - Optional array of user IDs that were @-mentioned in
+     *   `content`.
+     * @param args.notifyAudience - Optional broader audience to notify in addition to
+     *   `recipients` and `groups`. `'channel'` notifies everyone in the channel;
+     *   `'thread'` notifies everyone who has interacted with the thread.
+     * @returns The created comment object.
+     *
+     * @example
+     * ```typescript
+     * const comment = await api.threads.reopenThread({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'Reopening — need further discussion.',
+     * })
+     * ```
+     */
     reopenThread(args) {
         return this.addCommentWithAction(args, 'reopen');
     }
     addCommentWithAction(args, threadAction) {
         const { id, ...rest } = args;
-        return addCommentRequest({ baseUri: this.getBaseUri(), apiToken: this.apiToken, customFetch: this.customFetch }, { threadId: id, ...rest }, { threadAction });
+        return addCommentRequest({
+            baseUri: this.getBaseUri(),
+            apiToken: this.apiToken,
+            customFetch: this.customFetch,
+            schema: this.commentSchema,
+        }, { threadId: id, ...rest }, { threadAction });
     }
     simple(httpMethod, suffix, params, schema) {
         return request({

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

@@ -8,17 +8,45 @@ import { BaseClient } from './base-client.js';
  * `loginWithTodoist` are the available entry points.
  */
 export class UsersClient extends BaseClient {
-    /** Registers a new user via the Todoist-ID bridge. */
+    /**
+     * Registers a new user via the Todoist-ID bridge.
+     *
+     * @param args - Registration arguments.
+     * @param args.name - The new user's full name.
+     * @param args.email - The new user's email.
+     * @param args.password - The new user's password.
+     * @param args.lang - Optional preferred language.
+     * @param args.acceptTerms - Optional flag confirming the user accepts the terms of service.
+     * @returns The newly registered user object.
+     */
     register(args) {
         return this.post(`${ENDPOINT_USERS}/register`, args, UserSchema, { authed: false });
     }
-    /** Logs in an existing user. */
+    /**
+     * Logs in an existing user.
+     *
+     * @param args - Login credentials.
+     * @param args.email - The user's email.
+     * @param args.password - The user's password.
+     * @param args.setSessionCookie - Optional flag to set a session cookie (default: true).
+     * @returns The authenticated user object.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.login({
+     *   email: 'user@example.com',
+     *   password: 'secret',
+     * })
+     * ```
+     */
     login(args) {
         return this.post(`${ENDPOINT_USERS}/login`, args, UserSchema, { authed: false });
     }
     /**
      * Logs in using a valid token (sent via Authorization header). The SDK
      * client is already configured with the token, so no args are needed.
+     *
+     * @returns The authenticated user object.
      */
     loginWithToken() {
         return this.post(`${ENDPOINT_USERS}/login_with_token`, undefined, UserSchema);
@@ -27,17 +55,35 @@ export class UsersClient extends BaseClient {
      * Exchanges the browser's Todoist web-session cookie for a Comms session.
      * Only useful when running in a browser context on the shared Todoist
      * registrable domain — the cookie is sent automatically by the browser.
+     *
+     * @returns The authenticated user object.
      */
     loginWithTodoist() {
         return this.post(`${ENDPOINT_USERS}/login_with_todoist`, {}, UserSchema, { authed: false });
     }
-    /** Logs in (and auto-signs-up) via a Google ID token. */
+    /**
+     * Logs in (and auto-signs-up) via a Google ID token.
+     *
+     * @param args - Google login arguments.
+     * @param args.idToken - The Google ID token.
+     * @param args.nonce - The nonce that was sent to Google.
+     * @param args.timezone - Optional user timezone.
+     * @param args.lang - Optional preferred language.
+     * @param args.mfaToken - Optional MFA token from a prior `mfaChallenge` response.
+     * @returns The authenticated user object.
+     */
     loginWithGoogle(args) {
         return this.post(`${ENDPOINT_USERS}/login_with_google`, args, UserSchema, { authed: false });
     }
     /**
      * Completes an MFA challenge issued by `loginWithGoogle` (returns an MFA
      * token to pass back to `loginWithGoogle.mfaToken`).
+     *
+     * @param args - MFA challenge arguments.
+     * @param args.challengeId - The challenge ID from the prior login attempt.
+     * @param args.factor - The MFA factor identifier.
+     * @param args.methodType - The MFA method type.
+     * @returns The MFA token to forward to `loginWithGoogle`.
      */
     mfaChallenge(args) {
         return request({
@@ -60,7 +106,17 @@ export class UsersClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Returns the user associated with the current access token. */
+    /**
+     * Gets the user associated with the current access token.
+     *
+     * @returns The authenticated user's information.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.getSessionUser()
+     * console.log(user.fullName, user.email)
+     * ```
+     */
     getSessionUser() {
         return this.get(`${ENDPOINT_USERS}/get_session_user`, undefined, UserSchema);
     }
@@ -68,32 +124,74 @@ export class UsersClient extends BaseClient {
      * Fetches a single user. Defaults to the session user when no `id` is
      * passed. Cross-workspace lookups require that the caller and the target
      * share a workspace.
+     *
+     * @param args - Optional lookup arguments.
+     * @param args.id - The user ID. Defaults to the session user.
+     * @param args.workspaceId - Optional workspace ID for cross-workspace lookups.
+     * @param args.asList - Optional flag controlling list-style response.
+     * @returns The user object.
      */
     getUser(args) {
         return this.get(`${ENDPOINT_USERS}/getone`, args ?? {}, UserSchema);
     }
-    /** Looks up a user by their email address. */
+    /**
+     * Looks up a user by their email address.
+     *
+     * @param email - The email to look up.
+     * @returns The user object.
+     */
     getUserByEmail(email) {
         return this.get(`${ENDPOINT_USERS}/get_by_email`, { email }, UserSchema);
     }
     /**
      * Updates the logged-in user's profile. Most fields are proxied to
      * Todoist (full name, password, language, timezone, etc.).
+     *
+     * @param args - The user properties to update.
+     * @returns The updated user object.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.update({
+     *   name: 'John Doe',
+     *   timezone: 'America/New_York',
+     * })
+     * ```
      */
     update(args) {
         return this.post(`${ENDPOINT_USERS}/update`, args, UserSchema);
     }
-    /** Updates the user's password. Requires `currentPassword`. */
+    /**
+     * Updates the user's password.
+     *
+     * @param args - Password update arguments.
+     * @param args.newPassword - The new password.
+     * @param args.currentPassword - The user's existing password. Optional — sent for
+     *   re-authentication when the account has a password set.
+     * @returns The updated user object.
+     */
     updatePassword(args) {
         return this.post(`${ENDPOINT_USERS}/update_password`, args, UserSchema);
     }
-    /** Removes the user's avatar. */
+    /**
+     * Removes the user's avatar.
+     *
+     * @returns The updated user object.
+     */
     removeAvatar() {
         return this.post(`${ENDPOINT_USERS}/remove_avatar`, undefined, UserSchema);
     }
     /**
      * Invalidates the current API token and returns the user with a fresh
      * token.
+     *
+     * @returns The user object with the new token.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.invalidateToken()
+     * console.log('New token:', user.token)
+     * ```
      */
     invalidateToken() {
         return this.post(`${ENDPOINT_USERS}/invalidate_token`, undefined, UserSchema);
@@ -102,6 +200,8 @@ export class UsersClient extends BaseClient {
      * Validates that an arbitrary token is still active. Note this is sent
      * as a GET — the token is read from the query string, not the
      * Authorization header.
+     *
+     * @param token - The token to validate.
      */
     validateToken(token) {
         return request({
@@ -113,7 +213,18 @@ export class UsersClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Marks the user as active on a workspace (presence beacon). */
+    /**
+     * Marks the user as active on a workspace (presence beacon).
+     *
+     * @param args - Heartbeat arguments.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.platform - The platform identifier (e.g., 'mobile', 'desktop', 'api').
+     *
+     * @example
+     * ```typescript
+     * await api.users.heartbeat({ workspaceId: 123, platform: 'api' })
+     * ```
+     */
     heartbeat(args) {
         return request({
             httpMethod: 'GET',
@@ -124,7 +235,11 @@ export class UsersClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Resets the user's presence for a workspace. */
+    /**
+     * Resets the user's presence for a workspace (marks the user as inactive).
+     *
+     * @param workspaceId - The workspace ID.
+     */
     resetPresence(workspaceId) {
         return request({
             httpMethod: 'POST',
@@ -135,7 +250,12 @@ export class UsersClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Checks whether an email address is registered (and verified). */
+    /**
+     * Checks whether an email address is registered (and verified).
+     *
+     * @param email - The email to check.
+     * @returns Object indicating whether the email exists and is verified.
+     */
     checkEmail(email) {
         return request({
             httpMethod: 'POST',
@@ -149,6 +269,8 @@ export class UsersClient extends BaseClient {
     /**
      * Returns the current per-channel mail unsubscribe settings for the
      * caller's primary email.
+     *
+     * @returns Object mapping email-type keys to their opt-out flag.
      */
     getUnsubscribeSettings() {
         return request({
@@ -160,7 +282,12 @@ export class UsersClient extends BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data);
     }
-    /** Toggles per-email-type opt-out settings. */
+    /**
+     * Toggles per-email-type opt-out settings.
+     *
+     * @param settings - Object mapping email-type keys to their opt-out flag.
+     * @returns Status object with `"ok"` status.
+     */
     updateUnsubscribeSettings(settings) {
         return request({
             httpMethod: 'POST',