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.

11.4 KB
Raw Blame
import { z } from 'zod'

// Common enums and types
const NodeKind = z.enum(['TrendsQuery', 'FunnelsQuery', 'PathsQuery', 'HogQLQuery', 'EventsNode'])

const IntervalType = z.enum(['hour', 'day', 'week', 'month'])

const ChartDisplayType = z.enum([
    'ActionsLineGraph',
    'ActionsTable',
    'ActionsPie',
    'ActionsBar',
    'ActionsStackedBar',
    'ActionsAreaGraph',
    'ActionsBarValue',
    'WorldMap',
    'BoldNumber',
    'TwoDimensionalHeatmap',
])

// NOTE: Breakdowns are restricted to either person or event for simplicity
const BreakdownType = z.enum(['person', 'event'])

const FunnelVizType = z.enum(['steps', 'time_to_convert', 'trends'])

const FunnelOrderType = z.enum(['ordered', 'unordered', 'strict'])

const FunnelStepReference = z.enum(['total', 'previous'])

const BreakdownAttributionType = z.enum(['first_touch', 'last_touch', 'all_events'])

const FunnelLayout = z.enum(['horizontal', 'vertical'])

const FunnelConversionWindowTimeUnit = z.enum(['minute', 'hour', 'day', 'week', 'month'])

// Base schemas
const DateRange = z.object({
    date_from: z.string().nullable().optional(),
    date_to: z.string().nullable().optional(),
    explicitDate: z.boolean().optional(),
})

const PropertyFilter = z.object({
    key: z.string(),
    value: z
        .union([z.string(), z.number(), z.array(z.string()), z.array(z.number())])
        .nullable()
        .optional(),
    operator: z.string().optional(),
    type: z.string().optional(),
})

// NOTE: Only a single level of nesting is supported here, since we can't specify recursive schema for tool inputs.
const PropertyGroupFilter = z.object({
    type: z.enum(['AND', 'OR']),
    values: z.array(PropertyFilter),
})

const AnyPropertyFilter = z.union([PropertyFilter, PropertyGroupFilter])

const HogQLVariable = z.object({
    variableId: z.string(),
    code_name: z.string(),
    value: z.any().optional(),
    isNull: z.boolean().optional(),
})

const HogQLFilters = z.object({
    properties: z.array(AnyPropertyFilter).optional(),
    dateRange: DateRange.optional(),
    filterTestAccounts: z.boolean().optional(),
})

const ChartAxis = z.object({
    column: z.string().describe('Name of a column returned by the SQL query.'),
    settings: z
        .object({
            formatting: z
                .object({
                    style: z.enum(['none', 'number', 'short', 'percent']).optional(),
                    decimalPlaces: z.number().optional(),
                    prefix: z.string().optional(),
                    suffix: z.string().optional(),
                })
                .optional()
                .describe('Display formatting for this axis, such as percent, decimals, prefix, or suffix.'),
            display: z
                .object({
                    label: z.string().optional(),
                    displayType: z.enum(['auto', 'line', 'bar', 'area']).optional(),
                    yAxisPosition: z.enum(['left', 'right']).optional(),
                })
                .optional(),
        })
        .optional(),
})

const ChartSettings = z.object({
    xAxis: ChartAxis.optional().describe('Column used as the X axis, usually a time bucket or category.'),
    yAxis: z
        .array(ChartAxis)
        .optional()
        .describe(
            'Numeric columns plotted as Y series. Include only final metrics the user cares about, not helper columns such as numerators or denominators.'
        ),
    seriesBreakdownColumn: z
        .string()
        .nullable()
        .optional()
        .describe('Column that splits a single Y metric into multiple colored series.'),
    showLegend: z.boolean().optional(),
    showNullsAsZero: z.boolean().optional(),
    stackBars100: z.boolean().optional(),
})

const TableSettings = z.object({
    columns: z.array(ChartAxis).optional().describe('Columns to display and their order.'),
    pinnedColumns: z.array(z.string()).optional(),
    transpose: z.boolean().optional(),
})

// Math types that don't require a property
const BaseMathType = z.enum([
    'total',
    'dau',
    'weekly_active',
    'monthly_active',
    'unique_session',
    'first_time_for_user',
    'first_matching_event_for_user',
])

// Math types that require a math_property
const PropertyMathType = z.enum(['avg', 'sum', 'min', 'max', 'median', 'p75', 'p90', 'p95', 'p99'])

// Combined math types
const MathType = z.union([BaseMathType, PropertyMathType])

const PROPERTY_MATH_TYPES = ['avg', 'sum', 'min', 'max', 'median', 'p75', 'p90', 'p95', 'p99']

// Base entity object without refinement for extension
const BaseEntityObject = z.object({
    custom_name: z.string().describe('A display name'),
    math: MathType.optional(),
    math_property: z.string().optional(),
    properties: z.union([z.array(AnyPropertyFilter), PropertyGroupFilter]).optional(),
})

const EventsNode = BaseEntityObject.extend({
    kind: z.literal('EventsNode'),
    event: z.string().optional(),
    limit: z.number().optional(),
}).refine(
    (data) => {
        if (PROPERTY_MATH_TYPES.includes(data.math || '')) {
            return !!data.math_property
        }
        return true
    },
    {
        message: `math_property is required for ${PROPERTY_MATH_TYPES.join(', ')} math types`,
    }
)

const AnyEntityNode = EventsNode

// Base query interface
const InsightsQueryBase = z.object({
    dateRange: DateRange.optional(),
    // No hard default: omission lets the project's "Filter out internal and test
    // users" default setting apply, matching UI behavior for new insights.
    filterTestAccounts: z.boolean().optional(),
    properties: z
        .union([z.array(AnyPropertyFilter), PropertyGroupFilter])
        .optional()
        .default([]),
})

// Breakdown filter
const BreakdownFilter = z.object({
    breakdown_type: BreakdownType.nullable().optional().default('event'),
    breakdown_limit: z.number().optional(),
    breakdown: z
        .union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))])
        .nullable()
        .optional(),
})

// Compare filter
const CompareFilter = z.object({
    compare: z.boolean().optional().default(false),
    compare_to: z.string().optional(),
})

// Trends filter
const TrendsFilter = z.object({
    display: ChartDisplayType.optional().default('ActionsLineGraph'),
    showLegend: z.boolean().optional().default(false),
})

// Trends query
const TrendsQuerySchema = InsightsQueryBase.extend({
    kind: z.literal('TrendsQuery'),
    interval: IntervalType.optional().default('day'),
    series: z.array(AnyEntityNode),
    trendsFilter: TrendsFilter.optional(),
    breakdownFilter: BreakdownFilter.optional(),
    compareFilter: CompareFilter.optional(),
    conversionGoal: z.any().nullable().optional(),
})

// HogQL query
const HogQLQuerySchema = z.object({
    kind: z.literal('HogQLQuery'),
    query: z.string(),
    filters: HogQLFilters.optional(),
    connectionId: z
        .string()
        .optional()
        .describe(
            'Optional id of an external data source (e.g. a Postgres or DuckDB direct-query connection). When set, the query runs against that source instead of ClickHouse. Use external-data-sources-connections-list to discover available connection ids.'
        ),
})

// Funnels filter
const FunnelsFilter = z.object({
    layout: FunnelLayout.optional(),
    breakdownAttributionType: BreakdownAttributionType.optional(),
    breakdownAttributionValue: z.number().optional(),
    funnelToStep: z.number().optional(),
    funnelFromStep: z.number().optional(),
    funnelOrderType: FunnelOrderType.optional(),
    funnelVizType: FunnelVizType.optional(),
    funnelWindowInterval: z.number().optional().default(14),
    funnelWindowIntervalUnit: FunnelConversionWindowTimeUnit.optional().default('day'),
    funnelStepReference: FunnelStepReference.optional(),
})

// Funnels query
const FunnelsQuerySchema = InsightsQueryBase.extend({
    kind: z.literal('FunnelsQuery'),
    interval: IntervalType.optional(),
    series: z.array(AnyEntityNode).min(2, 'At least two steps are required for a funnel'),
    funnelsFilter: FunnelsFilter.optional(),
    breakdownFilter: BreakdownFilter.optional(),
})

// Paths types
const PathType = z.enum(['$pageview', '$screen', 'custom_event', 'hogql'])

const PathCleaningFilter = z.object({
    alias: z.string().optional(),
    regex: z.string().optional(),
})

// Paths filter
const PathsFilter = z.object({
    includeEventTypes: z.array(PathType).optional(),
    pathsHogQLExpression: z
        .string()
        .optional()
        .describe('A HogQL expression to use as the path step name. Requires includeEventTypes to contain "hogql".'),
    startPoint: z.string().optional().describe('Only show paths starting at this step'),
    endPoint: z.string().optional().describe('Only show paths ending at this step'),
    stepLimit: z.number().optional().default(5).describe('Maximum number of path steps (default 5)'),
    edgeLimit: z.number().optional().default(50).describe('Maximum number of edges to return (default 50)'),
    excludeEvents: z.array(z.string()).optional().describe('Events to exclude from the path'),
    pathGroupings: z.array(z.string()).optional().describe('Wildcard groups to merge similar path steps'),
    localPathCleaningFilters: z
        .array(PathCleaningFilter)
        .optional()
        .describe('Regex rules to clean/simplify path step names'),
    minEdgeWeight: z.number().optional(),
    maxEdgeWeight: z.number().optional(),
})

// Paths query
const PathsQuerySchema = InsightsQueryBase.extend({
    kind: z.literal('PathsQuery'),
    pathsFilter: PathsFilter.default({ stepLimit: 5, edgeLimit: 50 }),
})

// Insight Schema
const InsightVizNodeSchema = z.object({
    kind: z.literal('InsightVizNode'),
    source: z.discriminatedUnion('kind', [TrendsQuerySchema, FunnelsQuerySchema, PathsQuerySchema]),
})

const DataVisualizationNodeSchema = z.object({
    kind: z.literal('DataVisualizationNode'),
    source: HogQLQuerySchema,
    display: ChartDisplayType.optional().describe(
        'Visualization type. Time series should usually use ActionsLineGraph or ActionsAreaGraph; use ActionsTable only when table rows are the intended output.'
    ),
    chartSettings: ChartSettings.optional(),
    tableSettings: TableSettings.optional(),
})

// Any insight query
const InsightQuerySchema = z.discriminatedUnion('kind', [InsightVizNodeSchema, DataVisualizationNodeSchema])

// Export all schemas
export {
    // Enums
    NodeKind,
    IntervalType,
    ChartDisplayType,
    BreakdownType,
    FunnelVizType,
    FunnelOrderType,
    FunnelStepReference,
    BreakdownAttributionType,
    FunnelLayout,
    FunnelConversionWindowTimeUnit,
    // Math types
    BaseMathType,
    PropertyMathType,
    MathType,
    // Base types
    DateRange,
    PropertyFilter,
    PropertyGroupFilter,
    AnyPropertyFilter,
    ChartAxis,
    ChartSettings,
    TableSettings,
    // Entity nodes
    EventsNode,
    AnyEntityNode,
    // Filters
    BreakdownFilter,
    CompareFilter,
    TrendsFilter,
    FunnelsFilter,
    PathsFilter,
    // HogQL types
    HogQLVariable,
    HogQLFilters,
    // Queries
    TrendsQuerySchema,
    FunnelsQuerySchema,
    PathsQuerySchema,
    HogQLQuerySchema,
    InsightVizNodeSchema,
    DataVisualizationNodeSchema,
    InsightQuerySchema,
}

export type TrendsQuery = z.infer<typeof TrendsQuerySchema>
export type FunnelsQuery = z.infer<typeof FunnelsQuerySchema>
export type PathsQuery = z.infer<typeof PathsQuerySchema>
export type HogQLQuery = z.infer<typeof HogQLQuerySchema>
export type InsightQuery = z.infer<typeof InsightQuerySchema>