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.

35.0 KB
Raw Blame
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 })
        })
    })
})