featurebase-node 0.0.2

package/src/resources/conversations/index.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Conversations,
+  type Conversation,
+  type ConversationPart,
+  type ConversationPartAuthor,
+  type ConversationParticipant,
+  type ConversationTagApplication,
+  type CsatEmailDelivery,
+  type CsatRatedAgent,
+  type CsatWorkflowLink,
+  type EmailRecipients,
+  type ConversationListResponse,
+  type ConversationDeleteResponse,
+  type ConversationCreateParams,
+  type ConversationRetrieveParams,
+  type ConversationUpdateParams,
+  type ConversationListParams,
+  type ConversationDeleteParams,
+  type ConversationRedactParams,
+  type ConversationReplyParams,
+} from './conversations';
+export { Participants, type ParticipantAddParams, type ParticipantRemoveParams } from './participants';
+export {
+  Tags,
+  type AttachedConversationTag,
+  type ConversationTagMutationActor,
+  type TagAttachParams,
+  type TagDetachParams,
+} from './tags';

package/src/resources/conversations/participants.ts

@@ -0,0 +1,263 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ConversationsAPI from './conversations';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+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 Participants extends APIResource {
+  /**
+   * Adds a contact (customer or lead) as a participant to an existing conversation.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The conversation ID (short ID)
+   *
+   * ### Request Body
+   *
+   * | Field                | Type   | Required | Description                                                           |
+   * | -------------------- | ------ | -------- | --------------------------------------------------------------------- |
+   * | `participant`        | object | Yes      | The contact to add (see below)                                        |
+   * | `participant.id`     | string | No\*     | The Featurebase ID (24-character ObjectId) - matches customer or lead |
+   * | `participant.userId` | string | No\*     | External user ID from your system - matches customer only             |
+   * | `participant.email`  | string | No\*     | Email address - matches customer only                                 |
+   * | `actingAdminId`      | string | No       | Admin ID performing the action (for attribution)                      |
+   *
+   * \*At least one of `id`, `userId`, or `email` is required in the participant
+   * object.
+   *
+   * ### Lookup Priority
+   *
+   * 1. If `id` is provided, looks up by Featurebase ID (matches both customer and
+   *    lead types)
+   * 2. If `userId` is provided, looks up by external user ID (matches customer type
+   *    only)
+   * 3. If `email` is provided, looks up by email address (matches customer type
+   *    only)
+   *
+   * ### Response
+   *
+   * Returns the updated conversation object.
+   *
+   * ### Example Request (by Featurebase ID)
+   *
+   * ```json
+   * {
+   *   "participant": {
+   *     "id": "676f0f6765bdaa7d7d760f88"
+   *   },
+   *   "actingAdminId": "507f1f77bcf86cd799439011"
+   * }
+   * ```
+   *
+   * ### Example Request (by external userId)
+   *
+   * ```json
+   * {
+   *   "participant": {
+   *     "userId": "user_123"
+   *   }
+   * }
+   * ```
+   *
+   * ### Example Request (by email)
+   *
+   * ```json
+   * {
+   *   "participant": {
+   *     "email": "john@example.com"
+   *   }
+   * }
+   * ```
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "conversation",
+   *   "id": "12345",
+   *   "participants": [
+   *     { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" },
+   *     { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" }
+   *   ],
+   *   ...
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const conversation =
+   *   await client.conversations.participants.add('12345', {
+   *     participant: {},
+   *   });
+   * ```
+   */
+  add(
+    id: string,
+    params: ParticipantAddParams,
+    options?: RequestOptions,
+  ): APIPromise<ConversationsAPI.Conversation> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/conversations/${id}/participants`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Removes a contact (customer or lead) from an existing conversation.
+   *
+   * **Note:** You cannot remove the last participant from a conversation.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The conversation ID (short ID)
+   *
+   * ### Request Body
+   *
+   * | Field           | Type   | Required | Description                                                         |
+   * | --------------- | ------ | -------- | ------------------------------------------------------------------- |
+   * | `id`            | string | Yes      | The Featurebase ID of the contact to remove (24-character ObjectId) |
+   * | `actingAdminId` | string | No       | Admin ID performing the action (for attribution)                    |
+   *
+   * ### Response
+   *
+   * Returns the updated conversation object.
+   *
+   * ### Example Request
+   *
+   * ```json
+   * {
+   *   "id": "676f0f6765bdaa7d7d760f88",
+   *   "actingAdminId": "507f1f77bcf86cd799439011"
+   * }
+   * ```
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "conversation",
+   *   "id": "12345",
+   *   "participants": [
+   *     { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" }
+   *   ],
+   *   ...
+   * }
+   * ```
+   *
+   * ### Error Cases
+   *
+   * - **400 Bad Request** - Cannot remove the last participant from a conversation
+   * - **404 Not Found** - Conversation or contact not found in participants
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const conversation =
+   *   await client.conversations.participants.remove('12345', {
+   *     id: '676f0f6765bdaa7d7d760f88',
+   *   });
+   * ```
+   */
+  remove(
+    id: string,
+    params: ParticipantRemoveParams,
+    options?: RequestOptions,
+  ): APIPromise<ConversationsAPI.Conversation> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.delete(path`/v2/conversations/${id}/participants`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface ParticipantAddParams {
+  /**
+   * Body param: The contact to add as a participant. At least one of id, userId, or
+   * email is required.
+   */
+  participant: ParticipantAddParams.Participant;
+
+  /**
+   * Body param: The admin ID performing this action. If not provided, changes are
+   * attributed to the system bot user.
+   */
+  actingAdminId?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export namespace ParticipantAddParams {
+  /**
+   * The contact to add as a participant. At least one of id, userId, or email is
+   * required.
+   */
+  export interface Participant {
+    /**
+     * The Featurebase ID of the contact (customer or lead)
+     */
+    id?: string;
+
+    /**
+     * The email address of the contact (matches customer type only)
+     */
+    email?: string;
+
+    /**
+     * The external user ID from your system (matches customer type only)
+     */
+    userId?: string;
+  }
+}
+
+export interface ParticipantRemoveParams {
+  /**
+   * Body param: The Featurebase ID of the contact (customer or lead) to remove
+   */
+  id: string;
+
+  /**
+   * Body param: The admin ID performing this action. If not provided, changes are
+   * attributed to the system bot user.
+   */
+  actingAdminId?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export declare namespace Participants {
+  export {
+    type ParticipantAddParams as ParticipantAddParams,
+    type ParticipantRemoveParams as ParticipantRemoveParams,
+  };
+}

package/src/resources/conversations/tags.ts

@@ -0,0 +1,252 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+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 Tags 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 attachedConversationTag =
+   *   await client.conversations.tags.attach('12345', {
+   *     actingAdminId: '507f1f77bcf86cd799439011',
+   *     tagId: '67ec1234abcd5678ef901234',
+   *   });
+   * ```
+   */
+  attach(id: string, params: TagAttachParams, options?: RequestOptions): APIPromise<AttachedConversationTag> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/conversations/${id}/tags`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : 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 attachedConversationTag =
+   *   await client.conversations.tags.detach(
+   *     '67ec1234abcd5678ef901234',
+   *     {
+   *       id: '12345',
+   *       actingAdminId: '507f1f77bcf86cd799439011',
+   *     },
+   *   );
+   * ```
+   */
+  detach(
+    tagID: string,
+    params: TagDetachParams,
+    options?: RequestOptions,
+  ): APIPromise<AttachedConversationTag> {
+    const { id, 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.delete(path`/v2/conversations/${id}/tags/${tagID}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface AttachedConversationTag {
+  /**
+   * Unique tag identifier
+   */
+  id: string;
+
+  /**
+   * Current tag name
+   */
+  name: string;
+
+  /**
+   * Object type identifier for a tag
+   */
+  type: 'tag';
+
+  /**
+   * ISO timestamp when the tag was applied
+   */
+  appliedAt?: string | null;
+
+  /**
+   * Actor that applied the tag
+   */
+  appliedBy?: ConversationTagMutationActor | null;
+
+  /**
+   * ISO timestamp when the tag was removed, if applicable
+   */
+  removedAt?: string | null;
+
+  /**
+   * Actor that applied the tag
+   */
+  removedBy?: ConversationTagMutationActor | null;
+
+  /**
+   * Reply/message ID used as the deterministic attachment target for this
+   * conversation tag mutation.
+   */
+  targetPartId?: string | null;
+}
+
+/**
+ * Actor that applied the tag
+ */
+export interface ConversationTagMutationActor {
+  /**
+   * 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 TagAttachParams {
+  /**
+   * 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'?: string;
+}
+
+export interface TagDetachParams {
+  /**
+   * 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'?: string;
+}
+
+export declare namespace Tags {
+  export {
+    type AttachedConversationTag as AttachedConversationTag,
+    type ConversationTagMutationActor as ConversationTagMutationActor,
+    type TagAttachParams as TagAttachParams,
+    type TagDetachParams as TagDetachParams,
+  };
+}

package/src/resources/conversations.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './conversations/index';