posthog-node 5.25.0 → 5.26.0

package/src/client.ts

@@ -1,7 +1,6 @@
 import { version } from './version'
 
 import {
-  FeatureFlagDetail,
   FeatureFlagValue,
   isBlockedUA,
   isPlainObject,
@@ -26,9 +25,12 @@ import {
   OverrideFeatureFlagsOptions,
   PostHogOptions,
   SendFeatureFlagsOptions,
+  FlagEvaluationOptions,
+  AllFlagsOptions,
 } from './types'
 import {
   FeatureFlagsPoller,
+  type FeatureFlagEvaluationContext,
   RequiresServerEvaluation,
   InconclusiveMatchError,
 } from './extensions/feature-flags/feature-flags'
@@ -611,6 +613,16 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     })
   }
 
+  private _resolveDistinctId<T>(
+    distinctIdOrOptions: string | T | undefined,
+    options: T | undefined
+  ): { distinctId: string | undefined; options: T | undefined } {
+    if (typeof distinctIdOrOptions === 'string') {
+      return { distinctId: distinctIdOrOptions, options }
+    }
+    return { distinctId: this.context?.get()?.distinctId, options: distinctIdOrOptions }
+  }
+
   /**
    * Internal method that handles feature flag evaluation with full details.
    * Used by getFeatureFlag, getFeatureFlagPayload, and getFeatureFlagResult.
@@ -663,6 +675,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     personProperties = adjustedProperties.allPersonProperties
     groupProperties = adjustedProperties.allGroupProperties
+    const evaluationContext = this.createFeatureFlagEvaluationContext(
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
 
     // set defaults
     if (onlyEvaluateLocally == undefined) {
@@ -687,14 +705,9 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       const flag = this.featureFlagsPoller?.featureFlagsByKey[key]
       if (flag) {
         try {
-          const localResult = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(
-            flag,
-            distinctId,
-            groups,
-            personProperties,
-            groupProperties,
-            matchValue
-          )
+          const localResult = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(flag, evaluationContext, {
+            matchValue,
+          })
           if (localResult) {
             flagWasLocallyEvaluated = true
             const value = localResult.value
@@ -721,10 +734,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     // Fall back to remote evaluation if needed
     if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
       const flagsResponse = await super.getFeatureFlagDetailsStateless(
-        distinctId,
-        groups,
-        personProperties,
-        groupProperties,
+        evaluationContext.distinctId,
+        evaluationContext.groups,
+        evaluationContext.personProperties,
+        evaluationContext.groupProperties,
         disableGeoip,
         [key]
       )
@@ -1008,21 +1021,30 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param options - Optional configuration for flag evaluation
    * @returns Promise that resolves to the flag result or undefined
    */
+  async getFeatureFlagResult(key: string, options?: FlagEvaluationOptions): Promise<FeatureFlagResult | undefined>
   async getFeatureFlagResult(
     key: string,
     distinctId: string,
-    options?: {
-      groups?: Record<string, string>
-      personProperties?: Record<string, string>
-      groupProperties?: Record<string, Record<string, string>>
-      onlyEvaluateLocally?: boolean
-      sendFeatureFlagEvents?: boolean
-      disableGeoip?: boolean
-    }
+    options?: FlagEvaluationOptions
+  ): Promise<FeatureFlagResult | undefined>
+  async getFeatureFlagResult(
+    key: string,
+    distinctIdOrOptions?: string | FlagEvaluationOptions,
+    options?: FlagEvaluationOptions
   ): Promise<FeatureFlagResult | undefined> {
-    return this._getFeatureFlagResult(key, distinctId, {
-      ...options,
-      sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true,
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(
+      distinctIdOrOptions,
+      options
+    )
+
+    if (!resolvedDistinctId) {
+      this._logger.warn('[PostHog] distinctId is required — pass it explicitly or use withContext()')
+      return undefined
+    }
+
+    return this._getFeatureFlagResult(key, resolvedDistinctId, {
+      ...resolvedOptions,
+      sendFeatureFlagEvents: resolvedOptions?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true,
     })
   }
 
@@ -1155,18 +1177,24 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param options - Optional configuration for flag evaluation
    * @returns Promise that resolves to a record of flag keys and their values
    */
+  async getAllFlags(options?: AllFlagsOptions): Promise<Record<string, FeatureFlagValue>>
+  async getAllFlags(distinctId: string, options?: AllFlagsOptions): Promise<Record<string, FeatureFlagValue>>
   async getAllFlags(
-    distinctId: string,
-    options?: {
-      groups?: Record<string, string>
-      personProperties?: Record<string, string>
-      groupProperties?: Record<string, Record<string, string>>
-      onlyEvaluateLocally?: boolean
-      disableGeoip?: boolean
-      flagKeys?: string[]
-    }
+    distinctIdOrOptions?: string | AllFlagsOptions,
+    options?: AllFlagsOptions
   ): Promise<Record<string, FeatureFlagValue>> {
-    const response = await this.getAllFlagsAndPayloads(distinctId, options)
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(
+      distinctIdOrOptions,
+      options
+    )
+    if (!resolvedDistinctId) {
+      this._logger.warn(
+        '[PostHog] distinctId is required to get feature flags — pass it explicitly or use withContext()'
+      )
+      return {}
+    }
+
+    const response = await this.getAllFlagsAndPayloads(resolvedDistinctId, resolvedOptions)
     return response.featureFlags || {}
   }
 
@@ -1203,22 +1231,28 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param options - Optional configuration for flag evaluation
    * @returns Promise that resolves to flags and payloads
    */
+  async getAllFlagsAndPayloads(options?: AllFlagsOptions): Promise<PostHogFlagsAndPayloadsResponse>
+  async getAllFlagsAndPayloads(distinctId: string, options?: AllFlagsOptions): Promise<PostHogFlagsAndPayloadsResponse>
   async getAllFlagsAndPayloads(
-    distinctId: string,
-    options?: {
-      groups?: Record<string, string>
-      personProperties?: Record<string, string>
-      groupProperties?: Record<string, Record<string, string>>
-      onlyEvaluateLocally?: boolean
-      disableGeoip?: boolean
-      flagKeys?: string[]
-    }
+    distinctIdOrOptions?: string | AllFlagsOptions,
+    options?: AllFlagsOptions
   ): Promise<PostHogFlagsAndPayloadsResponse> {
-    const { groups, disableGeoip, flagKeys } = options || {}
-    let { onlyEvaluateLocally, personProperties, groupProperties } = options || {}
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(
+      distinctIdOrOptions,
+      options
+    )
+    if (!resolvedDistinctId) {
+      this._logger.warn(
+        '[PostHog] distinctId is required to get feature flags and payloads — pass it explicitly or use withContext()'
+      )
+      return { featureFlags: {}, featureFlagPayloads: {} }
+    }
+
+    const { groups, disableGeoip, flagKeys } = resolvedOptions || {}
+    let { onlyEvaluateLocally, personProperties, groupProperties } = resolvedOptions || {}
 
     const adjustedProperties = this.addLocalPersonAndGroupProperties(
-      distinctId,
+      resolvedDistinctId,
       groups,
       personProperties,
       groupProperties
@@ -1226,19 +1260,19 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     personProperties = adjustedProperties.allPersonProperties
     groupProperties = adjustedProperties.allGroupProperties
+    const evaluationContext = this.createFeatureFlagEvaluationContext(
+      resolvedDistinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
 
     // set defaults
     if (onlyEvaluateLocally == undefined) {
       onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false
     }
 
-    const localEvaluationResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(
-      distinctId,
-      groups,
-      personProperties,
-      groupProperties,
-      flagKeys
-    )
+    const localEvaluationResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(evaluationContext, flagKeys)
 
     let featureFlags = {}
     let featureFlagPayloads = {}
@@ -1251,10 +1285,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     if (fallbackToFlags && !onlyEvaluateLocally) {
       const remoteEvaluationResult = await super.getFeatureFlagsAndPayloadsStateless(
-        distinctId,
-        groups,
-        personProperties,
-        groupProperties,
+        evaluationContext.distinctId,
+        evaluationContext.groups,
+        evaluationContext.personProperties,
+        evaluationContext.groupProperties,
         disableGeoip,
         flagKeys
       )
@@ -1510,6 +1544,24 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return this.context?.get()
   }
 
+  /**
+   * Set context without a callback wrapper.
+   *
+   * Uses `AsyncLocalStorage.enterWith()` to attach context to the current
+   * async execution context. The context lives until that async context ends.
+   *
+   * Must be called in the same async scope that makes PostHog calls.
+   * Calling this outside a request-scoped async context will leak context
+   * across unrelated work. Prefer `withContext()` when you can wrap code
+   * in a callback — it creates an isolated scope that cleans up automatically.
+   *
+   * @param data - Context data to apply (distinctId, sessionId, properties)
+   * @param options - Context options (fresh: true to start with clean context instead of inheriting)
+   */
+  enterContext(data: Partial<ContextData>, options?: ContextOptions): void {
+    this.context?.enter(data as ContextData, options)
+  }
+
   /**
    * Shutdown the PostHog client gracefully.
    *
@@ -1691,6 +1743,21 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return { allPersonProperties, allGroupProperties }
   }
 
+  private createFeatureFlagEvaluationContext(
+    distinctId: string,
+    groups?: Record<string, string>,
+    personProperties?: Record<string, any>,
+    groupProperties?: Record<string, Record<string, any>>
+  ): FeatureFlagEvaluationContext {
+    return {
+      distinctId,
+      groups: groups || {},
+      personProperties: personProperties || {},
+      groupProperties: groupProperties || {},
+      evaluationCache: {},
+    }
+  }
+
   /**
    * Capture an error exception as an event.
    *

package/src/extensions/context/context.ts

@@ -13,21 +13,26 @@ export class PostHogContext implements IPostHogContext {
   }
 
   run<T>(context: ContextData, fn: () => T, options?: ContextOptions): T {
-    const fresh = options?.fresh === true
+    return this.storage.run(this.resolve(context, options), fn)
+  }
+
+  enter(context: ContextData, options?: ContextOptions): void {
+    this.storage.enterWith(this.resolve(context, options))
+  }
+
+  private resolve(context: ContextData, options?: ContextOptions): ContextData {
+    if (options?.fresh === true) {
+      return context
+    }
 
-    if (fresh) {
-      return this.storage.run(context, fn)
-    } else {
-      const currentContext = this.get() || {}
-      const mergedContext: ContextData = {
-        distinctId: context.distinctId ?? currentContext.distinctId,
-        sessionId: context.sessionId ?? currentContext.sessionId,
-        properties: {
-          ...(currentContext.properties || {}),
-          ...(context.properties || {}),
-        },
-      }
-      return this.storage.run(mergedContext, fn)
+    const current = this.get() || {}
+    return {
+      distinctId: context.distinctId ?? current.distinctId,
+      sessionId: context.sessionId ?? current.sessionId,
+      properties: {
+        ...(current.properties || {}),
+        ...(context.properties || {}),
+      },
     }
   }
 }

package/src/extensions/context/types.ts

@@ -16,4 +16,5 @@ export interface ContextOptions {
 export interface IPostHogContext {
   get(): ContextData | undefined
   run<T>(context: ContextData, fn: () => T, options?: ContextOptions): T
+  enter(context: ContextData, options?: ContextOptions): void
 }

package/src/extensions/feature-flags/feature-flags.ts

@@ -58,6 +58,19 @@ type FeatureFlagsPollerOptions = {
   strictLocalEvaluation?: boolean
 }
 
+export type FeatureFlagEvaluationContext = {
+  distinctId: string
+  groups: Record<string, string>
+  personProperties: Record<string, any>
+  groupProperties: Record<string, Record<string, any>>
+  evaluationCache: Record<string, FeatureFlagValue>
+}
+
+type ComputeFlagAndPayloadOptions = {
+  matchValue?: FeatureFlagValue
+  skipLoadCheck?: boolean
+}
+
 class FeatureFlagsPoller {
   pollingInterval: number
   personalApiKey: string
@@ -122,6 +135,22 @@ class FeatureFlagsPoller {
     }
   }
 
+  private createEvaluationContext(
+    distinctId: string,
+    groups: Record<string, string> = {},
+    personProperties: Record<string, any> = {},
+    groupProperties: Record<string, Record<string, any>> = {},
+    evaluationCache: Record<string, FeatureFlagValue> = {}
+  ): FeatureFlagEvaluationContext {
+    return {
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties,
+      evaluationCache,
+    }
+  }
+
   async getFeatureFlag(
     key: string,
     distinctId: string,
@@ -141,14 +170,9 @@ class FeatureFlagsPoller {
     featureFlag = this.featureFlagsByKey[key]
 
     if (featureFlag !== undefined) {
+      const evaluationContext = this.createEvaluationContext(distinctId, groups, personProperties, groupProperties)
       try {
-        const result = await this.computeFlagAndPayloadLocally(
-          featureFlag,
-          distinctId,
-          groups,
-          personProperties,
-          groupProperties
-        )
+        const result = await this.computeFlagAndPayloadLocally(featureFlag, evaluationContext)
         response = result.value
         this.logMsgIfDebug(() => console.debug(`Successfully computed flag locally: ${key} -> ${response}`))
       } catch (e) {
@@ -164,10 +188,7 @@ class FeatureFlagsPoller {
   }
 
   async getAllFlagsAndPayloads(
-    distinctId: string,
-    groups: Record<string, string> = {},
-    personProperties: Record<string, any> = {},
-    groupProperties: Record<string, Record<string, any>> = {},
+    evaluationContext: FeatureFlagEvaluationContext,
     flagKeysToExplicitlyEvaluate?: string[]
   ): Promise<{
     response: Record<string, FeatureFlagValue>
@@ -184,20 +205,17 @@ class FeatureFlagsPoller {
       ? flagKeysToExplicitlyEvaluate.map((key) => this.featureFlagsByKey[key]).filter(Boolean)
       : this.featureFlags
 
-    // Create a shared evaluation cache to prevent memory leaks when processing many flags
-    const sharedEvaluationCache: Record<string, FeatureFlagValue> = {}
+    const sharedEvaluationContext = {
+      ...evaluationContext,
+      evaluationCache: evaluationContext.evaluationCache ?? {},
+    }
 
     await Promise.all(
       flagsToEvaluate.map(async (flag) => {
         try {
           const { value: matchValue, payload: matchPayload } = await this.computeFlagAndPayloadLocally(
             flag,
-            distinctId,
-            groups,
-            personProperties,
-            groupProperties,
-            undefined /* matchValue */,
-            sharedEvaluationCache
+            sharedEvaluationContext
           )
           response[flag.key] = matchValue
           if (matchPayload) {
@@ -219,17 +237,14 @@ class FeatureFlagsPoller {
 
   async computeFlagAndPayloadLocally(
     flag: PostHogFeatureFlag,
-    distinctId: string,
-    groups: Record<string, string> = {},
-    personProperties: Record<string, any> = {},
-    groupProperties: Record<string, Record<string, any>> = {},
-    matchValue?: FeatureFlagValue,
-    evaluationCache?: Record<string, FeatureFlagValue>,
-    skipLoadCheck: boolean = false
+    evaluationContext: FeatureFlagEvaluationContext,
+    options: ComputeFlagAndPayloadOptions = {}
   ): Promise<{
     value: FeatureFlagValue
     payload: JsonType | null
   }> {
+    const { matchValue, skipLoadCheck = false } = options
+
     // Only load flags if not already loaded and not skipping the check
     if (!skipLoadCheck) {
       await this.loadFeatureFlags()
@@ -245,14 +260,7 @@ class FeatureFlagsPoller {
     if (matchValue !== undefined) {
       flagValue = matchValue
     } else {
-      flagValue = await this.computeFlagValueLocally(
-        flag,
-        distinctId,
-        groups,
-        personProperties,
-        groupProperties,
-        evaluationCache
-      )
+      flagValue = await this.computeFlagValueLocally(flag, evaluationContext)
     }
 
     // Always compute payload based on the final flagValue (whether provided or computed)
@@ -263,12 +271,10 @@ class FeatureFlagsPoller {
 
   private async computeFlagValueLocally(
     flag: PostHogFeatureFlag,
-    distinctId: string,
-    groups: Record<string, string> = {},
-    personProperties: Record<string, any> = {},
-    groupProperties: Record<string, Record<string, any>> = {},
-    evaluationCache: Record<string, FeatureFlagValue> = {}
+    evaluationContext: FeatureFlagEvaluationContext
   ): Promise<FeatureFlagValue> {
+    const { distinctId, groups, personProperties, groupProperties } = evaluationContext
+
     if (flag.ensure_experience_continuity) {
       throw new InconclusiveMatchError('Flag has experience continuity enabled')
     }
@@ -299,32 +305,30 @@ class FeatureFlagsPoller {
         return false
       }
 
+      if (
+        flag.bucketing_identifier === 'device_id' &&
+        (personProperties?.$device_id === undefined ||
+          personProperties?.$device_id === null ||
+          personProperties?.$device_id === '')
+      ) {
+        this.logMsgIfDebug(() =>
+          console.warn(`[FEATURE FLAGS] Ignoring bucketing_identifier for group flag: ${flag.key}`)
+        )
+      }
+
       const focusedGroupProperties = groupProperties[groupName]
-      return await this.matchFeatureFlagProperties(
-        flag,
-        groups[groupName],
-        focusedGroupProperties,
-        evaluationCache,
-        distinctId,
-        groups,
-        personProperties,
-        groupProperties
-      )
+      return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties, evaluationContext)
     } else {
       const bucketingValue = this.getBucketingValueForFlag(flag, distinctId, personProperties)
       if (bucketingValue === undefined) {
+        this.logMsgIfDebug(() =>
+          console.warn(
+            `[FEATURE FLAGS] Can't compute feature flag: ${flag.key} without $device_id, falling back to server evaluation`
+          )
+        )
         throw new InconclusiveMatchError(`Can't compute feature flag: ${flag.key} without $device_id`)
       }
-      return await this.matchFeatureFlagProperties(
-        flag,
-        bucketingValue,
-        personProperties,
-        evaluationCache,
-        distinctId,
-        groups,
-        personProperties,
-        groupProperties
-      )
+      return await this.matchFeatureFlagProperties(flag, bucketingValue, personProperties, evaluationContext)
     }
   }
 
@@ -384,13 +388,10 @@ class FeatureFlagsPoller {
 
   private async evaluateFlagDependency(
     property: FlagProperty,
-    distinctId: string,
-    groups: Record<string, string>,
-    personProperties: Record<string, any>,
-    groupProperties: Record<string, Record<string, any>>,
     properties: Record<string, any>,
-    evaluationCache: Record<string, FeatureFlagValue>
+    evaluationContext: FeatureFlagEvaluationContext
   ): Promise<boolean> {
+    const { evaluationCache } = evaluationContext
     const targetFlagKey = property.key
 
     if (!this.featureFlagsByKey) {
@@ -434,14 +435,7 @@ class FeatureFlagsPoller {
         } else {
           // Reuse full flag evaluation so dependencies respect person vs group bucketing rules.
           try {
-            const depResult = await this.computeFlagValueLocally(
-              depFlag,
-              distinctId,
-              groups,
-              personProperties,
-              groupProperties,
-              evaluationCache
-            )
+            const depResult = await this.computeFlagValueLocally(depFlag, evaluationContext)
             evaluationCache[depFlagKey] = depResult
           } catch (error) {
             throw new InconclusiveMatchError(
@@ -486,11 +480,7 @@ class FeatureFlagsPoller {
     flag: PostHogFeatureFlag,
     bucketingValue: string,
     properties: Record<string, any>,
-    evaluationCache: Record<string, FeatureFlagValue> = {},
-    distinctId: string = bucketingValue,
-    groups: Record<string, string> = {},
-    personProperties: Record<string, any> = {},
-    groupProperties: Record<string, Record<string, any>> = {}
+    evaluationContext: FeatureFlagEvaluationContext
   ): Promise<FeatureFlagValue> {
     const flagFilters = flag.filters || {}
     const flagConditions = flagFilters.groups || []
@@ -499,19 +489,7 @@ class FeatureFlagsPoller {
 
     for (const condition of flagConditions) {
       try {
-        if (
-          await this.isConditionMatch(
-            flag,
-            bucketingValue,
-            condition,
-            properties,
-            evaluationCache,
-            distinctId,
-            groups,
-            personProperties,
-            groupProperties
-          )
-        ) {
+        if (await this.isConditionMatch(flag, bucketingValue, condition, properties, evaluationContext)) {
           const variantOverride = condition.variant
           const flagVariants = flagFilters.multivariate?.variants || []
           if (variantOverride && flagVariants.some((variant) => variant.key === variantOverride)) {
@@ -551,11 +529,7 @@ class FeatureFlagsPoller {
     bucketingValue: string,
     condition: FeatureFlagCondition,
     properties: Record<string, any>,
-    evaluationCache: Record<string, FeatureFlagValue> = {},
-    distinctId: string = bucketingValue,
-    groups: Record<string, string> = {},
-    personProperties: Record<string, any> = {},
-    groupProperties: Record<string, Record<string, any>> = {}
+    evaluationContext: FeatureFlagEvaluationContext
   ): Promise<boolean> {
     const rolloutPercentage = condition.rollout_percentage
     const warnFunction = (msg: string): void => {
@@ -569,15 +543,7 @@ class FeatureFlagsPoller {
         if (propertyType === 'cohort') {
           matches = matchCohort(prop, properties, this.cohorts, this.debugMode)
         } else if (propertyType === 'flag') {
-          matches = await this.evaluateFlagDependency(
-            prop,
-            distinctId,
-            groups,
-            personProperties,
-            groupProperties,
-            properties,
-            evaluationCache
-          )
+          matches = await this.evaluateFlagDependency(prop, properties, evaluationContext)
         } else {
           matches = matchProperty(prop, properties, warnFunction)
         }