featurebase-node 0.8.1 → 0.10.0

package/src/resources/support/conversations/conversations.ts

@@ -5,14 +5,6 @@ import * as ConversationsAPI from './conversations';
 import * as ConversationTagsAPI from '../conversation-tags';
 import * as ParticipantsAPI from './participants';
 import { ParticipantAddParams, ParticipantRemoveParams, Participants } from './participants';
-import * as TagsAPI from './tags';
-import {
-  AttachedConversationTag,
-  ConversationTagMutationActor,
-  TagAttachParams,
-  TagDetachParams,
-  Tags,
-} from './tags';
 import { APIPromise } from '../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination';
 import { buildHeaders } from '../../../internal/headers';
@@ -23,7 +15,6 @@ import { path } from '../../../internal/utils/path';
  * Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information.
  */
 export class Conversations extends APIResource {
-  tags: TagsAPI.Tags = new TagsAPI.Tags(this._client);
   participants: ParticipantsAPI.Participants = new ParticipantsAPI.Participants(this._client);
 
   /**
@@ -583,6 +574,148 @@ 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.
+   *
+   * ### 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
+   * {
+   *   "tagId": "67ec1234abcd5678ef901234",
+   *   "actingAdminId": "507f1f77bcf86cd799439011"
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.support.conversations.attachTag('12345', {
+   *     actingAdminId: '507f1f77bcf86cd799439011',
+   *     tagId: '67ec1234abcd5678ef901234',
+   *   });
+   * ```
+   */
+  attachTag(
+    id: string,
+    params: ConversationAttachTagParams,
+    options?: RequestOptions,
+  ): APIPromise<ConversationAttachTagResponse> {
+    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
+   * {
+   *   "actingAdminId": "507f1f77bcf86cd799439011"
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.support.conversations.detachTag(
+   *     '67ec1234abcd5678ef901234',
+   *     {
+   *       id: '12345',
+   *       actingAdminId: '507f1f77bcf86cd799439011',
+   *     },
+   *   );
+   * ```
+   */
+  detachTag(
+    tagID: string,
+    params: ConversationDetachTagParams,
+    options?: RequestOptions,
+  ): APIPromise<ConversationDetachTagResponse> {
+    const { id, 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.delete(path`/v2/conversations/${id}/tags/${tagID}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Redacts a conversation part (message) from a conversation. Redaction permanently
    * removes the message content while preserving the conversation structure.
@@ -801,6 +934,119 @@ export class Conversations extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Search conversations with a structured filter AST and an optional full-text
+   * query.
+   *
+   * The endpoint has two modes that are picked automatically from the body:
+   *
+   * - **Filter mode** (`query` set, `search` omitted): structured filtering against
+   *   indexed conversation fields. Sorted by `lastActivityAt` desc by default; set
+   *   `sort` to `last_activity_at:asc` for the inverse.
+   * - **Search mode** (`search` set, `query` optional): full-text search across
+   *   conversation messages, then narrowed by the same `query` AST so the same
+   *   filters apply. Results are ranked by relevance.
+   *
+   * ### Structured query AST
+   *
+   * Each clause has the shape `{ field, operator, value }`. You can pass a single
+   * clause or wrap up to 15 in a top-level `AND` group:
+   *
+   * ```json
+   * {
+   *   "query": {
+   *     "operator": "AND",
+   *     "value": [
+   *       { "field": "state", "operator": "=", "value": "open" },
+   *       {
+   *         "field": "admin_assignee_id",
+   *         "operator": "=",
+   *         "value": "507f1f77bcf86cd799439011"
+   *       }
+   *     ]
+   *   }
+   * }
+   * ```
+   *
+   * Top-level `OR` groups and nested groups are not supported in this version.
+   *
+   * ### Supported fields and operators
+   *
+   * | Field                        | Type                                                                        | Operators              |
+   * | ---------------------------- | --------------------------------------------------------------------------- | ---------------------- |
+   * | `state`                      | enum (`open` / `closed` / `snoozed`)                                        | `=`, `!=`, `IN`, `NIN` |
+   * | `priority`                   | boolean                                                                     | `=`, `!=`              |
+   * | `admin_assignee_id`          | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN` |
+   * | `team_assignee_id`           | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN` |
+   * | `brand_id`                   | id or null                                                                  | `=`, `!=`, `IN`, `NIN` |
+   * | `tag_ids`                    | id (matches any conversation containing this tag)                           | `=`, `!=`, `IN`, `NIN` |
+   * | `user_id` / `participant_id` | id of a conversation participant                                            | `=`, `!=`, `IN`, `NIN` |
+   * | `company_id`                 | company id (matches conversations whose participants belong to the company) | `=`, `!=`, `IN`, `NIN` |
+   * | `mentioned_admin_ids`        | admin id                                                                    | `=`, `!=`, `IN`, `NIN` |
+   * | `created_at`                 | unix seconds                                                                | `=`, `>`, `<`          |
+   *
+   * For unbounded fields a query consisting only of `!=` or `NIN` clauses is
+   * rejected with `query_too_broad` to prevent full-org scans. Combine the negation
+   * with at least one positive clause (`=`, `IN`, `>`, `<`) instead. Bounded enum
+   * fields (`state`, `priority`) are exempt because their negation is naturally
+   * bounded.
+   *
+   * ### Pagination
+   *
+   * Cursor-based, `limit` between 1 and 100 (default 10). Pagination cursors are
+   * mode-specific - reusing a filter-mode cursor in search mode (or vice versa)
+   * returns `400`. `totalCount` is approximate and capped at 1000;
+   * `totalCountCapped` is `true` when the real count may be higher.
+   *
+   * ### Response
+   *
+   * Returns a slim conversation row optimised for inbox / list rendering - just the
+   * fields you need to render a row and link to the conversation. Fetch the full
+   * conversation via `GET /v2/conversations/{id}` when the user opens one.
+   *
+   * Search-specific additions on each row:
+   *
+   * - `conversationUser` - the customer / lead the conversation is with. Use this
+   *   for the row identity.
+   * - `surroundingConversationParts` - context window of human messages around the
+   *   matched message (≈15 before + 15 from the match onwards in search mode,
+   *   sliding to first / last 30 if the match is near the conversation boundaries;
+   *   falls back to the latest 30 messages in filter mode). Each `previewMarkdown`
+   *   value is truncated server-side; fetch the full conversation for complete
+   *   history and full bodies.
+   * - `matchingPartAuthor` - author of the specific message that matched the search
+   *   query (search mode only). May be a teammate or bot.
+   * - `matchingPart` - reference to the matched message (search mode only).
+   * - `matchingBodyPreviewMarkdown` - plain-text / markdown preview of the matched
+   *   body (search mode only).
+   * - `relevanceScore` - aggregate score (search mode only).
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.support.conversations.search();
+   * ```
+   */
+  search(params: ConversationSearchParams, options?: RequestOptions): APIPromise<ConversationSearchResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/conversations/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
 }
 
 export type ConversationsCursorPage = CursorPage<Conversation>;
@@ -2022,7 +2268,7 @@ export namespace ConversationPart {
     /**
      * Actor that applied the tag
      */
-    actor?: TagsAPI.ConversationTagMutationActor;
+    actor?: TagUpdate.Actor;
 
     /**
      * Tag name at the time of the event or the best available current display name
@@ -2035,6 +2281,28 @@ export namespace ConversationPart {
     targetPartId?: string | null;
   }
 
+  export namespace TagUpdate {
+    /**
+     * Actor that applied the tag
+     */
+    export interface Actor {
+      /**
+       * Actor that caused the tag mutation
+       */
+      type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
+
+      /**
+       * Actor identifier when available
+       */
+      id?: string | null;
+
+      /**
+       * Actor display name when available
+       */
+      name?: string | null;
+    }
+  }
+
   /**
    * Represents a workflow wait start, finish, or interruption in the conversation
    * thread
@@ -2249,7 +2517,7 @@ export interface ConversationTagApplication {
   /**
    * Actor that applied the tag
    */
-  appliedBy?: TagsAPI.ConversationTagMutationActor;
+  appliedBy?: ConversationTagApplication.AppliedBy;
 
   /**
    * ISO timestamp when the tag was removed from this reply, if it was removed
@@ -2259,7 +2527,7 @@ export interface ConversationTagApplication {
   /**
    * Actor that applied the tag
    */
-  removedBy?: TagsAPI.ConversationTagMutationActor;
+  removedBy?: ConversationTagApplication.RemovedBy;
 
   /**
    * Resolved tag object when the tag still exists in the shared workspace catalog
@@ -2267,6 +2535,48 @@ export interface ConversationTagApplication {
   tag?: ConversationTagsAPI.ConversationTag;
 }
 
+export namespace ConversationTagApplication {
+  /**
+   * Actor that applied the tag
+   */
+  export interface AppliedBy {
+    /**
+     * Actor that caused the tag mutation
+     */
+    type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
+
+    /**
+     * Actor identifier when available
+     */
+    id?: string | null;
+
+    /**
+     * Actor display name when available
+     */
+    name?: string | null;
+  }
+
+  /**
+   * Actor that applied the tag
+   */
+  export interface RemovedBy {
+    /**
+     * Actor that caused the tag mutation
+     */
+    type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
+
+    /**
+     * Actor identifier when available
+     */
+    id?: string | null;
+
+    /**
+     * Actor display name when available
+     */
+    name?: string | null;
+  }
+}
+
 export interface CsatEmailDelivery {
   /**
    * Email delivery status for the CSAT request when applicable
@@ -2360,131 +2670,676 @@ export interface ConversationDeleteResponse {
   object: 'conversation';
 }
 
-export interface ConversationCreateParams {
+export interface ConversationAttachTagResponse {
   /**
-   * Body param: The content of the initial message in markdown format. Images
-   * referenced by URL or as base64 data URIs will be automatically uploaded and
-   * stored.
+   * Unique tag identifier
    */
-  bodyMarkdown: string;
+  id: string;
 
   /**
-   * Body param: The author initiating the conversation. Use type "contact" for
-   * customer/lead or "admin" for outreach.
+   * Current tag name
    */
-  from: ConversationCreateParams.ContactFrom | ConversationCreateParams.AdminFrom;
+  name: string;
 
   /**
-   * Body param: The channel for the conversation. Defaults to "desktop"
-   * (SDK/widget).
+   * Object type identifier for a tag
    */
-  channel?: 'desktop' | 'email';
+  type: 'tag';
 
   /**
-   * Body param: The time the conversation was created as an ISO timestamp. If not
-   * provided, the current time will be used. This field is recommended for migrating
-   * past conversations from another source.
+   * ISO timestamp when the tag was applied
    */
-  createdAt?: string | null;
+  appliedAt?: string | null;
 
   /**
-   * Body param: Recipients for admin-initiated outreach. Required when from.type is
-   * "admin". Specify at least one recipient in the "to" field.
+   * Actor that applied the tag
    */
-  recipients?: ConversationCreateParams.Recipients;
+  appliedBy?: ConversationAttachTagResponse.AppliedBy | null;
 
   /**
-   * Body param: Subject line for the email. Required when channel is "email" and
-   * from.type is "admin".
+   * ISO timestamp when the tag was removed, if applicable
    */
-  subject?: string;
+  removedAt?: string | null;
 
   /**
-   * Header param: API version for this request. Defaults to your organization's
-   * configured API version if not specified.
+   * Actor that applied the tag
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
-}
+  removedBy?: ConversationAttachTagResponse.RemovedBy | null;
 
-export namespace ConversationCreateParams {
   /**
-   * Conversation initiated by a contact
+   * Reply/message ID used as the deterministic attachment target for this
+   * conversation tag mutation.
    */
-  export interface ContactFrom {
-    /**
-     * The Featurebase contact ID
-     */
-    id: string;
+  targetPartId?: string | null;
+}
 
+export namespace ConversationAttachTagResponse {
+  /**
+   * Actor that applied the tag
+   */
+  export interface AppliedBy {
     /**
-     * The type of author. Use "contact" for customer/lead initiated conversations.
+     * Actor that caused the tag mutation
      */
-    type: 'contact';
-  }
+    type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
 
-  /**
-   * Conversation initiated by an admin (outreach)
-   */
-  export interface AdminFrom {
     /**
-     * The Featurebase admin ID
+     * Actor identifier when available
      */
-    id: string;
+    id?: string | null;
 
     /**
-     * The type of author. Use "admin" for admin initiated outreach conversations.
+     * Actor display name when available
      */
-    type: 'admin';
+    name?: string | null;
   }
 
   /**
-   * Recipients for admin-initiated outreach. Required when from.type is "admin".
-   * Specify at least one recipient in the "to" field.
+   * Actor that applied the tag
    */
-  export interface Recipients {
+  export interface RemovedBy {
     /**
-     * Primary recipients (To field)
+     * Actor that caused the tag mutation
      */
-    to: ConversationsAPI.EmailRecipients;
+    type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
 
     /**
-     * Primary recipients (To field)
+     * Actor identifier when available
      */
-    bcc?: ConversationsAPI.EmailRecipients;
+    id?: string | null;
 
     /**
-     * Primary recipients (To field)
+     * Actor display name when available
      */
-    cc?: ConversationsAPI.EmailRecipients;
+    name?: string | null;
   }
 }
 
-export interface ConversationRetrieveParams {
+export interface ConversationDetachTagResponse {
   /**
-   * API version for this request. Defaults to your organization's configured API
-   * version if not specified.
+   * Unique tag identifier
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
-}
+  id: string;
 
-export interface ConversationUpdateParams {
   /**
-   * Body param: The admin ID performing this action. Changes will be attributed to
-   * this admin. If not provided, changes are attributed to the system bot user. The
-   * admin must be a member of the organization.
+   * Current tag name
    */
-  actingAdminId?: string;
+  name: string;
 
   /**
-   * Body param: The admin ID to assign the conversation to, or null to unassign.
+   * Object type identifier for a tag
    */
-  adminAssigneeId?: string | null;
+  type: 'tag';
 
   /**
-   * Body param: Custom attributes to set on the conversation. Uses the same
-   * validation as v1 API.
+   * ISO timestamp when the tag was applied
    */
-  customAttributes?: { [key: string]: unknown };
+  appliedAt?: string | null;
+
+  /**
+   * Actor that applied the tag
+   */
+  appliedBy?: ConversationDetachTagResponse.AppliedBy | null;
+
+  /**
+   * ISO timestamp when the tag was removed, if applicable
+   */
+  removedAt?: string | null;
+
+  /**
+   * Actor that applied the tag
+   */
+  removedBy?: ConversationDetachTagResponse.RemovedBy | null;
+
+  /**
+   * Reply/message ID used as the deterministic attachment target for this
+   * conversation tag mutation.
+   */
+  targetPartId?: string | null;
+}
+
+export namespace ConversationDetachTagResponse {
+  /**
+   * Actor that applied the tag
+   */
+  export interface AppliedBy {
+    /**
+     * Actor that caused the tag mutation
+     */
+    type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
+
+    /**
+     * Actor identifier when available
+     */
+    id?: string | null;
+
+    /**
+     * Actor display name when available
+     */
+    name?: string | null;
+  }
+
+  /**
+   * Actor that applied the tag
+   */
+  export interface RemovedBy {
+    /**
+     * Actor that caused the tag mutation
+     */
+    type: 'admin' | 'customer' | 'lead' | 'bot' | 'integration' | 'system' | 'workflow';
+
+    /**
+     * Actor identifier when available
+     */
+    id?: string | null;
+
+    /**
+     * Actor display name when available
+     */
+    name?: string | null;
+  }
+}
+
+export interface ConversationSearchResponse {
+  /**
+   * Array of search results
+   */
+  data: Array<ConversationSearchResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (null if no more results)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Total number of conversations matching the query, capped at 200. When the actual
+   * total is at or above the cap, `totalCountCapped` is true and the value is
+   * exactly the cap.
+   */
+  totalCount?: number;
+
+  /**
+   * True when totalCount is exactly the cap and the real count is `>= totalCount`.
+   * UI may render as "200+".
+   */
+  totalCountCapped?: boolean;
+}
+
+export namespace ConversationSearchResponse {
+  export interface Data {
+    /**
+     * Unique conversation identifier
+     */
+    id: string;
+
+    /**
+     * ID of the assigned admin
+     */
+    adminAssigneeId: string | null;
+
+    /**
+     * ID of the brand associated with this conversation
+     */
+    brandId: string | null;
+
+    /**
+     * ISO timestamp when conversation was created
+     */
+    createdAt: string;
+
+    /**
+     * ISO timestamp of last activity
+     */
+    lastActivityAt: string | null;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation';
+
+    /**
+     * Participants in this conversation
+     */
+    participants: Array<ConversationsAPI.ConversationParticipant>;
+
+    /**
+     * Whether this conversation is marked as priority
+     */
+    priority: boolean;
+
+    /**
+     * ISO timestamp when priority was set
+     */
+    prioritySetAt: string | null;
+
+    /**
+     * Current state of the conversation
+     */
+    state: 'open' | 'closed' | 'snoozed';
+
+    /**
+     * Current tags applied anywhere in this conversation
+     */
+    tags: Array<ConversationTagsAPI.ConversationTag>;
+
+    /**
+     * ID of the assigned team
+     */
+    teamAssigneeId: string | null;
+
+    /**
+     * ISO timestamp when conversation was last updated
+     */
+    updatedAt: string;
+
+    /**
+     * Whether we are awaiting a customer reply
+     */
+    awaitingCustomerReply?: boolean;
+
+    /**
+     * The customer or lead the conversation is with. Use this for the row identity;
+     * use `matchingPartAuthor` if you specifically want the message author.
+     */
+    conversationUser?: Data.ConversationUser | null;
+
+    /**
+     * Plain-text / markdown preview of the matching conversation part body (search
+     * mode only)
+     */
+    matchingBodyPreviewMarkdown?: string | null;
+
+    /**
+     * Reference to the conversation part that best matched the search query (search
+     * mode only)
+     */
+    matchingPart?: Data.MatchingPart | null;
+
+    /**
+     * The customer or lead the conversation is with. Use this for the row identity;
+     * use `matchingPartAuthor` if you specifically want the message author.
+     */
+    matchingPartAuthor?: Data.MatchingPartAuthor | null;
+
+    /**
+     * Aggregate relevance score for the conversation (search mode only). Higher is
+     * more relevant.
+     */
+    relevanceScore?: number | null;
+
+    source?: Data.Source;
+
+    /**
+     * Window of conversation messages around the matching part for lightweight context
+     * previews. In search mode this is up to 15 messages before plus 15 from the
+     * matching message onwards (sliding to first 30 / last 30 if the match is near the
+     * conversation boundaries). In filter mode (no matching message) this falls back
+     * to the latest 30 messages. Always capped and truncated by the server; fetch the
+     * full conversation for complete message history.
+     */
+    surroundingConversationParts?: Array<Data.SurroundingConversationPart>;
+
+    /**
+     * Conversation title
+     */
+    title?: string;
+  }
+
+  export namespace Data {
+    /**
+     * The customer or lead the conversation is with. Use this for the row identity;
+     * use `matchingPartAuthor` if you specifically want the message author.
+     */
+    export interface ConversationUser {
+      /**
+       * Author id
+       */
+      id: string;
+
+      /**
+       * Author type
+       */
+      type: 'admin' | 'customer' | 'lead' | 'bot' | 'guest' | 'integration';
+
+      /**
+       * Companies the author belongs to (customers only)
+       */
+      companies?: Array<ConversationUser.Company>;
+
+      /**
+       * Email when known
+       */
+      email?: string | null;
+
+      /**
+       * Display name when known
+       */
+      name?: string | null;
+
+      /**
+       * Profile picture URL when known
+       */
+      profilePicture?: string | null;
+    }
+
+    export namespace ConversationUser {
+      export interface Company {
+        id: string;
+
+        name?: string;
+      }
+    }
+
+    /**
+     * Reference to the conversation part that best matched the search query (search
+     * mode only)
+     */
+    export interface MatchingPart {
+      /**
+       * Conversation part id
+       */
+      id: string;
+
+      /**
+       * ISO timestamp when the matching part was created
+       */
+      createdAt?: string | null;
+
+      /**
+       * Conversation part type
+       */
+      partType?: string;
+    }
+
+    /**
+     * The customer or lead the conversation is with. Use this for the row identity;
+     * use `matchingPartAuthor` if you specifically want the message author.
+     */
+    export interface MatchingPartAuthor {
+      /**
+       * Author id
+       */
+      id: string;
+
+      /**
+       * Author type
+       */
+      type: 'admin' | 'customer' | 'lead' | 'bot' | 'guest' | 'integration';
+
+      /**
+       * Companies the author belongs to (customers only)
+       */
+      companies?: Array<MatchingPartAuthor.Company>;
+
+      /**
+       * Email when known
+       */
+      email?: string | null;
+
+      /**
+       * Display name when known
+       */
+      name?: string | null;
+
+      /**
+       * Profile picture URL when known
+       */
+      profilePicture?: string | null;
+    }
+
+    export namespace MatchingPartAuthor {
+      export interface Company {
+        id: string;
+
+        name?: string;
+      }
+    }
+
+    export interface Source {
+      /**
+       * Body of the initial message as HTML with signed image URLs
+       */
+      bodyHtml: string;
+
+      /**
+       * Body of the initial message as markdown
+       */
+      bodyMarkdown: string;
+
+      /**
+       * Channel through which the conversation was initiated
+       */
+      channel: 'unknown' | 'desktop' | 'android' | 'ios' | 'email';
+
+      author?: ConversationsAPI.ConversationParticipant;
+
+      /**
+       * How the conversation was initiated
+       */
+      deliveredAs?: 'customer_initiated' | 'admin_initiated';
+
+      /**
+       * Subject line for email conversations
+       */
+      subject?: string;
+
+      /**
+       * URL where the conversation was initiated
+       */
+      url?: string;
+    }
+
+    export interface SurroundingConversationPart {
+      /**
+       * Conversation part id
+       */
+      id: string;
+
+      /**
+       * Plain-text truncated preview of the part body
+       */
+      previewMarkdown: string | null;
+
+      /**
+       * True when previewMarkdown was truncated by the server
+       */
+      previewMarkdownTruncated: boolean;
+
+      /**
+       * The customer or lead the conversation is with. Use this for the row identity;
+       * use `matchingPartAuthor` if you specifically want the message author.
+       */
+      author?: SurroundingConversationPart.Author | null;
+
+      /**
+       * ISO timestamp when the part was created
+       */
+      createdAt?: string | null;
+
+      /**
+       * Conversation part type
+       */
+      partType?: string;
+    }
+
+    export namespace SurroundingConversationPart {
+      /**
+       * The customer or lead the conversation is with. Use this for the row identity;
+       * use `matchingPartAuthor` if you specifically want the message author.
+       */
+      export interface Author {
+        /**
+         * Author id
+         */
+        id: string;
+
+        /**
+         * Author type
+         */
+        type: 'admin' | 'customer' | 'lead' | 'bot' | 'guest' | 'integration';
+
+        /**
+         * Companies the author belongs to (customers only)
+         */
+        companies?: Array<Author.Company>;
+
+        /**
+         * Email when known
+         */
+        email?: string | null;
+
+        /**
+         * Display name when known
+         */
+        name?: string | null;
+
+        /**
+         * Profile picture URL when known
+         */
+        profilePicture?: string | null;
+      }
+
+      export namespace Author {
+        export interface Company {
+          id: string;
+
+          name?: string;
+        }
+      }
+    }
+  }
+}
+
+export interface ConversationCreateParams {
+  /**
+   * Body param: The content of the initial message in markdown format. Images
+   * referenced by URL or as base64 data URIs will be automatically uploaded and
+   * stored.
+   */
+  bodyMarkdown: string;
+
+  /**
+   * Body param: The author initiating the conversation. Use type "contact" for
+   * customer/lead or "admin" for outreach.
+   */
+  from: ConversationCreateParams.ContactFrom | ConversationCreateParams.AdminFrom;
+
+  /**
+   * Body param: The channel for the conversation. Defaults to "desktop"
+   * (SDK/widget).
+   */
+  channel?: 'desktop' | 'email';
+
+  /**
+   * Body param: The time the conversation was created as an ISO timestamp. If not
+   * provided, the current time will be used. This field is recommended for migrating
+   * past conversations from another source.
+   */
+  createdAt?: string | null;
+
+  /**
+   * Body param: Recipients for admin-initiated outreach. Required when from.type is
+   * "admin". Specify at least one recipient in the "to" field.
+   */
+  recipients?: ConversationCreateParams.Recipients;
+
+  /**
+   * Body param: Subject line for the email. Required when channel is "email" and
+   * from.type is "admin".
+   */
+  subject?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export namespace ConversationCreateParams {
+  /**
+   * Conversation initiated by a contact
+   */
+  export interface ContactFrom {
+    /**
+     * The Featurebase contact ID
+     */
+    id: string;
+
+    /**
+     * The type of author. Use "contact" for customer/lead initiated conversations.
+     */
+    type: 'contact';
+  }
+
+  /**
+   * Conversation initiated by an admin (outreach)
+   */
+  export interface AdminFrom {
+    /**
+     * The Featurebase admin ID
+     */
+    id: string;
+
+    /**
+     * The type of author. Use "admin" for admin initiated outreach conversations.
+     */
+    type: 'admin';
+  }
+
+  /**
+   * Recipients for admin-initiated outreach. Required when from.type is "admin".
+   * Specify at least one recipient in the "to" field.
+   */
+  export interface Recipients {
+    /**
+     * Primary recipients (To field)
+     */
+    to: ConversationsAPI.EmailRecipients;
+
+    /**
+     * Primary recipients (To field)
+     */
+    bcc?: ConversationsAPI.EmailRecipients;
+
+    /**
+     * Primary recipients (To field)
+     */
+    cc?: ConversationsAPI.EmailRecipients;
+  }
+}
+
+export interface ConversationRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface ConversationUpdateParams {
+  /**
+   * Body param: The admin ID performing this action. Changes will be attributed to
+   * this admin. If not provided, changes are attributed to the system bot user. The
+   * admin must be a member of the organization.
+   */
+  actingAdminId?: string;
+
+  /**
+   * Body param: The admin ID to assign the conversation to, or null to unassign.
+   */
+  adminAssigneeId?: string | null;
+
+  /**
+   * Body param: Custom attributes to set on the conversation. Uses the same
+   * validation as v1 API.
+   */
+  customAttributes?: { [key: string]: unknown };
 
   /**
    * Body param: Mark the conversation as read for specific admins and/or contacts.
@@ -2572,6 +3427,44 @@ export interface ConversationDeleteParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
+export interface ConversationAttachTagParams {
+  /**
+   * Body param: Required admin ID performing this tag attachment. Must be a member
+   * of the organization so the mutation can be attributed to a real admin actor.
+   */
+  actingAdminId: string;
+
+  /**
+   * Body param: The Featurebase tag ID to attach to the conversation.
+   */
+  tagId: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface ConversationDetachTagParams {
+  /**
+   * Path param: Conversation ID (short ID)
+   */
+  id: string;
+
+  /**
+   * Body param: Required admin ID performing this tag removal. Must be a member of
+   * the organization so the mutation can be attributed to a real admin actor.
+   */
+  actingAdminId: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
 export interface ConversationRedactParams {
   /**
    * Body param: The conversation short ID that contains the part to redact
@@ -2686,7 +3579,96 @@ export declare namespace ConversationReplyParams {
   }
 }
 
-Conversations.Tags = Tags;
+export interface ConversationSearchParams {
+  /**
+   * Body param: An opaque cursor for pagination. Use the nextCursor value from a
+   * previous response to fetch the next page of results.
+   */
+  cursor?: string;
+
+  /**
+   * Body param: A limit on the number of objects to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Body param: Structured filter AST. Either a single filter clause or one
+   * top-level AND group. Use this for filtering by `state`, `tag_ids`,
+   * `admin_assignee_id`, etc.
+   */
+  query?:
+    | ConversationSearchParams.ConversationSearchFilter
+    | ConversationSearchParams.ConversationSearchFilterGroup;
+
+  /**
+   * Body param: Plain-text full-text search across conversation messages.
+   * Server-managed - no operators, no field selection.
+   */
+  search?: string;
+
+  /**
+   * Body param: Sort direction for filter mode (ignored in search mode where results
+   * are sorted by relevance). Defaults to last_activity_at:desc.
+   */
+  sort?: 'last_activity_at:desc' | 'last_activity_at:asc';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export namespace ConversationSearchParams {
+  export interface ConversationSearchFilter {
+    /**
+     * Field name to filter on (e.g. `state`, `tag_ids`, `created_at`)
+     */
+    field: string;
+
+    /**
+     * Comparison operator
+     */
+    operator: '=' | '!=' | 'IN' | 'NIN' | '>' | '<' | '~' | '!~' | '^' | '$';
+
+    /**
+     * Value to compare against (primitive or array of primitives)
+     */
+    value: string | number | boolean | Array<string | number> | null;
+  }
+
+  export interface ConversationSearchFilterGroup {
+    /**
+     * Group operator: AND (all match) or OR (any match)
+     */
+    operator: 'AND' | 'OR';
+
+    /**
+     * Array of filter clauses (1-15 entries)
+     */
+    value: Array<ConversationSearchFilterGroup.Value>;
+  }
+
+  export namespace ConversationSearchFilterGroup {
+    export interface Value {
+      /**
+       * Field name to filter on (e.g. `state`, `tag_ids`, `created_at`)
+       */
+      field: string;
+
+      /**
+       * Comparison operator
+       */
+      operator: '=' | '!=' | 'IN' | 'NIN' | '>' | '<' | '~' | '!~' | '^' | '$';
+
+      /**
+       * Value to compare against (primitive or array of primitives)
+       */
+      value: string | number | boolean | Array<string | number> | null;
+    }
+  }
+}
+
 Conversations.Participants = Participants;
 
 export declare namespace Conversations {
@@ -2701,22 +3683,20 @@ export declare namespace Conversations {
     type CsatWorkflowLink as CsatWorkflowLink,
     type EmailRecipients as EmailRecipients,
     type ConversationDeleteResponse as ConversationDeleteResponse,
+    type ConversationAttachTagResponse as ConversationAttachTagResponse,
+    type ConversationDetachTagResponse as ConversationDetachTagResponse,
+    type ConversationSearchResponse as ConversationSearchResponse,
     type ConversationsCursorPage as ConversationsCursorPage,
     type ConversationCreateParams as ConversationCreateParams,
     type ConversationRetrieveParams as ConversationRetrieveParams,
     type ConversationUpdateParams as ConversationUpdateParams,
     type ConversationListParams as ConversationListParams,
     type ConversationDeleteParams as ConversationDeleteParams,
+    type ConversationAttachTagParams as ConversationAttachTagParams,
+    type ConversationDetachTagParams as ConversationDetachTagParams,
     type ConversationRedactParams as ConversationRedactParams,
     type ConversationReplyParams as ConversationReplyParams,
-  };
-
-  export {
-    Tags as Tags,
-    type AttachedConversationTag as AttachedConversationTag,
-    type ConversationTagMutationActor as ConversationTagMutationActor,
-    type TagAttachParams as TagAttachParams,
-    type TagDetachParams as TagDetachParams,
+    type ConversationSearchParams as ConversationSearchParams,
   };
 
   export {