posthog-node 4.10.1 → 4.10.2

package/CHANGELOG.md

@@ -1,18 +1,24 @@
 # Next
 
-# 4.10.1 – 2025-03-06
+# 4.10.2 - 2025-03-06
+
+1. Add: log error message when feature flags have computation errors.
+
+# 4.10.1 – 2025-03-06
 
 1. Fix: only set `platform` on PostHog exception frame properties
+1. Fix: prevent fetch floods when rate-limited.
+
 
-# 4.10.0 – 2025-03-06
+# 4.10.0 – 2025-03-06
 
 1. Attach requestId to $feature_flag_called if present in /decide response
 
-# 4.9.0 – 2025-03-04
+# 4.9.0 – 2025-03-04
 
 1. Allow feature flags to be evaluated individually when local evaluation is not being used
 
-# 4.8.1 – 2025-02-26
+# 4.8.1 – 2025-02-26
 
 1. Supports gracefully handling quotaLimited responses from the PostHog API for feature flag evaluation
 

package/lib/index.cjs.js

@@ -7,7 +7,7 @@ var node_fs = require('node:fs');
 var node_readline = require('node:readline');
 var node_path = require('node:path');
 
-var version = "4.10.1";
+var version = "4.10.2";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -29,6 +29,10 @@ var PostHogPersistedProperty;
     PostHogPersistedProperty["InstalledAppVersion"] = "installed_app_version";
     PostHogPersistedProperty["SessionReplay"] = "session_replay";
     PostHogPersistedProperty["DecideEndpointWasHit"] = "decide_endpoint_was_hit";
+    PostHogPersistedProperty["SurveyLastSeenDate"] = "survey_last_seen_date";
+    PostHogPersistedProperty["SurveysSeen"] = "surveys_seen";
+    PostHogPersistedProperty["Surveys"] = "surveys";
+    PostHogPersistedProperty["RemoteConfig"] = "remote_config";
 })(PostHogPersistedProperty || (PostHogPersistedProperty = {}));
 
 function assert(truthyValue, message) {
@@ -966,10 +970,6 @@ var QuotaLimitedFeature;
 class PostHogCoreStateless {
     constructor(apiKey, options) {
         this.flushPromise = null;
-        this.disableGeoip = true;
-        this.historicalMigration = false;
-        this.disabled = false;
-        this.defaultOptIn = true;
         this.pendingPromises = {};
         // internal
         this._events = new SimpleEventEmitter();
@@ -982,8 +982,10 @@ class PostHogCoreStateless {
         this.maxQueueSize = Math.max(this.flushAt, options?.maxQueueSize ?? 1000);
         this.flushInterval = options?.flushInterval ?? 10000;
         this.captureMode = options?.captureMode || 'json';
+        this.preloadFeatureFlags = options?.preloadFeatureFlags ?? true;
         // If enable is explicitly set to false we override the optout
         this.defaultOptIn = options?.defaultOptIn ?? true;
+        this.disableSurveys = options?.disableSurveys ?? false;
         this._retryOptions = {
             retryCount: options?.fetchRetryCount ?? 3,
             retryDelay: options?.fetchRetryDelay ?? 3000,
@@ -991,6 +993,7 @@ class PostHogCoreStateless {
         };
         this.requestTimeout = options?.requestTimeout ?? 10000; // 10 seconds
         this.featureFlagsRequestTimeoutMs = options?.featureFlagsRequestTimeoutMs ?? 3000; // 3 seconds
+        this.remoteConfigRequestTimeoutMs = options?.remoteConfigRequestTimeoutMs ?? 3000; // 3 seconds
         this.disableGeoip = options?.disableGeoip ?? true;
         this.disabled = options?.disabled ?? false;
         this.historicalMigration = options?.historicalMigration ?? false;
@@ -1127,6 +1130,29 @@ class PostHogCoreStateless {
             this.enqueue('capture', payload, options);
         });
     }
+    async getRemoteConfig() {
+        await this._initPromise;
+        let host = this.host;
+        if (host === 'https://us.i.posthog.com') {
+            host = 'https://us-assets.i.posthog.com';
+        }
+        else if (host === 'https://eu.i.posthog.com') {
+            host = 'https://eu-assets.i.posthog.com';
+        }
+        const url = `${host}/array/${this.apiKey}/config`;
+        const fetchOptions = {
+            method: 'GET',
+            headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
+        };
+        // Don't retry remote config API calls
+        return this.fetchWithRetry(url, fetchOptions, { retryCount: 0 }, this.remoteConfigRequestTimeoutMs)
+            .then((response) => response.json())
+            .catch((error) => {
+            this.logMsgIfDebug(() => console.error('Remote config could not be loaded', error));
+            this._events.emit('error', error);
+            return undefined;
+        });
+    }
     /***
      *** FEATURE FLAGS
      ***/
@@ -1216,6 +1242,10 @@ class PostHogCoreStateless {
             extraPayload['flag_keys_to_evaluate'] = flagKeysToEvaluate;
         }
         const decideResponse = await this.getDecide(distinctId, groups, personProperties, groupProperties, extraPayload);
+        // if there's an error on the decideResponse, log a console error, but don't throw an error
+        if (decideResponse?.errorsWhileComputingFlags) {
+            console.error('[FEATURE FLAGS] Error while computing feature flags, some flags may be missing or incorrect. Learn more at https://posthog.com/docs/feature-flags/best-practices');
+        }
         // Add check for quota limitation on feature flags
         if (decideResponse?.quotaLimited?.includes(QuotaLimitedFeature.FeatureFlags)) {
             console.warn('[FEATURE FLAGS] Feature flags quota limit exceeded - feature flags unavailable. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts');
@@ -1237,6 +1267,42 @@ class PostHogCoreStateless {
             requestId: decideResponse?.requestId,
         };
     }
+    /***
+     *** SURVEYS
+     ***/
+    async getSurveysStateless() {
+        await this._initPromise;
+        if (this.disableSurveys === true) {
+            this.logMsgIfDebug(() => console.log('Loading surveys is disabled.'));
+            return [];
+        }
+        const url = `${this.host}/api/surveys/?token=${this.apiKey}`;
+        const fetchOptions = {
+            method: 'GET',
+            headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
+        };
+        const response = await this.fetchWithRetry(url, fetchOptions)
+            .then((response) => {
+            if (response.status !== 200 || !response.json) {
+                const msg = `Surveys API could not be loaded: ${response.status}`;
+                const error = new Error(msg);
+                this.logMsgIfDebug(() => console.error(error));
+                this._events.emit('error', new Error(msg));
+                return undefined;
+            }
+            return response.json();
+        })
+            .catch((error) => {
+            this.logMsgIfDebug(() => console.error('Surveys API could not be loaded', error));
+            this._events.emit('error', error);
+            return undefined;
+        });
+        const newSurveys = response?.surveys;
+        if (newSurveys) {
+            this.logMsgIfDebug(() => console.log('PostHog Debug', 'Surveys fetched from API: ', JSON.stringify(newSurveys)));
+        }
+        return newSurveys ?? [];
+    }
     /***
      *** QUEUEING AND FLUSHING
      ***/
@@ -1520,8 +1586,8 @@ class FeatureFlagsPoller {
     ...options
   }) {
     this.debugMode = false;
-    this.lastRequestWasAuthenticationError = false;
-    this.authenticationErrorCount = 0;
+    this.shouldBeginExponentialBackoff = false;
+    this.backOffCount = 0;
     this.pollingInterval = pollingInterval;
     this.personalApiKey = personalApiKey;
     this.featureFlags = [];
@@ -1759,10 +1825,10 @@ class FeatureFlagsPoller {
    * @returns The polling interval to use for the next request.
    */
   getPollingInterval() {
-    if (!this.lastRequestWasAuthenticationError) {
+    if (!this.shouldBeginExponentialBackoff) {
       return this.pollingInterval;
     }
-    return Math.min(SIXTY_SECONDS, this.pollingInterval * 2 ** this.authenticationErrorCount);
+    return Math.min(SIXTY_SECONDS, this.pollingInterval * 2 ** this.backOffCount);
   }
   async _loadFeatureFlags() {
     if (this.poller) {
@@ -1772,45 +1838,69 @@ class FeatureFlagsPoller {
     this.poller = setTimeout(() => this._loadFeatureFlags(), this.getPollingInterval());
     try {
       const res = await this._requestFeatureFlagDefinitions();
-      if (res && res.status === 401) {
-        this.lastRequestWasAuthenticationError = true;
-        this.authenticationErrorCount += 1;
-        throw new ClientError(`Your project key or personal API key is invalid. Setting next polling interval to ${this.getPollingInterval()}ms. More information: https://posthog.com/docs/api#rate-limiting`);
-      }
-      if (res && res.status === 403) {
-        this.lastRequestWasAuthenticationError = true;
-        this.authenticationErrorCount += 1;
-        throw new ClientError(`Your personal API key does not have permission to fetch feature flag definitions for local evaluation. Setting next polling interval to ${this.getPollingInterval()}ms. Are you sure you're using the correct personal and Project API key pair? More information: https://posthog.com/docs/api/overview`);
-      }
-      if (res && res.status === 402) {
-        // Quota limited - clear all flags
-        console.warn('[FEATURE FLAGS] Feature flags quota limit exceeded - unsetting all local flags. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts');
-        this.featureFlags = [];
-        this.featureFlagsByKey = {};
-        this.groupTypeMapping = {};
-        this.cohorts = {};
-        this.loadedSuccessfullyOnce = false;
-        return;
-      }
-      if (res && res.status !== 200) {
-        // something else went wrong, or the server is down.
-        // In this case, don't override existing flags
+      // Handle undefined res case, this shouldn't happen, but it doesn't hurt to handle it anyway
+      if (!res) {
+        // Don't override existing flags when something goes wrong
         return;
       }
-      const responseJson = await res.json();
-      if (!('flags' in responseJson)) {
-        this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`));
+      // NB ON ERROR HANDLING & `loadedSuccessfullyOnce`:
+      //
+      // `loadedSuccessfullyOnce` indicates we've successfully loaded a valid set of flags at least once.
+      // If we set it to `true` in an error scenario (e.g. 402 Over Quota, 401 Invalid Key, etc.),
+      // any manual call to `loadFeatureFlags()` (without forceReload) will skip refetching entirely,
+      // leaving us stuck with zero or outdated flags. The poller does keep running, but we also want
+      // manual reloads to be possible as soon as the error condition is resolved.
+      //
+      // Therefore, on error statuses, we do *not* set `loadedSuccessfullyOnce = true`, ensuring that
+      // both the background poller and any subsequent manual calls can keep trying to load flags
+      // once the issue (quota, permission, rate limit, etc.) is resolved.
+      switch (res.status) {
+        case 401:
+          // Invalid API key
+          this.shouldBeginExponentialBackoff = true;
+          this.backOffCount += 1;
+          throw new ClientError(`Your project key or personal API key is invalid. Setting next polling interval to ${this.getPollingInterval()}ms. More information: https://posthog.com/docs/api#rate-limiting`);
+        case 402:
+          // Quota exceeded - clear all flags
+          console.warn('[FEATURE FLAGS] Feature flags quota limit exceeded - unsetting all local flags. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts');
+          this.featureFlags = [];
+          this.featureFlagsByKey = {};
+          this.groupTypeMapping = {};
+          this.cohorts = {};
+          return;
+        case 403:
+          // Permissions issue
+          this.shouldBeginExponentialBackoff = true;
+          this.backOffCount += 1;
+          throw new ClientError(`Your personal API key does not have permission to fetch feature flag definitions for local evaluation. Setting next polling interval to ${this.getPollingInterval()}ms. Are you sure you're using the correct personal and Project API key pair? More information: https://posthog.com/docs/api/overview`);
+        case 429:
+          // Rate limited
+          this.shouldBeginExponentialBackoff = true;
+          this.backOffCount += 1;
+          throw new ClientError(`You are being rate limited. Setting next polling interval to ${this.getPollingInterval()}ms. More information: https://posthog.com/docs/api#rate-limiting`);
+        case 200:
+          {
+            // Process successful response
+            const responseJson = await res.json();
+            if (!('flags' in responseJson)) {
+              this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`));
+              return;
+            }
+            this.featureFlags = responseJson.flags || [];
+            this.featureFlagsByKey = this.featureFlags.reduce((acc, curr) => (acc[curr.key] = curr, acc), {});
+            this.groupTypeMapping = responseJson.group_type_mapping || {};
+            this.cohorts = responseJson.cohorts || {};
+            this.loadedSuccessfullyOnce = true;
+            this.shouldBeginExponentialBackoff = false;
+            this.backOffCount = 0;
+            break;
+          }
+        default:
+          // Something else went wrong, or the server is down.
+          // In this case, don't override existing flags
+          return;
       }
-      this.featureFlags = responseJson.flags || [];
-      this.featureFlagsByKey = this.featureFlags.reduce((acc, curr) => (acc[curr.key] = curr, acc), {});
-      this.groupTypeMapping = responseJson.group_type_mapping || {};
-      this.cohorts = responseJson.cohorts || [];
-      this.loadedSuccessfullyOnce = true;
-      this.lastRequestWasAuthenticationError = false;
-      this.authenticationErrorCount = 0;
     } catch (err) {
-      // if an error that is not an instance of ClientError is thrown
-      // we silently ignore the error when reloading feature flags
       if (err instanceof ClientError) {
         this.onError?.(err);
       }
@@ -3058,16 +3148,20 @@ class PostHog extends PostHogCoreStateless {
     super.debug(enabled);
     this.featureFlagsPoller?.debug(enabled);
   }
-  capture({
-    distinctId,
-    event,
-    properties,
-    groups,
-    sendFeatureFlags,
-    timestamp,
-    disableGeoip,
-    uuid
-  }) {
+  capture(props) {
+    if (typeof props === 'string') {
+      this.logMsgIfDebug(() => console.warn('Called capture() with a string as the first argument when an object was expected.'));
+    }
+    const {
+      distinctId,
+      event,
+      properties,
+      groups,
+      sendFeatureFlags,
+      timestamp,
+      disableGeoip,
+      uuid
+    } = props;
     const _capture = props => {
       super.captureStateless(distinctId, event, props, {
         timestamp,