: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 { afterEach, describe, expect, it, vi } from 'vitest'
const { mockMe, mockApiClientCtor, mockCapture } = vi.hoisted(() => {
const mockMe = vi.fn()
const mockApiClientCtor = vi.fn().mockImplementation(function (config) {
return {
config,
users: () => ({ me: mockMe }),
}
})
return { mockMe, mockApiClientCtor, mockCapture: vi.fn() }
})
vi.mock('@/api/client', () => ({
ApiClient: mockApiClientCtor,
}))
vi.mock('@/lib/posthog', () => ({
getPostHogClient: () => ({ capture: mockCapture }),
}))
import type { RedisLike } from '@/hono/cache/RedisCache'
import { RequestContext } from '@/hono/request-context'
import { AnalyticsEvent } from '@/lib/posthog/analytics'
import type { RequestProperties } from '@/lib/request-properties'
import { makeRedisRateLimitStubs } from './helpers/redis-rate-limit-stubs'
function fakeRedis(): RedisLike {
const store = new Map<string, string>()
return {
get: async (key) => store.get(key) ?? null,
set: async (key, value) => {
store.set(key, String(value))
return 'OK'
},
del: async (...keys) => {
let n = 0
for (const k of keys) {
if (store.delete(k)) {
n++
}
}
return n
},
scan: async () => ['0', [...store.keys()]],
...makeRedisRateLimitStubs(),
}
}
function spyRedis(): RedisLike {
return {
get: vi.fn(async () => null),
set: vi.fn(async () => 'OK'),
del: vi.fn(async () => 0),
scan: vi.fn(async () => ['0', []] as [string, string[]]),
...makeRedisRateLimitStubs(),
}
}
const env = {} as any
function makeProps(overrides: Partial<RequestProperties> = {}): RequestProperties {
return {
userHash: 'test-user',
apiToken: 'phx_test',
sessionId: 'sess-1',
mcpClientName: 'test-client',
mcpClientVersion: '1.0',
mcpProtocolVersion: '2025-03-26',
transport: 'streamable-http',
requestStartTime: Date.now(),
...overrides,
}
}
describe('RequestContext', () => {
it.each([
{ impersonated: true, apiToken: 'phx_test', suppressed: true },
{ impersonated: false, apiToken: 'phx_test', suppressed: false },
{ impersonated: undefined, apiToken: 'phx_test', suppressed: false },
{ impersonated: undefined, apiToken: 'pha_test', suppressed: false },
])(
'passes trusted capture policy=$suppressed to captured events',
async ({ impersonated, apiToken, suppressed }) => {
mockCapture.mockClear()
const ctx = new RequestContext(fakeRedis(), env, makeProps({ apiToken }))
if (impersonated !== undefined) {
await ctx.tokenCache.set('apiKey', {
scopes: [],
scoped_teams: [],
scoped_organizations: [],
is_impersonated: impersonated,
suppress_analytics: impersonated,
})
}
await ctx.trackEvent(
AnalyticsEvent.MCP_FEEDBACK_SUBMITTED,
{ is_impersonated: !impersonated, suppress_analytics: !impersonated },
undefined,
undefined,
'user-123'
)
expect(mockCapture).toHaveBeenCalledWith(
expect.objectContaining({
event: AnalyticsEvent.MCP_FEEDBACK_SUBMITTED,
properties: expect.objectContaining({
is_impersonated: impersonated === true,
suppress_analytics: suppressed,
}),
})
)
}
)
describe('ApiClient construction', () => {
const originalEnv = { ...process.env }
afterEach(() => {
process.env = { ...originalEnv }
mockApiClientCtor.mockClear()
mockMe.mockClear()
})
it('passes POSTHOG_PUBLIC_URL as publicBaseUrl to the ApiClient', async () => {
process.env.POSTHOG_API_BASE_URL = 'http://posthog-web-django.posthog.svc.cluster.local:8000'
process.env.POSTHOG_PUBLIC_URL = 'https://us.posthog.com'
mockMe.mockResolvedValue({ success: true, data: { distinct_id: 'user-1' } })
const ctx = new RequestContext(fakeRedis(), env, makeProps())
await ctx.getDistinctId()
expect(mockApiClientCtor).toHaveBeenCalledTimes(1)
const config = mockApiClientCtor.mock.calls[0]![0]
expect(config.baseUrl).toBe('http://posthog-web-django.posthog.svc.cluster.local:8000')
expect(config.publicBaseUrl).toBe('https://us.posthog.com')
})
it('falls back to POSTHOG_API_BASE_URL when POSTHOG_PUBLIC_URL is not set', async () => {
process.env.POSTHOG_API_BASE_URL = 'https://us.posthog.com'
delete process.env.POSTHOG_PUBLIC_URL
mockMe.mockResolvedValue({ success: true, data: { distinct_id: 'user-1' } })
const ctx = new RequestContext(fakeRedis(), env, makeProps())
await ctx.getDistinctId()
const config = mockApiClientCtor.mock.calls[0]![0]
expect(config.baseUrl).toBe('https://us.posthog.com')
expect(config.publicBaseUrl).toBe('https://us.posthog.com')
})
it.each([
{ label: 'cached OAuth client name', cached: 'Claude', expected: 'Claude' },
{ label: 'no cached OAuth client name', cached: undefined, expected: undefined },
])('passes $label through as oauthClientName', async ({ cached, expected }) => {
const redis = fakeRedis()
if (cached) {
await redis.set('mcp:token:test-user:clientName', JSON.stringify(cached))
}
mockMe.mockResolvedValue({ success: true, data: { distinct_id: 'user-1' } })
const ctx = new RequestContext(redis, env, makeProps())
await ctx.getDistinctId()
expect(mockApiClientCtor.mock.calls[0]![0].oauthClientName).toBe(expected)
})
it('forwards the session client identity after the API client already exists', async () => {
mockMe.mockResolvedValue({ success: true, data: { distinct_id: 'user-1' } })
const ctx = new RequestContext(fakeRedis(), env, makeProps({ mcpClientName: undefined }))
await ctx.getContext()
ctx.setMcpContexts(
{
authMethod: 'personal_api_key',
mcpClientName: undefined,
},
{
mcpClientName: 'external-claims-smoke-a',
mcpClientVersion: '1.0',
mcpProtocolVersion: '2025-03-26',
}
)
const api = mockApiClientCtor.mock.results[0]!.value
expect(api.config).toMatchObject({
mcpClientName: 'external-claims-smoke-a',
mcpClientVersion: '1.0',
mcpProtocolVersion: '2025-03-26',
})
})
it('uses the session client identity when API construction happens later', async () => {
mockMe.mockResolvedValue({ success: true, data: { distinct_id: 'user-1' } })
const ctx = new RequestContext(fakeRedis(), env, makeProps({ mcpClientName: undefined }))
ctx.setMcpContexts(
{
authMethod: 'personal_api_key',
mcpClientName: undefined,
},
{
mcpClientName: 'external-claims-smoke-b',
mcpClientVersion: '2.0',
mcpProtocolVersion: '2025-03-26',
}
)
await ctx.getContext()
expect(mockApiClientCtor.mock.calls[0]![0]).toMatchObject({
mcpClientName: 'external-claims-smoke-b',
mcpClientVersion: '2.0',
mcpProtocolVersion: '2025-03-26',
})
})
})
// `agent-feedback` and the context-switch events capture through `trackEvent`, which
// reads these properties. `clientInfo` arrives on `initialize` only, so reading the
// request alone records no client for every call after the first.
describe('buildClientProperties', () => {
it('falls back to the session client identity mid-session', () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps({ mcpClientName: undefined }))
ctx.setMcpContexts(
{ authMethod: 'personal_api_key', mcpClientName: undefined },
{
mcpClientName: 'claude-code',
mcpClientVersion: '1.0',
mcpProtocolVersion: '2025-03-26',
mcpConsumer: 'plugin',
mcpVendorClient: 'ClaudeCode',
}
)
expect(ctx.buildClientProperties()).toMatchObject({
$mcp_client_name: 'claude-code',
$mcp_client_version: '1.0',
$mcp_protocol_version: '2025-03-26',
$mcp_consumer: 'plugin',
$mcp_vendor_client: 'ClaudeCode',
})
})
it('keeps the live request identity when the call carries one', () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps({ mcpClientName: 'cursor' }))
ctx.setMcpContexts(
{ authMethod: 'personal_api_key', mcpClientName: 'cursor' },
{ mcpClientName: 'claude-code' }
)
expect(ctx.buildClientProperties()).toMatchObject({ $mcp_client_name: 'cursor' })
})
})
describe('getDistinctId', () => {
it('deduplicates concurrent calls into a single API request', async () => {
mockMe.mockResolvedValue({ success: true, data: { distinct_id: 'user-123' } })
const ctx = new RequestContext(fakeRedis(), env, makeProps())
const [a, b, c] = await Promise.all([ctx.getDistinctId(), ctx.getDistinctId(), ctx.getDistinctId()])
expect(a).toBe('user-123')
expect(b).toBe('user-123')
expect(c).toBe('user-123')
expect(mockMe).toHaveBeenCalledTimes(1)
})
it('returns cached distinctId without calling API', async () => {
const redis = fakeRedis()
await redis.set('mcp:token:test-user:distinctId', JSON.stringify('cached-id'))
mockMe.mockClear()
const ctx = new RequestContext(redis, env, makeProps())
const result = await ctx.getDistinctId()
expect(result).toBe('cached-id')
expect(mockMe).not.toHaveBeenCalled()
})
it('caches the resolved distinctId for subsequent calls', async () => {
mockMe.mockResolvedValueOnce({ success: true, data: { distinct_id: 'fresh-id' } })
const redis = fakeRedis()
const ctx = new RequestContext(redis, env, makeProps())
await ctx.getDistinctId()
const cached = await redis.get('mcp:token:test-user:distinctId')
expect(JSON.parse(cached!)).toBe('fresh-id')
})
it('throws when API returns an error', async () => {
mockMe.mockResolvedValue({ success: false, error: { message: 'Unauthorized' } })
const ctx = new RequestContext(fakeRedis(), env, makeProps())
await expect(ctx.getDistinctId()).rejects.toThrow('Failed to get user')
})
})
describe('getSessionUuid', () => {
it('returns undefined when sessionId is undefined', async () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps())
expect(await ctx.getSessionUuid(undefined)).toBeUndefined()
})
it('returns a stable UUID for the same sessionId', async () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps())
const first = await ctx.getSessionUuid('sess-abc')
const second = await ctx.getSessionUuid('sess-abc')
expect(first).toBe(second)
expect(first).toMatch(/^[0-9a-f-]{36}$/)
})
it('returns different UUIDs for different sessionIds', async () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps())
const a = await ctx.getSessionUuid('sess-1')
const b = await ctx.getSessionUuid('sess-2')
expect(a).not.toBe(b)
})
})
describe('getSessionUuid memoization', () => {
it('serves one lookup per key and retries after a failure', async () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps())
const spy = vi.spyOn(ctx.sessionManager, 'getSessionUuid')
const first = await ctx.getSessionUuid('sess-memo')
const second = await ctx.getSessionUuid('sess-memo')
expect(second).toBe(first)
expect(spy).toHaveBeenCalledTimes(1)
// A cached rejection would outlive the blip that caused it, and three tool-error
// paths await this outside a try.
spy.mockRejectedValueOnce(new Error('redis down'))
await expect(ctx.getSessionUuid('sess-retry')).rejects.toThrow('redis down')
spy.mockRestore()
await expect(ctx.getSessionUuid('sess-retry')).resolves.toMatch(/^[0-9a-f-]{36}$/)
})
})
describe('getEffectiveSessionUuid', () => {
it.each([
{ mcpConversationId: undefined, sessionId: 'sess-1', mcpSessionId: 'mcp-1', expectedKey: 'sess-1' },
{ mcpConversationId: undefined, sessionId: undefined, mcpSessionId: 'mcp-1', expectedKey: 'mcp-1' },
{ mcpConversationId: undefined, sessionId: undefined, mcpSessionId: undefined, expectedKey: undefined },
{ mcpConversationId: 'conv-1', sessionId: 'sess-1', mcpSessionId: 'mcp-1', expectedKey: 'conv-1' },
// MCP 2026-07-28 sends neither of the other two, so without the handle these events
// ship with no `$session_id`.
{ mcpConversationId: 'conv-1', sessionId: undefined, mcpSessionId: undefined, expectedKey: 'conv-1' },
])(
'conversationId=$mcpConversationId sessionId=$sessionId mcpSessionId=$mcpSessionId → resolves via expectedKey=$expectedKey',
async ({ mcpConversationId, sessionId, mcpSessionId, expectedKey }) => {
const ctx = new RequestContext(fakeRedis(), env, makeProps())
const effective = await ctx.getEffectiveSessionUuid({
mcpConversationId,
sessionId,
mcpSessionId,
} as any)
expect(effective).toBe(expectedKey ? await ctx.getSessionUuid(expectedKey) : undefined)
if (expectedKey) {
expect(effective).toMatch(/^[0-9a-f-]{36}$/)
}
}
)
})
describe('buildClientProperties', () => {
it('includes all request properties', () => {
const ctx = new RequestContext(
fakeRedis(),
env,
makeProps({
mcpClientName: 'claude-code',
mcpClientVersion: '2.0',
mcpProtocolVersion: '2025-03-26',
mcpConsumer: 'posthog-code',
transport: 'streamable-http',
})
)
const result = ctx.buildClientProperties()
expect(result).toMatchObject({
$ai_product: 'mcp',
$mcp_source: 'posthog_mcp_analytics',
$mcp_server_name: 'PostHog',
$mcp_server_version: '1.0.0',
$mcp_client_name: 'claude-code',
$mcp_client_version: '2.0',
$mcp_protocol_version: '2025-03-26',
$mcp_consumer: 'posthog-code',
$mcp_transport: 'streamable-http',
mcp_runtime: 'hono',
})
})
it('adds stable session properties without replacing request properties', () => {
const ctx = new RequestContext(
fakeRedis(),
env,
makeProps({
mcpClientName: 'Claude Desktop',
mcpClientVersion: '2.0',
mcpProtocolVersion: '2025-03-26',
mcpConsumer: 'request-consumer',
mcpVendorClient: 'ClaudeAI',
transport: 'streamable-http',
})
)
ctx.setMcpContexts(
{
authMethod: 'personal_api_key',
sessionId: 'sess-1',
mcpClientName: 'Claude Desktop',
mcpClientVersion: '2.0',
mcpProtocolVersion: '2025-03-26',
mcpConsumer: 'request-consumer',
mcpVendorClient: 'ClaudeAI',
transport: 'streamable-http',
mode: 'cli',
},
{
mcpClientName: 'claude-code',
mcpClientVersion: '1.0',
mcpProtocolVersion: '2025-03-26',
mcpConsumer: 'session-consumer',
mcpVendorClient: 'ClaudeCode',
}
)
const result = ctx.buildClientProperties()
expect(result).toMatchObject({
$mcp_client_name: 'Claude Desktop',
$mcp_client_version: '2.0',
$mcp_consumer: 'request-consumer',
$mcp_vendor_client: 'ClaudeAI',
mcp_session_client_name: 'claude-code',
mcp_session_client_version: '1.0',
mcp_session_consumer: 'session-consumer',
mcp_session_vendor_client: 'ClaudeCode',
})
})
it('omits undefined properties', () => {
const ctx = new RequestContext(
fakeRedis(),
env,
makeProps({
mcpClientName: undefined,
mcpClientVersion: undefined,
mcpProtocolVersion: undefined,
mcpConsumer: undefined,
transport: undefined,
})
)
const result = ctx.buildClientProperties()
expect(result).toMatchObject({
$ai_product: 'mcp',
$mcp_source: 'posthog_mcp_analytics',
$mcp_server_name: 'PostHog',
$mcp_server_version: '1.0.0',
mcp_runtime: 'hono',
})
expect(result.$mcp_client_name).toBeUndefined()
expect(result.$mcp_consumer).toBeUndefined()
expect(result.$mcp_transport).toBeUndefined()
})
})
describe('cache', () => {
it('throws when userHash is missing', () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps({ userHash: '' }))
expect(() => ctx.cache).toThrow('User hash is required')
})
it('returns the same cache instance on repeated access', () => {
const ctx = new RequestContext(fakeRedis(), env, makeProps())
expect(ctx.cache).toBe(ctx.cache)
})
it('keeps token cache entries on the default 7 day TTL', async () => {
const redis = spyRedis()
const ctx = new RequestContext(redis, env, makeProps())
await ctx.tokenCache.set('distinctId', 'user-123')
expect(redis.set).toHaveBeenCalledWith(
'mcp:token:test-user:distinctId',
JSON.stringify('user-123'),
'EX',
7 * 24 * 60 * 60
)
})
})
})