posthog-node 4.10.1 → 4.11.0

package/test/feature-flags.decide.spec.ts

@@ -0,0 +1,293 @@
+import { PostHog as PostHog, PostHogOptions } from '../src/posthog-node'
+import fetch from '../src/fetch'
+import { apiImplementation, apiImplementationV4 } from './test-utils'
+import { waitForPromises } from 'posthog-core/test/test-utils/test-utils'
+import { PostHogV4DecideResponse } from 'posthog-core/src/types'
+jest.mock('../src/fetch')
+
+jest.spyOn(console, 'debug').mockImplementation()
+
+const mockedFetch = jest.mocked(fetch, true)
+
+const posthogImmediateResolveOptions: PostHogOptions = {
+  fetchRetryCount: 0,
+}
+
+describe('decide v4', () => {
+  describe('getFeatureFlag v4', () => {
+    it('returns false if the flag is not found', async () => {
+      const decideResponse: PostHogV4DecideResponse = {
+        flags: {},
+        errorsWhileComputingFlags: false,
+        requestId: '0152a345-295f-4fba-adac-2e6ea9c91082',
+      }
+      mockedFetch.mockImplementation(apiImplementationV4(decideResponse))
+
+      const posthog = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        ...posthogImmediateResolveOptions,
+      })
+      let capturedMessage: any
+      posthog.on('capture', (message) => {
+        capturedMessage = message
+      })
+
+      const result = await posthog.getFeatureFlag('non-existent-flag', 'some-distinct-id')
+
+      expect(result).toBe(false)
+      expect(mockedFetch).toHaveBeenCalledWith('http://example.com/decide/?v=4', expect.any(Object))
+
+      await waitForPromises()
+      expect(capturedMessage).toMatchObject({
+        distinct_id: 'some-distinct-id',
+        event: '$feature_flag_called',
+        library: posthog.getLibraryId(),
+        library_version: posthog.getLibraryVersion(),
+        properties: {
+          '$feature/non-existent-flag': false,
+          $feature_flag: 'non-existent-flag',
+          $feature_flag_response: false,
+          $feature_flag_request_id: '0152a345-295f-4fba-adac-2e6ea9c91082',
+          $groups: undefined,
+          $lib: posthog.getLibraryId(),
+          $lib_version: posthog.getLibraryVersion(),
+          locally_evaluated: false,
+        },
+      })
+    })
+
+    it.each([
+      {
+        key: 'variant-flag',
+        expectedResponse: 'variant-value',
+        expectedReason: 'Matched condition set 3',
+        expectedId: 2,
+        expectedVersion: 23,
+      },
+      {
+        key: 'boolean-flag',
+        expectedResponse: true,
+        expectedReason: 'Matched condition set 1',
+        expectedId: 1,
+        expectedVersion: 12,
+      },
+      {
+        key: 'non-matching-flag',
+        expectedResponse: false,
+        expectedReason: 'Did not match any condition',
+        expectedId: 3,
+        expectedVersion: 2,
+      },
+    ])(
+      'captures a feature flag called event with extra metadata when the flag is found',
+      async ({ key, expectedResponse, expectedReason, expectedId, expectedVersion }) => {
+        const decideResponse: PostHogV4DecideResponse = {
+          flags: {
+            'variant-flag': {
+              key: 'variant-flag',
+              enabled: true,
+              variant: 'variant-value',
+              reason: {
+                code: 'variant',
+                condition_index: 2,
+                description: 'Matched condition set 3',
+              },
+              metadata: {
+                id: 2,
+                version: 23,
+                payload: '{"key": "value"}',
+                description: 'description',
+              },
+            },
+            'boolean-flag': {
+              key: 'boolean-flag',
+              enabled: true,
+              variant: undefined,
+              reason: {
+                code: 'boolean',
+                condition_index: 1,
+                description: 'Matched condition set 1',
+              },
+              metadata: {
+                id: 1,
+                version: 12,
+                payload: undefined,
+                description: 'description',
+              },
+            },
+            'non-matching-flag': {
+              key: 'non-matching-flag',
+              enabled: false,
+              variant: undefined,
+              reason: {
+                code: 'boolean',
+                condition_index: 1,
+                description: 'Did not match any condition',
+              },
+              metadata: {
+                id: 3,
+                version: 2,
+                payload: undefined,
+                description: 'description',
+              },
+            },
+          },
+          errorsWhileComputingFlags: false,
+          requestId: '0152a345-295f-4fba-adac-2e6ea9c91082',
+        }
+        mockedFetch.mockImplementation(apiImplementationV4(decideResponse))
+
+        const posthog = new PostHog('TEST_API_KEY', {
+          host: 'http://example.com',
+          ...posthogImmediateResolveOptions,
+        })
+        let capturedMessage: any
+        posthog.on('capture', (message) => {
+          capturedMessage = message
+        })
+
+        const result = await posthog.getFeatureFlag(key, 'some-distinct-id')
+
+        expect(result).toBe(expectedResponse)
+        expect(mockedFetch).toHaveBeenCalledWith('http://example.com/decide/?v=4', expect.any(Object))
+
+        await waitForPromises()
+        expect(capturedMessage).toMatchObject({
+          distinct_id: 'some-distinct-id',
+          event: '$feature_flag_called',
+          library: posthog.getLibraryId(),
+          library_version: posthog.getLibraryVersion(),
+          properties: {
+            [`$feature/${key}`]: expectedResponse,
+            $feature_flag: key,
+            $feature_flag_response: expectedResponse,
+            $feature_flag_id: expectedId,
+            $feature_flag_version: expectedVersion,
+            $feature_flag_reason: expectedReason,
+            $feature_flag_request_id: '0152a345-295f-4fba-adac-2e6ea9c91082',
+            $groups: undefined,
+            $lib: posthog.getLibraryId(),
+            $lib_version: posthog.getLibraryVersion(),
+            locally_evaluated: false,
+          },
+        })
+      }
+    )
+
+    describe('getFeatureFlagPayload v4', () => {
+      it('returns payload', async () => {
+        mockedFetch.mockImplementation(
+          apiImplementationV4({
+            flags: {
+              'flag-with-payload': {
+                key: 'flag-with-payload',
+                enabled: true,
+                variant: undefined,
+                reason: {
+                  code: 'boolean',
+                  condition_index: 1,
+                  description: 'Matched condition set 2',
+                },
+                metadata: {
+                  id: 1,
+                  version: 12,
+                  payload: '[0, 1, 2]',
+                  description: 'description',
+                },
+              },
+            },
+            errorsWhileComputingFlags: false,
+          })
+        )
+
+        const posthog = new PostHog('TEST_API_KEY', {
+          host: 'http://example.com',
+          ...posthogImmediateResolveOptions,
+        })
+        let capturedMessage: any
+        posthog.on('capture', (message) => {
+          capturedMessage = message
+        })
+
+        const result = await posthog.getFeatureFlagPayload('flag-with-payload', 'some-distinct-id')
+
+        expect(result).toEqual([0, 1, 2])
+        expect(mockedFetch).toHaveBeenCalledWith('http://example.com/decide/?v=4', expect.any(Object))
+
+        await waitForPromises()
+        expect(capturedMessage).toBeUndefined()
+      })
+    })
+  })
+})
+
+describe('decide v3', () => {
+  describe('getFeatureFlag v3', () => {
+    it('returns false if the flag is not found', async () => {
+      mockedFetch.mockImplementation(apiImplementation({ decideFlags: {} }))
+
+      const posthog = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        ...posthogImmediateResolveOptions,
+      })
+      let capturedMessage: any
+      posthog.on('capture', (message) => {
+        capturedMessage = message
+      })
+
+      const result = await posthog.getFeatureFlag('non-existent-flag', 'some-distinct-id')
+
+      expect(result).toBe(false)
+      expect(mockedFetch).toHaveBeenCalledWith('http://example.com/decide/?v=4', expect.any(Object))
+
+      await waitForPromises()
+      expect(capturedMessage).toMatchObject({
+        distinct_id: 'some-distinct-id',
+        event: '$feature_flag_called',
+        library: posthog.getLibraryId(),
+        library_version: posthog.getLibraryVersion(),
+        properties: {
+          '$feature/non-existent-flag': false,
+          $feature_flag: 'non-existent-flag',
+          $feature_flag_response: false,
+          $groups: undefined,
+          $lib: posthog.getLibraryId(),
+          $lib_version: posthog.getLibraryVersion(),
+          locally_evaluated: false,
+        },
+      })
+    })
+
+    describe('getFeatureFlagPayload v3', () => {
+      it('returns payload', async () => {
+        mockedFetch.mockImplementation(
+          apiImplementation({
+            decideFlags: {
+              'flag-with-payload': true,
+            },
+            decideFlagPayloads: {
+              'flag-with-payload': [0, 1, 2],
+            },
+          })
+        )
+
+        const posthog = new PostHog('TEST_API_KEY', {
+          host: 'http://example.com',
+          ...posthogImmediateResolveOptions,
+        })
+        let capturedMessage: any = undefined
+        posthog.on('capture', (message) => {
+          capturedMessage = message
+        })
+
+        const result = await posthog.getFeatureFlagPayload('flag-with-payload', 'some-distinct-id')
+
+        expect(result).toEqual([0, 1, 2])
+        expect(mockedFetch).toHaveBeenCalledWith('http://example.com/decide/?v=4', expect.any(Object))
+
+        await waitForPromises()
+        expect(capturedMessage).toBeUndefined()
+      })
+    })
+  })
+})

package/test/feature-flags.spec.ts

@@ -347,7 +347,7 @@ describe('local evaluation', () => {
       })
     ).toEqual('decide-fallback-value')
     expect(mockedFetch).toHaveBeenCalledWith(
-      'http://example.com/decide/?v=3',
+      'http://example.com/decide/?v=4',
       expect.objectContaining({
         body: JSON.stringify({
           token: 'TEST_API_KEY',
@@ -371,7 +371,7 @@ describe('local evaluation', () => {
       await posthog.getFeatureFlag('complex-flag', 'some-distinct-id', { personProperties: { doesnt_matter: '1' } })
     ).toEqual('decide-fallback-value')
     expect(mockedFetch).toHaveBeenCalledWith(
-      'http://example.com/decide/?v=3',
+      'http://example.com/decide/?v=4',
       expect.objectContaining({
         body: JSON.stringify({
           token: 'TEST_API_KEY',

package/test/lazy.spec.ts

@@ -0,0 +1,71 @@
+import { Lazy } from '../src/lazy'
+
+describe('Lazy', () => {
+  it('should only call the factory once', async (): Promise<void> => {
+    let callCount = 0
+    const factory = async (): Promise<string> => {
+      callCount++
+      return 'value'
+    }
+
+    const lazy = new Lazy(factory)
+    expect(callCount).toBe(0)
+
+    const value1 = await lazy.getValue()
+    expect(value1).toBe('value')
+    expect(callCount).toBe(1)
+
+    const value2 = await lazy.getValue()
+    expect(value2).toBe('value')
+    expect(callCount).toBe(1)
+  })
+
+  it('should handle errors in the factory', async (): Promise<void> => {
+    const factory = async (): Promise<string> => {
+      throw new Error('Factory error')
+    }
+
+    const lazy = new Lazy(factory)
+    await expect(lazy.getValue()).rejects.toThrow('Factory error')
+  })
+
+  it('should handle undefined values', async (): Promise<void> => {
+    const factory = async (): Promise<undefined> => {
+      return undefined
+    }
+
+    const lazy = new Lazy(factory)
+    const value = await lazy.getValue()
+    expect(value).toBeUndefined()
+  })
+
+  it('should handle complex types', async (): Promise<void> => {
+    interface ComplexType {
+      id: number
+      name: string
+    }
+
+    const factory = async (): Promise<ComplexType> => {
+      return { id: 1, name: 'test' }
+    }
+
+    const lazy = new Lazy<ComplexType>(factory)
+    const value = await lazy.getValue()
+    expect(value).toEqual({ id: 1, name: 'test' })
+  })
+
+  it('should handle concurrent calls', async (): Promise<void> => {
+    let callCount = 0
+    const factory = async (): Promise<string> => {
+      callCount++
+      return 'value'
+    }
+
+    const lazy = new Lazy(factory)
+    const [value1, value2] = await Promise.all([lazy.getValue(), lazy.getValue()])
+
+    expect(value1).toBe('value')
+    expect(value2).toBe('value')
+    expect(callCount).toBe(1)
+  })
+})

package/test/posthog-node.spec.ts

@@ -328,6 +328,17 @@ describe('PostHog Node.js', () => {
 
       await client.shutdown()
     })
+
+    it('should warn if capture is called with a string', () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      posthog.debug(true)
+      // @ts-expect-error - Testing the warning when passing a string instead of an object
+      posthog.capture('test-event')
+      expect(warnSpy).toHaveBeenCalledWith(
+        'Called capture() with a string as the first argument when an object was expected.'
+      )
+      warnSpy.mockRestore()
+    })
   })
 
   describe('shutdown', () => {
@@ -603,7 +614,7 @@ describe('PostHog Node.js', () => {
       )
       expect(mockedFetch).toHaveBeenCalledTimes(1)
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.stringContaining('"geoip_disable":true') })
       )
     })
@@ -636,7 +647,7 @@ describe('PostHog Node.js', () => {
       await waitForPromises()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST' })
       )
 
@@ -645,7 +656,7 @@ describe('PostHog Node.js', () => {
           distinct_id: 'distinct_id',
           event: 'node test event',
           properties: expect.objectContaining({
-            $active_feature_flags: ['feature-1', 'feature-2', 'feature-variant', 'feature-array'],
+            $active_feature_flags: ['feature-1', 'feature-2', 'feature-array', 'feature-variant'],
             '$feature/feature-1': true,
             '$feature/feature-2': true,
             '$feature/feature-array': true,
@@ -661,7 +672,7 @@ describe('PostHog Node.js', () => {
 
       expect(mockedFetch).not.toHaveBeenCalledWith(...anyLocalEvalCall)
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.stringContaining('"geoip_disable":true') })
       )
     })
@@ -721,7 +732,7 @@ describe('PostHog Node.js', () => {
       expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
       // no decide call
       expect(mockedFetch).not.toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST' })
       )
 
@@ -779,7 +790,7 @@ describe('PostHog Node.js', () => {
       expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
       // no decide call
       expect(mockedFetch).not.toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST' })
       )
 
@@ -827,12 +838,12 @@ describe('PostHog Node.js', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.not.stringContaining('geoip_disable') })
       )
 
       expect(getLastBatchEvents()?.[0].properties).toEqual({
-        $active_feature_flags: ['feature-1', 'feature-2', 'feature-variant', 'feature-array'],
+        $active_feature_flags: ['feature-1', 'feature-2', 'feature-array', 'feature-variant'],
         '$feature/feature-1': true,
         '$feature/feature-2': true,
         '$feature/feature-array': true,
@@ -1080,7 +1091,7 @@ describe('PostHog Node.js', () => {
       ).resolves.toEqual(2)
       expect(mockedFetch).toHaveBeenCalledTimes(1)
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.stringContaining('"geoip_disable":true') })
       )
     })
@@ -1122,7 +1133,7 @@ describe('PostHog Node.js', () => {
       ).resolves.toEqual([1])
       expect(mockedFetch).toHaveBeenCalledTimes(1)
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.stringContaining('"geoip_disable":true') })
       )
     })
@@ -1142,7 +1153,7 @@ describe('PostHog Node.js', () => {
       ).resolves.toEqual(2)
       expect(mockedFetch).toHaveBeenCalledTimes(1)
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.stringContaining('"geoip_disable":true') })
       )
 
@@ -1151,7 +1162,7 @@ describe('PostHog Node.js', () => {
       await expect(posthog.isFeatureEnabled('feature-variant', '123', { disableGeoip: false })).resolves.toEqual(true)
       expect(mockedFetch).toHaveBeenCalledTimes(1)
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({ method: 'POST', body: expect.not.stringContaining('geoip_disable') })
       )
     })
@@ -1165,7 +1176,7 @@ describe('PostHog Node.js', () => {
       jest.runOnlyPendingTimers()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({
           body: JSON.stringify({
             token: 'TEST_API_KEY',
@@ -1195,7 +1206,7 @@ describe('PostHog Node.js', () => {
       jest.runOnlyPendingTimers()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({
           body: JSON.stringify({
             token: 'TEST_API_KEY',
@@ -1226,7 +1237,7 @@ describe('PostHog Node.js', () => {
       jest.runOnlyPendingTimers()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({
           body: JSON.stringify({
             token: 'TEST_API_KEY',
@@ -1250,7 +1261,7 @@ describe('PostHog Node.js', () => {
       jest.runOnlyPendingTimers()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({
           body: JSON.stringify({
             token: 'TEST_API_KEY',
@@ -1270,7 +1281,7 @@ describe('PostHog Node.js', () => {
       jest.runOnlyPendingTimers()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({
           body: JSON.stringify({
             token: 'TEST_API_KEY',
@@ -1292,7 +1303,7 @@ describe('PostHog Node.js', () => {
       jest.runOnlyPendingTimers()
 
       expect(mockedFetch).toHaveBeenCalledWith(
-        'http://example.com/decide/?v=3',
+        'http://example.com/decide/?v=4',
         expect.objectContaining({
           body: JSON.stringify({
             token: 'TEST_API_KEY',
@@ -1308,5 +1319,25 @@ describe('PostHog Node.js', () => {
         })
       )
     })
+
+    it('should log error when decide response has errors', async () => {
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+
+      mockedFetch.mockImplementation(
+        apiImplementation({
+          decideFlags: { 'feature-1': true },
+          decideFlagPayloads: {},
+          errorsWhileComputingFlags: true,
+        })
+      )
+
+      await posthog.getFeatureFlag('feature-1', '123')
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[FEATURE FLAGS] Error while computing feature flags, some flags may be missing or incorrect. Learn more at https://posthog.com/docs/feature-flags/best-practices'
+      )
+
+      errorSpy.mockRestore()
+    })
   })
 })

package/test/test-utils.ts

@@ -1,15 +1,40 @@
+import { PostHogV4DecideResponse } from 'posthog-core/src/types'
+
+export const apiImplementationV4 = (decideResponse?: PostHogV4DecideResponse) => {
+  return (url: any): Promise<any> => {
+    if ((url as any).includes('/decide/?v=4')) {
+      return Promise.resolve({
+        status: 200,
+        text: () => Promise.resolve('ok'),
+        json: () => Promise.resolve(decideResponse),
+      }) as any
+    }
+
+    return Promise.resolve({
+      status: 400,
+      text: () => Promise.resolve('ok'),
+      json: () =>
+        Promise.resolve({
+          status: 'ok',
+        }),
+    }) as any
+  }
+}
+
 export const apiImplementation = ({
   localFlags,
   decideFlags,
   decideFlagPayloads,
   decideStatus = 200,
   localFlagsStatus = 200,
+  errorsWhileComputingFlags = false,
 }: {
   localFlags?: any
   decideFlags?: any
   decideFlagPayloads?: any
   decideStatus?: number
   localFlagsStatus?: number
+  errorsWhileComputingFlags?: boolean
 }) => {
   return (url: any): Promise<any> => {
     if ((url as any).includes('/decide/')) {
@@ -25,6 +50,7 @@ export const apiImplementation = ({
               featureFlagPayloads: Object.fromEntries(
                 Object.entries(decideFlagPayloads || {}).map(([k, v]) => [k, JSON.stringify(v)])
               ),
+              errorsWhileComputingFlags,
             })
           }
         },
@@ -65,4 +91,4 @@ export const anyLocalEvalCall = [
   'http://example.com/api/feature_flag/local_evaluation?token=TEST_API_KEY&send_cohorts',
   expect.any(Object),
 ]
-export const anyDecideCall = ['http://example.com/decide/?v=3', expect.any(Object)]
+export const anyDecideCall = ['http://example.com/decide/?v=4', expect.any(Object)]