@doist/comms-sdk 0.10.0 → 0.11.1

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

@@ -24,7 +24,11 @@ const notify_audience_1 = require("./notify-audience");
  */
 function addCommentRequest(context, params, options) {
     const normalized = (0, notify_audience_1.applyNotifyAudience)(params);
-    const withId = { ...normalized, id: (0, uuidv7_1.resolveCreateId)(normalized.id) };
+    const withId = {
+        ...normalized,
+        id: (0, uuidv7_1.resolveCreateId)(normalized.id),
+        threadId: (0, uuidv7_1.resolveReferenceId)(normalized.threadId, 'threadId'),
+    };
     const payload = options?.threadAction
         ? { ...withId, threadAction: options.threadAction }
         : withId;

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

@@ -31,26 +31,55 @@ class ConversationsClient extends base_client_1.BaseClient {
             : exports.ConversationListSchema;
     }
     /**
-     * Gets all conversations for a workspace.
+     * Gets a page of conversations for a workspace, newest activity first.
+     * The server returns at most 500 rows per request (20 by default); pass
+     * the last row's `lastActive`/`id` as `olderThan`/`beforeId` to fetch
+     * the next page. Paired, they form a strict compound boundary, so pages
+     * never repeat rows. Omitting `archived` returns active and archived
+     * conversations mixed.
      *
      * @param args - The arguments for getting conversations.
      * @param args.workspaceId - The workspace ID.
-     * @param args.archived - Optional flag to include archived conversations.
+     * @param args.archived - Optional flag to filter archived (true) or active (false) conversations.
+     * @param args.olderThan - Optional date to get conversations last active before.
+     * @param args.beforeId - Optional conversation id. Paired with olderThan it forms the
+     *   strict compound cursor; alone it pages by conversation id order instead.
+     * @param args.limit - Optional page size (server default 20, max 500).
      * @returns An array of conversation objects.
      *
      * @example
      * ```typescript
-     * const conversations = await api.conversations.getConversations({ workspaceId: 123 })
-     * conversations.forEach(c => console.log(c.title))
+     * const page = await api.conversations.getConversations({ workspaceId: 123, limit: 500 })
+     * const last = page.at(-1)
+     * const nextPage = last
+     *     ? await api.conversations.getConversations({
+     *           workspaceId: 123,
+     *           limit: 500,
+     *           olderThan: last.lastActive,
+     *           beforeId: last.id,
+     *       })
+     *     : []
      * ```
      */
     getConversations(args) {
+        // Fields are picked explicitly (matching getThreads/getComments) so a
+        // future Date field can't silently reach the generic snake-casing,
+        // which would turn it into an empty object on the wire.
+        const params = { workspaceId: args.workspaceId };
+        if (args.archived != null)
+            params.archived = args.archived;
+        if (args.olderThan)
+            params.olderThanTs = Math.floor(args.olderThan.getTime() / 1000);
+        if (args.beforeId != null)
+            params.beforeId = args.beforeId;
+        if (args.limit != null)
+            params.limit = args.limit;
         return (0, http_client_1.request)({
             httpMethod: 'GET',
             baseUri: this.getBaseUri(),
             relativePath: `${endpoints_1.ENDPOINT_CONVERSATIONS}/get`,
             apiToken: this.apiToken,
-            payload: args,
+            payload: params,
             customFetch: this.customFetch,
         }).then((response) => this.conversationListSchema.parse(response.data));
     }

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

@@ -116,7 +116,11 @@ class ThreadsClient extends base_client_1.BaseClient {
      */
     createThread(args) {
         const normalized = (0, notify_audience_1.applyNotifyAudience)(args);
-        return this.simple('POST', 'add', { ...normalized, id: (0, uuidv7_1.resolveCreateId)(args.id) }, this.threadSchema);
+        return this.simple('POST', 'add', {
+            ...normalized,
+            id: (0, uuidv7_1.resolveCreateId)(normalized.id),
+            channelId: (0, uuidv7_1.resolveReferenceId)(normalized.channelId, 'channelId'),
+        }, this.threadSchema);
     }
     /**
      * Partial update of an existing thread.
@@ -344,7 +348,7 @@ class ThreadsClient extends base_client_1.BaseClient {
             apiToken: this.apiToken,
             customFetch: this.customFetch,
             schema: this.commentSchema,
-        }, { threadId: id, ...rest }, { threadAction });
+        }, { threadId: (0, uuidv7_1.resolveReferenceId)(id, 'id'), ...rest }, { threadAction });
     }
     simple(httpMethod, suffix, params, schema) {
         return (0, http_client_1.request)({

package/dist/cjs/testUtils/test-defaults.js

@@ -4,9 +4,11 @@ exports.mockWorkspaceUser = exports.mockComment = exports.mockConversation = exp
 const endpoints_1 = require("../consts/endpoints");
 exports.TEST_API_TOKEN = 'test-api-token';
 exports.TEST_API_BASE_URL = (0, endpoints_1.getCommsBaseUri)().replace(/\/$/, '');
-// Canonical test IDs — shaped so they pass SDK-side validation.
-exports.TEST_CHANNEL_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3y';
-exports.TEST_THREAD_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3z';
+// Stable test IDs. TEST_CHANNEL_ID and TEST_THREAD_ID are base58
+// UUIDv7-shaped because create-thread and add-comment paths validate them
+// SDK-side.
+exports.TEST_CHANNEL_ID = 'CQ7yksHFbYFrSPVTaHVCs';
+exports.TEST_THREAD_ID = 'CQ7yksHFbYFrSPVTaHVCt';
 exports.TEST_COMMENT_ID = '7YpL3oZ4kZ9vP7Q1tR2sX41';
 exports.TEST_CONVERSATION_ID = '7YpL3oZ4kZ9vP7Q1tR2sX42';
 exports.TEST_MESSAGE_ID = '7YpL3oZ4kZ9vP7Q1tR2sX43';

package/dist/cjs/types/requests.js

@@ -106,6 +106,9 @@ exports.GetCommentsArgsSchema = zod_1.z.object({
 exports.GetConversationsArgsSchema = zod_1.z.object({
     workspaceId: zod_1.z.number(),
     archived: zod_1.z.boolean().nullable().optional(),
+    olderThan: zod_1.z.date().nullable().optional(),
+    beforeId: zod_1.z.string().nullable().optional(),
+    limit: zod_1.z.number().nullable().optional(),
 });
 exports.GetOrCreateConversationArgsSchema = zod_1.z.object({
     workspaceId: zod_1.z.number(),

package/dist/cjs/utils/uuidv7.js

@@ -4,6 +4,7 @@ exports.UuidV7Error = void 0;
 exports.encodeUuidToBase58 = encodeUuidToBase58;
 exports.decodeBase58ToUuidBytes = decodeBase58ToUuidBytes;
 exports.generateId = generateId;
+exports.resolveReferenceId = resolveReferenceId;
 exports.resolveCreateId = resolveCreateId;
 exports.isValidUuidV7Base58 = isValidUuidV7Base58;
 exports.base58FromUuidString = base58FromUuidString;
@@ -112,6 +113,13 @@ function generateId() {
     const hex = (0, uuid_1.v7)().replace(/-/g, '');
     return encodeUuidToBase58(hexToBytes(hex));
 }
+/** Validate an existing entity ID without minting a replacement. */
+function resolveReferenceId(id, fieldName) {
+    if (!isValidUuidV7Base58(id)) {
+        throw new UuidV7Error(`invalid ${fieldName} ${JSON.stringify(id)} — use a base58 UUIDv7 value for \`${fieldName}\`.`);
+    }
+    return id;
+}
 /**
  * Resolve the `id` for a create-style API call: validate the caller-supplied
  * value (throwing {@link UuidV7Error} before the request leaves the SDK) or

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

@@ -1,6 +1,6 @@
 import { ENDPOINT_COMMENTS } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { resolveCreateId } from '../utils/uuidv7.js';
+import { resolveCreateId, resolveReferenceId } from '../utils/uuidv7.js';
 import { applyNotifyAudience } from './notify-audience.js';
 /**
  * Internal helper that powers `comments.createComment`,
@@ -21,7 +21,11 @@ import { applyNotifyAudience } from './notify-audience.js';
  */
 export function addCommentRequest(context, params, options) {
     const normalized = applyNotifyAudience(params);
-    const withId = { ...normalized, id: resolveCreateId(normalized.id) };
+    const withId = {
+        ...normalized,
+        id: resolveCreateId(normalized.id),
+        threadId: resolveReferenceId(normalized.threadId, 'threadId'),
+    };
     const payload = options?.threadAction
         ? { ...withId, threadAction: options.threadAction }
         : withId;

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

@@ -28,26 +28,55 @@ export class ConversationsClient extends BaseClient {
             : ConversationListSchema;
     }
     /**
-     * Gets all conversations for a workspace.
+     * Gets a page of conversations for a workspace, newest activity first.
+     * The server returns at most 500 rows per request (20 by default); pass
+     * the last row's `lastActive`/`id` as `olderThan`/`beforeId` to fetch
+     * the next page. Paired, they form a strict compound boundary, so pages
+     * never repeat rows. Omitting `archived` returns active and archived
+     * conversations mixed.
      *
      * @param args - The arguments for getting conversations.
      * @param args.workspaceId - The workspace ID.
-     * @param args.archived - Optional flag to include archived conversations.
+     * @param args.archived - Optional flag to filter archived (true) or active (false) conversations.
+     * @param args.olderThan - Optional date to get conversations last active before.
+     * @param args.beforeId - Optional conversation id. Paired with olderThan it forms the
+     *   strict compound cursor; alone it pages by conversation id order instead.
+     * @param args.limit - Optional page size (server default 20, max 500).
      * @returns An array of conversation objects.
      *
      * @example
      * ```typescript
-     * const conversations = await api.conversations.getConversations({ workspaceId: 123 })
-     * conversations.forEach(c => console.log(c.title))
+     * const page = await api.conversations.getConversations({ workspaceId: 123, limit: 500 })
+     * const last = page.at(-1)
+     * const nextPage = last
+     *     ? await api.conversations.getConversations({
+     *           workspaceId: 123,
+     *           limit: 500,
+     *           olderThan: last.lastActive,
+     *           beforeId: last.id,
+     *       })
+     *     : []
      * ```
      */
     getConversations(args) {
+        // Fields are picked explicitly (matching getThreads/getComments) so a
+        // future Date field can't silently reach the generic snake-casing,
+        // which would turn it into an empty object on the wire.
+        const params = { workspaceId: args.workspaceId };
+        if (args.archived != null)
+            params.archived = args.archived;
+        if (args.olderThan)
+            params.olderThanTs = Math.floor(args.olderThan.getTime() / 1000);
+        if (args.beforeId != null)
+            params.beforeId = args.beforeId;
+        if (args.limit != null)
+            params.limit = args.limit;
         return request({
             httpMethod: 'GET',
             baseUri: this.getBaseUri(),
             relativePath: `${ENDPOINT_CONVERSATIONS}/get`,
             apiToken: this.apiToken,
-            payload: args,
+            payload: params,
             customFetch: this.customFetch,
         }).then((response) => this.conversationListSchema.parse(response.data));
     }

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ENDPOINT_THREADS } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
 import { CommentSchema, createCommentSchema, createThreadSchema, StatusOkSchema, ThreadSchema, UnreadThreadSchema, } from '../types/entities.js';
-import { resolveCreateId } from '../utils/uuidv7.js';
+import { resolveCreateId, resolveReferenceId } from '../utils/uuidv7.js';
 import { addCommentRequest } from './add-comment-helper.js';
 import { BaseClient } from './base-client.js';
 import { applyNotifyAudience } from './notify-audience.js';
@@ -113,7 +113,11 @@ export class ThreadsClient extends BaseClient {
      */
     createThread(args) {
         const normalized = applyNotifyAudience(args);
-        return this.simple('POST', 'add', { ...normalized, id: resolveCreateId(args.id) }, this.threadSchema);
+        return this.simple('POST', 'add', {
+            ...normalized,
+            id: resolveCreateId(normalized.id),
+            channelId: resolveReferenceId(normalized.channelId, 'channelId'),
+        }, this.threadSchema);
     }
     /**
      * Partial update of an existing thread.
@@ -341,7 +345,7 @@ export class ThreadsClient extends BaseClient {
             apiToken: this.apiToken,
             customFetch: this.customFetch,
             schema: this.commentSchema,
-        }, { threadId: id, ...rest }, { threadAction });
+        }, { threadId: resolveReferenceId(id, 'id'), ...rest }, { threadAction });
     }
     simple(httpMethod, suffix, params, schema) {
         return request({

package/dist/esm/testUtils/test-defaults.js

@@ -1,9 +1,11 @@
 import { getCommsBaseUri } from '../consts/endpoints.js';
 export const TEST_API_TOKEN = 'test-api-token';
 export const TEST_API_BASE_URL = getCommsBaseUri().replace(/\/$/, '');
-// Canonical test IDs — shaped so they pass SDK-side validation.
-export const TEST_CHANNEL_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3y';
-export const TEST_THREAD_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3z';
+// Stable test IDs. TEST_CHANNEL_ID and TEST_THREAD_ID are base58
+// UUIDv7-shaped because create-thread and add-comment paths validate them
+// SDK-side.
+export const TEST_CHANNEL_ID = 'CQ7yksHFbYFrSPVTaHVCs';
+export const TEST_THREAD_ID = 'CQ7yksHFbYFrSPVTaHVCt';
 export const TEST_COMMENT_ID = '7YpL3oZ4kZ9vP7Q1tR2sX41';
 export const TEST_CONVERSATION_ID = '7YpL3oZ4kZ9vP7Q1tR2sX42';
 export const TEST_MESSAGE_ID = '7YpL3oZ4kZ9vP7Q1tR2sX43';

package/dist/esm/types/requests.js

@@ -103,6 +103,9 @@ export const GetCommentsArgsSchema = z.object({
 export const GetConversationsArgsSchema = z.object({
     workspaceId: z.number(),
     archived: z.boolean().nullable().optional(),
+    olderThan: z.date().nullable().optional(),
+    beforeId: z.string().nullable().optional(),
+    limit: z.number().nullable().optional(),
 });
 export const GetOrCreateConversationArgsSchema = z.object({
     workspaceId: z.number(),

package/dist/esm/utils/uuidv7.js

@@ -101,6 +101,13 @@ export function generateId() {
     const hex = uuidv7().replace(/-/g, '');
     return encodeUuidToBase58(hexToBytes(hex));
 }
+/** Validate an existing entity ID without minting a replacement. */
+export function resolveReferenceId(id, fieldName) {
+    if (!isValidUuidV7Base58(id)) {
+        throw new UuidV7Error(`invalid ${fieldName} ${JSON.stringify(id)} — use a base58 UUIDv7 value for \`${fieldName}\`.`);
+    }
+    return id;
+}
 /**
  * Resolve the `id` for a create-style API call: validate the caller-supplied
  * value (throwing {@link UuidV7Error} before the request leaves the SDK) or

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

@@ -167,17 +167,34 @@ export declare class ConversationsClient extends BaseClient {
     private readonly conversationSchema;
     private readonly conversationListSchema;
     /**
-     * Gets all conversations for a workspace.
+     * Gets a page of conversations for a workspace, newest activity first.
+     * The server returns at most 500 rows per request (20 by default); pass
+     * the last row's `lastActive`/`id` as `olderThan`/`beforeId` to fetch
+     * the next page. Paired, they form a strict compound boundary, so pages
+     * never repeat rows. Omitting `archived` returns active and archived
+     * conversations mixed.
      *
      * @param args - The arguments for getting conversations.
      * @param args.workspaceId - The workspace ID.
-     * @param args.archived - Optional flag to include archived conversations.
+     * @param args.archived - Optional flag to filter archived (true) or active (false) conversations.
+     * @param args.olderThan - Optional date to get conversations last active before.
+     * @param args.beforeId - Optional conversation id. Paired with olderThan it forms the
+     *   strict compound cursor; alone it pages by conversation id order instead.
+     * @param args.limit - Optional page size (server default 20, max 500).
      * @returns An array of conversation objects.
      *
      * @example
      * ```typescript
-     * const conversations = await api.conversations.getConversations({ workspaceId: 123 })
-     * conversations.forEach(c => console.log(c.title))
+     * const page = await api.conversations.getConversations({ workspaceId: 123, limit: 500 })
+     * const last = page.at(-1)
+     * const nextPage = last
+     *     ? await api.conversations.getConversations({
+     *           workspaceId: 123,
+     *           limit: 500,
+     *           olderThan: last.lastActive,
+     *           beforeId: last.id,
+     *       })
+     *     : []
      * ```
      */
     getConversations(args: GetConversationsArgs): Promise<Conversation[]>;

package/dist/types/testUtils/test-defaults.d.ts

@@ -1,8 +1,8 @@
 import type { Channel, Comment, Conversation, Group, Thread, User, Workspace, WorkspaceUser } from '../types/entities.js';
 export declare const TEST_API_TOKEN = "test-api-token";
 export declare const TEST_API_BASE_URL: string;
-export declare const TEST_CHANNEL_ID = "7YpL3oZ4kZ9vP7Q1tR2sX3y";
-export declare const TEST_THREAD_ID = "7YpL3oZ4kZ9vP7Q1tR2sX3z";
+export declare const TEST_CHANNEL_ID = "CQ7yksHFbYFrSPVTaHVCs";
+export declare const TEST_THREAD_ID = "CQ7yksHFbYFrSPVTaHVCt";
 export declare const TEST_COMMENT_ID = "7YpL3oZ4kZ9vP7Q1tR2sX41";
 export declare const TEST_CONVERSATION_ID = "7YpL3oZ4kZ9vP7Q1tR2sX42";
 export declare const TEST_MESSAGE_ID = "7YpL3oZ4kZ9vP7Q1tR2sX43";

package/dist/types/types/requests.d.ts

@@ -164,6 +164,9 @@ export type GetCommentsArgs = z.infer<typeof GetCommentsArgsSchema>;
 export declare const GetConversationsArgsSchema: z.ZodObject<{
     workspaceId: z.ZodNumber;
     archived: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    olderThan: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
+    beforeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export type GetConversationsArgs = z.infer<typeof GetConversationsArgsSchema>;
 export declare const GetOrCreateConversationArgsSchema: z.ZodObject<{

package/dist/types/utils/uuidv7.d.ts

@@ -14,6 +14,8 @@ export declare function decodeBase58ToUuidBytes(value: string): Uint8Array;
  * group — the backend requires the client to supply the ID on create.
  */
 export declare function generateId(): string;
+/** Validate an existing entity ID without minting a replacement. */
+export declare function resolveReferenceId(id: string, fieldName: string): string;
 /**
  * Resolve the `id` for a create-style API call: validate the caller-supplied
  * value (throwing {@link UuidV7Error} before the request leaves the SDK) or

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "0.10.0",
+    "version": "0.11.1",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",