posthog-node 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -1,6 +1,53 @@
 # Next
 
-# 5.4.0 – 2025-09-07
+# 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.
 
@@ -31,6 +78,7 @@ feat: respect local evaluation preferences with `sendFeatureFlags`; add property
 ## 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.4.0";
+var version = "5.5.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -2861,7 +2861,8 @@ class PostHogBackendClient extends PostHogCoreStateless {
     const capturePromise = Promise.resolve().then(async () => {
       if (sendFeatureFlags) {
         // 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);
+        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.
@@ -2918,7 +2919,8 @@ class PostHogBackendClient extends PostHogCoreStateless {
     const capturePromise = Promise.resolve().then(async () => {
       if (sendFeatureFlags) {
         // 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);
+        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.
@@ -3285,13 +3287,32 @@ class PostHogBackendClient extends PostHogCoreStateless {
       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
+  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 || {})) {
@@ -3299,14 +3320,14 @@ class PostHogBackendClient extends PostHogCoreStateless {
       }
       return await this.getAllFlags(distinctId, {
         groups: groupsWithStringValues,
-        personProperties: cleanPersonProperties,
-        groupProperties: cleanGroupProperties,
+        personProperties: finalPersonProperties,
+        groupProperties: finalGroupProperties,
         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;
+    // 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 = {