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

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

@@ -6,15 +6,36 @@ import { BaseClient } from './base-client.js';
 export class InboxClient extends BaseClient {
     /**
      * Gets inbox items (threads).
+     *
+     * @param args - The arguments for getting inbox.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.newerThan - Optional date to get items newer than.
+     * @param args.olderThan - Optional date to get items older than.
+     * @param args.limit - Optional limit on number of items returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @param args.archiveFilter - Optional filter: 'active' (default), 'archived', or 'all'.
+     * @returns Inbox threads.
+     *
+     * @example
+     * ```typescript
+     * const inbox = await api.inbox.getInbox({
+     *   workspaceId: 123,
+     *   newerThan: new Date('2024-01-01'),
+     * })
+     *
+     * // Include archived (done) items alongside active ones
+     * const allInbox = await api.inbox.getInbox({
+     *   workspaceId: 123,
+     *   archiveFilter: 'all',
+     * })
+     * ```
      */
     getInbox(args) {
         const params = { workspace_id: args.workspaceId };
-        const newerThan = args.newerThan ?? args.since;
-        if (newerThan)
-            params.newer_than_ts = Math.floor(newerThan.getTime() / 1000);
-        const olderThan = args.olderThan ?? args.until;
-        if (olderThan)
-            params.older_than_ts = Math.floor(olderThan.getTime() / 1000);
+        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);
         if (args.limit)
             params.limit = args.limit;
         if (args.cursor)
@@ -30,7 +51,18 @@ export class InboxClient extends BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data.map((thread) => InboxThreadSchema.parse(thread)));
     }
-    /** Gets unread count for inbox. */
+    /**
+     * Gets unread count for inbox.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns The unread count.
+     *
+     * @example
+     * ```typescript
+     * const count = await api.inbox.getCount(123)
+     * console.log(`Unread items: ${count}`)
+     * ```
+     */
     getCount(workspaceId) {
         return request({
             httpMethod: 'GET',
@@ -41,7 +73,16 @@ export class InboxClient extends BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data.data);
     }
-    /** Archives a thread in the inbox. */
+    /**
+     * Archives a thread in the inbox.
+     *
+     * @param id - The thread ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.archiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
+     * ```
+     */
     archiveThread(id) {
         return request({
             httpMethod: 'POST',
@@ -52,7 +93,16 @@ export class InboxClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Unarchives a thread in the inbox. */
+    /**
+     * Unarchives a thread in the inbox.
+     *
+     * @param id - The thread ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.unarchiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
+     * ```
+     */
     unarchiveThread(id) {
         return request({
             httpMethod: 'POST',
@@ -63,7 +113,16 @@ export class InboxClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Marks all inbox items as read in a workspace. */
+    /**
+     * Marks all inbox items as read in a workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.markAllRead(123)
+     * ```
+     */
     markAllRead(workspaceId) {
         return request({
             httpMethod: 'POST',
@@ -74,14 +133,28 @@ export class InboxClient extends BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Archives all inbox items in a workspace. */
+    /**
+     * Archives all inbox items in a workspace.
+     *
+     * @param args - The arguments for archiving all.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.channelIds - Optional array of channel IDs to filter by.
+     * @param args.olderThan - Optional date to filter items older than.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.archiveAll({
+     *   workspaceId: 123,
+     *   olderThan: new Date('2024-01-01'),
+     * })
+     * ```
+     */
     archiveAll(args) {
         const params = { workspace_id: args.workspaceId };
         if (args.channelIds)
             params.channel_ids = args.channelIds;
-        const olderThan = args.olderThan ?? args.until;
-        if (olderThan)
-            params.older_than_ts = Math.floor(olderThan.getTime() / 1000);
+        if (args.olderThan)
+            params.older_than_ts = Math.floor(args.olderThan.getTime() / 1000);
         return request({
             httpMethod: 'POST',
             baseUri: this.getBaseUri(),

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

@@ -14,7 +14,20 @@ function reactionTarget(args) {
  * Client for interacting with Comms reaction endpoints.
  */
 export class ReactionsClient extends BaseClient {
-    /** Adds an emoji reaction to a thread, comment, or conversation message. */
+    /**
+     * Adds an emoji reaction to a thread, comment, or conversation message.
+     *
+     * @param args - The arguments for adding a reaction.
+     * @param args.threadId - Optional thread ID.
+     * @param args.commentId - Optional comment ID.
+     * @param args.messageId - Optional message ID (for conversation messages).
+     * @param args.reaction - The reaction emoji to add.
+     *
+     * @example
+     * ```typescript
+     * await api.reactions.add({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z', reaction: '👍' })
+     * ```
+     */
     add(args) {
         return request({
             httpMethod: 'POST',
@@ -30,6 +43,18 @@ export class ReactionsClient extends BaseClient {
      *
      * Returns an object with emoji reactions as keys and arrays of user IDs as
      * values, or null if no reactions.
+     *
+     * @param args - The arguments for getting reactions.
+     * @param args.threadId - Optional thread ID.
+     * @param args.commentId - Optional comment ID.
+     * @param args.messageId - Optional message ID (for conversation messages).
+     * @returns A reaction object with emoji reactions as keys and arrays of user IDs as values, or null if no reactions.
+     *
+     * @example
+     * ```typescript
+     * const reactions = await api.reactions.get({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z' })
+     * // Returns: { "👍": [101, 202, 303], "❤️": [101, 202] }
+     * ```
      */
     get(args) {
         return request({
@@ -41,7 +66,20 @@ export class ReactionsClient extends BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data);
     }
-    /** Removes an emoji reaction from a thread, comment, or conversation message. */
+    /**
+     * Removes an emoji reaction from a thread, comment, or conversation message.
+     *
+     * @param args - The arguments for removing a reaction.
+     * @param args.threadId - Optional thread ID.
+     * @param args.commentId - Optional comment ID.
+     * @param args.messageId - Optional message ID (for conversation messages).
+     * @param args.reaction - The reaction emoji to remove.
+     *
+     * @example
+     * ```typescript
+     * await api.reactions.remove({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z', reaction: '👍' })
+     * ```
+     */
     remove(args) {
         return request({
             httpMethod: 'POST',

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

@@ -8,6 +8,26 @@ import { BaseClient } from './base-client.js';
 export class SearchClient extends BaseClient {
     /**
      * Searches across all threads and conversations in a workspace.
+     *
+     * @param args - The arguments for searching.
+     * @param args.query - The search query string. Optional when `mentionSelf: true` is set; required otherwise.
+     * @param args.workspaceId - The workspace ID to search in.
+     * @param args.channelIds - Optional array of channel IDs to filter by.
+     * @param args.authorIds - Optional array of author user IDs to filter by.
+     * @param args.mentionSelf - Optional flag to filter by mentions of the current user. When true, `query` may be omitted.
+     * @param args.dateFrom - Optional start date for filtering (YYYY-MM-DD).
+     * @param args.dateTo - Optional end date for filtering (YYYY-MM-DD).
+     * @param args.limit - Optional limit on number of results returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns Search results with pagination.
+     *
+     * @example
+     * ```typescript
+     * const results = await api.search.search({
+     *   query: 'important meeting',
+     *   workspaceId: 123,
+     * })
+     * ```
      */
     search(args) {
         const params = { workspace_id: args.workspaceId };
@@ -41,6 +61,21 @@ export class SearchClient extends BaseClient {
     }
     /**
      * Searches within comments of a specific thread.
+     *
+     * @param args - The arguments for searching within a thread.
+     * @param args.query - The search query string.
+     * @param args.threadId - The thread ID to search in.
+     * @param args.limit - Optional limit on number of results returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns Comment IDs that match the search query.
+     *
+     * @example
+     * ```typescript
+     * const results = await api.search.searchThread({
+     *   query: 'deadline',
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     * })
+     * ```
      */
     searchThread(args) {
         const params = {
@@ -62,6 +97,21 @@ export class SearchClient extends BaseClient {
     }
     /**
      * Searches within messages of a specific conversation.
+     *
+     * @param args - The arguments for searching within a conversation.
+     * @param args.query - The search query string.
+     * @param args.conversationId - The conversation ID to search in.
+     * @param args.limit - Optional limit on number of results returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns Message IDs that match the search query.
+     *
+     * @example
+     * ```typescript
+     * const results = await api.search.searchConversation({
+     *   query: 'budget',
+     *   conversationId: '7YpL3oZ4kZ9vP7Q1tR2sX42',
+     * })
+     * ```
      */
     searchConversation(args) {
         const params = {

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

@@ -17,19 +17,40 @@ const GetUnreadResponseSchema = z.object({
  */
 export class ThreadsClient extends BaseClient {
     /**
-     * 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(),
@@ -39,52 +60,147 @@ export class ThreadsClient extends BaseClient {
             customFetch: this.customFetch,
         }).then((response) => 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);
     }
-    /** 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);
     }
-    /** 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);
     }
-    /** 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);
     }
+    /**
+     * 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,25 +208,104 @@ 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);
     }
+    /**
+     * 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);
     }
+    /**
+     * 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');
     }