posthog-node 5.21.1 → 5.21.2

package/dist/client.d.ts

@@ -1,6 +1,5 @@
-import { JsonType, PostHogCoreStateless, PostHogFetchOptions, PostHogFetchResponse, PostHogFlagsAndPayloadsResponse, PostHogPersistedProperty, PostHogCaptureOptions } from '@posthog/core';
-import { EventMessage, GroupIdentifyMessage, IdentifyMessage, IPostHog, OverrideFeatureFlagsOptions, PostHogOptions } from './types';
-import { FeatureFlagValue } from '@posthog/core';
+import { FeatureFlagValue, JsonType, PostHogCaptureOptions, PostHogCoreStateless, PostHogFetchOptions, PostHogFetchResponse, PostHogFlagsAndPayloadsResponse, PostHogPersistedProperty } from '@posthog/core';
+import { EventMessage, FeatureFlagResult, GroupIdentifyMessage, IdentifyMessage, IPostHog, OverrideFeatureFlagsOptions, PostHogOptions } from './types';
 import ErrorTracking from './extensions/error-tracking';
 import { PostHogEventProperties } from '@posthog/core';
 import { ContextData, ContextOptions, IPostHogContext } from './extensions/context/types';
@@ -395,6 +394,17 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
      * @returns Promise that resolves to true if ready, false if timed out
      */
     waitForLocalEvaluationReady(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Internal method that handles feature flag evaluation with full details.
+     * Used by getFeatureFlag, getFeatureFlagPayload, and getFeatureFlagResult.
+     *
+     * @param key - The feature flag key
+     * @param distinctId - The user's distinct ID
+     * @param options - Evaluation options (includes sendFeatureFlagEvents, defaults to true)
+     * @param matchValue - Optional match value for payload lookup (used by getFeatureFlagPayload)
+     * @returns Promise that resolves to the flag result or undefined
+     */
+    private _getFeatureFlagResult;
     /**
      * Get the value of a feature flag for a specific user.
      *
@@ -488,6 +498,45 @@ export declare abstract class PostHogBackendClient extends PostHogCoreStateless
         sendFeatureFlagEvents?: boolean;
         disableGeoip?: boolean;
     }): Promise<JsonType | undefined>;
+    /**
+     * Get the result of evaluating a feature flag, including its value and payload.
+     * This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.
+     *
+     * @example
+     * ```ts
+     * // Get flag result
+     * const result = await client.getFeatureFlagResult('my-flag', 'user_123')
+     * if (result) {
+     *   console.log('Flag enabled:', result.enabled)
+     *   console.log('Variant:', result.variant)
+     *   console.log('Payload:', result.payload)
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // With groups and properties
+     * const result = await client.getFeatureFlagResult('org-feature', 'user_123', {
+     *   groups: { organization: 'acme-corp' },
+     *   personProperties: { plan: 'enterprise' }
+     * })
+     * ```
+     *
+     * {@label Feature flags}
+     *
+     * @param key - The feature flag key
+     * @param distinctId - The user's distinct ID
+     * @param options - Optional configuration for flag evaluation
+     * @returns Promise that resolves to the flag result or undefined
+     */
+    getFeatureFlagResult(key: string, distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+        disableGeoip?: boolean;
+    }): Promise<FeatureFlagResult | undefined>;
     /**
      * Get the remote config payload for a feature flag.
      *

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":"AAEA,OAAO,EAEL,gBAAgB,EAGhB,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,+BAA+B,EAE/B,wBAAwB,EACzB,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,YAAY,EAIZ,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACR,2BAA2B,EAC3B,cAAc,EAEf,MAAM,SAAS,CAAA;AAMhB,OAAO,aAAa,MAAM,6BAA6B,CAAA;AACvD,OAAO,EAAkB,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAGtE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AASzF,8BAAsB,oBAAqB,SAAQ,oBAAqB,YAAW,QAAQ;IACzF,OAAO,CAAC,cAAc,CAA6B;IAEnD,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAC/C,SAAS,CAAC,aAAa,EAAE,aAAa,CAAA;IACtC,OAAO,CAAC,YAAY,CAAQ;IAC5B,SAAgB,OAAO,EAAE,cAAc,CAAA;IACvC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;IAG5C,OAAO,CAAC,cAAc,CAAC,CAAkC;IACzD,OAAO,CAAC,iBAAiB,CAAC,CAA0B;IAEpD,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBACS,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB;IA+CxD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,CAAC,GAAG,EAAE,wBAAwB,GAAG,GAAG,GAAG,SAAS;IAIpE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,CAAC,GAAG,EAAE,wBAAwB,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IAI5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI/E;;;;;;;;;;;;;OAaG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;;;;;;;;;;;;OAaG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;;;;;;;;;;;OAaG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvB;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,OAAO,GAAE,OAAc,GAAG,IAAI;IAKpC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAqBlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACG,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,QAAQ,CAAC,EAAE,UAAU,EAAE,UAAe,EAAE,YAAY,EAAE,EAAE,eAAe,GAAG,IAAI;IAc9E;;;;;;;;;;;;;;;;;;;OAmBG;IACG,iBAAiB,CAAC,EAAE,UAAU,EAAE,UAAe,EAAE,YAAY,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IActG;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAIhF;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxG;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAAsB,IAAI,OAAO;IAIjC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,2BAA2B,CAAC,SAAS,GAAE,MAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuBvF;;;;;;;;;OASG;YACW,qBAAqB;IAwNnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAA;QAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;KACvB,GACA,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAcxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,qBAAqB,CACzB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,gBAAgB,EAC7B,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,4FAA4F;QAC5F,qBAAqB,CAAC,EAAE,OAAO,CAAA;QAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;KACvB,GACA,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IA0BhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,oBAAoB,CACxB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAA;QAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;KACvB,GACA,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAOzC;;;;;;;;;;;;;;;;;OAiBG;IACG,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IA0B5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAA;QAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;KACvB,GACA,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAQ/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAK5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,GACA,OAAO,CAAC,+BAA+B,CAAC;IAwE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,aAAa,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAIxG;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,oBAAoB,CAAC,SAAS,EAAE,2BAA2B,GAAG,IAAI;IAyClE;;;;;;OAMG;IACH,OAAO,CAAC,6BAA6B;IAoCrC,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,eAAe,GAAG,SAAS;IAEnE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,CAAC;IASpF;;;;;;;;;;;;;;;OAeG;IACH,UAAU,IAAI,WAAW,GAAG,SAAS;IAIrC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAM5C,2BAA2B;IAqCzC,OAAO,CAAC,0BAA0B;YA+BpB,uBAAuB;IAkErC,OAAO,CAAC,gCAAgC;IAqBxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,gBAAgB,CACd,KAAK,EAAE,OAAO,EACd,UAAU,CAAC,EAAE,MAAM,EACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EACnD,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,GAC1B,IAAI;IAWP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,yBAAyB,CAC7B,KAAK,EAAE,OAAO,EACd,UAAU,CAAC,EAAE,MAAM,EACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC;IAWH,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;QAC7D,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,sBAAsB,CAAA;QAClC,OAAO,EAAE,qBAAqB,CAAA;KAC/B,CAAC;IAiHF,OAAO,CAAC,cAAc;CAuBvB"}

package/dist/client.js

@@ -175,21 +175,56 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
             });
         });
     }
-    async getFeatureFlag(key, distinctId, options) {
-        if (void 0 !== this._flagOverrides && key in this._flagOverrides) return this._flagOverrides[key];
-        const { groups, disableGeoip } = options || {};
-        let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {};
+    async _getFeatureFlagResult(key, distinctId, options = {}, matchValue) {
+        const sendFeatureFlagEvents = options.sendFeatureFlagEvents ?? true;
+        if (void 0 !== this._flagOverrides && key in this._flagOverrides) {
+            const overrideValue = this._flagOverrides[key];
+            if (void 0 === overrideValue) return;
+            const overridePayload = this._payloadOverrides?.[key];
+            return {
+                key,
+                enabled: false !== overrideValue,
+                variant: 'string' == typeof overrideValue ? overrideValue : void 0,
+                payload: overridePayload
+            };
+        }
+        const { groups, disableGeoip } = options;
+        let { onlyEvaluateLocally, personProperties, groupProperties } = options;
         const adjustedProperties = this.addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties);
         personProperties = adjustedProperties.allPersonProperties;
         groupProperties = adjustedProperties.allGroupProperties;
         if (void 0 == onlyEvaluateLocally) onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false;
-        if (void 0 == sendFeatureFlagEvents) sendFeatureFlagEvents = this.options.sendFeatureFlagEvent ?? true;
-        let response = await this.featureFlagsPoller?.getFeatureFlag(key, distinctId, groups, personProperties, groupProperties);
-        const flagWasLocallyEvaluated = void 0 !== response;
+        let result;
+        let flagWasLocallyEvaluated = false;
         let requestId;
         let evaluatedAt;
-        let flagDetail;
         let featureFlagError;
+        let flagId;
+        let flagVersion;
+        let flagReason;
+        const localEvaluationEnabled = void 0 !== this.featureFlagsPoller;
+        if (localEvaluationEnabled) {
+            await this.featureFlagsPoller?.loadFeatureFlags();
+            const flag = this.featureFlagsPoller?.featureFlagsByKey[key];
+            if (flag) try {
+                const localResult = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties, matchValue);
+                if (localResult) {
+                    flagWasLocallyEvaluated = true;
+                    const value = localResult.value;
+                    flagId = flag.id;
+                    flagReason = 'Evaluated locally';
+                    result = {
+                        key,
+                        enabled: false !== value,
+                        variant: 'string' == typeof value ? value : void 0,
+                        payload: localResult.payload ?? void 0
+                    };
+                }
+            } catch (e) {
+                if (e instanceof feature_flags_js_namespaceObject.RequiresServerEvaluation || e instanceof feature_flags_js_namespaceObject.InconclusiveMatchError) this._logger?.info(`${e.name} when computing flag locally: ${key}: ${e.message}`);
+                else throw e;
+            }
+        }
         if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
             const flagsResponse = await super.getFeatureFlagDetailsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, [
                 key
@@ -201,68 +236,87 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
                 const errors = [];
                 if (flagsResponse.errorsWhileComputingFlags) errors.push(external_types_js_namespaceObject.FeatureFlagError.ERRORS_WHILE_COMPUTING);
                 if (flagsResponse.quotaLimited?.includes('feature_flags')) errors.push(external_types_js_namespaceObject.FeatureFlagError.QUOTA_LIMITED);
-                flagDetail = flagsResponse.flags[key];
+                const flagDetail = flagsResponse.flags[key];
                 if (void 0 === flagDetail) errors.push(external_types_js_namespaceObject.FeatureFlagError.FLAG_MISSING);
+                else {
+                    flagId = flagDetail.metadata?.id;
+                    flagVersion = flagDetail.metadata?.version;
+                    flagReason = flagDetail.reason?.description ?? flagDetail.reason?.code;
+                    let parsedPayload;
+                    if (flagDetail.metadata?.payload !== void 0) try {
+                        parsedPayload = JSON.parse(flagDetail.metadata.payload);
+                    } catch  {
+                        parsedPayload = flagDetail.metadata.payload;
+                    }
+                    result = {
+                        key,
+                        enabled: flagDetail.enabled,
+                        variant: flagDetail.variant,
+                        payload: parsedPayload
+                    };
+                }
                 if (errors.length > 0) featureFlagError = errors.join(',');
-                response = (0, core_namespaceObject.getFeatureFlagValue)(flagDetail);
             }
         }
-        const featureFlagReportedKey = `${key}_${response}`;
-        if (sendFeatureFlagEvents && (!(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: flagDetail?.metadata?.id,
-                $feature_flag_version: flagDetail?.metadata?.version,
-                $feature_flag_reason: flagDetail?.reason?.description ?? flagDetail?.reason?.code,
-                locally_evaluated: flagWasLocallyEvaluated,
-                [`$feature/${key}`]: response,
-                $feature_flag_request_id: requestId,
-                $feature_flag_evaluated_at: evaluatedAt
-            };
-            if (featureFlagError) properties.$feature_flag_error = featureFlagError;
-            this.capture({
-                distinctId,
-                event: '$feature_flag_called',
-                properties,
-                groups,
-                disableGeoip
-            });
+        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: evaluatedAt
+                };
+                if (featureFlagError) properties.$feature_flag_error = featureFlagError;
+                this.capture({
+                    distinctId,
+                    event: '$feature_flag_called',
+                    properties,
+                    groups,
+                    disableGeoip
+                });
+            }
         }
-        return response;
+        if (void 0 !== result && void 0 !== this._payloadOverrides && key in this._payloadOverrides) result = {
+            ...result,
+            payload: this._payloadOverrides[key]
+        };
+        return result;
+    }
+    async getFeatureFlag(key, distinctId, options) {
+        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;
+        return result.variant ?? true;
     }
     async getFeatureFlagPayload(key, distinctId, matchValue, options) {
         if (void 0 !== this._payloadOverrides && key in this._payloadOverrides) return this._payloadOverrides[key];
-        const { groups, disableGeoip } = options || {};
-        let { onlyEvaluateLocally, personProperties, groupProperties } = options || {};
-        const adjustedProperties = this.addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties);
-        personProperties = adjustedProperties.allPersonProperties;
-        groupProperties = adjustedProperties.allGroupProperties;
-        let response;
-        const localEvaluationEnabled = void 0 !== this.featureFlagsPoller;
-        if (localEvaluationEnabled) {
-            await this.featureFlagsPoller?.loadFeatureFlags();
-            const flag = this.featureFlagsPoller?.featureFlagsByKey[key];
-            if (flag) try {
-                const result = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties, matchValue);
-                if (result) {
-                    matchValue = result.value;
-                    response = result.payload;
-                }
-            } catch (e) {
-                if (e instanceof feature_flags_js_namespaceObject.RequiresServerEvaluation || e instanceof feature_flags_js_namespaceObject.InconclusiveMatchError) this._logger?.info(`${e.name} when computing flag locally: ${flag.key}: ${e.message}`);
-                else throw e;
-            }
-        }
-        if (void 0 == onlyEvaluateLocally) onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false;
-        const payloadWasLocallyEvaluated = void 0 !== response;
-        if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) response = await super.getFeatureFlagPayloadStateless(key, distinctId, groups, personProperties, groupProperties, disableGeoip);
-        return response;
+        const result = await this._getFeatureFlagResult(key, distinctId, {
+            ...options,
+            sendFeatureFlagEvents: false
+        }, matchValue);
+        if (void 0 === result) return;
+        return result.payload ?? null;
+    }
+    async getFeatureFlagResult(key, distinctId, options) {
+        return this._getFeatureFlagResult(key, distinctId, {
+            ...options,
+            sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true
+        });
     }
     async getRemoteConfigPayload(flagKey) {
         if (!this.options.personalApiKey) throw new Error('Personal API key is required for remote config payload decryption');

package/dist/client.mjs

@@ -1,5 +1,5 @@
 import { version } from "./version.mjs";
-import { PostHogCoreStateless, getFeatureFlagValue, isBlockedUA, isPlainObject, safeSetTimeout, uuidv7 } from "@posthog/core";
+import { PostHogCoreStateless, isBlockedUA, isPlainObject, safeSetTimeout, uuidv7 } from "@posthog/core";
 import { FeatureFlagError } from "./types.mjs";
 import { FeatureFlagsPoller, InconclusiveMatchError, RequiresServerEvaluation } from "./extensions/feature-flags/feature-flags.mjs";
 import error_tracking from "./extensions/error-tracking/index.mjs";
@@ -137,21 +137,56 @@ class PostHogBackendClient extends PostHogCoreStateless {
             });
         });
     }
-    async getFeatureFlag(key, distinctId, options) {
-        if (void 0 !== this._flagOverrides && key in this._flagOverrides) return this._flagOverrides[key];
-        const { groups, disableGeoip } = options || {};
-        let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {};
+    async _getFeatureFlagResult(key, distinctId, options = {}, matchValue) {
+        const sendFeatureFlagEvents = options.sendFeatureFlagEvents ?? true;
+        if (void 0 !== this._flagOverrides && key in this._flagOverrides) {
+            const overrideValue = this._flagOverrides[key];
+            if (void 0 === overrideValue) return;
+            const overridePayload = this._payloadOverrides?.[key];
+            return {
+                key,
+                enabled: false !== overrideValue,
+                variant: 'string' == typeof overrideValue ? overrideValue : void 0,
+                payload: overridePayload
+            };
+        }
+        const { groups, disableGeoip } = options;
+        let { onlyEvaluateLocally, personProperties, groupProperties } = options;
         const adjustedProperties = this.addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties);
         personProperties = adjustedProperties.allPersonProperties;
         groupProperties = adjustedProperties.allGroupProperties;
         if (void 0 == onlyEvaluateLocally) onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false;
-        if (void 0 == sendFeatureFlagEvents) sendFeatureFlagEvents = this.options.sendFeatureFlagEvent ?? true;
-        let response = await this.featureFlagsPoller?.getFeatureFlag(key, distinctId, groups, personProperties, groupProperties);
-        const flagWasLocallyEvaluated = void 0 !== response;
+        let result;
+        let flagWasLocallyEvaluated = false;
         let requestId;
         let evaluatedAt;
-        let flagDetail;
         let featureFlagError;
+        let flagId;
+        let flagVersion;
+        let flagReason;
+        const localEvaluationEnabled = void 0 !== this.featureFlagsPoller;
+        if (localEvaluationEnabled) {
+            await this.featureFlagsPoller?.loadFeatureFlags();
+            const flag = this.featureFlagsPoller?.featureFlagsByKey[key];
+            if (flag) try {
+                const localResult = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties, matchValue);
+                if (localResult) {
+                    flagWasLocallyEvaluated = true;
+                    const value = localResult.value;
+                    flagId = flag.id;
+                    flagReason = 'Evaluated locally';
+                    result = {
+                        key,
+                        enabled: false !== value,
+                        variant: 'string' == typeof value ? value : void 0,
+                        payload: localResult.payload ?? void 0
+                    };
+                }
+            } catch (e) {
+                if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) this._logger?.info(`${e.name} when computing flag locally: ${key}: ${e.message}`);
+                else throw e;
+            }
+        }
         if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
             const flagsResponse = await super.getFeatureFlagDetailsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, [
                 key
@@ -163,68 +198,87 @@ class PostHogBackendClient extends PostHogCoreStateless {
                 const errors = [];
                 if (flagsResponse.errorsWhileComputingFlags) errors.push(FeatureFlagError.ERRORS_WHILE_COMPUTING);
                 if (flagsResponse.quotaLimited?.includes('feature_flags')) errors.push(FeatureFlagError.QUOTA_LIMITED);
-                flagDetail = flagsResponse.flags[key];
+                const flagDetail = flagsResponse.flags[key];
                 if (void 0 === flagDetail) errors.push(FeatureFlagError.FLAG_MISSING);
+                else {
+                    flagId = flagDetail.metadata?.id;
+                    flagVersion = flagDetail.metadata?.version;
+                    flagReason = flagDetail.reason?.description ?? flagDetail.reason?.code;
+                    let parsedPayload;
+                    if (flagDetail.metadata?.payload !== void 0) try {
+                        parsedPayload = JSON.parse(flagDetail.metadata.payload);
+                    } catch  {
+                        parsedPayload = flagDetail.metadata.payload;
+                    }
+                    result = {
+                        key,
+                        enabled: flagDetail.enabled,
+                        variant: flagDetail.variant,
+                        payload: parsedPayload
+                    };
+                }
                 if (errors.length > 0) featureFlagError = errors.join(',');
-                response = getFeatureFlagValue(flagDetail);
             }
         }
-        const featureFlagReportedKey = `${key}_${response}`;
-        if (sendFeatureFlagEvents && (!(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: flagDetail?.metadata?.id,
-                $feature_flag_version: flagDetail?.metadata?.version,
-                $feature_flag_reason: flagDetail?.reason?.description ?? flagDetail?.reason?.code,
-                locally_evaluated: flagWasLocallyEvaluated,
-                [`$feature/${key}`]: response,
-                $feature_flag_request_id: requestId,
-                $feature_flag_evaluated_at: evaluatedAt
-            };
-            if (featureFlagError) properties.$feature_flag_error = featureFlagError;
-            this.capture({
-                distinctId,
-                event: '$feature_flag_called',
-                properties,
-                groups,
-                disableGeoip
-            });
+        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: evaluatedAt
+                };
+                if (featureFlagError) properties.$feature_flag_error = featureFlagError;
+                this.capture({
+                    distinctId,
+                    event: '$feature_flag_called',
+                    properties,
+                    groups,
+                    disableGeoip
+                });
+            }
         }
-        return response;
+        if (void 0 !== result && void 0 !== this._payloadOverrides && key in this._payloadOverrides) result = {
+            ...result,
+            payload: this._payloadOverrides[key]
+        };
+        return result;
+    }
+    async getFeatureFlag(key, distinctId, options) {
+        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;
+        return result.variant ?? true;
     }
     async getFeatureFlagPayload(key, distinctId, matchValue, options) {
         if (void 0 !== this._payloadOverrides && key in this._payloadOverrides) return this._payloadOverrides[key];
-        const { groups, disableGeoip } = options || {};
-        let { onlyEvaluateLocally, personProperties, groupProperties } = options || {};
-        const adjustedProperties = this.addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties);
-        personProperties = adjustedProperties.allPersonProperties;
-        groupProperties = adjustedProperties.allGroupProperties;
-        let response;
-        const localEvaluationEnabled = void 0 !== this.featureFlagsPoller;
-        if (localEvaluationEnabled) {
-            await this.featureFlagsPoller?.loadFeatureFlags();
-            const flag = this.featureFlagsPoller?.featureFlagsByKey[key];
-            if (flag) try {
-                const result = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties, matchValue);
-                if (result) {
-                    matchValue = result.value;
-                    response = result.payload;
-                }
-            } catch (e) {
-                if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) this._logger?.info(`${e.name} when computing flag locally: ${flag.key}: ${e.message}`);
-                else throw e;
-            }
-        }
-        if (void 0 == onlyEvaluateLocally) onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false;
-        const payloadWasLocallyEvaluated = void 0 !== response;
-        if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) response = await super.getFeatureFlagPayloadStateless(key, distinctId, groups, personProperties, groupProperties, disableGeoip);
-        return response;
+        const result = await this._getFeatureFlagResult(key, distinctId, {
+            ...options,
+            sendFeatureFlagEvents: false
+        }, matchValue);
+        if (void 0 === result) return;
+        return result.payload ?? null;
+    }
+    async getFeatureFlagResult(key, distinctId, options) {
+        return this._getFeatureFlagResult(key, distinctId, {
+            ...options,
+            sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true
+        });
     }
     async getRemoteConfigPayload(flagKey) {
         if (!this.options.personalApiKey) throw new Error('Personal API key is required for remote config payload decryption');

package/dist/types.d.ts

@@ -201,6 +201,15 @@ export declare const FeatureFlagError: {
     readonly UNKNOWN_ERROR: "unknown_error";
 };
 export type FeatureFlagErrorType = (typeof FeatureFlagError)[keyof typeof FeatureFlagError] | string;
+/**
+ * Result of evaluating a feature flag, including its value and payload.
+ */
+export type FeatureFlagResult = {
+    key: string;
+    enabled: boolean;
+    variant: string | undefined;
+    payload: JsonType | undefined;
+};
 export interface IPostHog {
     /**
      * @description Capture allows you to capture anything a user does within your system,
@@ -338,6 +347,33 @@ export interface IPostHog {
     getFeatureFlagPayload(key: string, distinctId: string, matchValue?: FeatureFlagValue, options?: {
         onlyEvaluateLocally?: boolean;
     }): Promise<JsonType | undefined>;
+    /**
+     * @description Get the result of evaluating a feature flag, including its value and payload.
+     * This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.
+     *
+     * @example
+     * ```ts
+     * const result = await client.getFeatureFlagResult('my-flag', 'user_123')
+     * if (result) {
+     *   console.log('Flag enabled:', result.enabled)
+     *   console.log('Variant:', result.variant)
+     *   console.log('Payload:', result.payload)
+     * }
+     * ```
+     *
+     * @param key - The feature flag key
+     * @param distinctId - The user's distinct ID
+     * @param options - Optional configuration for flag evaluation
+     * @returns Promise that resolves to the flag result or undefined
+     */
+    getFeatureFlagResult(key: string, distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+        disableGeoip?: boolean;
+    }): Promise<FeatureFlagResult | undefined>;
     /**
      * @description Sets a groups properties, which allows asking questions like "Who are the most active companies"
      * using my product in PostHog.

package/dist/types.d.ts.map

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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "5.21.1";
+export declare const version = "5.21.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     version: ()=>version
 });
-const version = '5.21.1';
+const version = '5.21.2';
 exports.version = __webpack_exports__.version;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "version"

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = '5.21.1';
+const version = '5.21.2';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "5.21.1",
+  "version": "5.21.2",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",

package/src/client.ts

@@ -1,22 +1,25 @@
 import { version } from './version'
 
 import {
+  FeatureFlagDetail,
+  FeatureFlagValue,
+  isBlockedUA,
+  isPlainObject,
   JsonType,
+  PostHogCaptureOptions,
   PostHogCoreStateless,
-  PostHogFlagsResponse,
   PostHogFetchOptions,
   PostHogFetchResponse,
   PostHogFlagsAndPayloadsResponse,
+  PostHogFlagsResponse,
   PostHogPersistedProperty,
-  PostHogCaptureOptions,
-  isPlainObject,
-  isBlockedUA,
 } from '@posthog/core'
 import {
   EventMessage,
   FeatureFlagError,
   FeatureFlagErrorType,
   FeatureFlagOverrideOptions,
+  FeatureFlagResult,
   GroupIdentifyMessage,
   IdentifyMessage,
   IPostHog,
@@ -24,7 +27,6 @@ import {
   PostHogOptions,
   SendFeatureFlagsOptions,
 } from './types'
-import { FeatureFlagDetail, FeatureFlagValue, getFeatureFlagValue } from '@posthog/core'
 import {
   FeatureFlagsPoller,
   RequiresServerEvaluation,
@@ -600,65 +602,47 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   }
 
   /**
-   * Get the value of a feature flag for a specific user.
-   *
-   * @example
-   * ```ts
-   * // Basic feature flag check
-   * const flagValue = await client.getFeatureFlag('new-feature', 'user_123')
-   * if (flagValue === 'variant-a') {
-   *   // Show variant A
-   * } else if (flagValue === 'variant-b') {
-   *   // Show variant B
-   * } else {
-   *   // Flag is disabled or not found
-   * }
-   * ```
-   *
-   * @example
-   * ```ts
-   * // With groups and properties
-   * const flagValue = await client.getFeatureFlag('org-feature', 'user_123', {
-   *   groups: { organization: 'acme-corp' },
-   *   personProperties: { plan: 'enterprise' },
-   *   groupProperties: { organization: { tier: 'premium' } }
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Only evaluate locally
-   * const flagValue = await client.getFeatureFlag('local-flag', 'user_123', {
-   *   onlyEvaluateLocally: true
-   * })
-   * ```
-   *
-   * {@label Feature flags}
+   * Internal method that handles feature flag evaluation with full details.
+   * Used by getFeatureFlag, getFeatureFlagPayload, and getFeatureFlagResult.
    *
    * @param key - The feature flag key
    * @param distinctId - The user's distinct ID
-   * @param options - Optional configuration for flag evaluation
-   * @returns Promise that resolves to the flag value or undefined
+   * @param options - Evaluation options (includes sendFeatureFlagEvents, defaults to true)
+   * @param matchValue - Optional match value for payload lookup (used by getFeatureFlagPayload)
+   * @returns Promise that resolves to the flag result or undefined
    */
-  async getFeatureFlag(
+  private async _getFeatureFlagResult(
     key: string,
     distinctId: string,
-    options?: {
+    options: {
       groups?: Record<string, string>
       personProperties?: Record<string, string>
       groupProperties?: Record<string, Record<string, string>>
       onlyEvaluateLocally?: boolean
       sendFeatureFlagEvents?: boolean
       disableGeoip?: boolean
-    }
-  ): Promise<FeatureFlagValue | undefined> {
+    } = {},
+    matchValue?: FeatureFlagValue
+  ): Promise<FeatureFlagResult | undefined> {
+    const sendFeatureFlagEvents = options.sendFeatureFlagEvents ?? true
     // Check for overrides first - they take precedence over all evaluation
     if (this._flagOverrides !== undefined && key in this._flagOverrides) {
-      return this._flagOverrides[key]
+      const overrideValue = this._flagOverrides[key]
+      // undefined override simulates "flag doesn't exist"
+      if (overrideValue === undefined) {
+        return undefined
+      }
+      const overridePayload = this._payloadOverrides?.[key]
+      return {
+        key,
+        enabled: overrideValue !== false,
+        variant: typeof overrideValue === 'string' ? overrideValue : undefined,
+        payload: overridePayload,
+      }
     }
 
-    const { groups, disableGeoip } = options || {}
-    let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {}
+    const { groups, disableGeoip } = options
+    let { onlyEvaluateLocally, personProperties, groupProperties } = options
 
     const adjustedProperties = this.addLocalPersonAndGroupProperties(
       distinctId,
@@ -674,26 +658,58 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (onlyEvaluateLocally == undefined) {
       onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false
     }
-    if (sendFeatureFlagEvents == undefined) {
-      sendFeatureFlagEvents = this.options.sendFeatureFlagEvent ?? true
-    }
 
-    let response = await this.featureFlagsPoller?.getFeatureFlag(
-      key,
-      distinctId,
-      groups,
-      personProperties,
-      groupProperties
-    )
-
-    const flagWasLocallyEvaluated = response !== undefined
+    let result: FeatureFlagResult | undefined = undefined
+    let flagWasLocallyEvaluated = false
     let requestId: string | undefined = undefined
     let evaluatedAt: number | undefined = undefined
-    let flagDetail: FeatureFlagDetail | undefined = undefined
     let featureFlagError: FeatureFlagErrorType | undefined = undefined
+    // Track metadata for event tracking (not exposed in FeatureFlagResult)
+    let flagId: number | undefined = undefined
+    let flagVersion: number | undefined = undefined
+    let flagReason: string | undefined = undefined
+
+    // Try local evaluation first
+    const localEvaluationEnabled = this.featureFlagsPoller !== undefined
+    if (localEvaluationEnabled) {
+      await this.featureFlagsPoller?.loadFeatureFlags()
 
+      const flag = this.featureFlagsPoller?.featureFlagsByKey[key]
+      if (flag) {
+        try {
+          const localResult = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(
+            flag,
+            distinctId,
+            groups,
+            personProperties,
+            groupProperties,
+            matchValue
+          )
+          if (localResult) {
+            flagWasLocallyEvaluated = true
+            const value = localResult.value
+            flagId = flag.id
+            flagReason = 'Evaluated locally'
+            result = {
+              key,
+              enabled: value !== false,
+              variant: typeof value === 'string' ? value : undefined,
+              payload: localResult.payload ?? undefined,
+            }
+          }
+        } catch (e) {
+          if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) {
+            // Fall through to server evaluation
+            this._logger?.info(`${e.name} when computing flag locally: ${key}: ${e.message}`)
+          } else {
+            throw e
+          }
+        }
+      }
+    }
+
+    // Fall back to remote evaluation if needed
     if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
-      // Call getFeatureFlagDetailsStateless directly to get access to error information
       const flagsResponse = await super.getFeatureFlagDetailsStateless(
         distinctId,
         groups,
@@ -704,13 +720,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       )
 
       if (flagsResponse === undefined) {
-        // Request failed (network error, timeout, etc.)
         featureFlagError = FeatureFlagError.UNKNOWN_ERROR
       } else {
         requestId = flagsResponse.requestId
         evaluatedAt = flagsResponse.evaluatedAt
 
-        // Track errors from the response
         const errors: string[] = []
 
         if (flagsResponse.errorsWhileComputingFlags) {
@@ -721,61 +735,162 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
           errors.push(FeatureFlagError.QUOTA_LIMITED)
         }
 
-        flagDetail = flagsResponse.flags[key]
+        const flagDetail = flagsResponse.flags[key]
 
         if (flagDetail === undefined) {
           errors.push(FeatureFlagError.FLAG_MISSING)
+        } else {
+          // Extract metadata for event tracking
+          flagId = flagDetail.metadata?.id
+          flagVersion = flagDetail.metadata?.version
+          flagReason = flagDetail.reason?.description ?? flagDetail.reason?.code
+
+          // Parse payload once from the API response
+          let parsedPayload: JsonType | undefined = undefined
+          if (flagDetail.metadata?.payload !== undefined) {
+            try {
+              parsedPayload = JSON.parse(flagDetail.metadata.payload)
+            } catch {
+              // If parsing fails, return the raw string (matches parsePayload behavior)
+              parsedPayload = flagDetail.metadata.payload
+            }
+          }
+
+          result = {
+            key,
+            enabled: flagDetail.enabled,
+            variant: flagDetail.variant,
+            payload: parsedPayload,
+          }
         }
 
         if (errors.length > 0) {
           featureFlagError = errors.join(',')
         }
-
-        response = getFeatureFlagValue(flagDetail)
       }
     }
 
-    const featureFlagReportedKey = `${key}_${response}`
+    // 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 (
-      sendFeatureFlagEvents &&
-      (!(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]
-      }
+      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: evaluatedAt,
+        }
+
+        if (featureFlagError) {
+          properties.$feature_flag_error = featureFlagError
+        }
 
-      const properties: Record<string, any> = {
-        $feature_flag: key,
-        $feature_flag_response: response,
-        $feature_flag_id: flagDetail?.metadata?.id,
-        $feature_flag_version: flagDetail?.metadata?.version,
-        $feature_flag_reason: flagDetail?.reason?.description ?? flagDetail?.reason?.code,
-        locally_evaluated: flagWasLocallyEvaluated,
-        [`$feature/${key}`]: response,
-        $feature_flag_request_id: requestId,
-        $feature_flag_evaluated_at: evaluatedAt,
+        this.capture({
+          distinctId,
+          event: '$feature_flag_called',
+          properties,
+          groups,
+          disableGeoip,
+        })
       }
+    }
 
-      if (featureFlagError) {
-        properties.$feature_flag_error = featureFlagError
+    // Apply payload override if present (even when there's no flag override)
+    // This ensures consistency with getFeatureFlagPayload behavior
+    if (result !== undefined && this._payloadOverrides !== undefined && key in this._payloadOverrides) {
+      result = {
+        ...result,
+        payload: this._payloadOverrides[key],
       }
+    }
 
-      this.capture({
-        distinctId,
-        event: '$feature_flag_called',
-        properties,
-        groups,
-        disableGeoip,
-      })
+    return result
+  }
+
+  /**
+   * Get the value of a feature flag for a specific user.
+   *
+   * @example
+   * ```ts
+   * // Basic feature flag check
+   * const flagValue = await client.getFeatureFlag('new-feature', 'user_123')
+   * if (flagValue === 'variant-a') {
+   *   // Show variant A
+   * } else if (flagValue === 'variant-b') {
+   *   // Show variant B
+   * } else {
+   *   // Flag is disabled or not found
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With groups and properties
+   * const flagValue = await client.getFeatureFlag('org-feature', 'user_123', {
+   *   groups: { organization: 'acme-corp' },
+   *   personProperties: { plan: 'enterprise' },
+   *   groupProperties: { organization: { tier: 'premium' } }
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Only evaluate locally
+   * const flagValue = await client.getFeatureFlag('local-flag', 'user_123', {
+   *   onlyEvaluateLocally: true
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param key - The feature flag key
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to the flag value or undefined
+   */
+  async getFeatureFlag(
+    key: string,
+    distinctId: string,
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+      sendFeatureFlagEvents?: boolean
+      disableGeoip?: boolean
     }
-    return response
+  ): Promise<FeatureFlagValue | undefined> {
+    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
+    }
+    return result.variant ?? true
   }
 
   /**
@@ -828,74 +943,77 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
   ): Promise<JsonType | undefined> {
     // 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) {
       return this._payloadOverrides[key]
     }
 
-    const { groups, disableGeoip } = options || {}
-    let { onlyEvaluateLocally, personProperties, groupProperties } = options || {}
-
-    const adjustedProperties = this.addLocalPersonAndGroupProperties(
+    // sendFeatureFlagEvents is intentionally ignored for payload-only calls.
+    // getFeatureFlagPayload never sends $feature_flag_called events, matching pre-refactoring behavior.
+    // The option is kept in the signature for backwards compatibility (marked @deprecated above).
+    const result = await this._getFeatureFlagResult(
+      key,
       distinctId,
-      groups,
-      personProperties,
-      groupProperties
+      { ...options, sendFeatureFlagEvents: false },
+      matchValue
     )
 
-    personProperties = adjustedProperties.allPersonProperties
-    groupProperties = adjustedProperties.allGroupProperties
-
-    let response = undefined
-
-    const localEvaluationEnabled = this.featureFlagsPoller !== undefined
-    if (localEvaluationEnabled) {
-      // Ensure flags are loaded before checking for the specific flag
-      await this.featureFlagsPoller?.loadFeatureFlags()
-
-      const flag = this.featureFlagsPoller?.featureFlagsByKey[key]
-      if (flag) {
-        try {
-          const result = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(
-            flag,
-            distinctId,
-            groups,
-            personProperties,
-            groupProperties,
-            matchValue
-          )
-          if (result) {
-            matchValue = result.value
-            response = result.payload
-          }
-        } catch (e) {
-          if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) {
-            // Fall through to server evaluation
-            this._logger?.info(`${e.name} when computing flag locally: ${flag.key}: ${e.message}`)
-          } else {
-            throw e
-          }
-        }
-      }
-    }
-
-    // set defaults
-    if (onlyEvaluateLocally == undefined) {
-      onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false
+    // Return undefined when API fails or flag not found
+    if (result === undefined) {
+      return undefined
     }
 
-    const payloadWasLocallyEvaluated = response !== undefined
+    // Return payload if available, null if flag exists but no payload
+    return result.payload ?? null
+  }
 
-    if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) {
-      response = await super.getFeatureFlagPayloadStateless(
-        key,
-        distinctId,
-        groups,
-        personProperties,
-        groupProperties,
-        disableGeoip
-      )
+  /**
+   * Get the result of evaluating a feature flag, including its value and payload.
+   * This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.
+   *
+   * @example
+   * ```ts
+   * // Get flag result
+   * const result = await client.getFeatureFlagResult('my-flag', 'user_123')
+   * if (result) {
+   *   console.log('Flag enabled:', result.enabled)
+   *   console.log('Variant:', result.variant)
+   *   console.log('Payload:', result.payload)
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With groups and properties
+   * const result = await client.getFeatureFlagResult('org-feature', 'user_123', {
+   *   groups: { organization: 'acme-corp' },
+   *   personProperties: { plan: 'enterprise' }
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param key - The feature flag key
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to the flag result or undefined
+   */
+  async getFeatureFlagResult(
+    key: string,
+    distinctId: string,
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+      sendFeatureFlagEvents?: boolean
+      disableGeoip?: boolean
     }
-    return response
+  ): Promise<FeatureFlagResult | undefined> {
+    return this._getFeatureFlagResult(key, distinctId, {
+      ...options,
+      sendFeatureFlagEvents: options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true,
+    })
   }
 
   /**

package/src/types.ts

@@ -232,6 +232,16 @@ export const FeatureFlagError = {
 
 export type FeatureFlagErrorType = (typeof FeatureFlagError)[keyof typeof FeatureFlagError] | string
 
+/**
+ * Result of evaluating a feature flag, including its value and payload.
+ */
+export type FeatureFlagResult = {
+  key: string
+  enabled: boolean
+  variant: string | undefined
+  payload: JsonType | undefined
+}
+
 export interface IPostHog {
   /**
    * @description Capture allows you to capture anything a user does within your system,
@@ -385,6 +395,38 @@ export interface IPostHog {
     }
   ): Promise<JsonType | undefined>
 
+  /**
+   * @description Get the result of evaluating a feature flag, including its value and payload.
+   * This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.
+   *
+   * @example
+   * ```ts
+   * const result = await client.getFeatureFlagResult('my-flag', 'user_123')
+   * if (result) {
+   *   console.log('Flag enabled:', result.enabled)
+   *   console.log('Variant:', result.variant)
+   *   console.log('Payload:', result.payload)
+   * }
+   * ```
+   *
+   * @param key - The feature flag key
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to the flag result or undefined
+   */
+  getFeatureFlagResult(
+    key: string,
+    distinctId: string,
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+      sendFeatureFlagEvents?: boolean
+      disableGeoip?: boolean
+    }
+  ): Promise<FeatureFlagResult | undefined>
+
   /**
    * @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.21.1'
+export const version = '5.21.2'