featurebase-node 0.15.1 → 0.15.3

package/resources/feedback/posts/posts.d.mts

@@ -1,6 +1,8 @@
 import { APIResource } from "../../../core/resource.mjs";
 import * as PostsAPI from "./posts.mjs";
 import * as PostStatusesAPI from "../post-statuses.mjs";
+import * as InsightsAPI from "./insights.mjs";
+import { InsightConvertToPostParams, InsightLinkParams, InsightListParams, InsightUnlinkParams, Insights } from "./insights.mjs";
 import * as VotersAPI from "./voters.mjs";
 import { VoterAddParams, VoterAddResponse, VoterListParams, VoterListResponse, VoterListResponsesCursorPage, VoterRemoveParams, VoterRemoveResponse, Voters } from "./voters.mjs";
 import * as TicketsAPI from "../../support/tickets/tickets.mjs";
@@ -12,16 +14,28 @@ import { RequestOptions } from "../../../internal/request-options.mjs";
  */
 export declare class Posts extends APIResource {
     voters: VotersAPI.Voters;
+    insights: InsightsAPI.Insights;
     /**
      * 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)
@@ -47,20 +61,155 @@ export declare 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>;
@@ -76,6 +225,46 @@ export declare 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(
@@ -165,6 +354,8 @@ export declare 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
      *
@@ -432,6 +623,12 @@ export interface Post {
      */
     id: string;
     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
      */
@@ -464,10 +661,20 @@ export interface Post {
      */
     eta: string | null;
     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
      */
@@ -476,6 +683,24 @@ export interface Post {
      * Whether the post is pinned to the top
      */
     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
      */
@@ -484,6 +709,11 @@ export interface Post {
      * Total opportunity amount from linked HubSpot deals and Salesforce opportunities
      */
     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
      */
@@ -509,8 +739,64 @@ 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 declare 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.
+     */
+    interface Anchor {
+        commentId?: string | null;
+        conversationId?: string | null;
+        messageId?: string | null;
+        ranges?: Array<Anchor.Range> | null;
+        sourceRecordId?: string | null;
+        submissionId?: string | null;
+    }
+    namespace Anchor {
+        interface Range {
+            end: number;
+            start: number;
+        }
+    }
+    /**
+     * Provenance of an insight: which channel it came from and how it was captured.
+     */
+    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
      */
@@ -686,6 +972,126 @@ 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 declare namespace PostList {
+    /**
+     * Pagination metadata for page-based requests
+     */
+    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 declare namespace PostProcessing {
+    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
@@ -770,6 +1176,12 @@ export declare namespace PostSearchResponse {
          */
         id: string;
         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
          */
@@ -802,10 +1214,20 @@ export declare namespace PostSearchResponse {
          */
         eta: string | null;
         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
          */
@@ -814,6 +1236,24 @@ export declare namespace PostSearchResponse {
          * Whether the post is pinned to the top
          */
         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
          */
@@ -822,6 +1262,11 @@ export declare namespace PostSearchResponse {
          * Total opportunity amount from linked HubSpot deals and Salesforce opportunities
          */
         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
          */
@@ -847,8 +1292,64 @@ export declare 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;
     }
     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.
+         */
+        interface Anchor {
+            commentId?: string | null;
+            conversationId?: string | null;
+            messageId?: string | null;
+            ranges?: Array<Anchor.Range> | null;
+            sourceRecordId?: string | null;
+            submissionId?: string | null;
+        }
+        namespace Anchor {
+            interface Range {
+                end: number;
+                start: number;
+            }
+        }
+        /**
+         * Provenance of an insight: which channel it came from and how it was captured.
+         */
+        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
          */
@@ -984,30 +1485,36 @@ export declare namespace PostSearchResponse {
     }
 }
 export interface PostCreateParams {
-    /**
-     * Body param: Board ID to create post in
-     */
-    boardId: string;
-    /**
-     * Body param: Post title
-     */
-    title: string;
     /**
      * Body param: Admin ID to assign this post to
      */
     assigneeId?: string;
+    /**
+     * Body param: Id of an existing open request this post is evidence for. The post
+     * is created, then linked.
+     */
+    attachTo?: string;
     /**
      * 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;
+    /**
+     * Body param: Board ID to create the post in. Omit to use the default board of the
+     * organization.
+     */
+    boardId?: string;
     /**
      * Body param: Whether comments are enabled on this post
      */
     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;
     /**
@@ -1030,18 +1537,51 @@ export interface PostCreateParams {
      * Body param: Whether post is pending moderation
      */
     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;
      * omitted integrations will not be pushed to.
      */
     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
      * post is created from the dashboard. Defaults to false (no emails sent).
      */
     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
      */
@@ -1050,6 +1590,12 @@ export interface PostCreateParams {
      * Body param: Tag names to attach
      */
     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.
@@ -1099,6 +1645,40 @@ export declare 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.
+     */
+    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 {
     /**
@@ -1114,8 +1694,10 @@ export interface PostUpdateParams {
     assigneeId?: string | null;
     /**
      * 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;
     /**
@@ -1192,6 +1774,12 @@ export interface PostListParams extends CursorPageParams {
      * Query param: Include posts that are in review
      */
     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
      */
@@ -1288,7 +1876,8 @@ export interface PostUnmergeParams {
     'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
 }
 export declare namespace Posts {
-    export { type Post as Post, type PostAccess as PostAccess, type PostAuthor as PostAuthor, type PostFeatures as PostFeatures, type PostTag as PostTag, type SearchFilter as SearchFilter, type SearchFilterGroup as SearchFilterGroup, 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 PostMergeParams as PostMergeParams, type PostSearchParams as PostSearchParams, type PostUnmergeParams as PostUnmergeParams, };
+    export { type Post as Post, 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, 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 PostMergeParams as PostMergeParams, type PostSearchParams as PostSearchParams, type PostUnmergeParams as PostUnmergeParams, };
     export { Voters as Voters, type VoterListResponse as VoterListResponse, type VoterAddResponse as VoterAddResponse, type VoterRemoveResponse as VoterRemoveResponse, type VoterListResponsesCursorPage as VoterListResponsesCursorPage, type VoterListParams as VoterListParams, 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, };
 }
 //# sourceMappingURL=posts.d.mts.map