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

package/dist/esm/utils/url-helpers.js

@@ -45,7 +45,9 @@ export function getCommsURL(params) {
  * @param baseUrl - Optional base URL (defaults to 'https://comms.todoist.com')
  */
 export function getFullCommsURL(params, baseUrl = COMMS_BASE_URL) {
-    return `${baseUrl}${getCommsURL(params)}`;
+    // Strip a trailing slash so links don't double up — `getCommsURL` paths start with '/'.
+    const normalizedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    return `${normalizedBase}${getCommsURL(params)}`;
 }
 /** Returns the URL for a thread in a channel. */
 export function getThreadURL(params) {

package/dist/types/clients/add-comment-helper.d.ts

@@ -1,11 +1,30 @@
-import { type Comment } from '../types/entities.js';
+import { type Comment, type createCommentSchema } from '../types/entities.js';
 import type { CustomFetch } from '../types/http.js';
 import type { CreateCommentArgs, ThreadAction } from '../types/requests.js';
 type ClientContext = {
     baseUri: string;
     apiToken: string;
     customFetch?: CustomFetch;
+    /** Per-client Comment schema, base-bound for the returned comment's web `url`. */
+    schema: ReturnType<typeof createCommentSchema>;
 };
+/**
+ * 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.
+ */
 export declare function addCommentRequest(context: ClientContext, params: CreateCommentArgs, options?: {
     threadAction?: ThreadAction;
 }): Promise<Comment>;

package/dist/types/clients/base-client.d.ts

@@ -1,9 +1,12 @@
+import type { ApiVersion } from '../types/api-version.js';
 import type { CustomFetch } from '../types/http.js';
 export type ClientConfig = {
     /** API token for authentication */
     apiToken: string;
     /** Optional custom base URL. If not provided, uses the default Comms API URL */
     baseUrl?: string;
+    /** Optional API version. Defaults to 'v1' */
+    version?: ApiVersion;
     /** Optional custom fetch implementation for cross-platform compatibility */
     customFetch?: CustomFetch;
 };
@@ -14,6 +17,7 @@ export type ClientConfig = {
 export declare class BaseClient {
     protected readonly apiToken: string;
     protected readonly baseUrl?: string;
+    protected readonly defaultVersion: ApiVersion;
     protected readonly customFetch?: CustomFetch;
     constructor(config: ClientConfig);
     /**
@@ -21,4 +25,10 @@ export declare class BaseClient {
      * slash so relative paths resolve cleanly through `URL`.
      */
     protected getBaseUri(): string;
+    /**
+     * 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.
+     */
+    protected getLinkBaseUrl(): string | undefined;
 }

package/dist/types/clients/channels-client.d.ts

@@ -64,28 +64,148 @@ export declare const ChannelListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
  * to keep an optimistic-UI ID stable through the round-trip.
  */
 export declare class ChannelsClient extends BaseClient {
-    /** Lists channels in a workspace. */
+    private readonly linkBaseUrl;
+    private readonly channelSchema;
+    private readonly 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: GetChannelsArgs): Promise<Channel[]>;
-    /** Fetches a single channel by ID. */
+    /**
+     * Gets a single channel object by id.
+     *
+     * @param id - The channel ID.
+     * @returns The channel object.
+     */
     getChannel(id: string): Promise<Channel>;
-    /** 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: CreateChannelArgs): Promise<Channel>;
-    /** 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: UpdateChannelArgs): Promise<Channel>;
-    /** 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: {
         id: string;
         filterClosed: 'only_open' | 'all' | 'only_closed';
     }): Promise<StatusOk>;
-    /** Permanently deletes a channel. */
+    /**
+     * Permanently deletes a channel.
+     *
+     * @param id - The channel ID.
+     */
     deleteChannel(id: string): Promise<StatusOk>;
+    /**
+     * Archives a channel.
+     *
+     * @param id - The channel ID.
+     */
     archiveChannel(id: string): Promise<StatusOk>;
+    /**
+     * Unarchives a channel.
+     *
+     * @param id - The channel ID.
+     */
     unarchiveChannel(id: string): Promise<StatusOk>;
+    /**
+     * Favorites a channel.
+     *
+     * @param id - The channel ID.
+     */
     favoriteChannel(id: string): Promise<StatusOk>;
+    /**
+     * Unfavorites a channel.
+     *
+     * @param id - The channel ID.
+     */
     unfavoriteChannel(id: string): Promise<StatusOk>;
+    /**
+     * 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: AddChannelUserArgs): Promise<Channel>;
+    /**
+     * 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: AddChannelUsersArgs): Promise<Channel>;
+    /**
+     * 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: RemoveChannelUserArgs): Promise<Channel>;
+    /**
+     * 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: RemoveChannelUsersArgs): Promise<Channel>;
     private simple;
 }

package/dist/types/clients/comments-client.d.ts

@@ -134,24 +134,95 @@ export declare const CommentListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
  * on `createComment` when the caller doesn't supply one.
  */
 export declare class CommentsClient extends BaseClient {
+    private readonly linkBaseUrl;
+    private readonly commentSchema;
+    private readonly commentListSchema;
+    private readonly wrappedCommentSchema;
     /**
-     * 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: GetCommentsArgs): Promise<Comment[]>;
-    /** 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: string): Promise<Comment>;
     /**
-     * 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: CreateCommentArgs): Promise<Comment>;
-    /** 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: UpdateCommentArgs): Promise<Comment>;
-    /** Permanently deletes a comment. */
+    /**
+     * Permanently deletes a comment.
+     *
+     * @param id - The comment ID.
+     */
     deleteComment(id: string): Promise<StatusOk>;
     /**
-     * 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: MarkCommentPositionArgs): Promise<StatusOk>;
 }

package/dist/types/clients/conversation-messages-client.d.ts

@@ -113,15 +113,89 @@ export declare const ConversationMessageListSchema: z.ZodArray<z.ZodPipe<z.ZodOb
  * message `id` on `createMessage` when the caller doesn't supply one.
  */
 export declare class ConversationMessagesClient extends BaseClient {
-    /** Lists messages in a conversation. */
+    private readonly linkBaseUrl;
+    private readonly messageSchema;
+    private readonly messageListSchema;
+    /**
+     * 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: GetConversationMessagesArgs): Promise<ConversationMessage[]>;
-    /** 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: string): Promise<ConversationMessage>;
-    /** 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: CreateConversationMessageArgs): Promise<ConversationMessage>;
-    /** 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: UpdateConversationMessageArgs): Promise<ConversationMessage>;
-    /** Permanently deletes a message. */
+    /**
+     * Permanently deletes a conversation message.
+     *
+     * @param id - The message ID.
+     *
+     * @example
+     * ```typescript
+     * await api.conversationMessages.deleteMessage('7YpL3oZ4kZ9vP7Q1tR2sX43')
+     * ```
+     */
     deleteMessage(id: string): Promise<StatusOk>;
     private simple;
 }

package/dist/types/clients/conversations-client.d.ts

@@ -163,29 +163,144 @@ export declare const ConversationListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
  * already-assigned `id` and your generated one is silently dropped.
  */
 export declare class ConversationsClient extends BaseClient {
-    /** Lists conversations in a workspace. */
+    private readonly linkBaseUrl;
+    private readonly conversationSchema;
+    private readonly 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: GetConversationsArgs): Promise<Conversation[]>;
-    /** Fetches a single conversation by ID. */
+    /**
+     * Gets a single conversation object by id.
+     *
+     * @param id - The conversation ID.
+     * @returns The conversation object.
+     */
     getConversation(id: string): Promise<Conversation>;
     /**
      * 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: GetOrCreateConversationArgs): Promise<Conversation>;
-    /** 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: UpdateConversationArgs): Promise<Conversation>;
+    /**
+     * Archives a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
     archiveConversation(id: string): Promise<Conversation>;
+    /**
+     * Unarchives a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
     unarchiveConversation(id: string): Promise<Conversation>;
+    /**
+     * 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: AddConversationUserArgs): Promise<Conversation>;
+    /**
+     * 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: AddConversationUsersArgs): Promise<Conversation>;
+    /**
+     * 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: RemoveConversationUserArgs): Promise<Conversation>;
+    /**
+     * 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: RemoveConversationUsersArgs): Promise<Conversation>;
+    /**
+     * 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: {
         id: string;
         objIndex?: number;
         messageId?: string;
     }): Promise<StatusOk>;
+    /**
+     * 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: {
         id: string;
         objIndex?: number;
@@ -194,13 +309,41 @@ export declare class ConversationsClient extends BaseClient {
     /**
      * 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: number): Promise<{
         data: UnreadConversation[];
         version: number;
     }>;
+    /**
+     * Clears all unread conversations for a workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     */
     clearUnread(workspaceId: number): Promise<StatusOk>;
+    /**
+     * 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: MuteConversationArgs): Promise<Conversation>;
+    /**
+     * Unmutes a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
     unmuteConversation(id: string): Promise<Conversation>;
     private simple;
 }