@rpcbase/server 0.520.0 → 0.522.0

package/dist/index.js

@@ -448,6 +448,36 @@ const getDefaultRandom = () => ({
 let defaultGenerator;
 const uuidv7 = () => uuidv7obj().toString();
 const uuidv7obj = () => (defaultGenerator || (defaultGenerator = new V7Generator())).generate();
+var types_PostHogPersistedProperty = /* @__PURE__ */ (function(PostHogPersistedProperty) {
+  PostHogPersistedProperty["AnonymousId"] = "anonymous_id";
+  PostHogPersistedProperty["DistinctId"] = "distinct_id";
+  PostHogPersistedProperty["Props"] = "props";
+  PostHogPersistedProperty["EnablePersonProcessing"] = "enable_person_processing";
+  PostHogPersistedProperty["PersonMode"] = "person_mode";
+  PostHogPersistedProperty["FeatureFlagDetails"] = "feature_flag_details";
+  PostHogPersistedProperty["FeatureFlags"] = "feature_flags";
+  PostHogPersistedProperty["FeatureFlagPayloads"] = "feature_flag_payloads";
+  PostHogPersistedProperty["BootstrapFeatureFlagDetails"] = "bootstrap_feature_flag_details";
+  PostHogPersistedProperty["BootstrapFeatureFlags"] = "bootstrap_feature_flags";
+  PostHogPersistedProperty["BootstrapFeatureFlagPayloads"] = "bootstrap_feature_flag_payloads";
+  PostHogPersistedProperty["OverrideFeatureFlags"] = "override_feature_flags";
+  PostHogPersistedProperty["Queue"] = "queue";
+  PostHogPersistedProperty["OptedOut"] = "opted_out";
+  PostHogPersistedProperty["SessionId"] = "session_id";
+  PostHogPersistedProperty["SessionStartTimestamp"] = "session_start_timestamp";
+  PostHogPersistedProperty["SessionLastTimestamp"] = "session_timestamp";
+  PostHogPersistedProperty["PersonProperties"] = "person_properties";
+  PostHogPersistedProperty["GroupProperties"] = "group_properties";
+  PostHogPersistedProperty["InstalledAppBuild"] = "installed_app_build";
+  PostHogPersistedProperty["InstalledAppVersion"] = "installed_app_version";
+  PostHogPersistedProperty["SessionReplay"] = "session_replay";
+  PostHogPersistedProperty["SurveyLastSeenDate"] = "survey_last_seen_date";
+  PostHogPersistedProperty["SurveysSeen"] = "surveys_seen";
+  PostHogPersistedProperty["Surveys"] = "surveys";
+  PostHogPersistedProperty["RemoteConfig"] = "remote_config";
+  PostHogPersistedProperty["FlagsEndpointWasHit"] = "flags_endpoint_was_hit";
+  return PostHogPersistedProperty;
+})({});
 const DEFAULT_BLOCKED_UA_STRS = [
   "amazonbot",
   "amazonproductbot",
@@ -535,36 +565,6 @@ const isBlockedUA = function(ua, customBlockedUserAgents = []) {
     return -1 !== uaLower.indexOf(blockedUaLower);
   });
 };
-var types_PostHogPersistedProperty = /* @__PURE__ */ (function(PostHogPersistedProperty) {
-  PostHogPersistedProperty["AnonymousId"] = "anonymous_id";
-  PostHogPersistedProperty["DistinctId"] = "distinct_id";
-  PostHogPersistedProperty["Props"] = "props";
-  PostHogPersistedProperty["EnablePersonProcessing"] = "enable_person_processing";
-  PostHogPersistedProperty["PersonMode"] = "person_mode";
-  PostHogPersistedProperty["FeatureFlagDetails"] = "feature_flag_details";
-  PostHogPersistedProperty["FeatureFlags"] = "feature_flags";
-  PostHogPersistedProperty["FeatureFlagPayloads"] = "feature_flag_payloads";
-  PostHogPersistedProperty["BootstrapFeatureFlagDetails"] = "bootstrap_feature_flag_details";
-  PostHogPersistedProperty["BootstrapFeatureFlags"] = "bootstrap_feature_flags";
-  PostHogPersistedProperty["BootstrapFeatureFlagPayloads"] = "bootstrap_feature_flag_payloads";
-  PostHogPersistedProperty["OverrideFeatureFlags"] = "override_feature_flags";
-  PostHogPersistedProperty["Queue"] = "queue";
-  PostHogPersistedProperty["OptedOut"] = "opted_out";
-  PostHogPersistedProperty["SessionId"] = "session_id";
-  PostHogPersistedProperty["SessionStartTimestamp"] = "session_start_timestamp";
-  PostHogPersistedProperty["SessionLastTimestamp"] = "session_timestamp";
-  PostHogPersistedProperty["PersonProperties"] = "person_properties";
-  PostHogPersistedProperty["GroupProperties"] = "group_properties";
-  PostHogPersistedProperty["InstalledAppBuild"] = "installed_app_build";
-  PostHogPersistedProperty["InstalledAppVersion"] = "installed_app_version";
-  PostHogPersistedProperty["SessionReplay"] = "session_replay";
-  PostHogPersistedProperty["SurveyLastSeenDate"] = "survey_last_seen_date";
-  PostHogPersistedProperty["SurveysSeen"] = "surveys_seen";
-  PostHogPersistedProperty["Surveys"] = "surveys";
-  PostHogPersistedProperty["RemoteConfig"] = "remote_config";
-  PostHogPersistedProperty["FlagsEndpointWasHit"] = "flags_endpoint_was_hit";
-  return PostHogPersistedProperty;
-})({});
 const nativeIsArray = Array.isArray;
 const ObjProto = Object.prototype;
 const type_utils_toString = ObjProto.toString;
@@ -2111,7 +2111,8 @@ class ErrorTracking {
       properties: {
         ...exceptionProperties,
         ...properties
-      }
+      },
+      _originatedFromCaptureException: true
     };
   }
   startAutocaptureIfEnabled() {
@@ -2146,7 +2147,7 @@ class ErrorTracking {
     this._rateLimiter.stop();
   }
 }
-const version = "5.24.11";
+const version = "5.26.0";
 const FeatureFlagError = {
   ERRORS_WHILE_COMPUTING: "errors_while_computing_flags",
   FLAG_MISSING: "flag_missing",
@@ -2220,32 +2221,47 @@ class FeatureFlagsPoller {
   logMsgIfDebug(fn) {
     if (this.debugMode) fn();
   }
+  createEvaluationContext(distinctId, groups = {}, personProperties = {}, groupProperties = {}, evaluationCache = {}) {
+    return {
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties,
+      evaluationCache
+    };
+  }
   async getFeatureFlag(key, distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
     await this.loadFeatureFlags();
     let response;
     let featureFlag;
     if (!this.loadedSuccessfullyOnce) return response;
     featureFlag = this.featureFlagsByKey[key];
-    if (void 0 !== featureFlag) try {
-      const result = await this.computeFlagAndPayloadLocally(featureFlag, distinctId, groups, personProperties, groupProperties);
-      response = result.value;
-      this.logMsgIfDebug(() => console.debug(`Successfully computed flag locally: ${key} -> ${response}`));
-    } catch (e) {
-      if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) this.logMsgIfDebug(() => console.debug(`${e.name} when computing flag locally: ${key}: ${e.message}`));
-      else if (e instanceof Error) this.onError?.(new Error(`Error computing flag locally: ${key}: ${e}`));
+    if (void 0 !== featureFlag) {
+      const evaluationContext = this.createEvaluationContext(distinctId, groups, personProperties, groupProperties);
+      try {
+        const result = await this.computeFlagAndPayloadLocally(featureFlag, evaluationContext);
+        response = result.value;
+        this.logMsgIfDebug(() => console.debug(`Successfully computed flag locally: ${key} -> ${response}`));
+      } catch (e) {
+        if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) this.logMsgIfDebug(() => console.debug(`${e.name} when computing flag locally: ${key}: ${e.message}`));
+        else if (e instanceof Error) this.onError?.(new Error(`Error computing flag locally: ${key}: ${e}`));
+      }
     }
     return response;
   }
-  async getAllFlagsAndPayloads(distinctId, groups = {}, personProperties = {}, groupProperties = {}, flagKeysToExplicitlyEvaluate) {
+  async getAllFlagsAndPayloads(evaluationContext, flagKeysToExplicitlyEvaluate) {
     await this.loadFeatureFlags();
     const response = {};
     const payloads = {};
     let fallbackToFlags = 0 == this.featureFlags.length;
     const flagsToEvaluate = flagKeysToExplicitlyEvaluate ? flagKeysToExplicitlyEvaluate.map((key) => this.featureFlagsByKey[key]).filter(Boolean) : this.featureFlags;
-    const sharedEvaluationCache = {};
+    const sharedEvaluationContext = {
+      ...evaluationContext,
+      evaluationCache: evaluationContext.evaluationCache ?? {}
+    };
     await Promise.all(flagsToEvaluate.map(async (flag) => {
       try {
-        const { value: matchValue, payload: matchPayload } = await this.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties, void 0, sharedEvaluationCache);
+        const { value: matchValue, payload: matchPayload } = await this.computeFlagAndPayloadLocally(flag, sharedEvaluationContext);
         response[flag.key] = matchValue;
         if (matchPayload) payloads[flag.key] = matchPayload;
       } catch (e) {
@@ -2260,27 +2276,28 @@ class FeatureFlagsPoller {
       fallbackToFlags
     };
   }
-  async computeFlagAndPayloadLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}, matchValue, evaluationCache, skipLoadCheck = false) {
+  async computeFlagAndPayloadLocally(flag, evaluationContext, options = {}) {
+    const { matchValue, skipLoadCheck = false } = options;
     if (!skipLoadCheck) await this.loadFeatureFlags();
     if (!this.loadedSuccessfullyOnce) return {
       value: false,
       payload: null
     };
     let flagValue;
-    flagValue = void 0 !== matchValue ? matchValue : await this.computeFlagValueLocally(flag, distinctId, groups, personProperties, groupProperties, evaluationCache);
+    flagValue = void 0 !== matchValue ? matchValue : await this.computeFlagValueLocally(flag, evaluationContext);
     const payload = this.getFeatureFlagPayload(flag.key, flagValue);
     return {
       value: flagValue,
       payload
     };
   }
-  async computeFlagValueLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}, evaluationCache = {}) {
+  async computeFlagValueLocally(flag, evaluationContext) {
+    const { distinctId, groups, personProperties, groupProperties } = evaluationContext;
     if (flag.ensure_experience_continuity) throw new InconclusiveMatchError("Flag has experience continuity enabled");
     if (!flag.active) return false;
     const flagFilters = flag.filters || {};
     const aggregation_group_type_index = flagFilters.aggregation_group_type_index;
-    if (void 0 == aggregation_group_type_index) return await this.matchFeatureFlagProperties(flag, distinctId, personProperties, evaluationCache);
-    {
+    if (void 0 != aggregation_group_type_index) {
       const groupName = this.groupTypeMapping[String(aggregation_group_type_index)];
       if (!groupName) {
         this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Unknown group type index ${aggregation_group_type_index} for feature flag ${flag.key}`));
@@ -2290,9 +2307,27 @@ class FeatureFlagsPoller {
         this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Can't compute group feature flag: ${flag.key} without group names passed in`));
         return false;
       }
+      if ("device_id" === flag.bucketing_identifier && (personProperties?.$device_id === void 0 || personProperties?.$device_id === null || personProperties?.$device_id === "")) this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Ignoring bucketing_identifier for group flag: ${flag.key}`));
       const focusedGroupProperties = groupProperties[groupName];
-      return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties, evaluationCache);
+      return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties, evaluationContext);
     }
+    {
+      const bucketingValue = this.getBucketingValueForFlag(flag, distinctId, personProperties);
+      if (void 0 === bucketingValue) {
+        this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Can't compute feature flag: ${flag.key} without $device_id, falling back to server evaluation`));
+        throw new InconclusiveMatchError(`Can't compute feature flag: ${flag.key} without $device_id`);
+      }
+      return await this.matchFeatureFlagProperties(flag, bucketingValue, personProperties, evaluationContext);
+    }
+  }
+  getBucketingValueForFlag(flag, distinctId, properties) {
+    if (flag.filters?.aggregation_group_type_index != void 0) return distinctId;
+    if ("device_id" === flag.bucketing_identifier) {
+      const deviceId = properties?.$device_id;
+      if (null == deviceId || "" === deviceId) return;
+      return deviceId;
+    }
+    return distinctId;
   }
   getFeatureFlagPayload(key, flagValue) {
     let payload = null;
@@ -2310,7 +2345,8 @@ class FeatureFlagsPoller {
     }
     return null;
   }
-  async evaluateFlagDependency(property, distinctId, properties, evaluationCache) {
+  async evaluateFlagDependency(property, properties, evaluationContext) {
+    const { evaluationCache } = evaluationContext;
     const targetFlagKey = property.key;
     if (!this.featureFlagsByKey) throw new InconclusiveMatchError("Feature flags not available for dependency evaluation");
     if (!("dependency_chain" in property)) throw new InconclusiveMatchError(`Flag dependency property for '${targetFlagKey}' is missing required 'dependency_chain' field`);
@@ -2321,7 +2357,7 @@ class FeatureFlagsPoller {
       if (!(depFlagKey in evaluationCache)) {
         const depFlag = this.featureFlagsByKey[depFlagKey];
         if (depFlag) if (depFlag.active) try {
-          const depResult = await this.matchFeatureFlagProperties(depFlag, distinctId, properties, evaluationCache);
+          const depResult = await this.computeFlagValueLocally(depFlag, evaluationContext);
           evaluationCache[depFlagKey] = depResult;
         } catch (error) {
           throw new InconclusiveMatchError(`Error evaluating flag dependency '${depFlagKey}' for flag '${targetFlagKey}': ${error}`);
@@ -2340,16 +2376,16 @@ class FeatureFlagsPoller {
     if ("string" == typeof expectedValue) return flagValue === expectedValue;
     return false;
   }
-  async matchFeatureFlagProperties(flag, distinctId, properties, evaluationCache = {}) {
+  async matchFeatureFlagProperties(flag, bucketingValue, properties, evaluationContext) {
     const flagFilters = flag.filters || {};
     const flagConditions = flagFilters.groups || [];
     let isInconclusive = false;
     let result;
     for (const condition of flagConditions) try {
-      if (await this.isConditionMatch(flag, distinctId, condition, properties, evaluationCache)) {
+      if (await this.isConditionMatch(flag, bucketingValue, condition, properties, evaluationContext)) {
         const variantOverride = condition.variant;
         const flagVariants = flagFilters.multivariate?.variants || [];
-        result = variantOverride && flagVariants.some((variant) => variant.key === variantOverride) ? variantOverride : await this.getMatchingVariant(flag, distinctId) || true;
+        result = variantOverride && flagVariants.some((variant) => variant.key === variantOverride) ? variantOverride : await this.getMatchingVariant(flag, bucketingValue) || true;
         break;
       }
     } catch (e) {
@@ -2361,7 +2397,7 @@ class FeatureFlagsPoller {
     if (isInconclusive) throw new InconclusiveMatchError("Can't determine if feature flag is enabled or not with given properties");
     return false;
   }
-  async isConditionMatch(flag, distinctId, condition, properties, evaluationCache = {}) {
+  async isConditionMatch(flag, bucketingValue, condition, properties, evaluationContext) {
     const rolloutPercentage = condition.rollout_percentage;
     const warnFunction = (msg) => {
       this.logMsgIfDebug(() => console.warn(msg));
@@ -2370,16 +2406,16 @@ class FeatureFlagsPoller {
       for (const prop of condition.properties) {
         const propertyType = prop.type;
         let matches = false;
-        matches = "cohort" === propertyType ? matchCohort(prop, properties, this.cohorts, this.debugMode) : "flag" === propertyType ? await this.evaluateFlagDependency(prop, distinctId, properties, evaluationCache) : matchProperty(prop, properties, warnFunction);
+        matches = "cohort" === propertyType ? matchCohort(prop, properties, this.cohorts, this.debugMode) : "flag" === propertyType ? await this.evaluateFlagDependency(prop, properties, evaluationContext) : matchProperty(prop, properties, warnFunction);
         if (!matches) return false;
       }
       if (void 0 == rolloutPercentage) return true;
     }
-    if (void 0 != rolloutPercentage && await _hash(flag.key, distinctId) > rolloutPercentage / 100) return false;
+    if (void 0 != rolloutPercentage && await _hash(flag.key, bucketingValue) > rolloutPercentage / 100) return false;
     return true;
   }
-  async getMatchingVariant(flag, distinctId) {
-    const hashValue = await _hash(flag.key, distinctId, "variant");
+  async getMatchingVariant(flag, bucketingValue) {
+    const hashValue = await _hash(flag.key, bucketingValue, "variant");
     const matchingVariant = this.variantLookupTable(flag).find((variant) => hashValue >= variant.valueMin && hashValue < variant.valueMax);
     if (matchingVariant) return matchingVariant.key;
   }
@@ -2567,8 +2603,8 @@ class FeatureFlagsPoller {
     }
   }
 }
-async function _hash(key, distinctId, salt = "") {
-  const hashString = await hashSHA1(`${key}.${distinctId}${salt}`);
+async function _hash(key, bucketingValue, salt = "") {
+  const hashString = await hashSHA1(`${key}.${bucketingValue}${salt}`);
   return parseInt(hashString.slice(0, 15), 16) / LONG_SCALE;
 }
 function matchProperty(property, propertyValues, warnFunction) {
@@ -2804,6 +2840,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
   }
   capture(props) {
     if ("string" == typeof props) this._logger.warn("Called capture() with a string as the first argument when an object was expected.");
+    if ("$exception" === props.event && !props._originatedFromCaptureException) this._logger.warn("Using `posthog.capture('$exception')` is unreliable because it does not attach required metadata. Use `posthog.captureException(error)` instead, which attaches required metadata automatically.");
     this.addPendingPromise(this.prepareEventMessage(props).then(({ distinctId, event, properties, options }) => super.captureStateless(distinctId, event, properties, {
       timestamp: options.timestamp,
       disableGeoip: options.disableGeoip,
@@ -2814,6 +2851,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
   }
   async captureImmediate(props) {
     if ("string" == typeof props) this._logger.warn("Called captureImmediate() with a string as the first argument when an object was expected.");
+    if ("$exception" === props.event && !props._originatedFromCaptureException) this._logger.warn("Capturing a `$exception` event via `posthog.captureImmediate('$exception')` is unreliable because it does not attach required metadata. Use `posthog.captureExceptionImmediate(error)` instead, which attaches this metadata by default.");
     return this.addPendingPromise(this.prepareEventMessage(props).then(({ distinctId, event, properties, options }) => super.captureStatelessImmediate(distinctId, event, properties, {
       timestamp: options.timestamp,
       disableGeoip: options.disableGeoip,
@@ -2876,6 +2914,16 @@ class PostHogBackendClient extends PostHogCoreStateless {
       });
     });
   }
+  _resolveDistinctId(distinctIdOrOptions, options) {
+    if ("string" == typeof distinctIdOrOptions) return {
+      distinctId: distinctIdOrOptions,
+      options
+    };
+    return {
+      distinctId: this.context?.get()?.distinctId,
+      options: distinctIdOrOptions
+    };
+  }
   async _getFeatureFlagResult(key, distinctId, options = {}, matchValue) {
     const sendFeatureFlagEvents = options.sendFeatureFlagEvents ?? true;
     if (void 0 !== this._flagOverrides && key in this._flagOverrides) {
@@ -2894,6 +2942,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
     const adjustedProperties = this.addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties);
     personProperties = adjustedProperties.allPersonProperties;
     groupProperties = adjustedProperties.allGroupProperties;
+    const evaluationContext = this.createFeatureFlagEvaluationContext(distinctId, groups, personProperties, groupProperties);
     if (void 0 == onlyEvaluateLocally) onlyEvaluateLocally = this.options.strictLocalEvaluation ?? false;
     let result;
     let flagWasLocallyEvaluated = false;
@@ -2908,7 +2957,9 @@ class PostHogBackendClient extends PostHogCoreStateless {
       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);
+        const localResult = await this.featureFlagsPoller?.computeFlagAndPayloadLocally(flag, evaluationContext, {
+          matchValue
+        });
         if (localResult) {
           flagWasLocallyEvaluated = true;
           const value = localResult.value;
@@ -2927,7 +2978,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
       }
     }
     if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
-      const flagsResponse = await super.getFeatureFlagDetailsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, [
+      const flagsResponse = await super.getFeatureFlagDetailsStateless(evaluationContext.distinctId, evaluationContext.groups, evaluationContext.personProperties, evaluationContext.groupProperties, disableGeoip, [
         key
       ]);
       if (void 0 === flagsResponse) featureFlagError = FeatureFlagError.UNKNOWN_ERROR;
@@ -3013,10 +3064,12 @@ class PostHogBackendClient extends PostHogCoreStateless {
     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 getFeatureFlagResult(key, distinctIdOrOptions, options) {
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(distinctIdOrOptions, options);
+    if (!resolvedDistinctId) return void this._logger.warn("[PostHog] distinctId is required — pass it explicitly or use withContext()");
+    return this._getFeatureFlagResult(key, resolvedDistinctId, {
+      ...resolvedOptions,
+      sendFeatureFlagEvents: resolvedOptions?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true
     });
   }
   async getRemoteConfigPayload(flagKey) {
@@ -3035,18 +3088,32 @@ class PostHogBackendClient extends PostHogCoreStateless {
     if (void 0 === feat) return;
     return !!feat || false;
   }
-  async getAllFlags(distinctId, options) {
-    const response = await this.getAllFlagsAndPayloads(distinctId, options);
+  async getAllFlags(distinctIdOrOptions, options) {
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(distinctIdOrOptions, options);
+    if (!resolvedDistinctId) {
+      this._logger.warn("[PostHog] distinctId is required to get feature flags — pass it explicitly or use withContext()");
+      return {};
+    }
+    const response = await this.getAllFlagsAndPayloads(resolvedDistinctId, resolvedOptions);
     return response.featureFlags || {};
   }
-  async getAllFlagsAndPayloads(distinctId, options) {
-    const { groups, disableGeoip, flagKeys } = options || {};
-    let { onlyEvaluateLocally, personProperties, groupProperties } = options || {};
-    const adjustedProperties = this.addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties);
+  async getAllFlagsAndPayloads(distinctIdOrOptions, options) {
+    const { distinctId: resolvedDistinctId, options: resolvedOptions } = this._resolveDistinctId(distinctIdOrOptions, options);
+    if (!resolvedDistinctId) {
+      this._logger.warn("[PostHog] distinctId is required to get feature flags and payloads — pass it explicitly or use withContext()");
+      return {
+        featureFlags: {},
+        featureFlagPayloads: {}
+      };
+    }
+    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 localEvaluationResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(distinctId, groups, personProperties, groupProperties, flagKeys);
+    const localEvaluationResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(evaluationContext, flagKeys);
     let featureFlags = {};
     let featureFlagPayloads = {};
     let fallbackToFlags = true;
@@ -3056,7 +3123,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
       fallbackToFlags = localEvaluationResult.fallbackToFlags;
     }
     if (fallbackToFlags && !onlyEvaluateLocally) {
-      const remoteEvaluationResult = await super.getFeatureFlagsAndPayloadsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, flagKeys);
+      const remoteEvaluationResult = await super.getFeatureFlagsAndPayloadsStateless(evaluationContext.distinctId, evaluationContext.groups, evaluationContext.personProperties, evaluationContext.groupProperties, disableGeoip, flagKeys);
       featureFlags = {
         ...featureFlags,
         ...remoteEvaluationResult.flags || {}
@@ -3141,6 +3208,9 @@ class PostHogBackendClient extends PostHogCoreStateless {
   getContext() {
     return this.context?.get();
   }
+  enterContext(data, options) {
+    this.context?.enter(data, options);
+  }
   async _shutdown(shutdownTimeoutMs) {
     this.featureFlagsPoller?.stopPoller(shutdownTimeoutMs);
     this.errorTracking.shutdown();
@@ -3238,6 +3308,15 @@ class PostHogBackendClient extends PostHogCoreStateless {
       allGroupProperties
     };
   }
+  createFeatureFlagEvaluationContext(distinctId, groups, personProperties, groupProperties) {
+    return {
+      distinctId,
+      groups: groups || {},
+      personProperties: personProperties || {},
+      groupProperties: groupProperties || {},
+      evaluationCache: {}
+    };
+  }
   captureException(error, distinctId, additionalProperties, uuid) {
     if (!ErrorTracking.isPreviouslyCapturedError(error)) {
       const syntheticException = new Error("PostHog syntheticException");
@@ -3262,6 +3341,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
     const contextData = this.context?.get();
     let mergedDistinctId = distinctId || contextData?.distinctId;
     const mergedProperties = {
+      ...this.props,
       ...contextData?.properties || {},
       ...properties || {}
     };
@@ -3348,20 +3428,22 @@ class PostHogContext {
     return this.storage.getStore();
   }
   run(context, fn, options) {
-    const fresh = options?.fresh === true;
-    if (fresh) return this.storage.run(context, fn);
-    {
-      const currentContext = this.get() || {};
-      const mergedContext = {
-        distinctId: context.distinctId ?? currentContext.distinctId,
-        sessionId: context.sessionId ?? currentContext.sessionId,
-        properties: {
-          ...currentContext.properties || {},
-          ...context.properties || {}
-        }
-      };
-      return this.storage.run(mergedContext, fn);
-    }
+    return this.storage.run(this.resolve(context, options), fn);
+  }
+  enter(context, options) {
+    this.storage.enterWith(this.resolve(context, options));
+  }
+  resolve(context, options) {
+    if (options?.fresh === true) return context;
+    const current = this.get() || {};
+    return {
+      distinctId: context.distinctId ?? current.distinctId,
+      sessionId: context.sessionId ?? current.sessionId,
+      properties: {
+        ...current.properties || {},
+        ...context.properties || {}
+      }
+    };
   }
 }
 function setupExpressErrorHandler(_posthog, app) {