featurebase-node 0.11.0 → 0.13.0

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

@@ -313,6 +313,188 @@ export class Posts extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Search feedback posts 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 posts matching the filter, ordered by `sort` (default
+   *   `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
+   *   post `title` and `content`, returning matches ranked by relevance. Optional:
+   *   combine with `query` to constrain the search to a board / status / time
+   *   window, and/or `sort` to override relevance ranking with chronological order.
+   *
+   * ```json
+   * {
+   *   "search": "mobile dark mode",
+   *   "query": {
+   *     "operator": "AND",
+   *     "value": [
+   *       {
+   *         "field": "boardId",
+   *         "operator": "IN",
+   *         "value": ["507f1f77bcf86cd799439011"]
+   *       }
+   *     ]
+   *   },
+   *   "limit": 20
+   * }
+   * ```
+   *
+   * `search` is server-managed: no operators, no field selection, no special syntax
+   * — same plain-text contract as `/v2/conversations/search`. The string must be
+   * 1–500 characters; up to ~1024 BM25-tokenizer characters are forwarded to
+   * Turbopuffer (longer queries are truncated at a word boundary).
+   *
+   * ### 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": "boardId",
+   *         "operator": "IN",
+   *         "value": ["507f1f77bcf86cd799439011"]
+   *       },
+   *       { "field": "upvotes", "operator": ">", "value": 10 }
+   *     ]
+   *   },
+   *   "sort": "upvotes:desc",
+   *   "limit": 20
+   * }
+   * ```
+   *
+   * 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 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 `~`, `!~`, `^`,
+   * `$` 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 (`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.
+   *
+   * ### Sort
+   *
+   * Allowed values:
+   *
+   * - `createdAt:desc` (default), `createdAt:asc`
+   * - `updatedAt:desc`, `updatedAt:asc`
+   * - `upvotes:desc`, `upvotes:asc`
+   * - `eta:desc`, `eta:asc`
+   * - `monthlySpend:desc`, `monthlySpend:asc` (sum of upvoters' monthly spend)
+   * - `opportunityAmount:desc`, `opportunityAmount:asc` (linked HubSpot/Salesforce
+   *   value)
+   * - `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
+   * 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 exclusions are always applied and CANNOT be disabled via the AST:
+   *
+   * - Spam posts (`isSpam: true`) are excluded.
+   * - Merged posts (those rolled into another post) are excluded — the canonical row
+   *   is what's returned.
+   * - Support-board (ticket) categories are excluded — tickets have their own
+   *   `/v2/tickets` surface.
+   *
+   * ### Response
+   *
+   * Returns a standard list envelope with post rows identical to
+   * `GET /v2/posts/{id}`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.feedback.posts.search();
+   * ```
+   */
+  search(params: PostSearchParams, options?: RequestOptions): APIPromise<PostSearchResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/posts/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
 }
 
 export type PostsCursorPage = CursorPage<Post>;
@@ -673,6 +855,377 @@ export interface PostDeleteResponse {
   object: 'post';
 }
 
+export interface PostSearchResponse {
+  /**
+   * Array of search results
+   */
+  data: Array<PostSearchResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (null if no more results)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Total number of posts 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 PostSearchResponse {
+  export interface Data {
+    /**
+     * Unique identifier
+     */
+    id: string;
+
+    access: Data.Access;
+
+    /**
+     * ID of the admin assigned to this post, null if unassigned
+     */
+    assigneeId: string | null;
+
+    author: Data.Author | null;
+
+    /**
+     * Board (category) ID this post belongs to
+     */
+    boardId: string;
+
+    /**
+     * Total number of comments
+     */
+    commentCount: number;
+
+    /**
+     * Post content in HTML format
+     */
+    content: string;
+
+    /**
+     * ISO 8601 timestamp when created
+     */
+    createdAt: string;
+
+    /**
+     * Custom field values keyed by field ID
+     */
+    customFields: { [key: string]: unknown };
+
+    /**
+     * Estimated completion time as ISO 8601 timestamp, null if not set
+     */
+    eta: string | null;
+
+    features: Data.Features;
+
+    /**
+     * Whether the post is pending moderation review
+     */
+    inReview: boolean;
+
+    /**
+     * Third-party integration links associated with this post
+     */
+    integrations: Data.Integrations;
+
+    /**
+     * Whether the post is pinned to the top
+     */
+    isPinned: boolean;
+
+    /**
+     * Object type identifier
+     */
+    object: 'post';
+
+    /**
+     * Total opportunity amount from linked HubSpot deals and Salesforce opportunities
+     */
+    opportunityAmount: number | null;
+
+    /**
+     * Full URL to view the post
+     */
+    postUrl: string;
+
+    /**
+     * URL-friendly slug
+     */
+    slug: string;
+
+    status: PostStatusesAPI.PostStatus;
+
+    /**
+     * Tags attached to this post
+     */
+    tags: Array<Data.Tag>;
+
+    /**
+     * Post title
+     */
+    title: string;
+
+    /**
+     * ISO 8601 timestamp when last modified
+     */
+    updatedAt: string;
+
+    /**
+     * Total number of upvotes
+     */
+    upvotes: number;
+  }
+
+  export namespace Data {
+    export interface Access {
+      /**
+       * External company IDs explicitly granted access to this post. Empty array means
+       * no company-level restrictions. Non-empty means only users belonging to these
+       * companies can see the post.
+       */
+      companyExternalIds: Array<string>;
+
+      /**
+       * User IDs explicitly granted access to this post. Empty array means no user-level
+       * restrictions (post uses board/org visibility). Non-empty means only these users
+       * (plus admins) can see the post.
+       */
+      userIds: Array<string>;
+    }
+
+    export interface Author {
+      /**
+       * Author unique identifier
+       */
+      id: string | null;
+
+      /**
+       * Author email (if available)
+       */
+      email: string | null;
+
+      /**
+       * Author display name
+       */
+      name: string;
+
+      /**
+       * Author profile picture URL
+       */
+      profilePicture: string | null;
+
+      /**
+       * Type of user who authored the post
+       */
+      type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
+    }
+
+    export interface Features {
+      /**
+       * Whether comments are allowed on this post
+       */
+      commentsEnabled: boolean;
+    }
+
+    /**
+     * Third-party integration links associated with this post
+     */
+    export interface Integrations {
+      clickup: Array<Integrations.Clickup>;
+
+      devops: Array<Integrations.Devop>;
+
+      github: Array<Integrations.GitHub>;
+
+      hubspot: Array<Integrations.Hubspot>;
+
+      jira: Array<Integrations.Jira>;
+
+      linear: Array<Integrations.Linear>;
+
+      salesforce: Array<Integrations.Salesforce>;
+    }
+
+    export namespace Integrations {
+      export interface Clickup {
+        /**
+         * ClickUp task ID
+         */
+        id: string;
+
+        /**
+         * ClickUp task title
+         */
+        title: string;
+
+        /**
+         * URL to the ClickUp task
+         */
+        url: string;
+      }
+
+      export interface Devop {
+        /**
+         * Azure DevOps work item ID
+         */
+        id: number;
+
+        /**
+         * Azure DevOps project ID
+         */
+        projectId: string;
+
+        /**
+         * Azure DevOps project name
+         */
+        projectName: string;
+
+        /**
+         * Work item title
+         */
+        title: string;
+
+        /**
+         * URL to the work item
+         */
+        url: string;
+      }
+
+      export interface GitHub {
+        /**
+         * GitHub issue ID
+         */
+        id: string;
+
+        /**
+         * GitHub issue number
+         */
+        number: string;
+
+        /**
+         * Full repository name (owner/repo)
+         */
+        repositoryFullName: string;
+
+        /**
+         * Repository name
+         */
+        repositoryName: string;
+
+        /**
+         * GitHub issue title
+         */
+        title: string;
+
+        /**
+         * URL to the GitHub issue
+         */
+        url: string;
+      }
+
+      export interface Hubspot {
+        /**
+         * Deal amount (for DEAL type)
+         */
+        dealAmount: number | null;
+
+        /**
+         * Whether the deal is closed (for DEAL type)
+         */
+        dealClosed: boolean | null;
+
+        /**
+         * HubSpot object ID
+         */
+        objectId: number;
+
+        /**
+         * HubSpot object type
+         */
+        type: 'TICKET' | 'DEAL' | 'CONTACT';
+      }
+
+      export interface Jira {
+        /**
+         * Jira issue ID
+         */
+        issueId: string;
+
+        /**
+         * URL to the Jira issue
+         */
+        issueUrl: string | null;
+      }
+
+      export interface Linear {
+        /**
+         * Linear issue ID
+         */
+        issueId: string;
+
+        /**
+         * URL to the Linear issue
+         */
+        issueUrl: string | null;
+      }
+
+      export interface Salesforce {
+        /**
+         * Opportunity amount (for Opportunity type)
+         */
+        amount: number | null;
+
+        /**
+         * Whether the opportunity is closed (for Opportunity type)
+         */
+        isClosed: boolean | null;
+
+        /**
+         * Salesforce record ID
+         */
+        objectId: string;
+
+        /**
+         * Salesforce object type
+         */
+        objectType: 'Opportunity' | 'Case';
+      }
+    }
+
+    export interface Tag {
+      /**
+       * Tag unique identifier
+       */
+      id: string;
+
+      /**
+       * Tag color hex code
+       */
+      color: string | null;
+
+      /**
+       * Tag name
+       */
+      name: string;
+    }
+  }
+}
+
 export interface PostCreateParams {
   /**
    * Body param: Board ID to create post in
@@ -960,18 +1513,136 @@ export interface PostDeleteParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
+export interface PostSearchParams {
+  /**
+   * 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?: PostSearchParams.SearchFilter | PostSearchParams.SearchFilterGroup;
+
+  /**
+   * Body param: Plain-text full-text search across post `title` and `content`.
+   * Server-managed (hybrid BM25 + vector) — no operators, no field selection. 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. Combine with
+   * `query` to constrain the search to a board / status / time window.
+   */
+  search?: string;
+
+  /**
+   * 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`. Snake_case names (`created_at:desc`, `monthly_spend:asc`,
+   * …) are accepted for back-compat — prefer camelCase in new code.
+   */
+  sort?:
+    | 'createdAt:desc'
+    | 'createdAt:asc'
+    | 'updatedAt:desc'
+    | 'updatedAt:asc'
+    | 'upvotes:desc'
+    | 'upvotes:asc'
+    | 'eta:desc'
+    | 'eta: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'
+    | 'opportunity_amount:asc'
+    | 'comment_count:desc'
+    | 'comment_count: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 PostSearchParams {
+  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;
+    }
+  }
+}
+
 Posts.Voters = Voters;
 
 export declare namespace Posts {
   export {
     type Post as Post,
     type PostDeleteResponse as PostDeleteResponse,
+    type PostSearchResponse as PostSearchResponse,
     type PostsCursorPage as PostsCursorPage,
     type PostCreateParams as PostCreateParams,
     type PostRetrieveParams as PostRetrieveParams,
     type PostUpdateParams as PostUpdateParams,
     type PostListParams as PostListParams,
     type PostDeleteParams as PostDeleteParams,
+    type PostSearchParams as PostSearchParams,
   };
 
   export {