featurebase-node 0.12.0 → 0.14.0

package/src/resources/feedback/comments.ts

@@ -1,6 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as CommentsAPI from './comments';
+import * as PostsAPI from './posts/posts';
 import * as TicketsAPI from '../support/tickets/tickets';
 import { APIPromise } from '../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
@@ -12,6 +14,103 @@ import { path } from '../../internal/utils/path';
  * Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.
  */
 export class Comments extends APIResource {
+  /**
+   * Returns comments for your organization.
+   *
+   * Comments are threaded discussions. Each comment can have:
+   *
+   * - Author information
+   * - Voting (upvotes/downvotes)
+   * - Privacy settings (public/private)
+   * - Moderation status
+   * - Parent comment reference for threading
+   *
+   * ### Filtering
+   *
+   * Optionally filter by:
+   *
+   * - `postId` - Get comments for a specific post
+   * - `changelogId` - Get comments for a specific changelog
+   *
+   * If no filter is provided, returns all comments across the organization.
+   *
+   * ### Pagination
+   *
+   * This endpoint uses **cursor-based pagination**:
+   *
+   * - `limit` - Number of comments to return (1-100, default 10)
+   * - `cursor` - Opaque cursor from a previous response's `nextCursor` field
+   *
+   * **Example:** To paginate through results:
+   *
+   * 1. First request: `GET /v2/comments?postId={id}&limit=10`
+   * 2. If `nextCursor` is not null, use it for the next page
+   * 3. Next request: `GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}`
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of comment objects (flat structure with `parentCommentId` for
+   *   threading)
+   * - `nextCursor` - Cursor for the next page (null if no more results)
+   *
+   * ### Comment Structure
+   *
+   * Each comment includes:
+   *
+   * - `id` - Unique comment identifier
+   * - `postId` / `changelogId` - Reference to the parent content
+   * - `parentCommentId` - Reference to parent comment (null for root comments)
+   * - `content` - Comment content in HTML format
+   * - `author` - Author information (id, name, profilePicture, type)
+   * - `upvotes` / `downvotes` / `score` - Voting metrics
+   * - `isPrivate` - Whether comment is only visible to admins
+   * - `inReview` - Whether comment is pending moderation
+   * - `created` / `updated` - Unix timestamps
+   *
+   * ### Additional Filters
+   *
+   * - `privacy` - Filter by privacy: "public", "private", or "all"
+   * - `inReview` - Filter by moderation status (true/false)
+   *
+   * ### Sorting
+   *
+   * Use `sortBy` to sort results:
+   *
+   * - `best` - Sort by confidence score (default, like Reddit)
+   * - `top` - Sort by net score (upvotes - downvotes)
+   * - `new` - Sort by creation date, newest first
+   * - `old` - Sort by creation date, oldest first
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const comment of client.feedback.comments.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    params: CommentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CommentsCursorPage, Comment> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.getAPIList('/v2/comments', CursorPage<Comment>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Creates a new comment or reply to an existing comment.
    *
@@ -199,103 +298,6 @@ export class Comments extends APIResource {
     });
   }
 
-  /**
-   * Returns comments for your organization.
-   *
-   * Comments are threaded discussions. Each comment can have:
-   *
-   * - Author information
-   * - Voting (upvotes/downvotes)
-   * - Privacy settings (public/private)
-   * - Moderation status
-   * - Parent comment reference for threading
-   *
-   * ### Filtering
-   *
-   * Optionally filter by:
-   *
-   * - `postId` - Get comments for a specific post
-   * - `changelogId` - Get comments for a specific changelog
-   *
-   * If no filter is provided, returns all comments across the organization.
-   *
-   * ### Pagination
-   *
-   * This endpoint uses **cursor-based pagination**:
-   *
-   * - `limit` - Number of comments to return (1-100, default 10)
-   * - `cursor` - Opaque cursor from a previous response's `nextCursor` field
-   *
-   * **Example:** To paginate through results:
-   *
-   * 1. First request: `GET /v2/comments?postId={id}&limit=10`
-   * 2. If `nextCursor` is not null, use it for the next page
-   * 3. Next request: `GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}`
-   *
-   * ### Response Format
-   *
-   * Returns a list object with:
-   *
-   * - `object` - Always "list"
-   * - `data` - Array of comment objects (flat structure with `parentCommentId` for
-   *   threading)
-   * - `nextCursor` - Cursor for the next page (null if no more results)
-   *
-   * ### Comment Structure
-   *
-   * Each comment includes:
-   *
-   * - `id` - Unique comment identifier
-   * - `postId` / `changelogId` - Reference to the parent content
-   * - `parentCommentId` - Reference to parent comment (null for root comments)
-   * - `content` - Comment content in HTML format
-   * - `author` - Author information (id, name, profilePicture, type)
-   * - `upvotes` / `downvotes` / `score` - Voting metrics
-   * - `isPrivate` - Whether comment is only visible to admins
-   * - `inReview` - Whether comment is pending moderation
-   * - `created` / `updated` - Unix timestamps
-   *
-   * ### Additional Filters
-   *
-   * - `privacy` - Filter by privacy: "public", "private", or "all"
-   * - `inReview` - Filter by moderation status (true/false)
-   *
-   * ### Sorting
-   *
-   * Use `sortBy` to sort results:
-   *
-   * - `best` - Sort by confidence score (default, like Reddit)
-   * - `top` - Sort by net score (upvotes - downvotes)
-   * - `new` - Sort by creation date, newest first
-   * - `old` - Sort by creation date, oldest first
-   *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const comment of client.feedback.comments.list()) {
-   *   // ...
-   * }
-   * ```
-   */
-  list(
-    params: CommentListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<CommentsCursorPage, Comment> {
-    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
-    return this._client.getAPIList('/v2/comments', CursorPage<Comment>, {
-      query,
-      ...options,
-      headers: buildHeaders([
-        {
-          ...(featurebaseVersion?.toString() != null ?
-            { 'Featurebase-Version': featurebaseVersion?.toString() }
-          : undefined),
-        },
-        options?.headers,
-      ]),
-    });
-  }
-
   /**
    * Deletes a comment by its unique identifier.
    *
@@ -438,6 +440,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>;
@@ -448,7 +611,7 @@ export interface Comment {
    */
   id: string;
 
-  author: Comment.Author | null;
+  author: CommentAuthor | null;
 
   /**
    * Changelog ID this comment belongs to
@@ -526,28 +689,26 @@ export interface Comment {
   upvotes: number;
 }
 
-export namespace Comment {
-  export interface Author {
-    /**
-     * Author unique identifier
-     */
-    id: string | null;
+export interface CommentAuthor {
+  /**
+   * Author unique identifier
+   */
+  id: string | null;
 
-    /**
-     * Author display name
-     */
-    name: string;
+  /**
+   * Author display name
+   */
+  name: string;
 
-    /**
-     * Author profile picture URL
-     */
-    profilePicture: string | null;
+  /**
+   * Author profile picture URL
+   */
+  profilePicture: string | null;
 
-    /**
-     * Type of user who authored the comment
-     */
-    type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
-  }
+  /**
+   * Type of user who authored the comment
+   */
+  type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
 }
 
 export interface CommentDelete0Response {
@@ -571,6 +732,155 @@ 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: CommentsAPI.CommentAuthor | 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 interface CommentListParams extends CursorPageParams {
+  /**
+   * Query param: Filter comments by changelog ID
+   */
+  changelogId?: string;
+
+  /**
+   * Query param: Filter by review status
+   */
+  inReview?: boolean | null;
+
+  /**
+   * Query param: Filter comments by post ID
+   */
+  postId?: string;
+
+  /**
+   * Query param: Filter comments by privacy
+   */
+  privacy?: 'public' | 'private' | 'all';
+
+  /**
+   * Query param: Sort order for comments
+   */
+  sortBy?: 'best' | 'top' | 'new' | 'old';
+
+  /**
+   * 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 interface CommentCreateParams {
   /**
    * Body param: Comment content in HTML format
@@ -687,52 +997,62 @@ export interface CommentUpdateParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
-export interface CommentListParams extends CursorPageParams {
+export interface CommentDelete0Params {
   /**
-   * Query param: Filter comments by changelog ID
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
    */
-  changelogId?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
 
+export interface CommentDelete1Params {
   /**
-   * Query param: Filter by review status
+   * Body param: Comment ID
    */
-  inReview?: boolean | null;
+  id: string;
 
   /**
-   * Query param: Filter comments by post ID
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
    */
-  postId?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
 
+export interface CommentSearchParams {
   /**
-   * Query param: Filter comments by privacy
+   * Body param: An opaque cursor for pagination. Use the `nextCursor` value from a
+   * previous response to fetch the next page of results.
    */
-  privacy?: 'public' | 'private' | 'all';
+  cursor?: string;
 
   /**
-   * Query param: Sort order for comments
+   * Body param: A limit on the number of objects to be returned, between 1 and 100.
    */
-  sortBy?: 'best' | 'top' | 'new' | 'old';
+  limit?: number;
 
   /**
-   * Header param: API version for this request. Defaults to your organization's
-   * configured API version if not specified.
+   * 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.
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
-}
+  query?: PostsAPI.SearchFilter | PostsAPI.SearchFilterGroup;
 
-export interface CommentDelete0Params {
   /**
-   * API version for this request. Defaults to your organization's configured API
-   * version if not specified.
+   * 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.
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
-}
+  search?: string;
 
-export interface CommentDelete1Params {
   /**
-   * Body param: Comment ID
+   * 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`.
    */
-  id: string;
+  sort?: 'createdAt:desc' | 'createdAt:asc' | 'confidenceScore:desc' | 'confidenceScore:asc' | 'score:desc';
 
   /**
    * Header param: API version for this request. Defaults to your organization's
@@ -744,14 +1064,17 @@ export interface CommentDelete1Params {
 export declare namespace Comments {
   export {
     type Comment as Comment,
+    type CommentAuthor as CommentAuthor,
     type CommentDelete0Response as CommentDelete0Response,
     type CommentDelete1Response as CommentDelete1Response,
+    type CommentSearchResponse as CommentSearchResponse,
     type CommentsCursorPage as CommentsCursorPage,
+    type CommentListParams as CommentListParams,
     type CommentCreateParams as CommentCreateParams,
     type CommentRetrieveParams as CommentRetrieveParams,
     type CommentUpdateParams as CommentUpdateParams,
-    type CommentListParams as CommentListParams,
     type CommentDelete0Params as CommentDelete0Params,
     type CommentDelete1Params as CommentDelete1Params,
+    type CommentSearchParams as CommentSearchParams,
   };
 }