posthog-node 5.32.1 → 5.33.0

package/dist/client.mjs

@@ -1,6 +1,7 @@
 import { version } from "./version.mjs";
 import { PostHogCoreStateless, isBlockedUA, isPlainObject, safeSetTimeout, uuidv7 } from "@posthog/core";
 import { FeatureFlagError } from "./types.mjs";
+import { FeatureFlagEvaluations } from "./feature-flag-evaluations.mjs";
 import { FeatureFlagsPoller, InconclusiveMatchError, RequiresServerEvaluation } from "./extensions/feature-flags/feature-flags.mjs";
 import error_tracking from "./extensions/error-tracking/index.mjs";
 import { PostHogMemoryStorage } from "./storage-memory.mjs";
@@ -10,6 +11,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() : '';
 }
@@ -21,6 +31,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 PostHogCoreStateless {
     constructor(apiKey, options = {}){
         const normalizedApiKey = normalizeApiKey(apiKey);
@@ -317,37 +335,30 @@ class PostHogBackendClient extends 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,
@@ -356,6 +367,7 @@ class PostHogBackendClient extends 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
@@ -365,6 +377,7 @@ class PostHogBackendClient extends 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,
@@ -392,8 +405,14 @@ class PostHogBackendClient extends 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) {
@@ -454,6 +473,136 @@ class PostHogBackendClient extends 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 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 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
@@ -630,27 +779,31 @@ class PostHogBackendClient extends PostHogCoreStateless {
             evaluationCache: {}
         };
     }
-    captureException(error, distinctId, additionalProperties, uuid) {
+    captureException(error, distinctId, additionalProperties, uuid, flags) {
         if (!error_tracking.isPreviouslyCapturedError(error)) {
             const syntheticException = new Error('PostHog syntheticException');
             this.addPendingPromise(error_tracking.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 (!error_tracking.isPreviouslyCapturedError(error)) {
             const syntheticException = new Error('PostHog syntheticException');
             return this.addPendingPromise(error_tracking.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 = {
@@ -668,6 +821,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
             event,
             properties: mergedProperties,
             groups,
+            flags,
             sendFeatureFlags,
             timestamp,
             disableGeoip,
@@ -675,18 +829,17 @@ class PostHogBackendClient extends 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,
@@ -733,4 +886,4 @@ class PostHogBackendClient extends PostHogCoreStateless {
         return result;
     }
 }
-export { PostHogBackendClient };
+export { PostHogBackendClient, _resetDeprecationWarningsForTests };

package/dist/exports.d.ts

@@ -1,6 +1,7 @@
 export * from './extensions/sentry-integration';
 export * from './extensions/express';
 export * from './types';
+export { FeatureFlagEvaluations } from './feature-flag-evaluations';
 export { FeatureFlagError } from '@posthog/core';
 export type { FeatureFlagErrorType } from '@posthog/core';
 //# sourceMappingURL=exports.d.ts.map

package/dist/exports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../src/exports.ts"],"names":[],"mappings":"AAAA,cAAc,iCAAiC,CAAA;AAC/C,cAAc,sBAAsB,CAAA;AACpC,cAAc,SAAS,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../src/exports.ts"],"names":[],"mappings":"AAAA,cAAc,iCAAiC,CAAA;AAC/C,cAAc,sBAAsB,CAAA;AACpC,cAAc,SAAS,CAAA;AAEvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA"}

package/dist/exports.js

@@ -6,6 +6,9 @@ var __webpack_modules__ = {
     "./extensions/sentry-integration": function(module) {
         module.exports = require("./extensions/sentry-integration.js");
     },
+    "./feature-flag-evaluations": function(module) {
+        module.exports = require("./feature-flag-evaluations.js");
+    },
     "./types": function(module) {
         module.exports = require("./types.js");
     },
@@ -57,11 +60,13 @@ var __webpack_exports__ = {};
 (()=>{
     __webpack_require__.r(__webpack_exports__);
     __webpack_require__.d(__webpack_exports__, {
-        FeatureFlagError: ()=>_posthog_core__WEBPACK_IMPORTED_MODULE_3__.FeatureFlagError
+        FeatureFlagError: ()=>_posthog_core__WEBPACK_IMPORTED_MODULE_4__.FeatureFlagError,
+        FeatureFlagEvaluations: ()=>_feature_flag_evaluations__WEBPACK_IMPORTED_MODULE_3__.FeatureFlagEvaluations
     });
     var _extensions_sentry_integration__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__("./extensions/sentry-integration");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
     for(var __WEBPACK_IMPORT_KEY__ in _extensions_sentry_integration__WEBPACK_IMPORTED_MODULE_0__)if ([
+        "FeatureFlagEvaluations",
         "FeatureFlagError",
         "default"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
@@ -71,6 +76,7 @@ var __webpack_exports__ = {};
     var _extensions_express__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__("./extensions/express");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
     for(var __WEBPACK_IMPORT_KEY__ in _extensions_express__WEBPACK_IMPORTED_MODULE_1__)if ([
+        "FeatureFlagEvaluations",
         "FeatureFlagError",
         "default"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
@@ -80,17 +86,21 @@ var __webpack_exports__ = {};
     var _types__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__("./types");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
     for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_2__)if ([
+        "FeatureFlagEvaluations",
         "FeatureFlagError",
         "default"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
         return _types__WEBPACK_IMPORTED_MODULE_2__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _posthog_core__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__("@posthog/core");
+    var _feature_flag_evaluations__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__("./feature-flag-evaluations");
+    var _posthog_core__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__("@posthog/core");
 })();
 exports.FeatureFlagError = __webpack_exports__.FeatureFlagError;
+exports.FeatureFlagEvaluations = __webpack_exports__.FeatureFlagEvaluations;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "FeatureFlagError"
+    "FeatureFlagError",
+    "FeatureFlagEvaluations"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/exports.mjs

@@ -1,5 +1,6 @@
+import { FeatureFlagEvaluations } from "./feature-flag-evaluations.mjs";
 import { FeatureFlagError } from "@posthog/core";
 export * from "./extensions/sentry-integration.mjs";
 export * from "./extensions/express.mjs";
 export * from "./types.mjs";
-export { FeatureFlagError };
+export { FeatureFlagError, FeatureFlagEvaluations };

package/dist/feature-flag-evaluations.d.ts

@@ -0,0 +1,151 @@
+import { FeatureFlagValue, JsonType } from '@posthog/core';
+/**
+ * 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 declare class FeatureFlagEvaluations {
+    private readonly _host;
+    private readonly _distinctId;
+    private readonly _groups;
+    private readonly _disableGeoip;
+    private readonly _flags;
+    private readonly _requestId;
+    private readonly _evaluatedAt;
+    private readonly _flagDefinitionsLoadedAt;
+    private readonly _errorsWhileComputing;
+    private readonly _quotaLimited;
+    private readonly _accessed;
+    private readonly _isSlice;
+    /**
+     * @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;
+    });
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 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;
+    /**
+     * 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;
+    /**
+     * Returns the flag keys that are part of this evaluation.
+     */
+    get keys(): string[];
+    /**
+     * 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>;
+    private _cloneWith;
+    private _recordAccess;
+}
+//# sourceMappingURL=feature-flag-evaluations.d.ts.map

package/dist/feature-flag-evaluations.d.ts.map

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