featurebase-node 0.0.2

package/src/resources/contacts/contacts.ts

@@ -0,0 +1,908 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ContactsAPI from './contacts';
+import * as CompaniesAPI from '../companies/companies';
+import * as EmailPreferencesAPI from './email-preferences';
+import {
+  EmailPreferenceRetrieveParams,
+  EmailPreferenceUpdateParams,
+  EmailPreferences,
+  PreferenceState,
+  PreferencesOutput,
+  UpdatePreferenceBody,
+} from './email-preferences';
+import * as ByUserIDAPI from './by-user-id/by-user-id';
+import {
+  ByUserID,
+  ByUserIDDeleteParams,
+  ByUserIDRetrieveParams,
+  ByUserIDRetrieveResponse,
+} from './by-user-id/by-user-id';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.
+ */
+export class Contacts extends APIResource {
+  byUserID: ByUserIDAPI.ByUserID = new ByUserIDAPI.ByUserID(this._client);
+  emailPreferences: EmailPreferencesAPI.EmailPreferences = new EmailPreferencesAPI.EmailPreferences(
+    this._client,
+  );
+
+  /**
+   * Retrieves a single contact by their Featurebase ID.
+   *
+   * Returns both customers and leads.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase contact ID (24-character ObjectId)
+   *
+   * ### Response Format
+   *
+   * Returns a single contact object with:
+   *
+   * - `object` - Always "contact"
+   * - `id` - Unique contact identifier
+   * - `userId` - External user ID from SSO (if set)
+   * - `email` - Contact email address
+   * - `name` - Contact display name
+   * - `profilePicture` - Profile picture URL
+   * - `type` - Contact type ("customer" or "lead")
+   * - `companies` - Array of companies the contact belongs to
+   * - `customFields` - Custom field values
+   * - `postsCreated` - Number of posts created
+   * - `commentsCreated` - Number of comments created
+   * - `lastActivity` - Last activity timestamp
+   *
+   * ### Example
+   *
+   * ```json
+   * {
+   *   "object": "contact",
+   *   "id": "676f0f6765bdaa7d7d760f88",
+   *   "email": "john@example.com",
+   *   "name": "John Doe",
+   *   "type": "customer",
+   *   ...
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const contact = await client.contacts.retrieve(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: ContactRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactRetrieveResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/contacts/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns a list of contacts (customers and leads) in your organization using
+   * cursor-based pagination.
+   *
+   * ### Query Parameters
+   *
+   * - `limit` - Number of contacts to return (1-100, default 10)
+   * - `cursor` - Cursor from previous response for pagination
+   * - `contactType` - Filter by contact type: "customer" (default), "lead", or "all"
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of contact objects
+   * - `nextCursor` - Cursor for the next page, or null if no more results
+   *
+   * ### Contact Object
+   *
+   * Each contact includes:
+   *
+   * - `id` - Unique contact identifier
+   * - `userId` - External user ID from SSO (if set)
+   * - `email` - Contact email address
+   * - `name` - Contact display name
+   * - `profilePicture` - Profile picture URL
+   * - `type` - Contact type ("customer" or "lead")
+   * - `companies` - Array of companies the contact belongs to
+   * - `customFields` - Custom field values
+   * - `postsCreated` - Number of posts created
+   * - `commentsCreated` - Number of comments created
+   * - `lastActivity` - Last activity timestamp
+   *
+   * ### Example
+   *
+   * ```json
+   * {
+   *   "object": "list",
+   *   "data": [
+   *     {
+   *       "object": "contact",
+   *       "id": "676f0f6765bdaa7d7d760f88",
+   *       "email": "john@example.com",
+   *       "name": "John Doe",
+   *       "type": "customer",
+   *       ...
+   *     }
+   *   ],
+   *   "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const contactList = await client.contacts.list();
+   * ```
+   */
+  list(params: ContactListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ContactList> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get('/v2/contacts', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Permanently deletes a contact by their Featurebase ID.
+   *
+   * Supports deleting both customers and leads.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase contact ID (24-character ObjectId)
+   *
+   * ### Deletion Behavior
+   *
+   * When a contact is deleted:
+   *
+   * - The contact record is permanently removed
+   * - Associated data cleanup is triggered asynchronously
+   * - Comments and posts created by the contact are handled according to retention
+   *   policies
+   *
+   * ### Response
+   *
+   * Returns a deletion confirmation object:
+   *
+   * - `id` - The ID of the deleted contact
+   * - `object` - Always "contact"
+   * - `deleted` - Always `true`
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "id": "676f0f6765bdaa7d7d760f88",
+   *   "object": "contact",
+   *   "deleted": true
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const deletedContact = await client.contacts.delete(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  delete(
+    id: string,
+    params: ContactDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DeletedContact> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/contacts/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Blocks a contact by their Featurebase ID from the messenger/inbox.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)
+   *
+   * ### Supported Contact Types
+   *
+   * This endpoint blocks both:
+   *
+   * - **Customers** - Users with registered accounts
+   * - **Leads** - Anonymous or unregistered visitors
+   *
+   * ### Blocking Behavior
+   *
+   * When a contact is blocked:
+   *
+   * - The contact cannot send new messages via messenger
+   * - Existing conversations are not deleted but no new messages can be added by the
+   *   blocked user
+   * - The block can be removed by unblocking the contact
+   *
+   * ### Response
+   *
+   * Returns a block confirmation object:
+   *
+   * - `id` - The ID of the blocked contact
+   * - `object` - Always "contact"
+   * - `blocked` - Always `true`
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "object": "contact",
+   *   "blocked": true
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.contacts.block(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  block(
+    id: string,
+    params: ContactBlockParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactBlockResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.post(path`/v2/contacts/${id}/block`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Creates a new contact or updates an existing one.
+   *
+   * If a contact with the given `email` or `userId` already exists, it will be
+   * updated. Otherwise, a new contact will be created.
+   *
+   * **At least one of `email` or `userId` must be provided for identification.**
+   *
+   * ### Request Body
+   *
+   * | Field                   | Type    | Required            | Description                             |
+   * | ----------------------- | ------- | ------------------- | --------------------------------------- |
+   * | `email`                 | string  | One of email/userId | Contact email address                   |
+   * | `userId`                | string  | One of email/userId | External user ID from your system       |
+   * | `name`                  | string  | No                  | Contact display name                    |
+   * | `profilePicture`        | string  | No                  | Profile picture URL                     |
+   * | `companies`             | array   | No                  | Companies the contact belongs to        |
+   * | `customFields`          | object  | No                  | Custom field values                     |
+   * | `subscribedToChangelog` | boolean | No                  | Whether subscribed to changelog         |
+   * | `locale`                | string  | No                  | Contact locale/language                 |
+   * | `phone`                 | string  | No                  | Contact phone number                    |
+   * | `roles`                 | array   | No                  | Role IDs to assign                      |
+   * | `userHash`              | string  | No                  | HMAC hash for identity verification     |
+   * | `createdAt`             | string  | No                  | When the contact was created (ISO 8601) |
+   *
+   * ### Company Object
+   *
+   * Each company in the `companies` array can have:
+   *
+   * - `id` (required) - External company ID from your system
+   * - `name` (required) - Company name
+   * - `monthlySpend` - Monthly spend/revenue
+   * - `customFields` - Custom field values
+   * - `industry` - Industry
+   * - `website` - Company website URL
+   * - `plan` - Current plan/subscription
+   * - `companySize` - Number of employees
+   * - `createdAt` - When the company was created
+   *
+   * ### Response
+   *
+   * Returns the created or updated contact object.
+   *
+   * - **201 Created** - A new contact was created
+   * - **200 OK** - An existing contact was updated
+   *
+   * ### Example Request
+   *
+   * ```json
+   * {
+   *   "email": "john@example.com",
+   *   "name": "John Doe",
+   *   "userId": "usr_12345",
+   *   "companies": [
+   *     {
+   *       "id": "company_123",
+   *       "name": "Acme Inc",
+   *       "monthlySpend": 500,
+   *       "plan": "enterprise"
+   *     }
+   *   ],
+   *   "customFields": {
+   *     "plan": "pro",
+   *     "signupSource": "website"
+   *   },
+   *   "subscribedToChangelog": true
+   * }
+   * ```
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "contact",
+   *   "id": "676f0f6765bdaa7d7d760f88",
+   *   "email": "john@example.com",
+   *   "name": "John Doe",
+   *   "userId": "usr_12345",
+   *   "type": "customer",
+   *   "companies": [...],
+   *   "customFields": {...},
+   *   ...
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.contacts.createOrUpdate();
+   * ```
+   */
+  createOrUpdate(
+    params: ContactCreateOrUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<ContactCreateOrUpdateResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/contacts', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Unblocks a contact by their Featurebase ID from the messenger/inbox.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)
+   *
+   * ### Supported Contact Types
+   *
+   * This endpoint unblocks both:
+   *
+   * - **Customers** - Users with registered accounts
+   * - **Leads** - Anonymous or unregistered visitors
+   *
+   * ### Unblocking Behavior
+   *
+   * When a contact is unblocked:
+   *
+   * - The contact can resume sending messages via messenger
+   * - Previously blocked conversations remain intact
+   * - The contact regains full messenger functionality
+   *
+   * ### Response
+   *
+   * Returns an unblock confirmation object:
+   *
+   * - `id` - The ID of the unblocked contact
+   * - `object` - Always "contact"
+   * - `unblocked` - Always `true`
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "object": "contact",
+   *   "unblocked": true
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.contacts.unblock(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  unblock(
+    id: string,
+    params: ContactUnblockParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactUnblockResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.post(path`/v2/contacts/${id}/unblock`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * User who submitted the response
+ */
+export interface Contact {
+  /**
+   * Unique identifier
+   */
+  id: string;
+
+  /**
+   * Contact display name
+   */
+  name: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'contact';
+
+  /**
+   * Type of contact
+   */
+  type: 'customer' | 'lead';
+
+  /**
+   * Number of comments created
+   */
+  commentsCreated?: number;
+
+  /**
+   * Companies the contact belongs to
+   */
+  companies?: Array<CompaniesAPI.Company>;
+
+  /**
+   * Custom field values on the contact
+   */
+  customFields?: { [key: string]: unknown };
+
+  /**
+   * Contact description/bio
+   */
+  description?: string;
+
+  /**
+   * Contact email
+   */
+  email?: string | null;
+
+  /**
+   * Last activity ISO timestamp
+   */
+  lastActivity?: string;
+
+  /**
+   * Contact locale
+   */
+  locale?: string;
+
+  /**
+   * Whether manually opted out from changelog
+   */
+  manuallyOptedOutFromChangelog?: boolean;
+
+  /**
+   * Organization ID the contact belongs to
+   */
+  organizationId?: string;
+
+  /**
+   * Number of posts created
+   */
+  postsCreated?: number;
+
+  /**
+   * Profile picture URL
+   */
+  profilePicture?: string | null;
+
+  /**
+   * Contact roles
+   */
+  roles?: Array<string>;
+
+  /**
+   * Whether subscribed to changelog
+   */
+  subscribedToChangelog?: boolean;
+
+  /**
+   * External user ID from SSO
+   */
+  userId?: string;
+
+  /**
+   * Whether email is verified
+   */
+  verified?: boolean;
+}
+
+export interface ContactList {
+  /**
+   * Array of contacts
+   */
+  data: Array<ContactList.Data>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+}
+
+export namespace ContactList {
+  /**
+   * User who submitted the response
+   */
+  export type Data = ContactsAPI.Contact | (null & {});
+}
+
+export interface DeletedContact {
+  /**
+   * Unique identifier of the deleted contact
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was deleted
+   */
+  deleted: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'contact';
+}
+
+/**
+ * User who submitted the response
+ */
+export type ContactRetrieveResponse = Contact | (null & {});
+
+export interface ContactBlockResponse {
+  /**
+   * Unique identifier of the blocked contact
+   */
+  id: string;
+
+  /**
+   * Indicates the contact was blocked
+   */
+  blocked: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'contact';
+}
+
+/**
+ * User who submitted the response
+ */
+export type ContactCreateOrUpdateResponse = Contact | (null & {});
+
+export interface ContactUnblockResponse {
+  /**
+   * Unique identifier of the unblocked contact
+   */
+  id: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'contact';
+
+  /**
+   * Indicates the contact was unblocked
+   */
+  unblocked: true;
+}
+
+export interface ContactRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ContactListParams {
+  /**
+   * Query param: Filter contacts by type. Defaults to "customer".
+   */
+  contactType?: 'customer' | 'lead' | 'all';
+
+  /**
+   * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+   * previous response to fetch the next page of results.
+   */
+  cursor?: string;
+
+  /**
+   * Query param: A limit on the number of objects to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ContactDeleteParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ContactBlockParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ContactCreateOrUpdateParams {
+  /**
+   * Body param: Companies the contact belongs to
+   */
+  companies?: Array<ContactCreateOrUpdateParams.Company>;
+
+  /**
+   * Body param: When the contact was created in your system (ISO 8601)
+   */
+  createdAt?: string | null;
+
+  /**
+   * Body param: Custom field values on the contact. Values can be string, number,
+   * boolean, null, or array of primitives.
+   */
+  customFields?: ContactCreateOrUpdateParams.CustomFields;
+
+  /**
+   * Body param: Contact email address. Used for identification if userId is not
+   * provided.
+   */
+  email?: string;
+
+  /**
+   * Body param: Contact locale/language preference
+   */
+  locale?: string;
+
+  /**
+   * Body param: Contact display name
+   */
+  name?: string;
+
+  /**
+   * Body param: Contact phone number
+   */
+  phone?: string | null;
+
+  /**
+   * Body param: Profile picture URL
+   */
+  profilePicture?: string | null;
+
+  /**
+   * Body param: Array of role IDs to assign to the contact
+   */
+  roles?: Array<string>;
+
+  /**
+   * Body param: Whether the contact is subscribed to changelog updates
+   */
+  subscribedToChangelog?: boolean;
+
+  /**
+   * Body param: HMAC-SHA256 hash of userId or email for identity verification
+   */
+  userHash?: string;
+
+  /**
+   * Body param: External user ID from your system. Takes precedence over email for
+   * identification.
+   */
+  userId?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export namespace ContactCreateOrUpdateParams {
+  export interface Company {
+    /**
+     * External company ID from your system
+     */
+    id: string;
+
+    /**
+     * Company name
+     */
+    name: string;
+
+    /**
+     * HMAC-SHA256 hash of company ID for identity verification
+     */
+    companyHash?: string;
+
+    /**
+     * Number of employees in the company
+     */
+    companySize?: number | null;
+
+    /**
+     * When the company was created (ISO 8601)
+     */
+    createdAt?: string | null;
+
+    /**
+     * Custom field values on the company. Values can be string, number, boolean, null,
+     * or array of primitives.
+     */
+    customFields?: Company.CustomFields;
+
+    /**
+     * Industry the company operates in
+     */
+    industry?: string;
+
+    /**
+     * Monthly spend/revenue from this company
+     */
+    monthlySpend?: number;
+
+    /**
+     * Current plan/subscription name
+     */
+    plan?: string;
+
+    /**
+     * Company website URL
+     */
+    website?: string;
+  }
+
+  export namespace Company {
+    /**
+     * Custom field values on the company. Values can be string, number, boolean, null,
+     * or array of primitives.
+     */
+    export interface CustomFields {
+      industry?: string;
+
+      plan?: string;
+
+      priority?: string;
+    }
+  }
+
+  /**
+   * Custom field values on the contact. Values can be string, number, boolean, null,
+   * or array of primitives.
+   */
+  export interface CustomFields {
+    accountType?: string;
+
+    plan?: string;
+
+    signupSource?: string;
+  }
+}
+
+export interface ContactUnblockParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+Contacts.ByUserID = ByUserID;
+Contacts.EmailPreferences = EmailPreferences;
+
+export declare namespace Contacts {
+  export {
+    type Contact as Contact,
+    type ContactList as ContactList,
+    type DeletedContact as DeletedContact,
+    type ContactRetrieveResponse as ContactRetrieveResponse,
+    type ContactBlockResponse as ContactBlockResponse,
+    type ContactCreateOrUpdateResponse as ContactCreateOrUpdateResponse,
+    type ContactUnblockResponse as ContactUnblockResponse,
+    type ContactRetrieveParams as ContactRetrieveParams,
+    type ContactListParams as ContactListParams,
+    type ContactDeleteParams as ContactDeleteParams,
+    type ContactBlockParams as ContactBlockParams,
+    type ContactCreateOrUpdateParams as ContactCreateOrUpdateParams,
+    type ContactUnblockParams as ContactUnblockParams,
+  };
+
+  export {
+    ByUserID as ByUserID,
+    type ByUserIDRetrieveResponse as ByUserIDRetrieveResponse,
+    type ByUserIDRetrieveParams as ByUserIDRetrieveParams,
+    type ByUserIDDeleteParams as ByUserIDDeleteParams,
+  };
+
+  export {
+    EmailPreferences as EmailPreferences,
+    type PreferenceState as PreferenceState,
+    type PreferencesOutput as PreferencesOutput,
+    type UpdatePreferenceBody as UpdatePreferenceBody,
+    type EmailPreferenceRetrieveParams as EmailPreferenceRetrieveParams,
+    type EmailPreferenceUpdateParams as EmailPreferenceUpdateParams,
+  };
+}