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

package/README.md

@@ -1,4 +1,4 @@
-# Comms SDK (TypeScript)
+# Comms SDK TypeScript
 
 The official TypeScript SDK for the Comms REST API.
 

package/dist/cjs/clients/add-comment-helper.js

@@ -3,7 +3,6 @@ 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));
@@ -36,6 +35,23 @@ function applyNotifyAudience(params) {
     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) };
@@ -49,5 +65,5 @@ function addCommentRequest(context, params, options) {
         apiToken: context.apiToken,
         payload,
         customFetch: context.customFetch,
-    }).then((response) => entities_1.CommentSchema.parse(response.data));
+    }).then((response) => context.schema.parse(response.data));
 }

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

@@ -2,6 +2,7 @@
 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.
@@ -10,6 +11,7 @@ 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;
     }
     /**
@@ -17,11 +19,15 @@ class BaseClient {
      * slash so relative paths resolve cleanly through `URL`.
      */
     getBaseUri() {
-        if (this.baseUrl) {
-            const normalizedBaseUrl = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`;
-            return `${normalizedBaseUrl}api/v1/`;
-        }
-        return (0, endpoints_1.getCommsBaseUri)();
+        return (0, endpoints_1.getCommsBaseUri)(this.defaultVersion, this.baseUrl);
+    }
+    /**
+     * Base URL for entity web links, or `undefined` to use getFullCommsURL's
+     * default web app. Trailing-slash normalization happens in
+     * `getFullCommsURL`, so the configured value is returned verbatim.
+     */
+    getLinkBaseUrl() {
+        return this.baseUrl;
     }
 }
 exports.BaseClient = BaseClient;

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

@@ -14,7 +14,31 @@ exports.ChannelListSchema = zod_1.z.array(entities_1.ChannelSchema);
  * to keep an optimistic-UI ID stable through the round-trip.
  */
 class ChannelsClient extends base_client_1.BaseClient {
-    /** Lists channels in a workspace. */
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.channelSchema = this.linkBaseUrl
+            ? (0, entities_1.createChannelSchema)(this.linkBaseUrl)
+            : entities_1.ChannelSchema;
+        this.channelListSchema = this.linkBaseUrl
+            ? zod_1.z.array(this.channelSchema)
+            : exports.ChannelListSchema;
+    }
+    /**
+     * Gets all channels for a given workspace.
+     *
+     * @param args - The arguments for getting channels.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.archived - Optional flag to include archived channels.
+     * @returns An array of channel objects.
+     *
+     * @example
+     * ```typescript
+     * const channels = await api.channels.getChannels({ workspaceId: 123 })
+     * channels.forEach(ch => console.log(ch.name))
+     * ```
+     */
     getChannels(args) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -23,51 +47,155 @@ class ChannelsClient extends base_client_1.BaseClient {
             apiToken: this.apiToken,
             payload: args,
             customFetch: this.customFetch,
-        }).then((response) => exports.ChannelListSchema.parse(response.data));
+        }).then((response) => this.channelListSchema.parse(response.data));
     }
-    /** Fetches a single channel by ID. */
+    /**
+     * Gets a single channel object by id.
+     *
+     * @param id - The channel ID.
+     * @returns The channel object.
+     */
     getChannel(id) {
-        return this.simple('GET', 'getone', { id }, entities_1.ChannelSchema);
+        return this.simple('GET', 'getone', { id }, this.channelSchema);
     }
-    /** Creates a new channel. `id` is auto-generated if not supplied. */
+    /**
+     * Creates a new channel. `id` is auto-generated if not supplied — pass your
+     * own `id` to keep an optimistic-UI ID stable through the round-trip.
+     *
+     * @param args - The arguments for creating a channel.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.name - The channel name.
+     * @param args.description - Optional channel description.
+     * @param args.color - Optional channel color.
+     * @param args.userIds - Optional array of user IDs to add to the channel.
+     * @param args.public - Optional flag to make the channel public.
+     * @returns The created channel object.
+     *
+     * @example
+     * ```typescript
+     * const channel = await api.channels.createChannel({
+     *   workspaceId: 123,
+     *   name: 'Engineering',
+     *   description: 'Engineering team channel',
+     * })
+     * ```
+     */
     createChannel(args) {
-        return this.simple('POST', 'add', { ...args, id: (0, uuidv7_1.resolveCreateId)(args.id) }, entities_1.ChannelSchema);
+        return this.simple('POST', 'add', { ...args, id: (0, uuidv7_1.resolveCreateId)(args.id) }, this.channelSchema);
     }
-    /** Partial update of an existing channel. */
+    /**
+     * Partial update of an existing channel.
+     *
+     * @param args - The arguments for updating a channel.
+     * @param args.id - The channel ID.
+     * @param args.name - Optional new channel name.
+     * @param args.description - Optional new channel description.
+     * @param args.color - Optional new channel color.
+     * @param args.public - Optional flag to change channel visibility.
+     * @returns The updated channel object.
+     */
     updateChannel(args) {
-        return this.simple('POST', 'update', { ...args }, entities_1.ChannelSchema);
+        return this.simple('POST', 'update', { ...args }, this.channelSchema);
     }
-    /** Updates the channel's view filter (`only_open` / `all` / `only_closed`). */
+    /**
+     * Updates the channel's view filter (`only_open` / `all` / `only_closed`).
+     *
+     * @param args - The arguments for updating the channel filter.
+     * @param args.id - The channel ID.
+     * @param args.filterClosed - The new filter value.
+     */
     updateFilters(args) {
         return this.simple('POST', 'update_filters', { ...args }, entities_1.StatusOkSchema);
     }
-    /** Permanently deletes a channel. */
+    /**
+     * Permanently deletes a channel.
+     *
+     * @param id - The channel ID.
+     */
     deleteChannel(id) {
         return this.simple('POST', 'remove', { id }, entities_1.StatusOkSchema);
     }
+    /**
+     * Archives a channel.
+     *
+     * @param id - The channel ID.
+     */
     archiveChannel(id) {
         return this.simple('POST', 'archive', { id }, entities_1.StatusOkSchema);
     }
+    /**
+     * Unarchives a channel.
+     *
+     * @param id - The channel ID.
+     */
     unarchiveChannel(id) {
         return this.simple('POST', 'unarchive', { id }, entities_1.StatusOkSchema);
     }
+    /**
+     * Favorites a channel.
+     *
+     * @param id - The channel ID.
+     */
     favoriteChannel(id) {
         return this.simple('POST', 'favorite', { id }, entities_1.StatusOkSchema);
     }
+    /**
+     * Unfavorites a channel.
+     *
+     * @param id - The channel ID.
+     */
     unfavoriteChannel(id) {
         return this.simple('POST', 'unfavorite', { id }, entities_1.StatusOkSchema);
     }
+    /**
+     * Adds a user to a channel.
+     *
+     * @param args - The arguments for adding a user.
+     * @param args.id - The channel ID.
+     * @param args.userId - The user ID to add.
+     *
+     * @example
+     * ```typescript
+     * await api.channels.addUser({ id: '7YpL3oZ4kZ9vP7Q1tR2sX44', userId: 101 })
+     * ```
+     */
     addUser(args) {
-        return this.simple('POST', 'add_user', { ...args }, entities_1.ChannelSchema);
+        return this.simple('POST', 'add_user', { ...args }, this.channelSchema);
     }
+    /**
+     * Adds multiple users to a channel.
+     *
+     * @param args - The arguments for adding users.
+     * @param args.id - The channel ID.
+     * @param args.userIds - Array of user IDs to add.
+     *
+     * @example
+     * ```typescript
+     * await api.channels.addUsers({ id: '7YpL3oZ4kZ9vP7Q1tR2sX44', userIds: [101, 202] })
+     * ```
+     */
     addUsers(args) {
-        return this.simple('POST', 'add_users', { ...args }, entities_1.ChannelSchema);
+        return this.simple('POST', 'add_users', { ...args }, this.channelSchema);
     }
+    /**
+     * Removes a user from a channel.
+     *
+     * @param args - The arguments for removing a user.
+     * @param args.id - The channel ID.
+     * @param args.userId - The user ID to remove.
+     */
     removeUser(args) {
-        return this.simple('POST', 'remove_user', { ...args }, entities_1.ChannelSchema);
+        return this.simple('POST', 'remove_user', { ...args }, this.channelSchema);
     }
+    /**
+     * Removes multiple users from a channel.
+     *
+     * @param args - The arguments for removing users.
+     * @param args.id - The channel ID.
+     * @param args.userIds - Array of user IDs to remove.
+     */
     removeUsers(args) {
-        return this.simple('POST', 'remove_users', { ...args }, entities_1.ChannelSchema);
+        return this.simple('POST', 'remove_users', { ...args }, this.channelSchema);
     }
     simple(httpMethod, suffix, params, schema) {
         return (0, http_client_1.request)({

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

@@ -13,16 +13,46 @@ exports.CommentListSchema = zod_1.z.array(entities_1.CommentSchema);
  * on `createComment` when the caller doesn't supply one.
  */
 class CommentsClient extends base_client_1.BaseClient {
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singletons when no custom base is configured.
+        this.commentSchema = this.linkBaseUrl
+            ? (0, entities_1.createCommentSchema)(this.linkBaseUrl)
+            : entities_1.CommentSchema;
+        this.commentListSchema = this.linkBaseUrl
+            ? zod_1.z.array(this.commentSchema)
+            : exports.CommentListSchema;
+        // `getone` wraps the comment in `{ comment: ... }`; built once per client.
+        this.wrappedCommentSchema = zod_1.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)
@@ -34,11 +64,15 @@ class CommentsClient extends base_client_1.BaseClient {
             apiToken: this.apiToken,
             payload: params,
             customFetch: this.customFetch,
-        }).then((response) => exports.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 = zod_1.z.object({ comment: entities_1.CommentSchema }).transform((data) => data.comment);
         return (0, http_client_1.request)({
             httpMethod: 'GET',
             baseUri: this.getBaseUri(),
@@ -46,15 +80,51 @@ class CommentsClient extends base_client_1.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 (0, add_comment_helper_1.addCommentRequest)({ baseUri: this.getBaseUri(), apiToken: this.apiToken, customFetch: this.customFetch }, args);
+        return (0, add_comment_helper_1.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 (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -63,9 +133,13 @@ class CommentsClient extends base_client_1.BaseClient {
             apiToken: this.apiToken,
             payload: { ...args },
             customFetch: this.customFetch,
-        }).then((response) => entities_1.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 (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -77,7 +151,18 @@ class CommentsClient extends base_client_1.BaseClient {
         }).then((response) => entities_1.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 (0, http_client_1.request)({

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

@@ -13,7 +13,36 @@ exports.ConversationMessageListSchema = zod_1.z.array(entities_1.ConversationMes
  * message `id` on `createMessage` when the caller doesn't supply one.
  */
 class ConversationMessagesClient extends base_client_1.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
+            ? (0, entities_1.createConversationMessageSchema)(this.linkBaseUrl)
+            : entities_1.ConversationMessageSchema;
+        this.messageListSchema = this.linkBaseUrl
+            ? zod_1.z.array(this.messageSchema)
+            : exports.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)
@@ -31,13 +60,41 @@ class ConversationMessagesClient extends base_client_1.BaseClient {
             apiToken: this.apiToken,
             payload: params,
             customFetch: this.customFetch,
-        }).then((response) => exports.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 }, entities_1.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,
@@ -54,9 +111,25 @@ class ConversationMessagesClient extends base_client_1.BaseClient {
             params.directGroupMentions = args.directGroupMentions;
         if (args.notify !== undefined)
             params.notify = args.notify;
-        return this.simple('POST', 'add', params, entities_1.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)
@@ -67,9 +140,18 @@ class ConversationMessagesClient extends base_client_1.BaseClient {
             params.directMentions = args.directMentions;
         if (args.directGroupMentions)
             params.directGroupMentions = args.directGroupMentions;
-        return this.simple('POST', 'update', params, entities_1.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 }, entities_1.StatusOkSchema);
     }