posthog-node 2.2.2 → 2.3.0

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="node" />
+import { JsonType as JsonType$1 } from 'posthog-core/src';
+
 declare type PosthogCoreOptions = {
     host?: string;
     flushAt?: number;
@@ -10,6 +12,7 @@ declare type PosthogCoreOptions = {
         distinctId?: string;
         isIdentifiedId?: boolean;
         featureFlags?: Record<string, boolean | string>;
+        featureFlagPayloads?: Record<string, JsonType>;
     };
     fetchRetryCount?: number;
     fetchRetryDelay?: number;
@@ -31,7 +34,33 @@ declare type PostHogFetchResponse = {
     status: number;
     text: () => Promise<string>;
     json: () => Promise<any>;
-};
+};
+declare type PostHogDecideResponse = {
+    config: {
+        enable_collect_everything: boolean;
+    };
+    editorParams: {
+        toolbarVersion: string;
+        jsURL: string;
+    };
+    isAuthenticated: true;
+    supportedCompression: string[];
+    featureFlags: {
+        [key: string]: string | boolean;
+    };
+    featureFlagPayloads: {
+        [key: string]: JsonType;
+    };
+    errorsWhileComputingFlags: boolean;
+    sessionRecording: boolean;
+};
+declare type PosthogFlagsAndPayloadsResponse = {
+    featureFlags: PostHogDecideResponse['featureFlags'];
+    featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];
+};
+declare type JsonType = string | number | boolean | null | {
+    [key: string]: JsonType;
+} | Array<JsonType>;
 
 interface IdentifyMessageV1 {
     distinctId: string;
@@ -129,6 +158,23 @@ declare type PostHogNodeV1 = {
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
     }): Promise<string | boolean | undefined>;
+    /**
+     * @description Retrieves payload associated with the specified flag and matched value that is passed in.
+     * (Expected to be used in conjuction with getFeatureFlag but allows for manual lookup).
+     * If matchValue isn't passed, getFeatureFlag is called implicitly.
+     * Will try to evaluate for payload locally first otherwise default to network call if allowed
+     *
+     * @param key the unique key of your feature flag
+     * @param distinctId the current unique id
+     * @param matchValue optional- the matched flag string or boolean
+     * @param options: dict with optional parameters below
+     * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
+     *
+     * @returns payload of a json type object
+     */
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
+        onlyEvaluateLocally?: boolean;
+    }): Promise<JsonType$1 | undefined>;
     /**
      * @description Sets a groups properties, which allows asking questions like "Who are the most active companies"
      * using my product in PostHog.
@@ -180,6 +226,13 @@ declare class PostHog implements PostHogNodeV1 {
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
     }): Promise<string | boolean | undefined>;
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+    }): Promise<JsonType | undefined>;
     isFeatureEnabled(key: string, distinctId: string, options?: {
         groups?: Record<string, string>;
         personProperties?: Record<string, string>;
@@ -193,6 +246,12 @@ declare class PostHog implements PostHogNodeV1 {
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
     }): Promise<Record<string, string | boolean>>;
+    getAllFlagsAndPayloads(distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+    }): Promise<PosthogFlagsAndPayloadsResponse>;
     groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void;
     reloadFeatureFlags(): Promise<void>;
     flush(): void;

package/lib/index.esm.js

@@ -155,7 +155,7 @@ function __spreadArray(to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 }
 
-var version = "2.2.2";
+var version = "2.3.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -163,6 +163,7 @@ var PostHogPersistedProperty;
     PostHogPersistedProperty["DistinctId"] = "distinct_id";
     PostHogPersistedProperty["Props"] = "props";
     PostHogPersistedProperty["FeatureFlags"] = "feature_flags";
+    PostHogPersistedProperty["FeatureFlagPayloads"] = "feature_flag_payloads";
     PostHogPersistedProperty["OverrideFeatureFlags"] = "override_feature_flags";
     PostHogPersistedProperty["Queue"] = "queue";
     PostHogPersistedProperty["OptedOut"] = "opted_out";
@@ -771,6 +772,7 @@ var PostHogCore = /** @class */ (function () {
                 return ((res[key] = ((_b = (_a = options.bootstrap) === null || _a === void 0 ? void 0 : _a.featureFlags) === null || _b === void 0 ? void 0 : _b[key]) || false), res);
             }, {});
             this.setKnownFeatureFlags(activeFlags);
+            (options === null || options === void 0 ? void 0 : options.bootstrap.featureFlagPayloads) && this.setKnownFeatureFlagPayloads(options === null || options === void 0 ? void 0 : options.bootstrap.featureFlagPayloads);
         }
     };
     Object.defineProperty(PostHogCore.prototype, "props", {
@@ -950,11 +952,10 @@ var PostHogCore = /** @class */ (function () {
         return this;
     };
     PostHogCore.prototype.groupIdentify = function (groupType, groupKey, groupProperties) {
-        var payload = {
+        var payload = this.buildPayload({
             event: '$groupidentify',
-            distinctId: "$".concat(groupType, "_").concat(groupKey),
             properties: __assign({ $group_type: groupType, $group_key: groupKey, $group_set: groupProperties || {} }, this.getCommonEventProperties()),
-        };
+        });
         this.enqueue('capture', payload);
         return this;
     };
@@ -995,7 +996,7 @@ var PostHogCore = /** @class */ (function () {
             var url, distinctId, groups, personProperties, groupProperties, fetchOptions;
             var _this = this;
             return __generator(this, function (_a) {
-                url = "".concat(this.host, "/decide/?v=2");
+                url = "".concat(this.host, "/decide/?v=3");
                 distinctId = this.getDistinctId();
                 groups = this.props.$groups || {};
                 personProperties = this.getPersistedProperty(PostHogPersistedProperty.PersonProperties) || {};
@@ -1016,7 +1017,17 @@ var PostHogCore = /** @class */ (function () {
                     .then(function (r) { return r.json(); })
                     .then(function (res) {
                     if (res.featureFlags) {
-                        _this.setKnownFeatureFlags(res.featureFlags);
+                        var newFeatureFlags = res.featureFlags;
+                        var newFeatureFlagPayloads = res.featureFlagPayloads;
+                        if (res.errorsWhileComputingFlags) {
+                            // if not all flags were computed, we upsert flags instead of replacing them
+                            var currentFlags = _this.getPersistedProperty(PostHogPersistedProperty.FeatureFlags);
+                            var currentFlagPayloads = _this.getPersistedProperty(PostHogPersistedProperty.FeatureFlagPayloads);
+                            newFeatureFlags = __assign(__assign({}, currentFlags), res.featureFlags);
+                            newFeatureFlagPayloads = __assign(__assign({}, currentFlagPayloads), res.featureFlagPayloads);
+                        }
+                        _this.setKnownFeatureFlags(newFeatureFlags);
+                        _this.setKnownFeatureFlagPayloads(newFeatureFlagPayloads);
                     }
                     return res;
                 })
@@ -1031,6 +1042,9 @@ var PostHogCore = /** @class */ (function () {
         this.setPersistedProperty(PostHogPersistedProperty.FeatureFlags, featureFlags);
         this._events.emit('featureflags', featureFlags);
     };
+    PostHogCore.prototype.setKnownFeatureFlagPayloads = function (featureFlagPayloads) {
+        this.setPersistedProperty(PostHogPersistedProperty.FeatureFlagPayloads, featureFlagPayloads);
+    };
     PostHogCore.prototype.getFeatureFlag = function (key) {
         var featureFlags = this.getFeatureFlags();
         if (!featureFlags) {
@@ -1038,8 +1052,9 @@ var PostHogCore = /** @class */ (function () {
             return undefined;
         }
         var response = featureFlags[key];
+        // `/decide` v3 returns all flags
         if (response === undefined) {
-            // `/decide` returns nothing for flags which are false.
+            // For cases where the flag is unknown, return false
             response = false;
         }
         if (this.sendFeatureFlagEvent && !this.flagCallReported[key]) {
@@ -1052,6 +1067,37 @@ var PostHogCore = /** @class */ (function () {
         // If we have flags we either return the value (true or string) or false
         return response;
     };
+    PostHogCore.prototype.getFeatureFlagPayload = function (key) {
+        var payloads = this.getFeatureFlagPayloads();
+        if (!payloads) {
+            return undefined;
+        }
+        var response = payloads[key];
+        // Undefined means a loading or missing data issue. Null means evaluation happened and there was no match
+        if (response === undefined) {
+            return null;
+        }
+        return this._parsePayload(response);
+    };
+    PostHogCore.prototype.getFeatureFlagPayloads = function () {
+        var _this = this;
+        var payloads = this.getPersistedProperty(PostHogPersistedProperty.FeatureFlagPayloads);
+        if (payloads) {
+            return Object.fromEntries(Object.entries(payloads).map(function (_a) {
+                var k = _a[0], v = _a[1];
+                return [k, _this._parsePayload(v)];
+            }));
+        }
+        return payloads;
+    };
+    PostHogCore.prototype._parsePayload = function (response) {
+        try {
+            return JSON.parse(response);
+        }
+        catch (_a) {
+            return response;
+        }
+    };
     PostHogCore.prototype.getFeatureFlags = function () {
         var flags = this.getPersistedProperty(PostHogPersistedProperty.FeatureFlags);
         var overriddenFlags = this.getPersistedProperty(PostHogPersistedProperty.OverrideFeatureFlags);
@@ -1069,6 +1115,14 @@ var PostHogCore = /** @class */ (function () {
         }
         return flags;
     };
+    PostHogCore.prototype.getFeatureFlagsAndPayloads = function () {
+        var flags = this.getFeatureFlags();
+        var payloads = this.getFeatureFlagPayloads();
+        return {
+            flags: flags,
+            payloads: payloads,
+        };
+    };
     PostHogCore.prototype.isFeatureEnabled = function (key) {
         var response = this.getFeatureFlag(key);
         if (response === undefined) {
@@ -1357,6 +1411,7 @@ function () {
     this.pollingInterval = pollingInterval;
     this.personalApiKey = personalApiKey;
     this.featureFlags = [];
+    this.featureFlagsByKey = {};
     this.groupTypeMapping = {};
     this.loadedSuccessfullyOnce = false;
     this.timeout = timeout;
@@ -1415,10 +1470,9 @@ function () {
             if (featureFlag !== undefined) {
               try {
                 response = this.computeFlagLocally(featureFlag, distinctId, groups, personProperties, groupProperties);
-                console.debug("Successfully computed flag locally: ".concat(key, " -> ").concat(response));
               } catch (e) {
                 if (e instanceof InconclusiveMatchError) {
-                  console.debug("Can't compute flag locally: ".concat(key, ": ").concat(e));
+                  console.error("InconclusiveMatchError when computing flag locally: ".concat(key, ": ").concat(e));
                 } else if (e instanceof Error) {
                   console.error("Error computing flag locally: ".concat(key, ": ").concat(e));
                 }
@@ -1433,7 +1487,51 @@ function () {
     });
   };
 
-  FeatureFlagsPoller.prototype.getAllFlags = function (distinctId, groups, personProperties, groupProperties) {
+  FeatureFlagsPoller.prototype.computeFeatureFlagPayloadLocally = function (key, matchValue) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+
+    return __awaiter(this, void 0, void 0, function () {
+      var response;
+      return __generator(this, function (_j) {
+        switch (_j.label) {
+          case 0:
+            return [4
+            /*yield*/
+            , this.loadFeatureFlags()];
+
+          case 1:
+            _j.sent();
+
+            response = undefined;
+
+            if (!this.loadedSuccessfullyOnce) {
+              return [2
+              /*return*/
+              , undefined];
+            }
+
+            if (typeof matchValue == 'boolean') {
+              response = (_d = (_c = (_b = (_a = this.featureFlagsByKey) === null || _a === void 0 ? void 0 : _a[key]) === null || _b === void 0 ? void 0 : _b.filters) === null || _c === void 0 ? void 0 : _c.payloads) === null || _d === void 0 ? void 0 : _d[matchValue.toString()];
+            } else if (typeof matchValue == 'string') {
+              response = (_h = (_g = (_f = (_e = this.featureFlagsByKey) === null || _e === void 0 ? void 0 : _e[key]) === null || _f === void 0 ? void 0 : _f.filters) === null || _g === void 0 ? void 0 : _g.payloads) === null || _h === void 0 ? void 0 : _h[matchValue];
+            } // Undefined means a loading or missing data issue. Null means evaluation happened and there was no match
+
+
+            if (response === undefined) {
+              return [2
+              /*return*/
+              , null];
+            }
+
+            return [2
+            /*return*/
+            , response];
+        }
+      });
+    });
+  };
+
+  FeatureFlagsPoller.prototype.getAllFlagsAndPayloads = function (distinctId, groups, personProperties, groupProperties) {
     if (groups === void 0) {
       groups = {};
     }
@@ -1447,7 +1545,7 @@ function () {
     }
 
     return __awaiter(this, void 0, void 0, function () {
-      var response, fallbackToDecide;
+      var response, payloads, fallbackToDecide;
 
       var _this = this;
 
@@ -1462,22 +1560,58 @@ function () {
             _a.sent();
 
             response = {};
+            payloads = {};
             fallbackToDecide = this.featureFlags.length == 0;
             this.featureFlags.map(function (flag) {
-              try {
-                response[flag.key] = _this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties);
-              } catch (e) {
-                if (e instanceof InconclusiveMatchError) ; else if (e instanceof Error) {
-                  console.error("Error computing flag locally: ".concat(flag.key, ": ").concat(e));
-                }
-
-                fallbackToDecide = true;
-              }
+              return __awaiter(_this, void 0, void 0, function () {
+                var matchValue, matchPayload, e_1;
+                return __generator(this, function (_a) {
+                  switch (_a.label) {
+                    case 0:
+                      _a.trys.push([0, 2,, 3]);
+
+                      matchValue = this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties);
+                      response[flag.key] = matchValue;
+                      return [4
+                      /*yield*/
+                      , this.computeFeatureFlagPayloadLocally(flag.key, matchValue)];
+
+                    case 1:
+                      matchPayload = _a.sent();
+
+                      if (matchPayload) {
+                        payloads[flag.key] = matchPayload;
+                      }
+
+                      return [3
+                      /*break*/
+                      , 3];
+
+                    case 2:
+                      e_1 = _a.sent();
+
+                      if (e_1 instanceof InconclusiveMatchError) ; else if (e_1 instanceof Error) {
+                        console.error("Error computing flag locally: ".concat(flag.key, ": ").concat(e_1));
+                      }
+
+                      fallbackToDecide = true;
+                      return [3
+                      /*break*/
+                      , 3];
+
+                    case 3:
+                      return [2
+                      /*return*/
+                      ];
+                  }
+                });
+              });
             });
             return [2
             /*return*/
             , {
               response: response,
+              payloads: payloads,
               fallbackToDecide: fallbackToDecide
             }];
         }
@@ -1718,6 +1852,14 @@ function () {
               throw new ClientError("Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview");
             }
 
+            if (res && res.status !== 200) {
+              // something else went wrong, or the server is down.
+              // In this case, don't override existing flags
+              return [2
+              /*return*/
+              ];
+            }
+
             return [4
             /*yield*/
             , res.json()];
@@ -1730,6 +1872,9 @@ function () {
             }
 
             this.featureFlags = responseJson.flags || [];
+            this.featureFlagsByKey = this.featureFlags.reduce(function (acc, curr) {
+              return acc[curr.key] = curr, acc;
+            }, {});
             this.groupTypeMapping = responseJson.group_type_mapping || {};
             this.loadedSuccessfullyOnce = true;
             return [3
@@ -2001,7 +2146,7 @@ function () {
         pollingInterval: typeof options.featureFlagsPollingInterval === 'number' ? options.featureFlagsPollingInterval : THIRTY_SECONDS,
         personalApiKey: options.personalApiKey,
         projectApiKey: apiKey,
-        timeout: (_a = options.requestTimeout) !== null && _a !== void 0 ? _a : 10,
+        timeout: (_a = options.requestTimeout) !== null && _a !== void 0 ? _a : 10000,
         host: this._sharedClient.host,
         fetch: options.fetch
       });
@@ -2143,6 +2288,101 @@ function () {
     });
   };
 
+  PostHog.prototype.getFeatureFlagPayload = function (key, distinctId, matchValue, options) {
+    var _a;
+
+    return __awaiter(this, void 0, void 0, function () {
+      var _b, groups, personProperties, groupProperties, _c, onlyEvaluateLocally, response, payloadWasLocallyEvaluated;
+
+      return __generator(this, function (_d) {
+        switch (_d.label) {
+          case 0:
+            _b = options || {}, groups = _b.groups, personProperties = _b.personProperties, groupProperties = _b.groupProperties;
+            _c = options || {}, onlyEvaluateLocally = _c.onlyEvaluateLocally, _c.sendFeatureFlagEvents;
+            response = undefined;
+            if (!!matchValue) return [3
+            /*break*/
+            , 2];
+            return [4
+            /*yield*/
+            , this.getFeatureFlag(key, distinctId, __assign(__assign({}, options), {
+              onlyEvaluateLocally: true
+            }))];
+
+          case 1:
+            matchValue = _d.sent();
+            _d.label = 2;
+
+          case 2:
+            if (!matchValue) return [3
+            /*break*/
+            , 4];
+            return [4
+            /*yield*/
+            , (_a = this.featureFlagsPoller) === null || _a === void 0 ? void 0 : _a.computeFeatureFlagPayloadLocally(key, matchValue)];
+
+          case 3:
+            response = _d.sent();
+            _d.label = 4;
+
+          case 4:
+            // set defaults
+            if (onlyEvaluateLocally == undefined) {
+              onlyEvaluateLocally = false;
+            }
+
+
+            if (onlyEvaluateLocally == undefined) {
+              onlyEvaluateLocally = false;
+            }
+
+            payloadWasLocallyEvaluated = response !== undefined;
+            if (!(!payloadWasLocallyEvaluated && !onlyEvaluateLocally)) return [3
+            /*break*/
+            , 6];
+            this.reInit(distinctId);
+
+            if (groups != undefined) {
+              this._sharedClient.groups(groups);
+            }
+
+            if (personProperties) {
+              this._sharedClient.personProperties(personProperties);
+            }
+
+            if (groupProperties) {
+              this._sharedClient.groupProperties(groupProperties);
+            }
+
+            return [4
+            /*yield*/
+            , this._sharedClient.reloadFeatureFlagsAsync(false)];
+
+          case 5:
+            _d.sent();
+
+            response = this._sharedClient.getFeatureFlagPayload(key);
+            _d.label = 6;
+
+          case 6:
+            try {
+              return [2
+              /*return*/
+              , JSON.parse(response)];
+            } catch (_e) {
+              return [2
+              /*return*/
+              , response];
+            }
+
+            return [2
+            /*return*/
+            ];
+        }
+      });
+    });
+  };
+
   PostHog.prototype.isFeatureEnabled = function (key, distinctId, options) {
     return __awaiter(this, void 0, void 0, function () {
       var feat;
@@ -2171,10 +2411,30 @@ function () {
   };
 
   PostHog.prototype.getAllFlags = function (distinctId, options) {
+    return __awaiter(this, void 0, void 0, function () {
+      var response;
+      return __generator(this, function (_a) {
+        switch (_a.label) {
+          case 0:
+            return [4
+            /*yield*/
+            , this.getAllFlagsAndPayloads(distinctId, options)];
+
+          case 1:
+            response = _a.sent();
+            return [2
+            /*return*/
+            , response.featureFlags];
+        }
+      });
+    });
+  };
+
+  PostHog.prototype.getAllFlagsAndPayloads = function (distinctId, options) {
     var _a;
 
     return __awaiter(this, void 0, void 0, function () {
-      var _b, groups, personProperties, groupProperties, onlyEvaluateLocally, localEvaluationResult, response, fallbackToDecide, remoteEvaluationResult;
+      var _b, groups, personProperties, groupProperties, onlyEvaluateLocally, localEvaluationResult, featureFlags, featureFlagPayloads, fallbackToDecide, remoteEvaluationResult;
 
       return __generator(this, function (_c) {
         switch (_c.label) {
@@ -2188,15 +2448,17 @@ function () {
 
             return [4
             /*yield*/
-            , (_a = this.featureFlagsPoller) === null || _a === void 0 ? void 0 : _a.getAllFlags(distinctId, groups, personProperties, groupProperties)];
+            , (_a = this.featureFlagsPoller) === null || _a === void 0 ? void 0 : _a.getAllFlagsAndPayloads(distinctId, groups, personProperties, groupProperties)];
 
           case 1:
             localEvaluationResult = _c.sent();
-            response = {};
+            featureFlags = {};
+            featureFlagPayloads = {};
             fallbackToDecide = true;
 
             if (localEvaluationResult) {
-              response = localEvaluationResult.response;
+              featureFlags = localEvaluationResult.response;
+              featureFlagPayloads = localEvaluationResult.payloads;
               fallbackToDecide = localEvaluationResult.fallbackToDecide;
             }
 
@@ -2224,15 +2486,18 @@ function () {
           case 2:
             _c.sent();
 
-            remoteEvaluationResult = this._sharedClient.getFeatureFlags();
-            return [2
-            /*return*/
-            , __assign(__assign({}, response), remoteEvaluationResult)];
+            remoteEvaluationResult = this._sharedClient.getFeatureFlagsAndPayloads();
+            featureFlags = __assign(__assign({}, featureFlags), remoteEvaluationResult.flags || {});
+            featureFlagPayloads = __assign(__assign({}, featureFlagPayloads), remoteEvaluationResult.payloads || {});
+            _c.label = 3;
 
           case 3:
             return [2
             /*return*/
-            , response];
+            , {
+              featureFlags: featureFlags,
+              featureFlagPayloads: featureFlagPayloads
+            }];
         }
       });
     });
@@ -2242,6 +2507,7 @@ function () {
     var groupType = _a.groupType,
         groupKey = _a.groupKey,
         properties = _a.properties;
+    this.reInit("$".concat(groupType, "_").concat(groupKey));
 
     this._sharedClient.groupIdentify(groupType, groupKey, properties);
   };