featurebase-node 0.12.0 → 0.13.0

package/src/resources/feedback/comments.ts

@@ -438,6 +438,167 @@ export class Comments extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Search comments with a structured filter AST, full-text search, sorting, and
+   * cursor pagination.
+   *
+   * ### Two modes (combinable)
+   *
+   * - **Filter mode** — pass a structured `query` AST (and/or `sort`) and the
+   *   endpoint returns comments matching the filter, ordered by `sort` (default
+   *   `createdAt:desc`). Same shape as `/v2/posts/search`,
+   *   `/v2/conversations/search`, `/v2/companies/search`, `/v2/contacts/search`.
+   * - **Search mode** — pass a top-level `search` string and the endpoint runs a
+   *   hybrid full-text + vector search over comment `content`, returning matches
+   *   ranked by relevance. Optional: combine with `query` to constrain the search to
+   *   a post / changelog / author / time window, and/or `sort` to override relevance
+   *   ranking with chronological order.
+   *
+   * ```json
+   * {
+   *   "search": "dark mode feedback",
+   *   "query": {
+   *     "operator": "AND",
+   *     "value": [
+   *       {
+   *         "field": "postId",
+   *         "operator": "=",
+   *         "value": "507f1f77bcf86cd799439011"
+   *       }
+   *     ]
+   *   },
+   *   "limit": 20
+   * }
+   * ```
+   *
+   * `search` is server-managed: no operators, no field selection, no special syntax
+   * — same plain-text contract as `/v2/posts/search`. The string must be 1–500
+   * characters.
+   *
+   * ### 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. To list every comment a
+   * contact has authored:
+   *
+   * ```json
+   * {
+   *   "query": {
+   *     "field": "authorId",
+   *     "operator": "=",
+   *     "value": "507f1f77bcf86cd799439011"
+   *   },
+   *   "sort": "createdAt:desc",
+   *   "limit": 100
+   * }
+   * ```
+   *
+   * Top-level `OR` groups and nested groups are not supported in this version.
+   *
+   * ### Supported fields and operators
+   *
+   * Field names are camelCase, matching the rest of the v2 public API. The other v2
+   * search endpoints (posts, contacts, companies, conversations) shipped earlier
+   * with snake_case field names and continue to accept those for back-compat;
+   * comments search is greenfield and ships with camelCase only.
+   *
+   * | Field                                 | Type                    | Operators                                                                   |
+   * | ------------------------------------- | ----------------------- | --------------------------------------------------------------------------- |
+   * | `authorId`                            | string (user id)        | `=`, `!=`, `IN`, `NIN`                                                      |
+   * | `postId`                              | id or null (submission) | `=`, `!=`, `IN`, `NIN` (use `null` for changelog-only comments)             |
+   * | `changelogId`                         | id or null              | `=`, `!=`, `IN`, `NIN` (use `null` for post-only comments)                  |
+   * | `parentCommentId`                     | id or null              | `=`, `!=`, `IN`, `NIN` (use `null` for root comments, non-null for replies) |
+   * | `isPrivate`                           | boolean                 | `=`, `!=`                                                                   |
+   * | `inReview`                            | boolean                 | `=`, `!=`                                                                   |
+   * | `createdAt`                           | unix seconds            | `=`, `!=`, `>`, `<`, `>=`, `<=`                                             |
+   * | `upvotes`, `score`, `confidenceScore` | number                  | `=`, `!=`, `>`, `<`, `>=`, `<=`                                             |
+   *
+   * Use the top-level `search` field for full-text search across comment `content`
+   * (see "Search mode" above). The clause-level operators `~`, `!~`, `^`, `$` are
+   * reserved for future use and currently return `400`.
+   *
+   * A filter-mode query (no `search`) 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. Boolean fields (`isPrivate`, `inReview`) are bounded so a standalone
+   * negation on them is allowed. Search mode (with `search` set) relaxes this — the
+   * FTS query itself acts as the positive constraint.
+   *
+   * ### Sort
+   *
+   * Allowed values:
+   *
+   * - `createdAt:desc` (default in filter mode), `createdAt:asc` — newest / oldest
+   *   first
+   * - `confidenceScore:desc` (the dashboard's "Best" view), `confidenceScore:asc`
+   *   (low-confidence first, useful for moderation)
+   * - `score:desc` — raw upvotes − downvotes ("Top")
+   *
+   * Numeric counters (`upvotes`, `score`, `confidenceScore`) remain available as
+   * filter fields with the full range of operators; only the sort axes above are
+   * surfaced to keep the cursor-pagination contract small. `score:asc` and `upvotes`
+   * (both directions) are deliberately not exposed: `upvotes:desc` is identical to
+   * `score:desc` for the vast majority of comments (no downvotes), and
+   * "most-downvoted-first" / "least-upvoted-first" have no product use case.
+   *
+   * When `search` is set, results are ranked by relevance unless `sort` is also set,
+   * in which case the matching comments are returned in the requested order. The
+   * chosen sort axis (or relevance) is encoded in the cursor; switching `sort` (or
+   * toggling `search` on/off) mid-pagination returns `400 invalid_cursor`. Restart
+   * pagination without a cursor when changing the sort or search shape.
+   *
+   * ### Pagination
+   *
+   * Cursor-based, `limit` between 1 and 100 (default 10). In filter mode,
+   * `totalCount` is approximate and capped at 5000; `totalCountCapped` is `true`
+   * when the real count may be higher. In search mode, `totalCount` reflects the
+   * matching survivor set after the AST filter and is capped at 200 (the Turbopuffer
+   * top-K).
+   *
+   * ### Server-side guards
+   *
+   * These visibility rules are always applied and CANNOT be widened via the AST:
+   *
+   * - Callers without the `view_comments_private` permission can only see public
+   *   comments. Sending `{ field: "isPrivate", operator: "=", value: true }` as such
+   *   a caller returns an empty result, NOT a 403 — the security floor wins.
+   * - Callers without the `moderate_comments` permission can only see in-review
+   *   comments they authored themselves. `inReview` queries from such callers are
+   *   intersected with the authored-by-self constraint.
+   * - Spam comments (`isSpam: true`) are NOT excluded — this matches the legacy
+   *   `GET /v2/comments` behavior. If you want to exclude spam, filter on the
+   *   `isSpam` field (NOT exposed today; track follow-up).
+   *
+   * ### Response
+   *
+   * Returns a standard list envelope with comment rows identical to
+   * `GET /v2/comments/{id}`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.feedback.comments.search();
+   * ```
+   */
+  search(params: CommentSearchParams, options?: RequestOptions): APIPromise<CommentSearchResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/comments/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
 }
 
 export type CommentsCursorPage = CursorPage<Comment>;
@@ -571,6 +732,146 @@ export interface CommentDelete1Response {
   success: boolean;
 }
 
+export interface CommentSearchResponse {
+  /**
+   * Array of search results
+   */
+  data: Array<CommentSearchResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (null if no more results)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Total number of comments matching the query, capped at 5000 in filter mode and
+   * 200 (the Turbopuffer top-K) in search mode. When at 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 CommentSearchResponse {
+  export interface Data {
+    /**
+     * Unique identifier
+     */
+    id: string;
+
+    author: Data.Author | null;
+
+    /**
+     * Changelog ID this comment belongs to
+     */
+    changelogId: string | null;
+
+    /**
+     * Comment content in HTML format
+     */
+    content: string;
+
+    /**
+     * ISO 8601 timestamp when created
+     */
+    createdAt: string;
+
+    /**
+     * Number of downvotes
+     */
+    downvotes: number;
+
+    /**
+     * Whether the comment is in review
+     */
+    inReview: boolean;
+
+    /**
+     * Whether the comment is deleted
+     */
+    isDeleted: boolean;
+
+    /**
+     * Whether the comment is pinned
+     */
+    isPinned: boolean;
+
+    /**
+     * Whether the comment is private
+     */
+    isPrivate: boolean;
+
+    /**
+     * Whether the comment is spam
+     */
+    isSpam: boolean;
+
+    /**
+     * Object type identifier
+     */
+    object: 'comment';
+
+    /**
+     * Parent comment ID for replies, null for root comments
+     */
+    parentCommentId: string | null;
+
+    /**
+     * Post ID this comment belongs to
+     */
+    postId: string | null;
+
+    /**
+     * Net score (upvotes - downvotes)
+     */
+    score: number;
+
+    /**
+     * ISO 8601 timestamp when updated
+     */
+    updatedAt: string;
+
+    /**
+     * Number of upvotes
+     */
+    upvotes: number;
+  }
+
+  export namespace Data {
+    export interface Author {
+      /**
+       * Author unique identifier
+       */
+      id: string | null;
+
+      /**
+       * Author display name
+       */
+      name: string;
+
+      /**
+       * Author profile picture URL
+       */
+      profilePicture: string | null;
+
+      /**
+       * Type of user who authored the comment
+       */
+      type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
+    }
+  }
+}
+
 export interface CommentCreateParams {
   /**
    * Body param: Comment content in HTML format
@@ -741,11 +1042,105 @@ export interface CommentDelete1Params {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
+export interface CommentSearchParams {
+  /**
+   * 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?: CommentSearchParams.SearchFilter | CommentSearchParams.SearchFilterGroup;
+
+  /**
+   * Body param: Plain-text full-text search across comment `content`. Server-managed
+   * (hybrid BM25 + vector, semanticRatio 0.5) — no operators, no field selection.
+   * When `search` is set, results are ranked by relevance unless `sort` is also set,
+   * in which case the matching comments are returned in the requested order. Combine
+   * with `query` to constrain the search to a post / changelog / author / time
+   * window.
+   */
+  search?: string;
+
+  /**
+   * Body param: Sort field + direction. Defaults to `createdAt:desc` in filter mode
+   * and to relevance in search mode. The chosen sort axis is encoded in the cursor;
+   * switching `sort` (or toggling `search` on/off) mid-pagination returns
+   * `400 invalid_cursor`.
+   */
+  sort?: 'createdAt:desc' | 'createdAt:asc' | 'confidenceScore:desc' | 'confidenceScore:asc' | 'score:desc';
+
+  /**
+   * 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 CommentSearchParams {
+  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 Comments {
   export {
     type Comment as Comment,
     type CommentDelete0Response as CommentDelete0Response,
     type CommentDelete1Response as CommentDelete1Response,
+    type CommentSearchResponse as CommentSearchResponse,
     type CommentsCursorPage as CommentsCursorPage,
     type CommentCreateParams as CommentCreateParams,
     type CommentRetrieveParams as CommentRetrieveParams,
@@ -753,5 +1148,6 @@ export declare namespace Comments {
     type CommentListParams as CommentListParams,
     type CommentDelete0Params as CommentDelete0Params,
     type CommentDelete1Params as CommentDelete1Params,
+    type CommentSearchParams as CommentSearchParams,
   };
 }

package/src/resources/feedback/feedback.ts

@@ -13,6 +13,8 @@ import {
   CommentDelete1Response,
   CommentListParams,
   CommentRetrieveParams,
+  CommentSearchParams,
+  CommentSearchResponse,
   CommentUpdateParams,
   Comments,
   CommentsCursorPage,
@@ -98,6 +100,7 @@ export declare namespace Feedback {
     type Comment as Comment,
     type CommentDelete0Response as CommentDelete0Response,
     type CommentDelete1Response as CommentDelete1Response,
+    type CommentSearchResponse as CommentSearchResponse,
     type CommentsCursorPage as CommentsCursorPage,
     type CommentCreateParams as CommentCreateParams,
     type CommentRetrieveParams as CommentRetrieveParams,
@@ -105,6 +108,7 @@ export declare namespace Feedback {
     type CommentListParams as CommentListParams,
     type CommentDelete0Params as CommentDelete0Params,
     type CommentDelete1Params as CommentDelete1Params,
+    type CommentSearchParams as CommentSearchParams,
   };
 
   export {

package/src/resources/feedback/index.ts

@@ -12,12 +12,14 @@ export {
   type Comment,
   type CommentDelete0Response,
   type CommentDelete1Response,
+  type CommentSearchResponse,
   type CommentCreateParams,
   type CommentRetrieveParams,
   type CommentUpdateParams,
   type CommentListParams,
   type CommentDelete0Params,
   type CommentDelete1Params,
+  type CommentSearchParams,
   type CommentsCursorPage,
 } from './comments';
 export {

package/src/resources/feedback/posts/posts.ts

@@ -322,7 +322,7 @@ export class Posts extends APIResource {
    *
    * - **Filter mode** — pass a structured `query` AST (and/or `sort`) and the
    *   endpoint returns posts matching the filter, ordered by `sort` (default
-   *   `created_at:desc`). Same shape as `/v2/conversations/search`,
+   *   `createdAt:desc`). Same shape as `/v2/conversations/search`,
    *   `/v2/companies/search`, `/v2/contacts/search`.
    * - **Search mode** — pass a top-level `search` string and the endpoint runs a
    *   hybrid full-text + vector search (BM25 + embeddings, semanticRatio 0.5) over
@@ -337,7 +337,7 @@ export class Posts extends APIResource {
    *     "operator": "AND",
    *     "value": [
    *       {
-   *         "field": "board_id",
+   *         "field": "boardId",
    *         "operator": "IN",
    *         "value": ["507f1f77bcf86cd799439011"]
    *       }
@@ -363,7 +363,7 @@ export class Posts extends APIResource {
    *     "operator": "AND",
    *     "value": [
    *       {
-   *         "field": "board_id",
+   *         "field": "boardId",
    *         "operator": "IN",
    *         "value": ["507f1f77bcf86cd799439011"]
    *       },
@@ -375,21 +375,44 @@ export class Posts extends APIResource {
    * }
    * ```
    *
+   * To list every post a contact has upvoted (the inverse of
+   * `feedback.posts.voters.list(postId)`):
+   *
+   * ```json
+   * {
+   *   "query": {
+   *     "field": "voterId",
+   *     "operator": "=",
+   *     "value": "507f1f77bcf86cd799439011"
+   *   },
+   *   "sort": "upvotes:desc",
+   *   "limit": 100
+   * }
+   * ```
+   *
    * Top-level `OR` groups and nested groups are not supported in this version.
    *
    * ### Supported fields and operators
    *
-   * | Field                                                             | Type                         | Operators                                          |
-   * | ----------------------------------------------------------------- | ---------------------------- | -------------------------------------------------- |
-   * | `board_id`                                                        | id (categoryId)              | `=`, `!=`, `IN`, `NIN`                             |
-   * | `status_id`                                                       | id (postStatus)              | `=`, `!=`, `IN`, `NIN`                             |
-   * | `tag_id`                                                          | id (postTags)                | `=`, `!=`, `IN`, `NIN`                             |
-   * | `author_id`                                                       | string (user id)             | `=`, `!=`, `IN`, `NIN`                             |
-   * | `assignee_id`                                                     | id or null (admin)           | `=`, `!=`, `IN`, `NIN` (use `null` for unassigned) |
-   * | `company_id`                                                      | string (external company id) | `=`, `!=`, `IN`, `NIN`                             |
-   * | `created_at`, `updated_at`, `eta`                                 | unix seconds                 | `=`, `!=`, `>`, `<`, `>=`, `<=`                    |
-   * | `upvotes`, `comment_count`, `monthly_spend`, `opportunity_amount` | number                       | `=`, `!=`, `>`, `<`, `>=`, `<=`                    |
-   * | `in_review`, `is_pinned`                                          | boolean                      | `=`, `!=`                                          |
+   * Field names are camelCase, matching the rest of the v2 public API. Snake_case
+   * names that this endpoint originally shipped with (`board_id`, `status_id`,
+   * `tag_id`, `author_id`, `voter_id`, `assignee_id`, `company_id`, `created_at`,
+   * `updated_at`, `comment_count`, `monthly_spend`, `opportunity_amount`,
+   * `in_review`, `is_pinned`) are still accepted for back-compat but are deprecated
+   * — please migrate to camelCase in new code.
+   *
+   * | Field                                                          | Type                         | Operators                                                                                                                                |
+   * | -------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+   * | `boardId`                                                      | id (categoryId)              | `=`, `!=`, `IN`, `NIN`                                                                                                                   |
+   * | `statusId`                                                     | id (postStatus)              | `=`, `!=`, `IN`, `NIN`                                                                                                                   |
+   * | `tagId`                                                        | id (postTags)                | `=`, `!=`, `IN`, `NIN`                                                                                                                   |
+   * | `authorId`                                                     | string (user id)             | `=`, `!=`, `IN`, `NIN`                                                                                                                   |
+   * | `voterId`                                                      | id (customer)                | `=`, `IN` (use to list every post a contact has upvoted; only matches `type: customer` upvoters — guests/admins are not searchable here) |
+   * | `assigneeId`                                                   | id or null (admin)           | `=`, `!=`, `IN`, `NIN` (use `null` for unassigned)                                                                                       |
+   * | `companyId`                                                    | string (external company id) | `=`, `!=`, `IN`, `NIN`                                                                                                                   |
+   * | `createdAt`, `updatedAt`, `eta`                                | unix seconds                 | `=`, `!=`, `>`, `<`, `>=`, `<=`                                                                                                          |
+   * | `upvotes`, `commentCount`, `monthlySpend`, `opportunityAmount` | number                       | `=`, `!=`, `>`, `<`, `>=`, `<=`                                                                                                          |
+   * | `inReview`, `isPinned`                                         | boolean                      | `=`, `!=`                                                                                                                                |
    *
    * Use the top-level `search` field for full-text search across `title` and
    * `content` (see "Search mode" above). The clause-level operators `~`, `!~`, `^`,
@@ -398,7 +421,7 @@ export class Posts extends APIResource {
    * A filter-mode query (no `search`) 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. Boolean fields (`in_review`, `is_pinned`) are bounded so a standalone
+   * instead. Boolean fields (`inReview`, `isPinned`) are bounded so a standalone
    * negation on them is allowed. Search mode (with `search` set) relaxes this — the
    * FTS query itself acts as the positive constraint.
    *
@@ -406,15 +429,18 @@ export class Posts extends APIResource {
    *
    * Allowed values:
    *
-   * - `created_at:desc` (default), `created_at:asc`
-   * - `updated_at:desc`, `updated_at:asc`
+   * - `createdAt:desc` (default), `createdAt:asc`
+   * - `updatedAt:desc`, `updatedAt:asc`
    * - `upvotes:desc`, `upvotes:asc`
    * - `eta:desc`, `eta:asc`
-   * - `trending_score:desc`, `trending_score:asc`
-   * - `monthly_spend:desc`, `monthly_spend:asc` (sum of upvoters' monthly spend)
-   * - `opportunity_amount:desc`, `opportunity_amount:asc` (linked HubSpot/Salesforce
+   * - `monthlySpend:desc`, `monthlySpend:asc` (sum of upvoters' monthly spend)
+   * - `opportunityAmount:desc`, `opportunityAmount:asc` (linked HubSpot/Salesforce
    *   value)
-   * - `comment_count:desc`, `comment_count:asc`
+   * - `commentCount:desc`, `commentCount:asc`
+   *
+   * Snake_case sort axes (`created_at:desc`, `monthly_spend:asc`, etc.) are accepted
+   * for back-compat — the cursor encodes the canonical camelCase identity, so a
+   * caller can switch naming conventions mid-pagination without restarting.
    *
    * When `search` is set, results are ranked by relevance unless `sort` is also set,
    * in which case the matching posts are returned in the requested order. The chosen
@@ -1515,21 +1541,30 @@ export interface PostSearchParams {
   search?: string;
 
   /**
-   * Body param: Sort field + direction. Defaults to `created_at:desc`. The chosen
+   * Body param: Sort field + direction. Defaults to `createdAt:desc`. The chosen
    * sort axis is encoded in the cursor; switching `sort` mid-pagination returns
-   * `400 invalid_cursor`.
+   * `400 invalid_cursor`. Snake_case names (`created_at:desc`, `monthly_spend:asc`,
+   * …) are accepted for back-compat — prefer camelCase in new code.
    */
   sort?:
-    | 'created_at:desc'
-    | 'created_at:asc'
-    | 'updated_at:desc'
-    | 'updated_at:asc'
+    | 'createdAt:desc'
+    | 'createdAt:asc'
+    | 'updatedAt:desc'
+    | 'updatedAt:asc'
     | 'upvotes:desc'
     | 'upvotes:asc'
     | 'eta:desc'
     | 'eta:asc'
-    | 'trending_score:desc'
-    | 'trending_score:asc'
+    | 'monthlySpend:desc'
+    | 'monthlySpend:asc'
+    | 'opportunityAmount:desc'
+    | 'opportunityAmount:asc'
+    | 'commentCount:desc'
+    | 'commentCount:asc'
+    | 'created_at:desc'
+    | 'created_at:asc'
+    | 'updated_at:desc'
+    | 'updated_at:asc'
     | 'monthly_spend:desc'
     | 'monthly_spend:asc'
     | 'opportunity_amount:desc'