featurebase-node 0.14.1 → 0.14.3

package/src/resources/reports.ts

@@ -65,10 +65,13 @@ export class Reports extends APIResource {
    *
    * 1. Pick a `metric` and `aggregation` from the datasets catalog
    *    (`GET /v2/reports/datasets`). Counts use `count`; duration metrics support
-   *    `avg`, `median`, `min`, `max` and `percentile` (pass `percentile: 95` for
-   *    p95); rate metrics use `value`.
+   *    `sum`, `avg`, `median`, `min`, `max`, `range` and `percentile` (pass
+   *    `percentile: 95` for p95); rate metrics use `value`.
    * 2. Set the reporting window with `startDate` / `endDate` (ISO 8601) and a
    *    `granularity` (`hour`, `day`, `week`, `month`) for the returned time series.
+   *    Reporting data is available from **July 12, 2026**. Windows ending earlier
+   *    are rejected; crossing windows are clamped to that boundary in the requested
+   *    timezone.
    * 3. Optionally narrow with `filters` — a rule
    *    (`{ "kind": "rule", "fieldId": "...", "operator": "in", "value": [...] }`) or
    *    an `and`/`or` group of rules. Attribute IDs and allowed operators come from
@@ -78,14 +81,39 @@ export class Reports extends APIResource {
    * 5. Optionally pass `compareStartDate` / `compareEndDate` to get `previousValue`
    *    / `deltaPercent` alongside every data point.
    *
+   * ### Top-N and Show Other
+   *
+   * For high-cardinality breakdowns, cap the number of returned series:
+   *
+   * - `topValuesLimit` keeps only the top **N** `groupBy` values;
+   *   `segmentTopValuesLimit` does the same for `segmentBy`. Allowed values: **5, 7,
+   *   10, 15, 20**. `topValuesLimit` requires `groupBy`; `segmentTopValuesLimit`
+   *   requires `segmentBy`.
+   * - Members are ranked by the selected metric/aggregation over the **full filtered
+   *   primary range**, so the ranked set is **stable across every time bucket** (a
+   *   value that spikes in one bucket but is small overall does not enter the set).
+   *   A comparison period reuses the **primary period's** ranked set — it is never
+   *   re-ranked, so the legend stays identical period-over-period.
+   * - `showOther` / `segmentShowOther` append a single synthetic bucket with id
+   *   `__other__` and label `Other` that sums every value outside the top set.
+   *   Because the values are summed, Show Other is only supported for **additive
+   *   aggregations** (`count`, `sum`, `value`); it is rejected for `avg`, `median`,
+   *   `min`, `max`, `range`, `percentile`, and for percentage metrics (whose ratios
+   *   cannot be summed). `showOther` also requires `topValuesLimit` (and
+   *   `segmentShowOther` requires `segmentTopValuesLimit`). Plain `topValuesLimit`
+   *   (without Show Other) works with any aggregation.
+   * - The `__other__` group/segment aggregates rows outside the selected top groups
+   *   and **cannot be drilled into** (`POST /v2/reports/drill-in` rejects
+   *   `dataPointFilters.groupValue` / `segmentValue` equal to `__other__`).
+   *
    * ### Example
    *
    * ```json
    * {
    *   "metric": "new_conversations",
    *   "aggregation": "count",
-   *   "startDate": "2026-06-01",
-   *   "endDate": "2026-06-30",
+   *   "startDate": "2026-07-12",
+   *   "endDate": "2026-07-15",
    *   "granularity": "day",
    *   "groupBy": "conversation.channel",
    *   "filters": {
@@ -121,10 +149,10 @@ export class Reports extends APIResource {
    * ```ts
    * const response = await client.reports.query({
    *   aggregation: 'count',
-   *   endDate: '2026-06-30',
+   *   endDate: '2026-07-15',
    *   granularity: 'day',
    *   metric: 'new_conversations',
-   *   startDate: '2026-06-01',
+   *   startDate: '2026-07-12',
    * });
    * ```
    */
@@ -222,10 +250,10 @@ export class Reports extends APIResource {
    * @example
    * ```ts
    * const response = await client.reports.drillIn({
-   *   endDate: 'xxxxxxxxxx',
+   *   endDate: '2026-07-15',
    *   granularity: 'day',
    *   metric: 'new_conversations',
-   *   startDate: 'xxxxxxxxxx',
+   *   startDate: '2026-07-12',
    * });
    * ```
    */
@@ -275,6 +303,12 @@ export interface ReportAttribute {
 
   name: string;
 
+  /**
+   * Whether the filter uses the latest mutable state, an immutable historical
+   * action/snapshot, or a metric-dependent mapping.
+   */
+  semantics: 'current_state' | 'historical_action' | 'historical_snapshot' | 'dynamic_metric_mapped';
+
   /**
    * Whether the attribute can be used in `filters` rules.
    */
@@ -405,12 +439,24 @@ export interface ReportMetric {
    */
   id: string;
 
-  allowedAggregations: Array<'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'percentile' | 'value'>;
+  allowedAggregations: Array<
+    'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value'
+  >;
 
   description: string;
 
   name: string;
 
+  /**
+   * Attribute IDs this specific metric accepts in filter expressions.
+   */
+  supportedFilterAttributeIds: Array<string>;
+
+  /**
+   * Attribute IDs this specific metric accepts as `groupBy` or `segmentBy`.
+   */
+  supportedGroupByDimensions: Array<string>;
+
   /**
    * Which `view` values `POST /v2/reports/query` accepts for this metric. Most
    * metrics support `standard` and `hourly_heatmap`; conversation-flow metrics are
@@ -425,6 +471,36 @@ export interface ReportMetric {
   type: 'count' | 'percentage' | 'duration' | 'number';
 
   unit: 'count' | 'percentage' | 'duration_ms' | 'number';
+
+  /**
+   * Local calendar date (ISO 8601) from which this specific metric has data, when it
+   * differs from the global reporting floor. Windows ending before this date are
+   * rejected for this metric.
+   */
+  dataAvailableFromIso?: string;
+
+  /**
+   * Whether this variant is the default selection for its `variantGroupId`.
+   */
+  isDefaultVariant?: boolean;
+
+  /**
+   * Metrics sharing a `variantGroupId` are timestamp variants of one logical metric
+   * (same display `name`); each measures the same population at a different
+   * timestamp. Query the concrete metric `id` to pick a variant.
+   */
+  variantGroupId?: string;
+
+  /**
+   * Stable identifier for this variant within its group (e.g. `created_at`,
+   * `started_at`).
+   */
+  variantId?: string;
+
+  /**
+   * Human-readable variant label for pickers (e.g. `Created at`, `Started at`).
+   */
+  variantLabel?: string;
 }
 
 export interface ReportSegmentDatum {
@@ -476,6 +552,7 @@ export interface ReportDrillInResponse {
       | boolean
       | Array<string>
       | ReportDrillInResponse.ReportDrillInIdentityCell
+      | ReportDrillInResponse.ReportDrillInSourceDetailsCell
       | null;
   }>;
 
@@ -493,6 +570,11 @@ export namespace ReportDrillInResponse {
 
     name: string;
 
+    /**
+     * Whether this column may be used in the drill-in sort request.
+     */
+    supportsSort: boolean;
+
     valueType: string;
 
     category?: string;
@@ -502,6 +584,43 @@ export namespace ReportDrillInResponse {
     datasetId: string;
 
     metricId: string;
+
+    rawMetricId: string;
+
+    reconciliation: Meta.Reconciliation;
+
+    rowGrain: string;
+
+    rowSemantics: 'metric_rows' | 'numerator_rows';
+
+    sourceFact: string;
+
+    emptyReason?: 'no_matching_rows' | 'denominator_unavailable';
+
+    metricRowId?: string;
+  }
+
+  export namespace Meta {
+    export interface Reconciliation {
+      kind:
+        | 'rows'
+        | 'actions_across_conversations'
+        | 'active_hour_rate'
+        | 'positive_ratings_over_eligible_ratings'
+        | 'missed_over_evaluated';
+
+      rowCount: number;
+
+      status: 'not_applicable' | 'available' | 'denominator_unavailable';
+
+      denominatorHours?: number;
+
+      displayedRate?: number;
+
+      eligibleDenominatorTotal?: number;
+
+      rawNumeratorTotal?: number;
+    }
   }
 
   export interface ReportDrillInIdentityCell {
@@ -514,6 +633,26 @@ export namespace ReportDrillInResponse {
     avatarUrl?: string;
 
     color?: string;
+
+    provenance?: 'current' | 'historical' | 'fallback' | 'unassigned';
+  }
+
+  export interface ReportDrillInSourceDetailsCell {
+    items: Array<ReportDrillInSourceDetailsCell.Item>;
+
+    kind: 'source_details';
+  }
+
+  export namespace ReportDrillInSourceDetailsCell {
+    export interface Item {
+      label: string;
+
+      id?: string;
+
+      type?: string;
+
+      url?: string;
+    }
   }
 }
 
@@ -555,6 +694,8 @@ export interface ReportQueryResponse {
 
   segmentData?: Array<ReportSegmentDatum>;
 
+  table?: ReportQueryResponse.Table;
+
   timeSeries?: Array<ReportTimeSeriesDatum>;
 }
 
@@ -565,7 +706,7 @@ export namespace ReportQueryResponse {
      * aggregations — see the `allowedAggregations` field in the
      * `GET /v2/reports/datasets` catalog.
      */
-    aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'percentile' | 'value';
+    aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value';
 
     datasetId: string;
 
@@ -603,6 +744,98 @@ export namespace ReportQueryResponse {
 
     sortOrder?: number;
   }
+
+  export interface Table {
+    columns: Array<Table.Column>;
+
+    key: string;
+
+    mode: 'aggregate' | 'records';
+
+    page: number;
+
+    pageSize: number;
+
+    rows: Array<Table.Row>;
+
+    totalRows: number;
+
+    sort?: Table.Sort;
+
+    summaryRows?: Array<Table.SummaryRow>;
+  }
+
+  export namespace Table {
+    export interface Column {
+      id: string;
+
+      kind: 'dimension' | 'metric' | 'record_attribute';
+
+      label: string;
+
+      sortable: boolean;
+
+      unit: 'count' | 'percentage' | 'duration_ms' | 'number' | 'text' | 'datetime';
+
+      align?: 'left' | 'right';
+
+      sticky?: boolean;
+
+      summary?: 'sum' | 'weighted_rate' | 'none';
+
+      valueType?: string;
+    }
+
+    export interface Row {
+      id: string;
+
+      cells: { [key: string]: Row.Cells };
+    }
+
+    export namespace Row {
+      export interface Cells {
+        display: string;
+
+        denominator?: number;
+
+        numerator?: number;
+
+        raw?: unknown;
+
+        sortValue?: string | number | null;
+
+        value?: unknown;
+      }
+    }
+
+    export interface Sort {
+      columnId: string;
+
+      direction: 'asc' | 'desc';
+    }
+
+    export interface SummaryRow {
+      id: string;
+
+      cells: { [key: string]: SummaryRow.Cells };
+    }
+
+    export namespace SummaryRow {
+      export interface Cells {
+        display: string;
+
+        denominator?: number;
+
+        numerator?: number;
+
+        raw?: unknown;
+
+        sortValue?: string | number | null;
+
+        value?: unknown;
+      }
+    }
+  }
 }
 
 export interface ReportListDatasetsParams {
@@ -619,10 +852,11 @@ export interface ReportQueryParams {
    * subset of aggregations — see the `allowedAggregations` field in the
    * `GET /v2/reports/datasets` catalog.
    */
-  aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'percentile' | 'value';
+  aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value';
 
   /**
    * Body param: End of the reporting window (ISO 8601 date or datetime, inclusive).
+   * Windows ending before 2026-07-12 are rejected.
    */
   endDate: string;
 
@@ -639,7 +873,8 @@ export interface ReportQueryParams {
 
   /**
    * Body param: Start of the reporting window (ISO 8601 date or datetime,
-   * inclusive).
+   * inclusive). Reporting data is available from 2026-07-12; crossing windows are
+   * clamped to that boundary.
    */
   startDate: string;
 
@@ -685,12 +920,48 @@ export interface ReportQueryParams {
    */
   segmentBy?: string;
 
+  /**
+   * Body param: When `true`, fold `segmentBy` values outside the top set into a
+   * synthetic `__other__` / `Other` segment. Only supported for additive
+   * aggregations (`count`, `sum`, `value`) and not for percentage metrics. The
+   * `__other__` segment cannot be drilled into. Requires `segmentBy` and
+   * `segmentTopValuesLimit`.
+   */
+  segmentShowOther?: boolean;
+
+  /**
+   * Body param: Keep only the top N `segmentBy` values per series, ranked by the
+   * selected metric over the full filtered primary range. Under a time View-by the
+   * ranked segment set is identical across every bucket; under a dimension View-by
+   * the ranking is applied within each retained parent group. Allowed values: `5`,
+   * `7`, `10`, `15`, `20`. Requires `segmentBy`.
+   */
+  segmentTopValuesLimit?: 5 | 7 | 10 | 15 | 20;
+
+  /**
+   * Body param: When `true`, append a single synthetic group with id `__other__` and
+   * label `Other` that sums the values of every `groupBy` value outside the top set.
+   * Only supported for additive aggregations (`count`, `sum`, `value`) and not for
+   * percentage metrics. The `__other__` group cannot be drilled into. Requires
+   * `groupBy` and `topValuesLimit`.
+   */
+  showOther?: boolean;
+
   /**
    * Body param: IANA timezone for date bucketing (e.g. `America/New_York`). Defaults
    * to UTC.
    */
   timezone?: string;
 
+  /**
+   * Body param: Keep only the top N `groupBy` (View-by) values, ranked by the
+   * selected metric/aggregation over the full filtered primary range. Allowed
+   * values: `5`, `7`, `10`, `15`, `20`. The ranked set is stable across every time
+   * bucket, and a comparison period reuses the primary period's ranked set (never
+   * re-ranked). Requires `groupBy`.
+   */
+  topValuesLimit?: 5 | 7 | 10 | 15 | 20;
+
   /**
    * Body param: Result shape. `standard` returns a time series (plus grouped/segment
    * data when requested), `hourly_heatmap` buckets by day-of-week × hour-of-day,
@@ -738,7 +1009,8 @@ export interface ReportLookupFilterValuesParams {
 
 export interface ReportDrillInParams {
   /**
-   * Body param
+   * Body param: End of the reporting window (ISO 8601 date or datetime, inclusive).
+   * Windows ending before 2026-07-12 are rejected.
    */
   endDate: string;
 
@@ -753,10 +1025,23 @@ export interface ReportDrillInParams {
   metric: string;
 
   /**
-   * Body param
+   * Body param: Start of the reporting window (ISO 8601 date or datetime,
+   * inclusive). Reporting data is available from 2026-07-12; crossing windows are
+   * clamped to that boundary.
    */
   startDate: string;
 
+  /**
+   * Body param: Stable editor ID of the saved chart that launched this drill-in.
+   */
+  chartEditorId?: string;
+
+  /**
+   * Body param: Column IDs to include in each returned row. Omit for legacy
+   * full-width static rows; pass an empty array to use `defaultColumnIds`.
+   */
+  columns?: Array<string>;
+
   /**
    * Body param: Narrows the drill-in to one data point from a previous query (time
    * bucket, group value, heatmap cell, or flow edge). Pass `{}` to list all
@@ -803,6 +1088,11 @@ export interface ReportDrillInParams {
    */
   selectedMetricId?: string;
 
+  /**
+   * Body param: Stable metric-row ID selected within the launching chart.
+   */
+  selectedMetricRowId?: string;
+
   /**
    * Body param
    */

package/src/resources/support/conversations/conversations.ts

@@ -984,18 +984,53 @@ export class Conversations extends APIResource {
    * `participant_id`, `company_id`, `created_at`) are still accepted for back-compat
    * but are deprecated — please migrate to camelCase in new code.
    *
-   * | Field                      | Type                                                                        | Operators              |
-   * | -------------------------- | --------------------------------------------------------------------------- | ---------------------- |
-   * | `state`                    | enum (`open` / `closed` / `snoozed`)                                        | `=`, `!=`, `IN`, `NIN` |
-   * | `priority`                 | boolean                                                                     | `=`, `!=`              |
-   * | `adminAssigneeId`          | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN` |
-   * | `teamAssigneeId`           | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN` |
-   * | `brandId`                  | id or null                                                                  | `=`, `!=`, `IN`, `NIN` |
-   * | `tagIds`                   | id (matches any conversation containing this tag)                           | `=`, `!=`, `IN`, `NIN` |
-   * | `userId` / `participantId` | id of a conversation participant                                            | `=`, `!=`, `IN`, `NIN` |
-   * | `companyId`                | company id (matches conversations whose participants belong to the company) | `=`, `!=`, `IN`, `NIN` |
-   * | `mentionedAdminIds`        | admin id                                                                    | `=`, `!=`, `IN`, `NIN` |
-   * | `createdAt`                | unix seconds                                                                | `=`, `>`, `<`          |
+   * | Field                            | Type                                                                        | Operators                                                               |
+   * | -------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+   * | `state`                          | enum (`open` / `closed` / `snoozed`)                                        | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `priority`                       | boolean                                                                     | `=`, `!=`                                                               |
+   * | `adminAssigneeId`                | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `teamAssigneeId`                 | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `brandId`                        | id or null                                                                  | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `tagIds`                         | id (matches any conversation containing this tag)                           | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `userId` / `participantId`       | id of a conversation participant                                            | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `companyId`                      | company id (matches conversations whose participants belong to the company) | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `mentionedAdminIds`              | admin id                                                                    | `=`, `!=`, `IN`, `NIN`                                                  |
+   * | `createdAt`                      | unix seconds                                                                | `=`, `>`, `<`                                                           |
+   * | `customAttributes.<attributeId>` | conversation custom attribute (see below)                                   | `=`, `!=`, `IN`, `NIN`; plus `>`, `<`, `>=`, `<=` for `number` / `date` |
+   *
+   * ### Filtering by custom attributes
+   *
+   * Any non-archived conversation custom attribute can be used as a filter field via
+   * `customAttributes.<attributeId>`, where `<attributeId>` is the attribute's `id`
+   * from `GET /v2/conversation_attributes`. The accepted value shape follows the
+   * attribute's `fieldSubType`:
+   *
+   * - `select` / `multi-select` — pass an option **label** (e.g.
+   *   `"Product question"`) or an option **id**; both are matched interchangeably,
+   *   and id-based filters keep working after options are renamed
+   * - `text` — string
+   * - `number` — number; range operators (`>`, `<`, `>=`, `<=`) are supported
+   * - `date` — ISO 8601 string or unix seconds; range operators are supported
+   * - `checkbox` — boolean
+   *
+   * Example — all conversations where the "Issue type" select attribute is "Product
+   * question":
+   *
+   * ```json
+   * {
+   *   "query": {
+   *     "field": "customAttributes.6863d3fca1234b0d5e15c86c",
+   *     "operator": "=",
+   *     "value": "Product question"
+   *   },
+   *   "include": ["customAttributeDefinitions"]
+   * }
+   * ```
+   *
+   * Referencing an attribute id that does not exist (or has been archived) returns a
+   * `field_unknown` error. Set `include` to `["customAttributeDefinitions"]` to get
+   * each returned conversation's attribute values resolved with names and types
+   * alongside the ID-keyed `customAttributes` map.
    *
    * For unbounded fields a query consisting only of `!=` or `NIN` clauses is
    * rejected with `query_too_broad` to prevent full-org scans. Combine the negation
@@ -1329,9 +1364,11 @@ export namespace Conversation {
     requestId: string;
 
     /**
-     * Source that created the CSAT request
+     * Source that created the CSAT request. `workflow` = Ask For Conversation Rating
+     * workflow action, `fibi_auto` = automatic Fibi AI Agent survey on
+     * resolve/handoff.
      */
-    requestSource: 'workflow';
+    requestSource: 'workflow' | 'fibi_auto';
 
     /**
      * Lifecycle status for this historical CSAT request
@@ -1437,7 +1474,7 @@ export namespace Conversation {
     /**
      * Source of the latest CSAT request when known
      */
-    requestSource?: 'workflow';
+    requestSource?: 'workflow' | 'fibi_auto';
 
     /**
      * CSAT score from 1 to 5 when rated
@@ -2001,9 +2038,11 @@ export namespace ConversationPart {
       requestId: string;
 
       /**
-       * Source that created the CSAT request
+       * Source that created the CSAT request. `workflow` = Ask For Conversation Rating
+       * workflow action, `fibi_auto` = automatic Fibi AI Agent survey on
+       * resolve/handoff.
        */
-      requestSource: 'workflow';
+      requestSource: 'workflow' | 'fibi_auto';
 
       /**
        * Status of the CSAT request represented by this part
@@ -2088,9 +2127,11 @@ export namespace ConversationPart {
       requestId: string;
 
       /**
-       * Source that created the CSAT request
+       * Source that created the CSAT request. `workflow` = Ask For Conversation Rating
+       * workflow action, `fibi_auto` = automatic Fibi AI Agent survey on
+       * resolve/handoff.
        */
-      requestSource: 'workflow';
+      requestSource: 'workflow' | 'fibi_auto';
 
       /**
        * CSAT score from 1 to 5

package/src/resources/users/contacts/contacts.ts

@@ -140,7 +140,7 @@ export class Contacts extends APIResource {
    * | `subscribedToChangelog` | boolean | No                  | Whether subscribed to changelog         |
    * | `locale`                | string  | No                  | Contact locale/language                 |
    * | `phone`                 | string  | No                  | Contact phone number                    |
-   * | `roles`                 | array   | No                  | Role IDs to assign                      |
+   * | `roles`                 | array   | No                  | Role (User Tag) names to assign         |
    * | `userHash`              | string  | No                  | HMAC hash for identity verification     |
    * | `createdAt`             | string  | No                  | When the contact was created (ISO 8601) |
    *
@@ -994,7 +994,7 @@ export interface ContactCreateOrUpdateParams {
   profilePicture?: string | null;
 
   /**
-   * Body param: Array of role IDs to assign to the contact
+   * Body param: Array of role (User Tag) names to assign to the contact
    */
   roles?: Array<string>;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.14.1'; // x-release-please-version
+export const VERSION = '0.14.3'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.14.1";
+export declare const VERSION = "0.14.3";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.14.1";
+export declare const VERSION = "0.14.3";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.14.1'; // x-release-please-version
+exports.VERSION = '0.14.3'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.14.1'; // x-release-please-version
+export const VERSION = '0.14.3'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map