@posthog/core 1.1.0 → 1.2.1

package/src/__tests__/featureFlagUtils.spec.ts

@@ -0,0 +1,427 @@
+import {
+  getFlagValuesFromFlags,
+  getPayloadsFromFlags,
+  getFlagDetailsFromFlagsAndPayloads,
+  getFeatureFlagValue,
+  normalizeFlagsResponse,
+} from '@/featureFlagUtils'
+import { PostHogFlagsResponse, FeatureFlagDetail } from '@/types'
+
+describe('featureFlagUtils', () => {
+  describe('getFeatureFlagValue', () => {
+    it('should return variant if present', () => {
+      const flag: FeatureFlagDetail = {
+        key: 'test-flag',
+        enabled: true,
+        variant: 'test-variant',
+        reason: undefined,
+        metadata: { id: 1, version: undefined, description: undefined, payload: undefined },
+      }
+      expect(getFeatureFlagValue(flag)).toBe('test-variant')
+    })
+
+    it('should return enabled if no variant', () => {
+      const flag1: FeatureFlagDetail = {
+        key: 'test-flag-1',
+        enabled: true,
+        variant: undefined,
+        reason: undefined,
+        metadata: { id: 1, version: undefined, description: undefined, payload: undefined },
+      }
+      const flag2: FeatureFlagDetail = {
+        key: 'test-flag-2',
+        enabled: false,
+        variant: undefined,
+        reason: undefined,
+        metadata: { id: 2, version: undefined, description: undefined, payload: undefined },
+      }
+      expect(getFeatureFlagValue(flag1)).toBe(true)
+      expect(getFeatureFlagValue(flag2)).toBe(false)
+    })
+
+    it('should return undefined if neither variant nor enabled', () => {
+      const flag: FeatureFlagDetail = {
+        key: 'test-flag',
+        enabled: false,
+        variant: undefined,
+        reason: undefined,
+        metadata: { id: 1, version: undefined, description: undefined, payload: undefined },
+      }
+      expect(getFeatureFlagValue(flag)).toBe(false)
+    })
+  })
+
+  describe('getFlagValuesFromFlags', () => {
+    it('should extract flag values from flags', () => {
+      const flags: Record<string, FeatureFlagDetail> = {
+        'flag-1': {
+          key: 'flag-1',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 1, version: undefined, description: undefined, payload: undefined },
+        },
+        'flag-2': {
+          key: 'flag-2',
+          enabled: false,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 2, version: undefined, description: undefined, payload: undefined },
+        },
+        'flag-3': {
+          key: 'flag-3',
+          enabled: true,
+          variant: 'test-variant',
+          reason: undefined,
+          metadata: { id: 3, version: undefined, description: undefined, payload: undefined },
+        },
+      }
+
+      expect(getFlagValuesFromFlags(flags)).toEqual({
+        'flag-1': true,
+        'flag-2': false,
+        'flag-3': 'test-variant',
+      })
+    })
+
+    it('should handle empty flags object', () => {
+      expect(getFlagValuesFromFlags({})).toEqual({})
+    })
+  })
+
+  describe('getPayloadsFromFlags', () => {
+    it('should extract payloads from enabled flags with metadata', () => {
+      const flags: Record<string, FeatureFlagDetail> = {
+        'flag-with-object-payload': {
+          key: 'flag-with-object-payload',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 1, version: undefined, description: undefined, payload: '{"key": "value"}' },
+        },
+        'flag-with-single-item-array-payload': {
+          key: 'flag-with-single-item-array-payload',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 1, version: undefined, description: undefined, payload: '[5]' },
+        },
+        'flag-with-array-payload': {
+          key: 'flag-with-array-payload',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 1, version: undefined, description: undefined, payload: '[1, 2, 3]' },
+        },
+        'disabled-flag': {
+          key: 'disabled-flag',
+          enabled: false,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 2, version: undefined, description: undefined, payload: undefined },
+        },
+        'enabled-flag-no-payload': {
+          key: 'enabled-flag-no-payload',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 3, version: undefined, description: undefined, payload: undefined },
+        },
+      }
+
+      expect(getPayloadsFromFlags(flags)).toEqual({
+        'flag-with-object-payload': { key: 'value' },
+        'flag-with-single-item-array-payload': [5],
+        'flag-with-array-payload': [1, 2, 3],
+      })
+    })
+
+    it('should handle empty flags object', () => {
+      expect(getPayloadsFromFlags({})).toEqual({})
+    })
+
+    it('should handle flags with no payloads', () => {
+      const flags: Record<string, FeatureFlagDetail> = {
+        'flag-1': {
+          key: 'flag-1',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 1, version: undefined, description: undefined, payload: undefined },
+        },
+        'flag-2': {
+          key: 'flag-2',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: { id: 2, version: undefined, description: undefined, payload: undefined },
+        },
+      }
+
+      expect(getPayloadsFromFlags(flags)).toEqual({})
+    })
+  })
+
+  describe('getFlagDetailsFromFlagsAndPayloads', () => {
+    it('should convert v1 flags and payloads to flag details', () => {
+      const flagsResponse: PostHogFlagsResponse = {
+        featureFlags: {
+          'flag-1': true,
+          'flag-2': 'variant-1',
+          'flag-3': false,
+        },
+        featureFlagPayloads: {
+          'flag-1': { key: 'value1' },
+          'flag-2': { key: 'value2' },
+        },
+        flags: {},
+        errorsWhileComputingFlags: false,
+      }
+
+      const result = getFlagDetailsFromFlagsAndPayloads(flagsResponse)
+
+      expect(result).toEqual({
+        'flag-1': {
+          key: 'flag-1',
+          enabled: true,
+          variant: undefined,
+          reason: undefined,
+          metadata: {
+            id: undefined,
+            version: undefined,
+            payload: '{"key":"value1"}',
+            description: undefined,
+          },
+        },
+        'flag-2': {
+          key: 'flag-2',
+          enabled: true,
+          variant: 'variant-1',
+          reason: undefined,
+          metadata: {
+            id: undefined,
+            version: undefined,
+            payload: '{"key":"value2"}',
+            description: undefined,
+          },
+        },
+        'flag-3': {
+          key: 'flag-3',
+          enabled: false,
+          variant: undefined,
+          reason: undefined,
+          metadata: {
+            id: undefined,
+            version: undefined,
+            payload: undefined,
+            description: undefined,
+          },
+        },
+      })
+    })
+
+    it('should handle empty flags and payloads', () => {
+      const flagsResponse: PostHogFlagsResponse = {
+        featureFlags: {},
+        featureFlagPayloads: {},
+        flags: {},
+        errorsWhileComputingFlags: false,
+      }
+
+      expect(getFlagDetailsFromFlagsAndPayloads(flagsResponse)).toEqual({})
+    })
+  })
+
+  describe('normalizeFlagsResponse', () => {
+    it('should convert v4 response to v1 format', () => {
+      const v4Response: PostHogFlagsResponse = {
+        flags: {
+          'flag-1': {
+            key: 'flag-1',
+            enabled: true,
+            variant: undefined,
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: '{"key":"value1"}',
+              description: undefined,
+            },
+          },
+          'flag-2': {
+            key: 'flag-2',
+            enabled: true,
+            variant: 'variant-1',
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: '{"key":"value2"}',
+              description: undefined,
+            },
+          },
+          'flag-3': {
+            key: 'flag-3',
+            enabled: false,
+            variant: undefined,
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: undefined,
+              description: undefined,
+            },
+          },
+        },
+        errorsWhileComputingFlags: false,
+        featureFlags: {},
+        featureFlagPayloads: {},
+      }
+
+      const result = normalizeFlagsResponse(v4Response)
+
+      expect(result).toEqual({
+        featureFlags: {
+          'flag-1': true,
+          'flag-2': 'variant-1',
+          'flag-3': false,
+        },
+        featureFlagPayloads: {
+          'flag-1': { key: 'value1' },
+          'flag-2': { key: 'value2' },
+        },
+        flags: v4Response.flags,
+        errorsWhileComputingFlags: false,
+      })
+    })
+
+    it('should convert v1 response to v4 format', () => {
+      const v1Response: Omit<PostHogFlagsResponse, 'flags'> = {
+        featureFlags: {
+          'flag-1': true,
+          'flag-2': 'variant-1',
+          'flag-3': false,
+        },
+        featureFlagPayloads: {
+          'flag-1': { key: 'value1' },
+          'flag-2': { key: 'value2' },
+        },
+        errorsWhileComputingFlags: false,
+      }
+
+      const result = normalizeFlagsResponse(v1Response)
+
+      expect(result).toEqual({
+        featureFlags: {
+          'flag-1': true,
+          'flag-2': 'variant-1',
+          'flag-3': false,
+        },
+        featureFlagPayloads: {
+          'flag-1': { key: 'value1' },
+          'flag-2': { key: 'value2' },
+        },
+        flags: {
+          'flag-1': {
+            key: 'flag-1',
+            enabled: true,
+            variant: undefined,
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: '{"key":"value1"}',
+              description: undefined,
+            },
+          },
+          'flag-2': {
+            key: 'flag-2',
+            enabled: true,
+            variant: 'variant-1',
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: '{"key":"value2"}',
+              description: undefined,
+            },
+          },
+          'flag-3': {
+            key: 'flag-3',
+            enabled: false,
+            variant: undefined,
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: undefined,
+              description: undefined,
+            },
+          },
+        },
+        errorsWhileComputingFlags: false,
+      })
+    })
+
+    it('should handle empty flags and payloads', () => {
+      const v1Response: Omit<PostHogFlagsResponse, 'flags'> = {
+        featureFlags: {},
+        featureFlagPayloads: {},
+        errorsWhileComputingFlags: false,
+      }
+
+      const result = normalizeFlagsResponse(v1Response)
+
+      expect(result).toEqual({
+        featureFlags: {},
+        featureFlagPayloads: {},
+        flags: {},
+        errorsWhileComputingFlags: false,
+      })
+    })
+
+    it('should preserve additional fields', () => {
+      const v1Response: Omit<PostHogFlagsResponse, 'flags'> = {
+        featureFlags: {
+          'flag-1': true,
+        },
+        featureFlagPayloads: {
+          'flag-1': { key: 'value1' },
+        },
+        errorsWhileComputingFlags: false,
+        sessionRecording: true,
+        quotaLimited: ['feature_flags'],
+        requestId: 'test-request-id',
+      }
+
+      const result = normalizeFlagsResponse(v1Response)
+
+      expect(result).toEqual({
+        featureFlags: {
+          'flag-1': true,
+        },
+        featureFlagPayloads: {
+          'flag-1': { key: 'value1' },
+        },
+        flags: {
+          'flag-1': {
+            key: 'flag-1',
+            enabled: true,
+            variant: undefined,
+            reason: undefined,
+            metadata: {
+              id: undefined,
+              version: undefined,
+              payload: '{"key":"value1"}',
+              description: undefined,
+            },
+          },
+        },
+        errorsWhileComputingFlags: false,
+        sessionRecording: true,
+        quotaLimited: ['feature_flags'],
+        requestId: 'test-request-id',
+      })
+    })
+  })
+})

package/src/__tests__/gzip.spec.ts

@@ -0,0 +1,69 @@
+import { isGzipSupported, gzipCompress } from '@/gzip'
+import { gzip } from 'node:zlib'
+import { randomBytes, randomUUID } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const RANDOM_TEST_INPUT = JSON.stringify({
+  abc: randomBytes(16),
+  def: randomBytes(64),
+})
+const API_TEST_INPUT = JSON.stringify({
+  api_key: 'TEST_API_KEY',
+  batch: [
+    {
+      event: 'custom-event',
+      distinct_id: 'user-distinct-id',
+      library: 'posthog-core-tests',
+      library_version: '2.0.0-alpha',
+      properties: {
+        $lib: 'posthog-core-tests',
+        $lib_version: '2.0.0-alpha',
+        $session_id: 'session.id',
+      },
+      timestamp: new Date().toISOString(),
+      uuid: randomUUID(),
+      type: 'capture',
+    },
+  ],
+  sent_at: new Date().toISOString(),
+})
+
+describe('gzip', () => {
+  describe('isGzipSupported', () => {
+    it('should return true if CompressStream exists', () => {
+      expect(globalThis.CompressionStream).toBeDefined()
+      expect(isGzipSupported()).toBe(true)
+    })
+    it('should return false if CompressStream not available', () => {
+      const CompressionStream = globalThis.CompressionStream
+      delete (globalThis as any).CompressionStream
+      expect(isGzipSupported()).toBe(false)
+      ;(globalThis as any).CompressionStream = CompressionStream
+    })
+  })
+  describe('gzipCompress', () => {
+    it('compressed random data should match node', async () => {
+      const compressed = await gzipCompress(RANDOM_TEST_INPUT)
+      expect(compressed).not.toBe(null)
+      if (!compressed) {
+        return
+      }
+      const webCompress = Buffer.from(await compressed.arrayBuffer())
+      const nodeCompress = await promisify(gzip)(RANDOM_TEST_INPUT)
+      expect(webCompress).not.toBeFalsy()
+      expect(webCompress).toEqual(nodeCompress)
+    })
+
+    it('compressed mock request should match node', async () => {
+      const compressed = await gzipCompress(API_TEST_INPUT)
+      expect(compressed).not.toBe(null)
+      if (!compressed) {
+        return
+      }
+      const webCompress = Buffer.from(await compressed.arrayBuffer())
+      const nodeCompress = await promisify(gzip)(API_TEST_INPUT)
+      expect(webCompress).not.toBeFalsy()
+      expect(webCompress).toEqual(nodeCompress)
+    })
+  })
+})

package/src/__tests__/posthog.ai.spec.ts

@@ -0,0 +1,110 @@
+import {
+  parseBody,
+  waitForPromises,
+  createTestClient,
+  PostHogCoreTestClient,
+  PostHogCoreTestClientMocks,
+} from '@/testing'
+
+describe('PostHog Core', () => {
+  let posthog: PostHogCoreTestClient
+  let mocks: PostHogCoreTestClientMocks
+
+  jest.useFakeTimers()
+
+  beforeEach(() => {
+    ;[posthog, mocks] = createTestClient('TEST_API_KEY', { flushAt: 1 })
+  })
+
+  describe('ai', () => {
+    it('should capture feedback', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      posthog.captureTraceFeedback('trace-id', 'feedback')
+
+      await waitForPromises()
+      expect(mocks.fetch).toHaveBeenCalledTimes(1)
+      const body = parseBody(mocks.fetch.mock.calls[0])
+
+      expect(body).toMatchObject({
+        batch: [
+          {
+            event: '$ai_feedback',
+            properties: {
+              $ai_feedback_text: 'feedback',
+              $ai_trace_id: 'trace-id',
+            },
+          },
+        ],
+      })
+    })
+
+    it('should convert numeric traceId in captureTraceFeedback', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      posthog.captureTraceFeedback(10, 'feedback')
+
+      await waitForPromises()
+      expect(mocks.fetch).toHaveBeenCalledTimes(1)
+      const body = parseBody(mocks.fetch.mock.calls[0])
+
+      expect(body).toMatchObject({
+        batch: [
+          {
+            event: '$ai_feedback',
+            properties: {
+              $ai_feedback_text: 'feedback',
+              $ai_trace_id: '10',
+            },
+          },
+        ],
+      })
+    })
+
+    it('should capture a metric', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      posthog.captureTraceMetric('trace-id', 'metric-name', 'good')
+
+      await waitForPromises()
+      expect(mocks.fetch).toHaveBeenCalledTimes(1)
+      const body = parseBody(mocks.fetch.mock.calls[0])
+
+      expect(body).toMatchObject({
+        batch: [
+          {
+            event: '$ai_metric',
+            properties: {
+              $ai_metric_name: 'metric-name',
+              $ai_metric_value: 'good',
+              $ai_trace_id: 'trace-id',
+            },
+          },
+        ],
+      })
+    })
+
+    it('should convert numeric arguments in captureTraceMetric', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      posthog.captureTraceMetric(10, 'metric-name', 1)
+
+      await waitForPromises()
+      expect(mocks.fetch).toHaveBeenCalledTimes(1)
+      const body = parseBody(mocks.fetch.mock.calls[0])
+
+      expect(body).toMatchObject({
+        batch: [
+          {
+            event: '$ai_metric',
+            properties: {
+              $ai_metric_name: 'metric-name',
+              $ai_metric_value: '1',
+              $ai_trace_id: '10',
+            },
+          },
+        ],
+      })
+    })
+  })
+})

package/src/__tests__/posthog.capture.spec.ts

@@ -0,0 +1,91 @@
+import {
+  parseBody,
+  waitForPromises,
+  createTestClient,
+  PostHogCoreTestClient,
+  PostHogCoreTestClientMocks,
+} from '@/testing'
+import { uuidv7 } from '@/vendor/uuidv7'
+
+describe('PostHog Core', () => {
+  let posthog: PostHogCoreTestClient
+  let mocks: PostHogCoreTestClientMocks
+
+  jest.useFakeTimers()
+
+  beforeEach(() => {
+    ;[posthog, mocks] = createTestClient('TEST_API_KEY', { flushAt: 1 })
+  })
+
+  describe('capture', () => {
+    it('should capture an event', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      posthog.capture('custom-event')
+
+      await waitForPromises()
+      expect(mocks.fetch).toHaveBeenCalledTimes(1)
+      const [url, options] = mocks.fetch.mock.calls[0]
+      expect(url).toMatch(/^https:\/\/us\.i\.posthog\.com\/batch\//)
+      expect(options.method).toBe('POST')
+      const body = parseBody(mocks.fetch.mock.calls[0])
+
+      expect(body).toEqual({
+        api_key: 'TEST_API_KEY',
+        batch: [
+          {
+            event: 'custom-event',
+            distinct_id: posthog.getDistinctId(),
+            library: 'posthog-core-tests',
+            library_version: '2.0.0-alpha',
+            properties: {
+              $lib: 'posthog-core-tests',
+              $lib_version: '2.0.0-alpha',
+              $session_id: expect.any(String),
+            },
+            timestamp: '2022-01-01T00:00:00.000Z',
+            uuid: expect.any(String),
+            type: 'capture',
+          },
+        ],
+        sent_at: expect.any(String),
+      })
+    })
+
+    it('should allow overriding the timestamp', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      posthog.capture('custom-event', { foo: 'bar' }, { timestamp: new Date('2021-01-02') })
+      await waitForPromises()
+      const body = parseBody(mocks.fetch.mock.calls[0])
+      expect(body).toMatchObject({
+        api_key: 'TEST_API_KEY',
+        batch: [
+          {
+            event: 'custom-event',
+            timestamp: '2021-01-02T00:00:00.000Z',
+          },
+        ],
+      })
+    })
+
+    it('should allow overriding the uuid', async () => {
+      jest.setSystemTime(new Date('2022-01-01'))
+
+      const id = uuidv7()
+
+      posthog.capture('custom-event', { foo: 'bar' }, { uuid: id })
+      await waitForPromises()
+      const body = parseBody(mocks.fetch.mock.calls[0])
+
+      expect(body).toMatchObject({
+        batch: [
+          {
+            event: 'custom-event',
+            uuid: expect.any(String),
+          },
+        ],
+      })
+    })
+  })
+})