posthog-node 5.2.1 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Next
 
+# 5.4.0 – 2025-09-07
+
+feat: respect local evaluation preferences with `sendFeatureFlags`; add property overrides from the event to those local computations so that the locally evaluated flags can be more accuratee.  NB: this change chagnes the default behavior of `capture` and `captureImmediately` – we will now only send feature flag data along with those events if `sendFeatureFlags` is explicitly specified, instead of optimistically sending along locally evaluated flags by default.
+
+# 5.3.1 - 2025-07-07
+
+1. feat: decouple feature flag local evaluation from personal API keys; support decrypting remote config payloads without relying on the feature flags poller
+
 # 5.2.1 - 2025-07-07
 
 1. feat: add captureExceptionImmediate method on posthog client

package/lib/edge/index.cjs

@@ -937,7 +937,7 @@ function setupExpressErrorHandler(_posthog, app) {
   });
 }
 
-var version = "5.2.1";
+var version = "5.4.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -2231,7 +2231,9 @@ class FeatureFlagsPoller {
           payloads[flag.key] = matchPayload;
         }
       } catch (e) {
-        if (e instanceof InconclusiveMatchError) ; else if (e instanceof Error) {
+        if (e instanceof InconclusiveMatchError) {
+          this.onError?.(new Error(`Unable to compute flag locally: ${flag.key} - ${e.message}`));
+        } else if (e instanceof Error) {
           this.onError?.(new Error(`Error computing flag locally: ${flag.key}: ${e}`));
         }
         fallbackToFlags = true;
@@ -2501,23 +2503,6 @@ class FeatureFlagsPoller {
   stopPoller() {
     clearTimeout(this.poller);
   }
-  _requestRemoteConfigPayload(flagKey) {
-    const url = `${this.host}/api/projects/@current/feature_flags/${flagKey}/remote_config/`;
-    const options = this.getPersonalApiKeyRequestOptions();
-    let abortTimeout = null;
-    if (this.timeout && typeof this.timeout === 'number') {
-      const controller = new AbortController();
-      abortTimeout = safeSetTimeout(() => {
-        controller.abort();
-      }, this.timeout);
-      options.signal = controller.signal;
-    }
-    try {
-      return this.fetch(url, options);
-    } finally {
-      clearTimeout(abortTimeout);
-    }
-  }
 }
 // # This function takes a distinct_id and a feature flag key and returns a float between 0 and 1.
 // # Given the same distinct_id and key, it'll always return the same float. These floats are
@@ -2802,21 +2787,25 @@ class PostHogBackendClient extends PostHogCoreStateless {
       if (options.personalApiKey.includes('phc_')) {
         throw new Error('Your Personal API key is invalid. These keys are prefixed with "phx_" and can be created in PostHog project settings.');
       }
-      this.featureFlagsPoller = new FeatureFlagsPoller({
-        pollingInterval: this.options.featureFlagsPollingInterval,
-        personalApiKey: options.personalApiKey,
-        projectApiKey: apiKey,
-        timeout: options.requestTimeout ?? 10000,
-        host: this.host,
-        fetch: options.fetch,
-        onError: err => {
-          this._events.emit('error', err);
-        },
-        onLoad: count => {
-          this._events.emit('localEvaluationFlagsLoaded', count);
-        },
-        customHeaders: this.getCustomHeaders()
-      });
+      // Only start the poller if local evaluation is enabled (defaults to true for backward compatibility)
+      const shouldEnableLocalEvaluation = options.enableLocalEvaluation !== false;
+      if (shouldEnableLocalEvaluation) {
+        this.featureFlagsPoller = new FeatureFlagsPoller({
+          pollingInterval: this.options.featureFlagsPollingInterval,
+          personalApiKey: options.personalApiKey,
+          projectApiKey: apiKey,
+          timeout: options.requestTimeout ?? 10000,
+          host: this.host,
+          fetch: options.fetch,
+          onError: err => {
+            this._events.emit('error', err);
+          },
+          onLoad: count => {
+            this._events.emit('localEvaluationFlagsLoaded', count);
+          },
+          customHeaders: this.getCustomHeaders()
+        });
+      }
     }
     this.errorTracking = new ErrorTracking(this, options);
     this.distinctIdHasSentFlagCalls = {};
@@ -2868,32 +2857,16 @@ class PostHogBackendClient extends PostHogCoreStateless {
         uuid
       });
     };
-    const _getFlags = async (distinctId, groups, disableGeoip) => {
-      return (await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)).flags;
-    };
     // :TRICKY: If we flush, or need to shut down, to not lose events we want this promise to resolve before we flush
     const capturePromise = Promise.resolve().then(async () => {
       if (sendFeatureFlags) {
-        // If we are sending feature flags, we need to make sure we have the latest flags
-        // return await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)
-        return await _getFlags(distinctId, groups, disableGeoip);
+        // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
+        return await this.getFeatureFlagsForEvent(distinctId, groups, properties, disableGeoip);
       }
       if (event === '$feature_flag_called') {
         // If we're capturing a $feature_flag_called event, we don't want to enrich the event with cached flags that may be out of date.
         return {};
       }
-      if ((this.featureFlagsPoller?.featureFlags?.length || 0) > 0) {
-        // Otherwise we may as well check for the flags locally and include them if they are already loaded
-        const groupsWithStringValues = {};
-        for (const [key, value] of Object.entries(groups || {})) {
-          groupsWithStringValues[key] = String(value);
-        }
-        return await this.getAllFlags(distinctId, {
-          groups: groupsWithStringValues,
-          disableGeoip,
-          onlyEvaluateLocally: true
-        });
-      }
       return {};
     }).then(flags => {
       // Derive the relevant flag properties to add
@@ -2942,31 +2915,15 @@ class PostHogBackendClient extends PostHogCoreStateless {
         uuid
       });
     };
-    const _getFlags = async (distinctId, groups, disableGeoip) => {
-      return (await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)).flags;
-    };
     const capturePromise = Promise.resolve().then(async () => {
       if (sendFeatureFlags) {
-        // If we are sending feature flags, we need to make sure we have the latest flags
-        // return await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)
-        return await _getFlags(distinctId, groups, disableGeoip);
+        // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
+        return await this.getFeatureFlagsForEvent(distinctId, groups, properties, disableGeoip);
       }
       if (event === '$feature_flag_called') {
         // If we're capturing a $feature_flag_called event, we don't want to enrich the event with cached flags that may be out of date.
         return {};
       }
-      if ((this.featureFlagsPoller?.featureFlags?.length || 0) > 0) {
-        // Otherwise we may as well check for the flags locally and include them if they are already loaded
-        const groupsWithStringValues = {};
-        for (const [key, value] of Object.entries(groups || {})) {
-          groupsWithStringValues[key] = String(value);
-        }
-        return await this.getAllFlags(distinctId, {
-          groups: groupsWithStringValues,
-          disableGeoip,
-          onlyEvaluateLocally: true
-        });
-      }
       return {};
     }).then(flags => {
       // Derive the relevant flag properties to add
@@ -3172,7 +3129,10 @@ class PostHogBackendClient extends PostHogCoreStateless {
     return response;
   }
   async getRemoteConfigPayload(flagKey) {
-    const response = await this.featureFlagsPoller?._requestRemoteConfigPayload(flagKey);
+    if (!this.options.personalApiKey) {
+      throw new Error('Personal API key is required for remote config payload decryption');
+    }
+    const response = await this._requestRemoteConfigPayload(flagKey);
     if (!response) {
       return undefined;
     }
@@ -3266,6 +3226,88 @@ class PostHogBackendClient extends PostHogCoreStateless {
     this.featureFlagsPoller?.stopPoller();
     return super._shutdown(shutdownTimeoutMs);
   }
+  async _requestRemoteConfigPayload(flagKey) {
+    if (!this.options.personalApiKey) {
+      return undefined;
+    }
+    const url = `${this.host}/api/projects/@current/feature_flags/${flagKey}/remote_config/`;
+    const options = {
+      method: 'GET',
+      headers: {
+        ...this.getCustomHeaders(),
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.options.personalApiKey}`
+      }
+    };
+    let abortTimeout = null;
+    if (this.options.requestTimeout && typeof this.options.requestTimeout === 'number') {
+      const controller = new AbortController();
+      abortTimeout = safeSetTimeout(() => {
+        controller.abort();
+      }, this.options.requestTimeout);
+      options.signal = controller.signal;
+    }
+    try {
+      return await this.fetch(url, options);
+    } catch (error) {
+      this._events.emit('error', error);
+      return undefined;
+    } finally {
+      if (abortTimeout) {
+        clearTimeout(abortTimeout);
+      }
+    }
+  }
+  extractPropertiesFromEvent(eventProperties, groups) {
+    if (!eventProperties) {
+      return {
+        personProperties: {},
+        groupProperties: {}
+      };
+    }
+    const personProperties = {};
+    const groupProperties = {};
+    for (const [key, value] of Object.entries(eventProperties)) {
+      // If the value is a plain object and the key exists in groups, treat it as group properties
+      if (isPlainObject(value) && groups && key in groups) {
+        const groupProps = {};
+        for (const [groupKey, groupValue] of Object.entries(value)) {
+          groupProps[String(groupKey)] = String(groupValue);
+        }
+        groupProperties[String(key)] = groupProps;
+      } else {
+        // Otherwise treat as person property
+        personProperties[String(key)] = String(value);
+      }
+    }
+    return {
+      personProperties,
+      groupProperties
+    };
+  }
+  async getFeatureFlagsForEvent(distinctId, groups, eventProperties, disableGeoip) {
+    // Extract person and group properties from the event properties
+    const {
+      personProperties: cleanPersonProperties,
+      groupProperties: cleanGroupProperties
+    } = this.extractPropertiesFromEvent(eventProperties, groups);
+    // Prefer local evaluation if available
+    if ((this.featureFlagsPoller?.featureFlags?.length || 0) > 0) {
+      const groupsWithStringValues = {};
+      for (const [key, value] of Object.entries(groups || {})) {
+        groupsWithStringValues[key] = String(value);
+      }
+      return await this.getAllFlags(distinctId, {
+        groups: groupsWithStringValues,
+        personProperties: cleanPersonProperties,
+        groupProperties: cleanGroupProperties,
+        disableGeoip,
+        onlyEvaluateLocally: true
+      });
+    }
+    // Fall back to remote evaluation if local evaluation is not available/is not being used
+    return (await super.getFeatureFlagsStateless(distinctId, groups, cleanPersonProperties, cleanGroupProperties, disableGeoip)).flags;
+  }
   addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties) {
     const allPersonProperties = {
       distinct_id: distinctId,