featurebase-node 0.15.1 → 0.15.2

package/src/resources/changelogs/index.ts

@@ -4,6 +4,7 @@ export {
   Changelogs,
   type Changelog,
   type PublishUnpublishSuccess,
+  type ChangelogRetrieveResponse,
   type ChangelogDeleteResponse,
   type ChangelogCreateParams,
   type ChangelogRetrieveParams,

package/src/resources/feedback/comments.ts

@@ -856,8 +856,10 @@ export interface CommentCreateParams {
 
   /**
    * 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;
 

package/src/resources/feedback/custom-fields.ts

@@ -193,6 +193,21 @@ export namespace CustomField {
      * Option display label
      */
     label: string;
+
+    /**
+     * Option description
+     */
+    description?: string;
+
+    /**
+     * Option group label
+     */
+    group?: string;
+
+    /**
+     * Option icon
+     */
+    icon?: string;
   }
 }
 

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

@@ -1,5 +1,12 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Insights,
+  type InsightListParams,
+  type InsightConvertToPostParams,
+  type InsightLinkParams,
+  type InsightUnlinkParams,
+} from './insights';
 export {
   Posts,
   type Post,

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

@@ -0,0 +1,340 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as PostsAPI from './posts';
+import { PostsCursorPage } from './posts';
+import { APIPromise } from '../../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses.
+ */
+export class Insights extends APIResource {
+  /**
+   * Returns the insights filed under the request `{id}` — the customer quotes kept
+   * as evidence for it. Newest first.
+   *
+   * Posts linked with `attachTo` are **not** listed here: they are posts, not
+   * insights, and they stay in `GET /v2/posts`. This endpoint lists exactly the rows
+   * that `POST /v2/posts/{insightId}/link-insight` filed under this request.
+   *
+   * ### Query parameters
+   *
+   * - `limit` — insights per page, 1–100. **Defaults to 100**, so most requests
+   *   return their whole evidence set in one call.
+   * - `cursor` — opaque cursor from a previous response's `nextCursor`.
+   *
+   * ### Response format
+   *
+   * The standard post list envelope:
+   *
+   * - `object` — always `"list"`
+   * - `data` — the insights, each in the same shape as any other post object, with
+   *   `kind: 'insight'` and `linkedIssueId` set to `{id}`
+   * - `nextCursor` — pass it back as `cursor` for the next page; `null` on the last
+   *   page
+   *
+   * `pagination` is never returned by this endpoint — it is cursor-paginated only.
+   *
+   * ### Notes
+   *
+   * - Pass the **request's** id, not an insight's. An id that is not a request (an
+   *   insight, or an unknown id in this workspace) is not an error: the list simply
+   *   comes back empty.
+   * - The insights returned are not readable through `GET /v2/posts/{insightId}` —
+   *   that endpoint serves work items only.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const post of client.feedback.posts.insights.list(
+   *   '507f1f77bcf86cd799439011',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    id: string,
+    params: InsightListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PostsCursorPage, PostsAPI.Post> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.getAPIList(path`/v2/posts/${id}/insights`, CursorPage<PostsAPI.Post>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Promotes the insight `{id}` into a request of its own — the way back from
+   * `link-insight`.
+   *
+   * `kind` becomes `issue`, any link to another request is cleared (that request's
+   * `linkedInsightCount` is recounted), and the row is a post again:
+   * `GET /v2/posts/{id}` answers it, and `GET /v2/posts` lists it.
+   *
+   * The promoted request is given the workspace's default status if it had none, is
+   * filed on the internal board (its previous board is kept as the request's source
+   * category), and is created **hidden from the portal** — publish it with
+   * `PATCH /v2/posts/{id}` when you want customers to see it. It then announces
+   * itself like a freshly created request: the `post.created` webhook fires and the
+   * workspace's tracker integrations receive it, subject to the same rules as any
+   * other creation. Featurebase also looks for other existing insights that support
+   * the new request, in the background.
+   *
+   * Calling this on a post that is already a request is a no-op and returns it
+   * unchanged.
+   *
+   * ### Request
+   *
+   * No body. The insight is named by the path.
+   *
+   * ### Response
+   *
+   * The resulting request, in the standard post format.
+   *
+   * @example
+   * ```ts
+   * const post =
+   *   await client.feedback.posts.insights.convertToPost(
+   *     '507f1f77bcf86cd799439011',
+   *   );
+   * ```
+   */
+  convertToPost(
+    id: string,
+    params: InsightConvertToPostParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PostsAPI.Post> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.post(path`/v2/posts/${id}/convert-to-issue`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * An **insight** is a customer's own words kept as evidence under a request — a
+   * quote, not a request of its own, and never returned by `GET /v2/posts`.
+   *
+   * This endpoint turns the post `{id}` into an insight under the request `issueId`.
+   * Use it for the sentence a customer actually said; use `attachTo` on
+   * `POST /v2/posts` when the thing you are filing is a request in its own right and
+   * should stay one.
+   *
+   * ### What changes
+   *
+   * - The post becomes an insight: `kind` is `insight` and `linkedIssueId` is the
+   *   request.
+   * - **It leaves the posts resource.** `GET /v2/posts/{id}` answers `404` from then
+   *   on, and it no longer appears in `GET /v2/posts`. Read it back through
+   *   `GET /v2/posts/{issueId}/insights`, which is where it now lives.
+   * - Its author counts as a supporter of the request: the insight's upvoters are
+   *   rolled onto the request (deduped by user, so a customer who had already voted
+   *   is not counted twice) and the insight's author is subscribed to the request's
+   *   updates. The request's `upvotes` goes up accordingly.
+   * - The request's `linkedInsightCount` is recounted from the live set of insights
+   *   pointing at it.
+   *
+   * Linking again to the same request is a no-op and returns the insight unchanged.
+   *
+   * An insight that is already filed under a DIFFERENT request is MOVED — but only
+   * if nobody has confirmed that first link by hand. The old link is dropped first,
+   * and the old request is remembered as "not a match" so automatic matching never
+   * puts it back there. An insight whose link was already confirmed by a person
+   * (every link made through this endpoint counts as confirmed) is refused with
+   * `400 Insight is already linked to another issue. Detach it first.` — call
+   * `POST /v2/posts/{id}/unlink-insight` first, then link it where you want it.
+   *
+   * ### Which targets are refused
+   *
+   * - `404` — no post with `{id}` in this workspace, or one the API key cannot see
+   *   (`Insight not found.`); no request with `issueId`, or one the API key cannot
+   *   see (`Issue not found.`).
+   * - `400` — `issueId` equals `{id}` (a post cannot be linked to itself); the
+   *   target is not a request (it is itself an insight, or a record — convert or
+   *   restore it first); the target is a processed submission (`atomizedAt` — link
+   *   to the requests that came out of it); the post being linked is a record (link
+   *   the record's extracted insights instead); the post is already filed under
+   *   another request by hand (unlink it first).
+   * - `400 invalid_id` — `{id}` or `issueId` is not a valid object id.
+   *
+   * A merged, held-for-moderation, spam-held or closed target is **not** refused
+   * here: those guards apply to automatic (AI) attachment only, and a person linking
+   * by hand is trusted to mean it.
+   *
+   * ### Response
+   *
+   * The updated insight, in the standard post format (`kind: 'insight'`,
+   * `linkedIssueId` set). The request it was linked to is not returned — fetch it
+   * with `GET /v2/posts/{issueId}` if you need its new `upvotes` and
+   * `linkedInsightCount`.
+   *
+   * ### Body
+   *
+   * - `issueId` — the request to file this post under. Required.
+   * - `linkSource` — deprecated and ignored; a link made through the API is always a
+   *   manual link.
+   *
+   * ### Errors
+   *
+   * Failures raised by the insight service (404 / 400 / 409) are returned as
+   * `{ "code": <status>, "message": "..." }` rather than in the Stripe-style
+   * envelope the rest of this resource uses. The status code is the contract; do not
+   * parse the body shape.
+   *
+   * @example
+   * ```ts
+   * const post = await client.feedback.posts.insights.link(
+   *   '507f1f77bcf86cd799439011',
+   *   { issueId: '507f1f77bcf86cd799439011' },
+   * );
+   * ```
+   */
+  link(id: string, params: InsightLinkParams, options?: RequestOptions): APIPromise<PostsAPI.Post> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/posts/${id}/link-insight`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Detaches the insight `{id}` from the request it was filed under.
+   *
+   * **The row stays an insight** — the customer's words do not disappear, they just
+   * return to the unlinked pool. `linkedIssueId` becomes `null`, and
+   * `GET /v2/posts/{id}` still answers `404`: an unlinked insight is still not a
+   * post. To get a post back, call `POST /v2/posts/{id}/convert-to-issue`.
+   *
+   * ### What does NOT change
+   *
+   * The votes this insight rolled onto the request are **not** taken back, and the
+   * author stays subscribed to it. They are real demand that was expressed, and the
+   * roll-up was deduplicated against votes the customer may have cast independently
+   * — unwinding it would remove votes it never created. The request's `upvotes`
+   * therefore stays where the link left it. Its `linkedInsightCount` IS recounted
+   * and goes down.
+   *
+   * The request that was just unlinked is remembered as "not a match" for this
+   * insight, so automatic matching never files it there again.
+   *
+   * Calling this on a post that is not an insight, or on an insight that is already
+   * unlinked, is a no-op and returns the row unchanged.
+   *
+   * ### Request
+   *
+   * No body. The insight is named by the path.
+   *
+   * ### Response
+   *
+   * The updated insight, in the standard post format.
+   *
+   * @example
+   * ```ts
+   * const post = await client.feedback.posts.insights.unlink(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  unlink(
+    id: string,
+    params: InsightUnlinkParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PostsAPI.Post> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.post(path`/v2/posts/${id}/unlink-insight`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface InsightListParams extends CursorPageParams {
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface InsightConvertToPostParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface InsightLinkParams {
+  /**
+   * Body param: ID of the request this post becomes evidence for. Must be a request
+   * in this workspace that can still take evidence.
+   */
+  issueId: string;
+
+  /**
+   * @deprecated Body param: Deprecated and ignored. A link made through the API is
+   * always recorded as a manual link.
+   */
+  linkSource?: 'manual' | 'ai';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface InsightUnlinkParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export declare namespace Insights {
+  export {
+    type InsightListParams as InsightListParams,
+    type InsightConvertToPostParams as InsightConvertToPostParams,
+    type InsightLinkParams as InsightLinkParams,
+    type InsightUnlinkParams as InsightUnlinkParams,
+  };
+}
+
+export { type PostsCursorPage };