posthog-node 5.32.1 → 5.33.0

package/src/client.ts

@@ -28,6 +28,12 @@ import {
   FlagEvaluationOptions,
   AllFlagsOptions,
 } from './types'
+import {
+  EvaluatedFlagRecord,
+  FeatureFlagEvaluations,
+  FeatureFlagEvaluationsHost,
+  FlagCalledEventParams,
+} from './feature-flag-evaluations'
 import {
   FeatureFlagsPoller,
   type FeatureFlagEvaluationContext,
@@ -50,6 +56,26 @@ const WAITUNTIL_DEBOUNCE_MS = 50
 const WAITUNTIL_MAX_WAIT_MS = 500
 const DEFAULT_NODE_HOST = 'https://us.i.posthog.com'
 
+// Process-wide dedup for deprecation warnings — without this, calling a deprecated
+// method in a loop would spam logs. Matches Python's `warnings.warn` default-dedup behavior.
+const _emittedDeprecations = new Set<string>()
+
+function emitDeprecationWarningOnce(id: string, message: string): void {
+  if (_emittedDeprecations.has(id)) {
+    return
+  }
+  _emittedDeprecations.add(id)
+  // eslint-disable-next-line no-console
+  console.warn(`[PostHog] ${message}`)
+}
+
+/**
+ * @internal — clears the process-wide deprecation dedup set. Test-only.
+ */
+export function _resetDeprecationWarningsForTests(): void {
+  _emittedDeprecations.clear()
+}
+
 function normalizeApiKey(value?: unknown): string {
   return typeof value === 'string' ? value.trim() : ''
 }
@@ -64,6 +90,27 @@ function normalizeHost(value?: unknown): string {
   return normalizedValue || DEFAULT_NODE_HOST
 }
 
+/**
+ * Derive `$feature/{key}` and `$active_feature_flags` event properties from a flat
+ * `{ key: value }` map returned by the legacy `sendFeatureFlags` path.
+ */
+function buildFlagEventProperties(flagValues: Record<string, FeatureFlagValue> | undefined): Record<string, any> {
+  if (!flagValues) {
+    return {}
+  }
+  const additionalProperties: Record<string, any> = {}
+  for (const [feature, variant] of Object.entries(flagValues)) {
+    additionalProperties[`$feature/${feature}`] = variant
+  }
+  const activeFlags = Object.keys(flagValues)
+    .filter((flag) => flagValues[flag] !== false)
+    .sort()
+  if (activeFlags.length > 0) {
+    additionalProperties['$active_feature_flags'] = activeFlags
+  }
+  return additionalProperties
+}
+
 // The actual exported Nodejs API.
 export abstract class PostHogBackendClient extends PostHogCoreStateless implements IPostHog {
   private _memoryStorage = new PostHogMemoryStorage()
@@ -921,56 +968,38 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     // Send feature flag event if configured
     if (sendFeatureFlagEvents) {
-      // Compute the response value for event tracking
       const response = result === undefined ? undefined : result.enabled === false ? false : (result.variant ?? true)
-      const featureFlagReportedKey = `${key}_${response}`
-
-      if (
-        !(distinctId in this.distinctIdHasSentFlagCalls) ||
-        !this.distinctIdHasSentFlagCalls[distinctId].includes(featureFlagReportedKey)
-      ) {
-        if (Object.keys(this.distinctIdHasSentFlagCalls).length >= this.maxCacheSize) {
-          this.distinctIdHasSentFlagCalls = {}
-        }
-        if (Array.isArray(this.distinctIdHasSentFlagCalls[distinctId])) {
-          this.distinctIdHasSentFlagCalls[distinctId].push(featureFlagReportedKey)
-        } else {
-          this.distinctIdHasSentFlagCalls[distinctId] = [featureFlagReportedKey]
-        }
-
-        const properties: Record<string, any> = {
-          $feature_flag: key,
-          $feature_flag_response: response,
-          $feature_flag_id: flagId,
-          $feature_flag_version: flagVersion,
-          $feature_flag_reason: flagReason,
-          locally_evaluated: flagWasLocallyEvaluated,
-          [`$feature/${key}`]: response,
-          $feature_flag_request_id: requestId,
-          $feature_flag_evaluated_at: flagWasLocallyEvaluated ? Date.now() : evaluatedAt,
-        }
-
-        // Add local evaluation definition load timestamp
-        if (flagWasLocallyEvaluated && this.featureFlagsPoller) {
-          const flagDefinitionsLoadedAt = this.featureFlagsPoller.getFlagDefinitionsLoadedAt()
-
-          if (flagDefinitionsLoadedAt !== undefined) {
-            properties.$feature_flag_definitions_loaded_at = flagDefinitionsLoadedAt
-          }
-        }
+      const properties: Record<string, any> = {
+        $feature_flag: key,
+        $feature_flag_response: response,
+        $feature_flag_id: flagId,
+        $feature_flag_version: flagVersion,
+        $feature_flag_reason: flagReason,
+        locally_evaluated: flagWasLocallyEvaluated,
+        [`$feature/${key}`]: response,
+        $feature_flag_request_id: requestId,
+        $feature_flag_evaluated_at: flagWasLocallyEvaluated ? Date.now() : evaluatedAt,
+      }
 
-        if (featureFlagError) {
-          properties.$feature_flag_error = featureFlagError
+      if (flagWasLocallyEvaluated && this.featureFlagsPoller) {
+        const flagDefinitionsLoadedAt = this.featureFlagsPoller.getFlagDefinitionsLoadedAt()
+        if (flagDefinitionsLoadedAt !== undefined) {
+          properties.$feature_flag_definitions_loaded_at = flagDefinitionsLoadedAt
         }
+      }
 
-        this.capture({
-          distinctId,
-          event: '$feature_flag_called',
-          properties,
-          groups,
-          disableGeoip,
-        })
+      if (featureFlagError) {
+        properties.$feature_flag_error = featureFlagError
       }
+
+      this._captureFlagCalledEventIfNeeded({
+        distinctId,
+        key,
+        response,
+        groups,
+        disableGeoip,
+        properties,
+      })
     }
 
     // Apply payload override if present (even when there's no flag override)
@@ -1021,6 +1050,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * {@label Feature flags}
    *
+   * @deprecated Use {@link evaluateFlags} and call `flags.getFlag(key)` on the returned snapshot.
+   *   This consolidates flag evaluation into a single `/flags` request per incoming request and
+   *   avoids drift between the values your code branched on and the values attached to events.
+   *   Will be removed in the next major version.
+   *
    * @param key - The feature flag key
    * @param distinctId - The user's distinct ID
    * @param options - Optional configuration for flag evaluation
@@ -1038,6 +1072,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       disableGeoip?: boolean
     }
   ): Promise<FeatureFlagValue | undefined> {
+    emitDeprecationWarningOnce(
+      'getFeatureFlag',
+      '`getFeatureFlag` is deprecated and will be removed in a future major version. ' +
+        'Use `posthog.evaluateFlags(distinctId, ...)` and call `flags.getFlag(key)` instead — ' +
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+    )
     const result = await this._getFeatureFlagResult(key, distinctId, {
       ...options,
       sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true,
@@ -1080,6 +1120,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * {@label Feature flags}
    *
+   * @deprecated Use {@link evaluateFlags} and call `flags.getFlagPayload(key)` on the returned
+   *   snapshot. This consolidates flag evaluation into a single `/flags` request per incoming
+   *   request. Will be removed in the next major version.
+   *
    * @param key - The feature flag key
    * @param distinctId - The user's distinct ID
    * @param matchValue - Optional match value to get payload for
@@ -1100,6 +1144,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       disableGeoip?: boolean
     }
   ): Promise<JsonType | undefined> {
+    emitDeprecationWarningOnce(
+      'getFeatureFlagPayload',
+      '`getFeatureFlagPayload` is deprecated and will be removed in a future major version. ' +
+        'Use `posthog.evaluateFlags(distinctId, ...)` and call `flags.getFlagPayload(key)` instead — ' +
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+    )
     // Check for payload overrides first - they take precedence over all evaluation
     // This is checked independently from flag overrides
     if (this._payloadOverrides !== undefined && key in this._payloadOverrides) {
@@ -1254,6 +1304,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * {@label Feature flags}
    *
+   * @deprecated Use {@link evaluateFlags} and call `flags.isEnabled(key)` on the returned snapshot.
+   *   This consolidates flag evaluation into a single `/flags` request per incoming request.
+   *   Will be removed in the next major version.
+   *
    * @param key - The feature flag key
    * @param distinctId - The user's distinct ID
    * @param options - Optional configuration for flag evaluation
@@ -1271,10 +1325,24 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       disableGeoip?: boolean
     }
   ): Promise<boolean | undefined> {
-    const feat = await this.getFeatureFlag(key, distinctId, options)
-    if (feat === undefined) {
+    emitDeprecationWarningOnce(
+      'isFeatureEnabled',
+      '`isFeatureEnabled` is deprecated and will be removed in a future major version. ' +
+        'Use `posthog.evaluateFlags(distinctId, ...)` and call `flags.isEnabled(key)` instead — ' +
+        'this consolidates flag evaluation into a single `/flags` request per incoming request.'
+    )
+    // Bypass the public `getFeatureFlag` so the user only sees one deprecation warning per call.
+    const result = await this._getFeatureFlagResult(key, distinctId, {
+      ...options,
+      sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true,
+    })
+    if (result === undefined) {
       return undefined
     }
+    if (result.enabled === false) {
+      return false
+    }
+    const feat: FeatureFlagValue = result.variant ?? true
     return !!feat || false
   }
 
@@ -1454,6 +1522,286 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return { featureFlags, featureFlagPayloads }
   }
 
+  /**
+   * Evaluate all feature flags for a user in a single call and return a
+   * {@link FeatureFlagEvaluations} snapshot. Branch on `.isEnabled()` / `.getFlag()`,
+   * then pass the same snapshot to `capture()` via the `flags` option so the
+   * captured event carries the exact flag values the code branched on.
+   *
+   * Prefer this over repeated `isFeatureEnabled()` / `getFeatureFlag()` calls and
+   * over `capture({ sendFeatureFlags: true })` — it consolidates flag evaluation
+   * into a single `/flags` request per incoming request.
+   *
+   * **Local evaluation is transparent.** When the poller can resolve a flag from
+   * cached definitions, no network call is made and the snapshot's `$feature_flag_called`
+   * events are tagged `locally_evaluated: true`.
+   *
+   * **Trim the request.** Pass `flagKeys` to scope the underlying `/flags` request
+   * to a subset of flags — useful when you only need a few flags and want to reduce
+   * the response payload.
+   *
+   * **Trim the event payload.** Use `flags.only([...])` or `flags.onlyAccessed()`
+   * to filter which flags get attached to a captured event without re-fetching.
+   *
+   * @example
+   * Basic usage:
+   * ```ts
+   * const flags = await client.evaluateFlags('user_123', {
+   *   personProperties: { plan: 'enterprise' },
+   * })
+   * if (flags.isEnabled('new-dashboard')) {
+   *   renderNewDashboard()
+   * }
+   * client.capture({ distinctId: 'user_123', event: 'page_viewed', flags })
+   * ```
+   *
+   * @example
+   * Scope the `/flags` request to specific keys:
+   * ```ts
+   * const flags = await client.evaluateFlags('user_123', {
+   *   flagKeys: ['new-dashboard', 'checkout-flow'],
+   *   personProperties: { plan: 'enterprise' },
+   * })
+   * ```
+   *
+   * @example
+   * Attach only the flags the developer actually checked:
+   * ```ts
+   * const flags = await client.evaluateFlags('user_123')
+   * if (flags.isEnabled('new-dashboard')) { ... }
+   * client.capture({ distinctId: 'user_123', event: 'page_viewed', flags: flags.onlyAccessed() })
+   * ```
+   *
+   * @example
+   * Use `withContext()` to avoid repeating the distinctId:
+   * ```ts
+   * await client.withContext({ distinctId: 'user_123' }, async () => {
+   *   const flags = await client.evaluateFlags()
+   *   if (flags.isEnabled('new-dashboard')) { ... }
+   *   client.capture({ event: 'page_viewed', flags })
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param distinctIdOrOptions - The user's distinct ID, or options when the distinctId comes from `withContext()`
+   * @param options - Optional configuration for flag evaluation. Supports the same fields as `getAllFlags()`, including `flagKeys` to scope the `/flags` request.
+   * @returns Promise that resolves to a `FeatureFlagEvaluations` snapshot
+   */
+  async evaluateFlags(options?: AllFlagsOptions): Promise<FeatureFlagEvaluations>
+  async evaluateFlags(distinctId: string, options?: AllFlagsOptions): Promise<FeatureFlagEvaluations>
+  async evaluateFlags(
+    distinctIdOrOptions?: string | AllFlagsOptions,
+    options?: AllFlagsOptions
+  ): Promise<FeatureFlagEvaluations> {
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(
+      distinctIdOrOptions,
+      options
+    )
+
+    if (!resolvedDistinctId) {
+      this._logger.warn(
+        '[PostHog] distinctId is required to evaluate feature flags — pass it explicitly or use withContext()'
+      )
+      return new FeatureFlagEvaluations({
+        host: this._getFeatureFlagEvaluationsHost(),
+        distinctId: '',
+        flags: {},
+      })
+    }
+
+    const { groups, disableGeoip, flagKeys } = resolvedOptions || {}
+    let { onlyEvaluateLocally, personProperties, groupProperties } = resolvedOptions || {}
+
+    const adjustedProperties = this.addLocalPersonAndGroupProperties(
+      resolvedDistinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+    personProperties = adjustedProperties.allPersonProperties
+    groupProperties = adjustedProperties.allGroupProperties
+    const evaluationContext = this.createFeatureFlagEvaluationContext(
+      resolvedDistinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false
+    }
+
+    const records: Record<string, EvaluatedFlagRecord> = {}
+    let requestId: string | undefined = undefined
+    let evaluatedAt: number | undefined = undefined
+    let errorsWhileComputing = false
+    let quotaLimited = false
+
+    // Try local evaluation first and decorate each flag with metadata from the poller.
+    // `flagKeys` scopes the evaluation to a subset of definitions when provided.
+    const localResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(evaluationContext, flagKeys)
+    const locallyEvaluatedKeys = new Set<string>()
+    if (localResult) {
+      for (const [key, value] of Object.entries(localResult.response)) {
+        const flagDef = this.featureFlagsPoller?.featureFlagsByKey[key]
+        records[key] = {
+          key,
+          enabled: value !== false,
+          variant: typeof value === 'string' ? value : undefined,
+          payload: localResult.payloads[key],
+          id: flagDef?.id,
+          // The local-evaluation flag definition (`PostHogFeatureFlag`) does not carry a
+          // version field; only the remote `/flags` response does via `metadata.version`.
+          version: undefined,
+          reason: 'Evaluated locally',
+          locallyEvaluated: true,
+        }
+        locallyEvaluatedKeys.add(key)
+      }
+    }
+
+    // Fall back to remote evaluation for any flags the poller couldn't resolve locally.
+    // We use the detail-shaped endpoint so the resulting records carry id/version/reason
+    // and fired $feature_flag_called events match what isFeatureEnabled()/getFeatureFlag() emit.
+    const fallbackToFlags = localResult ? localResult.fallbackToFlags : true
+    if (fallbackToFlags && !onlyEvaluateLocally) {
+      const details = await super.getFeatureFlagDetailsStateless(
+        evaluationContext.distinctId,
+        evaluationContext.groups,
+        evaluationContext.personProperties,
+        evaluationContext.groupProperties,
+        disableGeoip,
+        flagKeys
+      )
+      if (details) {
+        requestId = details.requestId
+        evaluatedAt = details.evaluatedAt
+        errorsWhileComputing = Boolean((details as any).errorsWhileComputingFlags)
+        quotaLimited = Array.isArray(details.quotaLimited) && details.quotaLimited.includes('feature_flags')
+        for (const [key, detail] of Object.entries(details.flags)) {
+          if (locallyEvaluatedKeys.has(key)) {
+            continue
+          }
+          let parsedPayload: JsonType | undefined = undefined
+          if (detail.metadata?.payload !== undefined) {
+            try {
+              parsedPayload = JSON.parse(detail.metadata.payload)
+            } catch {
+              parsedPayload = detail.metadata.payload
+            }
+          }
+          records[key] = {
+            key,
+            enabled: detail.enabled,
+            variant: detail.variant,
+            payload: parsedPayload,
+            id: detail.metadata?.id,
+            version: detail.metadata?.version,
+            reason: detail.reason?.description ?? detail.reason?.code,
+            locallyEvaluated: false,
+          }
+        }
+      }
+    }
+
+    // Apply overrides last so they take precedence over evaluation.
+    if (this._flagOverrides !== undefined) {
+      for (const [key, value] of Object.entries(this._flagOverrides)) {
+        if (value === undefined) {
+          delete records[key]
+          continue
+        }
+        const existing = records[key]
+        records[key] = {
+          key,
+          enabled: value !== false,
+          variant: typeof value === 'string' ? value : undefined,
+          payload: existing?.payload,
+          id: existing?.id,
+          version: existing?.version,
+          reason: existing?.reason,
+          locallyEvaluated: existing?.locallyEvaluated ?? false,
+        }
+      }
+    }
+    if (this._payloadOverrides !== undefined) {
+      for (const [key, payload] of Object.entries(this._payloadOverrides)) {
+        const existing = records[key]
+        if (existing) {
+          records[key] = { ...existing, payload }
+        }
+      }
+    }
+
+    return new FeatureFlagEvaluations({
+      host: this._getFeatureFlagEvaluationsHost(),
+      distinctId: resolvedDistinctId,
+      groups,
+      disableGeoip,
+      flags: records,
+      requestId,
+      evaluatedAt,
+      flagDefinitionsLoadedAt: this.featureFlagsPoller?.getFlagDefinitionsLoadedAt(),
+      errorsWhileComputing,
+      quotaLimited,
+    })
+  }
+
+  /**
+   * Fires a `$feature_flag_called` event for the given flag if the (distinctId, flag, response)
+   * triple hasn't already been reported for this client. Shared by the single-flag evaluation
+   * path and `FeatureFlagEvaluations.isEnabled() / getFlag()` so both paths dedupe identically.
+   *
+   * @internal
+   */
+  protected _captureFlagCalledEventIfNeeded(params: FlagCalledEventParams): void {
+    const { distinctId, key, response, groups, disableGeoip, properties } = params
+    const featureFlagReportedKey = `${key}_${response}`
+
+    if (
+      distinctId in this.distinctIdHasSentFlagCalls &&
+      this.distinctIdHasSentFlagCalls[distinctId].includes(featureFlagReportedKey)
+    ) {
+      return
+    }
+
+    if (Object.keys(this.distinctIdHasSentFlagCalls).length >= this.maxCacheSize) {
+      this.distinctIdHasSentFlagCalls = {}
+    }
+    if (Array.isArray(this.distinctIdHasSentFlagCalls[distinctId])) {
+      this.distinctIdHasSentFlagCalls[distinctId].push(featureFlagReportedKey)
+    } else {
+      this.distinctIdHasSentFlagCalls[distinctId] = [featureFlagReportedKey]
+    }
+
+    this.capture({
+      distinctId,
+      event: '$feature_flag_called',
+      properties,
+      groups,
+      disableGeoip,
+    })
+  }
+
+  private _featureFlagEvaluationsHost?: FeatureFlagEvaluationsHost
+
+  private _getFeatureFlagEvaluationsHost(): FeatureFlagEvaluationsHost {
+    if (!this._featureFlagEvaluationsHost) {
+      this._featureFlagEvaluationsHost = {
+        captureFlagCalledEventIfNeeded: (params) => this._captureFlagCalledEventIfNeeded(params),
+        logWarning: (message) => {
+          if (this.options.featureFlagsLogWarnings !== false) {
+            // These warnings guide API usage (misuse of `onlyAccessed()` / `only()`) and
+            // should always surface — unlike `this._logger.warn` which is gated on debug mode.
+            console.warn(`[PostHog] ${message}`)
+          }
+        },
+      }
+    }
+    return this._featureFlagEvaluationsHost
+  }
+
   /**
    * Create or update a group and its properties.
    *
@@ -1933,18 +2281,21 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param error - The error to capture
    * @param distinctId - Optional user distinct ID
    * @param additionalProperties - Optional additional properties to include
+   * @param uuid - Optional event UUID
+   * @param flags - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
    */
   captureException(
     error: unknown,
     distinctId?: string,
     additionalProperties?: Record<string | number, any>,
-    uuid?: EventMessage['uuid']
+    uuid?: EventMessage['uuid'],
+    flags?: FeatureFlagEvaluations
   ): void {
     if (!ErrorTracking.isPreviouslyCapturedError(error)) {
       const syntheticException = new Error('PostHog syntheticException')
       this.addPendingPromise(
         ErrorTracking.buildEventMessage(error, { syntheticException }, distinctId, additionalProperties).then((msg) =>
-          this.capture({ ...msg, uuid })
+          this.capture({ ...msg, uuid, flags })
         )
       )
     }
@@ -1983,18 +2334,20 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param error - The error to capture
    * @param distinctId - Optional user distinct ID
    * @param additionalProperties - Optional additional properties to include
+   * @param flags - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
    * @returns Promise that resolves when the error is captured
    */
   async captureExceptionImmediate(
     error: unknown,
     distinctId?: string,
-    additionalProperties?: Record<string | number, any>
+    additionalProperties?: Record<string | number, any>,
+    flags?: FeatureFlagEvaluations
   ): Promise<void> {
     if (!ErrorTracking.isPreviouslyCapturedError(error)) {
       const syntheticException = new Error('PostHog syntheticException')
       return this.addPendingPromise(
         ErrorTracking.buildEventMessage(error, { syntheticException }, distinctId, additionalProperties).then((msg) =>
-          this.captureImmediate(msg)
+          this.captureImmediate({ ...msg, flags })
         )
       )
     }
@@ -2006,8 +2359,17 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     properties: PostHogEventProperties
     options: PostHogCaptureOptions
   }> {
-    const { distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip, uuid }: EventMessage =
-      props
+    const {
+      distinctId,
+      event,
+      properties,
+      groups,
+      flags,
+      sendFeatureFlags,
+      timestamp,
+      disableGeoip,
+      uuid,
+    }: EventMessage = props
 
     const contextData = this.context?.get()
 
@@ -2034,6 +2396,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       event,
       properties: mergedProperties,
       groups,
+      flags,
       sendFeatureFlags,
       timestamp,
       disableGeoip,
@@ -2047,40 +2410,42 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     // :TRICKY: If we flush, or need to shut down, to not lose events we want this promise to resolve before we flush
     const eventProperties = await Promise.resolve()
       .then(async () => {
+        // Precedence: an explicit `flags` snapshot always wins, regardless of
+        // `sendFeatureFlags`. The snapshot guarantees the event carries the same
+        // values the developer branched on with no additional network call. The
+        // `sendFeatureFlags` path only runs when no snapshot is provided.
+        if (flags) {
+          if (sendFeatureFlags) {
+            console.warn(
+              '[PostHog] Both `flags` and `sendFeatureFlags` were passed to capture(); using `flags` and ignoring `sendFeatureFlags`.'
+            )
+          }
+          return flags._getEventProperties()
+        }
+
         if (sendFeatureFlags) {
+          emitDeprecationWarningOnce(
+            'sendFeatureFlags',
+            '`sendFeatureFlags` is deprecated and will be removed in a future major version. ' +
+              'Pass a `flags` snapshot from `posthog.evaluateFlags(...)` instead — it avoids a ' +
+              'second `/flags` request per capture and guarantees the event carries the exact ' +
+              'flag values your code branched on.'
+          )
           // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
           const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined
-          return await this.getFeatureFlagsForEvent(
+          const flagValues = await this.getFeatureFlagsForEvent(
             eventMessage.distinctId!,
             groups,
             disableGeoip,
             sendFeatureFlagsOptions
           )
+          return buildFlagEventProperties(flagValues)
         }
 
-        if (eventMessage.event === '$feature_flag_called') {
-          // If we're capturing a $feature_flag_called event, we don't want to enrich the event with cached flags that may be out of date.
-          return {}
-        }
+        // $feature_flag_called events are not enriched with cached flags — the flags
+        // on that event should reflect the specific call, not a potentially stale snapshot.
         return {}
       })
-      .then((flags) => {
-        // Derive the relevant flag properties to add
-        const additionalProperties: Record<string, any> = {}
-        if (flags) {
-          for (const [feature, variant] of Object.entries(flags)) {
-            additionalProperties[`$feature/${feature}`] = variant
-          }
-        }
-        const activeFlags = Object.keys(flags || {})
-          .filter((flag) => flags?.[flag] !== false)
-          .sort()
-        if (activeFlags.length > 0) {
-          additionalProperties['$active_feature_flags'] = activeFlags
-        }
-
-        return additionalProperties
-      })
       .catch(() => {
         // Something went wrong getting the flag info - we should capture the event anyways
         return {}

package/src/exports.ts

@@ -2,6 +2,8 @@ export * from './extensions/sentry-integration'
 export * from './extensions/express'
 export * from './types'
 
+export { FeatureFlagEvaluations } from './feature-flag-evaluations'
+
 // Re-export FeatureFlagError from core for backwards compatibility.
 // These were originally defined in posthog-node and moved to core for reuse across SDKs.
 export { FeatureFlagError } from '@posthog/core'