featurebase-node 0.14.3 → 0.15.0

package/resources/support/conversations/conversations.mjs

@@ -13,91 +13,6 @@ export class Conversations extends APIResource {
         super(...arguments);
         this.participants = new ParticipantsAPI.Participants(this._client);
     }
-    /**
-     * Returns a list of conversations in your organization using cursor-based
-     * pagination.
-     *
-     * ### Query Parameters
-     *
-     * - `limit` - Number of conversations to return (1-100, default 10)
-     * - `cursor` - Cursor from previous response for pagination
-     * - `tagIds` - Optional tag filter as a comma-separated list of tag IDs. Matches
-     *   conversations that contain all of the provided tags.
-     *
-     * ### Response Format
-     *
-     * Returns a list object with:
-     *
-     * - `object` - Always "list"
-     * - `data` - Array of conversation objects
-     * - `nextCursor` - Cursor for the next page, or null if no more results
-     *
-     * ### Conversation Object
-     *
-     * Each conversation includes:
-     *
-     * - `id` - Unique conversation identifier (short ID)
-     * - `title` - Conversation title
-     * - `state` - Current state ("open", "closed", or "snoozed")
-     * - `priority` - Whether the conversation is marked as priority
-     * - `adminAssigneeId` - ID of assigned admin (if any)
-     * - `teamAssigneeId` - ID of assigned team (if any)
-     * - `tags` - Current tags applied anywhere in the conversation
-     * - `participants` - Array of participants
-     * - `source` - Information about the first message
-     * - `createdAt` - Creation timestamp
-     * - `updatedAt` - Last update timestamp
-     *
-     * ### Example
-     *
-     * ```json
-     * {
-     *   "object": "list",
-     *   "data": [
-     *     {
-     *       "object": "conversation",
-     *       "id": "12345",
-     *       "title": "Question about pricing",
-     *       "state": "open",
-     *       "priority": false,
-     *       "adminAssigneeId": null,
-     *       "participants": [
-     *         { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
-     *       ],
-     *       ...
-     *     }
-     *   ],
-     *   "nextCursor": "eyJpZCI6IjEyMzQ1In0="
-     * }
-     * ```
-     *
-     * ### Version Availability
-     *
-     * This endpoint is only available in API version 2026-01-01.nova and newer.
-     *
-     * @example
-     * ```ts
-     * // Automatically fetches more pages as needed.
-     * for await (const conversation of client.support.conversations.list()) {
-     *   // ...
-     * }
-     * ```
-     */
-    list(params = {}, options) {
-        const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
-        return this._client.getAPIList('/v2/conversations', (CursorPage), {
-            query,
-            ...options,
-            headers: buildHeaders([
-                {
-                    ...(featurebaseVersion?.toString() != null ?
-                        { 'Featurebase-Version': featurebaseVersion?.toString() }
-                        : undefined),
-                },
-                options?.headers,
-            ]),
-        });
-    }
     /**
      * Creates a new conversation. Supports both contact-initiated (customer/lead) and
      * admin-initiated (outreach) conversations.
@@ -365,54 +280,6 @@ export class Conversations extends APIResource {
             ]),
         });
     }
-    /**
-     * Permanently deletes a conversation by its short ID.
-     *
-     * ### Path Parameters
-     *
-     * - `id` - The conversation short ID (numeric)
-     *
-     * ### Response
-     *
-     * Returns a deletion confirmation object:
-     *
-     * ```json
-     * {
-     *   "id": "12345",
-     *   "object": "conversation",
-     *   "deleted": true
-     * }
-     * ```
-     *
-     * ### Caution
-     *
-     * This operation is **irreversible**. The conversation and all its messages will
-     * be permanently deleted.
-     *
-     * ### Version Availability
-     *
-     * This endpoint is only available in API version 2026-01-01.nova and newer.
-     *
-     * @example
-     * ```ts
-     * const conversation =
-     *   await client.support.conversations.delete('12345');
-     * ```
-     */
-    delete(id, params = {}, options) {
-        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
-        return this._client.delete(path `/v2/conversations/${id}`, {
-            ...options,
-            headers: buildHeaders([
-                {
-                    ...(featurebaseVersion?.toString() != null ?
-                        { 'Featurebase-Version': featurebaseVersion?.toString() }
-                        : undefined),
-                },
-                options?.headers,
-            ]),
-        });
-    }
     /**
      * Updates a conversation's properties. Supports partial updates - only provided
      * fields will be updated.
@@ -556,97 +423,236 @@ export class Conversations extends APIResource {
         });
     }
     /**
-     * Adds a reply to an existing conversation. Supports both contact (customer/lead)
-     * and admin replies.
+     * Returns a list of conversations in your organization using cursor-based
+     * pagination.
      *
-     * ### Path Parameters
+     * ### Query Parameters
      *
-     * - `id` - The conversation ID (short ID)
+     * - `limit` - Number of conversations to return (1-100, default 10)
+     * - `cursor` - Cursor from previous response for pagination
+     * - `tagIds` - Optional tag filter as a comma-separated list of tag IDs. Matches
+     *   conversations that contain all of the provided tags.
      *
-     * ### Request Body
+     * ### Response Format
      *
-     * The request body varies based on who is sending the reply:
+     * Returns a list object with:
      *
-     * #### Contact Reply (customer/lead)
+     * - `object` - Always "list"
+     * - `data` - Array of conversation objects
+     * - `nextCursor` - Cursor for the next page, or null if no more results
      *
-     * | Field               | Type    | Required | Description                                                                                                                        |
-     * | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-     * | `type`              | string  | Yes      | Must be "contact"                                                                                                                  |
-     * | `userId`            | string  | No\*     | External user ID from your system                                                                                                  |
-     * | `id`                | string  | No\*     | Featurebase contact ID (24-character ObjectId)                                                                                     |
-     * | `bodyMarkdown`      | string  | Yes      | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |
-     * | `messageType`       | string  | Yes      | Must be "reply"                                                                                                                    |
-     * | `skipNotifications` | boolean | No       | Skip sending notifications (default: false). Useful for bulk imports.                                                              |
+     * ### Conversation Object
      *
-     * \*At least one of `userId` or `id` is required.
+     * Each conversation includes:
      *
-     * #### Admin Reply
+     * - `id` - Unique conversation identifier (short ID)
+     * - `title` - Conversation title
+     * - `state` - Current state ("open", "closed", or "snoozed")
+     * - `priority` - Whether the conversation is marked as priority
+     * - `adminAssigneeId` - ID of assigned admin (if any)
+     * - `teamAssigneeId` - ID of assigned team (if any)
+     * - `tags` - Current tags applied anywhere in the conversation
+     * - `participants` - Array of participants
+     * - `source` - Information about the first message
+     * - `createdAt` - Creation timestamp
+     * - `updatedAt` - Last update timestamp
      *
-     * | Field               | Type    | Required | Description                                                                                                                        |
-     * | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-     * | `type`              | string  | Yes      | Must be "admin"                                                                                                                    |
-     * | `id`                | string  | Yes      | Featurebase admin ID (24-character ObjectId)                                                                                       |
-     * | `bodyMarkdown`      | string  | Yes      | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |
-     * | `messageType`       | string  | Yes      | "reply" for customer-visible reply, "note" for internal note                                                                       |
-     * | `skipNotifications` | boolean | No       | Skip sending notifications (default: false). Useful for bulk imports.                                                              |
+     * ### Example
      *
-     * ### Response
+     * ```json
+     * {
+     *   "object": "list",
+     *   "data": [
+     *     {
+     *       "object": "conversation",
+     *       "id": "12345",
+     *       "title": "Question about pricing",
+     *       "state": "open",
+     *       "priority": false,
+     *       "adminAssigneeId": null,
+     *       "participants": [
+     *         { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
+     *       ],
+     *       ...
+     *     }
+     *   ],
+     *   "nextCursor": "eyJpZCI6IjEyMzQ1In0="
+     * }
+     * ```
      *
-     * Returns the created conversation part object with a **201 Created** status. The
-     * response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown`
-     * fields.
+     * ### Version Availability
      *
-     * ### Example Contact Reply
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
      *
-     * ```json
-     * {
-     *   "type": "contact",
-     *   "userId": "user_123",
-     *   "bodyMarkdown": "Thank you for your help!",
-     *   "messageType": "reply"
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const conversation of client.support.conversations.list()) {
+     *   // ...
      * }
      * ```
+     */
+    list(params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+        return this._client.getAPIList('/v2/conversations', (CursorPage), {
+            query,
+            ...options,
+            headers: buildHeaders([
+                {
+                    ...(featurebaseVersion?.toString() != null ?
+                        { 'Featurebase-Version': featurebaseVersion?.toString() }
+                        : undefined),
+                },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Permanently deletes a conversation by its short ID.
      *
-     * ### Example Admin Reply
+     * ### Path Parameters
+     *
+     * - `id` - The conversation short ID (numeric)
+     *
+     * ### Response
+     *
+     * Returns a deletion confirmation object:
      *
      * ```json
      * {
-     *   "type": "admin",
-     *   "id": "507f1f77bcf86cd799439011",
-     *   "bodyMarkdown": "I'm happy to help! Here's what you need to do...",
-     *   "messageType": "reply"
+     *   "id": "12345",
+     *   "object": "conversation",
+     *   "deleted": true
      * }
      * ```
      *
-     * ### Example Admin Note (Internal)
+     * ### Caution
+     *
+     * This operation is **irreversible**. The conversation and all its messages will
+     * be permanently deleted.
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const conversation =
+     *   await client.support.conversations.delete('12345');
+     * ```
+     */
+    delete(id, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.delete(path `/v2/conversations/${id}`, {
+            ...options,
+            headers: buildHeaders([
+                {
+                    ...(featurebaseVersion?.toString() != null ?
+                        { 'Featurebase-Version': featurebaseVersion?.toString() }
+                        : undefined),
+                },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Attaches a workspace tag to a conversation.
+     *
+     * This endpoint requires both the tag ID to attach and the `actingAdminId` of the
+     * admin on whose behalf the mutation is recorded.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The conversation ID (short ID)
+     *
+     * ### Request Body
+     *
+     * | Field           | Type   | Required | Description                                                              |
+     * | --------------- | ------ | -------- | ------------------------------------------------------------------------ |
+     * | `tagId`         | string | Yes      | The Featurebase tag ID to attach                                         |
+     * | `actingAdminId` | string | Yes      | The admin performing the mutation. Must be a member of the organization. |
+     *
+     * ### Behavior
+     *
+     * Featurebase resolves the latest taggable reply/message in the conversation and
+     * records the tag attachment against that part so audit metadata remains
+     * deterministic.
+     *
+     * ### Response
+     *
+     * Returns the affected tag plus attachment metadata such as `targetPartId`,
+     * `appliedAt`, and `appliedBy`.
+     *
+     * ### Example Request
      *
      * ```json
      * {
-     *   "type": "admin",
-     *   "id": "507f1f77bcf86cd799439011",
-     *   "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.",
-     *   "messageType": "note"
+     *   "tagId": "67ec1234abcd5678ef901234",
+     *   "actingAdminId": "507f1f77bcf86cd799439011"
      * }
      * ```
      *
-     * ### Example Response
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const attachedConversationTag =
+     *   await client.support.conversations.attachTag('12345', {
+     *     actingAdminId: '507f1f77bcf86cd799439011',
+     *     tagId: '67ec1234abcd5678ef901234',
+     *   });
+     * ```
+     */
+    attachTag(id, params, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.post(path `/v2/conversations/${id}/tags`, {
+            body,
+            ...options,
+            headers: buildHeaders([
+                {
+                    ...(featurebaseVersion?.toString() != null ?
+                        { 'Featurebase-Version': featurebaseVersion?.toString() }
+                        : undefined),
+                },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Removes a workspace tag from a conversation.
+     *
+     * This endpoint requires the `actingAdminId` of the admin on whose behalf the
+     * mutation is recorded.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The conversation ID (short ID)
+     * - `tagId` - The Featurebase tag ID to remove
+     *
+     * ### Request Body
+     *
+     * | Field           | Type   | Required | Description                                                              |
+     * | --------------- | ------ | -------- | ------------------------------------------------------------------------ |
+     * | `actingAdminId` | string | Yes      | The admin performing the mutation. Must be a member of the organization. |
+     *
+     * ### Behavior
+     *
+     * Featurebase resolves the latest taggable reply/message in the conversation and
+     * records the tag removal against that part so audit metadata remains
+     * deterministic.
+     *
+     * ### Response
+     *
+     * Returns the affected tag payload with the most relevant attachment metadata
+     * available for that relationship.
+     *
+     * ### Example Request
      *
      * ```json
      * {
-     *   "object": "conversation_part",
-     *   "id": "3",
-     *   "partType": "user_msg",
-     *   "bodyHtml": "<p>Thank you for your help!</p>",
-     *   "bodyMarkdown": "Thank you for your help!",
-     *   "author": {
-     *     "type": "customer",
-     *     "id": "676f0f6765bdaa7d7d760f88",
-     *     "name": "John Doe",
-     *     "email": "john@example.com"
-     *   },
-     *   "channel": "desktop",
-     *   "createdAt": "2025-01-15T10:40:00.000Z",
-     *   "updatedAt": "2025-01-15T10:40:00.000Z"
+     *   "actingAdminId": "507f1f77bcf86cd799439011"
      * }
      * ```
      *
@@ -656,17 +662,19 @@ export class Conversations extends APIResource {
      *
      * @example
      * ```ts
-     * const conversationPart =
-     *   await client.support.conversations.reply('12345', {
-     *     bodyMarkdown: 'Thank you for your help!',
-     *     messageType: 'reply',
-     *     type: 'contact',
-     *   });
+     * const attachedConversationTag =
+     *   await client.support.conversations.detachTag(
+     *     '67ec1234abcd5678ef901234',
+     *     {
+     *       id: '12345',
+     *       actingAdminId: '507f1f77bcf86cd799439011',
+     *     },
+     *   );
      * ```
      */
-    reply(id, params, options) {
-        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-        return this._client.post(path `/v2/conversations/${id}/reply`, {
+    detachTag(tagID, params, options) {
+        const { id, 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.delete(path `/v2/conversations/${id}/tags/${tagID}`, {
             body,
             ...options,
             headers: buildHeaders([
@@ -773,10 +781,8 @@ export class Conversations extends APIResource {
         });
     }
     /**
-     * Attaches a workspace tag to a conversation.
-     *
-     * This endpoint requires both the tag ID to attach and the `actingAdminId` of the
-     * admin on whose behalf the mutation is recorded.
+     * Adds a reply to an existing conversation. Supports both contact (customer/lead)
+     * and admin replies.
      *
      * ### Path Parameters
      *
@@ -784,92 +790,88 @@ export class Conversations extends APIResource {
      *
      * ### Request Body
      *
-     * | Field           | Type   | Required | Description                                                              |
-     * | --------------- | ------ | -------- | ------------------------------------------------------------------------ |
-     * | `tagId`         | string | Yes      | The Featurebase tag ID to attach                                         |
-     * | `actingAdminId` | string | Yes      | The admin performing the mutation. Must be a member of the organization. |
+     * The request body varies based on who is sending the reply:
      *
-     * ### Behavior
+     * #### Contact Reply (customer/lead)
      *
-     * Featurebase resolves the latest taggable reply/message in the conversation and
-     * records the tag attachment against that part so audit metadata remains
-     * deterministic.
+     * | Field               | Type    | Required | Description                                                                                                                        |
+     * | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+     * | `type`              | string  | Yes      | Must be "contact"                                                                                                                  |
+     * | `userId`            | string  | No\*     | External user ID from your system                                                                                                  |
+     * | `id`                | string  | No\*     | Featurebase contact ID (24-character ObjectId)                                                                                     |
+     * | `bodyMarkdown`      | string  | Yes      | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |
+     * | `messageType`       | string  | Yes      | Must be "reply"                                                                                                                    |
+     * | `skipNotifications` | boolean | No       | Skip sending notifications (default: false). Useful for bulk imports.                                                              |
+     *
+     * \*At least one of `userId` or `id` is required.
+     *
+     * #### Admin Reply
+     *
+     * | Field               | Type    | Required | Description                                                                                                                        |
+     * | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+     * | `type`              | string  | Yes      | Must be "admin"                                                                                                                    |
+     * | `id`                | string  | Yes      | Featurebase admin ID (24-character ObjectId)                                                                                       |
+     * | `bodyMarkdown`      | string  | Yes      | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |
+     * | `messageType`       | string  | Yes      | "reply" for customer-visible reply, "note" for internal note                                                                       |
+     * | `skipNotifications` | boolean | No       | Skip sending notifications (default: false). Useful for bulk imports.                                                              |
      *
      * ### Response
      *
-     * Returns the affected tag plus attachment metadata such as `targetPartId`,
-     * `appliedAt`, and `appliedBy`.
+     * Returns the created conversation part object with a **201 Created** status. The
+     * response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown`
+     * fields.
      *
-     * ### Example Request
+     * ### Example Contact Reply
      *
      * ```json
      * {
-     *   "tagId": "67ec1234abcd5678ef901234",
-     *   "actingAdminId": "507f1f77bcf86cd799439011"
+     *   "type": "contact",
+     *   "userId": "user_123",
+     *   "bodyMarkdown": "Thank you for your help!",
+     *   "messageType": "reply"
      * }
      * ```
      *
-     * ### Version Availability
-     *
-     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     * ### Example Admin Reply
      *
-     * @example
-     * ```ts
-     * const attachedConversationTag =
-     *   await client.support.conversations.attachTag('12345', {
-     *     actingAdminId: '507f1f77bcf86cd799439011',
-     *     tagId: '67ec1234abcd5678ef901234',
-     *   });
+     * ```json
+     * {
+     *   "type": "admin",
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "bodyMarkdown": "I'm happy to help! Here's what you need to do...",
+     *   "messageType": "reply"
+     * }
      * ```
-     */
-    attachTag(id, params, options) {
-        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-        return this._client.post(path `/v2/conversations/${id}/tags`, {
-            body,
-            ...options,
-            headers: buildHeaders([
-                {
-                    ...(featurebaseVersion?.toString() != null ?
-                        { 'Featurebase-Version': featurebaseVersion?.toString() }
-                        : undefined),
-                },
-                options?.headers,
-            ]),
-        });
-    }
-    /**
-     * Removes a workspace tag from a conversation.
-     *
-     * This endpoint requires the `actingAdminId` of the admin on whose behalf the
-     * mutation is recorded.
      *
-     * ### Path Parameters
-     *
-     * - `id` - The conversation ID (short ID)
-     * - `tagId` - The Featurebase tag ID to remove
-     *
-     * ### Request Body
-     *
-     * | Field           | Type   | Required | Description                                                              |
-     * | --------------- | ------ | -------- | ------------------------------------------------------------------------ |
-     * | `actingAdminId` | string | Yes      | The admin performing the mutation. Must be a member of the organization. |
-     *
-     * ### Behavior
-     *
-     * Featurebase resolves the latest taggable reply/message in the conversation and
-     * records the tag removal against that part so audit metadata remains
-     * deterministic.
-     *
-     * ### Response
+     * ### Example Admin Note (Internal)
      *
-     * Returns the affected tag payload with the most relevant attachment metadata
-     * available for that relationship.
+     * ```json
+     * {
+     *   "type": "admin",
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.",
+     *   "messageType": "note"
+     * }
+     * ```
      *
-     * ### Example Request
+     * ### Example Response
      *
      * ```json
      * {
-     *   "actingAdminId": "507f1f77bcf86cd799439011"
+     *   "object": "conversation_part",
+     *   "id": "3",
+     *   "partType": "user_msg",
+     *   "bodyHtml": "<p>Thank you for your help!</p>",
+     *   "bodyMarkdown": "Thank you for your help!",
+     *   "author": {
+     *     "type": "customer",
+     *     "id": "676f0f6765bdaa7d7d760f88",
+     *     "name": "John Doe",
+     *     "email": "john@example.com"
+     *   },
+     *   "channel": "desktop",
+     *   "createdAt": "2025-01-15T10:40:00.000Z",
+     *   "updatedAt": "2025-01-15T10:40:00.000Z"
      * }
      * ```
      *
@@ -879,19 +881,17 @@ export class Conversations extends APIResource {
      *
      * @example
      * ```ts
-     * const attachedConversationTag =
-     *   await client.support.conversations.detachTag(
-     *     '67ec1234abcd5678ef901234',
-     *     {
-     *       id: '12345',
-     *       actingAdminId: '507f1f77bcf86cd799439011',
-     *     },
-     *   );
+     * const conversationPart =
+     *   await client.support.conversations.reply('12345', {
+     *     bodyMarkdown: 'Thank you for your help!',
+     *     messageType: 'reply',
+     *     type: 'contact',
+     *   });
      * ```
      */
-    detachTag(tagID, params, options) {
-        const { id, 'Featurebase-Version': featurebaseVersion, ...body } = params;
-        return this._client.delete(path `/v2/conversations/${id}/tags/${tagID}`, {
+    reply(id, params, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.post(path `/v2/conversations/${id}/reply`, {
             body,
             ...options,
             headers: buildHeaders([
@@ -1004,6 +1004,16 @@ export class Conversations extends APIResource {
      * fields (`state`, `priority`) are exempt because their negation is naturally
      * bounded.
      *
+     * ### Inbox visibility
+     *
+     * An open-state filter uses the same visibility rule as the Featurebase dashboard
+     * inbox. Workflow and outbound-message shells are excluded until a customer or
+     * lead interacts with them. As a result, `state = "open"` (or an `IN`/`NIN` filter
+     * that resolves exclusively to open) returns the conversations shown in the
+     * dashboard's open inbox rather than unreplied campaign or automation shells.
+     * Searches without an open-only state filter keep their existing organization-wide
+     * semantics.
+     *
      * ### Pagination
      *
      * Cursor-based, `limit` between 1 and 100 (default 10). Pagination cursors are