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.

12.0 KB
Raw Blame
// The view models of the Views tab. Server times are ISO strings; `readAt` is device epoch ms.

import type { MetricChartKind, MetricFormat, MetricInterval, MetricPoint, MetricSeries } from './types'

export type ViewKind = 'dashboard' | 'insight' | 'web_analytics'

/** The views a pin can hold: the ones the Views list can draw as a Number or a Chart. */
export type PinKind = Extract<ViewKind, 'dashboard' | 'insight'>

export type PinDisplayMode = 'row' | 'number' | 'chart'

/**
 * Where a view was opened from, for `mobile_view_opened`. `dashboard`: a tile on a dashboard screen. `widget`: the
 * Chart home screen widget.
 */
export type ViewEntry = 'pinned' | 'recent' | 'browse' | 'search' | 'deep_link' | 'dashboard' | 'widget'

export interface ViewRef {
    kind: ViewKind
    /** Dashboard id as a string or insight `short_id`; null for web analytics. */
    ref: string | null
    /** The web path without the project prefix, such as `/dashboard/12`. */
    href: string | null
    name: string
}

/** How this phone shows a pin. Device-local; the Views list can choose a default when no preference exists. */
export interface PinDisplay {
    mode: PinDisplayMode
    /** A dashboard pin in Number or Chart mode reads this tile's insight with `from_dashboard`. */
    tileId?: number
    insightId?: number
    insightShortId?: string
}

export interface PinView extends ViewRef {
    kind: PinKind
    ref: string
    /** The row the list keeps for this view. Local rank and display are keyed by it. */
    shortcutId: string
    /** Every row that matches this view, across environments. Unpin deletes all of them. */
    shortcutIds: string[]
    /** Position in the server's order (`order`, then path). */
    serverOrder: number
    /** Device-local order; null sorts after ranked pins, in server order. */
    rank: number | null
    display: PinDisplay
}

export interface RecentView extends ViewRef {
    viewedAt: string
    source: 'device' | 'server'
}

/** A row in Browse or in search results. */
export interface BrowseRow extends ViewRef {
    description: string | null
    /** Dashboards: this user's last web view. Insights: last modified. */
    at: string | null
}

/** A view opened on this phone, kept on the device for Recent. */
export interface DeviceRecentEntry {
    kind: ViewKind
    ref: string | null
    name: string
    viewedAt: string
}

/** The refresh fields of one data item. They change only on a response with a result and no error. */
export interface Freshness {
    restoredFromDevice?: boolean
    /** Cache-only misses must not renew the age of the last successful result. */
    dataReadAt?: number
    lastRefreshAt: string | null
    cacheTargetAge: string | null
    nextAllowedRefreshAt: string | null
    /** Device ms of the last response for this item, good or not. */
    readAt: number
    /** The last read failed. The other fields keep the last good values. */
    refreshFailed: boolean
}

export interface NumberDelta {
    previous: number
    /** `value - previous`, scaled to points for `percentage_scaled`. */
    change: number
    /** Percent change, null when `previous` is 0. */
    percent: number | null
    /** `points` for values that are already percentages: show `change`, not `percent`. */
    unit: 'percent' | 'points'
    /** `compare`: the previous period. `previous_bucket`: the bucket before the value's bucket. */
    basis: 'compare' | 'previous_bucket'
    /** The bucket the value is compared with, for "vs Oct 6". Null for window totals. */
    previousAt: string | null
}

export interface InsightSeriesView {
    key: string
    label: string
    points: MetricPoint[]
    /** `previous` marks the compare series of the period before. */
    compare: 'current' | 'previous' | null
    /** The series index in the trends query, for the actors query. */
    seriesIndex: number
    breakdownValue: string | number | null | (string | number | null)[]
}

export interface ResolvedRange {
    from: string
    to: string
}

/** The range the view saved: `query.source.dateRange`, or the dashboard's `filters`. */
export interface SavedRange {
    dateFrom: string | null
    dateTo: string | null
}

/** One funnel step and the people who reached it. */
export interface FunnelStepView {
    key: string
    /** The step's custom name, else its event or action name. */
    name: string
    count: number
    /** Percent of the people who entered the funnel at step 1. Null when nobody entered. */
    percentOfFirst: number | null
    /** Percent of the people who reached the step before. Null for step 1. */
    percentOfPrevious: number | null
    /** People who reached the step before but not this one. Null for step 1. */
    droppedOff: number | null
    /** Median seconds from the step before. Null for step 1, or when nobody converted. */
    medianSeconds: number | null
}

export interface FunnelView {
    steps: FunnelStepView[]
    /** Percent of step 1 that reached the last step. */
    conversion: number | null
    /** The breakdown values the steps add up. 0 without a breakdown. */
    breakdownValues: number
}

export type RetentionPeriodUnit = 'hour' | 'day' | 'week' | 'month'

export interface RetentionCellView {
    count: number
    /** 0 to 100, of the cohort size, or of the period before for `reference: 'previous'`. */
    percent: number
}

export interface RetentionCohortView {
    key: string
    /** Start of the cohort's period 0, ISO. */
    date: string
    /** People in the cohort: the count of period 0. */
    size: number
    /** From period 0, every period that has started. Periods still in the future are left out. */
    cells: RetentionCellView[]
}

export interface RetentionView {
    period: RetentionPeriodUnit
    /** "Week 0", "Week 1" and so on: one per period column. */
    periodLabels: string[]
    cohorts: RetentionCohortView[]
    reference: 'total' | 'previous'
}

/** One value of a ranking: a breakdown value, or a series when there is no breakdown. */
export interface RankedValueView {
    key: string
    label: string
    value: number
}

export interface SqlColumnView {
    name: string
    /** The ClickHouse type reduced to the web's scalar names: INTEGER, FLOAT, DECIMAL, STRING, DATE, DATETIME, BOOLEAN or other. */
    scalar: string
    isNumerical: boolean
    isDate: boolean
    /** From `tableSettings.columns[].settings.formatting`, else from the matching `chartSettings.yAxis` entry. */
    format: InsightPresentation | null
}

export type SqlCell = string | number | boolean | null

export interface SqlTableView {
    columns: SqlColumnView[]
    rows: SqlCell[][]
    /** The server cut the result at its limit, so `rows` is a prefix. */
    hasMore: boolean
}

export interface RankingView {
    /** Highest first. SQL rows keep the server's order, which the author chose. */
    rows: RankedValueView[]
    /** The sum of the rows, or null when the math counts distinct people, whom several rows can share. */
    total: number | null
}

export interface InsightCapabilities {
    number: boolean
    chart: boolean
    /** "View people" and "Watch recordings" at a point. */
    people: boolean
}

/** A saved insight's own number settings: a SQL column's `formatting`, or a trends insight's aggregation axis. */
export interface InsightPresentation {
    kind: 'sql' | 'trends'
    style: string | null
    prefix: string
    suffix: string
    decimalPlaces?: number
    minDecimalPlaces?: number
    /** Multiplies the value before it is formatted. The web's SQL table shows a percent column's fractions as percents. */
    scale?: number
}

export interface InsightValueFormat extends MetricFormat {
    presentation?: InsightPresentation
}

/** One read of an insight, as the list and the view screens see it. */
export interface InsightSnapshot extends Freshness {
    insightId: number
    shortId: string
    name: string
    description: string | null
    /** `TrendsQuery`, `FunnelsQuery`, `HogQLQuery` and so on. */
    queryKind: string | null
    /** The response's query, with the dashboard and tile layers applied. Compare and the Point sheet use its `source`. */
    query: unknown
    resolvedRange: ResolvedRange | null
    timezone: string | null
    savedRange: SavedRange
    interval: MetricInterval
    format: InsightValueFormat
    /** The big number. See `valueAt`. */
    value: number | null
    /** The bucket `value` is for. Null when `value` is the window's total. */
    valueAt: string | null
    previous: number | null
    delta: NumberDelta | null
    /** The first current series, for the number pin's sparkline. */
    series: MetricSeries | null
    allSeries: InsightSeriesView[]
    /** Line or bar for a trends display over time, with any number of series and breakdowns. */
    chartKind: MetricChartKind | null
    /** Funnel steps of a `FunnelsQuery` in the steps layout. */
    funnel: FunnelView | null
    retention: RetentionView | null
    /** Totals per breakdown value or series, for value bars, tables and pies. */
    ranking: RankingView | null
    /** The result of a SQL insight (`HogQLQuery`), whatever its display. Null for other kinds. */
    sqlTable: SqlTableView | null
    /** Start of the bucket that contains now. It is never complete. */
    inProgressFrom: string | null
    /** On a dashboard: the tile ignores the dashboard range. */
    usesOwnRange: boolean
    capabilities: InsightCapabilities
    /** "Line", "Bar", "Big number", "Funnel" and so on. */
    kindLabel: string
    /** The last good response computed fresh instead of reading the cache. */
    computed: boolean
    /** The author's name, for the About sheet. */
    createdBy: string | null
    createdAt: string | null
}

export interface DashboardTileView {
    tileId: number
    kind: 'insight' | 'text'
    insightId: number | null
    shortId: string | null
    name: string
    text: string | null
    /** Shows "Uses its own range". */
    usesOwnRange: boolean
    /** A SQL tile without `{filters}`: the app reads it without the range override. */
    ignoresRangeOverride: boolean
    capabilities: InsightCapabilities
    kindLabel: string
    /** Why a pin cannot show the tile: a trends insight with several series, or with a breakdown. */
    seriesCount: number
    hasBreakdown: boolean
}

export interface DashboardView {
    id: number
    name: string
    description: string | null
    savedRange: SavedRange
    /** `Dashboard.last_refresh`, shared by every viewer. Only the bulk refresh rule reads it. */
    lastRefresh: string | null
    /** In phone order: the web's one-column layout. */
    tiles: DashboardTileView[]
}

export interface WebOverviewMetric {
    key: string
    label: string
    format: MetricFormat
    value: number | null
    previous: number | null
    changePercent: number | null
    isIncreaseBad: boolean
}

export interface WebOverviewSnapshot extends Freshness {
    metrics: WebOverviewMetric[]
    resolvedRange: ResolvedRange | null
    timezone: string | null
    computed: boolean
}

/** A person at a chart point. */
export interface ActorRow {
    id: string
    name: string
    /** Session ids that matched, for "Watch recordings". Empty without `includeRecordings`. */
    recordings: string[]
}

export type RangePresetKey =
    | 'today'
    | 'yesterday'
    | '24h'
    | '7d'
    | '30d'
    | '90d'
    | 'this_week'
    | 'this_month'
    | 'last_month'
    | 'this_year'
    | 'all'
    | '1h'
    | '48h'
    | '14d'
    | '180d'
    | 'last_week'

/** How a stepped range moves: one calendar unit, a rolling window of whole days, or a window of hours. */
export type RangeStepUnit = 'day' | 'week' | 'month' | 'year' | 'days' | 'hours'

/** A range the user picked for this session. `null` elsewhere means the view's saved range. */
export type RangeChoice =
    | { kind: 'preset'; key: RangePresetKey }
    | {
          kind: 'fixed'
          /** `YYYY-MM-DD` in the project timezone, or an ISO datetime when `explicitDate`. */
          dateFrom: string
          dateTo: string
          explicitDate: boolean
          unit: RangeStepUnit
          /** The preset a step started from, so stepping back to its window returns to it. */
          origin: RangePresetKey | null
      }