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

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

@@ -15,7 +15,18 @@ export const GroupListSchema = z.array(GroupSchema);
  * `workspace_id` alongside the group `id`.
  */
 export class GroupsClient extends BaseClient {
-    /** Lists groups in a workspace. */
+    /**
+     * Gets all groups for a given workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns An array of group objects.
+     *
+     * @example
+     * ```typescript
+     * const groups = await api.groups.getGroups(123)
+     * groups.forEach(g => console.log(g.name))
+     * ```
+     */
     getGroups(workspaceId) {
         return request({
             httpMethod: 'GET',
@@ -26,31 +37,113 @@ export class GroupsClient extends BaseClient {
             customFetch: this.customFetch,
         }).then((response) => GroupListSchema.parse(response.data));
     }
-    /** Fetches a single group by ID (requires `workspaceId`). */
+    /**
+     * Gets a single group object by id. Requires `workspaceId`.
+     *
+     * @param args - The arguments for getting a group.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     * @returns The group object.
+     */
     getGroup(args) {
         return this.simple('GET', 'getone', { ...args }, GroupSchema);
     }
-    /** Creates a new group. `id` is auto-generated if not supplied. */
+    /**
+     * Creates a new group. `id` is auto-generated if not supplied.
+     *
+     * @param args - The arguments for creating a group.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.name - The group name.
+     * @param args.id - Optional caller-supplied group ID (for optimistic-UI workflows).
+     * @param args.description - Optional group description.
+     * @param args.userIds - Optional array of user IDs to add to the group.
+     * @returns The created group object.
+     *
+     * @example
+     * ```typescript
+     * const group = await api.groups.createGroup({
+     *   workspaceId: 123,
+     *   name: 'Engineering Team',
+     *   userIds: [1, 2, 3],
+     * })
+     * ```
+     */
     createGroup(args) {
         return this.simple('POST', 'add', { ...args, id: resolveCreateId(args.id) }, GroupSchema);
     }
-    /** Updates a group. Requires `workspaceId`. */
+    /**
+     * Updates a group's properties. Requires `workspaceId`.
+     *
+     * @param args - The arguments for updating a group.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.name - Optional new group name.
+     * @param args.description - Optional new group description.
+     * @returns The updated group object.
+     */
     updateGroup(args) {
         return this.simple('POST', 'update', { ...args }, GroupSchema);
     }
-    /** Permanently deletes a group. Requires `workspaceId`. */
+    /**
+     * Permanently deletes a group. Requires `workspaceId`.
+     *
+     * @param args - The arguments for deleting a group.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     */
     deleteGroup(args) {
         return this.simple('POST', 'remove', { ...args }, StatusOkSchema);
     }
+    /**
+     * Adds a user to a group.
+     *
+     * @param args - The arguments for adding a user.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userId - The user ID to add.
+     */
     addUser(args) {
         return this.simple('POST', 'add_user', { ...args }, StatusOkSchema);
     }
+    /**
+     * Adds multiple users to a group.
+     *
+     * @param args - The arguments for adding users.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userIds - Array of user IDs to add.
+     *
+     * @example
+     * ```typescript
+     * await api.groups.addUsers({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX45',
+     *   workspaceId: 123,
+     *   userIds: [101, 202, 303],
+     * })
+     * ```
+     */
     addUsers(args) {
         return this.simple('POST', 'add_users', { ...args }, StatusOkSchema);
     }
+    /**
+     * Removes a user from a group.
+     *
+     * @param args - The arguments for removing a user.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userId - The user ID to remove.
+     */
     removeUser(args) {
         return this.simple('POST', 'remove_user', { ...args }, StatusOkSchema);
     }
+    /**
+     * Removes multiple users from a group.
+     *
+     * @param args - The arguments for removing users.
+     * @param args.id - The group ID.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userIds - Array of user IDs to remove.
+     */
     removeUsers(args) {
         return this.simple('POST', 'remove_users', { ...args }, StatusOkSchema);
     }

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

@@ -1,20 +1,54 @@
+import { z } from 'zod';
 import { ENDPOINT_INBOX } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { InboxThreadSchema } from '../types/entities.js';
+import { createInboxThreadSchema, InboxThreadSchema } from '../types/entities.js';
 import { BaseClient } from './base-client.js';
+export const InboxThreadListSchema = z.array(InboxThreadSchema);
 /** Client for `/api/v1/inbox/`. */
 export class InboxClient extends BaseClient {
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.inboxThreadSchema = this.linkBaseUrl
+            ? createInboxThreadSchema(this.linkBaseUrl)
+            : InboxThreadSchema;
+        this.inboxThreadListSchema = this.linkBaseUrl
+            ? z.array(this.inboxThreadSchema)
+            : InboxThreadListSchema;
+    }
     /**
      * 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)
@@ -28,9 +62,20 @@ export class InboxClient extends BaseClient {
             apiToken: this.apiToken,
             payload: params,
             customFetch: this.customFetch,
-        }).then((response) => response.data.map((thread) => InboxThreadSchema.parse(thread)));
+        }).then((response) => this.inboxThreadListSchema.parse(response.data));
     }
-    /** 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 +86,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 +106,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 +126,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 +146,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 = {