posthog-node 4.10.2 → 4.11.0

package/src/lazy.ts

@@ -0,0 +1,55 @@
+/**
+ * A lazy value that is only computed when needed. Inspired by C#'s Lazy<T> class.
+ */
+export class Lazy<T> {
+  private value: T | undefined
+  private factory: () => Promise<T>
+  private initializationPromise: Promise<T> | undefined
+
+  constructor(factory: () => Promise<T>) {
+    this.factory = factory
+  }
+
+  /**
+   * Gets the value, initializing it if necessary.
+   * Multiple concurrent calls will share the same initialization promise.
+   */
+  async getValue(): Promise<T> {
+    if (this.value !== undefined) {
+      return this.value
+    }
+
+    if (this.initializationPromise === undefined) {
+      this.initializationPromise = (async () => {
+        try {
+          const result = await this.factory()
+          this.value = result
+          return result
+        } finally {
+          // Clear the promise so we can retry if needed
+          this.initializationPromise = undefined
+        }
+      })()
+    }
+
+    return this.initializationPromise
+  }
+
+  /**
+   * Returns true if the value has been initialized.
+   */
+  isInitialized(): boolean {
+    return this.value !== undefined
+  }
+
+  /**
+   * Returns a promise that resolves when the value is initialized.
+   * If already initialized, resolves immediately.
+   */
+  async waitForInitialization(): Promise<void> {
+    if (this.isInitialized()) {
+      return
+    }
+    await this.getValue()
+  }
+}

package/src/posthog-node.ts

@@ -12,9 +12,11 @@ import {
 } from '../../posthog-core/src'
 import { PostHogMemoryStorage } from '../../posthog-core/src/storage-memory'
 import { EventMessage, GroupIdentifyMessage, IdentifyMessage, PostHogNodeV1 } from './types'
+import { FeatureFlagDetail, FeatureFlagValue } from '../../posthog-core/src/types'
 import { FeatureFlagsPoller } from './feature-flags'
 import fetch from './fetch'
 import ErrorTracking from './error-tracking'
+import { getFeatureFlagValue } from 'posthog-core/src/featureFlagUtils'
 
 export type PostHogOptions = PostHogCoreOptions & {
   persistence?: 'memory'
@@ -173,7 +175,9 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
             additionalProperties[`$feature/${feature}`] = variant
           }
         }
-        const activeFlags = Object.keys(flags || {}).filter((flag) => flags?.[flag] !== false)
+        const activeFlags = Object.keys(flags || {})
+          .filter((flag) => flags?.[flag] !== false)
+          .sort()
         if (activeFlags.length > 0) {
           additionalProperties['$active_feature_flags'] = activeFlags
         }
@@ -227,7 +231,7 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       sendFeatureFlagEvents?: boolean
       disableGeoip?: boolean
     }
-  ): Promise<string | boolean | undefined> {
+  ): Promise<FeatureFlagValue | undefined> {
     const { groups, disableGeoip } = options || {}
     let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {}
 
@@ -259,8 +263,9 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
 
     const flagWasLocallyEvaluated = response !== undefined
     let requestId = undefined
+    let flagDetail: FeatureFlagDetail | undefined = undefined
     if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
-      const remoteResponse = await super.getFeatureFlagStateless(
+      const remoteResponse = await super.getFeatureFlagDetailStateless(
         key,
         distinctId,
         groups,
@@ -268,8 +273,14 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
         groupProperties,
         disableGeoip
       )
-      response = remoteResponse.response
-      requestId = remoteResponse.requestId
+
+      if (remoteResponse === undefined) {
+        return undefined
+      }
+
+      flagDetail = remoteResponse.response
+      response = getFeatureFlagValue(flagDetail) ?? false
+      requestId = remoteResponse?.requestId
     }
 
     const featureFlagReportedKey = `${key}_${response}`
@@ -293,6 +304,9 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
         properties: {
           $feature_flag: key,
           $feature_flag_response: response,
+          $feature_flag_id: flagDetail?.metadata?.id,
+          $feature_flag_version: flagDetail?.metadata?.version,
+          $feature_flag_reason: flagDetail?.reason?.description ?? flagDetail?.reason?.code,
           locally_evaluated: flagWasLocallyEvaluated,
           [`$feature/${key}`]: response,
           $feature_flag_request_id: requestId,
@@ -307,7 +321,7 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
   async getFeatureFlagPayload(
     key: string,
     distinctId: string,
-    matchValue?: string | boolean,
+    matchValue?: FeatureFlagValue,
     options?: {
       groups?: Record<string, string>
       personProperties?: Record<string, string>
@@ -332,17 +346,22 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
 
     let response = undefined
 
-    // Try to get match value locally if not provided
-    if (!matchValue) {
-      matchValue = await this.getFeatureFlag(key, distinctId, {
-        ...options,
-        onlyEvaluateLocally: true,
-      })
-    }
+    const localEvaluationEnabled = this.featureFlagsPoller !== undefined
+    if (localEvaluationEnabled) {
+      // Try to get match value locally if not provided
+      if (!matchValue) {
+        matchValue = await this.getFeatureFlag(key, distinctId, {
+          ...options,
+          onlyEvaluateLocally: true,
+          sendFeatureFlagEvents: false,
+        })
+      }
 
-    if (matchValue) {
-      response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
+      if (matchValue) {
+        response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
+      }
     }
+    //}
 
     // set defaults
     if (onlyEvaluateLocally == undefined) {
@@ -404,9 +423,9 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       onlyEvaluateLocally?: boolean
       disableGeoip?: boolean
     }
-  ): Promise<Record<string, string | boolean>> {
+  ): Promise<Record<string, FeatureFlagValue>> {
     const response = await this.getAllFlagsAndPayloads(distinctId, options)
-    return response.featureFlags
+    return response.featureFlags || {}
   }
 
   async getAllFlagsAndPayloads(

package/src/types.ts

@@ -1,4 +1,4 @@
-import { JsonType } from '../../posthog-core/src'
+import { FeatureFlagValue, JsonType } from '../../posthog-core/src'
 
 export interface IdentifyMessage {
   distinctId: string
@@ -155,7 +155,7 @@ export type PostHogNodeV1 = {
       onlyEvaluateLocally?: boolean
       sendFeatureFlagEvents?: boolean
     }
-  ): Promise<string | boolean | undefined>
+  ): Promise<FeatureFlagValue | undefined>
 
   /**
    * @description Retrieves payload associated with the specified flag and matched value that is passed in.
@@ -186,7 +186,7 @@ export type PostHogNodeV1 = {
   getFeatureFlagPayload(
     key: string,
     distinctId: string,
-    matchValue?: string | boolean,
+    matchValue?: FeatureFlagValue,
     options?: {
       onlyEvaluateLocally?: boolean
     }

package/test/crypto.spec.ts

@@ -0,0 +1,36 @@
+import * as crypto from '../src/crypto'
+import * as cryptoHelpers from '../src/crypto-helpers'
+
+describe('crypto', () => {
+  describe('hashSHA1', () => {
+    const testString = 'some-flag.some_distinct_id'
+    const expectedHash = 'e4ce124e800a818c63099f95fa085dc2b620e173'
+
+    afterEach(() => {
+      jest.restoreAllMocks() // <- Reset all mocks after each test
+    })
+
+    it('should hash correctly using Node.js crypto', async () => {
+      jest.spyOn(cryptoHelpers, 'getWebCrypto').mockResolvedValue(undefined)
+
+      const hash = await crypto.hashSHA1(testString)
+      expect(hash).toBe(expectedHash)
+    })
+
+    it('should hash correctly using Web Crypto API', async () => {
+      jest.spyOn(cryptoHelpers, 'getNodeCrypto').mockResolvedValue(undefined)
+
+      const hash = await crypto.hashSHA1(testString)
+      expect(hash).toBe(expectedHash)
+    })
+
+    it('should throw if no crypto implementation is available', async () => {
+      jest.spyOn(cryptoHelpers, 'getNodeCrypto').mockResolvedValue(undefined)
+      jest.spyOn(cryptoHelpers, 'getWebCrypto').mockResolvedValue(undefined)
+
+      await expect(crypto.hashSHA1(testString)).rejects.toThrow(
+        'No crypto implementation available. Tried Node Crypto API and Web SubtleCrypto API'
+      )
+    })
+  })
+})

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)
+  })
+})