featurebase-node 0.13.0 → 0.14.0

package/src/resources/users/contacts/contacts.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../../../core/resource';
 import * as ContactsAPI from './contacts';
+import * as PostsAPI from '../../feedback/posts/posts';
 import * as CompaniesAPI from '../companies/companies';
 import * as EmailPreferencesAPI from './email-preferences';
 import {
@@ -35,19 +36,27 @@ export class Contacts extends APIResource {
   );
 
   /**
-   * Retrieves a single contact by their Featurebase ID.
-   *
-   * Returns both customers and leads.
+   * Returns a list of contacts (customers and leads) in your organization using
+   * cursor-based pagination.
    *
-   * ### Path Parameters
+   * ### Query Parameters
    *
-   * - `id` - The Featurebase contact ID (24-character ObjectId)
+   * - `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 single contact object with:
+   * 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:
    *
-   * - `object` - Always "contact"
    * - `id` - Unique contact identifier
    * - `userId` - External user ID from SSO (if set)
    * - `email` - Contact email address
@@ -64,11 +73,133 @@ export class Contacts extends APIResource {
    *
    * ```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
+   * // Automatically fetches more pages as needed.
+   * for await (const contact of client.users.contacts.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    params: ContactListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ContactListDataCursorPage, ContactList.Data> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.getAPIList('/v2/contacts', CursorPage<ContactList.Data>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : 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": {...},
    *   ...
    * }
    * ```
@@ -79,18 +210,17 @@ export class Contacts extends APIResource {
    *
    * @example
    * ```ts
-   * const contact = await client.users.contacts.retrieve(
-   *   '507f1f77bcf86cd799439011',
-   * );
+   * const response =
+   *   await client.users.contacts.createOrUpdate();
    * ```
    */
-  retrieve(
-    id: string,
-    params: ContactRetrieveParams | null | undefined = {},
+  createOrUpdate(
+    params: ContactCreateOrUpdateParams,
     options?: RequestOptions,
-  ): APIPromise<ContactRetrieveResponse> {
-    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
-    return this._client.get(path`/v2/contacts/${id}`, {
+  ): APIPromise<ContactCreateOrUpdateResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/contacts', {
+      body,
       ...options,
       headers: buildHeaders([
         {
@@ -104,27 +234,19 @@ export class Contacts extends APIResource {
   }
 
   /**
-   * 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"
+   * Retrieves a single contact by their Featurebase ID.
    *
-   * ### Response Format
+   * Returns both customers and leads.
    *
-   * Returns a list object with:
+   * ### Path Parameters
    *
-   * - `object` - Always "list"
-   * - `data` - Array of contact objects
-   * - `nextCursor` - Cursor for the next page, or null if no more results
+   * - `id` - The Featurebase contact ID (24-character ObjectId)
    *
-   * ### Contact Object
+   * ### Response Format
    *
-   * Each contact includes:
+   * 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
@@ -141,18 +263,12 @@ export class Contacts extends APIResource {
    *
    * ```json
    * {
-   *   "object": "list",
-   *   "data": [
-   *     {
-   *       "object": "contact",
-   *       "id": "676f0f6765bdaa7d7d760f88",
-   *       "email": "john@example.com",
-   *       "name": "John Doe",
-   *       "type": "customer",
-   *       ...
-   *     }
-   *   ],
-   *   "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
+   *   "object": "contact",
+   *   "id": "676f0f6765bdaa7d7d760f88",
+   *   "email": "john@example.com",
+   *   "name": "John Doe",
+   *   "type": "customer",
+   *   ...
    * }
    * ```
    *
@@ -162,19 +278,18 @@ export class Contacts extends APIResource {
    *
    * @example
    * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const contact of client.users.contacts.list()) {
-   *   // ...
-   * }
+   * const contact = await client.users.contacts.retrieve(
+   *   '507f1f77bcf86cd799439011',
+   * );
    * ```
    */
-  list(
-    params: ContactListParams | null | undefined = {},
+  retrieve(
+    id: string,
+    params: ContactRetrieveParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<ContactListDataCursorPage, ContactList.Data> {
-    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
-    return this._client.getAPIList('/v2/contacts', CursorPage<ContactList.Data>, {
-      query,
+  ): APIPromise<ContactRetrieveResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/contacts/${id}`, {
       ...options,
       headers: buildHeaders([
         {
@@ -254,7 +369,7 @@ export class Contacts extends APIResource {
   }
 
   /**
-   * Blocks a contact by their Featurebase ID from the messenger/inbox.
+   * Blocks a contact by their Featurebase ID using the global moderation system.
    *
    * ### Path Parameters
    *
@@ -272,6 +387,8 @@ export class Contacts extends APIResource {
    * When a contact is blocked:
    *
    * - The contact cannot send new messages via messenger
+   * - The contact cannot interact with feedback/changelog surfaces for this
+   *   organization
    * - 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
@@ -325,87 +442,42 @@ export class Contacts extends APIResource {
   }
 
   /**
-   * Creates a new contact or updates an existing one.
+   * Unblocks a contact by their Featurebase ID from the global moderation system.
    *
-   * 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.**
+   * ### Path Parameters
    *
-   * ### Request Body
+   * - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)
    *
-   * | 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) |
+   * ### Supported Contact Types
    *
-   * ### Company Object
+   * This endpoint unblocks both:
    *
-   * Each company in the `companies` array can have:
+   * - **Customers** - Users with registered accounts
+   * - **Leads** - Anonymous or unregistered visitors
    *
-   * - `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
+   * ### Unblocking Behavior
    *
-   * ### Response
+   * When a contact is unblocked:
    *
-   * Returns the created or updated contact object.
+   * - The contact can resume sending messages via messenger
+   * - Previously blocked conversations remain intact
+   * - The contact regains full messenger functionality
    *
-   * - **201 Created** - A new contact was created
-   * - **200 OK** - An existing contact was updated
+   * ### Response
    *
-   * ### Example Request
+   * Returns an unblock confirmation object:
    *
-   * ```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
-   * }
-   * ```
+   * - `id` - The ID of the unblocked contact
+   * - `object` - Always "contact"
+   * - `unblocked` - Always `true`
    *
    * ### Example Response
    *
    * ```json
    * {
+   *   "id": "507f1f77bcf86cd799439011",
    *   "object": "contact",
-   *   "id": "676f0f6765bdaa7d7d760f88",
-   *   "email": "john@example.com",
-   *   "name": "John Doe",
-   *   "userId": "usr_12345",
-   *   "type": "customer",
-   *   "companies": [...],
-   *   "customFields": {...},
-   *   ...
+   *   "unblocked": true
    * }
    * ```
    *
@@ -415,17 +487,18 @@ export class Contacts extends APIResource {
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.users.contacts.createOrUpdate();
+   * const response = await client.users.contacts.unblock(
+   *   '507f1f77bcf86cd799439011',
+   * );
    * ```
    */
-  createOrUpdate(
-    params: ContactCreateOrUpdateParams,
+  unblock(
+    id: string,
+    params: ContactUnblockParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ContactCreateOrUpdateResponse> {
-    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-    return this._client.post('/v2/contacts', {
-      body,
+  ): APIPromise<ContactUnblockResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.post(path`/v2/contacts/${id}/unblock`, {
       ...options,
       headers: buildHeaders([
         {
@@ -547,76 +620,6 @@ export class Contacts extends APIResource {
       ]),
     });
   }
-
-  /**
-   * 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.users.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?.toString() != null ?
-            { 'Featurebase-Version': featurebaseVersion?.toString() }
-          : undefined),
-        },
-        options?.headers,
-      ]),
-    });
-  }
 }
 
 export type ContactListDataCursorPage = CursorPage<ContactList.Data>;
@@ -934,14 +937,6 @@ export interface ContactUnblockResponse {
   unblocked: true;
 }
 
-export interface ContactRetrieveParams {
-  /**
-   * 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 ContactListParams extends CursorPageParams {
   /**
    * Query param: Filter contacts by type. Defaults to "customer".
@@ -955,22 +950,6 @@ export interface ContactListParams extends CursorPageParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
-export interface ContactDeleteParams {
-  /**
-   * 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 ContactBlockParams {
-  /**
-   * 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 ContactCreateOrUpdateParams {
   /**
    * Body param: Companies the contact belongs to
@@ -1123,6 +1102,38 @@ export namespace ContactCreateOrUpdateParams {
   }
 }
 
+export interface ContactRetrieveParams {
+  /**
+   * 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 ContactDeleteParams {
+  /**
+   * 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 ContactBlockParams {
+  /**
+   * 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 ContactUnblockParams {
+  /**
+   * 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 ContactSearchParams {
   /**
    * Body param: An opaque cursor for pagination. Use the `nextCursor` value from a
@@ -1139,7 +1150,7 @@ export interface ContactSearchParams {
    * Body param: Structured filter AST. Either a single filter clause or one
    * top-level AND group (max 15 clauses). Top-level OR groups are not yet supported.
    */
-  query?: ContactSearchParams.SearchFilter | ContactSearchParams.SearchFilterGroup;
+  query?: PostsAPI.SearchFilter | PostsAPI.SearchFilterGroup;
 
   /**
    * Body param: Sort field + direction. Defaults to `lastActivity:desc` (matches the
@@ -1173,64 +1184,6 @@ export interface ContactSearchParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
-export namespace ContactSearchParams {
-  export interface SearchFilter {
-    /**
-     * 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 SearchFilterGroup {
-    /**
-     * Group operator: AND (all match) or OR (any match)
-     */
-    operator: 'AND' | 'OR';
-
-    /**
-     * Array of filter clauses (1-15 entries)
-     */
-    value: Array<SearchFilterGroup.Value>;
-  }
-
-  export namespace SearchFilterGroup {
-    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;
-    }
-  }
-}
-
-export interface ContactUnblockParams {
-  /**
-   * 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';
-}
-
 Contacts.ByUserID = ByUserID;
 Contacts.EmailPreferences = EmailPreferences;
 
@@ -1245,13 +1198,13 @@ export declare namespace Contacts {
     type ContactSearchResponse as ContactSearchResponse,
     type ContactUnblockResponse as ContactUnblockResponse,
     type ContactListDataCursorPage as ContactListDataCursorPage,
-    type ContactRetrieveParams as ContactRetrieveParams,
     type ContactListParams as ContactListParams,
+    type ContactCreateOrUpdateParams as ContactCreateOrUpdateParams,
+    type ContactRetrieveParams as ContactRetrieveParams,
     type ContactDeleteParams as ContactDeleteParams,
     type ContactBlockParams as ContactBlockParams,
-    type ContactCreateOrUpdateParams as ContactCreateOrUpdateParams,
-    type ContactSearchParams as ContactSearchParams,
     type ContactUnblockParams as ContactUnblockParams,
+    type ContactSearchParams as ContactSearchParams,
   };
 
   export {