featurebase-node 0.15.1 → 0.15.3

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

@@ -3,6 +3,14 @@
 import { APIResource } from '../../../core/resource';
 import * as PostsAPI from './posts';
 import * as PostStatusesAPI from '../post-statuses';
+import * as InsightsAPI from './insights';
+import {
+  InsightConvertToPostParams,
+  InsightLinkParams,
+  InsightListParams,
+  InsightUnlinkParams,
+  Insights,
+} from './insights';
 import * as VotersAPI from './voters';
 import {
   VoterAddParams,
@@ -26,17 +34,29 @@ import { path } from '../../../internal/utils/path';
  */
 export class Posts extends APIResource {
   voters: VotersAPI.Voters = new VotersAPI.Voters(this._client);
+  insights: InsightsAPI.Insights = new InsightsAPI.Insights(this._client);
 
   /**
    * Creates a new post (feedback submission) in the specified board.
    *
    * ### Required Fields
    *
-   * - `title` - Post title (minimum 2 characters)
-   * - `boardId` - Board ID to create the post in
+   * - `title` - Post title (minimum 2 characters). Required unless `intakeMode` is
+   *   `feedback`; see "Intake mode" below.
    *
    * ### Optional Fields
    *
+   * - `boardId` - Board ID to create the post in. Omit to use the organization's
+   *   default board.
+   * - `intakeMode` - What the text is: `request` (default) or `feedback`. See
+   *   "Intake mode" below.
+   * - `source` - Where the request came from:
+   *   `{ channel, externalId, url?, conversationId?, label? }`. See "Provenance and
+   *   idempotency" below.
+   * - `attachTo` - Id of an existing open request this post belongs with. The new
+   *   post stays a post. See "attachTo, or link-insight?" below.
+   * - `internal` - Store this request on the hidden internal board (never
+   *   portal-visible). Cannot be combined with `boardId`.
    * - `content` - Post content in HTML format
    * - `tags` - Array of tag names to attach
    * - `statusId` - Status ID to set (defaults to board's default status)
@@ -62,20 +82,155 @@ export class Posts extends APIResource {
    *
    * Resolution priority: `id` > `userId` > `email` > authenticated user
    *
+   * ### Intake mode
+   *
+   * `intakeMode` is the caller's declared intent, and the ONE field that selects how
+   * the post is processed. `author` and `source` only describe where the text came
+   * from; they never select the path.
+   *
+   * - `request` (default, and the behaviour of every call that does not send the
+   *   field): a finished request. Stored exactly as supplied — no AI claim
+   *   extraction, no rewrite — whoever the author is. Featurebase may still link
+   *   existing customer evidence TO the new request in the background; that never
+   *   modifies it.
+   * - `feedback`: raw customer feedback (a Slack message, a call note, a survey
+   *   answer). Processed exactly like a post written on the portal: organized into a
+   *   request when the workspace's "Organize submissions" lane is on, otherwise its
+   *   claims are extracted and matched against existing requests. The workspace's
+   *   Autopilot dial, plan, AI budget, moderation and spam settings all apply, and
+   *   the post is processed even when it is filed under the API key's own user.
+   *   `statusId` and `eta` are rejected in this mode (400): raw feedback carries no
+   *   decision yet. Feedback creates are rate-limited per workspace more strictly
+   *   than requests (429 with `Retry-After`).
+   *
+   * At most 5 requests organized from one submission notify the team (admin
+   * notifications, mentions, Slack, Discord and tracker pushes); the rest are
+   * created silently — still revealed, published and returned in
+   * `processing.results` — and still fire the `post.created` webhook.
+   *
+   * In `feedback` mode `title` is optional: raw text rarely has one. Omit it (or
+   * send it blank) and the first line of `content` becomes the title, cut to 120
+   * characters. `content` is then required — an empty title and an empty content
+   * together are rejected with a 400 on `content`. In `request` mode `title` stays
+   * required, minimum 2 characters.
+   *
+   * #### How much text a feedback create may carry
+   *
+   * Feedback text is read whole or not at all: up to the limit of its
+   * `source.channel` it is read in full, from the first line to the last; anything
+   * longer is rejected (400 on `content`) instead of being trimmed, and the error
+   * message states the limit and the length that was sent.
+   *
+   * | `source.channel`   | Limit (characters) | Sized for                  |
+   * | ------------------ | ------------------ | -------------------------- |
+   * | `call`             | 120,000            | a two-hour call transcript |
+   * | `email`            | 60,000             | a long email thread        |
+   * | `api`              | 60,000             | a document or an export    |
+   * | `slack`, `discord` | 30,000             | a thread or channel export |
+   *
+   * Text sent without a `source.channel` gets the `api` limit. The limits are the
+   * same for every workspace.
+   *
+   * The count is of plain text: the title and the content with its HTML markup
+   * removed. Workspaces that do not process feedback at all (the AI is switched off)
+   * have no limit — the text is stored exactly as sent. To send more, split it and
+   * give each part its own `source.externalId`.
+   *
+   * Long text takes longer. A short message is processed in seconds; a long one is
+   * read in parts, one after the other, and every ask it produces is then matched
+   * and filed in turn — allow tens of minutes for a two-hour transcript. An ask that
+   * comes up more than once in the same text is reported once. One submission yields
+   * at most 30 requests: when the text holds more separate asks than that, the 29
+   * strongest become requests as usual and the rest are listed — one line each, the
+   * ask and the customer's own words — in a single request held for a teammate.
+   * Where the workspace does not organize submissions, at most 50 asks are captured
+   * from one submission; the rest of a longer text is not read.
+   *
+   * Long feedback is rate-limited on its own: at most 20 submissions per workspace
+   * per hour may be longer than a single reading pass (about 16,000 characters where
+   * the workspace organizes submissions, otherwise 6,000 — 24,000 for a `call`).
+   * Past that the create answers 429 with `Retry-After`; shorter feedback is not
+   * affected.
+   *
+   * The response reports what happened in `intakeMode` and `processing`:
+   * `processing.status` is `queued` when an AI run was enqueued (its result lands on
+   * the post asynchronously), `skipped` with a `reason` when nothing was enqueued
+   * (`request_mode`, `autopilot_off`, `pipeline_paused`, `support_board`,
+   * `spam_held`, `staff_authored`, …), or `existing` on an idempotent replay. To
+   * read where the feedback ended up afterwards, fetch the post with
+   * `GET /v2/posts/{id}`.
+   *
+   * ### Provenance and idempotency
+   *
+   * `source` records where a request came from and makes the create idempotent:
+   *
+   * - `source.externalId` is the stable id of the message or record in your system.
+   *   Sending the same `(channel, externalId)` twice returns the post created the
+   *   first time, unchanged, with `deduped: true` — the first delivery always wins.
+   * - Ids are stored namespaced as `api:<externalId>`, so they can never collide
+   *   with ids Featurebase writes itself.
+   * - `feedback`, `widget` and `support` are reserved for posts authored on the
+   *   portal, the widget and the inbox, and are rejected with a 400.
+   * - With `source` and no `author`, the post is attributed to a guest named after
+   *   `source.label` (or the channel), because a relayed request belongs to the
+   *   customer who said it — not to the API key that carried it.
+   *
+   * ### attachTo, or link-insight?
+   *
+   * Both attach something to a request that already exists, and they do different
+   * things.
+   *
+   * `attachTo` records that the NEW post belongs with an existing request. **The
+   * post stays a post**: it keeps `kind: 'issue'`, it is still returned by
+   * `GET /v2/posts` and `GET /v2/posts/{id}`, it keeps its own votes, and its author
+   * does **not** become a supporter of the target — nothing about the target changes
+   * except that it now counts this post among the posts linked to it. The link is
+   * silent: no notification, no ack to the author. The post does **not** appear in
+   * `GET /v2/posts/{targetId}/insights` — that endpoint lists insights, and this is
+   * a post.
+   *
+   * `POST /v2/posts/{id}/link-insight` does the opposite: it files the post as a
+   * **quote** under the request. The post becomes an insight, leaves the posts
+   * resource (`GET /v2/posts/{id}` answers 404 afterwards), appears in
+   * `GET /v2/posts/{targetId}/insights`, and its author is rolled up as a supporter
+   * of the request.
+   *
+   * So: two customers asking for the same thing, and you want both to keep their own
+   * request row → `attachTo`. A sentence a customer said that is evidence for a
+   * request you already track → create the post, then call `link-insight` on it.
+   * Both take the same kind of target: an open request in this workspace.
+   *
+   * `attachTo` cannot be combined with `intakeMode: 'feedback'` (400
+   * `invalid_parameter` on `attachTo`): `attachTo` says where the text belongs, and
+   * `feedback` mode asks Featurebase to decide that for every ask the text contains.
+   * Pick one.
+   *
+   * The link is made AFTER the post is written, so an unusable target is a **422
+   * that says the post was created** — it is not rolled back. The target is refused
+   * when it does not exist in this workspace, is not a request (an insight or a
+   * record), was merged into another request, is a processed submission, is still
+   * awaiting moderation, is held as spam, or is the new post itself.
+   *
    * ### Backdating (Imports)
    *
    * - `createdAt` - Override creation date for importing historical data
    *
    * ### Response
    *
-   * Returns the created post object with all fields populated.
+   * - **201** - the post was created. Returns the post object with all fields
+   *   populated, plus `intakeMode` and `processing`.
+   * - **200** - a post already existed for this
+   *   `(source.channel, source.externalId)`. Returns that post unchanged, with
+   *   `deduped: true` and `processing.status: 'existing'`. A replay is answered from
+   *   the existing post and never links anything a second time, whatever `attachTo`
+   *   says.
+   * - **422** - `attachTo` named a request that cannot carry evidence (missing,
+   *   merged, atomized, held for moderation or spam, not a request, or the post
+   *   itself). **The post was still created**; the error message says so.
    *
    * @example
    * ```ts
-   * const post = await client.feedback.posts.create({
-   *   boardId: '507f1f77bcf86cd799439011',
-   *   title: 'Add dark mode support',
-   * });
+   * const post = await client.feedback.posts.create();
    * ```
    */
   create(params: PostCreateParams, options?: RequestOptions): APIPromise<Post> {
@@ -106,6 +261,46 @@ export class Posts extends APIResource {
    * - Engagement metrics
    * - Custom field values
    *
+   * ### Feedback processing
+   *
+   * For a post created with `intakeMode: 'feedback'`, the response also carries
+   * `processing`, which says how far Featurebase has got with the text and what it
+   * made of it. It is absent on every other post, and on the list endpoint.
+   *
+   * `processing.status`:
+   *
+   * - `queued` - the text was accepted and no result has landed yet
+   * - `processing` - Featurebase is organizing the submission right now
+   * - `complete` - it is done; `results` lists what came out of it
+   * - `needs_review` - it is done, and a teammate still has to decide something
+   * - `skipped` - nothing ran, and nothing will; `reason` says why (the same reason
+   *   the create returned, for example `autopilot_off`). The post is stored exactly
+   *   as it was sent.
+   *
+   * `processing.results` is present in workspaces that organize submissions, once
+   * the run has finished: one entry per ask found in the text, in the order they
+   * appear. Each entry has the ask's `title` and its `outcome`:
+   *
+   * - `request` - the ask became a request of its own
+   * - `attached` - it was added as evidence to a request that already existed
+   * - `held` - it became a request waiting for a teammate to publish it
+   * - `question` - it asked something; no request was created and a teammate answers
+   *   it
+   *
+   * `postId` and `postTitle` name the request the ask became or was attached to.
+   * They are absent for a `question`, and absent when that request is not readable
+   * through this API.
+   *
+   * `held` results carry a `reason` code saying what the teammate still has to
+   * decide: `too_many_topics` (the submission held more separate asks than one
+   * submission can become requests, so this request lists the ones that did not
+   * fit), `uncertain`, `custom_fields` or `processing_failed` (the AI could not
+   * rewrite the text, or could not check the ask against existing requests, so a
+   * teammate confirms it). No other outcome carries it.
+   *
+   * Workspaces that do not organize submissions report `status` only: there the post
+   * you sent IS the request, so there is no separate result to list.
+   *
    * @example
    * ```ts
    * const post = await client.feedback.posts.retrieve(
@@ -228,6 +423,8 @@ export class Posts extends APIResource {
    * - `tags` - Filter by tag names (can be comma-separated or repeated)
    * - `q` - Search query for title/content
    * - `inReview` - Include posts pending moderation
+   * - `kind` - `issue` (default: work items) or `record`; insights are never served
+   *   by this resource — use `/v2/insights`
    *
    * ### Sorting
    *
@@ -579,6 +776,13 @@ export interface Post {
 
   access: PostAccess;
 
+  /**
+   * When kind is 'insight', where exactly the insight points back into its origin:
+   * an insight source record with character ranges into its fullText, or the native
+   * conversation/message/comment/post ids.
+   */
+  anchor: Post.Anchor | null;
+
   /**
    * ID of the admin assigned to this post, null if unassigned
    */
@@ -618,11 +822,23 @@ export interface Post {
 
   features: PostFeatures;
 
+  /**
+   * When kind is 'insight', the triage grouping key (source record id, conversation
+   * id, origin post id, or the insight's own id for singletons). Legacy insights may
+   * be null and group as singletons.
+   */
+  groupKey: string | null;
+
   /**
    * Whether the post is pending moderation review
    */
   inReview: boolean;
 
+  /**
+   * Provenance of an insight: which channel it came from and how it was captured.
+   */
+  insightSource: Post.InsightSource | null;
+
   /**
    * Third-party integration links associated with this post
    */
@@ -633,6 +849,27 @@ export interface Post {
    */
   isPinned: boolean;
 
+  /**
+   * Discriminates an actionable work item ('issue') from a customer submission whose
+   * claims were extracted into insights ('record' — not a work item). Defaults to
+   * 'issue' for all pre-existing posts. Default list responses return issues only;
+   * pass kind='record' to opt in. Raw signal ('insight') is never returned by the
+   * posts resource — insights are served by /v2/insights.
+   */
+  kind: 'issue' | 'insight' | 'record';
+
+  /**
+   * Number of insights linked to this issue as supporting evidence. Only meaningful
+   * when kind is 'issue'.
+   */
+  linkedInsightCount: number;
+
+  /**
+   * When kind is 'insight', the ID of the issue this insight supports. Null when the
+   * insight is unlinked or when kind is 'issue'.
+   */
+  linkedIssueId: string | null;
+
   /**
    * Object type identifier
    */
@@ -643,6 +880,12 @@ export interface Post {
    */
   opportunityAmount: number | null;
 
+  /**
+   * True when the issue is hidden from portal/public surfaces. Missing stored values
+   * are returned as false.
+   */
+  portalHidden: boolean;
+
   /**
    * Full URL to view the post
    */
@@ -674,9 +917,82 @@ export interface Post {
    * Total number of upvotes
    */
   upvotes: number;
+
+  /**
+   * Present and true only on POST /v2/posts, when the request carried a
+   * `source.externalId` that already had a post. The existing post is returned
+   * unchanged with HTTP 200; a newly created post returns HTTP 201 without this
+   * field.
+   */
+  deduped?: true;
+
+  /**
+   * Present only on POST /v2/posts: the `intakeMode` the post was processed under
+   * ('request' when the request named none). On an idempotent replay
+   * (`deduped: true`) this is the mode the post was ORIGINALLY created with.
+   */
+  intakeMode?: 'request' | 'feedback';
+
+  /**
+   * On POST /v2/posts — `queued`: a processing run (claim extraction or the Organize
+   * rewrite) was enqueued and its result lands asynchronously on the post.
+   * `skipped`: nothing was enqueued; `reason` says which gate decided
+   * ('request_mode' for every intakeMode: 'request' create). `existing`: the create
+   * was an idempotent replay and the post was not processed again. On GET
+   * /v2/posts/{id} this field is present only for posts created with
+   * `intakeMode: 'feedback'` and reports how far that processing has got ('queued',
+   * 'processing', 'complete', 'needs_review', or 'skipped' with the same `reason`
+   * the create returned), with `results` listing what was made of the submission
+   * once the run has finished.
+   */
+  processing?: PostProcessing;
 }
 
 export namespace Post {
+  /**
+   * When kind is 'insight', where exactly the insight points back into its origin:
+   * an insight source record with character ranges into its fullText, or the native
+   * conversation/message/comment/post ids.
+   */
+  export interface Anchor {
+    commentId?: string | null;
+
+    conversationId?: string | null;
+
+    messageId?: string | null;
+
+    ranges?: Array<Anchor.Range> | null;
+
+    sourceRecordId?: string | null;
+
+    submissionId?: string | null;
+  }
+
+  export namespace Anchor {
+    export interface Range {
+      end: number;
+
+      start: number;
+    }
+  }
+
+  /**
+   * Provenance of an insight: which channel it came from and how it was captured.
+   */
+  export interface InsightSource {
+    channel: 'slack' | 'discord' | 'email' | 'support' | 'widget' | 'call' | 'api' | 'feedback';
+
+    capturedBy?: 'manual' | 'auto' | 'ai' | 'api' | null;
+
+    conversationId?: string | null;
+
+    externalId?: string | null;
+
+    sourceLabel?: string | null;
+
+    url?: string | null;
+  }
+
   /**
    * Third-party integration links associated with this post
    */
@@ -893,6 +1209,156 @@ export interface PostFeatures {
   commentsEnabled: boolean;
 }
 
+export interface PostList {
+  /**
+   * Array of posts
+   */
+  data: Array<Post>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Pagination metadata for page-based requests
+   */
+  pagination?: PostList.Pagination;
+}
+
+export namespace PostList {
+  /**
+   * Pagination metadata for page-based requests
+   */
+  export interface Pagination {
+    /**
+     * Items per page
+     */
+    limit: number;
+
+    /**
+     * Current page number
+     */
+    page: number;
+
+    /**
+     * Total number of items
+     */
+    total: number;
+
+    /**
+     * Total number of pages
+     */
+    totalPages: number;
+  }
+}
+
+/**
+ * On POST /v2/posts — `queued`: a processing run (claim extraction or the Organize
+ * rewrite) was enqueued and its result lands asynchronously on the post.
+ * `skipped`: nothing was enqueued; `reason` says which gate decided
+ * ('request_mode' for every intakeMode: 'request' create). `existing`: the create
+ * was an idempotent replay and the post was not processed again. On GET
+ * /v2/posts/{id} this field is present only for posts created with
+ * `intakeMode: 'feedback'` and reports how far that processing has got ('queued',
+ * 'processing', 'complete', 'needs_review', or 'skipped' with the same `reason`
+ * the create returned), with `results` listing what was made of the submission
+ * once the run has finished.
+ */
+export interface PostProcessing {
+  /**
+   * 'queued' = an AI run was enqueued and has not landed yet; 'processing' = the run
+   * is working on the submission; 'complete' = it finished and `results` lists what
+   * it produced; 'needs_review' = it finished and a teammate still has to decide
+   * something; 'skipped' = nothing was enqueued (see `reason`); 'existing' =
+   * idempotent replay, not processed again.
+   */
+  status: 'queued' | 'processing' | 'complete' | 'needs_review' | 'skipped' | 'existing';
+
+  /**
+   * Why processing was skipped. 'request_mode' = intakeMode was 'request' (the
+   * default); 'autopilot_off' = the workspace's Autopilot dial is off or its plan
+   * does not include it; 'pipeline_paused' = the platform paused AI processing (it
+   * resumes automatically); 'support_board' / 'spam_held' / 'staff_authored' /
+   * 'no_content' = the post did not qualify; 'source_too_long' = the text was over
+   * the length limit when the run read it (a create that long is normally refused
+   * with a 400 first); 'extraction_failed' = the AI could not read the text after
+   * repeated attempts; nothing was written, and opening the post in Triage runs the
+   * analysis again.
+   */
+  reason?:
+    | 'request_mode'
+    | 'autopilot_off'
+    | 'insights_disabled'
+    | 'pipeline_paused'
+    | 'support_board'
+    | 'spam_held'
+    | 'staff_authored'
+    | 'not_a_post'
+    | 'no_board'
+    | 'no_id'
+    | 'no_content'
+    | 'source_too_long'
+    | 'extraction_failed'
+    | 'hook_error';
+
+  /**
+   * What the workspace's "Organize submissions" lane made of this submission, one
+   * entry per ask it found, in the order they appear in the text. Present on GET
+   * /v2/posts/{id} for posts created with `intakeMode: 'feedback'` once the run has
+   * finished. Absent while the run is still working, and absent for workspaces that
+   * do not organize submissions — there the post itself is the request.
+   */
+  results?: Array<PostProcessing.Result>;
+}
+
+export namespace PostProcessing {
+  export interface Result {
+    /**
+     * 'request' = the ask became a request of its own; 'attached' = it was added as
+     * evidence to a request that already existed; 'held' = it became a request that is
+     * waiting for a teammate to publish it; 'question' = it asked something and no
+     * request was created, so a teammate answers it.
+     */
+    outcome: 'attached' | 'request' | 'question' | 'held';
+
+    /**
+     * The ask, as it was written up.
+     */
+    title: string;
+
+    /**
+     * The request this ask became, or was attached to. Absent for a question, and
+     * absent when the request is not readable through this API (for example a ticket
+     * board).
+     */
+    postId?: string;
+
+    /**
+     * Title of `postId`.
+     */
+    postTitle?: string;
+
+    /**
+     * Why a 'held' result is waiting for a teammate. Only on a 'held' result, and only
+     * one of these codes: 'too_many_topics' = the submission held more separate asks
+     * than one submission can become requests, so this one request lists the asks that
+     * did not fit, one line each in the customer's words; 'uncertain' = the ask was
+     * too vague to file without a person; 'custom_fields' = the board requires custom
+     * fields this submission did not carry; 'processing_failed' = the AI could not
+     * rewrite the text (the request then holds the original words) or could not check
+     * this ask against existing requests, so a teammate confirms it is not a
+     * duplicate.
+     */
+    reason?: 'too_many_topics' | 'uncertain' | 'custom_fields' | 'processing_failed';
+  }
+}
+
 export interface PostTag {
   /**
    * Tag unique identifier
@@ -995,6 +1461,13 @@ export namespace PostSearchResponse {
 
     access: PostsAPI.PostAccess;
 
+    /**
+     * When kind is 'insight', where exactly the insight points back into its origin:
+     * an insight source record with character ranges into its fullText, or the native
+     * conversation/message/comment/post ids.
+     */
+    anchor: Data.Anchor | null;
+
     /**
      * ID of the admin assigned to this post, null if unassigned
      */
@@ -1034,11 +1507,23 @@ export namespace PostSearchResponse {
 
     features: PostsAPI.PostFeatures;
 
+    /**
+     * When kind is 'insight', the triage grouping key (source record id, conversation
+     * id, origin post id, or the insight's own id for singletons). Legacy insights may
+     * be null and group as singletons.
+     */
+    groupKey: string | null;
+
     /**
      * Whether the post is pending moderation review
      */
     inReview: boolean;
 
+    /**
+     * Provenance of an insight: which channel it came from and how it was captured.
+     */
+    insightSource: Data.InsightSource | null;
+
     /**
      * Third-party integration links associated with this post
      */
@@ -1049,6 +1534,27 @@ export namespace PostSearchResponse {
      */
     isPinned: boolean;
 
+    /**
+     * Discriminates an actionable work item ('issue') from a customer submission whose
+     * claims were extracted into insights ('record' — not a work item). Defaults to
+     * 'issue' for all pre-existing posts. Default list responses return issues only;
+     * pass kind='record' to opt in. Raw signal ('insight') is never returned by the
+     * posts resource — insights are served by /v2/insights.
+     */
+    kind: 'issue' | 'insight' | 'record';
+
+    /**
+     * Number of insights linked to this issue as supporting evidence. Only meaningful
+     * when kind is 'issue'.
+     */
+    linkedInsightCount: number;
+
+    /**
+     * When kind is 'insight', the ID of the issue this insight supports. Null when the
+     * insight is unlinked or when kind is 'issue'.
+     */
+    linkedIssueId: string | null;
+
     /**
      * Object type identifier
      */
@@ -1059,6 +1565,12 @@ export namespace PostSearchResponse {
      */
     opportunityAmount: number | null;
 
+    /**
+     * True when the issue is hidden from portal/public surfaces. Missing stored values
+     * are returned as false.
+     */
+    portalHidden: boolean;
+
     /**
      * Full URL to view the post
      */
@@ -1090,9 +1602,82 @@ export namespace PostSearchResponse {
      * Total number of upvotes
      */
     upvotes: number;
+
+    /**
+     * Present and true only on POST /v2/posts, when the request carried a
+     * `source.externalId` that already had a post. The existing post is returned
+     * unchanged with HTTP 200; a newly created post returns HTTP 201 without this
+     * field.
+     */
+    deduped?: true;
+
+    /**
+     * Present only on POST /v2/posts: the `intakeMode` the post was processed under
+     * ('request' when the request named none). On an idempotent replay
+     * (`deduped: true`) this is the mode the post was ORIGINALLY created with.
+     */
+    intakeMode?: 'request' | 'feedback';
+
+    /**
+     * On POST /v2/posts — `queued`: a processing run (claim extraction or the Organize
+     * rewrite) was enqueued and its result lands asynchronously on the post.
+     * `skipped`: nothing was enqueued; `reason` says which gate decided
+     * ('request_mode' for every intakeMode: 'request' create). `existing`: the create
+     * was an idempotent replay and the post was not processed again. On GET
+     * /v2/posts/{id} this field is present only for posts created with
+     * `intakeMode: 'feedback'` and reports how far that processing has got ('queued',
+     * 'processing', 'complete', 'needs_review', or 'skipped' with the same `reason`
+     * the create returned), with `results` listing what was made of the submission
+     * once the run has finished.
+     */
+    processing?: PostsAPI.PostProcessing;
   }
 
   export namespace Data {
+    /**
+     * When kind is 'insight', where exactly the insight points back into its origin:
+     * an insight source record with character ranges into its fullText, or the native
+     * conversation/message/comment/post ids.
+     */
+    export interface Anchor {
+      commentId?: string | null;
+
+      conversationId?: string | null;
+
+      messageId?: string | null;
+
+      ranges?: Array<Anchor.Range> | null;
+
+      sourceRecordId?: string | null;
+
+      submissionId?: string | null;
+    }
+
+    export namespace Anchor {
+      export interface Range {
+        end: number;
+
+        start: number;
+      }
+    }
+
+    /**
+     * Provenance of an insight: which channel it came from and how it was captured.
+     */
+    export interface InsightSource {
+      channel: 'slack' | 'discord' | 'email' | 'support' | 'widget' | 'call' | 'api' | 'feedback';
+
+      capturedBy?: 'manual' | 'auto' | 'ai' | 'api' | null;
+
+      conversationId?: string | null;
+
+      externalId?: string | null;
+
+      sourceLabel?: string | null;
+
+      url?: string | null;
+    }
+
     /**
      * Third-party integration links associated with this post
      */
@@ -1262,26 +1847,30 @@ export namespace PostSearchResponse {
 
 export interface PostCreateParams {
   /**
-   * Body param: Board ID to create post in
+   * Body param: Admin ID to assign this post to
    */
-  boardId: string;
+  assigneeId?: string;
 
   /**
-   * Body param: Post title
+   * Body param: Id of an existing open request this post is evidence for. The post
+   * is created, then linked.
    */
-  title: string;
+  attachTo?: string;
 
   /**
-   * Body param: Admin ID to assign this post to
+   * Body param: Author to attribute the post to. If not provided, uses the
+   * authenticated user — unless `source` is given, in which case a guest author is
+   * synthesised from `source.label` (or the channel name), because a relayed request
+   * belongs to the customer who said it. Supports multiple identification methods:
+   * id (Featurebase ID), userId (external SSO ID), or email.
    */
-  assigneeId?: string;
+  author?: TicketsAPI.AuthorInput;
 
   /**
-   * Body param: Author to attribute the post to. If not provided, uses the
-   * authenticated user. Supports multiple identification methods: id (Featurebase
-   * ID), userId (external SSO ID), or email.
+   * Body param: Board ID to create the post in. Omit to use the default board of the
+   * organization.
    */
-  author?: TicketsAPI.AuthorInput;
+  boardId?: string;
 
   /**
    * Body param: Whether comments are enabled on this post
@@ -1289,7 +1878,9 @@ export interface PostCreateParams {
   commentsEnabled?: boolean | null;
 
   /**
-   * Body param: Post content (HTML)
+   * Body param: Post content (HTML). Required when `intakeMode` is 'feedback' and no
+   * title is given. In 'feedback' mode its plain text is limited by `source.channel`
+   * (see `intakeMode`); longer content is rejected with a 400.
    */
   content?: string;
 
@@ -1315,6 +1906,23 @@ export interface PostCreateParams {
    */
   inReview?: boolean | null;
 
+  /**
+   * Body param: What the text is. 'request' (default): a finished request — stored
+   * exactly as supplied, no AI claim extraction, regardless of author. 'feedback':
+   * raw customer feedback — processed like a portal post (organized into a request,
+   * or its claims extracted and matched against existing requests) under the
+   * workspace's Autopilot dial, plan, AI budget and moderation settings. In
+   * 'feedback' mode `title` is optional (the first line of `content` becomes it),
+   * `statusId` and `eta` are rejected (400) because raw feedback has no decision
+   * yet, and text is read in full up to the limit of its `source.channel` — 120,000
+   * characters of plain text for 'call' (a two-hour transcript), 60,000 for 'email'
+   * and 'api', 30,000 for 'slack' and 'discord'; without a `source.channel` the
+   * 'api' limit applies — while anything longer is rejected (400) rather than
+   * trimmed. Long text takes tens of minutes rather than seconds to process, and one
+   * submission yields at most 30 requests.
+   */
+  intakeMode?: 'request' | 'feedback';
+
   /**
    * Body param: Push the created post to third-party integrations configured on your
    * organization. Each integration must be explicitly set to true to trigger;
@@ -1322,6 +1930,12 @@ export interface PostCreateParams {
    */
   integrations?: PostCreateParams.Integrations;
 
+  /**
+   * Body param: Create this request on the internal board. Never visible on the
+   * portal.
+   */
+  internal?: boolean;
+
   /**
    * Body param: Whether to send email notifications to admins when this post is
    * created. When true, admins will receive the same email notifications as when a
@@ -1329,6 +1943,20 @@ export interface PostCreateParams {
    */
   notifyAdmins?: boolean;
 
+  /**
+   * Body param: When true, hides the issue from portal/public surfaces. Omitted or
+   * false is visible.
+   */
+  portalHidden?: boolean;
+
+  /**
+   * Body param: Provenance of this request, and the idempotency key for the create.
+   * With `source` and no `author`, the post is attributed to a guest named after
+   * `label` (or the channel) so it belongs to the customer who said it, not to the
+   * API key.
+   */
+  source?: PostCreateParams.Source;
+
   /**
    * Body param: Status ID to set
    */
@@ -1339,6 +1967,13 @@ export interface PostCreateParams {
    */
   tags?: string | Array<string>;
 
+  /**
+   * Body param: Post title. Required unless `intakeMode` is 'feedback', where raw
+   * customer text rarely has one: omit it (or send it blank) and the first line of
+   * `content` becomes the title, cut to 120 characters.
+   */
+  title?: string;
+
   /**
    * Body param: Initial upvotes count. Defaults to 1 (post author is automatically
    * added as voter). Use 0 to create a post without any votes.
@@ -1396,6 +2031,45 @@ export namespace PostCreateParams {
      */
     slack?: boolean;
   }
+
+  /**
+   * Provenance of this request, and the idempotency key for the create. With
+   * `source` and no `author`, the post is attributed to a guest named after `label`
+   * (or the channel) so it belongs to the customer who said it, not to the API key.
+   */
+  export interface Source {
+    /**
+     * Channel the request arrived on. 'feedback', 'widget' and 'support' are reserved
+     * for posts authored on the portal, the widget and the inbox, and are rejected
+     * with a 400. With `intakeMode: 'feedback'` the channel also sets how much text is
+     * read: 'call' 120,000 characters, 'email' and 'api' 60,000, 'slack' and 'discord'
+     * 30,000.
+     */
+    channel: 'slack' | 'discord' | 'email' | 'support' | 'widget' | 'call' | 'api' | 'feedback';
+
+    /**
+     * Stable id of the message/record in the source system. Sending the same (channel,
+     * externalId) twice returns the post created the first time instead of a duplicate
+     * (HTTP 200 with `deduped: true`). Stored namespaced as `api:<externalId>`.
+     */
+    externalId: string;
+
+    /**
+     * Id of the support conversation this request came from
+     */
+    conversationId?: string;
+
+    /**
+     * Display name of the specific source. Also names the guest author when no
+     * `author` is given.
+     */
+    label?: string;
+
+    /**
+     * Deep link back to the original message/record
+     */
+    url?: string;
+  }
 }
 
 export interface PostRetrieveParams {
@@ -1414,8 +2088,10 @@ export interface PostUpdateParams {
 
   /**
    * Body param: Author to attribute the post to. If not provided, uses the
-   * authenticated user. Supports multiple identification methods: id (Featurebase
-   * ID), userId (external SSO ID), or email.
+   * authenticated user — unless `source` is given, in which case a guest author is
+   * synthesised from `source.label` (or the channel name), because a relayed request
+   * belongs to the customer who said it. Supports multiple identification methods:
+   * id (Featurebase ID), userId (external SSO ID), or email.
    */
   author?: TicketsAPI.AuthorInput;
 
@@ -1507,6 +2183,13 @@ export interface PostListParams extends CursorPageParams {
    */
   inReview?: boolean | null;
 
+  /**
+   * Query param: Filter by submission kind. Omitted or 'issue' returns work items
+   * only. Pass 'record' for customer submissions whose claims were extracted into
+   * insights. Insights are never served by this resource — use /v2/insights.
+   */
+  kind?: 'issue' | 'record';
+
   /**
    * Query param: Search query to filter posts by title/content
    */
@@ -1645,6 +2328,7 @@ export interface PostUnmergeParams {
 }
 
 Posts.Voters = Voters;
+Posts.Insights = Insights;
 
 export declare namespace Posts {
   export {
@@ -1652,6 +2336,8 @@ export declare namespace Posts {
     type PostAccess as PostAccess,
     type PostAuthor as PostAuthor,
     type PostFeatures as PostFeatures,
+    type PostList as PostList,
+    type PostProcessing as PostProcessing,
     type PostTag as PostTag,
     type SearchFilter as SearchFilter,
     type SearchFilterGroup as SearchFilterGroup,
@@ -1678,4 +2364,12 @@ export declare namespace Posts {
     type VoterAddParams as VoterAddParams,
     type VoterRemoveParams as VoterRemoveParams,
   };
+
+  export {
+    Insights as Insights,
+    type InsightListParams as InsightListParams,
+    type InsightConvertToPostParams as InsightConvertToPostParams,
+    type InsightLinkParams as InsightLinkParams,
+    type InsightUnlinkParams as InsightUnlinkParams,
+  };
 }