featurebase-node 0.10.0 → 0.11.0

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

@@ -438,6 +438,106 @@ export class Contacts extends APIResource {
     });
   }
 
+  /**
+   * Search contacts (customers and leads) with a structured filter AST, sorting, and
+   * cursor pagination.
+   *
+   * ### 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": "type", "operator": "=", "value": "customer" },
+   *       { "field": "last_activity", "operator": ">", "value": 1735689600 }
+   *     ]
+   *   },
+   *   "sort": "last_activity:desc",
+   *   "limit": 20
+   * }
+   * ```
+   *
+   * Top-level `OR` groups and nested groups are not supported in this version.
+   *
+   * ### Supported fields and operators
+   *
+   * | Field              | Type                             | Operators                   |
+   * | ------------------ | -------------------------------- | --------------------------- |
+   * | `external_id`      | string (caller-provided user id) | `=`, `!=`, `IN`, `NIN`      |
+   * | `email`            | string                           | `=`, `!=`, `IN`, `NIN`      |
+   * | `name`             | string                           | `=`, `!=`, `IN`, `NIN`, `~` |
+   * | `type`             | enum (`customer`, `lead`)        | `=`, `!=`, `IN`, `NIN`      |
+   * | `company_ids`      | id (Featurebase company `id`)    | `=`, `!=`, `IN`, `NIN`      |
+   * | `posts_created`    | number                           | `=`, `!=`, `>`, `<`         |
+   * | `comments_created` | number                           | `=`, `!=`, `>`, `<`         |
+   * | `last_activity`    | unix seconds                     | `=`, `!=`, `>`, `<`         |
+   * | `created_at`       | unix seconds                     | `=`, `!=`, `>`, `<`         |
+   *
+   * The `name ~ "..."` operator runs a word-aware substring search via the
+   * underlying text index. Other string operators (`!~`, `^`, `$`) are reserved for
+   * future use and currently return `400`.
+   *
+   * A query consisting only of `!=` or `NIN` clauses on unbounded fields is rejected
+   * with `query_too_broad` to prevent full-org scans. Combine the negation with at
+   * least one positive clause (`=`, `IN`, `>`, `<`) instead. The closed-enum field
+   * `type` is exempt from this guard.
+   *
+   * Contacts that have been merged into another contact (lead-to-customer rollup)
+   * are always excluded from results.
+   *
+   * ### Sort
+   *
+   * Allowed values:
+   *
+   * - `last_activity:desc` (default), `last_activity:asc`
+   * - `created_at:desc`, `created_at:asc`
+   * - `posts_created:desc`, `posts_created:asc`
+   * - `comments_created:desc`, `comments_created:asc`
+   *
+   * The chosen sort axis is encoded in the cursor; switching `sort` mid-pagination
+   * returns `400 invalid_cursor`. Restart pagination without a cursor when changing
+   * sort.
+   *
+   * ### Pagination
+   *
+   * Cursor-based, `limit` between 1 and 100 (default 10). `totalCount` is
+   * approximate and capped at 5000; `totalCountCapped` is `true` when the real count
+   * may be higher.
+   *
+   * ### Response
+   *
+   * Returns a standard list envelope with contact rows identical to
+   * `GET /v2/contacts/{id}`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.users.contacts.search();
+   * ```
+   */
+  search(params: ContactSearchParams, options?: RequestOptions): APIPromise<ContactSearchResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/contacts/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Unblocks a contact by their Featurebase ID from the messenger/inbox.
    *
@@ -679,6 +779,134 @@ export interface ContactBlockResponse {
  */
 export type ContactCreateOrUpdateResponse = Contact | (null & {});
 
+export interface ContactSearchResponse {
+  /**
+   * Array of search results
+   */
+  data: Array<ContactSearchResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (null if no more results)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Total number of contacts matching the query, capped at 5000. 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 may be higher.
+   */
+  totalCountCapped?: boolean;
+}
+
+export namespace ContactSearchResponse {
+  export interface Data {
+    /**
+     * 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 ContactUnblockResponse {
   /**
    * Unique identifier of the unblocked contact
@@ -885,6 +1113,96 @@ export namespace ContactCreateOrUpdateParams {
   }
 }
 
+export interface ContactSearchParams {
+  /**
+   * 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 (max 15 clauses). Top-level OR groups are not yet supported.
+   */
+  query?: ContactSearchParams.SearchFilter | ContactSearchParams.SearchFilterGroup;
+
+  /**
+   * Body param: Sort field + direction. Defaults to `last_activity:desc` (matches
+   * the dashboard's default contact ordering). The chosen sort axis is encoded in
+   * the cursor; switching `sort` mid-pagination returns `400 invalid_cursor`.
+   */
+  sort?:
+    | 'created_at:desc'
+    | 'created_at:asc'
+    | 'last_activity:desc'
+    | 'last_activity:asc'
+    | 'posts_created:desc'
+    | 'posts_created:asc'
+    | 'comments_created:desc'
+    | 'comments_created: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 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
@@ -904,6 +1222,7 @@ export declare namespace Contacts {
     type ContactRetrieveResponse as ContactRetrieveResponse,
     type ContactBlockResponse as ContactBlockResponse,
     type ContactCreateOrUpdateResponse as ContactCreateOrUpdateResponse,
+    type ContactSearchResponse as ContactSearchResponse,
     type ContactUnblockResponse as ContactUnblockResponse,
     type ContactListDataCursorPage as ContactListDataCursorPage,
     type ContactRetrieveParams as ContactRetrieveParams,
@@ -911,6 +1230,7 @@ export declare namespace Contacts {
     type ContactDeleteParams as ContactDeleteParams,
     type ContactBlockParams as ContactBlockParams,
     type ContactCreateOrUpdateParams as ContactCreateOrUpdateParams,
+    type ContactSearchParams as ContactSearchParams,
     type ContactUnblockParams as ContactUnblockParams,
   };
 

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

@@ -14,12 +14,14 @@ export {
   type ContactRetrieveResponse,
   type ContactBlockResponse,
   type ContactCreateOrUpdateResponse,
+  type ContactSearchResponse,
   type ContactUnblockResponse,
   type ContactRetrieveParams,
   type ContactListParams,
   type ContactDeleteParams,
   type ContactBlockParams,
   type ContactCreateOrUpdateParams,
+  type ContactSearchParams,
   type ContactUnblockParams,
   type ContactListDataCursorPage,
 } from './contacts';

package/src/resources/users/index.ts

@@ -4,11 +4,13 @@ export {
   Companies,
   type Company,
   type DeletedCompany,
+  type CompanySearchResponse,
   type CompanyRetrieveParams,
   type CompanyListParams,
   type CompanyDeleteParams,
   type CompanyCreateOrUpdateParams,
   type CompanyDeleteByCompanyIDParams,
+  type CompanySearchParams,
   type CompaniesCursorPage,
 } from './companies/index';
 export {
@@ -19,12 +21,14 @@ export {
   type ContactRetrieveResponse,
   type ContactBlockResponse,
   type ContactCreateOrUpdateResponse,
+  type ContactSearchResponse,
   type ContactUnblockResponse,
   type ContactRetrieveParams,
   type ContactListParams,
   type ContactDeleteParams,
   type ContactBlockParams,
   type ContactCreateOrUpdateParams,
+  type ContactSearchParams,
   type ContactUnblockParams,
   type ContactListDataCursorPage,
 } from './contacts/index';

package/src/resources/users/users.ts

@@ -11,6 +11,8 @@ import {
   CompanyDeleteParams,
   CompanyListParams,
   CompanyRetrieveParams,
+  CompanySearchParams,
+  CompanySearchResponse,
   DeletedCompany,
 } from './companies/companies';
 import * as ContactsAPI from './contacts/contacts';
@@ -26,6 +28,8 @@ import {
   ContactListParams,
   ContactRetrieveParams,
   ContactRetrieveResponse,
+  ContactSearchParams,
+  ContactSearchResponse,
   ContactUnblockParams,
   ContactUnblockResponse,
   Contacts,
@@ -49,6 +53,7 @@ export declare namespace Users {
     type ContactRetrieveResponse as ContactRetrieveResponse,
     type ContactBlockResponse as ContactBlockResponse,
     type ContactCreateOrUpdateResponse as ContactCreateOrUpdateResponse,
+    type ContactSearchResponse as ContactSearchResponse,
     type ContactUnblockResponse as ContactUnblockResponse,
     type ContactListDataCursorPage as ContactListDataCursorPage,
     type ContactRetrieveParams as ContactRetrieveParams,
@@ -56,6 +61,7 @@ export declare namespace Users {
     type ContactDeleteParams as ContactDeleteParams,
     type ContactBlockParams as ContactBlockParams,
     type ContactCreateOrUpdateParams as ContactCreateOrUpdateParams,
+    type ContactSearchParams as ContactSearchParams,
     type ContactUnblockParams as ContactUnblockParams,
   };
 
@@ -63,11 +69,13 @@ export declare namespace Users {
     Companies as Companies,
     type Company as Company,
     type DeletedCompany as DeletedCompany,
+    type CompanySearchResponse as CompanySearchResponse,
     type CompaniesCursorPage as CompaniesCursorPage,
     type CompanyRetrieveParams as CompanyRetrieveParams,
     type CompanyListParams as CompanyListParams,
     type CompanyDeleteParams as CompanyDeleteParams,
     type CompanyCreateOrUpdateParams as CompanyCreateOrUpdateParams,
     type CompanyDeleteByCompanyIDParams as CompanyDeleteByCompanyIDParams,
+    type CompanySearchParams as CompanySearchParams,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.10.0'; // x-release-please-version
+export const VERSION = '0.11.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.11.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.11.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.10.0'; // x-release-please-version
+exports.VERSION = '0.11.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.10.0'; // x-release-please-version
+export const VERSION = '0.11.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map