featurebase-node 0.10.0 → 0.12.0

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

@@ -342,6 +342,137 @@ export class Articles extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Search help-center articles by structured filters and/or hybrid full-text
+   * search, with sort and cursor pagination.
+   *
+   * This endpoint mirrors `POST /v2/conversations/search`. Two modes, dispatched off
+   * whether you pass `search`:
+   *
+   * - **Filter mode** (no `search`): the structured `query` AST is translated to a
+   *   Mongo predicate and paginated by `sort` + cursor. Same semantics as
+   *   `POST /v2/companies/search` and `POST /v2/contacts/search`.
+   * - **Search mode** (`search` set): the free-text query runs as a hybrid (vector +
+   *   BM25) search against the same article namespace the help-center copilot uses.
+   *   Hits are then survivor-pruned in Mongo against the structured `query` AST and
+   *   `organizationId`.
+   *
+   * `query` and `search` are independent and may be combined freely. An empty body
+   * lists everything for the org.
+   *
+   * ### Hybrid full-text search (`search`)
+   *
+   * ```json
+   * { "search": "how to set up sso" }
+   * ```
+   *
+   * - Free-form text, 1–500 chars. Server-managed: no operators, no field selection.
+   * - Hybrid (vector embedding + BM25 keyword) ranking. Results are returned in
+   *   relevance order unless you also pass `sort`, in which case the
+   *   relevance-matched survivor set is reordered along that axis.
+   * - Top 200 ranked articles are kept per request and paginated in-memory; the same
+   *   ranking is stable across pages.
+   * - May be combined with `query` to scope (e.g. `search` +
+   *   `{ help_center_id = "..." }`).
+   *
+   * ### 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": "help_center_id",
+   *         "operator": "=",
+   *         "value": "j7c5g8ah3ewxp4lo"
+   *       },
+   *       { "field": "state", "operator": "=", "value": "draft" },
+   *       { "field": "updated_at", "operator": ">", "value": 1735689600 }
+   *     ]
+   *   },
+   *   "sort": "updated_at:desc",
+   *   "limit": 20
+   * }
+   * ```
+   *
+   * Top-level `OR` groups and nested groups are not supported in this version.
+   *
+   * ### Supported AST fields and operators
+   *
+   * | Field            | Type                     | Operators                       |
+   * | ---------------- | ------------------------ | ------------------------------- |
+   * | `id`             | string (article id)      | `=`, `!=`, `IN`, `NIN`          |
+   * | `help_center_id` | string                   | `=`, `!=`, `IN`, `NIN`          |
+   * | `parent_id`      | string (collection id)   | `=`, `!=`, `IN`, `NIN`          |
+   * | `author_id`      | string                   | `=`, `!=`, `IN`, `NIN`          |
+   * | `slug`           | string                   | `=`, `!=`, `IN`, `NIN`          |
+   * | `state`          | enum (`live` \| `draft`) | `=`, `!=`, `IN`, `NIN`          |
+   * | `created_at`     | unix seconds             | `=`, `!=`, `>`, `<`, `>=`, `<=` |
+   * | `updated_at`     | unix seconds             | `=`, `!=`, `>`, `<`, `>=`, `<=` |
+   *
+   * There is no AST-level full-text field. The string operators `~`, `!~`, `^`, `$`
+   * are reserved for future structured-text use and currently return `400` - use the
+   * top-level `search` sibling for free-text matching.
+   *
+   * `state` is derived from each help center's default-locale translation:
+   * `state = "live"` matches articles with a published `live` translation in their
+   * HC's default locale; `state = "draft"` matches the draft equivalent. Same
+   * semantics as the `state` query param on `GET /v2/help_center/articles`.
+   *
+   * ### Sort
+   *
+   * Allowed values: `created_at:desc` (default in filter mode), `created_at:asc`,
+   * `updated_at:desc`, `updated_at:asc`.
+   *
+   * In **search mode**, omitting `sort` returns results in relevance order. Passing
+   * `sort` reorders the relevance survivor set chronologically.
+   *
+   * The chosen mode + sort axis is encoded in the cursor; switching mode or axis
+   * mid-pagination returns `400 invalid_cursor`. Restart pagination without a cursor
+   * when changing.
+   *
+   * ### Pagination
+   *
+   * Cursor-based, `limit` between 1 and 100 (default 10). In filter mode,
+   * `totalCount` is approximate and capped at 5 000. In search mode, `totalCount` is
+   * exact within the 200-row top-K window and `totalCountCapped` is `true` when that
+   * cap is hit.
+   *
+   * ### Response
+   *
+   * Returns a standard list envelope with article rows identical to
+   * `GET /v2/help_center/articles/{id}` (including translations, hydrated against
+   * each article's parent help center default locale).
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.helpCenter.articles.search();
+   * ```
+   */
+  search(params: ArticleSearchParams, options?: RequestOptions): APIPromise<ArticleSearchResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/help_center/articles/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
 }
 
 export type ArticlesCursorPage = CursorPage<Article>;
@@ -892,6 +1023,466 @@ export interface ArticleDeleteResponse {
   object: 'article';
 }
 
+export interface ArticleSearchResponse {
+  /**
+   * Array of search results
+   */
+  data: Array<ArticleSearchResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (null if no more results)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Total number of articles 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 ArticleSearchResponse {
+  export interface Data {
+    /**
+     * Article unique identifier
+     */
+    id: string;
+
+    /**
+     * Available locales
+     */
+    availableLocales: Array<
+      | 'bn'
+      | 'bs'
+      | 'pt-BR'
+      | 'bg'
+      | 'ca'
+      | 'hr'
+      | 'cs'
+      | 'da'
+      | 'nl'
+      | 'en'
+      | 'et'
+      | 'fi'
+      | 'fr'
+      | 'de'
+      | 'el'
+      | 'hi'
+      | 'hu'
+      | 'id'
+      | 'it'
+      | 'ja'
+      | 'ko'
+      | 'lv'
+      | 'lt'
+      | 'ms'
+      | 'mn'
+      | 'nb'
+      | 'pl'
+      | 'pt'
+      | 'ro'
+      | 'ru'
+      | 'sr'
+      | 'zh-CN'
+      | 'sk'
+      | 'sl'
+      | 'es'
+      | 'sw'
+      | 'sv'
+      | 'th'
+      | 'zh-TW'
+      | 'tr'
+      | 'uk'
+      | 'vi'
+    >;
+
+    /**
+     * ISO 8601 timestamp when created
+     */
+    createdAt: string;
+
+    /**
+     * Help Center ID
+     */
+    helpCenterId: string;
+
+    /**
+     * Current locale
+     */
+    locale:
+      | 'bn'
+      | 'bs'
+      | 'pt-BR'
+      | 'bg'
+      | 'ca'
+      | 'hr'
+      | 'cs'
+      | 'da'
+      | 'nl'
+      | 'en'
+      | 'et'
+      | 'fi'
+      | 'fr'
+      | 'de'
+      | 'el'
+      | 'hi'
+      | 'hu'
+      | 'id'
+      | 'it'
+      | 'ja'
+      | 'ko'
+      | 'lv'
+      | 'lt'
+      | 'ms'
+      | 'mn'
+      | 'nb'
+      | 'pl'
+      | 'pt'
+      | 'ro'
+      | 'ru'
+      | 'sr'
+      | 'zh-CN'
+      | 'sk'
+      | 'sl'
+      | 'es'
+      | 'sw'
+      | 'sv'
+      | 'th'
+      | 'zh-TW'
+      | 'tr'
+      | 'uk'
+      | 'vi';
+
+    /**
+     * Object type identifier
+     */
+    object: 'article';
+
+    /**
+     * Organization ID
+     */
+    organization: string;
+
+    /**
+     * Article state
+     */
+    state: 'live' | 'draft';
+
+    /**
+     * ISO 8601 timestamp when last updated
+     */
+    updatedAt: string;
+
+    /**
+     * Article author
+     */
+    author?: ArticlesAPI.ArticleAuthor;
+
+    /**
+     * Article body content (HTML)
+     */
+    body?: string;
+
+    /**
+     * Default locale
+     */
+    defaultLocale?:
+      | 'bn'
+      | 'bs'
+      | 'pt-BR'
+      | 'bg'
+      | 'ca'
+      | 'hr'
+      | 'cs'
+      | 'da'
+      | 'nl'
+      | 'en'
+      | 'et'
+      | 'fi'
+      | 'fr'
+      | 'de'
+      | 'el'
+      | 'hi'
+      | 'hu'
+      | 'id'
+      | 'it'
+      | 'ja'
+      | 'ko'
+      | 'lv'
+      | 'lt'
+      | 'ms'
+      | 'mn'
+      | 'nb'
+      | 'pl'
+      | 'pt'
+      | 'ro'
+      | 'ru'
+      | 'sr'
+      | 'zh-CN'
+      | 'sk'
+      | 'sl'
+      | 'es'
+      | 'sw'
+      | 'sv'
+      | 'th'
+      | 'zh-TW'
+      | 'tr'
+      | 'uk'
+      | 'vi';
+
+    /**
+     * Article description
+     */
+    description?: string;
+
+    /**
+     * External URL
+     */
+    externalUrl?: string;
+
+    /**
+     * Featurebase URL
+     */
+    featurebaseUrl?: string;
+
+    /**
+     * Article icon
+     */
+    icon?: Data.Icon | null;
+
+    /**
+     * Whether draft differs from live
+     */
+    isDraftDiffersFromLive?: boolean;
+
+    /**
+     * Whether the article is published
+     */
+    isPublished?: boolean;
+
+    /**
+     * ISO 8601 timestamp when live version was last updated
+     */
+    liveUpdatedAt?: string;
+
+    /**
+     * Display order
+     */
+    order?: number | null;
+
+    /**
+     * Parent collection ID
+     */
+    parentId?: string | null;
+
+    /**
+     * Path to article within help center hierarchy
+     */
+    path?: string;
+
+    /**
+     * Published locales
+     */
+    publishedLocales?: Array<
+      | 'bn'
+      | 'bs'
+      | 'pt-BR'
+      | 'bg'
+      | 'ca'
+      | 'hr'
+      | 'cs'
+      | 'da'
+      | 'nl'
+      | 'en'
+      | 'et'
+      | 'fi'
+      | 'fr'
+      | 'de'
+      | 'el'
+      | 'hi'
+      | 'hu'
+      | 'id'
+      | 'it'
+      | 'ja'
+      | 'ko'
+      | 'lv'
+      | 'lt'
+      | 'ms'
+      | 'mn'
+      | 'nb'
+      | 'pl'
+      | 'pt'
+      | 'ro'
+      | 'ru'
+      | 'sr'
+      | 'zh-CN'
+      | 'sk'
+      | 'sl'
+      | 'es'
+      | 'sw'
+      | 'sv'
+      | 'th'
+      | 'zh-TW'
+      | 'tr'
+      | 'uk'
+      | 'vi'
+    >;
+
+    /**
+     * URL slug
+     */
+    slug?: string;
+
+    /**
+     * Associated survey ID
+     */
+    surveyId?: string;
+
+    /**
+     * Article title
+     */
+    title?: string;
+
+    /**
+     * ISO 8601 timestamp when translation was created
+     */
+    translationCreatedAt?: string;
+
+    /**
+     * Translations by locale code
+     */
+    translations?: Data.Translations;
+
+    /**
+     * ISO 8601 timestamp when translation was last updated
+     */
+    translationUpdatedAt?: string;
+
+    /**
+     * Visibility settings
+     */
+    visibleBy?: Array<string>;
+  }
+
+  export namespace Data {
+    /**
+     * Article icon
+     */
+    export interface Icon {
+      /**
+       * Icon type
+       */
+      type: 'emoji' | 'custom';
+
+      /**
+       * Icon value (emoji or URL)
+       */
+      value: string;
+    }
+
+    /**
+     * Translations by locale code
+     */
+    export interface Translations {
+      id?: ArticlesAPI.ArticleTranslation;
+
+      bg?: ArticlesAPI.ArticleTranslation;
+
+      bn?: ArticlesAPI.ArticleTranslation;
+
+      bs?: ArticlesAPI.ArticleTranslation;
+
+      ca?: ArticlesAPI.ArticleTranslation;
+
+      cs?: ArticlesAPI.ArticleTranslation;
+
+      da?: ArticlesAPI.ArticleTranslation;
+
+      de?: ArticlesAPI.ArticleTranslation;
+
+      el?: ArticlesAPI.ArticleTranslation;
+
+      en?: ArticlesAPI.ArticleTranslation;
+
+      es?: ArticlesAPI.ArticleTranslation;
+
+      et?: ArticlesAPI.ArticleTranslation;
+
+      fi?: ArticlesAPI.ArticleTranslation;
+
+      fr?: ArticlesAPI.ArticleTranslation;
+
+      hi?: ArticlesAPI.ArticleTranslation;
+
+      hr?: ArticlesAPI.ArticleTranslation;
+
+      hu?: ArticlesAPI.ArticleTranslation;
+
+      it?: ArticlesAPI.ArticleTranslation;
+
+      ja?: ArticlesAPI.ArticleTranslation;
+
+      ko?: ArticlesAPI.ArticleTranslation;
+
+      lt?: ArticlesAPI.ArticleTranslation;
+
+      lv?: ArticlesAPI.ArticleTranslation;
+
+      mn?: ArticlesAPI.ArticleTranslation;
+
+      ms?: ArticlesAPI.ArticleTranslation;
+
+      nb?: ArticlesAPI.ArticleTranslation;
+
+      nl?: ArticlesAPI.ArticleTranslation;
+
+      pl?: ArticlesAPI.ArticleTranslation;
+
+      pt?: ArticlesAPI.ArticleTranslation;
+
+      'pt-BR'?: ArticlesAPI.ArticleTranslation;
+
+      ro?: ArticlesAPI.ArticleTranslation;
+
+      ru?: ArticlesAPI.ArticleTranslation;
+
+      sk?: ArticlesAPI.ArticleTranslation;
+
+      sl?: ArticlesAPI.ArticleTranslation;
+
+      sr?: ArticlesAPI.ArticleTranslation;
+
+      sv?: ArticlesAPI.ArticleTranslation;
+
+      sw?: ArticlesAPI.ArticleTranslation;
+
+      th?: ArticlesAPI.ArticleTranslation;
+
+      tr?: ArticlesAPI.ArticleTranslation;
+
+      uk?: ArticlesAPI.ArticleTranslation;
+
+      vi?: ArticlesAPI.ArticleTranslation;
+
+      'zh-CN'?: ArticlesAPI.ArticleTranslation;
+
+      'zh-TW'?: ArticlesAPI.ArticleTranslation;
+    }
+  }
+}
+
 export interface ArticleCreateParams {
   /**
    * Body param: The title of the article
@@ -1238,6 +1829,99 @@ export interface ArticleDeleteParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
+export interface ArticleSearchParams {
+  /**
+   * Body param: An opaque cursor for pagination. Use the `nextCursor` value from a
+   * previous response to fetch the next page of results. The pagination keyset
+   * (relevance score in search mode, sort-axis value in filter mode) is encoded in
+   * the cursor; switching mode mid-pagination returns `400 invalid_cursor`.
+   */
+  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?: ArticleSearchParams.SearchFilter | ArticleSearchParams.SearchFilterGroup;
+
+  /**
+   * Body param: Plain-text full-text search across article title, description, and
+   * body. Hybrid (vector + BM25) ranking via the same Turbopuffer namespace the
+   * help-center copilot uses - server-managed, no operators, no field selection.
+   * When set, results come back ranked by relevance unless `sort` is also passed (in
+   * which case the relevance-matched set is reordered along that axis).
+   */
+  search?: string;
+
+  /**
+   * 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' | 'updated_at:desc' | 'updated_at: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 ArticleSearchParams {
+  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 declare namespace Articles {
   export {
     type Article as Article,
@@ -1246,11 +1930,13 @@ export declare namespace Articles {
     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,
   };
 }