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.

55.8 KB
Raw Blame
import { create } from '@bufbuild/protobuf'
import { Code, ConnectError, type ServiceImpl, createClient, createRouterTransport } from '@connectrpc/connect'
import { DateTime } from 'luxon'
import * as http2 from 'node:http2'

import { PersonHogService } from '~/common/generated/personhog/personhog/service/v1/service_pb'
import { ConsistencyLevel } from '~/common/generated/personhog/personhog/types/v1/common_pb'
import {
    GroupSchema,
    GroupTypeMappingSchema,
    GroupTypeMappingsByKeySchema,
} from '~/common/generated/personhog/personhog/types/v1/group_pb'
import type {
    GetGroupRequest,
    GetGroupTypeMappingsByProjectIdsRequest,
    GetGroupTypeMappingsByTeamIdsRequest,
    GetGroupsBatchRequest,
} from '~/common/generated/personhog/personhog/types/v1/group_pb'
import { PersonSchema } from '~/common/generated/personhog/personhog/types/v1/person_pb'
import type {
    GetPersonsByDistinctIdsRequest,
    GetPersonsByUuidsRequest,
} from '~/common/generated/personhog/personhog/types/v1/person_pb'

import {
    PersonHogClient,
    type PersonHogClientConfig,
    createPersonhogTransport,
    parseRolloutTeamIds,
    resolveConsistencyHeader,
    resolvePersonRoutingKey,
    shouldUseGrpcForTeam,
    shouldUseGrpcForTeamItems,
    shouldUseGrpcForTeams,
} from './client'

const textEncoder = new TextEncoder()

function jsonBytes(obj: unknown): Uint8Array {
    return textEncoder.encode(JSON.stringify(obj))
}

const CREATED_AT_MS = BigInt(DateTime.fromISO('2024-06-15T12:00:00.000Z', { zone: 'utc' }).toMillis())

function makeProtoGroup(
    overrides: Partial<{
        id: bigint
        teamId: bigint
        groupTypeIndex: number
        groupKey: string
        groupProperties: Uint8Array
        createdAt: bigint
        propertiesLastUpdatedAt: Uint8Array
        propertiesLastOperation: Uint8Array
        version: bigint
    }> = {}
) {
    return create(GroupSchema, {
        id: 42n,
        teamId: 1n,
        groupTypeIndex: 0,
        groupKey: 'acme-corp',
        groupProperties: jsonBytes({ name: 'Acme Corp', industry: 'tech' }),
        createdAt: CREATED_AT_MS,
        propertiesLastUpdatedAt: jsonBytes({ name: '2024-06-15T12:00:00Z' }),
        propertiesLastOperation: jsonBytes({ name: 'set' }),
        version: 3n,
        ...overrides,
    })
}

function makeProtoPerson(
    overrides: Partial<{
        id: bigint
        uuid: string
        teamId: bigint
        properties: Uint8Array
        propertiesLastUpdatedAt: Uint8Array
        propertiesLastOperation: Uint8Array
        createdAt: bigint
        version: bigint
        isIdentified: boolean
        isUserId: boolean
        lastSeenAt: bigint
    }> = {}
) {
    return create(PersonSchema, {
        id: 42n,
        uuid: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
        teamId: 1n,
        properties: jsonBytes({ name: 'Test User', email: '[email protected]' }),
        propertiesLastUpdatedAt: jsonBytes({ name: '2024-06-15T12:00:00Z' }),
        propertiesLastOperation: jsonBytes({ name: 'set' }),
        createdAt: CREATED_AT_MS,
        version: 3n,
        isIdentified: true,
        ...overrides,
    })
}

const SERVICE_DEFAULTS: ServiceImpl<typeof PersonHogService> = {
    getGroup: () => ({}),
    getGroups: () => ({ groups: [], missingGroups: [] }),
    getGroupsBatch: () => ({ results: [] }),
    listGroups: () => ({ groups: [], hasMore: false }),
    getGroupTypeMappingsByTeamId: () => ({ mappings: [] }),
    getGroupTypeMappingsByTeamIds: () => ({ results: [] }),
    getGroupTypeMappingsByProjectId: () => ({ mappings: [] }),
    getGroupTypeMappingsByProjectIds: () => ({ results: [] }),
    getGroupTypeMappingByDashboardId: () => ({}),
    countGroupTypeMappings: () => ({ counts: [] }),
    createGroup: () => ({}),
    updateGroup: () => ({ updated: false }),
    deleteGroupsBatchForTeam: () => ({ deletedCount: 0n }),
    updateGroupTypeMapping: () => ({}),
    deleteGroupTypeMapping: () => ({ deleted: false }),
    deleteGroupTypeMappingsBatchForTeam: () => ({ deletedCount: 0n }),
    getPerson: () => ({}),
    getPersons: () => ({ persons: [] }),
    getPersonByUuid: () => ({}),
    getPersonsByUuids: () => ({ persons: [] }),
    getPersonByDistinctId: () => ({}),
    getPersonsByDistinctIdsInTeam: () => ({ results: [] }),
    getPersonsByDistinctIds: () => ({ results: [] }),
    getDistinctIdsForPerson: () => ({ distinctIds: [] }),
    getDistinctIdsForPersons: () => ({ personDistinctIds: [] }),
    getHashKeyOverrideContext: () => ({ results: [] }),
    upsertHashKeyOverrides: () => ({}),
    deleteHashKeyOverridesByTeams: () => ({}),
    checkCohortMembership: () => ({ memberships: [] }),
    countCohortMembers: () => ({ count: 0n }),
    deleteCohortMember: () => ({ deleted: false }),
    deleteCohortMembersBulk: () => ({ deletedCount: 0n }),
    insertCohortMembers: () => ({ insertedCount: 0n }),
    listCohortMemberIds: () => ({ personIds: [], nextCursor: 0n }),
    updatePersonProperties: () => ({}),
    deletePersons: () => ({ deletedCount: 0n }),
    deletePersonsBatchForTeam: () => ({ deletedCount: 0n }),
    deleteTombstonedPersons: () => ({
        deletedCount: 0n,
        skippedLiveCount: 0n,
        blockedPersonUuids: [],
        pendingPersonUuids: [],
        rowsDeleted: 0n,
    }),
    getPersonTombstones: () => ({ tombstones: [] }),
    ackPersonTombstones: () => ({ clearedCount: 0n }),
    listPersonTombstoneQueue: () => ({ entries: [] }),
    splitPerson: () => ({ splits: [] }),
    setPersonDistinctIdVersionFloor: () => ({}),
    setPersonVersionFloor: () => ({ updated: false }),
    ensurePersonVersionFloors: () => ({ results: [] }),
    getDistinctIdRows: () => ({ rows: [] }),
    listPersonsForTeam: () => ({ persons: [] }),
    raisePersonVersionFloors: () => ({ results: [] }),
    restorePersons: () => ({ results: [] }),
    writeDistinctIds: () => ({ results: [] }),
    fencePerson: () => ({}),
    fencePersons: () => ({}),
    releaseFence: () => ({}),
    releaseFences: () => ({}),
    foldPersonDocument: () => ({}),
    raisePersonVersion: () => ({ raised: false }),
}

function createMockClient(overrides: Partial<ServiceImpl<typeof PersonHogService>> = {}): PersonHogClient {
    const transport = createRouterTransport(({ service }) => {
        service(PersonHogService, {
            ...SERVICE_DEFAULTS,
            ...overrides,
        })
    })
    return PersonHogClient.fromTransport(transport)
}

describe('parseRolloutTeamIds', () => {
    it('returns empty set for empty string', () => {
        expect(parseRolloutTeamIds('')).toEqual(new Set())
    })

    it('returns empty set for whitespace-only string', () => {
        expect(parseRolloutTeamIds('   ')).toEqual(new Set())
    })

    it('parses comma-separated team IDs', () => {
        expect(parseRolloutTeamIds('1,2,3')).toEqual(new Set([1, 2, 3]))
    })

    it('handles whitespace around IDs', () => {
        expect(parseRolloutTeamIds(' 1 , 2 , 3 ')).toEqual(new Set([1, 2, 3]))
    })

    it('ignores non-numeric values', () => {
        expect(parseRolloutTeamIds('1,abc,3')).toEqual(new Set([1, 3]))
    })

    it('deduplicates IDs', () => {
        expect(parseRolloutTeamIds('1,1,2')).toEqual(new Set([1, 2]))
    })
})

describe('shouldUseGrpcForTeam', () => {
    it('returns true when team ID is in rollout set', () => {
        expect(shouldUseGrpcForTeam(new Set([1, 2, 3]), 2, 0)).toBe(true)
    })

    it('returns false when team ID is not in rollout set', () => {
        expect(shouldUseGrpcForTeam(new Set([1, 2, 3]), 99, 100)).toBe(false)
    })

    it('ignores percentage when rollout team IDs are set', () => {
        expect(shouldUseGrpcForTeam(new Set([1]), 99, 100)).toBe(false)
    })

    it('falls back to percentage when rollout set is empty', () => {
        // 100% should always return true
        expect(shouldUseGrpcForTeam(new Set(), 1, 100)).toBe(true)
    })

    it('falls back to percentage 0 when rollout set is empty', () => {
        expect(shouldUseGrpcForTeam(new Set(), 1, 0)).toBe(false)
    })
})

describe('shouldUseGrpcForTeams', () => {
    it('returns true when all team IDs are in rollout set', () => {
        expect(shouldUseGrpcForTeams(new Set([1, 5, 10]), [1, 5, 10], 0)).toBe(true)
    })

    it('returns false when only some team IDs are in rollout set', () => {
        expect(shouldUseGrpcForTeams(new Set([5]), [1, 5, 10], 100)).toBe(false)
    })

    it('returns false when no team IDs are in rollout set', () => {
        expect(shouldUseGrpcForTeams(new Set([99]), [1, 5, 10], 100)).toBe(false)
    })

    it('falls back to percentage when rollout set is empty', () => {
        expect(shouldUseGrpcForTeams(new Set(), [1], 100)).toBe(true)
    })

    it('returns false for empty team IDs array when rollout set is non-empty', () => {
        expect(shouldUseGrpcForTeams(new Set([1]), [], 100)).toBe(false)
    })
})

describe('shouldUseGrpcForTeamItems', () => {
    it('returns true when all items have team IDs in rollout set', () => {
        expect(shouldUseGrpcForTeamItems(new Set([1, 5]), [{ teamId: 1 }, { teamId: 5 }, { teamId: 1 }], 0)).toBe(true)
    })

    it('returns false when any item has a team ID not in rollout set', () => {
        expect(shouldUseGrpcForTeamItems(new Set([1]), [{ teamId: 1 }, { teamId: 99 }], 100)).toBe(false)
    })

    it('returns false for empty items when rollout set is non-empty', () => {
        expect(shouldUseGrpcForTeamItems(new Set([1]), [], 100)).toBe(false)
    })

    it('falls back to percentage when rollout set is empty', () => {
        expect(shouldUseGrpcForTeamItems(new Set(), [{ teamId: 1 }], 100)).toBe(true)
    })
})

describe('resolveConsistencyHeader', () => {
    it('returns "strong" when readOptions.consistency is STRONG', () => {
        expect(resolveConsistencyHeader({ readOptions: { consistency: ConsistencyLevel.STRONG } })).toBe('strong')
    })

    it('returns "eventual" when readOptions.consistency is EVENTUAL', () => {
        expect(resolveConsistencyHeader({ readOptions: { consistency: ConsistencyLevel.EVENTUAL } })).toBe('eventual')
    })

    it('returns "eventual" when readOptions is missing', () => {
        expect(resolveConsistencyHeader({})).toBe('eventual')
    })

    it('returns "eventual" when message is undefined', () => {
        expect(resolveConsistencyHeader(undefined)).toBe('eventual')
    })

    it('returns "eventual" when consistency is unset (0)', () => {
        expect(resolveConsistencyHeader({ readOptions: { consistency: 0 } })).toBe('eventual')
    })
})

describe('resolvePersonRoutingKey', () => {
    const routingKey = { teamId: 7n, personId: 42n }

    it.each([
        ['UpdatePersonProperties', ConsistencyLevel.UNSPECIFIED],
        ['FencePerson', ConsistencyLevel.UNSPECIFIED],
        ['ReleaseFence', ConsistencyLevel.UNSPECIFIED],
        ['FoldPersonDocument', ConsistencyLevel.UNSPECIFIED],
        ['GetPerson', ConsistencyLevel.STRONG],
    ])('returns the key for leader-bound %s', (method, consistency) => {
        expect(resolvePersonRoutingKey(method, { ...routingKey, readOptions: { consistency } })).toEqual(routingKey)
    })

    it.each([
        ['GetPerson', ConsistencyLevel.EVENTUAL],
        ['GetPersons', ConsistencyLevel.STRONG],
        ['GetPersonsByDistinctIds', ConsistencyLevel.UNSPECIFIED],
    ])('returns null for replica-bound %s', (method, consistency) => {
        expect(resolvePersonRoutingKey(method, { ...routingKey, readOptions: { consistency } })).toBeNull()
    })
})

describe('PersonHogClient', () => {
    describe('groups', () => {
        describe('fetchGroup', () => {
            it('converts proto group to domain group', async () => {
                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup() }),
                })

                const result = await client.groups.fetchGroup(1, 0, 'acme-corp')

                expect(result).toEqual({
                    id: 42,
                    team_id: 1,
                    group_type_index: 0,
                    group_key: 'acme-corp',
                    group_properties: { name: 'Acme Corp', industry: 'tech' },
                    properties_last_updated_at: { name: '2024-06-15T12:00:00Z' },
                    properties_last_operation: { name: 'set' },
                    created_at: DateTime.fromISO('2024-06-15T12:00:00.000Z', { zone: 'utc' }),
                    version: 3,
                })
            })

            it('returns undefined when group is not found', async () => {
                const client = createMockClient({
                    getGroup: () => ({}),
                })

                const result = await client.groups.fetchGroup(1, 0, 'nonexistent')

                expect(result).toBeUndefined()
            })

            it('handles empty JSON bytes as empty objects', async () => {
                const client = createMockClient({
                    getGroup: () => ({
                        group: makeProtoGroup({
                            groupProperties: new Uint8Array(0),
                            propertiesLastUpdatedAt: new Uint8Array(0),
                            propertiesLastOperation: new Uint8Array(0),
                        }),
                    }),
                })

                const result = await client.groups.fetchGroup(1, 0, 'empty-props')

                expect(result).toMatchObject({
                    group_properties: {},
                    properties_last_updated_at: {},
                    properties_last_operation: {},
                })
            })

            it('converts bigint fields to numbers', async () => {
                const client = createMockClient({
                    getGroup: () => ({
                        group: makeProtoGroup({ id: 999n, teamId: 77n, version: 15n }),
                    }),
                })

                const result = await client.groups.fetchGroup(77, 0, 'acme-corp')

                expect(result).toMatchObject({
                    id: 999,
                    team_id: 77,
                    version: 15,
                })
            })

            it('propagates gRPC errors', async () => {
                const client = createMockClient({
                    getGroup: () => {
                        throw new ConnectError('service unavailable', Code.Unavailable)
                    },
                })

                await expect(client.groups.fetchGroup(1, 0, 'key')).rejects.toThrow(ConnectError)
            })
        })

        describe('fetchGroupsByKeys', () => {
            it('converts batch proto response to domain objects', async () => {
                const client = createMockClient({
                    getGroupsBatch: () => ({
                        results: [
                            {
                                key: { teamId: 1n, groupTypeIndex: 0, groupKey: 'acme' },
                                group: makeProtoGroup({ groupProperties: jsonBytes({ name: 'Acme' }) }),
                            },
                            {
                                key: { teamId: 2n, groupTypeIndex: 1, groupKey: 'globex' },
                                group: makeProtoGroup({ groupProperties: jsonBytes({ name: 'Globex' }) }),
                            },
                        ],
                    }),
                })

                const result = await client.groups.fetchGroupsByKeys([1, 2], [0, 1], ['acme', 'globex'])

                expect(result).toEqual([
                    {
                        team_id: 1,
                        group_type_index: 0,
                        group_key: 'acme',
                        group_properties: { name: 'Acme' },
                        created_at: DateTime.fromMillis(Number(CREATED_AT_MS), { zone: 'utc' }),
                        version: 3,
                    },
                    {
                        team_id: 2,
                        group_type_index: 1,
                        group_key: 'globex',
                        group_properties: { name: 'Globex' },
                        created_at: DateTime.fromMillis(Number(CREATED_AT_MS), { zone: 'utc' }),
                        version: 3,
                    },
                ])
            })

            it('skips results with missing group (not found)', async () => {
                const client = createMockClient({
                    getGroupsBatch: () => ({
                        results: [
                            {
                                key: { teamId: 1n, groupTypeIndex: 0, groupKey: 'found' },
                                group: makeProtoGroup({ groupProperties: jsonBytes({ x: 1 }) }),
                            },
                            {
                                key: { teamId: 1n, groupTypeIndex: 1, groupKey: 'missing' },
                                // no group — server didn't find this one
                            },
                        ],
                    }),
                })

                const result = await client.groups.fetchGroupsByKeys([1, 1], [0, 1], ['found', 'missing'])

                expect(result).toEqual([
                    {
                        team_id: 1,
                        group_type_index: 0,
                        group_key: 'found',
                        group_properties: { x: 1 },
                        created_at: DateTime.fromMillis(Number(CREATED_AT_MS), { zone: 'utc' }),
                        version: 3,
                    },
                ])
            })

            it('returns empty array for empty input without calling gRPC', async () => {
                const handler = jest.fn()
                const client = createMockClient({ getGroupsBatch: handler })

                const result = await client.groups.fetchGroupsByKeys([], [], [])

                expect(result).toEqual([])
                expect(handler).not.toHaveBeenCalled()
            })

            it('chunks large batches into multiple gRPC calls', async () => {
                let callCount = 0
                const batchSizes: number[] = []

                const client = createMockClient({
                    getGroupsBatch: (req) => {
                        callCount++
                        batchSizes.push(req.keys.length)
                        return {
                            results: req.keys.map((key) => ({
                                key,
                                group: makeProtoGroup({ groupProperties: jsonBytes({ chunked: true }) }),
                            })),
                        }
                    },
                })

                // 300 items should produce 3 chunks: 100 + 100 + 100
                const count = 300
                const teamIds = Array.from({ length: count }, (_, i) => i + 1)
                const groupTypeIndexes = Array.from({ length: count }, () => 0)
                const groupKeys = Array.from({ length: count }, (_, i) => `key-${i}`)

                const result = await client.groups.fetchGroupsByKeys(teamIds, groupTypeIndexes, groupKeys)

                expect(callCount).toBe(3)
                expect(batchSizes).toEqual([100, 100, 100])
                expect(result).toHaveLength(300)
                expect(result.every((r) => r.group_properties.chunked === true)).toBe(true)
            })
        })

        describe('fetchGroupTypesByTeamIds', () => {
            it('converts proto mappings to domain format keyed by team ID', async () => {
                const client = createMockClient({
                    getGroupTypeMappingsByTeamIds: () => ({
                        results: [
                            create(GroupTypeMappingsByKeySchema, {
                                key: 1n,
                                mappings: [
                                    create(GroupTypeMappingSchema, { groupType: 'organization', groupTypeIndex: 0 }),
                                    create(GroupTypeMappingSchema, { groupType: 'project', groupTypeIndex: 1 }),
                                ],
                            }),
                            create(GroupTypeMappingsByKeySchema, {
                                key: 2n,
                                mappings: [create(GroupTypeMappingSchema, { groupType: 'company', groupTypeIndex: 0 })],
                            }),
                        ],
                    }),
                })

                const result = await client.groups.fetchGroupTypesByTeamIds([1, 2])

                expect(result).toEqual({
                    '1': [
                        { group_type: 'organization', group_type_index: 0 },
                        { group_type: 'project', group_type_index: 1 },
                    ],
                    '2': [{ group_type: 'company', group_type_index: 0 }],
                })
            })

            it('returns empty object for empty input without calling gRPC', async () => {
                const handler = jest.fn()
                const client = createMockClient({ getGroupTypeMappingsByTeamIds: handler })

                const result = await client.groups.fetchGroupTypesByTeamIds([])

                expect(result).toEqual({})
                expect(handler).not.toHaveBeenCalled()
            })

            it('returns empty object when server returns no results', async () => {
                const client = createMockClient({
                    getGroupTypeMappingsByTeamIds: () => ({ results: [] }),
                })

                const result = await client.groups.fetchGroupTypesByTeamIds([999])

                expect(result).toEqual({})
            })
        })

        describe('fetchGroupTypesByProjectIds', () => {
            it('converts proto mappings to domain format keyed by project ID', async () => {
                const client = createMockClient({
                    getGroupTypeMappingsByProjectIds: () => ({
                        results: [
                            create(GroupTypeMappingsByKeySchema, {
                                key: 100n,
                                mappings: [
                                    create(GroupTypeMappingSchema, { groupType: 'workspace', groupTypeIndex: 0 }),
                                ],
                            }),
                        ],
                    }),
                })

                const result = await client.groups.fetchGroupTypesByProjectIds([100])

                expect(result).toEqual({
                    '100': [{ group_type: 'workspace', group_type_index: 0 }],
                })
            })

            it('returns empty object for empty input without calling gRPC', async () => {
                const handler = jest.fn()
                const client = createMockClient({ getGroupTypeMappingsByProjectIds: handler })

                const result = await client.groups.fetchGroupTypesByProjectIds([])

                expect(result).toEqual({})
                expect(handler).not.toHaveBeenCalled()
            })
        })

        describe('empty result shape parity with Postgres', () => {
            it('fetchGroupTypesByTeamIds omits key for team with no mappings', async () => {
                const client = createMockClient({
                    getGroupTypeMappingsByTeamIds: () => ({
                        results: [
                            create(GroupTypeMappingsByKeySchema, {
                                key: 1n,
                                mappings: [
                                    create(GroupTypeMappingSchema, { groupType: 'organization', groupTypeIndex: 0 }),
                                ],
                            }),
                            // team 5 has no mappings — server does not include it
                        ],
                    }),
                })

                const result = await client.groups.fetchGroupTypesByTeamIds([1, 5])

                expect(result).toEqual({
                    '1': [{ group_type: 'organization', group_type_index: 0 }],
                })
                expect(result['5']).toBeUndefined()
                // Postgres would return { "1": [...], "5": [] }
                // Downstream code uses result[teamId] ?? [] to handle this
            })

            it('fetchGroupTypesByProjectIds omits key for project with no mappings', async () => {
                const client = createMockClient({
                    getGroupTypeMappingsByProjectIds: () => ({
                        results: [
                            create(GroupTypeMappingsByKeySchema, {
                                key: 100n,
                                mappings: [
                                    create(GroupTypeMappingSchema, { groupType: 'workspace', groupTypeIndex: 0 }),
                                ],
                            }),
                            // project 200 has no mappings — not included
                        ],
                    }),
                })

                const result = await client.groups.fetchGroupTypesByProjectIds([100, 200])

                expect(result).toEqual({
                    '100': [{ group_type: 'workspace', group_type_index: 0 }],
                })
                expect(result['200']).toBeUndefined()
            })
        })

        describe('request construction', () => {
            it('fetchGroup sends correct request with BigInt teamId and eventual consistency', async () => {
                let capturedRequest: GetGroupRequest | undefined
                const client = createMockClient({
                    getGroup: (req) => {
                        capturedRequest = req
                        return {}
                    },
                })

                await client.groups.fetchGroup(42, 2, 'my-group')

                expect(capturedRequest!.teamId).toBe(42n)
                expect(capturedRequest!.groupTypeIndex).toBe(2)
                expect(capturedRequest!.groupKey).toBe('my-group')
                expect(capturedRequest!.readOptions?.consistency).toBe(ConsistencyLevel.EVENTUAL)
            })

            it('fetchGroupsByKeys sends correct batch request with GroupKey protos', async () => {
                let capturedRequest: GetGroupsBatchRequest | undefined
                const client = createMockClient({
                    getGroupsBatch: (req) => {
                        capturedRequest = req
                        return { results: [] }
                    },
                })

                await client.groups.fetchGroupsByKeys([10, 20], [0, 3], ['key-a', 'key-b'])

                expect(capturedRequest!.keys).toHaveLength(2)
                expect(capturedRequest!.keys[0].teamId).toBe(10n)
                expect(capturedRequest!.keys[0].groupTypeIndex).toBe(0)
                expect(capturedRequest!.keys[0].groupKey).toBe('key-a')
                expect(capturedRequest!.keys[1].teamId).toBe(20n)
                expect(capturedRequest!.keys[1].groupTypeIndex).toBe(3)
                expect(capturedRequest!.keys[1].groupKey).toBe('key-b')
                expect(capturedRequest!.readOptions?.consistency).toBe(ConsistencyLevel.EVENTUAL)
            })

            it('fetchGroupTypesByTeamIds sends correct request with BigInt team IDs', async () => {
                let capturedRequest: GetGroupTypeMappingsByTeamIdsRequest | undefined
                const client = createMockClient({
                    getGroupTypeMappingsByTeamIds: (req) => {
                        capturedRequest = req
                        return { results: [] }
                    },
                })

                await client.groups.fetchGroupTypesByTeamIds([1, 2, 3])

                expect(capturedRequest!.teamIds).toEqual([1n, 2n, 3n])
                expect(capturedRequest!.readOptions?.consistency).toBe(ConsistencyLevel.EVENTUAL)
            })

            it('fetchGroupTypesByProjectIds sends correct request with BigInt project IDs', async () => {
                let capturedRequest: GetGroupTypeMappingsByProjectIdsRequest | undefined
                const client = createMockClient({
                    getGroupTypeMappingsByProjectIds: (req) => {
                        capturedRequest = req
                        return { results: [] }
                    },
                })

                await client.groups.fetchGroupTypesByProjectIds([100, 200])

                expect(capturedRequest!.projectIds).toEqual([100n, 200n])
                expect(capturedRequest!.readOptions?.consistency).toBe(ConsistencyLevel.EVENTUAL)
            })
        })

        describe('data conversion edge cases', () => {
            it('handles deeply nested JSON in group_properties', async () => {
                const nested = {
                    org: {
                        settings: {
                            billing: { plan: 'enterprise', addons: ['sso', 'audit-log'] },
                            limits: { users: 500, projects: 100 },
                        },
                    },
                    tags: ['b2b', 'saas'],
                    active: true,
                    score: 99.5,
                }
                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ groupProperties: jsonBytes(nested) }) }),
                })

                const result = await client.groups.fetchGroup(1, 0, 'nested')

                expect(result!.group_properties).toEqual(nested)
            })

            it('handles unicode and special characters in group keys and properties', async () => {
                const unicodeProps = {
                    name: '日本語テスト',
                    emoji: '🚀✨',
                    quotes: 'he said "hello"',
                    newlines: 'line1\nline2',
                    backslash: 'path\\to\\thing',
                }
                const client = createMockClient({
                    getGroup: () => ({
                        group: makeProtoGroup({
                            groupKey: 'grp-日本語-🚀',
                            groupProperties: jsonBytes(unicodeProps),
                        }),
                    }),
                })

                const result = await client.groups.fetchGroup(1, 0, 'grp-日本語-🚀')

                expect(result!.group_key).toBe('grp-日本語-🚀')
                expect(result!.group_properties).toEqual(unicodeProps)
            })

            it('handles large bigint IDs near Number.MAX_SAFE_INTEGER', async () => {
                const largeId = BigInt(Number.MAX_SAFE_INTEGER)
                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ id: largeId, version: largeId }) }),
                })

                const result = await client.groups.fetchGroup(1, 0, 'big-ids')

                expect(result!.id).toBe(Number.MAX_SAFE_INTEGER)
                expect(result!.version).toBe(Number.MAX_SAFE_INTEGER)
            })

            it('handles group_properties containing null values', async () => {
                const propsWithNulls = { name: 'Acme', website: null, count: 0, active: false }
                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ groupProperties: jsonBytes(propsWithNulls) }) }),
                })

                const result = await client.groups.fetchGroup(1, 0, 'nulls')

                expect(result!.group_properties).toEqual(propsWithNulls)
            })

            it('handles empty string group key', async () => {
                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ groupKey: '' }) }),
                })

                const result = await client.groups.fetchGroup(1, 0, '')

                expect(result!.group_key).toBe('')
            })
        })

        describe('timestamp conversion parity with Postgres', () => {
            function postgresPath(isoString: string): DateTime {
                return DateTime.fromISO(isoString).toUTC()
            }

            it('millisecond-precision timestamps produce identical DateTimes', async () => {
                const isoString = '2024-06-15T12:00:00.123Z'
                const epochMs = BigInt(DateTime.fromISO(isoString).toMillis())
                const fromPostgres = postgresPath(isoString)

                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ createdAt: epochMs }) }),
                })
                const result = await client.groups.fetchGroup(1, 0, 'test')

                expect(result!.created_at.toISO()).toBe(fromPostgres.toISO())
                expect(result!.created_at.toMillis()).toBe(fromPostgres.toMillis())
            })

            it('exact second boundary produces identical DateTimes', async () => {
                const isoString = '2024-01-01T00:00:00.000Z'
                const epochMs = BigInt(DateTime.fromISO(isoString).toMillis())

                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ createdAt: epochMs }) }),
                })
                const result = await client.groups.fetchGroup(1, 0, 'test')

                expect(result!.created_at.toISO()).toBe(isoString)
                expect(result!.created_at.toMillis()).toBe(1704067200000)
            })

            it('epoch zero produces valid DateTime', async () => {
                const client = createMockClient({
                    getGroup: () => ({ group: makeProtoGroup({ createdAt: 0n }) }),
                })
                const result = await client.groups.fetchGroup(1, 0, 'test')

                expect(result!.created_at.toMillis()).toBe(0)
                expect(result!.created_at.toISO()).toBe('1970-01-01T00:00:00.000Z')
            })
        })
    })

    describe('persons', () => {
        describe('fetchPersonsByDistinctIds', () => {
            it('converts proto person to domain person with distinct_id', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'user-123' },
                                person: makeProtoPerson(),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'user-123' }])

                expect(result).toEqual([
                    {
                        id: '42',
                        uuid: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
                        team_id: 1,
                        properties: { name: 'Test User', email: '[email protected]' },
                        properties_last_updated_at: { name: '2024-06-15T12:00:00Z' },
                        properties_last_operation: { name: 'set' },
                        created_at: DateTime.fromISO('2024-06-15T12:00:00.000Z', { zone: 'utc' }),
                        version: 3,
                        is_identified: true,
                        is_user_id: null,
                        last_seen_at: null,
                        distinct_id: 'user-123',
                    },
                ])
            })

            it('skips results with missing person (not found)', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'found' },
                                person: makeProtoPerson(),
                            },
                            {
                                key: { teamId: 1n, distinctId: 'missing' },
                                // no person
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([
                    { teamId: 1, distinctId: 'found' },
                    { teamId: 1, distinctId: 'missing' },
                ])

                expect(result).toHaveLength(1)
                expect(result[0].distinct_id).toBe('found')
            })

            it('returns empty array for empty input without calling gRPC', async () => {
                const handler = jest.fn()
                const client = createMockClient({ getPersonsByDistinctIds: handler })

                const result = await client.persons.fetchPersonsByDistinctIds([])

                expect(result).toEqual([])
                expect(handler).not.toHaveBeenCalled()
            })

            it('handles empty JSON bytes as defaults', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'user' },
                                person: makeProtoPerson({
                                    properties: new Uint8Array(0),
                                    propertiesLastUpdatedAt: new Uint8Array(0),
                                    propertiesLastOperation: new Uint8Array(0),
                                }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'user' }])

                expect(result[0].properties).toEqual({})
                expect(result[0].properties_last_updated_at).toEqual({})
                expect(result[0].properties_last_operation).toBeNull()
            })

            it('converts is_user_id correctly', async () => {
                const clientTrue = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ isUserId: true }),
                            },
                        ],
                    }),
                })
                const clientFalse = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ isUserId: false }),
                            },
                        ],
                    }),
                })

                const resultTrue = await clientTrue.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])
                const resultFalse = await clientFalse.persons.fetchPersonsByDistinctIds([
                    { teamId: 1, distinctId: 'u' },
                ])

                expect(resultTrue[0].is_user_id).toBe(1)
                expect(resultFalse[0].is_user_id).toBe(0)
            })

            it('converts last_seen_at when present', async () => {
                const lastSeenMs = BigInt(DateTime.fromISO('2024-12-25T10:30:00.000Z').toMillis())
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ lastSeenAt: lastSeenMs }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])

                expect(result[0].last_seen_at).toEqual(DateTime.fromISO('2024-12-25T10:30:00.000Z', { zone: 'utc' }))
            })

            it('propagates gRPC errors', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => {
                        throw new ConnectError('service unavailable', Code.Unavailable)
                    },
                })

                await expect(
                    client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])
                ).rejects.toThrow(ConnectError)
            })

            it('sends correct request with BigInt teamId and eventual consistency', async () => {
                let capturedRequest: GetPersonsByDistinctIdsRequest | undefined
                const client = createMockClient({
                    getPersonsByDistinctIds: (req) => {
                        capturedRequest = req
                        return { results: [] }
                    },
                })

                await client.persons.fetchPersonsByDistinctIds([
                    { teamId: 42, distinctId: 'user-a' },
                    { teamId: 99, distinctId: 'user-b' },
                ])

                expect(capturedRequest!.teamDistinctIds).toHaveLength(2)
                expect(capturedRequest!.teamDistinctIds[0].teamId).toBe(42n)
                expect(capturedRequest!.teamDistinctIds[0].distinctId).toBe('user-a')
                expect(capturedRequest!.teamDistinctIds[1].teamId).toBe(99n)
                expect(capturedRequest!.teamDistinctIds[1].distinctId).toBe('user-b')
                expect(capturedRequest!.readOptions?.consistency).toBe(ConsistencyLevel.EVENTUAL)
            })
        })

        describe('fetchPersonsByPersonIds', () => {
            it('converts proto persons to domain persons', async () => {
                const client = createMockClient({
                    getPersonsByUuids: () => ({
                        persons: [makeProtoPerson()],
                    }),
                })

                const result = await client.persons.fetchPersonsByPersonIds([
                    { teamId: 1, personId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' },
                ])

                expect(result).toEqual([
                    {
                        id: '42',
                        uuid: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
                        team_id: 1,
                        properties: { name: 'Test User', email: '[email protected]' },
                        properties_last_updated_at: { name: '2024-06-15T12:00:00Z' },
                        properties_last_operation: { name: 'set' },
                        created_at: DateTime.fromISO('2024-06-15T12:00:00.000Z', { zone: 'utc' }),
                        version: 3,
                        is_identified: true,
                        is_user_id: null,
                        last_seen_at: null,
                    },
                ])
            })

            it('returns empty array for empty input without calling gRPC', async () => {
                const handler = jest.fn()
                const client = createMockClient({ getPersonsByUuids: handler })

                const result = await client.persons.fetchPersonsByPersonIds([])

                expect(result).toEqual([])
                expect(handler).not.toHaveBeenCalled()
            })

            it('groups requests by team_id', async () => {
                const capturedRequests: GetPersonsByUuidsRequest[] = []
                const client = createMockClient({
                    getPersonsByUuids: (req) => {
                        capturedRequests.push(req)
                        return { persons: [] }
                    },
                })

                await client.persons.fetchPersonsByPersonIds([
                    { teamId: 1, personId: 'uuid-a' },
                    { teamId: 2, personId: 'uuid-b' },
                    { teamId: 1, personId: 'uuid-c' },
                ])

                expect(capturedRequests).toHaveLength(2)
                const team1Req = capturedRequests.find((r) => r.teamId === 1n)!
                const team2Req = capturedRequests.find((r) => r.teamId === 2n)!
                expect(team1Req.uuids).toEqual(['uuid-a', 'uuid-c'])
                expect(team2Req.uuids).toEqual(['uuid-b'])
            })

            it('sends correct request with BigInt teamId and eventual consistency', async () => {
                let capturedRequest: GetPersonsByUuidsRequest | undefined
                const client = createMockClient({
                    getPersonsByUuids: (req) => {
                        capturedRequest = req
                        return { persons: [] }
                    },
                })

                await client.persons.fetchPersonsByPersonIds([{ teamId: 42, personId: 'uuid-x' }])

                expect(capturedRequest!.teamId).toBe(42n)
                expect(capturedRequest!.uuids).toEqual(['uuid-x'])
                expect(capturedRequest!.readOptions?.consistency).toBe(ConsistencyLevel.EVENTUAL)
            })

            it('propagates gRPC errors', async () => {
                const client = createMockClient({
                    getPersonsByUuids: () => {
                        throw new ConnectError('timeout', Code.DeadlineExceeded)
                    },
                })

                await expect(
                    client.persons.fetchPersonsByPersonIds([{ teamId: 1, personId: 'uuid-a' }])
                ).rejects.toThrow(ConnectError)
            })
        })

        describe('data conversion edge cases', () => {
            it('handles deeply nested JSON in person properties', async () => {
                const nested = {
                    profile: {
                        settings: {
                            notifications: { email: true, push: false, sms: null },
                            theme: { mode: 'dark', colors: ['#000', '#fff'] },
                        },
                    },
                    tags: ['vip', 'beta'],
                    active: true,
                    score: 99.5,
                }
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'nested' },
                                person: makeProtoPerson({ properties: jsonBytes(nested) }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'nested' }])

                expect(result[0].properties).toEqual(nested)
            })

            it('handles unicode and special characters in properties', async () => {
                const unicodeProps = {
                    name: '日本語テスト',
                    emoji: '🚀✨',
                    quotes: 'he said "hello"',
                    newlines: 'line1\nline2',
                    backslash: 'path\\to\\thing',
                }
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'unicode' },
                                person: makeProtoPerson({ properties: jsonBytes(unicodeProps) }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'unicode' }])

                expect(result[0].properties).toEqual(unicodeProps)
            })

            it('handles large bigint IDs near Number.MAX_SAFE_INTEGER', async () => {
                const largeId = BigInt(Number.MAX_SAFE_INTEGER)
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'big' },
                                person: makeProtoPerson({ id: largeId, version: largeId }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'big' }])

                expect(result[0].id).toBe(String(Number.MAX_SAFE_INTEGER))
                expect(result[0].version).toBe(Number.MAX_SAFE_INTEGER)
            })

            it('handles properties containing null values', async () => {
                const propsWithNulls = { name: 'Alice', website: null, count: 0, active: false }
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'nulls' },
                                person: makeProtoPerson({ properties: jsonBytes(propsWithNulls) }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'nulls' }])

                expect(result[0].properties).toEqual(propsWithNulls)
            })

            it('person id is converted to string (not number)', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ id: 999n }),
                            },
                        ],
                    }),
                })

                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])

                expect(result[0].id).toBe('999')
                expect(typeof result[0].id).toBe('string')
            })
        })

        describe('timestamp conversion', () => {
            function postgresPath(isoString: string): DateTime {
                return DateTime.fromISO(isoString).toUTC()
            }

            it('millisecond-precision created_at produces identical DateTime', async () => {
                const isoString = '2024-06-15T12:00:00.123Z'
                const epochMs = BigInt(DateTime.fromISO(isoString).toMillis())
                const fromPostgres = postgresPath(isoString)

                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ createdAt: epochMs }),
                            },
                        ],
                    }),
                })
                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])

                expect(result[0].created_at.toISO()).toBe(fromPostgres.toISO())
                expect(result[0].created_at.toMillis()).toBe(fromPostgres.toMillis())
            })

            it('epoch zero created_at produces valid DateTime', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ createdAt: 0n }),
                            },
                        ],
                    }),
                })
                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])

                expect(result[0].created_at.toMillis()).toBe(0)
                expect(result[0].created_at.toISO()).toBe('1970-01-01T00:00:00.000Z')
            })

            it('millisecond-precision last_seen_at produces identical DateTime', async () => {
                const isoString = '2024-12-25T10:30:00.456Z'
                const epochMs = BigInt(DateTime.fromISO(isoString).toMillis())
                const fromPostgres = postgresPath(isoString)

                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson({ lastSeenAt: epochMs }),
                            },
                        ],
                    }),
                })
                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])

                expect(result[0].last_seen_at!.toISO()).toBe(fromPostgres.toISO())
                expect(result[0].last_seen_at!.toMillis()).toBe(fromPostgres.toMillis())
            })

            it('absent last_seen_at produces null', async () => {
                const client = createMockClient({
                    getPersonsByDistinctIds: () => ({
                        results: [
                            {
                                key: { teamId: 1n, distinctId: 'u' },
                                person: makeProtoPerson(),
                            },
                        ],
                    }),
                })
                const result = await client.persons.fetchPersonsByDistinctIds([{ teamId: 1, distinctId: 'u' }])

                expect(result[0].last_seen_at).toBeNull()
            })
        })
    })
})

describe('PersonHogClient HTTP/2 windows', () => {
    const NODE_DEFAULT_WINDOW = 65_535

    async function observeAdvertisedWindows(
        windows: Pick<PersonHogClientConfig, 'initialStreamWindowBytes' | 'initialConnectionWindowBytes'>,
        expectedConnection: number
    ): Promise<{ stream: number; connection: number }> {
        const server = http2.createServer()
        const sessions: http2.ServerHttp2Session[] = []
        let deadlineTimer: ReturnType<typeof setTimeout> | undefined
        const observed = new Promise<{ stream: number; connection: number }>((resolve, reject) => {
            deadlineTimer = setTimeout(() => reject(new Error('no stream reached the server')), 4_000)
            server.on('session', (session) => {
                sessions.push(session)
                session.on('stream', (stream) => {
                    stream.respond(
                        { ':status': 200, 'content-type': 'application/grpc', 'grpc-status': '12' },
                        { endStream: true }
                    )
                    const deadline = Date.now() + 2_000
                    const poll = (): void => {
                        if (session.state.remoteWindowSize === expectedConnection || Date.now() > deadline) {
                            resolve({
                                stream: session.remoteSettings.initialWindowSize ?? -1,
                                connection: session.state.remoteWindowSize ?? -1,
                            })
                        } else {
                            setImmediate(poll)
                        }
                    }
                    poll()
                })
                session.on('error', reject)
            })
        })
        await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
        const address = server.address() as { port: number }
        const { transport, stateMonitor } = createPersonhogTransport({
            addr: `127.0.0.1:${address.port}`,
            timeoutMs: 2_000,
            ...windows,
        })
        try {
            await createClient(PersonHogService, transport)
                .getPerson({ teamId: 1n, personId: 1n })
                .catch(() => undefined)
            return await observed
        } finally {
            clearTimeout(deadlineTimer)
            stateMonitor.close()
            for (const session of sessions) {
                session.destroy()
            }
            await new Promise<void>((resolve) => server.close(() => resolve()))
        }
    }

    it.each([
        ['defaults', {}, NODE_DEFAULT_WINDOW, NODE_DEFAULT_WINDOW],
        [
            'configured',
            { initialStreamWindowBytes: 4 * 1024 * 1024, initialConnectionWindowBytes: 8 * 1024 * 1024 },
            4 * 1024 * 1024,
            8 * 1024 * 1024,
        ],
    ])('advertises the %s windows to the server', async (_label, windows, stream, connection) => {
        await expect(observeAdvertisedWindows(windows, connection)).resolves.toEqual({ stream, connection })
    })
})