Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

86.7 KB
Raw Blame
import type { FunnelLayout } from 'lib/constants'
import type { AggregationAxisFormat } from 'lib/insights/aggregationAxisFormat'

import {
    BehavioralPropertyFilter,
    BinCountValue,
    BreakdownAttributionType,
    BreakdownType,
    ChartDisplayType,
    FilterLogicalOperator,
    FunnelConversionWindowTimeUnit,
    FunnelMathType,
    FunnelStepReference,
    FunnelVizType,
    IntervalType,
    LifecycleToggle,
    PathType,
    PropertyFilterType,
    PropertyOperator,
    RetentionPeriod,
    RetentionType,
    StepOrderValue,
} from '~/types'

import {
    ActionsNode,
    CompareFilter,
    DateRange,
    ErrorTrackingIssueAssignee,
    ErrorTrackingOrderBy,
    ErrorTrackingQueryStatus,
    EventsNode,
    EventsQuery,
    FunnelExclusionSteps,
    InsightNodeKind,
    MultipleBreakdownType,
    Node,
    NodeKind,
    PieChartSettings,
    type RecordingOrder,
    type RecordingOrderDirection,
    StickinessComputationMode,
    StickinessCriteria,
    TrendsFormulaNode,
} from './schema-general'
import { integer, positive_integer } from './type-utils'

/**
 * This filter only works with absolute dates. A bound without a UTC offset is read in the project timezone.
 */
export interface AssistantDateRange {
    /**
     * ISO8601 date string.
     */
    date_from: string
    /**
     * ISO8601 date string. A calendar day without a time (`2026-09-01`) is inclusive to the last moment of that day.
     */
    date_to?: string | null
}

/**
 * This filter only works with durations.
 */
export interface AssistantDurationRange {
    /**
     * Duration in the past. Supported units are: `h` (hour), `d` (day), `w` (week), `m` (month), `y` (year), `all` (all time). Use the `Start` suffix to define the exact left date boundary.
     * Examples: `-1d` last day from now, `-180d` last 180 days from now, `mStart` this month start, `-1dStart` yesterday's start.
     */
    date_from: string
}

export type AssistantDateRangeFilter = AssistantDateRange | AssistantDurationRange

export type AssistantArrayPropertyFilterOperator = PropertyOperator.Exact | PropertyOperator.IsNot
export interface AssistantArrayPropertyFilter {
    /**
     * `exact` - exact match of any of the values.
     * `is_not` - does not match any of the values.
     */
    operator: AssistantArrayPropertyFilterOperator
    /**
     * Only use property values from the plan. Always use strings as values. If you have a number, convert it to a string first. If you have a boolean, convert it to a string "true" or "false".
     */
    value: string[]
}

export type AssistantSetPropertyFilterOperator = PropertyOperator.IsSet | PropertyOperator.IsNotSet

export interface AssistantSetPropertyFilter {
    /**
     * `is_set` - the property has any value.
     * `is_not_set` - the property doesn't have a value or wasn't collected.
     */
    operator: AssistantSetPropertyFilterOperator
}

export type AssistantStringOrBooleanValuePropertyFilterOperator =
    | PropertyOperator.Exact
    | PropertyOperator.IsNot
    | PropertyOperator.IContains
    | PropertyOperator.NotIContains
    | PropertyOperator.Regex
    | PropertyOperator.NotRegex

export interface AssistantStringOrBooleanValuePropertyFilter {
    /**
     * `icontains` - case insensitive contains.
     * `not_icontains` - case insensitive does not contain.
     * `regex` - matches the regex pattern.
     * `not_regex` - does not match the regex pattern.
     */
    operator: AssistantStringOrBooleanValuePropertyFilterOperator
    /**
     * Only use property values from the plan. If the operator is `regex` or `not_regex`, the value must be a valid ClickHouse regex pattern to match against.
     * Otherwise, the value must be a substring that will be matched against the property value.
     * Use the string values `true` or `false` for boolean properties.
     */
    value: string | 'true' | 'false'
}

export type AssistantNumericValuePropertyFilterOperator =
    | PropertyOperator.Exact
    | PropertyOperator.GreaterThan
    | PropertyOperator.LessThan

export interface AssistantNumericValuePropertyFilter {
    operator: AssistantNumericValuePropertyFilterOperator
    value: number
}

export type AssistantStringNumberOrBooleanPropertyFilter =
    | AssistantStringOrBooleanValuePropertyFilter
    | AssistantNumericValuePropertyFilter
    | AssistantArrayPropertyFilter

export type AssistantDateTimePropertyFilterOperator =
    | PropertyOperator.IsDateExact
    | PropertyOperator.IsDateBefore
    | PropertyOperator.IsDateAfter

export interface AssistantDateTimePropertyFilter {
    operator: AssistantDateTimePropertyFilterOperator
    /**
     * Value must be a date in ISO 8601 format.
     */
    value: string
}

export type AssistantBasePropertyFilter =
    | AssistantStringNumberOrBooleanPropertyFilter
    | AssistantDateTimePropertyFilter
    | AssistantSetPropertyFilter

// TRICKY: Keep this property as enum to avoid converting to a string.
export enum AssistantGenericPropertyFilterType {
    event = PropertyFilterType.Event,
    person = PropertyFilterType.Person,
    session = PropertyFilterType.Session,
    feature = PropertyFilterType.Feature,
}

export type AssistantGenericPropertyFilter = AssistantBasePropertyFilter & {
    type: AssistantGenericPropertyFilterType
    /**
     * Use one of the properties the user has provided in the plan.
     */
    key: string
}

export type AssistantGroupPropertyFilter = AssistantBasePropertyFilter & {
    type: PropertyFilterType.Group
    /**
     * Use one of the properties the user has provided in the plan.
     */
    key: string
    /**
     * Index of the group type from the group mapping.
     */
    group_type_index: integer
}

export interface AssistantCohortPropertyFilter {
    /**
     * Filter events by cohort membership. Use this to narrow down results to persons belonging to a specific cohort.
     * Use `operator: "in"` to include cohort members, or `operator: "not_in"` to exclude them.
     * Examples:
     * - Include: `{ type: "cohort", key: "id", value: 42, operator: "in" }`
     * - Exclude: `{ type: "cohort", key: "id", value: 42, operator: "not_in" }`
     */
    type: PropertyFilterType.Cohort
    key: 'id'
    /** The cohort ID to filter by. */
    value: integer
    /** @default in */
    operator: PropertyOperator.In | PropertyOperator.NotIn
}

export type AssistantElementPropertyFilter = AssistantBasePropertyFilter & {
    /**
     * Filter by autocaptured HTML element properties (`$autocapture`, `$rageclick`).
     * Example: `{ type: "element", key: "text", value: "Sign Up", operator: "exact" }`
     */
    type: PropertyFilterType.Element
    /**
     * The element property to filter on.
     * `tag_name` — HTML tag (e.g., `button`, `a`, `input`).
     * `text` — visible text content of the element.
     * `href` — the `href` attribute for links.
     * `selector` — a CSS selector matching the element (e.g., `div.main > button.cta`).
     */
    key: 'tag_name' | 'text' | 'href' | 'selector'
}

export interface AssistantHogQLPropertyFilter {
    /**
     * Filter by a HogQL boolean expression for advanced filtering that can't be expressed with standard property filters.
     */
    type: PropertyFilterType.HogQL
    /**
     * A HogQL boolean expression used as a filter condition.
     *
     * Examples:
     * - Filter where a property exceeds a threshold: `toFloat(properties.load_time) > 5.0`
     * - Filter with string matching: `properties.$current_url LIKE '%/pricing%'`
     * - Filter with multiple conditions: `properties.$browser = 'Chrome' AND toFloat(properties.duration) > 30`
     */
    key: string
}

export interface AssistantFlagPropertyFilter {
    /**
     * Filter events by feature flag state — only include events where a specific flag evaluated to a given value.
     * Examples:
     * - Flag enabled: `{ type: "flag", key: "new-onboarding", operator: "flag_evaluates_to", value: true }`
     * - Specific variant: `{ type: "flag", key: "checkout-experiment", operator: "flag_evaluates_to", value: "variant-a" }`
     */
    type: PropertyFilterType.Flag
    /** The feature flag key. */
    key: string
    operator: PropertyOperator.FlagEvaluatesTo
    /** `true`/`false` for boolean flags, or a variant name string for multivariate flags. */
    value: boolean | string
}

export type AssistantRecordingPropertyFilter = AssistantBasePropertyFilter & {
    type: PropertyFilterType.Recording
    /**
     * Recording metric to filter on.
     * - `duration` — total recording duration in seconds.
     * - `active_seconds` — seconds with user activity.
     * - `inactive_seconds` — seconds without user activity.
     * - `console_error_count` — number of console errors.
     * - `console_log_count` — number of console log entries.
     * - `console_warn_count` — number of console warnings.
     * - `click_count` — number of clicks.
     * - `keypress_count` — number of key presses.
     * - `activity_score` — computed activity score (0-100).
     * - `visited_page` — URL visited during the session.
     * - `snapshot_source` — the recording source (e.g. "web", "mobile").
     */
    key:
        | 'duration'
        | 'active_seconds'
        | 'inactive_seconds'
        | 'console_error_count'
        | 'console_log_count'
        | 'console_warn_count'
        | 'click_count'
        | 'keypress_count'
        | 'activity_score'
        | 'visited_page'
        | 'snapshot_source'
}

export type AssistantPropertyFilter =
    | AssistantGenericPropertyFilter
    | AssistantGroupPropertyFilter
    | AssistantCohortPropertyFilter
    | AssistantElementPropertyFilter
    | AssistantHogQLPropertyFilter
    | AssistantFlagPropertyFilter

export type AssistantBehavioralPropertyFilterOperator =
    | PropertyOperator.Exact
    | PropertyOperator.GreaterThan
    | PropertyOperator.GreaterThanOrEqual
    | PropertyOperator.LessThan
    | PropertyOperator.LessThanOrEqual

export interface AssistantBehavioralPropertyFilter extends Omit<BehavioralPropertyFilter, 'operator'> {
    operator?: AssistantBehavioralPropertyFilterOperator
}

export type AssistantInsightPropertyFilter = AssistantPropertyFilter | AssistantBehavioralPropertyFilter

/**
 * Extended property filter union for recordings queries that also supports
 * recording-specific metric filters (e.g. duration, click_count, activity_score).
 */
export type AssistantRecordingsQueryPropertyFilter = AssistantPropertyFilter | AssistantRecordingPropertyFilter

export interface AssistantInsightsQueryBase {
    /**
     * Date range for the query
     */
    dateRange?: AssistantDateRangeFilter

    /**
     * Exclude internal and test users by applying the respective filters
     *
     * @default false
     */
    filterTestAccounts?: boolean

    /**
     * Property filters for all series
     *
     * @default []
     */
    properties?: AssistantInsightPropertyFilter[]

    /**
     * Sampling rate from 0 to 1 where 1 is 100% of the data.
     */
    samplingFactor?: number | null

    /**
     * Groups aggregation
     */
    aggregation_group_type_index?: integer | null
}

/**
 * Defines the event series.
 */
export interface AssistantTrendsEventsNode extends Omit<
    EventsNode,
    | 'fixedProperties'
    | 'properties'
    | 'math_hogql'
    | 'limit'
    | 'groupBy'
    | 'orderBy'
    | 'response'
    | 'math_property_revenue_currency'
> {
    properties?: AssistantPropertyFilter[]

    /**
     * Custom HogQL expression for aggregation. Use when the predefined `math` types are not sufficient.
     * When set, `math` must be set to `hogql`.
     *
     * Examples:
     * - Sum a numeric property: `sum(toFloat(properties.$revenue))`
     * - Average of a property: `avg(toFloat(properties.load_time))`
     * - Count distinct values: `count(distinct properties.$session_id)`
     * - Conditional count: `countIf(toFloat(properties.duration) > 30)`
     * - Percentile: `quantile(0.95)(toFloat(properties.response_time))`
     */
    math_hogql?: string
}

/**
 * Defines the action series. You must provide the action ID in the `id` field and the name in the `name` field.
 */
export interface AssistantTrendsActionsNode extends Omit<
    ActionsNode,
    | 'fixedProperties'
    | 'properties'
    | 'math_hogql'
    | 'limit'
    | 'groupBy'
    | 'orderBy'
    | 'response'
    | 'name'
    | 'math_property_revenue_currency'
> {
    properties?: AssistantPropertyFilter[]
    /**
     * Action name from the plan.
     */
    name: string

    /**
     * Custom HogQL expression for aggregation. Use when the predefined `math` types are not sufficient.
     * When set, `math` must be set to `hogql`.
     *
     * Examples:
     * - Sum a numeric property: `sum(toFloat(properties.$revenue))`
     * - Average of a property: `avg(toFloat(properties.load_time))`
     * - Count distinct values: `count(distinct properties.$session_id)`
     * - Conditional count: `countIf(toFloat(properties.duration) > 30)`
     * - Percentile: `quantile(0.95)(toFloat(properties.response_time))`
     */
    math_hogql?: string
}

/**
 * Defines a series that combines multiple events or actions with OR (e.g. "Pageview OR Pageleave"
 * as one line). Aggregation (`math*`) is read from the group, not the inner nodes — set it here.
 * Inner-node `event` / `id` / `properties` / `name` are respected normally; per-node `properties`
 * apply only to that node, so each event can carry its own filter.
 */
export interface AssistantTrendsGroupNode {
    kind: NodeKind.GroupNode
    /** Only `OR` is supported. */
    operator: FilterLogicalOperator.Or
    /**
     * Events and actions combined into the series. Mirror the group's `math*` on each node for
     * UI round-trip; they're ignored at execution time.
     * @minItems 2
     */
    nodes: (AssistantTrendsEventsNode | AssistantTrendsActionsNode)[]
    /** Display name for the combined series. */
    name?: string
    custom_name?: string
    /** Math aggregation for the combined series. The engine reads aggregation from here, not from inner nodes. */
    math?: AssistantTrendsEventsNode['math']
    math_property?: AssistantTrendsEventsNode['math_property']
    math_property_type?: AssistantTrendsEventsNode['math_property_type']
    math_multiplier?: AssistantTrendsEventsNode['math_multiplier']
    math_group_type_index?: AssistantTrendsEventsNode['math_group_type_index']
    /** Custom HogQL aggregation. When set, `math` must be `hogql`. */
    math_hogql?: string
}

export interface AssistantBaseMultipleBreakdownFilter {
    /**
     * Property name from the plan to break down by.
     */
    property: string
}

export interface AssistantGroupMultipleBreakdownFilter extends AssistantBaseMultipleBreakdownFilter {
    type: 'group'
    /**
     * Index of the group type from the group mapping.
     */
    group_type_index?: integer | null
}

export type AssistantEventMultipleBreakdownFilterType = Exclude<MultipleBreakdownType, 'group'>

export interface AssistantGenericMultipleBreakdownFilter extends AssistantBaseMultipleBreakdownFilter {
    type: AssistantEventMultipleBreakdownFilterType
}

export type AssistantMultipleBreakdownFilter =
    | AssistantGroupMultipleBreakdownFilter
    | AssistantGenericMultipleBreakdownFilter

export interface AssistantBreakdownFilter {
    /**
     * How many distinct values to show.
     * @default 25
     */
    breakdown_limit?: integer
}

export interface AssistantTrendsBreakdownFilter extends AssistantBreakdownFilter {
    /**
     * Use this field to define breakdowns.
     * @maxItems 3
     */
    breakdowns: AssistantMultipleBreakdownFilter[]
    /**
     * When `true`, applies the project's configured path cleaning rules to URL or path breakdown values (e.g. `$pathname`, `$current_url`). Use this whenever the user asks for a breakdown by a URL or path property and there is no specific reason to keep the raw values. The user does not need to provide a regex — path cleaning rules come from the project's settings.
     */
    breakdown_path_cleaning?: boolean
}

// An allow list, so a new ChartDisplayType (often SQL-only) does not reach agents unless someone adds it here.
export type AssistantTrendsDisplayType =
    | ChartDisplayType.ActionsLineGraph
    | ChartDisplayType.ActionsBar
    | ChartDisplayType.ActionsUnstackedBar
    | ChartDisplayType.ActionsAreaGraph
    | ChartDisplayType.ActionsLineGraphCumulative
    | ChartDisplayType.SlopeGraph
    | ChartDisplayType.BoxPlot
    | ChartDisplayType.Metric
    | ChartDisplayType.BoldNumber
    | ChartDisplayType.ActionsBarValue
    | ChartDisplayType.ActionsPie
    | ChartDisplayType.ActionsDonut
    | ChartDisplayType.ActionsProportionBar
    | ChartDisplayType.ActionsTable
    | ChartDisplayType.WorldMap
    // Not in the `display` description: the MCP chart app cannot show calendar_heatmap_data yet.
    | ChartDisplayType.CalendarHeatmap

export interface AssistantTrendsFilter {
    /**
     * Use custom formulas to perform mathematical operations like calculating percentages or metrics.
     * Use the following syntax: `A/B`, where `A` and `B` are the names of the series. You can combine math aggregations and formulas.
     * When using a formula, you must:
     * - Identify and specify **all** events and actions needed to solve the formula.
     * - Carefully review the list of available events and actions to find appropriate entities for each part of the formula.
     * - Ensure that you find events and actions corresponding to both the numerator and denominator in ratio calculations.
     * Examples of using math formulas:
     * - If you want to calculate the percentage of users who have completed onboarding, you need to find and use events or actions similar to `$identify` and `onboarding complete`, so the formula will be `A / B`, where `A` is `onboarding complete` (unique users) and `B` is `$identify` (unique users).
     * For a ratio or percentage, keep the formula as the raw ratio (e.g. `A/B`, which is in the 0-1 range) and set `aggregationAxisFormat` to `percentage_scaled` so it renders as a percentage. Do NOT multiply the formula by 100 (e.g. `A/B*100`) when using `percentage_scaled`, or the value will be scaled twice.
     */
    formulaNodes?: TrendsFormulaNode[]

    /**
     * Smoothing intervals for the trend line.
     * @default 1
     */
    smoothingIntervals?: integer

    /**
     * Visualization type. Available values:
     * `ActionsLineGraph` - time-series line chart; most common option, as it shows change over time.
     * `ActionsBar` - time-series bar chart with one bar per interval and breakdown values stacked in each bar. Do not use it to compare breakdown values or series as totals. Use `ActionsBarValue` for that.
     * `ActionsUnstackedBar` - time-series bar chart with series side by side in each interval.
     * `ActionsAreaGraph` - time-series area chart.
     * `ActionsLineGraphCumulative` - cumulative time-series line chart; good for cumulative metrics.
     * `SlopeGraph` - net change from the first to the last interval, one line per series.
     * `BoxPlot` - quartiles of a numeric `math_property` for each interval.
     * `Metric` - single large number with a change pill and a sparkline. Use for a period summary or an explicit current-versus-previous-period comparison ("how many X in the last 30 days", "what's our conversion rate this month", "how does this month compare to last"). Do not use for a question about change over time, a cadence, or a pattern. Use `ActionsLineGraph` so the person can inspect each interval. Set `compareFilter.compare` to `true` to compare the current period with the previous period. Without it, the pill compares the first interval with the last interval. Configure the display with the `metric*` fields below. Single series, no breakdown.
     * `BoldNumber` - single large number with no change or sparkline. Use instead of `Metric` only when a trend is meaningless, such as an all-time total or a fixed ratio. You CANNOT use this with breakdown or if the insight has more than one series.
     * `ActionsBarValue` - total value (NOT time-series) bar chart with one bar per breakdown value or series; good for categorical data such as "top pages" or "failures by reason".
     * `ActionsPie` - total value pie chart; good for visualizing proportions.
     * `ActionsDonut` - total value donut chart; same use as `ActionsPie`.
     * `ActionsProportionBar` - total value chart that shows the parts of one whole as a single flat bar, with one segment per breakdown value or series. Use it to show the share of each part in a total. It cannot compare to a previous period, so do not set `compareFilter.compare` with it.
     * `ActionsTable` - total value table; good when using breakdown to list users or other entities.
     * `WorldMap` - total value world map; use when breaking down by country using property `$geoip_country_code`, and only then.
     * @default ActionsLineGraph
     */
    display?: AssistantTrendsDisplayType

    /**
     * Whether to show the legend describing series and breakdowns.
     * @default false
     */
    showLegend?: boolean

    /**
     * Formats the trends value axis. Do not use the formatting unless you are absolutely sure that formatting will match the data.
     * `numeric` - no formatting. Prefer this option by default.
     * `duration` - formats the value in seconds to a human-readable duration, e.g., `132` becomes `2 minutes 12 seconds`. Use this option only if you are sure that the values are in seconds.
     * `duration_ms` - formats the value in miliseconds to a human-readable duration, e.g., `1050` becomes `1 second 50 milliseconds`. Use this option only if you are sure that the values are in miliseconds.
     * `percentage` - appends a percentage sign to a value that is ALREADY on the 0-100 scale, e.g., `50` becomes `50%`. Only use this when the underlying value is already a percentage.
     * `percentage_scaled` - multiplies a 0-1 value by 100 and appends a percentage sign, e.g., `0.5` becomes `50%`. Use this for ratios in the 0-1 range, such as a bounce rate (`avg($is_bounce)`) or a formula like `A/B`. Because this format already multiplies by 100, do NOT also multiply by 100 in the formula (e.g. `A/B*100`), as that would double-scale the value and render, say, `0.5` as `5000%`.
     * `currency` - formats the value as a currency, e.g., `1000` becomes `$1,000`.
     * @default numeric
     */
    aggregationAxisFormat?: AggregationAxisFormat

    /**
     * Custom prefix to add to the aggregation axis, e.g., `$` for USD dollars. You may need to add a space after prefix.
     */
    aggregationAxisPrefix?: string

    /**
     * Custom postfix to add to the aggregation axis, e.g., ` clicks` to format 5 as `5 clicks`. You may need to add a space before postfix.
     * Never set a postfix that `aggregationAxisFormat` already renders: `percentage` and `percentage_scaled` already append the `%` sign, so a `%` postfix would render values as `50%%`.
     */
    aggregationAxisPostfix?: string

    /**
     * Number of decimal places to show. Do not add this unless you are sure that values will have a decimal point.
     */
    decimalPlaces?: number

    /**
     * Whether to show a value on each data point.
     * @default false
     */
    showValuesOnSeries?: boolean

    /**
     * Whether to show a percentage of each series. Use only with
     * @default false
     */
    showPercentStackView?: boolean

    /**
     * Whether to scale the y-axis.
     * @default linear
     */
    yAxisScaleType?: 'log10' | 'linear'

    /** Custom label rendered under the X axis. */
    xAxisLabel?: string

    /** Custom label rendered alongside the Y axis. */
    yAxisLabel?: string

    /**
     * Whether to show alert threshold lines on the chart.
     * @default false
     */
    showAlertThresholdLines?: boolean

    /**
     * Whether to show labels on each series.
     * @default false
     */
    showLabelsOnSeries?: boolean

    /**
     * Whether to show multiple y-axes for different series.
     * @default false
     */
    showMultipleYAxes?: boolean

    /**
     * Only applies when `display` is `Metric`. Show the change pill next to the big number. What it
     * compares follows `metricSummary`: `total`/`average` compare against the previous period when
     * "compare to previous" is on (otherwise first→last of the series), and `latest` is always
     * first→last of the series.
     * @default true
     */
    metricShowChange?: boolean

    /**
     * Only applies when `display` is `Metric`. Hex color (e.g. `#388600`) for the change pill when
     * the metric went UP. Defaults to green (`#388600`). For a "lower is better" metric (latency,
     * error rate, cost), set this to a red (e.g. `#db3707`) so an increase reads as bad.
     */
    metricChangeIncreaseColor?: string

    /**
     * Only applies when `display` is `Metric`. Hex color (e.g. `#db3707`) for the change pill when
     * the metric went DOWN. Defaults to red (`#db3707`). For a "lower is better" metric (latency,
     * error rate, cost), set this to a green (e.g. `#388600`) so a decrease reads as good.
     */
    metricChangeDecreaseColor?: string

    /**
     * Only applies when `display` is `Metric`. Color the sparkline under the big number by whether
     * the metric increased or decreased over the period (using the increase/decrease line colors).
     * @default false
     */
    metricColorByDirection?: boolean

    /**
     * Only applies when `display` is `Metric` and `metricColorByDirection` is `true`. Hex color for
     * the sparkline when the metric went UP. Defaults to green (`#388600`). Flip to a red for a
     * "lower is better" metric.
     */
    metricLineIncreaseColor?: string

    /**
     * Only applies when `display` is `Metric` and `metricColorByDirection` is `true`. Hex color for
     * the sparkline when the metric went DOWN. Defaults to red (`#db3707`). Flip to a green for a
     * "lower is better" metric.
     */
    metricLineDecreaseColor?: string

    /**
     * Only applies when `display` is `Metric`. Which summary the resting big number shows: `total`
     * (sum over the period), `average` (mean of the points), or `latest` (last point). Hovering the
     * sparkline always shows the hovered point's value regardless of this setting. Also drives the
     * change pill: `total`/`average` compare against the previous period when "compare to previous"
     * is on; `latest` compares first→last of the series.
     * @default total
     */
    metricSummary?: 'total' | 'average' | 'latest'
}

export interface AssistantTrendsQuery extends AssistantInsightsQueryBase {
    kind: NodeKind.TrendsQuery

    /**
     * Granularity of the response. Can be one of `hour`, `day`, `week` or `month`
     *
     * @default day
     */
    interval?: IntervalType

    /**
     * Events, actions, or groups of events/actions to include. Prioritize the more popular and
     * fresh events and actions.
     *
     * Use a top-level `EventsNode` or `ActionsNode` entry for each independent series (one line
     * per entry on the chart). Use an `AssistantTrendsGroupNode` to combine multiple events or
     * actions into a single series joined by `OR` — for example, treating
     * "Pageview OR Pageleave" as one line. Only `OR` grouping is supported; pick groups only
     * when the user wants the events counted together, otherwise prefer separate series.
     */
    series: (AssistantTrendsEventsNode | AssistantTrendsActionsNode | AssistantTrendsGroupNode)[]

    /**
     * Properties specific to the trends insight
     */
    trendsFilter?: AssistantTrendsFilter

    /**
     * Breakdowns are used to segment data by property values of maximum three properties. They divide all defined trends series to multiple subseries based on the values of the property. Include breakdowns **only when they are essential to directly answer the user’s question**. You must not add breakdowns if the question can be addressed without additional segmentation. Always use the minimum set of breakdowns needed to answer the question.
     * When using breakdowns, you must:
     * - **Identify the property group** and name for each breakdown.
     * - **Provide the property name** for each breakdown.
     * - **Validate that the property value accurately reflects the intended criteria**.
     * Examples of using breakdowns:
     * - page views trend by country: you need to find a property such as `$geoip_country_code` and set it as a breakdown.
     * - number of users who have completed onboarding by an organization: you need to find a property such as `organization name` and set it as a breakdown.
     */
    breakdownFilter?: AssistantTrendsBreakdownFilter

    /**
     * Compare to date range
     */
    compareFilter?: CompareFilter
}

export type AssistantFunnelsMath =
    | FunnelMathType.AnyMatch
    | FunnelMathType.FirstTimeForUser
    | FunnelMathType.FirstTimeForUserWithFilters

export interface AssistantFunnelNodeShared {
    /**
     * Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one.
     * `first_time_for_user` - counts the number of users who have completed the event for the first time ever.
     * `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.
     */
    math?: AssistantFunnelsMath
    properties?: AssistantPropertyFilter[]
    /**
     * If true, this step can be skipped without breaking the funnel — conversion between the surrounding required steps still counts even if this step didn't happen.
     * Set this when the user asks for a non-required, skippable, or optional step in the funnel. Do not set it on the first or last step (those must be required).
     * @default false
     */
    optionalInFunnel?: boolean
}

export interface AssistantFunnelsEventsNode extends Omit<Node, 'response'>, AssistantFunnelNodeShared {
    kind: NodeKind.EventsNode
    /**
     * Name of the event.
     */
    event: string
    /**
     * Optional custom name for the event if it is needed to be renamed.
     */
    custom_name?: string
}

export interface AssistantFunnelsActionsNode extends Omit<Node, 'response'>, AssistantFunnelNodeShared {
    kind: NodeKind.ActionsNode
    /**
     * Action ID from the plan.
     */
    id: number
    /**
     * Action name from the plan.
     */
    name: string
}

/**
 * Defines a funnel step that combines multiple events or actions with OR (e.g. "Pageview OR Pageleave"
 * counted as a single step). Filters live on the inner nodes — set per-node `properties` to give each
 * event its own filter. Step-wide group filters, funnel math, and `optionalInFunnel` are not supported
 * on grouped steps.
 */
export interface AssistantFunnelsGroupNode {
    kind: NodeKind.GroupNode
    /** Only `OR` is supported. */
    operator: FilterLogicalOperator.Or
    /**
     * Events and actions combined into the step. Use per-node `properties` to filter each event;
     * there is no step-wide filter on a grouped step.
     * @minItems 2
     */
    nodes: (AssistantFunnelsEventsNode | AssistantFunnelsActionsNode)[]
    /** Display name for the combined step. */
    name?: string
    custom_name?: string
}

export type AssistantFunnelsNode = AssistantFunnelsEventsNode | AssistantFunnelsActionsNode | AssistantFunnelsGroupNode

/**
 * Exclustion steps for funnels. The "from" and "to" steps must not exceed the funnel's series length.
 */
export interface AssistantFunnelsExclusionEventsNode extends FunnelExclusionSteps {
    kind: NodeKind.EventsNode
    event: string
}

export interface AssistantFunnelsFilter {
    /**
     * Defines the behavior of event matching between steps. Prefer the `strict` option unless explicitly told to use a different one.
     * `ordered` - defines a sequential funnel. Step B must happen after Step A, but any number of events can happen between A and B.
     * `strict` - defines a funnel where all events must happen in order. Step B must happen directly after Step A without any events in between.
     * `any` - order doesn't matter. Steps can be completed in any sequence.
     * @default ordered
     */
    funnelOrderType?: StepOrderValue
    /**
     * Defines the type of visualization to use.
     * `steps` - one bar per step with the conversion between them (default). Use for "what's the conversion rate" and "where do users drop off".
     * `trends` - the conversion rate of the whole sequence as a time series. Use whenever the question is about change over time ("is conversion improving", "conversion per week", "since we shipped X"); a `steps` chart cannot show that.
     * `time_to_convert` - a histogram of how long users took to complete the funnel.
     * @default steps
     */
    funnelVizType?: FunnelVizType
    /**
     * Users may want to use exclusion events to filter out conversions in which a particular event occurred between specific steps. These events must not be included in the main sequence.
     * This doesn't exclude users who have completed the event before or after the funnel sequence, but often this is what users want. (If not sure, worth clarifying.)
     * You must include start and end indexes for each exclusion where the minimum index is one and the maximum index is the number of steps in the funnel.
     * For example, there is a sequence with three steps: sign up, finish onboarding, purchase. If the user wants to exclude all conversions in which users left the page before finishing the onboarding, the exclusion step would be the event `$pageleave` with start index 2 and end index 3.
     * When exclusion steps appear needed when you're planning the query, make sure to explicitly state this in the plan.
     * @default []
     */
    exclusions?: AssistantFunnelsExclusionEventsNode[]
    /**
     * Controls how the funnel chart is displayed: vertically (preferred) or horizontally.
     * @default vertical
     */
    layout?: FunnelLayout
    /**
     * Use this setting only when `funnelVizType` is `time_to_convert`: number of bins to show in histogram.
     * @asType integer
     */
    binCount?: BinCountValue
    /**
     * Controls a time frame value for a conversion to be considered. Select a reasonable value based on the user's query.
     * If needed, this can be practically unlimited by setting a large value, though it's rare to need that.
     * Use in combination with `funnelWindowIntervalUnit`. The default value is 14 days.
     * @default 14
     */
    funnelWindowInterval?: integer
    /**
     * Controls a time frame interval for a conversion to be considered. Select a reasonable value based on the user's query.
     * Use in combination with `funnelWindowInterval`. The default value is 14 days.
     * @default day
     */
    funnelWindowIntervalUnit?: FunnelConversionWindowTimeUnit
    /**
     * Whether conversion shown in the graph should be across all steps or just relative to the previous step.
     * @default total
     */
    funnelStepReference?: FunnelStepReference
    /**
     * Use this field only if the user explicitly asks to aggregate the funnel by unique sessions.
     * @default null
     */
    funnelAggregateByHogQL?: 'properties.$session_id' | null
    /**
     * Controls how the breakdown value is attributed to a specific step.
     * `first_touch` - the breakdown value is the first property value found in the entire funnel.
     * `last_touch` - the breakdown value is the last property value found in the entire funnel.
     * `all_events` - the breakdown value must be present in all steps of the funnel.
     * `step` - the breakdown value is the property value found at a specific step defined by `breakdownAttributionValue`.
     * @default first_touch
     */
    breakdownAttributionType?: BreakdownAttributionType
    /**
     * When `breakdownAttributionType` is `step`, this is the step number (0-indexed) to attribute the breakdown value to.
     * @asType integer
     */
    breakdownAttributionValue?: integer
}

export type AssistantFunnelsBreakdownType = Extract<BreakdownType, 'person' | 'event' | 'group' | 'session'>

export interface AssistantFunnelsBreakdownFilter extends AssistantBreakdownFilter {
    /**
     * Type of the entity to break down by. If `group` is used, you must also provide `breakdown_group_type_index` from the group mapping.
     * @default event
     */
    breakdown_type: AssistantFunnelsBreakdownType
    /**
     * The entity property to break down by.
     */
    breakdown: string
    /**
     * If `breakdown_type` is `group`, this is the index of the group. Use the index from the group mapping.
     */
    breakdown_group_type_index?: integer | null
}

export interface AssistantFunnelsQuery extends AssistantInsightsQueryBase {
    kind: NodeKind.FunnelsQuery
    /**
     * Granularity of the response. Can be one of `hour`, `day`, `week` or `month`
     */
    interval?: IntervalType
    /**
     * Events or actions to include. Prioritize the more popular and fresh events and actions.
     */
    series: AssistantFunnelsNode[]
    /**
     * Properties specific to the funnels insight
     */
    funnelsFilter?: AssistantFunnelsFilter
    /**
     * A breakdown is used to segment data by a single property value. They divide all defined funnel series into multiple subseries based on the values of the property. Include a breakdown **only when it is essential to directly answer the user’s question**. You must not add a breakdown if the question can be addressed without additional segmentation.
     * When using breakdowns, you must:
     * - **Identify the property group** and name for a breakdown.
     * - **Provide the property name** for a breakdown.
     * - **Validate that the property value accurately reflects the intended criteria**.
     * Examples of using a breakdown:
     * - page views to sign up funnel by country: you need to find a property such as `$geoip_country_code` and set it as a breakdown.
     * - conversion rate of users who have completed onboarding after signing up by an organization: you need to find a property such as `organization name` and set it as a breakdown.
     */
    breakdownFilter?: AssistantFunnelsBreakdownFilter
    /**
     * Use this field to define the aggregation by a specific group from the provided group mapping, which is NOT users or sessions.
     */
    aggregation_group_type_index?: integer
}

export interface AssistantRetentionEventsNode {
    type: 'events'
    /**
     * The event name from the plan as a string. This is the field the retention query engine uses to match events, so it must be populated exactly as the event appears in the plan. For actions use `AssistantRetentionActionsNode` instead, where `id` is the numeric action ID.
     */
    id: string
    /**
     * Optional human-readable label for the event, used for display only. Defaults to `id` if omitted and is never used for event matching.
     */
    name?: string
    /**
     * Custom name for the event if it is needed to be renamed.
     */
    custom_name?: string
    /**
     * Property filters for the event.
     */
    properties?: AssistantPropertyFilter[]
}

export interface AssistantRetentionActionsNode {
    type: 'actions'
    /**
     * The numeric action ID from the plan. This is the field the retention query engine uses to look up the action definition. For events use `AssistantRetentionEventsNode` instead, where `id` is the event name string.
     */
    id: number
    /**
     * Optional human-readable label for the action, used for display only. Defaults to the action's stored name if omitted and is never used for action matching.
     */
    name?: string
    /**
     * Property filters for the action.
     */
    properties?: AssistantPropertyFilter[]
}

export type AssistantRetentionEntity = AssistantRetentionEventsNode | AssistantRetentionActionsNode

export interface AssistantRetentionFilter {
    /**
     * Retention type: recurring or first time.
     * Recurring retention counts a user as part of a cohort if they performed the cohort event during that time period, irrespective of it was their first time or not.
     * First time retention only counts a user as part of the cohort if it was their first time performing the cohort event.
     */
    retentionType?: RetentionType
    /** Whether retention is with regard to initial cohort size, or that of the previous period. */
    retentionReference?: 'total' | 'previous'
    /**
     * How many intervals to show in the chart. The default value is 8 (meaning 7 periods after initial cohort).
     * @default 8
     */
    totalIntervals?: integer
    /** Minimum number of times an event must occur to count towards retention. */
    minimumOccurrences?: integer
    /** Retention event (event marking the user coming back). */
    returningEntity: AssistantRetentionEntity
    /** Activation event (event putting the actor into the initial cohort). */
    targetEntity: AssistantRetentionEntity
    /**
     * Retention period, the interval to track cohorts by.
     * @default Day
     */
    period?: RetentionPeriod
    /** Whether an additional series should be shown, showing the mean conversion for each period across cohorts. */
    meanRetentionCalculation?: 'simple' | 'weighted' | 'none'
    /**
     * Whether retention should be rolling (aka unbounded, cumulative).
     * Rolling retention means that a user coming back in period 5 makes them count towards all the previous periods.
     */
    cumulative?: boolean
    /**
     * The time window mode to use for retention calculations.
     */
    timeWindowMode?: 'strict_calendar_dates' | '24_hour_windows'
    /**
     * Custom brackets for retention calculations.
     * @maxItems 31
     */
    retentionCustomBrackets?: number[]
    /**
     * The aggregation type to use for retention.
     * @default count
     */
    aggregationType?: 'count' | 'sum' | 'avg'
    /** The event or person property to aggregate when aggregationType is sum or avg. */
    aggregationProperty?: string
    /**
     * The type of property to aggregate on (event or person). Defaults to event.
     * @default event
     */
    aggregationPropertyType?: 'event' | 'person' | 'data_warehouse'
    /** `ActionsLineGraph` (default) draws lines. `ActionsBar` draws bars. */
    display?: AssistantRetentionDisplayType
}

export type AssistantRetentionDisplayType = ChartDisplayType.ActionsLineGraph | ChartDisplayType.ActionsBar

export interface AssistantRetentionQuery extends AssistantInsightsQueryBase {
    kind: NodeKind.RetentionQuery
    /** Properties specific to the retention insight */
    retentionFilter: AssistantRetentionFilter
}

/**
 * Stickiness display types. Only time-series visualizations are supported:
 * - `ActionsLineGraph` - line chart (default)
 * - `ActionsBar` - bar chart
 * - `ActionsAreaGraph` - area chart
 */
export type AssistantStickinessDisplayType =
    | ChartDisplayType.ActionsLineGraph
    | ChartDisplayType.ActionsBar
    | ChartDisplayType.ActionsAreaGraph

/**
 * Defines the event series for the stickiness insight. Each series measures how many intervals
 * (e.g. days) within the date range a user performed the event. The X-axis shows the number of
 * intervals (1, 2, 3, ...) and the Y-axis shows the count of users.
 * When math is omitted, the default aggregation is by unique persons (person_id).
 */
export interface AssistantStickinessEventsNode extends Pick<
    EventsNode,
    | 'kind'
    | 'event'
    | 'name'
    | 'custom_name'
    | 'math'
    | 'math_multiplier'
    | 'math_property'
    | 'math_property_type'
    | 'math_group_type_index'
> {
    properties?: AssistantPropertyFilter[]

    /**
     * Custom HogQL expression for aggregation. Use when the predefined `math` types are not sufficient.
     * When set, `math` must be set to `hogql`.
     *
     * Examples:
     * - Sum a numeric property: `sum(toFloat(properties.$revenue))`
     * - Average of a property: `avg(toFloat(properties.load_time))`
     * - Count distinct values: `count(distinct properties.$session_id)`
     * - Conditional count: `countIf(toFloat(properties.duration) > 30)`
     * - Percentile: `quantile(0.95)(toFloat(properties.response_time))`
     */
    math_hogql?: string
}

/**
 * Defines the action series for the stickiness insight. You must provide the action ID in the `id` field and the name in the `name` field.
 * When math is omitted, the default aggregation is by unique persons (person_id).
 */
export interface AssistantStickinessActionsNode extends Pick<
    ActionsNode,
    | 'kind'
    | 'id'
    | 'custom_name'
    | 'math'
    | 'math_multiplier'
    | 'math_property'
    | 'math_property_type'
    | 'math_group_type_index'
> {
    properties?: AssistantPropertyFilter[]
    /**
     * Action name from the plan.
     */
    name: string

    /**
     * Custom HogQL expression for aggregation. Use when the predefined `math` types are not sufficient.
     * When set, `math` must be set to `hogql`.
     *
     * Examples:
     * - Sum a numeric property: `sum(toFloat(properties.$revenue))`
     * - Average of a property: `avg(toFloat(properties.load_time))`
     * - Count distinct values: `count(distinct properties.$session_id)`
     * - Conditional count: `countIf(toFloat(properties.duration) > 30)`
     * - Percentile: `quantile(0.95)(toFloat(properties.response_time))`
     */
    math_hogql?: string
}

export type AssistantStickinessNode = AssistantStickinessEventsNode | AssistantStickinessActionsNode

export interface AssistantStickinessFilter {
    /**
     * Visualization type for the stickiness chart.
     * `ActionsLineGraph` - line chart (default).
     * `ActionsBar` - bar chart.
     * `ActionsAreaGraph` - area chart.
     * @default ActionsLineGraph
     */
    display?: AssistantStickinessDisplayType

    /**
     * Whether to show the legend describing series.
     * @default false
     */
    showLegend?: boolean

    /**
     * Whether to show a value on each data point.
     * @default false
     */
    showValuesOnSeries?: boolean

    /**
     * Filter which intervals count based on event frequency within each interval.
     * For example, only count intervals where the user performed the event >= 3 times.
     */
    stickinessCriteria?: StickinessCriteria

    /**
     * Computation mode. `non_cumulative` (default) shows users active on exactly N intervals.
     * `cumulative` shows users active on N or more intervals.
     * @default non_cumulative
     */
    computedAs?: StickinessComputationMode
}

export interface AssistantStickinessQuery extends Omit<AssistantInsightsQueryBase, 'aggregation_group_type_index'> {
    kind: NodeKind.StickinessQuery

    /**
     * Granularity of the response. Can be one of `hour`, `day`, `week` or `month`.
     * This determines what counts as one "interval" for stickiness measurement.
     * For example, with `day` interval over a 30-day range, the X-axis shows 1 through 30 days,
     * and each bar/point shows how many users performed the event on exactly that many days.
     *
     * @default day
     */
    interval?: IntervalType

    /**
     * How many base intervals comprise one stickiness period. Defaults to 1.
     * For example, `interval: "day"` with `intervalCount: 7` groups by 7-day periods.
     */
    intervalCount?: positive_integer

    /**
     * Events or actions to include. Each series measures how many intervals (e.g. days) within
     * the date range a user performed the event. Prioritize the more popular and fresh events
     * and actions. When the `math` field is omitted on a series, it defaults to counting
     * unique persons.
     */
    series: AssistantStickinessNode[]

    /**
     * Properties specific to the stickiness insight
     */
    stickinessFilter?: AssistantStickinessFilter

    /**
     * Compare to date range. When enabled, shows the current and previous period side by side.
     */
    compareFilter?: CompareFilter
}

/**
 * Defines a regex-based path cleaning rule to normalize dynamic path components.
 * Path cleaning rules replace matching URL patterns with a readable alias,
 * which helps group similar paths together (e.g., `/user/123/profile` and `/user/456/profile` become `/user/:id/profile`).
 */
export interface AssistantPathCleaningFilter {
    /**
     * A human-readable alias that replaces matched path patterns in the visualization.
     * For example, `/user/:id/profile` to replace `/user/123/profile`.
     * Uses ClickHouse `replaceRegexpAll` replacement syntax — use `\\1` for capture group back-references.
     */
    alias: string
    /**
     * A ClickHouse regex pattern to match against path values. Matched paths will be replaced with the alias.
     * For example, `\/user\/\d+\/profile` to match any user profile URL.
     */
    regex: string
}

export interface AssistantPathsFilter {
    /**
     * Which event types to include in the path analysis. Available values:
     * `$pageview` - web page views. Path values are page URLs (from `$current_url`), with trailing slashes stripped.
     * `$screen` - mobile screen views. Path values are screen names (from `$screen_name`).
     * `custom_event` - custom events (any event not starting with `$`). Path values are event names.
     * `hogql` - custom HogQL expression defined in `pathsHogQLExpression`. Path values come from evaluating the expression.
     * You can combine multiple types. If not specified, all events are included without type filtering.
     * Paths never include `$feature_flag_called` events, whichever types are set.
     */
    includeEventTypes?: PathType[]
    /**
     * A HogQL expression to use as the path item. Required when `hogql` is included in `includeEventTypes`.
     * For example, `properties.$current_url` to use the current URL as the path item.
     */
    pathsHogQLExpression?: string
    /**
     * Filter to only show paths that start from this specific step.
     * The value format depends on the included event types:
     * For `$pageview` paths, use page URLs like `/login` or `/dashboard`.
     * For `$screen` paths, use screen names.
     * For `custom_event` paths, use event names.
     */
    startPoint?: string
    /**
     * Filter to only show paths that end at this specific step.
     * Same format as `startPoint`.
     */
    endPoint?: string
    /**
     * Event names or URLs to exclude from the path analysis entirely.
     * Excluded events are filtered out before building the path visualization.
     * Useful for removing noise from common but uninteresting events.
     * @default []
     */
    excludeEvents?: string[]
    /**
     * Glob-like patterns to group multiple path items into a single step.
     * Use `*` as a wildcard. The patterns are auto-escaped, so only `*` has special meaning.
     * For example, `/product/*` to group all product pages into one node.
     * @default []
     */
    pathGroupings?: string[]
    /**
     * Maximum number of steps (path depth) to show in the visualization.
     * Controls how deep the path analysis goes from the start.
     * @default 5
     */
    stepLimit?: integer
    /**
     * Maximum number of path edges (connections between steps) to return.
     * Higher values show more detail but can make the visualization harder to read.
     * @default 50
     */
    edgeLimit?: integer
    /**
     * ClickHouse regex-based rules to clean and normalize path values at the query level.
     * Each rule applies `replaceRegexpAll(path, regex, alias)` in sequence.
     * Useful for removing dynamic IDs or parameters from URLs.
     * @default []
     */
    localPathCleaningFilters?: AssistantPathCleaningFilter[]
    /**
     * Minimum number of users who traversed an edge for it to be displayed.
     * Filters out low-traffic paths to reduce visual noise.
     */
    minEdgeWeight?: integer
    /**
     * Maximum number of users who traversed an edge for it to be displayed.
     * Filters out high-traffic paths to focus on less common journeys.
     */
    maxEdgeWeight?: integer
    /**
     * Actors drilldown only. Restrict the returned persons to those who **departed from** a specific
     * node in the path graph. Format is `<stepIndex>_<value>`, e.g. `"2_https://example.com/pricing"`.
     * Take the value verbatim from a `source` field of a `query-paths` result row. Combine with
     * `pathEndKey` to pin a single edge (source → target). Leave unset to return every actor on the
     * path (constrained only by `startPoint` / `endPoint`). Ignored by non-actors paths queries.
     */
    pathStartKey?: string
    /**
     * Actors drilldown only. Restrict the returned persons to those who **arrived at** a specific
     * node in the path graph. Format is `<stepIndex>_<value>`, e.g. `"3_https://example.com/checkout"`.
     * Take the value verbatim from a `target` field of a `query-paths` result row. Combine with
     * `pathStartKey` to pin a single edge. Leave unset to return every actor on the path. Ignored by
     * non-actors paths queries.
     */
    pathEndKey?: string
    /**
     * Actors drilldown only. Restrict the returned persons to those who **dropped off** at a specific
     * node (reached it but did not continue). Format is `<stepIndex>_<value>`. Mutually exclusive with
     * `pathStartKey` / `pathEndKey`. Ignored by non-actors paths queries.
     */
    pathDropoffKey?: string
}

export interface AssistantPathsQuery extends AssistantInsightsQueryBase {
    kind: NodeKind.PathsQuery
    /**
     * Properties specific to the paths insight.
     * Paths show the most common sequences of events or pages that users navigate through,
     * helping identify popular user flows and drop-off points.
     */
    pathsFilter: AssistantPathsFilter
}

export interface AssistantLifecycleEventsNode extends Pick<EventsNode, 'kind' | 'event' | 'name' | 'custom_name'> {
    /**
     * Defines the event series for the lifecycle insight. Lifecycle does not support math aggregations.
     */
    kind: NodeKind.EventsNode
    properties?: AssistantPropertyFilter[]
}

export type AssistantLifecycleSeriesNode = AssistantLifecycleEventsNode | AssistantLifecycleActionsNode

export interface AssistantLifecycleActionsNode extends Pick<ActionsNode, 'kind' | 'id' | 'custom_name'> {
    /**
     * Defines the action series for the lifecycle insight. Lifecycle does not support math aggregations.
     * You must provide the action ID in the `id` field and the name in the `name` field.
     */
    kind: NodeKind.ActionsNode
    properties?: AssistantPropertyFilter[]
    /**
     * Action name from the plan.
     */
    name: string
}

export interface AssistantLifecycleFilter {
    /**
     * Whether to show a value on each data point.
     * @default false
     */
    showValuesOnSeries?: boolean
    /**
     * Lifecycles that have been removed from display are not included in this array.
     * Available values: `new`, `returning`, `resurrecting`, `dormant`.
     * - `new` - users who performed the event for the first time during the period.
     * - `returning` - users who were active in the previous period and are active in the current period.
     * - `resurrecting` - users who were inactive for one or more periods and became active again.
     * - `dormant` - users who were active in the previous period but are inactive in the current period.
     */
    toggledLifecycles?: LifecycleToggle[]
    /**
     * Whether to show the legend describing series.
     * @default false
     */
    showLegend?: boolean
    /**
     * Whether the lifecycle bars should be stacked.
     * @default true
     */
    stacked?: boolean
}

export interface AssistantLifecycleQuery extends AssistantInsightsQueryBase {
    kind: NodeKind.LifecycleQuery

    /**
     * Granularity of the response. Can be one of `hour`, `day`, `week` or `month`
     *
     * @default day
     */
    interval?: IntervalType

    /**
     * Event or action to analyze. Lifecycle insights only support a single series.
     * @maxItems 1
     */
    series: AssistantLifecycleSeriesNode[]

    /**
     * Properties specific to the lifecycle insight
     */
    lifecycleFilter?: AssistantLifecycleFilter
}

/**
 * Drills into a trends insight to list the persons behind a specific data point. Returned rows
 * are `distinct_id`, `name`, `email`, `event_count`, and optionally matched session recordings.
 *
 * Use the selector fields (`day`, `series`, `breakdown`, `compare`) to identify the specific
 * cell in the source insight.
 */
export interface AssistantTrendsActorsQuery {
    kind: NodeKind.InsightActorsQuery

    /** The source insight query whose data point we are drilling into. */
    source: AssistantTrendsQuery

    /** Bucket date for the data point. Must be an ISO date string (YYYY-MM-DD), e.g. '2024-01-15'. */
    day: string

    /** Series index (0-based) when the source has multiple series. */
    series?: integer

    /**
     * Breakdown values, one per dimension in the source's `breakdownFilter.breakdowns`, in the same order.
     * Array length must equal the number of breakdown dimensions.
     */
    breakdown?: string[]

    /** Whether to pull from the previous period when `compare` is enabled in the source. */
    compare?: 'current' | 'previous'

    /**
     * Whether to include matched session recordings for each actor.
     * @default true
     */
    includeRecordings?: boolean

    /**
     * Maximum number of persons to return in one page, from 1 to 1000. Higher values are clamped.
     * @default 100
     */
    limit?: integer

    /**
     * Number of persons to skip before the returned page. Use it with `limit` to walk the whole
     * result set: the response reports `limit`, `offset`, and `hasMore`, so when `hasMore` is true,
     * call again with `offset` raised by `limit`.
     * @default 0
     */
    offset?: integer
}

/** A single lifecycle bucket — see `AssistantLifecycleActorsQuery.status`. */
export type AssistantLifecycleStatus = 'new' | 'returning' | 'resurrecting' | 'dormant'

/**
 * Drills into a lifecycle insight to list the persons behind a specific bucket. Returned rows
 * are `distinct_id`, `email`, and `name`. Lifecycle is a bucket-membership query, so no
 * per-actor `event_count` or matched recordings are projected — the underlying lifecycle
 * runner does not surface a `matching_events` column.
 *
 * Use the selector fields (`day`, `status`) to identify the specific bucket — a lifecycle insight
 * is a 4-row stack (new / returning / resurrecting / dormant) per day.
 *
 * Note: lifecycle insights only support a single series and do not expose `compareFilter`, so
 * `series` and `compare` selectors are intentionally omitted.
 */
export interface AssistantLifecycleActorsQuery {
    kind: NodeKind.InsightActorsQuery

    /** The source lifecycle insight query whose bucket we are drilling into. */
    source: AssistantLifecycleQuery

    /** Bucket date for the data point. Must be an ISO date string (YYYY-MM-DD), e.g. '2024-01-15'. */
    day: string

    /**
     * Lifecycle status to drill into for the given day. Must be one of the bucket names visible
     * in the source's `lifecycleFilter.toggledLifecycles` (defaults to all four when omitted).
     */
    status: AssistantLifecycleStatus

    /**
     * Maximum number of persons to return in one page, from 1 to 1000. Higher values are clamped.
     * @default 100
     */
    limit?: integer

    /**
     * Number of persons to skip before the returned page. Use it with `limit` to walk the whole
     * result set: the response reports `limit`, `offset`, and `hasMore`, so when `hasMore` is true,
     * call again with `offset` raised by `limit`.
     * @default 0
     */
    offset?: integer
}

/**
 * Drills into a paths insight to list the persons behind it. Returned rows are `distinct_id`,
 * `name`, `email`, `event_count`, and optionally matched session recordings.
 *
 * There are no per-cell selectors like `day` or `series` — everything is configured on the `source`
 * paths query. Two modes:
 * - Whole path: set `pathsFilter.startPoint` / `endPoint` (plus `includeEventTypes`, date range,
 *   property filters) to return every actor on that path.
 * - Specific node/edge: set `pathsFilter.pathEndKey` (arrived at a node), `pathStartKey` (departed
 *   from a node), both together (a single `source → target` edge), or `pathDropoffKey` (dropped off).
 *   The key value is `<stepIndex>_<value>`, taken verbatim from a `query-paths` result row's
 *   `target` / `source`.
 */
export interface AssistantPathsActorsQuery {
    kind: NodeKind.InsightActorsQuery

    /** The source paths insight query whose actors we are listing. */
    source: AssistantPathsQuery

    /**
     * Whether to include matched session recordings for each actor.
     * @default true
     */
    includeRecordings?: boolean

    /**
     * Maximum number of persons to return in one page, from 1 to 1000. Higher values are clamped.
     * @default 100
     */
    limit?: integer

    /**
     * Number of persons to skip before the returned page. Use it with `limit` to walk the whole
     * result set: the response reports `limit`, `offset`, and `hasMore`, so when `hasMore` is true,
     * call again with `offset` raised by `limit`.
     * @default 0
     */
    offset?: integer
}

/**
 * Drills into a retention insight to list the persons in one acquisition cohort and show, for each,
 * which subsequent intervals they came back in. Returned rows are `distinct_id`, `email`, `name`,
 * followed by one column per retention interval (`<period>_0` … `<period>_N`, e.g. `day_0`, `day_1`,
 * … for a daily insight). Each interval column is `1` when the actor was active in that interval and
 * `0` otherwise; `<period>_0` is the acquisition interval and is always `1`. Rows are ordered by how
 * many intervals each actor returned in (most-retained first).
 *
 * The number and name of the interval columns are derived from the source — `retentionFilter.period`
 * sets the prefix and `retentionFilter.totalIntervals` (or `retentionCustomBrackets.length + 1` when
 * custom brackets are set) sets the count.
 *
 * Retention drilldown has no per-cell `day` / `series` / `compare` selectors and no matched-recordings
 * column — its persons output is appearance-based.
 */
export interface AssistantRetentionActorsQuery {
    kind: NodeKind.InsightActorsQuery

    /** The source retention insight query whose cohort we are drilling into. */
    source: AssistantRetentionQuery

    /**
     * Which acquisition cohort to drill into, 0-based. `0` is the acquisition interval itself (every
     * actor who entered the cohort); `1` is the cohort that entered one interval later, and so on.
     * Defaults to `0` when omitted.
     */
    interval?: integer

    /**
     * Maximum number of persons to return in one page, from 1 to 1000. Higher values are clamped.
     * @default 100
     */
    limit?: integer

    /**
     * Number of persons to skip before the returned page. Use it with `limit` to walk the whole
     * cohort: the response reports `limit`, `offset`, and `hasMore`, so when `hasMore` is true, call
     * again with `offset` raised by `limit`.
     * @default 0
     */
    offset?: integer
}

/**
 * Drills into a stickiness insight to list the persons behind one bar — the users who were active
 * in exactly `day` intervals within the source's date range (e.g. active on exactly 13 days).
 * Returned rows are `distinct_id`, `email`, and `name`.
 *
 * Pair this with `query-stickiness`: run the stickiness query first to read the distribution
 * (the X-axis is the number of active intervals, the Y-axis is the number of users), then call this
 * tool with the **same** stickiness query as `source` and `day` set to the bar you want to drill into.
 *
 * Stickiness drilldown is membership-based and does not surface a matched-recordings column, so
 * `includeRecordings` is intentionally omitted (as with lifecycle and retention).
 */
export interface AssistantStickinessActorsQuery {
    kind: NodeKind.InsightActorsQuery

    /** The source stickiness insight query whose bar we are drilling into. */
    source: AssistantStickinessQuery

    /**
     * The number of active intervals to drill into — the X-axis value of the stickiness bar.
     * Despite the name, this is an interval **count**, not a date: for a daily insight, `day: 13`
     * lists the users who were active on exactly 13 days within the source's date range.
     */
    day: integer

    /** 0-based index of the series to drill into when the source has multiple series. Defaults to 0. */
    series?: integer

    /** Whether to pull from the previous period when `compareFilter` is enabled in the source. */
    compare?: 'current' | 'previous'

    /**
     * Maximum number of persons to return in one page, from 1 to 1000. Higher values are clamped.
     * @default 100
     */
    limit?: integer

    /**
     * Number of persons to skip before the returned page. Use it with `limit` to walk the whole
     * result set: the response reports `limit`, `offset`, and `hasMore`, so when `hasMore` is true,
     * call again with `offset` raised by `limit`.
     * @default 0
     */
    offset?: integer
}

/**
 * Drills into a funnel insight to list the persons behind one step — either those who converted
 * through it or those who dropped off at it. Returned rows are `distinct_id`, `email`, `name`, and
 * optionally matched session recordings.
 *
 * Pair this with `query-funnel`: run the funnel query first to read the per-step counts, then call
 * this tool with the **same** funnel query as `source`. There are two mutually exclusive modes, and
 * the mode must match the source funnel's `funnelsFilter.funnelVizType`:
 *
 * 1. **Step mode** (source `funnelVizType: "steps"`, the default): use `funnelStep` to pick a step.
 *    A **positive** value lists actors who converted **through** that step; a **negative** value lists
 *    actors who **dropped off** at it. Steps are 1-based, so `funnelStep: 2` = converted through step 2,
 *    `funnelStep: -2` = dropped off at step 2. (You cannot drop off at step 1, so the smallest negative
 *    value is `-2`.) Add `funnelStepBreakdown` to scope to one breakdown series.
 *
 * 2. **Trends-dropoff mode** (source `funnelVizType: "trends"`): use `funnelTrendsDropOff` together with
 *    `funnelTrendsEntrancePeriodStart` to list the persons behind one point of a funnel-trends
 *    (conversion-over-time) chart.
 *
 * The funnel's `time_to_convert` viz type has no persons drilldown — do not use this tool with it.
 */
export interface AssistantFunnelsActorsQuery {
    kind: NodeKind.FunnelsActorsQuery

    /** The source funnel insight query whose step (or trends point) we are drilling into. */
    source: AssistantFunnelsQuery

    /**
     * Step mode only (source `funnelVizType: "steps"`). The 1-based index of the step to drill into.
     * **Positive** lists actors who converted through that step; **negative** lists actors who dropped
     * off at it. E.g. `2` = converted through step 2, `-2` = dropped off at step 2. The smallest
     * negative value is `-2` (no one can drop off at the entry step).
     */
    funnelStep?: integer

    /**
     * Step mode only. Scope the actors to a single breakdown series. Pass the breakdown value(s) from
     * the matching `query-funnel` result row verbatim (an array, e.g. `["Chrome"]`). Omit for the
     * baseline (non-breakdown) series.
     */
    funnelStepBreakdown?: string[]

    /**
     * Trends-dropoff mode only (source `funnelVizType: "trends"`). When `true`, list the actors who
     * dropped off; when `false`, list those who converted. Use together with
     * `funnelTrendsEntrancePeriodStart`.
     */
    funnelTrendsDropOff?: boolean

    /**
     * Trends-dropoff mode only. The entrance period to drill into, as a `YYYY-MM-DD HH:mm:ss` string
     * (e.g. `'2024-01-15 00:00:00'`), taken from the funnel-trends point the user is asking about.
     * Use together with `funnelTrendsDropOff`.
     */
    funnelTrendsEntrancePeriodStart?: string

    /**
     * Whether to include matched session recordings for each actor.
     * @default true
     */
    includeRecordings?: boolean

    /**
     * Maximum number of persons to return in one page, from 1 to 1000. Higher values are clamped.
     * @default 100
     */
    limit?: integer

    /**
     * Number of persons to skip before the returned page. Use it with `limit` to walk the whole
     * result set: the response reports `limit`, `offset`, and `hasMore`, so when `hasMore` is true,
     * call again with `offset` raised by `limit`.
     * @default 0
     */
    offset?: integer
}

/**
 * Query LLM traces to inspect AI/LLM usage. Returns a list of traces with latency,
 * token usage, costs, errors, and other metadata. Use for AI observability — debugging
 * slow generations, investigating errors, analyzing token spend, and auditing LLM behavior.
 *
 * This is a listing tool, not a visualization/insight tool. It does not support series,
 * breakdowns, or math aggregations. Use property filters and dateRange to narrow results.
 */
export interface AssistantTracesQuery {
    kind: NodeKind.TracesQuery

    /**
     * Date range for the query.
     */
    dateRange?: AssistantDateRangeFilter

    /**
     * Maximum number of traces to return.
     * @default 100
     */
    limit?: integer

    /**
     * Number of traces to skip for pagination.
     * @default 0
     */
    offset?: integer

    /**
     * Exclude internal and test users by applying the respective filters.
     * @default true
     */
    filterTestAccounts?: boolean

    /**
     * Exclude support impersonation traces.
     * @default false
     */
    filterSupportTraces?: boolean

    /**
     * Property filters to narrow results. Use event properties like `$ai_model`,
     * `$ai_provider`, `$ai_trace_id`, etc. to filter traces.
     * @default []
     */
    properties?: AssistantPropertyFilter[]

    /**
     * Filter traces by a specific person UUID.
     */
    personId?: string

    /**
     * Filter traces by group key. Requires `groupTypeIndex` to be set.
     */
    groupKey?: string

    /**
     * Group type index when filtering by group.
     */
    groupTypeIndex?: integer

    /**
     * Use random ordering instead of timestamp DESC.
     * Useful for representative sampling to avoid recency bias.
     * @default false
     */
    randomOrder?: boolean
}

/**
 * Fetch a single LLM trace by ID. Returns the full trace with all child events
 * and their complete properties — use for deep inspection of a specific trace
 * found via `query-llm-traces-list`.
 */
export interface AssistantTraceQuery {
    kind: NodeKind.TraceQuery

    /**
     * The trace ID to fetch (the `id` field from a trace in `query-llm-traces-list` results).
     */
    traceId: string

    /**
     * Date range for the query.
     */
    dateRange?: AssistantDateRangeFilter

    /**
     * Property filters to narrow events within the trace.
     * @default []
     */
    properties?: AssistantPropertyFilter[]
}

export interface AssistantHogQLQuery {
    kind: NodeKind.HogQLQuery
    /** SQL SELECT statement to execute. Mostly standard ClickHouse SQL with PostHog-specific additions. */
    query: string
}

export interface AssistantErrorTrackingQuery {
    kind: NodeKind.ErrorTrackingQuery
    /** Filter to a specific error tracking issue by ID. */
    issueId?: string
    /** Field to sort results by. */
    orderBy?: ErrorTrackingOrderBy
    /** Sort direction. */
    orderDirection?: 'ASC' | 'DESC'
    /** Date range to filter results. */
    dateRange?: DateRange
    /** Filter by issue status. */
    status?: ErrorTrackingQueryStatus
    /** Filter by assignee. */
    assignee?: ErrorTrackingIssueAssignee | null
    /** Whether to filter out test accounts. */
    filterTestAccounts?: boolean
    /** Free-text search across exception type, message, and stack frames. */
    searchQuery?: string
    /**
     * Property filters for the query
     *
     * @default []
     */
    filterGroup?: AssistantPropertyFilter[]
    /** Controls volume chart granularity. Use 1 for sparklines, 0 for counts only. */
    volumeResolution?: integer
    limit?: integer
    offset?: integer
}

/**
 * Simplified RecordingsQuery for MCP tool usage. Exposes the most useful
 * filtering and pagination fields with LLM-friendly descriptions while
 * hiding internal complexity (having_predicates, operand, actions, etc.).
 */
export interface AssistantRecordingsQuery {
    kind: NodeKind.RecordingsQuery
    /** Start of the date range. Supports relative dates like "-7d", "-24h" or ISO 8601 format. Default: "-3d". */
    date_from?: string | null
    /** End of the date range. Supports relative dates or ISO 8601 format. Default: now. */
    date_to?: string | null
    /**
     * Property filters to narrow results. Each filter has a `key`, `value`, `operator`, and `type`.
     *
     * Supported types:
     * - `person`: Filter by person properties (e.g. email, country).
     * - `session`: Filter by session properties (e.g. $session_duration, $channel_type, $entry_current_url).
     * - `event`: Filter by properties of events in the session (e.g. $current_url, $browser).
     * - `recording`: Filter by recording metrics (e.g. console_error_count, click_count, activity_score).
     * - `cohort`: Filter recordings to persons belonging to a cohort. Example: `{ type: "cohort", key: "id", value: 42, operator: "in" }`.
     */
    properties?: AssistantRecordingsQueryPropertyFilter[]
    /** Exclude internal and test users. Default: false. */
    filter_test_accounts?: boolean
    /** Sort field. Options: "start_time", "duration", "activity_score", "console_error_count", "click_count". Default: "start_time". */
    order?: RecordingOrder
    /** Sort direction: "ASC" or "DESC". Default: "DESC". */
    order_direction?: RecordingOrderDirection
    /** Maximum number of recordings to return. */
    limit?: integer
    /** Cursor for pagination from a previous response's next_cursor field. */
    after?: string
    /** Filter recordings to a specific person by their UUID. */
    person_uuid?: string
    /** Filter to specific session recording IDs. Use this when you have known session IDs (e.g., from $session_id on events) to fetch multiple recordings in a single call. */
    session_ids?: string[]
}

export interface AssistantInsightVizNode {
    kind: NodeKind.InsightVizNode
    /** Product analtycs query objects like TrendsQuery, FunnelsQuery, RetentionQuery, PathsQuery, StickinessQuery, LifecycleQuery */
    source: Record<string, any>
    /** Chart rendering options. */
    vizSpecificOptions?: AssistantVizSpecificOptions
}

export interface AssistantPieChartOptions {
    /** Hide the total on a pie chart. */
    hideAggregation?: boolean
}

export interface AssistantVizSpecificOptions {
    ActionsPie?: AssistantPieChartOptions
}

/**
 * Subset of `ChartDisplayType` values supported by `AssistantDataVisualizationNode`.
 *
 * - `ActionsTable` — render rows as a data table. This is the default when `display` is omitted.
 * - `BoldNumber` — big-number display for single-value results (first numeric column of the first row).
 * - `Metric` — big number with a change pill and a sparkline (a KPI or scorecard). Uses the first numeric Y column, one value per row.
 * - `ActionsLineGraph` — line chart. Requires at least two columns, including one numeric column.
 * - `ActionsBar` — bar chart with one bar per X-axis value.
 * - `ActionsBarValue` — horizontal bar chart (bar ranking) with one bar per category. Requires a category column and a numeric column.
 * - `ActionsPie` — pie chart for categorical proportions. Requires one label column and one numeric column.
 * - `ActionsDonut` — donut (ring) chart with the total in the center. Same columns as `ActionsPie`.
 * - `ActionsProportionBar` — one flat bar that shows the parts of one whole, one segment per label. Same columns as `ActionsPie`.
 * - `ActionsStackedBar` — bar chart stacked by a series breakdown column.
 * - `ActionsAreaGraph` — area chart. Requires at least two columns, including one numeric column.
 * - `TwoDimensionalHeatmap` — 2D heatmap. Requires an X column, a Y column, and a numeric value column.
 * - `ScatterPlot` — scatter plot of one measure against another. Requires two numeric columns, one per axis.
 * - `BoxPlot` — box plot from pre-aggregated SQL rows. Requires six numeric summary columns.
 */
export type AssistantDataVisualizationDisplayType =
    | ChartDisplayType.ActionsTable
    | ChartDisplayType.BoldNumber
    | ChartDisplayType.Metric
    | ChartDisplayType.ActionsLineGraph
    | ChartDisplayType.ActionsBar
    | ChartDisplayType.ActionsBarValue
    | ChartDisplayType.ActionsPie
    | ChartDisplayType.ActionsDonut
    | ChartDisplayType.ActionsProportionBar
    | ChartDisplayType.ActionsStackedBar
    | ChartDisplayType.ActionsAreaGraph
    | ChartDisplayType.TwoDimensionalHeatmap
    | ChartDisplayType.ScatterPlot
    | ChartDisplayType.BoxPlot

export interface AssistantDataVisualizationAxisDisplaySettings {
    /** Which Y axis this numeric series should use. Use `right` for a secondary Y axis. */
    yAxisPosition?: 'left' | 'right'
    /**
     * Chart type. `auto` uses `display`.
     */
    displayType?: 'auto' | 'line' | 'bar' | 'area'
    /** Draw a linear trend line for this series. Only meaningful for line, bar, and area charts. */
    trendLine?: boolean
    /** Series label in legends and tooltips; replaces the column name. */
    label?: string
    /** Custom color for this series as a hex string (e.g. `#1d4aff`). */
    color?: string
    /**
     * Keep this series out of the tooltip's total row, e.g. a target line over stacked bars.
     * A bar series still stacks, so set `displayType` to `line` for a series drawn over the stack.
     */
    excludeFromTotal?: boolean
    /**
     * Per-series override of chart-level `showValuesOnSeries`. `show` labels this series even when the
     * chart setting is off, `hide` leaves it unlabeled when the setting is on, `auto` follows the chart.
     */
    valueLabels?: 'auto' | 'show' | 'hide'
}

export interface AssistantDataVisualizationAxisFormatting {
    /** Text prepended to each value (e.g. `$`). */
    prefix?: string
    /** Value suffix (e.g. ` ms`). Omit for `percent`, which adds `%`. */
    suffix?: string
    /**
     * `none`: unformatted; `number`: thousands separators; `short`: abbreviations (1.2k, 3.4M).
     * `percent`: multiplies by 100 and adds `%`. Pass a 0–1 ratio (`a / b`) and omit the `%` suffix to avoid doubling it.
     */
    style?: 'none' | 'number' | 'short' | 'percent'
    /** Number of decimal places to display. */
    decimalPlaces?: number
}

export interface AssistantDataVisualizationAxisSettings {
    /** Display settings for a plotted Y series. */
    display?: AssistantDataVisualizationAxisDisplaySettings
    /** Number-formatting settings for the values on this axis or series. */
    formatting?: AssistantDataVisualizationAxisFormatting
}

export interface AssistantDataVisualizationAxis {
    /** Name of a column returned by the SQL query to map onto this axis. */
    column: string
    /** Optional series settings. Only applies to Y-axis series. */
    settings?: AssistantDataVisualizationAxisSettings
}

export interface AssistantDataVisualizationColumnDisplaySettings {
    /** Table column description shown in the header tooltip. */
    description?: string
}

export interface AssistantDataVisualizationColumnSettings {
    /** Display settings for this column. */
    display?: AssistantDataVisualizationColumnDisplaySettings
    /** Number-formatting settings for the values in this column. */
    formatting?: AssistantDataVisualizationAxisFormatting
}

/** A column with a description and number formatting. Series display settings apply only to Y-axis series. */
export interface AssistantDataVisualizationColumn {
    /** Name of a column returned by the SQL query. */
    column: string
    /** Optional display and number-formatting settings for this column. */
    settings?: AssistantDataVisualizationColumnSettings
}

export interface AssistantDataVisualizationGoalLine {
    /** Label rendered next to the goal line. */
    label: string
    /** Y-axis value at which the goal line is drawn. */
    value: number
}

export interface AssistantDataVisualizationYAxisSettings {
    /** Label rendered beside this Y axis. */
    label?: string
    /** Scale used for this Y axis. */
    scale?: 'linear' | 'logarithmic'
    /** Whether this Y axis should start at zero. */
    startAtZero?: boolean
    /** Show tick labels on this Y axis. */
    showTicks?: boolean
    /** Show grid lines for this Y axis. */
    showGridLines?: boolean
}

export interface AssistantDataVisualizationBoxPlotSettings {
    /** X-axis category column. Set to `null` for one overall distribution or one box per series. */
    xAxisColumn?: string | null
    /** Optional column that groups each X-axis value into separate colored series. Set to `null` for one series. */
    seriesColumn?: string | null
    /** Numeric column containing the minimum for each box. */
    minColumn: string
    /** Numeric column containing the 25th percentile for each box. */
    p25Column: string
    /** Numeric column containing the median for each box. */
    medianColumn: string
    /** Numeric column containing the mean for each box. */
    meanColumn: string
    /** Numeric column containing the 75th percentile for each box. */
    p75Column: string
    /** Numeric column containing the maximum for each box. */
    maxColumn: string
    /** Clip whiskers to 1.5 times the interquartile range. Defaults to true. */
    excludeOutliers?: boolean
}

export interface AssistantDataVisualizationMetricSettings {
    summary?: 'total' | 'average' | 'latest'
    showChange?: boolean
}

export interface AssistantDataVisualizationChartSettings {
    /**
     * Column used as the X axis. Typically a time bucket or categorical column, but `ScatterPlot`
     * plots two measures against each other, so it needs a numeric column here too.
     */
    xAxis?: AssistantDataVisualizationColumn
    /** Label rendered under the X axis. */
    xAxisLabel?: string
    /** One or more numeric columns plotted as Y series. */
    yAxis?: AssistantDataVisualizationAxis[]
    /** Settings for the left Y axis. */
    leftYAxisSettings?: AssistantDataVisualizationYAxisSettings
    /** Settings for the right Y axis. Only applies when a Y series uses `settings.display.yAxisPosition: "right"`. */
    rightYAxisSettings?: AssistantDataVisualizationYAxisSettings
    /** Column mappings for `BoxPlot`. The SQL must return one pre-aggregated row per X-axis and series pair. */
    boxPlot?: AssistantDataVisualizationBoxPlotSettings
    /**
     * Column that splits a single Y series into multiple colored series — e.g. breaking down
     * a line chart by `country`. Set to `null` or omit to disable. A breakdown buckets rows by
     * x value, so it is ignored when `display` is `ScatterPlot`.
     */
    seriesBreakdownColumn?: string | null
    /** Horizontal goal lines drawn across the chart. */
    goalLines?: AssistantDataVisualizationGoalLine[]
    /** Stack bars to 100% of the total. Only meaningful with `ActionsStackedBar`. */
    stackBars100?: boolean
    /** Show the chart legend. */
    showLegend?: boolean
    /** Where the legend sits. Defaults to right for pie and donut, top for other charts. */
    legendPosition?: 'top' | 'bottom' | 'left' | 'right'
    /**
     * Show annotations on the chart. Only applies to line, area, bar, and stacked bar charts
     * whose X axis is a date or datetime column.
     */
    showAnnotations?: boolean
    /** Settings for `ActionsPie` and `ActionsDonut`. */
    pie?: PieChartSettings
    /** Settings for `Metric`. `summary` defaults to `latest`. */
    metric?: AssistantDataVisualizationMetricSettings
    /** Render each data point's value as a label directly on the series. */
    showValuesOnSeries?: boolean
    /** Replace null aggregation results with zero. */
    showNullsAsZero?: boolean
    /** Show a total summing all Y series. Applies to line, bar, and area charts. */
    showTotalRow?: boolean
}

export interface AssistantDataVisualizationTableSettings {
    /** Columns to display and their order. Omit to show every column returned by the query. */
    columns?: AssistantDataVisualizationColumn[]
    /** Column names to pin to the left of the table. */
    pinnedColumns?: string[]
    /** Transpose rows and columns. */
    transpose?: boolean
}

/**
 * SQL-backed visualization. Use this when the analysis requires custom SQL that cannot be
 * expressed as a standard product-analytics insight — cross-source joins with the data
 * warehouse, window functions, or bespoke aggregations.
 *
 * Prefer `AssistantInsightVizNode` for standard product analytics (trends, funnels, retention,
 * paths, stickiness, lifecycle). Only reach for this node when SQL is strictly necessary.
 */
export interface AssistantDataVisualizationNode {
    kind: NodeKind.DataVisualizationNode
    /** HogQL query object that produces the rows to visualize. */
    source: Record<string, any>
    /**
     * Chart type (default `ActionsTable`): `BoldNumber` = one value; `Metric` = KPI;
     * `ActionsLineGraph` / `ActionsAreaGraph` = time series;
     * `ActionsPie` / `ActionsDonut` / `ActionsProportionBar` = shares;
     * `ActionsBar` / `ActionsStackedBar` = categories; `ActionsBarValue` = horizontal rankings;
     * `TwoDimensionalHeatmap` = 2D aggregates; `ScatterPlot` = two measures;
     * `BoxPlot` = distribution summaries with `chartSettings.boxPlot`.
     */
    display?: AssistantDataVisualizationDisplayType
    /** Chart configuration. Ignored when `display` is `ActionsTable` or `BoldNumber`. */
    chartSettings?: AssistantDataVisualizationChartSettings
    /** Table configuration. Only applies when `display` is `ActionsTable` or omitted. */
    tableSettings?: AssistantDataVisualizationTableSettings
}

// `MCPInsightSerializer.validate_query` wraps these shapes server-side before it saves the
// insight, so a query straight out of a `query-*` tool can be passed through unchanged. Each carries
// an index signature because zod strips every key the schema does not declare, which would send
// `{ kind }` alone to the endpoint and save an empty insight.
// A metrics query is saved bare and is not wrapped. It shares this shape because a separate union
// member puts `insight-update` over the claude.ai tool schema size limit.
export type AssistantMetricsNodeKind = NodeKind.MetricsQuery | NodeKind.MetricsHistogramQuery

export interface AssistantBareInsightQuery {
    kind: InsightNodeKind | AssistantMetricsNodeKind
    [key: string]: unknown
}

export interface AssistantBareHogQLQuery {
    kind: NodeKind.HogQLQuery
    /** The HogQL query to run. */
    query: string
    [key: string]: unknown
}

export interface AssistantEventsQuery {
    kind: NodeKind.EventsQuery
    /** Event columns as HogQL expressions. */
    select: EventsQuery['select']
    // The backend validates EventsQuery fields. Preserve filters and options without expanding the tool schema.
    [key: string]: unknown
}

export interface AssistantDataTableNode {
    kind: NodeKind.DataTableNode
    source: AssistantEventsQuery
    [key: string]: unknown
}

export interface AssistantBIVisualizationNode {
    kind: NodeKind.BIVisualizationNode
    source: AssistantBareHogQLQuery
    /** Complete worksheet configuration, including shelves and filters. Validated by the insight API. */
    config: Record<string, unknown>
    // Preserve display settings without expanding recursive worksheet filters in the tool schema.
    [key: string]: unknown
}

// Zod fills in omitted kinds and takes the first matching union branch. Match events sources
// before the generic insight wrapper so inferred tables keep their kind and table settings.
export type InsightQuery =
    | AssistantDataTableNode
    | AssistantBIVisualizationNode
    | AssistantInsightVizNode
    | AssistantDataVisualizationNode
    | AssistantBareInsightQuery
    | AssistantBareHogQLQuery
    | AssistantEventsQuery