@doist/comms-sdk 0.0.1 → 0.2.0

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

@@ -0,0 +1,239 @@
+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 { resolveCreateId } from '../utils/uuidv7.js';
+import { BaseClient } from './base-client.js';
+export const ConversationListSchema = z.array(ConversationSchema);
+const GetUnreadResponseSchema = z.object({
+    data: z.array(UnreadConversationSchema),
+    version: z.number().int(),
+});
+/**
+ * Client for `/api/v1/conversations/`. `getOrCreate` requires an `id` (the
+ * SDK auto-generates one for new conversations); the backend dedupes on
+ * `userIds`, so an existing conversation will be returned with its own
+ * already-assigned `id` and your generated one is silently dropped.
+ */
+export class ConversationsClient extends BaseClient {
+    /**
+     * 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',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_CONVERSATIONS}/get`,
+            apiToken: this.apiToken,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then((response) => ConversationListSchema.parse(response.data));
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Archives a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
+    archiveConversation(id) {
+        return this.simple('GET', 'archive', { id }, ConversationSchema);
+    }
+    /**
+     * Unarchives a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
+    unarchiveConversation(id) {
+        return this.simple('GET', 'unarchive', { id }, 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);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Unmutes a conversation.
+     *
+     * @param id - The conversation ID.
+     * @returns The updated conversation object.
+     */
+    unmuteConversation(id) {
+        return this.simple('GET', 'unmute', { id }, ConversationSchema);
+    }
+    simple(httpMethod, suffix, params, schema) {
+        return request({
+            httpMethod,
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_CONVERSATIONS}/${suffix}`,
+            apiToken: this.apiToken,
+            payload: params,
+            customFetch: this.customFetch,
+        }).then((response) => schema.parse(response.data));
+    }
+}

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

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { ENDPOINT_GROUPS } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
+import { GroupSchema, StatusOkSchema } from '../types/entities.js';
+import { resolveCreateId } from '../utils/uuidv7.js';
+import { BaseClient } from './base-client.js';
+export const GroupListSchema = z.array(GroupSchema);
+/**
+ * Client for `/api/v1/groups/`. The broadcast markers `EVERYONE` /
+ * `EVERYONE_IN_THREAD` are NOT addressable through these endpoints — they
+ * only appear as members of `direct_group_mentions` / `groups` lists on
+ * thread/comment writes.
+ *
+ * `getone` / `update` / `remove` and the member-management ops all require
+ * `workspace_id` alongside the group `id`.
+ */
+export class GroupsClient extends BaseClient {
+    /**
+     * 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',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_GROUPS}/get`,
+            apiToken: this.apiToken,
+            payload: { workspaceId },
+            customFetch: this.customFetch,
+        }).then((response) => GroupListSchema.parse(response.data));
+    }
+    /**
+     * 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.
+     *
+     * @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'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`.
+     *
+     * @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);
+    }
+    simple(httpMethod, suffix, params, schema) {
+        return request({
+            httpMethod,
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_GROUPS}/${suffix}`,
+            apiToken: this.apiToken,
+            payload: params,
+            customFetch: this.customFetch,
+        }).then((response) => schema.parse(response.data));
+    }
+}

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

@@ -0,0 +1,167 @@
+import { ENDPOINT_INBOX } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
+import { InboxThreadSchema } from '../types/entities.js';
+import { BaseClient } from './base-client.js';
+/** Client for `/api/v1/inbox/`. */
+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 };
+        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)
+            params.cursor = args.cursor;
+        if (args.archiveFilter)
+            params.archive_filter = args.archiveFilter;
+        return request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_INBOX}/get`,
+            apiToken: this.apiToken,
+            payload: params,
+            customFetch: this.customFetch,
+        }).then((response) => response.data.map((thread) => InboxThreadSchema.parse(thread)));
+    }
+    /**
+     * 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',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_INBOX}/get_count`,
+            apiToken: this.apiToken,
+            payload: { workspace_id: workspaceId },
+            customFetch: this.customFetch,
+        }).then((response) => response.data.data);
+    }
+    /**
+     * Archives a thread in the inbox.
+     *
+     * @param id - The thread ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.archiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
+     * ```
+     */
+    archiveThread(id) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_INBOX}/archive`,
+            apiToken: this.apiToken,
+            payload: { id },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * Unarchives a thread in the inbox.
+     *
+     * @param id - The thread ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.unarchiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
+     * ```
+     */
+    unarchiveThread(id) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_INBOX}/unarchive`,
+            apiToken: this.apiToken,
+            payload: { id },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * 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',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_INBOX}/mark_all_read`,
+            apiToken: this.apiToken,
+            payload: { workspace_id: workspaceId },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * 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;
+        if (args.olderThan)
+            params.older_than_ts = Math.floor(args.olderThan.getTime() / 1000);
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_INBOX}/archive_all`,
+            apiToken: this.apiToken,
+            payload: params,
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+}

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

@@ -0,0 +1,93 @@
+import { ENDPOINT_REACTIONS } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
+import { BaseClient } from './base-client.js';
+function reactionTarget(args) {
+    if (args.threadId)
+        return { threadId: args.threadId };
+    if (args.commentId)
+        return { commentId: args.commentId };
+    if (args.messageId)
+        return { messageId: args.messageId };
+    throw new Error('Must provide one of: threadId, commentId, or messageId');
+}
+/**
+ * Client for interacting with Comms reaction endpoints.
+ */
+export class ReactionsClient extends BaseClient {
+    /**
+     * 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',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_REACTIONS}/add`,
+            apiToken: this.apiToken,
+            payload: { ...reactionTarget(args), reaction: args.reaction },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * Gets reactions for a thread, comment, or conversation message.
+     *
+     * 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({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_REACTIONS}/get`,
+            apiToken: this.apiToken,
+            payload: reactionTarget(args),
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /**
+     * 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',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_REACTIONS}/remove`,
+            apiToken: this.apiToken,
+            payload: { ...reactionTarget(args), reaction: args.reaction },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+}