@doist/comms-sdk 0.7.1 → 0.9.0

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

@@ -3,38 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.addCommentRequest = addCommentRequest;
 const endpoints_1 = require("../consts/endpoints");
 const http_client_1 = require("../transport/http-client");
-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));
-function isNotifyAudience(value) {
-    return typeof value === 'string' && enums_1.NOTIFY_AUDIENCES.includes(value);
-}
-function collectMarkerOffenses(field, values) {
-    if (!values)
-        return null;
-    const offending = values.filter((id) => SENTINEL_GROUP_IDS.has(id));
-    return offending.length > 0 ? { field, offending } : null;
-}
-function applyNotifyAudience(params) {
-    const offenses = [
-        collectMarkerOffenses('groups', params.groups ?? undefined),
-        collectMarkerOffenses('directGroupMentions', params.directGroupMentions ?? undefined),
-    ].filter((o) => o !== null);
-    if (offenses.length > 0) {
-        const details = offenses
-            .map(({ field, offending }) => `\`${field}\` contains ${offending.join(', ')}`)
-            .join('; ');
-        throw new Error(`Reserved broadcast marker IDs found: ${details}. Pass these via \`notifyAudience\` on createComment / closeThread / reopenThread (e.g. \`notifyAudience: 'channel'\` for EVERYONE) instead of populating \`groups\` / \`directGroupMentions\` directly.`);
-    }
-    if (params.notifyAudience == null)
-        return params;
-    if (!isNotifyAudience(params.notifyAudience)) {
-        throw new Error(`Invalid \`notifyAudience\` value "${String(params.notifyAudience)}". Expected one of: ${enums_1.NOTIFY_AUDIENCES.join(', ')}.`);
-    }
-    const sentinel = enums_1.NOTIFY_AUDIENCE_GROUP_IDS[params.notifyAudience];
-    const { notifyAudience: _stripped, groups, ...rest } = params;
-    return { ...rest, groups: [...(groups ?? []), sentinel] };
-}
+const notify_audience_1 = require("./notify-audience");
 /**
  * Internal helper that powers `comments.createComment`,
  * `threads.closeThread`, and `threads.reopenThread`.
@@ -53,7 +23,7 @@ function applyNotifyAudience(params) {
  * @returns The parsed {@link Comment} returned by the API.
  */
 function addCommentRequest(context, params, options) {
-    const normalized = applyNotifyAudience(params);
+    const normalized = (0, notify_audience_1.applyNotifyAudience)(params);
     const withId = { ...normalized, id: (0, uuidv7_1.resolveCreateId)(normalized.id) };
     const payload = options?.threadAction
         ? { ...withId, threadAction: options.threadAction }

package/dist/cjs/clients/notify-audience.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyNotifyAudience = applyNotifyAudience;
+const enums_1 = require("../types/enums");
+const SENTINEL_GROUP_IDS = new Set(Object.values(enums_1.NOTIFY_AUDIENCE_GROUP_IDS));
+function isNotifyAudience(value) {
+    return typeof value === 'string' && enums_1.NOTIFY_AUDIENCES.includes(value);
+}
+function collectMarkerOffenses(field, values) {
+    if (!values)
+        return null;
+    const offending = values.filter((id) => SENTINEL_GROUP_IDS.has(id));
+    return offending.length > 0 ? { field, offending } : null;
+}
+/**
+ * Normalizes a `notifyAudience` flag into a sentinel `groups` entry
+ * (`EVERYONE` / `EVERYONE_IN_THREAD`) and rejects callers who put those
+ * reserved markers directly into `groups` / `directGroupMentions`.
+ *
+ * When `notifyAudience` is set it is stripped and its sentinel is appended to
+ * `groups`; the backend only understands the marker in `groups`. When it is
+ * unset the params are returned unchanged, preserving any explicit
+ * `groups` / `directGroupMentions` (including a `null`) on the wire.
+ */
+function applyNotifyAudience(params) {
+    const offenses = [
+        collectMarkerOffenses('groups', params.groups ?? undefined),
+        collectMarkerOffenses('directGroupMentions', params.directGroupMentions ?? undefined),
+    ].filter((o) => o !== null);
+    if (offenses.length > 0) {
+        const details = offenses
+            .map(({ field, offending }) => `\`${field}\` contains ${offending.join(', ')}`)
+            .join('; ');
+        throw new Error(`Reserved broadcast marker IDs found: ${details}. Pass these via \`notifyAudience\` (e.g. \`notifyAudience: 'channel'\` for EVERYONE) instead of populating \`groups\` / \`directGroupMentions\` directly.`);
+    }
+    if (params.notifyAudience == null) {
+        return params;
+    }
+    if (!isNotifyAudience(params.notifyAudience)) {
+        throw new Error(`Invalid \`notifyAudience\` value "${String(params.notifyAudience)}". Expected one of: ${enums_1.NOTIFY_AUDIENCES.join(', ')}.`);
+    }
+    const sentinel = enums_1.NOTIFY_AUDIENCE_GROUP_IDS[params.notifyAudience];
+    const { notifyAudience: _stripped, groups, ...rest } = params;
+    return { ...rest, groups: [...(groups ?? []), sentinel] };
+}

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

@@ -8,6 +8,7 @@ const entities_1 = require("../types/entities");
 const uuidv7_1 = require("../utils/uuidv7");
 const add_comment_helper_1 = require("./add-comment-helper");
 const base_client_1 = require("./base-client");
+const notify_audience_1 = require("./notify-audience");
 exports.ThreadListSchema = zod_1.z.array(entities_1.ThreadSchema);
 const GetUnreadResponseSchema = zod_1.z.object({
     data: zod_1.z.array(entities_1.UnreadThreadSchema),
@@ -95,6 +96,11 @@ class ThreadsClient extends base_client_1.BaseClient {
      * @param args.content - The thread content.
      * @param args.recipients - Optional array of user IDs to notify.
      * @param args.groups - Optional array of custom group IDs to notify.
+     * @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 — but a
+     *   brand-new thread has no interactions yet, so the backend discards
+     *   `'thread'` at create time. It is only meaningful on replies (`createComment`).
      * @param args.attachments - Optional array of {@link Attachment}s (from `attachments.upload`).
      * @returns The created thread object.
      *
@@ -104,11 +110,13 @@ class ThreadsClient extends base_client_1.BaseClient {
      *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
      *   title: 'New Feature Discussion',
      *   content: 'Let\'s discuss the new feature...',
+     *   notifyAudience: 'channel', // tag "Everyone in channel"
      * })
      * ```
      */
     createThread(args) {
-        return this.simple('POST', 'add', { ...args, id: (0, uuidv7_1.resolveCreateId)(args.id) }, this.threadSchema);
+        const normalized = (0, notify_audience_1.applyNotifyAudience)(args);
+        return this.simple('POST', 'add', { ...normalized, id: (0, uuidv7_1.resolveCreateId)(args.id) }, this.threadSchema);
     }
     /**
      * Partial update of an existing thread.

package/dist/cjs/types/entities.js

@@ -420,16 +420,29 @@ exports.UnreadConversationSchema = zod_1.z.object({
     directMention: zod_1.z.boolean(),
 });
 // SearchResult entity from API.
+// The API currently only emits 'thread' and 'conversation' results: a match inside a
+// comment is returned as a 'thread' result with `commentId` set, and a match inside a
+// message as a 'conversation' result with `messageId` set.
 exports.SEARCH_RESULT_TYPES = ['thread', 'comment', 'message', 'conversation'];
 exports.SearchResultSchema = zod_1.z.object({
+    /**
+     * Opaque search-result key in the form `thread_<threadId>` or
+     * `conversation_<conversationId>`. Unique per result; not a Comms object id — use
+     * `threadId`, `conversationId`, `commentId`, or `messageId` to reference objects.
+     */
     id: zod_1.z.string(),
     type: zod_1.z.enum(exports.SEARCH_RESULT_TYPES),
     snippet: zod_1.z.string(),
     snippetCreatorId: zod_1.z.number(),
     snippetLastUpdated: zod_1.z.date(),
+    /** The owning thread id. Set by the API on 'thread' results. */
     threadId: zod_1.z.string().nullable().optional(),
+    /** The owning conversation id. Set by the API on 'conversation' results. */
     conversationId: zod_1.z.string().nullable().optional(),
+    /** The matched comment id, set on 'thread' results when the match is a comment. */
     commentId: zod_1.z.string().nullable().optional(),
+    /** The matched message id, set by the API on 'conversation' results. */
+    messageId: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).transform(String).nullable().optional(),
     channelId: zod_1.z.string().nullable().optional(),
     channelName: zod_1.z.string().nullable().optional(),
     channelColor: zod_1.z.number().nullable().optional(),

package/dist/cjs/types/requests.js

@@ -42,6 +42,7 @@ exports.CreateThreadArgsSchema = zod_1.z.object({
     id: zod_1.z.string().optional(),
     recipients: zod_1.z.array(zod_1.z.number()).nullable().optional(),
     groups: zod_1.z.array(zod_1.z.string()).nullable().optional(),
+    notifyAudience: zod_1.z.enum(enums_1.NOTIFY_AUDIENCES).nullable().optional(),
     attachments: zod_1.z.array(entities_1.RequestAttachmentSchema).nullable().optional(),
 });
 exports.UpdateThreadArgsSchema = zod_1.z.object({

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

@@ -1,37 +1,7 @@
 import { ENDPOINT_COMMENTS } from '../consts/endpoints.js';
 import { request } from '../transport/http-client.js';
-import { NOTIFY_AUDIENCE_GROUP_IDS, NOTIFY_AUDIENCES } from '../types/enums.js';
 import { resolveCreateId } from '../utils/uuidv7.js';
-const SENTINEL_GROUP_IDS = new Set(Object.values(NOTIFY_AUDIENCE_GROUP_IDS));
-function isNotifyAudience(value) {
-    return typeof value === 'string' && NOTIFY_AUDIENCES.includes(value);
-}
-function collectMarkerOffenses(field, values) {
-    if (!values)
-        return null;
-    const offending = values.filter((id) => SENTINEL_GROUP_IDS.has(id));
-    return offending.length > 0 ? { field, offending } : null;
-}
-function applyNotifyAudience(params) {
-    const offenses = [
-        collectMarkerOffenses('groups', params.groups ?? undefined),
-        collectMarkerOffenses('directGroupMentions', params.directGroupMentions ?? undefined),
-    ].filter((o) => o !== null);
-    if (offenses.length > 0) {
-        const details = offenses
-            .map(({ field, offending }) => `\`${field}\` contains ${offending.join(', ')}`)
-            .join('; ');
-        throw new Error(`Reserved broadcast marker IDs found: ${details}. Pass these via \`notifyAudience\` on createComment / closeThread / reopenThread (e.g. \`notifyAudience: 'channel'\` for EVERYONE) instead of populating \`groups\` / \`directGroupMentions\` directly.`);
-    }
-    if (params.notifyAudience == null)
-        return params;
-    if (!isNotifyAudience(params.notifyAudience)) {
-        throw new Error(`Invalid \`notifyAudience\` value "${String(params.notifyAudience)}". Expected one of: ${NOTIFY_AUDIENCES.join(', ')}.`);
-    }
-    const sentinel = NOTIFY_AUDIENCE_GROUP_IDS[params.notifyAudience];
-    const { notifyAudience: _stripped, groups, ...rest } = params;
-    return { ...rest, groups: [...(groups ?? []), sentinel] };
-}
+import { applyNotifyAudience } from './notify-audience.js';
 /**
  * Internal helper that powers `comments.createComment`,
  * `threads.closeThread`, and `threads.reopenThread`.

package/dist/esm/clients/notify-audience.js

@@ -0,0 +1,42 @@
+import { NOTIFY_AUDIENCE_GROUP_IDS, NOTIFY_AUDIENCES } from '../types/enums.js';
+const SENTINEL_GROUP_IDS = new Set(Object.values(NOTIFY_AUDIENCE_GROUP_IDS));
+function isNotifyAudience(value) {
+    return typeof value === 'string' && NOTIFY_AUDIENCES.includes(value);
+}
+function collectMarkerOffenses(field, values) {
+    if (!values)
+        return null;
+    const offending = values.filter((id) => SENTINEL_GROUP_IDS.has(id));
+    return offending.length > 0 ? { field, offending } : null;
+}
+/**
+ * Normalizes a `notifyAudience` flag into a sentinel `groups` entry
+ * (`EVERYONE` / `EVERYONE_IN_THREAD`) and rejects callers who put those
+ * reserved markers directly into `groups` / `directGroupMentions`.
+ *
+ * When `notifyAudience` is set it is stripped and its sentinel is appended to
+ * `groups`; the backend only understands the marker in `groups`. When it is
+ * unset the params are returned unchanged, preserving any explicit
+ * `groups` / `directGroupMentions` (including a `null`) on the wire.
+ */
+export function applyNotifyAudience(params) {
+    const offenses = [
+        collectMarkerOffenses('groups', params.groups ?? undefined),
+        collectMarkerOffenses('directGroupMentions', params.directGroupMentions ?? undefined),
+    ].filter((o) => o !== null);
+    if (offenses.length > 0) {
+        const details = offenses
+            .map(({ field, offending }) => `\`${field}\` contains ${offending.join(', ')}`)
+            .join('; ');
+        throw new Error(`Reserved broadcast marker IDs found: ${details}. Pass these via \`notifyAudience\` (e.g. \`notifyAudience: 'channel'\` for EVERYONE) instead of populating \`groups\` / \`directGroupMentions\` directly.`);
+    }
+    if (params.notifyAudience == null) {
+        return params;
+    }
+    if (!isNotifyAudience(params.notifyAudience)) {
+        throw new Error(`Invalid \`notifyAudience\` value "${String(params.notifyAudience)}". Expected one of: ${NOTIFY_AUDIENCES.join(', ')}.`);
+    }
+    const sentinel = NOTIFY_AUDIENCE_GROUP_IDS[params.notifyAudience];
+    const { notifyAudience: _stripped, groups, ...rest } = params;
+    return { ...rest, groups: [...(groups ?? []), sentinel] };
+}

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

@@ -5,6 +5,7 @@ import { CommentSchema, createCommentSchema, createThreadSchema, StatusOkSchema,
 import { resolveCreateId } from '../utils/uuidv7.js';
 import { addCommentRequest } from './add-comment-helper.js';
 import { BaseClient } from './base-client.js';
+import { applyNotifyAudience } from './notify-audience.js';
 export const ThreadListSchema = z.array(ThreadSchema);
 const GetUnreadResponseSchema = z.object({
     data: z.array(UnreadThreadSchema),
@@ -92,6 +93,11 @@ export class ThreadsClient extends BaseClient {
      * @param args.content - The thread content.
      * @param args.recipients - Optional array of user IDs to notify.
      * @param args.groups - Optional array of custom group IDs to notify.
+     * @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 — but a
+     *   brand-new thread has no interactions yet, so the backend discards
+     *   `'thread'` at create time. It is only meaningful on replies (`createComment`).
      * @param args.attachments - Optional array of {@link Attachment}s (from `attachments.upload`).
      * @returns The created thread object.
      *
@@ -101,11 +107,13 @@ export class ThreadsClient extends BaseClient {
      *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
      *   title: 'New Feature Discussion',
      *   content: 'Let\'s discuss the new feature...',
+     *   notifyAudience: 'channel', // tag "Everyone in channel"
      * })
      * ```
      */
     createThread(args) {
-        return this.simple('POST', 'add', { ...args, id: resolveCreateId(args.id) }, this.threadSchema);
+        const normalized = applyNotifyAudience(args);
+        return this.simple('POST', 'add', { ...normalized, id: resolveCreateId(args.id) }, this.threadSchema);
     }
     /**
      * Partial update of an existing thread.

package/dist/esm/types/entities.js

@@ -410,16 +410,29 @@ export const UnreadConversationSchema = z.object({
     directMention: z.boolean(),
 });
 // SearchResult entity from API.
+// The API currently only emits 'thread' and 'conversation' results: a match inside a
+// comment is returned as a 'thread' result with `commentId` set, and a match inside a
+// message as a 'conversation' result with `messageId` set.
 export const SEARCH_RESULT_TYPES = ['thread', 'comment', 'message', 'conversation'];
 export const SearchResultSchema = z.object({
+    /**
+     * Opaque search-result key in the form `thread_<threadId>` or
+     * `conversation_<conversationId>`. Unique per result; not a Comms object id — use
+     * `threadId`, `conversationId`, `commentId`, or `messageId` to reference objects.
+     */
     id: z.string(),
     type: z.enum(SEARCH_RESULT_TYPES),
     snippet: z.string(),
     snippetCreatorId: z.number(),
     snippetLastUpdated: z.date(),
+    /** The owning thread id. Set by the API on 'thread' results. */
     threadId: z.string().nullable().optional(),
+    /** The owning conversation id. Set by the API on 'conversation' results. */
     conversationId: z.string().nullable().optional(),
+    /** The matched comment id, set on 'thread' results when the match is a comment. */
     commentId: z.string().nullable().optional(),
+    /** The matched message id, set by the API on 'conversation' results. */
+    messageId: z.union([z.string(), z.number()]).transform(String).nullable().optional(),
     channelId: z.string().nullable().optional(),
     channelName: z.string().nullable().optional(),
     channelColor: z.number().nullable().optional(),

package/dist/esm/types/requests.js

@@ -39,6 +39,7 @@ export const CreateThreadArgsSchema = z.object({
     id: z.string().optional(),
     recipients: z.array(z.number()).nullable().optional(),
     groups: z.array(z.string()).nullable().optional(),
+    notifyAudience: z.enum(NOTIFY_AUDIENCES).nullable().optional(),
     attachments: z.array(RequestAttachmentSchema).nullable().optional(),
 });
 export const UpdateThreadArgsSchema = z.object({

package/dist/types/clients/notify-audience.d.ts

@@ -0,0 +1,22 @@
+import { type NotifyAudience } from '../types/enums.js';
+/**
+ * Params bearing the group-targeting fields that can carry a `notifyAudience`.
+ * Shared by the comment-creating endpoints and thread creation.
+ */
+type NotifyAudienceParams = {
+    groups?: string[] | null;
+    directGroupMentions?: string[] | null;
+    notifyAudience?: NotifyAudience | null;
+};
+/**
+ * Normalizes a `notifyAudience` flag into a sentinel `groups` entry
+ * (`EVERYONE` / `EVERYONE_IN_THREAD`) and rejects callers who put those
+ * reserved markers directly into `groups` / `directGroupMentions`.
+ *
+ * When `notifyAudience` is set it is stripped and its sentinel is appended to
+ * `groups`; the backend only understands the marker in `groups`. When it is
+ * unset the params are returned unchanged, preserving any explicit
+ * `groups` / `directGroupMentions` (including a `null`) on the wire.
+ */
+export declare function applyNotifyAudience<T extends NotifyAudienceParams>(params: T): Omit<T, 'notifyAudience'>;
+export {};

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

@@ -336,6 +336,11 @@ export declare class ThreadsClient extends BaseClient {
      * @param args.content - The thread content.
      * @param args.recipients - Optional array of user IDs to notify.
      * @param args.groups - Optional array of custom group IDs to notify.
+     * @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 — but a
+     *   brand-new thread has no interactions yet, so the backend discards
+     *   `'thread'` at create time. It is only meaningful on replies (`createComment`).
      * @param args.attachments - Optional array of {@link Attachment}s (from `attachments.upload`).
      * @returns The created thread object.
      *
@@ -345,6 +350,7 @@ export declare class ThreadsClient extends BaseClient {
      *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
      *   title: 'New Feature Discussion',
      *   content: 'Let\'s discuss the new feature...',
+     *   notifyAudience: 'channel', // tag "Everyone in channel"
      * })
      * ```
      */

package/dist/types/types/entities.d.ts

@@ -2818,6 +2818,7 @@ export declare const SearchResultSchema: z.ZodObject<{
     threadId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     conversationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     commentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    messageId: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>>>;
     channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     channelName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     channelColor: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;

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

@@ -40,6 +40,10 @@ export declare const CreateThreadArgsSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     recipients: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
     groups: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    notifyAudience: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        channel: "channel";
+        thread: "thread";
+    }>>>;
     attachments: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
         attachmentId: z.ZodString;
         urlType: z.ZodString;

package/package.json

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