: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, beforeEach, describe, expect, it, vi } from 'vitest'
import { ApiClient } from '@/api/client'
import { MCP_CLIENT_IP_HEADERS, verifySignedClientIp } from '@/lib/client-ip-signature'
import { USER_AGENT, getUserAgent } from '@/lib/constants'
import { PostHogApiError, PostHogTransportError, ToolInputValidationError } from '@/lib/errors'
import { getToolByName } from '@/shared/test-utils'
import { GENERATED_TOOLS as PROXY_TOOLS } from '@/tools/generated/proxy-records'
import { GENERATED_TOOLS } from '@/tools/generated/skills'
import type { Context } from '@/tools/types'
describe('ApiClient', () => {
it('validates the resource path of a generated tool before fetching', async () => {
const send = vi.fn().mockResolvedValue(new Response('{}'))
vi.stubGlobal('fetch', send)
const client = new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' })
const context = { api: client, stateManager: { getOrgID: async () => 'example' } } as unknown as Context
const tool = getToolByName(PROXY_TOOLS, 'proxy-delete')
try {
await expect(tool.handler(context, tool.schema.parse({ id: '..' }))).rejects.toThrow(
ToolInputValidationError
)
expect(send).not.toHaveBeenCalled()
} finally {
vi.unstubAllGlobals()
}
})
it.each(['.', '..', '%2e', '.%2e', '%2e.', '%2e%2e', ''])(
'rejects invalid resource segment case %# before sending',
async (id) => {
const send = vi.fn().mockResolvedValue(new Response('{}'))
vi.stubGlobal('fetch', send)
const client = new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' })
try {
await expect(
client.request({ method: 'DELETE', path: `/api/organizations/example/proxy_records/${id}/` })
).rejects.toThrow(ToolInputValidationError)
expect(send).not.toHaveBeenCalled()
} finally {
vi.unstubAllGlobals()
}
}
)
it.each([200, 403, 500])('reads privacy only from the API response before handling status %s', async (status) => {
const shared = new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' })
const suppress = vi.fn()
const scoped = shared.withAnalyticsSuppression(suppress)
for (const header of [undefined, 'false', 'true']) {
vi.stubGlobal(
'fetch',
vi.fn(
async () =>
new Response(JSON.stringify({ detail: 'Synthetic response' }), {
status,
headers: header ? { 'X-PostHog-Suppress-Analytics': header } : {},
})
)
)
await scoped.request({ method: 'GET', path: '/api/projects/1/tasks/' }).catch(() => undefined)
}
expect(suppress).toHaveBeenCalledOnce()
expect(shared.config.onPrivateResponse).toBeUndefined()
vi.unstubAllGlobals()
})
it('should create ApiClient with required config', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'https://example.com',
})
expect(client).toBeInstanceOf(ApiClient)
})
it('should use custom baseUrl when provided', () => {
const customUrl = 'https://custom.example.com'
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: customUrl,
})
const baseUrl = (client as any).baseUrl
expect(baseUrl).toBe(customUrl)
})
describe('publicBaseUrl', () => {
it('defaults publicBaseUrl to baseUrl when not provided', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'http://posthog-web-django.posthog.svc.cluster.local:8000',
})
expect(client.publicBaseUrl).toBe('http://posthog-web-django.posthog.svc.cluster.local:8000')
})
it('uses publicBaseUrl override when provided', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'http://posthog-web-django.posthog.svc.cluster.local:8000',
publicBaseUrl: 'https://us.posthog.com',
})
expect(client.baseUrl).toBe('http://posthog-web-django.posthog.svc.cluster.local:8000')
expect(client.publicBaseUrl).toBe('https://us.posthog.com')
})
it('getProjectBaseUrl uses publicBaseUrl, not baseUrl', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'http://posthog-web-django.posthog.svc.cluster.local:8000',
publicBaseUrl: 'https://us.posthog.com',
})
expect(client.getProjectBaseUrl('42')).toBe('https://us.posthog.com/project/42')
})
it('getProjectBaseUrl returns publicBaseUrl alone for @current', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'http://posthog-web-django.posthog.svc.cluster.local:8000',
publicBaseUrl: 'https://us.posthog.com',
})
expect(client.getProjectBaseUrl('@current')).toBe('https://us.posthog.com')
})
it('getProjectBaseUrl falls back to baseUrl when publicBaseUrl is unset', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'https://eu.posthog.com',
})
expect(client.getProjectBaseUrl('7')).toBe('https://eu.posthog.com/project/7')
})
it('falls back to baseUrl when publicBaseUrl is an empty string', () => {
const client = new ApiClient({
apiToken: 'test-token',
baseUrl: 'https://eu.posthog.com',
publicBaseUrl: '',
})
expect(client.publicBaseUrl).toBe('https://eu.posthog.com')
expect(client.getProjectBaseUrl('7')).toBe('https://eu.posthog.com/project/7')
})
})
it('should send correct headers on fetch', async () => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
})
// Call the private fetch method
await (client as any).fetch('https://example.com/api/test', {
method: 'POST',
body: JSON.stringify({ key: 'value' }),
})
expect(mockFetch).toHaveBeenCalledOnce()
const [, options] = mockFetch.mock.calls[0]!
expect(options.headers).toEqual({
Authorization: 'Bearer test-token-123',
'Content-Type': 'application/json',
'User-Agent': USER_AGENT,
'X-PostHog-Client': 'mcp',
})
vi.unstubAllGlobals()
})
it('should send x-posthog-mcp-user-agent header when clientUserAgent is provided', async () => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
clientUserAgent: 'posthog/wizard 1.0.0',
})
await (client as any).fetch('https://example.com/api/test', {
method: 'POST',
body: JSON.stringify({ key: 'value' }),
})
expect(mockFetch).toHaveBeenCalledOnce()
const [, options] = mockFetch.mock.calls[0]!
expect(options.headers).toEqual({
Authorization: 'Bearer test-token-123',
'Content-Type': 'application/json',
'User-Agent': getUserAgent({ clientUserAgent: 'posthog/wizard 1.0.0' }),
'X-PostHog-Client': 'mcp',
'x-posthog-mcp-user-agent': 'posthog/wizard 1.0.0',
})
vi.unstubAllGlobals()
})
it('forwards mcpConsumer as x-posthog-mcp-consumer without altering User-Agent', async () => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
mcpConsumer: 'plugin',
mcpClientName: 'claude-code',
})
await (client as any).fetch('https://example.com/api/test', {
method: 'POST',
body: JSON.stringify({ key: 'value' }),
})
expect(mockFetch).toHaveBeenCalledOnce()
const [, options] = mockFetch.mock.calls[0]!
expect(options.headers).toEqual({
Authorization: 'Bearer test-token-123',
'Content-Type': 'application/json',
'User-Agent': USER_AGENT,
'X-PostHog-Client': 'mcp',
'x-posthog-mcp-client-name': 'claude-code',
'x-posthog-mcp-consumer': 'plugin',
})
vi.unstubAllGlobals()
})
it('forwards mcpConsumer alone when mcpClientName is missing', async () => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
mcpConsumer: 'slack',
})
await (client as any).fetch('https://example.com/api/test', { method: 'GET' })
const [, options] = mockFetch.mock.calls[0]!
expect(options.headers['User-Agent']).toBe(USER_AGENT)
expect(options.headers['x-posthog-mcp-consumer']).toBe('slack')
vi.unstubAllGlobals()
})
it('forwards the current task id to the PostHog API', async () => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
taskId: '019fcdb5-2e5b-7ab1-bdab-b77fafd3c96f',
})
await client.request({ method: 'GET', path: '/api/projects/1/tasks/task-1/comments/' })
const [, options] = mockFetch.mock.calls[0]!
expect(options.headers['X-PostHog-Task-Id']).toBe('019fcdb5-2e5b-7ab1-bdab-b77fafd3c96f')
vi.unstubAllGlobals()
})
it.each([
[
'forwards a stated intent',
'Repairing a tile that hit the query row limit',
'Repairing a tile that hit the query row limit',
],
['caps an overlong intent', 'i'.repeat(900), 'i'.repeat(500)],
['strips characters a header cannot carry', 'Fixing the 📈 tile\nfor the user', 'Fixing the tilefor the user'],
['omits an intent that is not a string', 42 as unknown as string, undefined],
['omits the header when the agent stated none', undefined, undefined],
] as const)('%s', async (_label, intent, expected) => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({ apiToken: 'test-token-123', baseUrl: 'https://example.com', intent })
await client.request({ method: 'GET', path: '/api/projects/1/dashboards/' })
const [, options] = mockFetch.mock.calls[0]!
expect(options.headers['x-posthog-intent']).toBe(expected)
vi.unstubAllGlobals()
})
it('sends an intent only from the copy that carries it, so concurrent calls cannot cross', async () => {
// A fresh Response per call: a body can only be read once.
const mockFetch = vi.fn().mockImplementation(async () => new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const shared = new ApiClient({ apiToken: 'test-token-123', baseUrl: 'https://example.com' })
await shared.withIntent('auditing the dashboard tiles').request({ method: 'GET', path: '/api/projects/1/' })
await shared.request({ method: 'GET', path: '/api/projects/1/' })
expect(mockFetch.mock.calls[0]![1].headers['x-posthog-intent']).toBe('auditing the dashboard tiles')
expect(mockFetch.mock.calls[1]![1].headers).not.toHaveProperty('x-posthog-intent')
expect(shared.config.intent).toBeUndefined()
vi.unstubAllGlobals()
})
it.each([
['an IP and a key', { clientIp: '203.0.113.7', clientIpSigningKeys: ['mcp-key', 'old-key'] }, '203.0.113.7'],
['an IP and no key', { clientIp: '203.0.113.7', clientIpSigningKeys: [] }, null],
['a key and no IP', { clientIpSigningKeys: ['mcp-key'] }, null],
] as const)('signs the end user IP for the activity log given %s', async (_label, extraConfig, expectedIp) => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
...extraConfig,
clientIpSigningKeys: [...extraConfig.clientIpSigningKeys],
})
await (client as any).fetch('https://example.com/api/test', { method: 'GET' })
const headers = mockFetch.mock.calls[0]![1].headers
expect(headers[MCP_CLIENT_IP_HEADERS.ip] ?? null).toBe(expectedIp)
if (expectedIp) {
const outcome = await verifySignedClientIp(
headers[MCP_CLIENT_IP_HEADERS.ip],
headers[MCP_CLIENT_IP_HEADERS.timestamp],
headers[MCP_CLIENT_IP_HEADERS.signature],
['mcp-key']
)
expect(outcome).toBe('valid')
}
vi.unstubAllGlobals()
})
it.each([
[
'both ids set',
{ mcpSessionId: 'abc123session', mcpConversationId: '01984ad9-bda4-7000-8000-abcdef012345' },
{
'x-posthog-mcp-session-id': 'abc123session',
'x-posthog-mcp-conversation-id': '01984ad9-bda4-7000-8000-abcdef012345',
},
],
['only session id set', { mcpSessionId: 'only-session' }, { 'x-posthog-mcp-session-id': 'only-session' }],
['neither id set', {}, {}],
] as const)('forwards mcp id headers — %s', async (_label, extraConfig, expectedHeaders) => {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({
apiToken: 'test-token-123',
baseUrl: 'https://example.com',
...extraConfig,
})
await (client as any).fetch('https://example.com/api/test', { method: 'GET' })
const [, options] = mockFetch.mock.calls[0]!
for (const [header, value] of Object.entries(expectedHeaders)) {
expect(options.headers[header]).toBe(value)
}
const absent = ['x-posthog-mcp-session-id', 'x-posthog-mcp-conversation-id'].filter(
(h) => !(h in expectedHeaders)
)
for (const header of absent) {
expect(options.headers).not.toHaveProperty(header)
}
vi.unstubAllGlobals()
})
describe('insights().get() — overrides forwarding', () => {
const variablesOverride =
'{"019d4838-1da4-0000-33c7-2561bf01f1c9":{"code_name":"eventname","variableId":"019d4838-1da4-0000-33c7-2561bf01f1c9","value":"signed_up"}}'
const filtersOverride = '{"date_from":"-7d"}'
function setupClient(): { client: ApiClient; mockFetch: ReturnType<typeof vi.fn> } {
const mockFetch = vi.fn()
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' })
return { client, mockFetch }
}
it('hits the retrieve endpoint with no query string when called by numeric id and no overrides', async () => {
const { client, mockFetch } = setupClient()
mockFetch.mockResolvedValueOnce(
new Response(JSON.stringify({ id: 42, short_id: 'abc12345' }), { status: 200 })
)
await client.insights({ projectId: '1' }).get({ insightId: '42' })
expect(mockFetch).toHaveBeenCalledTimes(1)
const [url] = mockFetch.mock.calls[0]!
expect(url).toBe('https://example.com/api/projects/1/insights/42/')
vi.unstubAllGlobals()
})
it('hits the retrieve endpoint with the override query string when called by numeric id with overrides', async () => {
const { client, mockFetch } = setupClient()
mockFetch.mockResolvedValueOnce(
new Response(JSON.stringify({ id: 42, short_id: 'abc12345' }), { status: 200 })
)
await client.insights({ projectId: '1' }).get({
insightId: '42',
variables_override: variablesOverride,
filters_override: filtersOverride,
})
expect(mockFetch).toHaveBeenCalledTimes(1)
const [url] = mockFetch.mock.calls[0]!
expect(url).toContain('https://example.com/api/projects/1/insights/42/?')
expect(url).toContain(`variables_override=${encodeURIComponent(variablesOverride)}`)
expect(url).toContain(`filters_override=${encodeURIComponent(filtersOverride)}`)
vi.unstubAllGlobals()
})
it('resolves short_id via the list endpoint in one hop when no overrides are provided', async () => {
const { client, mockFetch } = setupClient()
mockFetch.mockResolvedValueOnce(
new Response(JSON.stringify({ results: [{ id: 42, short_id: 'abc12345' }] }), { status: 200 })
)
const result = await client.insights({ projectId: '1' }).get({ insightId: 'abc12345' })
expect(mockFetch).toHaveBeenCalledTimes(1)
const [url] = mockFetch.mock.calls[0]!
expect(url).toContain('/api/projects/1/insights/?short_id=abc12345')
expect(result.success).toBe(true)
vi.unstubAllGlobals()
})
it('resolves short_id and applies overrides in a single list call', async () => {
const { client, mockFetch } = setupClient()
mockFetch.mockResolvedValueOnce(
new Response(JSON.stringify({ results: [{ id: 42, short_id: 'abc12345' }] }), { status: 200 })
)
await client.insights({ projectId: '1' }).get({
insightId: 'abc12345',
variables_override: variablesOverride,
})
// The list endpoint runs the same InsightSerializer.to_representation
// and applies overrides from query_params, so a single hop suffices.
expect(mockFetch).toHaveBeenCalledTimes(1)
const [url] = mockFetch.mock.calls[0]!
expect(url).toContain('/api/projects/1/insights/?')
expect(url).toContain('short_id=abc12345')
expect(url).toContain(`variables_override=${encodeURIComponent(variablesOverride)}`)
expect(url).not.toContain('filters_override')
vi.unstubAllGlobals()
})
it.each([
['a seven-digit number', 1234567, 'https://example.com/api/projects/1/insights/1234567/'],
['an eight-digit number', 12345678, 'https://example.com/api/projects/1/insights/12345678/'],
['a seven-digit numeric string', '1234567', 'https://example.com/api/projects/1/insights/1234567/'],
])('resolves %s through the retrieve endpoint only', async (_label, insightId, expectedUrl) => {
const { client, mockFetch } = setupClient()
mockFetch.mockResolvedValueOnce(
new Response(JSON.stringify({ id: 42, short_id: 'abc12345' }), { status: 200 })
)
const result = await client.insights({ projectId: '1' }).get({ insightId })
expect(mockFetch).toHaveBeenCalledTimes(1)
expect(mockFetch.mock.calls[0]![0]).toBe(expectedUrl)
expect(result.success).toBe(true)
vi.unstubAllGlobals()
})
it.each([
['an all-digit short_id', { results: [{ id: 42, short_id: '12345678' }] }, 1],
['a numeric id with no short_id match', { results: [] }, 2],
])('resolves an eight-digit numeric string that is %s', async (_label, listBody, expectedCalls) => {
const { client, mockFetch } = setupClient()
mockFetch
.mockResolvedValueOnce(new Response(JSON.stringify(listBody), { status: 200 }))
.mockResolvedValueOnce(
new Response(JSON.stringify({ id: 12345678, short_id: 'abc12345' }), { status: 200 })
)
const result = await client.insights({ projectId: '1' }).get({ insightId: '12345678' })
expect(mockFetch).toHaveBeenCalledTimes(expectedCalls)
expect(mockFetch.mock.calls[0]![0]).toContain('/api/projects/1/insights/?short_id=12345678')
if (expectedCalls === 2) {
expect(mockFetch.mock.calls[1]![0]).toBe('https://example.com/api/projects/1/insights/12345678/')
}
expect(result.success).toBe(true)
vi.unstubAllGlobals()
})
it('reports a missing alphanumeric short_id without a retrieve fallback', async () => {
const { client, mockFetch } = setupClient()
mockFetch.mockResolvedValueOnce(new Response(JSON.stringify({ results: [] }), { status: 200 }))
const result = await client.insights({ projectId: '1' }).get({ insightId: 'abc12345' })
expect(mockFetch).toHaveBeenCalledTimes(1)
expect(result.success).toBe(false)
const error = result.success ? undefined : result.error
expect(error).toBeInstanceOf(PostHogApiError)
expect((error as PostHogApiError).status).toBe(404)
vi.unstubAllGlobals()
})
})
describe('actors query paging', () => {
const retentionDrilldown = {
kind: 'InsightActorsQuery',
interval: 0,
source: { kind: 'RetentionQuery', retentionFilter: { period: 'Day', totalIntervals: 3 } },
}
function runActors(
method: 'retentionActors' | 'lifecycleActors',
query: Record<string, unknown>
): Promise<Record<string, any>> {
const mockFetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ results: [] }), { status: 200 }))
vi.stubGlobal('fetch', mockFetch)
const client = new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' })
return client
.query({ projectId: '1' })
[method]({ query })
.then(() => {
const [, options] = mockFetch.mock.calls[0]!
vi.unstubAllGlobals()
return JSON.parse(options.body).query
})
}
function runWithPage(page: Record<string, number>): Promise<Record<string, any>> {
return runActors('retentionActors', { ...retentionDrilldown, ...page })
}
it('pages on the outer ActorsQuery and keeps the drilldown source clean', async () => {
// The inner InsightActorsQuery rejects unknown keys, so leaking `limit`/`offset` into it
// turns every paged call into a 400.
const query = await runWithPage({ limit: 250, offset: 500 })
expect(query.kind).toBe('ActorsQuery')
expect(query.limit).toBe(250)
expect(query.offset).toBe(500)
expect(query.source).not.toHaveProperty('limit')
expect(query.source).not.toHaveProperty('offset')
expect(query.source.interval).toBe(0)
})
it.each([
['defaults to the first page', {}, 100, 0],
['clamps a limit above the maximum', { limit: 5000 }, 1000, 0],
['raises a limit below one', { limit: 0 }, 1, 0],
['floors a negative offset', { limit: 20, offset: -10 }, 20, 0],
])('%s', async (_name, page, expectedLimit, expectedOffset) => {
const query = await runWithPage(page)
expect(query.limit).toBe(expectedLimit)
expect(query.offset).toBe(expectedOffset)
})
it('omits orderBy on unranked actor lists so pages stay disjoint', async () => {
// Lifecycle has nothing to rank by. Sending `orderBy: []` suppresses the runner's
// default ordering, and unordered rows make consecutive pages overlap.
const query = await runActors('lifecycleActors', {
kind: 'InsightActorsQuery',
day: '2024-01-15',
status: 'returning',
source: { kind: 'LifecycleQuery', series: [{ kind: 'EventsNode', event: '$pageview' }] },
})
expect(query).not.toHaveProperty('orderBy')
})
})
// A scout reads its required skill pages before it can start, so a dropped
// connection on one of those reads costs the whole run a manual repeat.
// Safe methods apply nothing upstream, so the client repeats them itself.
describe('transient transport failures', () => {
const networkError = (): Error => new TypeError('fetch failed')
const stubFetch = (...outcomes: (Response | Error)[]): ReturnType<typeof vi.fn> => {
const mockFetch = vi.fn()
for (const outcome of outcomes) {
if (outcome instanceof Error) {
mockFetch.mockRejectedValueOnce(outcome)
} else {
mockFetch.mockResolvedValueOnce(outcome)
}
}
mockFetch.mockImplementation(() => Promise.reject(networkError()))
vi.stubGlobal('fetch', mockFetch)
return mockFetch
}
const skillContext = (): Context =>
({
api: new ApiClient({ apiToken: 'phx_test', baseUrl: 'https://us.posthog.com' }),
stateManager: { getProjectId: vi.fn().mockResolvedValue('17') },
}) as unknown as Context
/** Drains the backoff sleeps, then returns the value or the thrown error. */
const settle = async (promise: Promise<unknown>): Promise<unknown> => {
const outcome = promise.then(
(value) => value,
(error) => error
)
await vi.runAllTimersAsync()
return outcome
}
const runTool = (name: string, params: Record<string, unknown>): Promise<unknown> =>
settle(getToolByName(GENERATED_TOOLS, name).handler(skillContext(), params))
beforeEach(() => {
vi.useFakeTimers()
vi.spyOn(console, 'warn').mockImplementation(() => {})
vi.spyOn(console, 'error').mockImplementation(() => {})
})
afterEach(() => {
vi.useRealTimers()
vi.restoreAllMocks()
vi.unstubAllGlobals()
})
it('retries a paginated skill-get page that fails to connect', async () => {
const mockFetch = stubFetch(
networkError(),
new Response(JSON.stringify({ name: 'skills-store', body: 'page two' }), { status: 200 })
)
const result = await runTool('skill-get', {
skill_name: 'skills-store',
body_offset: 20000,
body_length: 20000,
})
expect(result).toEqual({ name: 'skills-store', body: 'page two' })
expect(mockFetch).toHaveBeenCalledTimes(2)
const [retriedUrl] = mockFetch.mock.calls[1]!
expect(retriedUrl).toContain('/llm_skills/name/skills-store/')
expect(retriedUrl).toContain('body_offset=20000')
})
it('retries a skill-file-get read whose body stream is cut short', async () => {
const truncated = new Response('{}', { status: 200 })
vi.spyOn(truncated, 'text').mockRejectedValue(new TypeError('Network connection lost'))
const mockFetch = stubFetch(
truncated,
new Response(JSON.stringify({ path: 'references/limits.md' }), { status: 200 })
)
const result = await runTool('skill-file-get', {
skill_name: 'skills-store',
file_path: 'references/limits.md',
})
expect(result).toEqual({ path: 'references/limits.md' })
expect(mockFetch).toHaveBeenCalledTimes(2)
})
it('reports a retryable failure once the retry budget is spent', async () => {
const mockFetch = stubFetch()
const error = await settle(
getToolByName(GENERATED_TOOLS, 'skill-file-get').handler(skillContext(), {
skill_name: 'skills-store',
file_path: 'SKILL.md',
})
)
expect(error).toBeInstanceOf(PostHogTransportError)
const transportError = error as PostHogTransportError
expect(transportError.retryable).toBe(true)
expect(transportError.attempts).toBe(3)
expect(transportError.message).toContain('safe to retry')
expect(mockFetch).toHaveBeenCalledTimes(3)
})
it('retries a token introspection that fails to connect', async () => {
const mockFetch = stubFetch(
networkError(),
new Response(JSON.stringify({ active: true, scope: 'query:read' }), { status: 200 })
)
const client = new ApiClient({ apiToken: 'pha_test', baseUrl: 'https://us.posthog.com' })
const result = await settle(client.oauth().introspect({ token: 'pha_test' }))
expect(result).toEqual({ success: true, data: { active: true, scope: 'query:read' } })
expect(mockFetch).toHaveBeenCalledTimes(2)
expect(mockFetch.mock.calls[1]![1]).toMatchObject({ method: 'POST' })
})
it('does not repeat a write whose outcome is unknown', async () => {
const mockFetch = stubFetch()
const client = new ApiClient({ apiToken: 'phx_test', baseUrl: 'https://us.posthog.com' })
const error = await settle(client.request({ method: 'POST', path: '/api/projects/17/llm_skills/' }))
expect(error).toBeInstanceOf(PostHogTransportError)
// The write may have reached the handler before the connection died,
// so telling the agent to send it again invites a double apply.
expect((error as PostHogTransportError).retryable).toBe(false)
expect((error as PostHogTransportError).message).toContain('may have been applied upstream')
expect(mockFetch).toHaveBeenCalledTimes(1)
})
const stubStalledFetch = (): ReturnType<typeof vi.fn> => {
const mockFetch = vi.fn(
(_url: string, init?: RequestInit) =>
new Promise<Response>((_resolve, reject) => {
init?.signal?.addEventListener('abort', () => reject(init.signal!.reason))
})
)
vi.stubGlobal('fetch', mockFetch)
return mockFetch
}
it.each([
{ method: 'GET' as const, retryable: true, advice: 'safe to retry' },
{ method: 'POST' as const, retryable: false, advice: 'may have been applied upstream' },
])('ends a $method request that never answers', async ({ method, retryable, advice }) => {
const mockFetch = stubStalledFetch()
const client = new ApiClient({ apiToken: 'phx_test', baseUrl: 'https://us.posthog.com' })
const error = await settle(client.request({ method, path: '/api/projects/17/signals/scout/notes/' }))
expect(error).toBeInstanceOf(PostHogTransportError)
expect(error).toMatchObject({ retryable, timedOut: true, attempts: 1 })
expect((error as PostHogTransportError).message).toContain(advice)
expect(mockFetch).toHaveBeenCalledTimes(1)
})
it.each([
{
name: 'event definition',
lookup: { id: 'event-id', name: 'test_event' },
update: (client: ApiClient) =>
client.projects().updateEventDefinition({
projectId: '17',
eventName: 'test_event',
data: { description: 'Test' },
}),
},
{
name: 'property definition',
lookup: { results: [{ id: 'property-id', name: 'test_property' }] },
update: (client: ApiClient) =>
client.projects().updatePropertyDefinition({
projectId: '17',
propertyName: 'test_property',
data: { description: 'Test' },
}),
},
])('ends a $name update that never answers', async ({ lookup, update }) => {
const mockFetch = stubStalledFetch()
mockFetch.mockResolvedValueOnce(new Response(JSON.stringify(lookup), { status: 200 }))
const client = new ApiClient({ apiToken: 'phx_test', baseUrl: 'https://us.posthog.com' })
const result = await settle(update(client))
expect(result).toMatchObject({ success: false })
const error = (result as { error: unknown }).error
expect(error).toBeInstanceOf(PostHogTransportError)
expect(error).toMatchObject({ method: 'PATCH', retryable: false, timedOut: true })
expect(mockFetch).toHaveBeenCalledTimes(2)
})
it.each(['/api/environments/17/query/', '/api/environments/17/mcp_tools/execute_sql/'])(
'gives a query request to %s more time than the default deadline',
async (path) => {
stubStalledFetch()
const client = new ApiClient({ apiToken: 'phx_test', baseUrl: 'https://us.posthog.com' })
let settled = false
const pending = client
.request({ method: 'POST', path })
.finally(() => {
settled = true
})
.catch((error) => error)
await vi.advanceTimersByTimeAsync(5 * 60 * 1000)
expect(settled).toBe(false)
await vi.runAllTimersAsync()
expect(await pending).toMatchObject({ timedOut: true })
}
)
it('ends a request at its own shorter deadline', async () => {
stubStalledFetch()
const client = new ApiClient({ apiToken: 'phx_test', baseUrl: 'https://us.posthog.com' })
const pending = client
.request({ method: 'GET', path: '/api/projects/17/integrations/', timeoutMs: 10 * 1000 })
.catch((error) => error)
await vi.advanceTimersByTimeAsync(10 * 1000)
expect(await pending).toMatchObject({ timedOut: true })
})
})
})