featurebase-node 0.10.0 → 0.12.0

package/src/resources/help-center/help-center.ts

@@ -11,6 +11,8 @@ import {
   ArticleIconInputNova,
   ArticleListParams,
   ArticleRetrieveParams,
+  ArticleSearchParams,
+  ArticleSearchResponse,
   ArticleTranslation,
   ArticleTranslationInputNova,
   ArticleUpdateParams,
@@ -102,12 +104,14 @@ export declare namespace HelpCenter {
     type ArticleTranslation as ArticleTranslation,
     type ArticleTranslationInputNova as ArticleTranslationInputNova,
     type ArticleDeleteResponse as ArticleDeleteResponse,
+    type ArticleSearchResponse as ArticleSearchResponse,
     type ArticlesCursorPage as ArticlesCursorPage,
     type ArticleCreateParams as ArticleCreateParams,
     type ArticleRetrieveParams as ArticleRetrieveParams,
     type ArticleUpdateParams as ArticleUpdateParams,
     type ArticleListParams as ArticleListParams,
     type ArticleDeleteParams as ArticleDeleteParams,
+    type ArticleSearchParams as ArticleSearchParams,
   };
 
   export {

package/src/resources/help-center/index.ts

@@ -8,11 +8,13 @@ export {
   type ArticleTranslation,
   type ArticleTranslationInputNova,
   type ArticleDeleteResponse,
+  type ArticleSearchResponse,
   type ArticleCreateParams,
   type ArticleRetrieveParams,
   type ArticleUpdateParams,
   type ArticleListParams,
   type ArticleDeleteParams,
+  type ArticleSearchParams,
   type ArticlesCursorPage,
 } from './articles';
 export {

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

@@ -946,7 +946,9 @@ export class Conversations extends APIResource {
    *   `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.
+   *   filters apply. Results are ranked by relevance by default; set `sort` to order
+   *   by `lastActivityAt` instead (the same query string still gates which
+   *   conversations appear, only their ordering changes).
    *
    * ### Structured query AST
    *
@@ -3596,9 +3598,7 @@ export interface ConversationSearchParams {
    * top-level AND group. Use this for filtering by `state`, `tag_ids`,
    * `admin_assignee_id`, etc.
    */
-  query?:
-    | ConversationSearchParams.ConversationSearchFilter
-    | ConversationSearchParams.ConversationSearchFilterGroup;
+  query?: ConversationSearchParams.SearchFilter | ConversationSearchParams.SearchFilterGroup;
 
   /**
    * Body param: Plain-text full-text search across conversation messages.
@@ -3607,8 +3607,10 @@ export interface ConversationSearchParams {
   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.
+   * Body param: Result ordering. When omitted, filter mode defaults to
+   * last_activity_at:desc and search mode defaults to relevance ranking. When set,
+   * both modes order by lastActivityAt in the requested direction (so you can ask a
+   * search query to return its hits in chronological order).
    */
   sort?: 'last_activity_at:desc' | 'last_activity_at:asc';
 
@@ -3620,7 +3622,7 @@ export interface ConversationSearchParams {
 }
 
 export namespace ConversationSearchParams {
-  export interface ConversationSearchFilter {
+  export interface SearchFilter {
     /**
      * Field name to filter on (e.g. `state`, `tag_ids`, `created_at`)
      */
@@ -3629,7 +3631,7 @@ export namespace ConversationSearchParams {
     /**
      * Comparison operator
      */
-    operator: '=' | '!=' | 'IN' | 'NIN' | '>' | '<' | '~' | '!~' | '^' | '$';
+    operator: '=' | '!=' | 'IN' | 'NIN' | '>' | '<' | '>=' | '<=' | '~' | '!~' | '^' | '$';
 
     /**
      * Value to compare against (primitive or array of primitives)
@@ -3637,7 +3639,7 @@ export namespace ConversationSearchParams {
     value: string | number | boolean | Array<string | number> | null;
   }
 
-  export interface ConversationSearchFilterGroup {
+  export interface SearchFilterGroup {
     /**
      * Group operator: AND (all match) or OR (any match)
      */
@@ -3646,10 +3648,10 @@ export namespace ConversationSearchParams {
     /**
      * Array of filter clauses (1-15 entries)
      */
-    value: Array<ConversationSearchFilterGroup.Value>;
+    value: Array<SearchFilterGroup.Value>;
   }
 
-  export namespace ConversationSearchFilterGroup {
+  export namespace SearchFilterGroup {
     export interface Value {
       /**
        * Field name to filter on (e.g. `state`, `tag_ids`, `created_at`)
@@ -3659,7 +3661,7 @@ export namespace ConversationSearchParams {
       /**
        * Comparison operator
        */
-      operator: '=' | '!=' | 'IN' | 'NIN' | '>' | '<' | '~' | '!~' | '^' | '$';
+      operator: '=' | '!=' | 'IN' | 'NIN' | '>' | '<' | '>=' | '<=' | '~' | '!~' | '^' | '$';
 
       /**
        * Value to compare against (primitive or array of primitives)

package/src/resources/users/companies/companies.ts

@@ -411,6 +411,101 @@ export class Companies extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Search companies 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": "plan", "operator": "IN", "value": ["enterprise", "pro"] },
+   *       { "field": "monthly_spend", "operator": ">", "value": 1000 }
+   *     ]
+   *   },
+   *   "sort": "monthly_spend: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 company id) | `=`, `!=`, `IN`, `NIN`      |
+   * | `name`          | string                              | `=`, `!=`, `IN`, `NIN`, `~` |
+   * | `monthly_spend` | number                              | `=`, `!=`, `>`, `<`         |
+   * | `plan`          | string                              | `=`, `!=`, `IN`, `NIN`      |
+   * | `industry`      | string                              | `=`, `!=`, `IN`, `NIN`      |
+   * | `website`       | string                              | `=`, `!=`, `IN`, `NIN`      |
+   * | `company_size`  | number                              | `=`, `!=`, `>`, `<`         |
+   * | `linked_users`  | 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 is rejected with
+   * `query_too_broad` to prevent full-org scans. Combine the negation with at least
+   * one positive clause (`=`, `IN`, `>`, `<`) instead.
+   *
+   * ### Sort
+   *
+   * Allowed values:
+   *
+   * - `created_at:desc` (default), `created_at:asc`
+   * - `monthly_spend:desc`, `monthly_spend:asc`
+   * - `last_activity:desc`, `last_activity: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 company rows identical to
+   * `GET /v2/companies/{id}`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.users.companies.search();
+   * ```
+   */
+  search(params: CompanySearchParams, options?: RequestOptions): APIPromise<CompanySearchResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/companies/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
 }
 
 export type CompaniesCursorPage = CursorPage<Company>;
@@ -504,6 +599,110 @@ export interface DeletedCompany {
   object: 'company';
 }
 
+export interface CompanySearchResponse {
+  /**
+   * Array of search results
+   */
+  data: Array<CompanySearchResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (null if no more results)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Total number of companies 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. UI
+   * can render as e.g. "5000+".
+   */
+  totalCountCapped?: boolean;
+}
+
+export namespace CompanySearchResponse {
+  export interface Data {
+    /**
+     * Featurebase internal ID
+     */
+    id: string;
+
+    /**
+     * External company ID from your system
+     */
+    companyId: string;
+
+    /**
+     * Company employee headcount
+     */
+    companySize: number | null;
+
+    /**
+     * ISO date when company was created
+     */
+    createdAt: string | null;
+
+    /**
+     * Industry
+     */
+    industry: string | null;
+
+    /**
+     * ISO date of last activity
+     */
+    lastActivity: string | null;
+
+    /**
+     * Number of users linked to this company
+     */
+    linkedUsers: number | null;
+
+    /**
+     * Monthly spend
+     */
+    monthlySpend: number | null;
+
+    /**
+     * Company name
+     */
+    name: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'company';
+
+    /**
+     * Plan or tier name
+     */
+    plan: string | null;
+
+    /**
+     * ISO date when company was last updated
+     */
+    updatedAt: string | null;
+
+    /**
+     * Company website URL
+     */
+    website: string | null;
+
+    /**
+     * Custom field values
+     */
+    customFields?: { [key: string]: unknown };
+  }
+}
+
 export interface CompanyRetrieveParams {
   /**
    * API version for this request. Defaults to your organization's configured API
@@ -605,18 +804,108 @@ export interface CompanyDeleteByCompanyIDParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
+export interface CompanySearchParams {
+  /**
+   * 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?: CompanySearchParams.SearchFilter | CompanySearchParams.SearchFilterGroup;
+
+  /**
+   * Body param: Sort field + direction. Defaults to `created_at:desc`. The chosen
+   * sort axis is encoded in the cursor; switching `sort` mid-pagination returns
+   * `400 invalid_cursor`.
+   */
+  sort?:
+    | 'created_at:desc'
+    | 'created_at:asc'
+    | 'monthly_spend:desc'
+    | 'monthly_spend:asc'
+    | 'last_activity:desc'
+    | 'last_activity: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 CompanySearchParams {
+  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;
+    }
+  }
+}
+
 Companies.Contacts = Contacts;
 
 export declare namespace Companies {
   export {
     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,
   };
 
   export {

package/src/resources/users/companies/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';
 export {