posthog-node 5.32.1 → 5.33.0

package/dist/client.d.ts

@@ -1,8 +1,13 @@
 import { FeatureFlagValue, JsonType, PostHogCaptureOptions, PostHogCoreStateless, PostHogFetchOptions, PostHogFetchResponse, PostHogFlagsAndPayloadsResponse, PostHogPersistedProperty } from '@posthog/core';
 import { EventMessage, FeatureFlagResult, GroupIdentifyMessage, IdentifyMessage, IPostHog, OverrideFeatureFlagsOptions, PostHogOptions, FlagEvaluationOptions, AllFlagsOptions } from './types';
+import { FeatureFlagEvaluations, FlagCalledEventParams } from './feature-flag-evaluations';
 import ErrorTracking from './extensions/error-tracking';
 import { PostHogEventProperties } from '@posthog/core';
 import { ContextData, ContextOptions, IPostHogContext } from './extensions/context/types';
+/**
+ * @internal — clears the process-wide deprecation dedup set. Test-only.
+ */
+export declare function _resetDeprecationWarningsForTests(): void;
 export declare abstract class PostHogBackendClient extends PostHogCoreStateless implements IPostHog {
     private _memoryStorage;
     private featureFlagsPoller?;
@@ -448,6 +453,11 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      *
      * {@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
@@ -490,6 +500,10 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      *
      * {@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
@@ -584,6 +598,10 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      *
      * {@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
@@ -668,6 +686,84 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      */
     getAllFlagsAndPayloads(options?: AllFlagsOptions): Promise<PostHogFlagsAndPayloadsResponse>;
     getAllFlagsAndPayloads(distinctId: string, options?: AllFlagsOptions): Promise<PostHogFlagsAndPayloadsResponse>;
+    /**
+     * 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
+     */
+    evaluateFlags(options?: AllFlagsOptions): Promise<FeatureFlagEvaluations>;
+    evaluateFlags(distinctId: string, options?: AllFlagsOptions): Promise<FeatureFlagEvaluations>;
+    /**
+     * 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;
+    private _featureFlagEvaluationsHost?;
+    private _getFeatureFlagEvaluationsHost;
     /**
      * Create or update a group and its properties.
      *
@@ -874,8 +970,10 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      * @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']): void;
+    captureException(error: unknown, distinctId?: string, additionalProperties?: Record<string | number, any>, uuid?: EventMessage['uuid'], flags?: FeatureFlagEvaluations): void;
     /**
      * Capture an error exception as an event immediately (synchronously).
      *
@@ -909,9 +1007,10 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      * @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
      */
-    captureExceptionImmediate(error: unknown, distinctId?: string, additionalProperties?: Record<string | number, any>): Promise<void>;
+    captureExceptionImmediate(error: unknown, distinctId?: string, additionalProperties?: Record<string | number, any>, flags?: FeatureFlagEvaluations): Promise<void>;
     prepareEventMessage(props: EventMessage): Promise<{
         distinctId: string;
         event: string;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -33,11 +33,13 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    _resetDeprecationWarningsForTests: ()=>_resetDeprecationWarningsForTests,
     PostHogBackendClient: ()=>PostHogBackendClient
 });
 const external_version_js_namespaceObject = require("./version.js");
 const core_namespaceObject = require("@posthog/core");
 const external_types_js_namespaceObject = require("./types.js");
+const external_feature_flag_evaluations_js_namespaceObject = require("./feature-flag-evaluations.js");
 const feature_flags_js_namespaceObject = require("./extensions/feature-flags/feature-flags.js");
 const index_js_namespaceObject = require("./extensions/error-tracking/index.js");
 var index_js_default = /*#__PURE__*/ __webpack_require__.n(index_js_namespaceObject);
@@ -48,6 +50,15 @@ const MAX_CACHE_SIZE = 50000;
 const WAITUNTIL_DEBOUNCE_MS = 50;
 const WAITUNTIL_MAX_WAIT_MS = 500;
 const DEFAULT_NODE_HOST = 'https://us.i.posthog.com';
+const _emittedDeprecations = new Set();
+function emitDeprecationWarningOnce(id, message) {
+    if (_emittedDeprecations.has(id)) return;
+    _emittedDeprecations.add(id);
+    console.warn(`[PostHog] ${message}`);
+}
+function _resetDeprecationWarningsForTests() {
+    _emittedDeprecations.clear();
+}
 function normalizeApiKey(value) {
     return 'string' == typeof value ? value.trim() : '';
 }
@@ -59,6 +70,14 @@ function normalizeHost(value) {
     const normalizedValue = 'string' == typeof value ? value.trim() : '';
     return normalizedValue || DEFAULT_NODE_HOST;
 }
+function buildFlagEventProperties(flagValues) {
+    if (!flagValues) return {};
+    const additionalProperties = {};
+    for (const [feature, variant] of Object.entries(flagValues))additionalProperties[`$feature/${feature}`] = variant;
+    const activeFlags = Object.keys(flagValues).filter((flag)=>false !== flagValues[flag]).sort();
+    if (activeFlags.length > 0) additionalProperties['$active_feature_flags'] = activeFlags;
+    return additionalProperties;
+}
 class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
     constructor(apiKey, options = {}){
         const normalizedApiKey = normalizeApiKey(apiKey);
@@ -355,37 +374,30 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
         }
         if (sendFeatureFlagEvents) {
             const response = void 0 === result ? void 0 : false === result.enabled ? 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 = {
-                    $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 (flagWasLocallyEvaluated && this.featureFlagsPoller) {
-                    const flagDefinitionsLoadedAt = this.featureFlagsPoller.getFlagDefinitionsLoadedAt();
-                    if (void 0 !== flagDefinitionsLoadedAt) properties.$feature_flag_definitions_loaded_at = flagDefinitionsLoadedAt;
-                }
-                if (featureFlagError) properties.$feature_flag_error = featureFlagError;
-                this.capture({
-                    distinctId,
-                    event: '$feature_flag_called',
-                    properties,
-                    groups,
-                    disableGeoip
-                });
+            const properties = {
+                $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 (flagWasLocallyEvaluated && this.featureFlagsPoller) {
+                const flagDefinitionsLoadedAt = this.featureFlagsPoller.getFlagDefinitionsLoadedAt();
+                if (void 0 !== flagDefinitionsLoadedAt) properties.$feature_flag_definitions_loaded_at = flagDefinitionsLoadedAt;
             }
+            if (featureFlagError) properties.$feature_flag_error = featureFlagError;
+            this._captureFlagCalledEventIfNeeded({
+                distinctId,
+                key,
+                response,
+                groups,
+                disableGeoip,
+                properties
+            });
         }
         if (void 0 !== result && void 0 !== this._payloadOverrides && key in this._payloadOverrides) result = {
             ...result,
@@ -394,6 +406,7 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
         return result;
     }
     async getFeatureFlag(key, distinctId, options) {
+        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
@@ -403,6 +416,7 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
         return result.variant ?? true;
     }
     async getFeatureFlagPayload(key, distinctId, matchValue, options) {
+        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.");
         if (void 0 !== this._payloadOverrides && key in this._payloadOverrides) return this._payloadOverrides[key];
         const result = await this._getFeatureFlagResult(key, distinctId, {
             ...options,
@@ -430,8 +444,14 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
         return parsed;
     }
     async isFeatureEnabled(key, distinctId, options) {
-        const feat = await this.getFeatureFlag(key, distinctId, options);
-        if (void 0 === feat) return;
+        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.");
+        const result = await this._getFeatureFlagResult(key, distinctId, {
+            ...options,
+            sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true
+        });
+        if (void 0 === result) return;
+        if (false === result.enabled) return false;
+        const feat = result.variant ?? true;
         return !!feat || false;
     }
     async getAllFlags(distinctIdOrOptions, options) {
@@ -492,6 +512,136 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
             featureFlagPayloads
         };
     }
+    async evaluateFlags(distinctIdOrOptions, options) {
+        const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(distinctIdOrOptions, options);
+        if (!resolvedDistinctId) {
+            this._logger.warn("[PostHog] distinctId is required to evaluate feature flags \u2014 pass it explicitly or use withContext()");
+            return new external_feature_flag_evaluations_js_namespaceObject.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 (void 0 == onlyEvaluateLocally) onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false;
+        const records = {};
+        let requestId;
+        let evaluatedAt;
+        let errorsWhileComputing = false;
+        let quotaLimited = false;
+        const localResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(evaluationContext, flagKeys);
+        const locallyEvaluatedKeys = new Set();
+        if (localResult) for (const [key, value] of Object.entries(localResult.response)){
+            const flagDef = this.featureFlagsPoller?.featureFlagsByKey[key];
+            records[key] = {
+                key,
+                enabled: false !== value,
+                variant: 'string' == typeof value ? value : void 0,
+                payload: localResult.payloads[key],
+                id: flagDef?.id,
+                version: void 0,
+                reason: 'Evaluated locally',
+                locallyEvaluated: true
+            };
+            locallyEvaluatedKeys.add(key);
+        }
+        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.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;
+                    if (detail.metadata?.payload !== void 0) 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
+                    };
+                }
+            }
+        }
+        if (void 0 !== this._flagOverrides) for (const [key, value] of Object.entries(this._flagOverrides)){
+            if (void 0 === value) {
+                delete records[key];
+                continue;
+            }
+            const existing = records[key];
+            records[key] = {
+                key,
+                enabled: false !== value,
+                variant: 'string' == typeof value ? value : void 0,
+                payload: existing?.payload,
+                id: existing?.id,
+                version: existing?.version,
+                reason: existing?.reason,
+                locallyEvaluated: existing?.locallyEvaluated ?? false
+            };
+        }
+        if (void 0 !== this._payloadOverrides) for (const [key, payload] of Object.entries(this._payloadOverrides)){
+            const existing = records[key];
+            if (existing) records[key] = {
+                ...existing,
+                payload
+            };
+        }
+        return new external_feature_flag_evaluations_js_namespaceObject.FeatureFlagEvaluations({
+            host: this._getFeatureFlagEvaluationsHost(),
+            distinctId: resolvedDistinctId,
+            groups,
+            disableGeoip,
+            flags: records,
+            requestId,
+            evaluatedAt,
+            flagDefinitionsLoadedAt: this.featureFlagsPoller?.getFlagDefinitionsLoadedAt(),
+            errorsWhileComputing,
+            quotaLimited
+        });
+    }
+    _captureFlagCalledEventIfNeeded(params) {
+        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
+        });
+    }
+    _getFeatureFlagEvaluationsHost() {
+        if (!this._featureFlagEvaluationsHost) this._featureFlagEvaluationsHost = {
+            captureFlagCalledEventIfNeeded: (params)=>this._captureFlagCalledEventIfNeeded(params),
+            logWarning: (message)=>{
+                if (false !== this.options.featureFlagsLogWarnings) console.warn(`[PostHog] ${message}`);
+            }
+        };
+        return this._featureFlagEvaluationsHost;
+    }
     groupIdentify({ groupType, groupKey, properties, distinctId, disableGeoip }) {
         super.groupIdentifyStateless(groupType, groupKey, properties, {
             disableGeoip
@@ -668,27 +818,31 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
             evaluationCache: {}
         };
     }
-    captureException(error, distinctId, additionalProperties, uuid) {
+    captureException(error, distinctId, additionalProperties, uuid, flags) {
         if (!index_js_default().isPreviouslyCapturedError(error)) {
             const syntheticException = new Error('PostHog syntheticException');
             this.addPendingPromise(index_js_default().buildEventMessage(error, {
                 syntheticException
             }, distinctId, additionalProperties).then((msg)=>this.capture({
                     ...msg,
-                    uuid
+                    uuid,
+                    flags
                 })));
         }
     }
-    async captureExceptionImmediate(error, distinctId, additionalProperties) {
+    async captureExceptionImmediate(error, distinctId, additionalProperties, flags) {
         if (!index_js_default().isPreviouslyCapturedError(error)) {
             const syntheticException = new Error('PostHog syntheticException');
             return this.addPendingPromise(index_js_default().buildEventMessage(error, {
                 syntheticException
-            }, distinctId, additionalProperties).then((msg)=>this.captureImmediate(msg)));
+            }, distinctId, additionalProperties).then((msg)=>this.captureImmediate({
+                    ...msg,
+                    flags
+                })));
         }
     }
     async prepareEventMessage(props) {
-        const { distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip, uuid } = props;
+        const { distinctId, event, properties, groups, flags, sendFeatureFlags, timestamp, disableGeoip, uuid } = props;
         const contextData = this.context?.get();
         let mergedDistinctId = distinctId || contextData?.distinctId;
         const mergedProperties = {
@@ -706,6 +860,7 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
             event,
             properties: mergedProperties,
             groups,
+            flags,
             sendFeatureFlags,
             timestamp,
             disableGeoip,
@@ -713,18 +868,17 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
         });
         if (!eventMessage) return Promise.reject(null);
         const eventProperties = await Promise.resolve().then(async ()=>{
+            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.");
                 const sendFeatureFlagsOptions = 'object' == typeof sendFeatureFlags ? sendFeatureFlags : void 0;
-                return await this.getFeatureFlagsForEvent(eventMessage.distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
+                const flagValues = await this.getFeatureFlagsForEvent(eventMessage.distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
+                return buildFlagEventProperties(flagValues);
             }
-            eventMessage.event;
             return {};
-        }).then((flags)=>{
-            const additionalProperties = {};
-            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(()=>({})).then((additionalProperties)=>{
             const props = {
                 ...additionalProperties,
@@ -772,8 +926,10 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
     }
 }
 exports.PostHogBackendClient = __webpack_exports__.PostHogBackendClient;
+exports._resetDeprecationWarningsForTests = __webpack_exports__._resetDeprecationWarningsForTests;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "PostHogBackendClient"
+    "PostHogBackendClient",
+    "_resetDeprecationWarningsForTests"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true