posthog-node 5.32.1 → 5.33.0

package/src/feature-flag-evaluations.ts

@@ -0,0 +1,321 @@
+import { FeatureFlagValue, JsonType } from '@posthog/core'
+
+import { FeatureFlagError } from './types'
+
+/**
+ * Internal per-flag record stored by a {@link FeatureFlagEvaluations} instance.
+ * Not part of the public API.
+ *
+ * @internal
+ */
+export type EvaluatedFlagRecord = {
+  key: string
+  enabled: boolean
+  variant: string | undefined
+  payload: JsonType | undefined
+  id: number | undefined
+  version: number | undefined
+  reason: string | undefined
+  locallyEvaluated: boolean
+}
+
+/**
+ * Parameters passed to the host when a `$feature_flag_called` event should be captured.
+ *
+ * @internal
+ */
+export type FlagCalledEventParams = {
+  distinctId: string
+  key: string
+  response: FeatureFlagValue | undefined
+  groups: Record<string, string | number> | undefined
+  disableGeoip: boolean | undefined
+  properties: Record<string, any>
+}
+
+/**
+ * Thin interface the evaluations object uses to talk back to the PostHog client.
+ * Keeps the class decoupled from the full client surface area.
+ *
+ * @internal
+ */
+export interface FeatureFlagEvaluationsHost {
+  captureFlagCalledEventIfNeeded(params: FlagCalledEventParams): void
+  logWarning(message: string): void
+}
+
+/**
+ * A snapshot of feature flag evaluations for a single distinctId at a point in time.
+ *
+ * Returned by {@link IPostHog.evaluateFlags} — branch on `isEnabled()` / `getFlag()`
+ * and pass the same object to `capture()` via the `flags` option so the captured event
+ * carries the exact flag values the code branched on.
+ *
+ * ```ts
+ * const flags = await posthog.evaluateFlags(distinctId, { personProperties: { plan: 'enterprise' } })
+ *
+ * if (flags.isEnabled('new-dashboard')) {
+ *   renderNewDashboard()
+ * }
+ *
+ * posthog.capture({ distinctId, event: 'page_viewed', flags })
+ * ```
+ *
+ * To narrow the set of flags that get attached to a captured event, use the in-memory
+ * helpers `only([...])` and `onlyAccessed()`. To narrow the set of flags requested from
+ * the server in the first place, pass `flagKeys` to `evaluateFlags()`.
+ */
+export class FeatureFlagEvaluations {
+  private readonly _host: FeatureFlagEvaluationsHost
+  private readonly _distinctId: string
+  private readonly _groups: Record<string, string | number> | undefined
+  private readonly _disableGeoip: boolean | undefined
+  private readonly _flags: Record<string, EvaluatedFlagRecord>
+  private readonly _requestId: string | undefined
+  private readonly _evaluatedAt: number | undefined
+  private readonly _flagDefinitionsLoadedAt: number | undefined
+  private readonly _errorsWhileComputing: boolean
+  private readonly _quotaLimited: boolean
+  private readonly _accessed: Set<string>
+  // True for snapshots produced by `only()` / `onlyAccessed()` — used to suppress
+  // misleading `flag_missing` events when branching is performed on a filtered slice.
+  private readonly _isSlice: boolean
+
+  /**
+   * @internal — instances are created by the SDK via `posthog.evaluateFlags()`.
+   */
+  constructor(init: {
+    host: FeatureFlagEvaluationsHost
+    distinctId: string
+    groups?: Record<string, string | number>
+    disableGeoip?: boolean
+    flags: Record<string, EvaluatedFlagRecord>
+    requestId?: string
+    evaluatedAt?: number
+    flagDefinitionsLoadedAt?: number
+    errorsWhileComputing?: boolean
+    quotaLimited?: boolean
+    accessed?: Set<string>
+    isSlice?: boolean
+  }) {
+    this._host = init.host
+    this._distinctId = init.distinctId
+    this._groups = init.groups
+    this._disableGeoip = init.disableGeoip
+    this._flags = init.flags
+    this._requestId = init.requestId
+    this._evaluatedAt = init.evaluatedAt
+    this._flagDefinitionsLoadedAt = init.flagDefinitionsLoadedAt
+    this._errorsWhileComputing = init.errorsWhileComputing ?? false
+    this._quotaLimited = init.quotaLimited ?? false
+    this._accessed = init.accessed ?? new Set()
+    this._isSlice = init.isSlice ?? false
+  }
+
+  /**
+   * Check whether a feature flag is enabled. Fires a `$feature_flag_called` event
+   * on the first access per (distinctId, flag, value) tuple, deduped via the SDK's
+   * existing cache.
+   *
+   * Flags that were not returned from the underlying evaluation are treated as
+   * disabled (returns `false`).
+   */
+  isEnabled(key: string): boolean {
+    const flag = this._flags[key]
+    this._recordAccess(key)
+    return flag?.enabled ?? false
+  }
+
+  /**
+   * Get the evaluated value of a feature flag. Fires a `$feature_flag_called` event
+   * on the first access per (distinctId, flag, value) tuple.
+   *
+   * Returns the variant string for multivariate flags, `true` for enabled flags
+   * without a variant, `false` for disabled flags, and `undefined` for flags that
+   * were not returned by the evaluation.
+   */
+  getFlag(key: string): FeatureFlagValue | undefined {
+    const flag = this._flags[key]
+    this._recordAccess(key)
+    if (!flag) {
+      return undefined
+    }
+    if (!flag.enabled) {
+      return false
+    }
+    return flag.variant ?? true
+  }
+
+  /**
+   * Get the payload associated with a feature flag. Does not count as an access
+   * for `onlyAccessed()` and does not fire any event.
+   */
+  getFlagPayload(key: string): JsonType | undefined {
+    return this._flags[key]?.payload
+  }
+
+  /**
+   * Return a filtered copy containing only flags that have been accessed via
+   * `isEnabled()` or `getFlag()` before this call.
+   *
+   * Order-dependent: if nothing has been accessed yet, the returned snapshot is
+   * empty. The method honors its name — pre-access if you want a populated result.
+   *
+   * **Note:** the returned snapshot is intended for `capture()`, not for further
+   * branching. Calling `isEnabled()` / `getFlag()` on it for a key that was filtered
+   * out is a no-op (no event is fired) — the flag wasn't actually missing, it was
+   * excluded from the slice.
+   */
+  onlyAccessed(): FeatureFlagEvaluations {
+    const filtered: Record<string, EvaluatedFlagRecord> = {}
+    for (const key of this._accessed) {
+      const flag = this._flags[key]
+      if (flag) {
+        filtered[key] = flag
+      }
+    }
+    return this._cloneWith(filtered)
+  }
+
+  /**
+   * Return a filtered copy containing only flags with the given keys. Keys that
+   * are not present in the evaluation are dropped and logged as a warning.
+   *
+   * **Note:** like `onlyAccessed()`, the returned snapshot is intended for `capture()`.
+   * Branching on a filtered key that was excluded from the slice is a no-op.
+   */
+  only(keys: string[]): FeatureFlagEvaluations {
+    const filtered: Record<string, EvaluatedFlagRecord> = {}
+    const missing: string[] = []
+    for (const key of keys) {
+      const flag = this._flags[key]
+      if (flag) {
+        filtered[key] = flag
+      } else {
+        missing.push(key)
+      }
+    }
+    if (missing.length > 0) {
+      this._host.logWarning(
+        `FeatureFlagEvaluations.only() was called with flag keys that are not in the evaluation set and will be dropped: ${missing.join(', ')}`
+      )
+    }
+    return this._cloneWith(filtered)
+  }
+
+  /**
+   * Returns the flag keys that are part of this evaluation.
+   */
+  get keys(): string[] {
+    return Object.keys(this._flags)
+  }
+
+  /**
+   * Build the `$feature/*` and `$active_feature_flags` event properties derived
+   * from the current flag set. Called by `capture()` when an event is captured
+   * with `flags: ...`.
+   *
+   * @internal
+   */
+  _getEventProperties(): Record<string, any> {
+    const properties: Record<string, any> = {}
+    const activeFlags: string[] = []
+    for (const [key, flag] of Object.entries(this._flags)) {
+      const value = flag.enabled === false ? false : (flag.variant ?? true)
+      properties[`$feature/${key}`] = value
+      if (flag.enabled) {
+        activeFlags.push(key)
+      }
+    }
+    if (activeFlags.length > 0) {
+      activeFlags.sort()
+      properties['$active_feature_flags'] = activeFlags
+    }
+    return properties
+  }
+
+  private _cloneWith(flags: Record<string, EvaluatedFlagRecord>): FeatureFlagEvaluations {
+    return new FeatureFlagEvaluations({
+      host: this._host,
+      distinctId: this._distinctId,
+      groups: this._groups,
+      disableGeoip: this._disableGeoip,
+      flags,
+      requestId: this._requestId,
+      evaluatedAt: this._evaluatedAt,
+      flagDefinitionsLoadedAt: this._flagDefinitionsLoadedAt,
+      errorsWhileComputing: this._errorsWhileComputing,
+      quotaLimited: this._quotaLimited,
+      // Copy the accessed set so the child can track further access independently
+      // of the parent. Callers expect `onlyAccessed()` on the parent to reflect
+      // only what the parent saw, not what happened on filtered views.
+      accessed: new Set(this._accessed),
+      isSlice: true,
+    })
+  }
+
+  private _recordAccess(key: string): void {
+    this._accessed.add(key)
+
+    // Empty snapshots (no resolvable distinctId) are returned by `evaluateFlags()` as a
+    // safety fallback. Firing $feature_flag_called for them would emit events with an
+    // empty distinct_id, polluting analytics — short-circuit here instead.
+    if (this._distinctId === '') {
+      return
+    }
+
+    // On filtered slices (returned by `only()` / `onlyAccessed()`), a key absent from
+    // the slice doesn't mean the flag is missing from PostHog — it was filtered out.
+    // Don't fire a misleading `flag_missing` event; slices are intended for `capture()`,
+    // not for further branching.
+    if (this._isSlice && !(key in this._flags)) {
+      return
+    }
+
+    const flag = this._flags[key]
+    const response: FeatureFlagValue | undefined =
+      flag === undefined ? undefined : flag.enabled === false ? false : (flag.variant ?? true)
+
+    const properties: Record<string, any> = {
+      $feature_flag: key,
+      $feature_flag_response: response,
+      $feature_flag_id: flag?.id,
+      $feature_flag_version: flag?.version,
+      $feature_flag_reason: flag?.reason,
+      locally_evaluated: flag?.locallyEvaluated ?? false,
+      [`$feature/${key}`]: response,
+      $feature_flag_request_id: this._requestId,
+      $feature_flag_evaluated_at: flag?.locallyEvaluated ? Date.now() : this._evaluatedAt,
+    }
+
+    if (flag?.locallyEvaluated && this._flagDefinitionsLoadedAt !== undefined) {
+      properties.$feature_flag_definitions_loaded_at = this._flagDefinitionsLoadedAt
+    }
+
+    // Build the comma-joined `$feature_flag_error` matching the single-flag path's
+    // granularity: response-level errors (errors-while-computing, quota-limited) are
+    // combined with per-flag errors (flag-missing) so consumers can filter by type.
+    const errors: string[] = []
+    if (this._errorsWhileComputing) {
+      errors.push(FeatureFlagError.ERRORS_WHILE_COMPUTING)
+    }
+    if (this._quotaLimited) {
+      errors.push(FeatureFlagError.QUOTA_LIMITED)
+    }
+    if (flag === undefined) {
+      errors.push(FeatureFlagError.FLAG_MISSING)
+    }
+    if (errors.length > 0) {
+      properties.$feature_flag_error = errors.join(',')
+    }
+
+    this._host.captureFlagCalledEventIfNeeded({
+      distinctId: this._distinctId,
+      key,
+      response,
+      groups: this._groups,
+      disableGeoip: this._disableGeoip,
+      properties,
+    })
+  }
+}

package/src/types.ts

@@ -8,6 +8,7 @@ import type {
 } from '@posthog/core'
 import { ContextData, ContextOptions } from './extensions/context/types'
 
+import type { FeatureFlagEvaluations } from './feature-flag-evaluations'
 import type { FlagDefinitionCacheProvider } from './extensions/feature-flags/cache'
 
 export type IdentifyMessage = {
@@ -27,6 +28,17 @@ export type EventMessage = Omit<IdentifyMessage, 'distinctId'> & {
   distinctId?: string // Optional - can be provided via context
   event: string
   groups?: Record<string, string | number> // Mapping of group type to group id
+  /**
+   * Attach feature flag values evaluated via `posthog.evaluateFlags()` to this event.
+   * Prefer this over `sendFeatureFlags` — it guarantees the event carries the exact
+   * values the code branched on and avoids a hidden `/flags` request on every capture.
+   */
+  flags?: FeatureFlagEvaluations
+  /**
+   * @deprecated Use the `flags` option with a `FeatureFlagEvaluations` object obtained
+   * from `posthog.evaluateFlags()` instead. `sendFeatureFlags` fires a separate `/flags`
+   * request on capture and may return different values than the ones the code branched on.
+   */
   sendFeatureFlags?: boolean | SendFeatureFlagsOptions
   timestamp?: Date
   uuid?: string
@@ -216,6 +228,14 @@ export type PostHogOptions = Omit<PostHogCoreOptions, 'before_send'> & {
    * @default false
    */
   strictLocalEvaluation?: boolean
+  /**
+   * Controls whether `FeatureFlagEvaluations` filter helpers (`onlyAccessed()` and
+   * `only()`) log warnings when their input is unexpected — for example, calling
+   * `onlyAccessed()` before accessing any flags, or passing unknown keys to `only()`.
+   *
+   * @default true
+   */
+  featureFlagsLogWarnings?: boolean
   /**
    * Provides the API to extend the lifetime of a serverless invocation until
    * background work (like flushing analytics events) completes after the response
@@ -312,9 +332,10 @@ export interface IPostHog {
    * @param event We recommend using [verb] [noun], like movie played or movie updated to easily identify what your events mean later on.
    * @param properties OPTIONAL | which can be a object with any information you'd like to add
    * @param groups OPTIONAL | object of what groups are related to this event, example: { company: 'id:5' }. Can be used to analyze companies instead of users.
-   * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
+   * @param flags OPTIONAL | A `FeatureFlagEvaluations` snapshot from `evaluateFlags()`. Attaches those exact flag values to the event with no extra network call.
+   * @param sendFeatureFlags OPTIONAL | Deprecated — prefer `flags`. Fires a hidden `/flags` request on capture to enrich the event with flag values.
    */
-  capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): void
+  capture({ distinctId, event, properties, groups, flags, sendFeatureFlags }: EventMessage): void
 
   /**
    * @description Capture an event immediately. Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
@@ -322,9 +343,10 @@ export interface IPostHog {
    * @param event We recommend using [verb] [noun], like movie played or movie updated to easily identify what your events mean later on.
    * @param properties OPTIONAL | which can be a object with any information you'd like to add
    * @param groups OPTIONAL | object of what groups are related to this event, example: { company: 'id:5' }. Can be used to analyze companies instead of users.
-   * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
+   * @param flags OPTIONAL | A `FeatureFlagEvaluations` snapshot from `evaluateFlags()`. Attaches those exact flag values to the event with no extra network call.
+   * @param sendFeatureFlags OPTIONAL | Deprecated — prefer `flags`. Fires a hidden `/flags` request on capture to enrich the event with flag values.
    */
-  captureImmediate({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): Promise<void>
+  captureImmediate({ distinctId, event, properties, groups, flags, sendFeatureFlags }: EventMessage): Promise<void>
 
   /**
    * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog,
@@ -379,6 +401,9 @@ export interface IPostHog {
    * @param sendFeatureFlagEvents optional - whether to send feature flag events. Used for Experiments. Defaults to true.
    *
    * @returns true if the flag is on, false if the flag is off, undefined if there was an error.
+   *
+   * @deprecated Use {@link IPostHog.evaluateFlags} and call `flags.isEnabled(key)` on the
+   *   returned snapshot. Will be removed in the next major version.
    */
   isFeatureEnabled(
     key: string,
@@ -407,6 +432,9 @@ export interface IPostHog {
    * @param sendFeatureFlagEvents optional - whether to send feature flag events. Used for Experiments. Defaults to true.
    *
    * @returns true or string(for multivariates) if the flag is on, false if the flag is off, undefined if there was an error.
+   *
+   * @deprecated Use {@link IPostHog.evaluateFlags} and call `flags.getFlag(key)` on the
+   *   returned snapshot. Will be removed in the next major version.
    */
   getFeatureFlag(
     key: string,
@@ -445,6 +473,9 @@ export interface IPostHog {
    * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
    *
    * @returns payload of a json type object
+   *
+   * @deprecated Use {@link IPostHog.evaluateFlags} and call `flags.getFlagPayload(key)` on
+   *   the returned snapshot. Will be removed in the next major version.
    */
   getFeatureFlagPayload(
     key: string,
@@ -513,6 +544,36 @@ export interface IPostHog {
     options?: FlagEvaluationOptions
   ): Promise<FeatureFlagResult | undefined>
 
+  /**
+   * @description 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 events carry
+   * the exact flag values the code branched on.
+   *
+   * Prefer this over calling `isFeatureEnabled()` / `getFeatureFlag()` repeatedly and
+   * over `capture({ sendFeatureFlags: true })` — it avoids multiple `/flags` requests
+   * per incoming request.
+   *
+   * @example
+   * ```ts
+   * const flags = await posthog.evaluateFlags('user_123', { personProperties: { plan: 'enterprise' } })
+   * if (flags.isEnabled('new-dashboard')) {
+   *   renderNewDashboard()
+   * }
+   * posthog.capture({ distinctId: 'user_123', event: 'page_viewed', flags })
+   * ```
+   *
+   * @param options - Optional configuration for flag evaluation. Pass `flagKeys` to scope the underlying `/flags` request to a subset of flags.
+   */
+  evaluateFlags(options?: AllFlagsOptions): Promise<FeatureFlagEvaluations>
+  /**
+   * @description Evaluate all feature flags for a specific user.
+   *
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation. Pass `flagKeys` to scope the underlying `/flags` request to a subset of flags.
+   */
+  evaluateFlags(distinctId: string, options?: AllFlagsOptions): Promise<FeatureFlagEvaluations>
+
   /**
    * @description Sets a groups properties, which allows asking questions like "Who are the most active companies"
    * using my product in PostHog.

package/src/version.ts

@@ -1 +1 @@
-export const version = '5.32.1'
+export const version = '5.33.0'