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

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { ENDPOINT_COMMENTS } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { CommentSchema, StatusOkSchema } from '../types/entities.js';
+import { CommentSchema, createCommentSchema, StatusOkSchema, } from '../types/entities.js';
 import { addCommentRequest } from './add-comment-helper.js';
 import { BaseClient } from './base-client.js';
 export const CommentListSchema = z.array(CommentSchema);
@@ -10,16 +10,46 @@ export const CommentListSchema = z.array(CommentSchema);
  * on `createComment` when the caller doesn't supply one.
  */
 export class CommentsClient extends BaseClient {
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.commentSchema = this.linkBaseUrl
+            ? createCommentSchema(this.linkBaseUrl)
+            : CommentSchema;
+        this.commentListSchema = this.linkBaseUrl
+            ? z.array(this.commentSchema)
+            : CommentListSchema;
+        // `getone` wraps the comment in `{ comment: ... }`; built once per client.
+        this.wrappedCommentSchema = z
+            .object({ comment: this.commentSchema })
+            .transform((data) => data.comment);
+    }
     /**
-     * Lists comments in a thread. `newerThan` / `olderThan` (`Date`) are
+     * Gets all comments for a thread. `newerThan` / `olderThan` (`Date`) are
      * converted to `newer_than_ts` / `older_than_ts` epoch seconds on the
      * wire.
+     *
+     * @param args - The arguments for getting comments.
+     * @param args.threadId - The thread ID.
+     * @param args.newerThan - Optional date to get comments newer than.
+     * @param args.olderThan - Optional date to get comments older than.
+     * @param args.limit - Optional limit on number of comments returned.
+     * @returns An array of comment objects.
+     *
+     * @example
+     * ```typescript
+     * const comments = await api.comments.getComments({
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   newerThan: new Date('2024-01-01'),
+     * })
+     * comments.forEach(c => console.log(c.content))
+     * ```
      */
     getComments(args) {
         const params = { threadId: args.threadId };
-        const newerThan = args.newerThan ?? args.from;
-        if (newerThan)
-            params.newerThanTs = Math.floor(newerThan.getTime() / 1000);
+        if (args.newerThan)
+            params.newerThanTs = Math.floor(args.newerThan.getTime() / 1000);
         if (args.olderThan)
             params.olderThanTs = Math.floor(args.olderThan.getTime() / 1000);
         if (args.limit)
@@ -31,11 +61,15 @@ export class CommentsClient extends BaseClient {
             apiToken: this.apiToken,
             payload: params,
             customFetch: this.customFetch,
-        }).then((response) => CommentListSchema.parse(response.data));
+        }).then((response) => this.commentListSchema.parse(response.data));
     }
-    /** Fetches a single comment by ID. The API wraps it in `{comment: ...}`. */
+    /**
+     * Gets a single comment object by id. The API wraps it in `{comment: ...}`.
+     *
+     * @param id - The comment ID.
+     * @returns The comment object.
+     */
     getComment(id) {
-        const wrappedSchema = z.object({ comment: CommentSchema }).transform((data) => data.comment);
         return request({
             httpMethod: 'GET',
             baseUri: this.getBaseUri(),
@@ -43,15 +77,51 @@ export class CommentsClient extends BaseClient {
             apiToken: this.apiToken,
             payload: { id },
             customFetch: this.customFetch,
-        }).then((response) => wrappedSchema.parse(response.data));
+        }).then((response) => this.wrappedCommentSchema.parse(response.data));
     }
     /**
-     * Creates a new comment. `id` is auto-generated if not supplied.
+     * Creates a new comment on a thread. `id` is auto-generated if not supplied.
+     *
+     * @param args - The arguments for creating a comment.
+     * @param args.threadId - The thread ID.
+     * @param args.content - The comment content.
+     * @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.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @returns The created comment object.
+     *
+     * @example
+     * ```typescript
+     * // Notify everyone who has interacted with the thread, plus two extra users.
+     * const comment = await api.comments.createComment({
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'Great idea! Let\'s proceed.',
+     *   notifyAudience: 'thread',
+     *   recipients: [101, 202],
+     * })
+     * ```
      */
     createComment(args) {
-        return addCommentRequest({ baseUri: this.getBaseUri(), apiToken: this.apiToken, customFetch: this.customFetch }, args);
+        return addCommentRequest({
+            baseUri: this.getBaseUri(),
+            apiToken: this.apiToken,
+            customFetch: this.customFetch,
+            schema: this.commentSchema,
+        }, args);
     }
-    /** Updates a comment. */
+    /**
+     * Updates a comment's properties.
+     *
+     * @param args - The arguments for updating a comment.
+     * @param args.id - The comment ID.
+     * @param args.content - The new comment content.
+     * @returns The updated comment object.
+     */
     updateComment(args) {
         return request({
             httpMethod: 'POST',
@@ -60,9 +130,13 @@ export class CommentsClient extends BaseClient {
             apiToken: this.apiToken,
             payload: { ...args },
             customFetch: this.customFetch,
-        }).then((response) => CommentSchema.parse(response.data));
+        }).then((response) => this.commentSchema.parse(response.data));
     }
-    /** Permanently deletes a comment. */
+    /**
+     * Permanently deletes a comment.
+     *
+     * @param id - The comment ID.
+     */
     deleteComment(id) {
         return request({
             httpMethod: 'POST',
@@ -74,7 +148,18 @@ export class CommentsClient extends BaseClient {
         }).then((response) => StatusOkSchema.parse(response.data));
     }
     /**
-     * Marks the user's read position in a thread. Comment IDs are strings.
+     * Marks the user's read position in a thread. Used to track where the user has read up to,
+     * so clients can scroll to this position and show a visual indicator (blue line).
+     * Comment IDs are strings.
+     *
+     * @param args - The arguments for marking read position.
+     * @param args.threadId - The thread ID.
+     * @param args.commentId - The comment ID to mark as the last read position.
+     *
+     * @example
+     * ```typescript
+     * await api.comments.markPosition({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z', commentId: '7YpL3oZ4kZ9vP7Q1tR2sX41' })
+     * ```
      */
     markPosition(args) {
         return request({

package/dist/esm/clients/conversation-messages-client.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { ENDPOINT_CONVERSATION_MESSAGES } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { ConversationMessageSchema, StatusOkSchema, } from '../types/entities.js';
+import { ConversationMessageSchema, createConversationMessageSchema, StatusOkSchema, } from '../types/entities.js';
 import { resolveCreateId } from '../utils/uuidv7.js';
 import { BaseClient } from './base-client.js';
 export const ConversationMessageListSchema = z.array(ConversationMessageSchema);
@@ -10,7 +10,36 @@ export const ConversationMessageListSchema = z.array(ConversationMessageSchema);
  * message `id` on `createMessage` when the caller doesn't supply one.
  */
 export class ConversationMessagesClient extends BaseClient {
-    /** Lists messages in a conversation. */
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.messageSchema = this.linkBaseUrl
+            ? createConversationMessageSchema(this.linkBaseUrl)
+            : ConversationMessageSchema;
+        this.messageListSchema = this.linkBaseUrl
+            ? z.array(this.messageSchema)
+            : ConversationMessageListSchema;
+    }
+    /**
+     * Gets all messages in a conversation.
+     *
+     * @param args - The arguments for getting messages.
+     * @param args.conversationId - The conversation ID.
+     * @param args.newerThan - Optional date to get messages newer than.
+     * @param args.olderThan - Optional date to get messages older than.
+     * @param args.limit - Optional limit on number of messages returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns An array of message objects.
+     *
+     * @example
+     * ```typescript
+     * const messages = await api.conversationMessages.getMessages({
+     *   conversationId: '7YpL3oZ4kZ9vP7Q1tR2sX42',
+     *   newerThan: new Date('2024-01-01'),
+     * })
+     * ```
+     */
     getMessages(args) {
         const params = { conversationId: args.conversationId };
         if (args.newerThan)
@@ -28,13 +57,41 @@ export class ConversationMessagesClient extends BaseClient {
             apiToken: this.apiToken,
             payload: params,
             customFetch: this.customFetch,
-        }).then((response) => ConversationMessageListSchema.parse(response.data));
+        }).then((response) => this.messageListSchema.parse(response.data));
     }
-    /** Fetches a single message by ID. */
+    /**
+     * Gets a single conversation message by id.
+     *
+     * @param id - The message ID.
+     * @returns The conversation message object.
+     *
+     * @example
+     * ```typescript
+     * const message = await api.conversationMessages.getMessage('7YpL3oZ4kZ9vP7Q1tR2sX43')
+     * ```
+     */
     getMessage(id) {
-        return this.simple('GET', 'getone', { id }, ConversationMessageSchema);
+        return this.simple('GET', 'getone', { id }, this.messageSchema);
     }
-    /** Creates a new message. `id` is auto-generated if not supplied. */
+    /**
+     * Creates a new message in a conversation. `id` is auto-generated if not
+     * supplied.
+     *
+     * @param args - The arguments for creating a message.
+     * @param args.conversationId - The conversation ID.
+     * @param args.content - The message content.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @param args.actions - Optional array of action objects.
+     * @returns The created message object.
+     *
+     * @example
+     * ```typescript
+     * const message = await api.conversationMessages.createMessage({
+     *   conversationId: '7YpL3oZ4kZ9vP7Q1tR2sX42',
+     *   content: 'Thanks for the update!',
+     * })
+     * ```
+     */
     createMessage(args) {
         const params = {
             conversationId: args.conversationId,
@@ -51,9 +108,25 @@ export class ConversationMessagesClient extends BaseClient {
             params.directGroupMentions = args.directGroupMentions;
         if (args.notify !== undefined)
             params.notify = args.notify;
-        return this.simple('POST', 'add', params, ConversationMessageSchema);
+        return this.simple('POST', 'add', params, this.messageSchema);
     }
-    /** Updates a message. */
+    /**
+     * Updates a conversation message.
+     *
+     * @param args - The arguments for updating a message.
+     * @param args.id - The message ID.
+     * @param args.content - The new message content.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @returns The updated message object.
+     *
+     * @example
+     * ```typescript
+     * const message = await api.conversationMessages.updateMessage({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX43',
+     *   content: 'Updated message content',
+     * })
+     * ```
+     */
     updateMessage(args) {
         const params = { id: args.id, content: args.content };
         if (args.attachments)
@@ -64,9 +137,18 @@ export class ConversationMessagesClient extends BaseClient {
             params.directMentions = args.directMentions;
         if (args.directGroupMentions)
             params.directGroupMentions = args.directGroupMentions;
-        return this.simple('POST', 'update', params, ConversationMessageSchema);
+        return this.simple('POST', 'update', params, this.messageSchema);
     }
-    /** Permanently deletes a message. */
+    /**
+     * Permanently deletes a conversation message.
+     *
+     * @param id - The message ID.
+     *
+     * @example
+     * ```typescript
+     * await api.conversationMessages.deleteMessage('7YpL3oZ4kZ9vP7Q1tR2sX43')
+     * ```
+     */
     deleteMessage(id) {
         return this.simple('POST', 'remove', { id }, StatusOkSchema);
     }

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { ENDPOINT_CONVERSATIONS } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { ConversationSchema, StatusOkSchema, UnreadConversationSchema, } from '../types/entities.js';
+import { ConversationSchema, createConversationSchema, StatusOkSchema, UnreadConversationSchema, } from '../types/entities.js';
 import { resolveCreateId } from '../utils/uuidv7.js';
 import { BaseClient } from './base-client.js';
 export const ConversationListSchema = z.array(ConversationSchema);
@@ -16,7 +16,31 @@ const GetUnreadResponseSchema = z.object({
  * already-assigned `id` and your generated one is silently dropped.
  */
 export class ConversationsClient extends BaseClient {
-    /** Lists conversations in a workspace. */
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.conversationSchema = this.linkBaseUrl
+            ? createConversationSchema(this.linkBaseUrl)
+            : ConversationSchema;
+        this.conversationListSchema = this.linkBaseUrl
+            ? z.array(this.conversationSchema)
+            : ConversationListSchema;
+    }
+    /**
+     * Gets all conversations for a workspace.
+     *
+     * @param args - The arguments for getting conversations.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.archived - Optional flag to include archived conversations.
+     * @returns An array of conversation objects.
+     *
+     * @example
+     * ```typescript
+     * const conversations = await api.conversations.getConversations({ workspaceId: 123 })
+     * conversations.forEach(c => console.log(c.title))
+     * ```
+     */
     getConversations(args) {
         return request({
             httpMethod: 'GET',
@@ -25,66 +49,193 @@ export class ConversationsClient extends BaseClient {
             apiToken: this.apiToken,
             payload: args,
             customFetch: this.customFetch,
-        }).then((response) => ConversationListSchema.parse(response.data));
+        }).then((response) => this.conversationListSchema.parse(response.data));
     }
-    /** Fetches a single conversation by ID. */
+    /**
+     * Gets a single conversation object by id.
+     *
+     * @param id - The conversation ID.
+     * @returns The conversation object.
+     */
     getConversation(id) {
-        return this.simple('GET', 'getone', { id }, ConversationSchema);
+        return this.simple('GET', 'getone', { id }, this.conversationSchema);
     }
     /**
      * Gets an existing 1:1 / group conversation with `userIds`, or creates a
      * new one. `id` is auto-generated if not supplied — on dedupe, the
      * backend returns the existing conversation's `id` instead.
+     *
+     * @param args - The arguments for getting or creating a conversation.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userIds - Array of user IDs to include in the conversation.
+     * @returns The conversation object (existing or newly created).
+     *
+     * @example
+     * ```typescript
+     * const conversation = await api.conversations.getOrCreateConversation({
+     *   workspaceId: 123,
+     *   userIds: [101, 202, 303],
+     * })
+     * ```
      */
     getOrCreateConversation(args) {
-        return this.simple('GET', 'get_or_create', { ...args, id: resolveCreateId(args.id) }, ConversationSchema);
+        return this.simple('GET', 'get_or_create', { ...args, id: resolveCreateId(args.id) }, this.conversationSchema);
     }
-    /** Updates a conversation's title. */
+    /**
+     * Updates a conversation's title.
+     *
+     * @param args - The arguments for updating a conversation.
+     * @param args.id - The conversation ID.
+     * @param args.title - The new title for the conversation.
+     * @param args.archived - Optional flag to archive/unarchive the conversation.
+     * @returns The updated conversation object.
+     *
+     * @example
+     * ```typescript
+     * const conversation = await api.conversations.updateConversation({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX42',
+     *   title: 'New Title',
+     * })
+     * ```
+     */
     updateConversation(args) {
         const params = { id: args.id, title: args.title };
         if (args.archived !== undefined)
             params.archived = args.archived;
-        return this.simple('POST', 'update', params, ConversationSchema);
+        return this.simple('POST', 'update', params, this.conversationSchema);
     }
+    /**
+     * Archives a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
     archiveConversation(id) {
-        return this.simple('GET', 'archive', { id }, ConversationSchema);
+        return this.simple('GET', 'archive', { id }, this.conversationSchema);
     }
+    /**
+     * Unarchives a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
     unarchiveConversation(id) {
-        return this.simple('GET', 'unarchive', { id }, ConversationSchema);
+        return this.simple('GET', 'unarchive', { id }, this.conversationSchema);
     }
+    /**
+     * Adds a user to a conversation.
+     *
+     * @param args - The arguments for adding a user.
+     * @param args.id - The conversation ID.
+     * @param args.userId - The user ID to add.
+     * @returns The updated conversation object.
+     */
     addUser(args) {
-        return this.simple('POST', 'add_user', { ...args }, ConversationSchema);
+        return this.simple('POST', 'add_user', { ...args }, this.conversationSchema);
     }
+    /**
+     * Adds multiple users to a conversation.
+     *
+     * @param args - The arguments for adding users.
+     * @param args.id - The conversation ID.
+     * @param args.userIds - Array of user IDs to add.
+     * @returns The updated conversation object.
+     *
+     * @example
+     * ```typescript
+     * await api.conversations.addUsers({ id: '7YpL3oZ4kZ9vP7Q1tR2sX42', userIds: [101, 202] })
+     * ```
+     */
     addUsers(args) {
-        return this.simple('POST', 'add_users', { ...args }, ConversationSchema);
+        return this.simple('POST', 'add_users', { ...args }, this.conversationSchema);
     }
+    /**
+     * Removes a user from a conversation.
+     *
+     * @param args - The arguments for removing a user.
+     * @param args.id - The conversation ID.
+     * @param args.userId - The user ID to remove.
+     * @returns The updated conversation object.
+     */
     removeUser(args) {
-        return this.simple('POST', 'remove_user', { ...args }, ConversationSchema);
+        return this.simple('POST', 'remove_user', { ...args }, this.conversationSchema);
     }
+    /**
+     * Removes multiple users from a conversation.
+     *
+     * @param args - The arguments for removing users.
+     * @param args.id - The conversation ID.
+     * @param args.userIds - Array of user IDs to remove.
+     * @returns The updated conversation object.
+     */
     removeUsers(args) {
-        return this.simple('POST', 'remove_users', { ...args }, ConversationSchema);
+        return this.simple('POST', 'remove_users', { ...args }, this.conversationSchema);
     }
+    /**
+     * Marks a conversation as read.
+     *
+     * @param args - The arguments for marking as read.
+     * @param args.id - The conversation ID.
+     * @param args.objIndex - Optional index of the message to mark as last read.
+     * @param args.messageId - Optional message ID to mark as last read.
+     */
     markRead(args) {
         return this.simple('POST', 'mark_read', { ...args }, StatusOkSchema);
     }
+    /**
+     * Marks a conversation as unread.
+     *
+     * @param args - The arguments for marking as unread.
+     * @param args.id - The conversation ID.
+     * @param args.objIndex - Optional index of the message to mark as last unread.
+     * @param args.messageId - Optional message ID to mark as last unread.
+     */
     markUnread(args) {
         return this.simple('POST', 'mark_unread', { ...args }, StatusOkSchema);
     }
     /**
      * Returns unread conversations for a workspace, paired with the unread
      * version counter.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns Object containing the array of unread conversation references and a version counter.
      */
     getUnread(workspaceId) {
         return this.simple('GET', 'get_unread', { workspaceId }, GetUnreadResponseSchema);
     }
+    /**
+     * Clears all unread conversations for a workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     */
     clearUnread(workspaceId) {
         return this.simple('GET', 'clear_unread', { workspaceId }, StatusOkSchema);
     }
+    /**
+     * Mutes a conversation for a specified number of minutes.
+     * The user will receive no notifications from this conversation during that period.
+     *
+     * @param args - The arguments for muting a conversation.
+     * @param args.id - The conversation ID.
+     * @param args.minutes - Number of minutes to mute the conversation.
+     * @returns The updated conversation object.
+     *
+     * @example
+     * ```typescript
+     * const conversation = await api.conversations.muteConversation({ id: '7YpL3oZ4kZ9vP7Q1tR2sX42', minutes: 30 })
+     * ```
+     */
     muteConversation(args) {
-        return this.simple('GET', 'mute', { ...args }, ConversationSchema);
+        return this.simple('GET', 'mute', { ...args }, this.conversationSchema);
     }
+    /**
+     * Unmutes a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
     unmuteConversation(id) {
-        return this.simple('GET', 'unmute', { id }, ConversationSchema);
+        return this.simple('GET', 'unmute', { id }, this.conversationSchema);
     }
     simple(httpMethod, suffix, params, schema) {
         return request({