: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { type RecordingApi, SESSION_ACTIVITY_LIMIT, type SessionEventsApi } from '@/api/recordings'
import type { ObservationApi, WatchFeedItemApi } from '@/api/replayVision'
import { parseSeekSeconds, shareSeconds } from './replayLinks'
import {
countryFlag,
fallbackTitle,
formatDuration,
formatOffset,
nearestEntryKey,
personLabel,
recordingView,
sessionListRows,
sessionTimeline,
summaryState,
} from './sessionAdapters'
const START = '2026-10-21T20:14:00.000Z'
function at(seconds: number): string {
return new Date(new Date(START).getTime() + seconds * 1000).toISOString()
}
/** One events row in `SESSION_EVENT_COLUMNS` order. */
function row(
seconds: number,
event: string,
fields: { path?: string; text?: string; issueId?: string; type?: string; message?: string } = {}
): unknown[] {
return [
at(seconds),
event,
fields.path ? `https://app.example.com${fields.path}` : null,
fields.path ?? null,
null,
fields.text ? [fields.text] : [],
event === '$autocapture' ? 'click' : null,
fields.issueId ?? null,
fields.type ? JSON.stringify([fields.type]) : null,
fields.message ? JSON.stringify([fields.message]) : null,
'Chrome',
'Mac OS X',
'Lisbon',
]
}
/** Splits rows the way the two queries return them: page views and clicks, then errors and rage clicks. */
function events(rows: unknown[][]): SessionEventsApi {
const problem = (item: unknown[]): boolean => item[1] === '$exception' || item[1] === '$rageclick'
return {
activity: { results: rows.filter((item) => !problem(item)) },
problems: { results: rows.filter(problem) },
}
}
function observation(overrides: Partial<ObservationApi> & { output?: Record<string, unknown> }): ObservationApi {
const { output, ...rest } = overrides
return {
id: 'obs-1',
scanner_id: 'scanner-1',
session_id: 's-1',
status: 'succeeded',
scanner_snapshot: { scanner_type: 'summarizer' },
scanner_result: { model_output: { scanner_type: 'summarizer', ...output } },
media: [],
created_at: START,
...rest,
}
}
describe('session adapters', () => {
test.each([
[{ properties: { email: '[email protected]' } }, null, '[email protected]'],
[{ name: '0192f3a8-6c1e-7d42-9b8e-3c5a8f3a1e07' }, null, 'Person 1e07'],
[null, 'robin-calloway', 'robin-calloway'],
[null, null, 'Anonymous person'],
])('labels a person %#', (person, distinctId, expected) => {
expect(personLabel(person, distinctId)).toBe(expected)
})
test.each([
['us', '🇺🇸'],
['GB', '🇬🇧'],
[' de ', '🇩🇪'],
['USA', null],
['ZZ', null],
['', null],
[null, null],
])('only renders usable country codes from profiles: %s', (code, expected) => {
const recording = recordingView({ id: 's-1', person: { properties: { $geoip_country_code: code } } })
expect(countryFlag(recording.countryCode)).toBe(expected)
})
test('formats offsets and durations', () => {
expect(formatOffset(134_000)).toBe('2:14')
expect(formatOffset(3_734_000)).toBe('1:02:14')
expect(formatDuration(252)).toBe('4 min 12 s')
expect(formatDuration(45)).toBe('45 s')
})
test('builds the timeline from the recording start, grouped by minute, errors linked to their issue', () => {
const timeline = sessionTimeline(
events([
row(-2, '$pageview', { path: '/files' }),
row(1, '$pageview', { path: '/files' }),
row(48, '$autocapture', { text: 'Q3 plan.pdf' }),
row(134, '$exception', { issueId: 'issue-9', type: 'TypeError', message: 'x is undefined' }),
row(136, '$rageclick', { text: 'Create link' }),
]),
START
)
expect(timeline.groups.map((group) => group.startMs)).toEqual([0, 120_000])
const entries = timeline.groups.flatMap((group) => group.entries)
// The repeated page view is dropped, and the one sent before the first snapshot sits at 0:00.
expect(entries.map((entry) => [entry.kind, entry.offsetMs, entry.text])).toEqual([
['pageview', 0, 'Viewed **/files**'],
['click', 48_000, 'Clicked **Q3 plan.pdf**'],
['exception', 134_000, '**TypeError** x is undefined'],
['rageclick', 136_000, 'Rage clicked **Create link**'],
])
expect(entries.find((entry) => entry.kind === 'exception')?.issueId).toBe('issue-9')
expect(timeline).toMatchObject({
firstExceptionMs: 134_000,
device: 'Chrome on Mac OS X',
city: 'Lisbon',
mainPath: '/files',
})
})
test('keeps an error that comes after the click query hit its cap', () => {
const clicks = Array.from({ length: SESSION_ACTIVITY_LIMIT }, (_, index) =>
row(index, '$autocapture', { text: `Item ${index}` })
)
const timeline = sessionTimeline(
{ activity: { results: clicks }, problems: { results: [row(400, '$exception', { type: 'TypeError' })] } },
START
)
const entries = timeline.groups.flatMap((group) => group.entries)
expect(entries.filter((entry) => entry.kind === 'click')).toHaveLength(20)
expect(entries[entries.length - 1]).toMatchObject({ kind: 'exception', offsetMs: 400_000 })
expect(timeline).toMatchObject({ eventCount: SESSION_ACTIVITY_LIMIT + 1, truncated: true })
expect(nearestEntryKey(timeline, 390_000)).toBe(entries[entries.length - 1]?.key)
})
test('titles a session without a summary from its events', () => {
const recording = recordingView({
id: 's-1',
recording_duration: 252,
start_url: 'https://app.example.com/home',
})
const timeline = sessionTimeline(
events([
row(0, '$pageview', { path: '/files' }),
row(10, '$exception', { type: 'TypeError' }),
row(11, '$rageclick'),
row(12, '$rageclick'),
row(13, '$rageclick'),
]),
START
)
expect(fallbackTitle(recording, timeline)).toBe('4 min on /files with 1 error and 3 rage clicks')
expect(fallbackTitle({ ...recording, durationSeconds: 20 }, null)).toBe('20 s on /home')
})
test('a finished summary wins over a re-scan in flight, and other scanner types never count', () => {
const running = observation({ id: 'obs-2', status: 'running', scanner_result: null })
const done = observation({ output: { title: 'User gives up on sharing', summary: 'Text' } })
const monitor = observation({
id: 'obs-3',
scanner_snapshot: { scanner_type: 'monitor' },
scanner_result: { model_output: { scanner_type: 'monitor' } },
})
expect(summaryState([running, done])).toMatchObject({
kind: 'ready',
summary: { title: 'User gives up on sharing' },
})
expect(summaryState([running])).toEqual({ kind: 'running' })
expect(summaryState([monitor])).toEqual({ kind: 'none' })
})
test.each([
[{ status: 'failed' as const, error_reason: 'provider_error:Gemini timed out' }, null],
[
{ status: 'ineligible' as const, error_reason: 'too_short:session is shorter than 5 seconds' },
'Session is shorter than 5 seconds.',
],
[{ status: 'ineligible' as const }, null],
])('a scan that ended without a summary is final, not something to summarize again %#', (ended, reason) => {
expect(summaryState([observation({ ...ended, scanner_result: null })])).toEqual({ kind: 'failed', reason })
})
test('chapters keep their index for the frame endpoint and mark the key moment', () => {
const state = summaryState([
observation({
output: {
key_moment_ms: 134_000,
chapters: [
{ kind: 'activity', start_ms: 0, end_ms: 60_000, title: 'Opens files' },
{ kind: 'idle', start_ms: 60_000, end_ms: 120_000, title: 'Idle' },
{ kind: 'activity', start_ms: 120_000, end_ms: 252_000, title: 'Share link fails' },
],
},
media: [{ kind: 'chapter', position: 2 }],
}),
])
if (state.kind !== 'ready') {
throw new Error('expected a summary')
}
expect(state.summary.chapters.map((chapter) => [chapter.index, chapter.isKeyMoment, chapter.hasFrame])).toEqual(
[
[0, false, false],
[2, true, true],
]
)
})
test('the list puts the feed first, once per session, then the recordings it left out', () => {
const recordings: RecordingApi[] = [
{
id: 's-2',
recording_duration: 60,
person: { properties: { email: '[email protected]', $geoip_country_code: 'gb' } },
},
{ id: 's-1', recording_duration: 252 },
]
const feed: WatchFeedItemApi[] = [
{
observation: observation({ session_id: 's-1', output: { title: 'Share fails' } }),
reason: { kind: 'notable' },
},
{ observation: observation({ id: 'obs-4', session_id: 's-1' }), reason: { kind: 'recent' } },
]
const rows = sessionListRows(feed, recordings)
expect(rows.map((item) => [item.sessionId, item.title, item.durationSeconds, item.countryCode])).toEqual([
['s-1', 'Share fails', 252, null],
['s-2', null, 60, 'GB'],
])
})
test.each([
['134', 134],
['12.7', 12],
['-1', undefined],
['abc', undefined],
[undefined, undefined],
])('parses t=%s', (value, expected) => {
expect(parseSeekSeconds(value)).toBe(expected)
})
test('shares at the linked time, else the key moment, else the start', () => {
expect(shareSeconds(134_500, 20)).toBe(20)
expect(shareSeconds(134_500, undefined)).toBe(134)
expect(shareSeconds(null, undefined)).toBe(0)
})
})