posthog-node 5.3.1 → 5.5.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Next
 
+# 5.5.0 – 2025-07-10
+
+1. feat: make the `sendFeatureFlags` parameter more declarative and ergonomic.  Implementation notes below:
+
+Modified `sendFeatureFlags` to be type `boolean | SendFeatureFlagsOptions`, (which is defined thusly)
+
+```ts
+export interface SendFeatureFlagsOptions {
+  onlyEvaluateLocally?: boolean
+  personProperties?: Record<string, any>
+  groupProperties?: Record<string, Record<string, any>>
+}
+```
+
+This lets users declare (1) whether to use local evaluation, and (2) which properties to supply explicitly for that evaluation, every time they want to send feature flags.  It also supports the old boolean behavior if folks don't care and would rather the SDK infer it.
+
+Now, you can make calls like this
+
+```ts
+posthog.captureImmediate({
+  distinctId: "user123",
+  event: "test event",
+  sendFeatureFlags: {
+    onlyEvaluateLocally: true,
+    personProperties: {
+      plan: "premium",
+    },
+  },
+  properties: {
+    foo: "bar",
+  },
+});
+```
+
+or simply
+
+```
+posthog.captureImmediate({
+  distinctId: "user123",
+  event: "test event",
+  sendFeatureFlags: true // this will still infer local evaluation if it appears to be configured, but it won't try to pull properties from the event message
+  properties: {
+    foo: "bar",
+  },
+});
+```
+
+# 5.4.0 – 2025-07-09
+
+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
@@ -27,6 +78,7 @@
 ## Breaking changes
 
 1. feat: migrate to native fetch, Node 20+ required
+2. PostHog Node now compresses messages with GZip before sending them to our servers when the runtime supports compression. This reduces network bandwidth and improves performance. Network traffic interceptors and test assertions on payloads must handle GZip decompression to inspect the data. Alternatively, you can disable compression by setting `disableCompression: true` in the client configuration during tests.
 
 # 5.0.0-alpha.1 - 2025-04-29
 

package/lib/edge/index.cjs

@@ -937,7 +937,7 @@ function setupExpressErrorHandler(_posthog, app) {
   });
 }
 
-var version = "5.3.1";
+var version = "5.5.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;
@@ -2855,32 +2857,17 @@ 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
+        const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined;
+        return await this.getFeatureFlagsForEvent(distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
       }
       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
@@ -2929,31 +2916,16 @@ 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
+        const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined;
+        return await this.getFeatureFlagsForEvent(distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
       }
       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
@@ -3288,6 +3260,75 @@ class PostHogBackendClient extends PostHogCoreStateless {
       }
     }
   }
+  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, disableGeoip, sendFeatureFlagsOptions) {
+    // Use properties directly from options if they exist
+    const finalPersonProperties = sendFeatureFlagsOptions?.personProperties || {};
+    const finalGroupProperties = sendFeatureFlagsOptions?.groupProperties || {};
+    // Check if we should only evaluate locally
+    const onlyEvaluateLocally = sendFeatureFlagsOptions?.onlyEvaluateLocally ?? false;
+    // If onlyEvaluateLocally is true, only use local evaluation
+    if (onlyEvaluateLocally) {
+      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: finalPersonProperties,
+          groupProperties: finalGroupProperties,
+          disableGeoip,
+          onlyEvaluateLocally: true
+        });
+      } else {
+        // If onlyEvaluateLocally is true but we don't have local flags, return empty
+        return {};
+      }
+    }
+    // Prefer local evaluation if available (default behavior; I'd rather not penalize users who haven't updated to the new API but still want to use local evaluation)
+    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: finalPersonProperties,
+        groupProperties: finalGroupProperties,
+        disableGeoip,
+        onlyEvaluateLocally: true
+      });
+    }
+    // Fall back to remote evaluation if local evaluation is not available
+    return (await super.getFeatureFlagsStateless(distinctId, groups, finalPersonProperties, finalGroupProperties, disableGeoip)).flags;
+  }
   addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties) {
     const allPersonProperties = {
       distinct_id: distinctId,