featurebase-node 0.14.0 → 0.14.2

package/src/resources/reports.ts

@@ -0,0 +1,1025 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as ReportsAPI from './reports';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * Query your workspace analytics: conversation volume, response times, CSAT, SLA compliance, teammate performance, AI agent resolutions and more. Start with the datasets catalog to discover metrics and attributes, then run queries with filters, grouping and period comparison.
+ */
+export class Reports extends APIResource {
+  /**
+   * Returns the reporting catalog: every dataset available to your workspace with
+   * its metrics and attributes.
+   *
+   * This is the discovery endpoint for the reporting API — read it before building
+   * query payloads:
+   *
+   * - **Metrics** carry the `metric` IDs accepted by `POST /v2/reports/query`, plus
+   *   each metric's `allowedAggregations`, unit, and whether it supports
+   *   office-hours restriction and period comparison.
+   * - **Attributes** carry the `fieldId`s accepted in filter rules and the attribute
+   *   IDs accepted as `groupBy` / `segmentBy`, plus each attribute's
+   *   `allowedOperators` and value type. Attributes with `staticOptions` list their
+   *   full value set inline; other filterable attributes resolve values via
+   *   `POST /v2/reports/filter-values`.
+   *
+   * The catalog includes your workspace's custom conversation/ticket attributes
+   * where applicable, so it can differ between workspaces.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer, and
+   * only for workspaces with the Reports product enabled (404 otherwise).
+   *
+   * @example
+   * ```ts
+   * const response = await client.reports.listDatasets();
+   * ```
+   */
+  listDatasets(
+    params: ReportListDatasetsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ReportListDatasetsResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get('/v2/reports/datasets', {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Executes an ad-hoc reporting query: one metric + aggregation over a date range,
+   * with optional filters, grouping, segmentation and period-over-period comparison.
+   *
+   * ### Building a query
+   *
+   * 1. Pick a `metric` and `aggregation` from the datasets catalog
+   *    (`GET /v2/reports/datasets`). Counts use `count`; duration metrics support
+   *    `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
+   *    the catalog.
+   * 4. Optionally break results down with `groupBy` (primary dimension) and
+   *    `segmentBy` (secondary dimension).
+   * 5. Optionally pass `compareStartDate` / `compareEndDate` to get `previousValue`
+   *    / `deltaPercent` alongside every data point.
+   *
+   * ### Example
+   *
+   * ```json
+   * {
+   *   "metric": "new_conversations",
+   *   "aggregation": "count",
+   *   "startDate": "2026-07-12",
+   *   "endDate": "2026-07-15",
+   *   "granularity": "day",
+   *   "groupBy": "conversation.channel",
+   *   "filters": {
+   *     "kind": "rule",
+   *     "fieldId": "conversation.state",
+   *     "operator": "is",
+   *     "value": "closed"
+   *   }
+   * }
+   * ```
+   *
+   * ### Response shape
+   *
+   * - `value` — the aggregate across the whole window
+   * - `timeSeries` — one datum per granularity bucket
+   * - `groupedData` / `segmentData` — present when `groupBy` / `segmentBy` were
+   *   requested
+   * - `flowData` — present for `view: "sankey"` (Overview conversation-flow metrics)
+   * - `meta` — echo of the resolved metric, dataset, unit and aggregation
+   *
+   * ### Special views
+   *
+   * - `view: "hourly_heatmap"` buckets by day-of-week × hour-of-day (use with volume
+   *   metrics)
+   * - `view: "sankey"` returns conversation flow edges (Overview metrics only)
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer, and
+   * only for workspaces with the Reports product enabled (404 otherwise).
+   *
+   * @example
+   * ```ts
+   * const response = await client.reports.query({
+   *   aggregation: 'count',
+   *   endDate: '2026-07-15',
+   *   granularity: 'day',
+   *   metric: 'new_conversations',
+   *   startDate: '2026-07-12',
+   * });
+   * ```
+   */
+  query(params: ReportQueryParams, options?: RequestOptions): APIPromise<ReportQueryResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/reports/query', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns the available values for a filterable attribute — use it to build valid
+   * `filters` rules for `POST /v2/reports/query`.
+   *
+   * Works for attributes whose values live in your workspace data (tags, teammates,
+   * teams, companies, plans, countries, ...). Attributes with `staticOptions` in the
+   * catalog don't need this endpoint — their value set is already inline.
+   *
+   * - `query` narrows results by search string
+   * - `selectedValues` resolves labels for values you already hold (returned
+   *   alongside search results)
+   *
+   * ### Example
+   *
+   * ```json
+   * { "fieldId": "conversation.tags", "query": "bill", "limit": 20 }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer, and
+   * only for workspaces with the Reports product enabled (404 otherwise).
+   *
+   * @example
+   * ```ts
+   * const response = await client.reports.lookupFilterValues({
+   *   fieldId: 'conversation.tags',
+   * });
+   * ```
+   */
+  lookupFilterValues(
+    params: ReportLookupFilterValuesParams,
+    options?: RequestOptions,
+  ): APIPromise<ReportLookupFilterValuesResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/reports/filter-values', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns the paginated row-level records behind a metric — either the whole
+   * reporting window, or one specific data point from a previous
+   * `POST /v2/reports/query` response.
+   *
+   * Send the **same** `metric`, date range, `granularity`, `filters`, `groupBy` /
+   * `segmentBy` and `view` as the query you're drilling into, plus
+   * `dataPointFilters` selecting the data point:
+   *
+   * - `timeBucket` — a `date` from the time series
+   * - `groupValue` / `segmentValue` — a `group` / `segment` value from grouped data
+   * - `dayOfWeek` + `hourOfDay` — a heatmap cell (`hourly_heatmap` view)
+   * - `flowPathId` or `sourceNodeId` + `targetNodeId` — a flow edge (`sankey` view)
+   *
+   * Pass `dataPointFilters: {}` to list all rows behind the metric for the window.
+   *
+   * Results are paginated with `page` / `pageSize` (max 200 per page);
+   * `availableColumns` describes every column the dataset can return and
+   * `defaultColumnIds` the recommended subset. Rows are keyed by column ID; identity
+   * cells (teammates, contacts) are objects with `id` + `label`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer, and
+   * only for workspaces with the Reports product enabled (404 otherwise).
+   *
+   * @example
+   * ```ts
+   * const response = await client.reports.drillIn({
+   *   endDate: 'xxxxxxxxxx',
+   *   granularity: 'day',
+   *   metric: 'new_conversations',
+   *   startDate: 'xxxxxxxxxx',
+   * });
+   * ```
+   */
+  drillIn(params: ReportDrillInParams, options?: RequestOptions): APIPromise<ReportDrillInResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/reports/drill-in', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface ReportAttribute {
+  /**
+   * Attribute ID — use as `fieldId` in filter rules and as `groupBy` / `segmentBy`
+   * in query requests.
+   */
+  id: string;
+
+  allowedOperators: Array<
+    | 'is'
+    | 'is_not'
+    | 'in'
+    | 'not_in'
+    | 'contains'
+    | 'not_contains'
+    | 'gte'
+    | 'lte'
+    | 'between'
+    | 'exists'
+    | 'not_exists'
+    | 'is_member_of'
+    | 'is_not_member_of'
+  >;
+
+  category: string;
+
+  description: string;
+
+  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.
+   */
+  supportsFilter: boolean;
+
+  /**
+   * Whether the attribute can be used as `groupBy` / `segmentBy`.
+   */
+  supportsGroupBy: boolean;
+
+  /**
+   * Whether `POST /v2/reports/filter-values` can list this attribute's values.
+   */
+  supportsValueLookup: boolean;
+
+  valueType: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'id';
+
+  multiValue?: boolean;
+
+  /**
+   * Fixed value set for enum-like attributes. Attributes without static options
+   * resolve values via `POST /v2/reports/filter-values`.
+   */
+  staticOptions?: Array<ReportAttributeOption>;
+}
+
+export interface ReportAttributeOption {
+  label: string;
+
+  value: string;
+}
+
+export interface ReportDataset {
+  id: string;
+
+  attributes: Array<ReportAttribute>;
+
+  description: string;
+
+  metrics: Array<ReportMetric>;
+
+  name: string;
+}
+
+export interface ReportFilterExpression {
+  /**
+   * Rules and/or nested groups of rules. Groups may nest up to 6 levels at runtime;
+   * 100 rules max per expression.
+   */
+  children: Array<ReportFilterRule | ReportFilterExpression.ReportFilterGroup>;
+
+  kind: 'group';
+
+  /**
+   * Group operator: `and` (all match) or `or` (any match).
+   */
+  op: 'and' | 'or';
+}
+
+export namespace ReportFilterExpression {
+  export interface ReportFilterGroup {
+    children: Array<ReportsAPI.ReportFilterRule>;
+
+    kind: 'group';
+
+    /**
+     * Group operator: `and` (all match) or `or` (any match).
+     */
+    op: 'and' | 'or';
+  }
+}
+
+export interface ReportFilterRule {
+  /**
+   * Attribute ID to filter on (e.g. `conversation.channel`). Discover attribute IDs
+   * via `GET /v2/reports/datasets`.
+   */
+  fieldId: string;
+
+  kind: 'rule';
+
+  /**
+   * Comparison operator. Each attribute supports a subset of operators — see the
+   * `allowedOperators` field in the `GET /v2/reports/datasets` catalog.
+   */
+  operator:
+    | 'is'
+    | 'is_not'
+    | 'in'
+    | 'not_in'
+    | 'contains'
+    | 'not_contains'
+    | 'gte'
+    | 'lte'
+    | 'between'
+    | 'exists'
+    | 'not_exists'
+    | 'is_member_of'
+    | 'is_not_member_of';
+
+  /**
+   * Value to compare against. Scalar for `is`, `is_not`, `contains`, `not_contains`,
+   * `gte`, `lte` (ISO date strings for date attributes); non-empty array for `in`,
+   * `not_in`, `is_member_of`, `is_not_member_of`; 2-element array for `between`;
+   * omit for `exists` / `not_exists`.
+   */
+  value?: string | number | boolean | Array<string | number | boolean>;
+}
+
+export interface ReportGroupedDatum {
+  /**
+   * Raw group value (e.g. an ID). Use `groupLabel` for display.
+   */
+  group: string;
+
+  value: number;
+
+  groupLabel?: string;
+
+  previousValue?: number;
+
+  segments?: Array<ReportSegmentDatum>;
+}
+
+export interface ReportMetric {
+  /**
+   * Metric ID — use as `metric` in query requests.
+   */
+  id: string;
+
+  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
+   * `sankey`-only.
+   */
+  supportedViews: Array<'standard' | 'hourly_heatmap' | 'sankey'>;
+
+  supportsOfficeHours: boolean;
+
+  supportsPeriodComparison: boolean;
+
+  type: 'count' | 'percentage' | 'duration' | 'number';
+
+  unit: 'count' | 'percentage' | 'duration_ms' | 'number';
+}
+
+export interface ReportSegmentDatum {
+  segment: string;
+
+  value: number;
+
+  previousValue?: number;
+
+  segmentLabel?: string;
+}
+
+export interface ReportTimeSeriesDatum {
+  /**
+   * Time bucket start (ISO 8601).
+   */
+  date: string;
+
+  value: number;
+
+  /**
+   * Value for the same bucket in the comparison window, when requested.
+   */
+  previousValue?: number;
+
+  segments?: Array<ReportSegmentDatum>;
+}
+
+export interface ReportDrillInResponse {
+  availableColumns: Array<ReportDrillInResponse.AvailableColumn>;
+
+  defaultColumnIds: Array<string>;
+
+  meta: ReportDrillInResponse.Meta;
+
+  object: 'report_drill_in_result';
+
+  page: number;
+
+  pageSize: number;
+
+  /**
+   * One record per underlying row, keyed by column ID.
+   */
+  rows: Array<{
+    [key: string]:
+      | string
+      | number
+      | boolean
+      | Array<string>
+      | ReportDrillInResponse.ReportDrillInIdentityCell
+      | null;
+  }>;
+
+  timezone: string;
+
+  total: number;
+}
+
+export namespace ReportDrillInResponse {
+  export interface AvailableColumn {
+    /**
+     * Column ID (an attribute ID or `metric.value`).
+     */
+    id: string;
+
+    name: string;
+
+    valueType: string;
+
+    category?: string;
+  }
+
+  export interface Meta {
+    datasetId: string;
+
+    metricId: string;
+  }
+
+  export interface ReportDrillInIdentityCell {
+    id: string;
+
+    kind: 'identity';
+
+    label: string;
+
+    avatarUrl?: string;
+
+    color?: string;
+  }
+}
+
+export interface ReportListDatasetsResponse {
+  data: Array<ReportDataset>;
+
+  object: 'list';
+}
+
+export interface ReportLookupFilterValuesResponse {
+  data: Array<ReportAttributeOption>;
+
+  object: 'list';
+}
+
+export interface ReportQueryResponse {
+  meta: ReportQueryResponse.Meta;
+
+  object: 'report_query_result';
+
+  /**
+   * Aggregated value across the whole reporting window.
+   */
+  value: number;
+
+  /**
+   * Percentage change vs the comparison window.
+   */
+  deltaPercent?: number;
+
+  flowData?: Array<ReportQueryResponse.FlowData>;
+
+  groupedData?: Array<ReportGroupedDatum>;
+
+  /**
+   * Aggregated value for the comparison window, when requested.
+   */
+  previousValue?: number;
+
+  segmentData?: Array<ReportSegmentDatum>;
+
+  table?: ReportQueryResponse.Table;
+
+  timeSeries?: Array<ReportTimeSeriesDatum>;
+}
+
+export namespace ReportQueryResponse {
+  export interface Meta {
+    /**
+     * Aggregation function applied to the metric. Each metric supports a subset of
+     * aggregations — see the `allowedAggregations` field in the
+     * `GET /v2/reports/datasets` catalog.
+     */
+    aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value';
+
+    datasetId: string;
+
+    granularity: string;
+
+    metric: string;
+
+    officeHoursOnly: boolean;
+
+    unit: 'count' | 'percentage' | 'duration_ms' | 'number';
+
+    groupBy?: string;
+
+    segmentBy?: string;
+  }
+
+  export interface FlowData {
+    metricId: string;
+
+    pathId: string;
+
+    source: string;
+
+    sourceLabel: string;
+
+    target: string;
+
+    targetLabel: string;
+
+    value: number;
+
+    colorKey?: string;
+
+    percentage?: number;
+
+    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 {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface ReportQueryParams {
+  /**
+   * Body param: Aggregation function applied to the metric. Each metric supports a
+   * subset of aggregations — see the `allowedAggregations` field in the
+   * `GET /v2/reports/datasets` catalog.
+   */
+  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;
+
+  /**
+   * Body param: Time bucket size for the returned time series.
+   */
+  granularity: 'hour' | 'day' | 'week' | 'month';
+
+  /**
+   * Body param: Metric ID to query (e.g. `new_conversations`). Discover metric IDs
+   * via `GET /v2/reports/datasets`.
+   */
+  metric: string;
+
+  /**
+   * 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: End of the comparison window. Must be paired with
+   * `compareStartDate`.
+   */
+  compareEndDate?: string;
+
+  /**
+   * Body param: Start of the comparison window for period-over-period deltas. Must
+   * be paired with `compareEndDate`.
+   */
+  compareStartDate?: string;
+
+  /**
+   * Body param: Filter expression: a single rule, or an `and`/`or` group combining
+   * rules and nested groups. Attribute IDs and their allowed operators come from
+   * `GET /v2/reports/datasets`.
+   */
+  filters?: ReportFilterRule | ReportFilterExpression;
+
+  /**
+   * Body param: Attribute ID to group results by (e.g. `conversation.channel`). See
+   * `supportsGroupBy` in the catalog.
+   */
+  groupBy?: string;
+
+  /**
+   * Body param: Restrict time-based metrics to configured office hours. Only
+   * supported by some metrics (see `supportsOfficeHours` in the catalog).
+   */
+  officeHoursOnly?: boolean;
+
+  /**
+   * Body param: Percentile (1-100) — required when `aggregation` is `percentile`.
+   */
+  percentile?: number;
+
+  /**
+   * Body param: Attribute ID for secondary segmentation within each group or time
+   * bucket.
+   */
+  segmentBy?: string;
+
+  /**
+   * Body param: IANA timezone for date bucketing (e.g. `America/New_York`). Defaults
+   * to UTC.
+   */
+  timezone?: string;
+
+  /**
+   * 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,
+   * `sankey` returns conversation flow data. Each metric lists its `supportedViews`
+   * in the `GET /v2/reports/datasets` catalog.
+   */
+  view?: 'standard' | 'hourly_heatmap' | 'sankey';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface ReportLookupFilterValuesParams {
+  /**
+   * Body param: Attribute ID to look up values for (must have
+   * `valueSource: "remote_search"` or static options in the catalog).
+   */
+  fieldId: string;
+
+  /**
+   * Body param: Maximum number of options to return (1-50, default 20).
+   */
+  limit?: number;
+
+  /**
+   * Body param: Optional search string to narrow the returned options.
+   */
+  query?: string;
+
+  /**
+   * Body param: Already-selected values to resolve labels for (returned alongside
+   * search results).
+   */
+  selectedValues?: Array<string>;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface ReportDrillInParams {
+  /**
+   * Body param
+   */
+  endDate: string;
+
+  /**
+   * Body param: Time bucket size for the returned time series.
+   */
+  granularity: 'hour' | 'day' | 'week' | 'month';
+
+  /**
+   * Body param: Metric ID the drill-in belongs to.
+   */
+  metric: string;
+
+  /**
+   * Body param
+   */
+  startDate: 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
+   * underlying rows.
+   */
+  dataPointFilters?: ReportDrillInParams.DataPointFilters;
+
+  /**
+   * Body param: Filter expression: a single rule, or an `and`/`or` group combining
+   * rules and nested groups. Attribute IDs and their allowed operators come from
+   * `GET /v2/reports/datasets`.
+   */
+  filters?: ReportFilterRule | ReportFilterExpression;
+
+  /**
+   * Body param
+   */
+  groupBy?: string;
+
+  /**
+   * Body param
+   */
+  officeHoursOnly?: boolean;
+
+  /**
+   * Body param: Page number (1-based).
+   */
+  page?: number;
+
+  /**
+   * Body param: Rows per page (1-200, default 25).
+   */
+  pageSize?: number;
+
+  /**
+   * Body param
+   */
+  segmentBy?: string;
+
+  /**
+   * Body param: A metric ID from the datasets catalog. Use when the originating
+   * chart aggregates several metrics to pick which one the drill-in follows.
+   * Defaults to `metric`.
+   */
+  selectedMetricId?: string;
+
+  /**
+   * Body param
+   */
+  sort?: Array<ReportDrillInParams.Sort>;
+
+  /**
+   * Body param
+   */
+  timezone?: string;
+
+  /**
+   * 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,
+   * `sankey` returns conversation flow data. Each metric lists its `supportedViews`
+   * in the `GET /v2/reports/datasets` catalog.
+   */
+  view?: 'standard' | 'hourly_heatmap' | 'sankey';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export namespace ReportDrillInParams {
+  /**
+   * 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 underlying rows.
+   */
+  export interface DataPointFilters {
+    /**
+     * Day of week (1 = Monday … 7 = Sunday) — for `hourly_heatmap` views.
+     */
+    dayOfWeek?: number;
+
+    /**
+     * Flow path ID — for `sankey` views.
+     */
+    flowPathId?: string;
+
+    /**
+     * Group value to drill into (a `group` value from `groupedData`).
+     */
+    groupValue?: string;
+
+    /**
+     * Hour of day (0-23) — for `hourly_heatmap` views.
+     */
+    hourOfDay?: number;
+
+    /**
+     * Segment value to drill into (a `segment` value from segment data).
+     */
+    segmentValue?: string;
+
+    /**
+     * Flow source node ID — for `sankey` views.
+     */
+    sourceNodeId?: string;
+
+    /**
+     * Flow target node ID — for `sankey` views.
+     */
+    targetNodeId?: string;
+
+    /**
+     * Time bucket to drill into (a `date` value from the query time series).
+     */
+    timeBucket?: string;
+  }
+
+  export interface Sort {
+    direction: 'asc' | 'desc';
+
+    /**
+     * Column ID to sort by (an attribute ID or `metric.value`).
+     */
+    fieldId: string;
+  }
+}
+
+export declare namespace Reports {
+  export {
+    type ReportAttribute as ReportAttribute,
+    type ReportAttributeOption as ReportAttributeOption,
+    type ReportDataset as ReportDataset,
+    type ReportFilterExpression as ReportFilterExpression,
+    type ReportFilterRule as ReportFilterRule,
+    type ReportGroupedDatum as ReportGroupedDatum,
+    type ReportMetric as ReportMetric,
+    type ReportSegmentDatum as ReportSegmentDatum,
+    type ReportTimeSeriesDatum as ReportTimeSeriesDatum,
+    type ReportDrillInResponse as ReportDrillInResponse,
+    type ReportListDatasetsResponse as ReportListDatasetsResponse,
+    type ReportLookupFilterValuesResponse as ReportLookupFilterValuesResponse,
+    type ReportQueryResponse as ReportQueryResponse,
+    type ReportListDatasetsParams as ReportListDatasetsParams,
+    type ReportQueryParams as ReportQueryParams,
+    type ReportLookupFilterValuesParams as ReportLookupFilterValuesParams,
+    type ReportDrillInParams as ReportDrillInParams,
+  };
+}