posthog-node 4.7.0 → 4.8.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Next
 
+# 4.8.1 – 2025-02-26
+
+1. Supports gracefully handling quotaLimited responses from the PostHog API for feature flag evaluation
+
+# 4.8.0 - 2025-02-26
+
+1. Add guardrails and exponential error backoff in the feature flag local evaluation poller to prevent high rates of 401/403 traffic towards `/local_evaluation`
+
 # 4.7.0 - 2025-02-20
 
 ## Added

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.7.0";
+var version = "4.8.1";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -958,6 +958,11 @@ class PostHogFetchNetworkError extends Error {
 function isPostHogFetchError(err) {
     return typeof err === 'object' && (err instanceof PostHogFetchHttpError || err instanceof PostHogFetchNetworkError);
 }
+var QuotaLimitedFeature;
+(function (QuotaLimitedFeature) {
+    QuotaLimitedFeature["FeatureFlags"] = "feature_flags";
+    QuotaLimitedFeature["Recordings"] = "recordings";
+})(QuotaLimitedFeature || (QuotaLimitedFeature = {}));
 class PostHogCoreStateless {
     constructor(apiKey, options) {
         this.flushPromise = null;
@@ -1201,6 +1206,14 @@ class PostHogCoreStateless {
             extraPayload['geoip_disable'] = true;
         }
         const decideResponse = await this.getDecide(distinctId, groups, personProperties, groupProperties, extraPayload);
+        // 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');
+            return {
+                flags: undefined,
+                payloads: undefined,
+            };
+        }
         const flags = decideResponse?.featureFlags;
         const payloads = decideResponse?.featureFlagPayloads;
         let parsedPayloads = payloads;
@@ -1495,6 +1508,8 @@ class FeatureFlagsPoller {
     ...options
   }) {
     this.debugMode = false;
+    this.lastRequestWasAuthenticationError = false;
+    this.authenticationErrorCount = 0;
     this.pollingInterval = pollingInterval;
     this.personalApiKey = personalApiKey;
     this.featureFlags = [];
@@ -1506,7 +1521,6 @@ class FeatureFlagsPoller {
     this.projectApiKey = projectApiKey;
     this.host = host;
     this.poller = undefined;
-    // NOTE: as any is required here as the AbortSignal typing is slightly misaligned but works just fine
     this.fetch = options.fetch || fetch$1;
     this.onError = options.onError;
     this.customHeaders = customHeaders;
@@ -1726,16 +1740,45 @@ class FeatureFlagsPoller {
       await this._loadFeatureFlags();
     }
   }
+  /**
+   * If a client is misconfigured with an invalid or improper API key, the polling interval is doubled each time
+   * until a successful request is made, up to a maximum of 60 seconds.
+   *
+   * @returns The polling interval to use for the next request.
+   */
+  getPollingInterval() {
+    if (!this.lastRequestWasAuthenticationError) {
+      return this.pollingInterval;
+    }
+    return Math.min(SIXTY_SECONDS, this.pollingInterval * 2 ** this.authenticationErrorCount);
+  }
   async _loadFeatureFlags() {
     if (this.poller) {
       clearTimeout(this.poller);
       this.poller = undefined;
     }
-    this.poller = setTimeout(() => this._loadFeatureFlags(), this.pollingInterval);
+    this.poller = setTimeout(() => this._loadFeatureFlags(), this.getPollingInterval());
     try {
       const res = await this._requestFeatureFlagDefinitions();
       if (res && res.status === 401) {
-        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`);
+        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.
@@ -1751,6 +1794,8 @@ class FeatureFlagsPoller {
       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
@@ -2939,7 +2984,11 @@ class ErrorTracking {
   }
 }
 
+// Standard local evaluation rate limit is 600 per minute (10 per second),
+// so the fastest a poller should ever be set is 100ms.
+const MINIMUM_POLLING_INTERVAL = 100;
 const THIRTY_SECONDS = 30 * 1000;
+const SIXTY_SECONDS = 60 * 1000;
 const MAX_CACHE_SIZE = 50 * 1000;
 // The actual exported Nodejs API.
 class PostHog extends PostHogCoreStateless {
@@ -2947,9 +2996,13 @@ class PostHog extends PostHogCoreStateless {
     super(apiKey, options);
     this._memoryStorage = new PostHogMemoryStorage();
     this.options = options;
+    this.options.featureFlagsPollingInterval = typeof options.featureFlagsPollingInterval === 'number' ? Math.max(options.featureFlagsPollingInterval, MINIMUM_POLLING_INTERVAL) : THIRTY_SECONDS;
     if (options.personalApiKey) {
+      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: typeof options.featureFlagsPollingInterval === 'number' ? options.featureFlagsPollingInterval : THIRTY_SECONDS,
+        pollingInterval: this.options.featureFlagsPollingInterval,
         personalApiKey: options.personalApiKey,
         projectApiKey: apiKey,
         timeout: options.requestTimeout ?? 10000,
@@ -3404,8 +3457,11 @@ function setupExpressErrorHandler(_posthog, app) {
   });
 }
 
+exports.MINIMUM_POLLING_INTERVAL = MINIMUM_POLLING_INTERVAL;
 exports.PostHog = PostHog;
 exports.PostHogSentryIntegration = PostHogSentryIntegration;
+exports.SIXTY_SECONDS = SIXTY_SECONDS;
+exports.THIRTY_SECONDS = THIRTY_SECONDS;
 exports.createEventProcessor = createEventProcessor;
 exports.sentryIntegration = sentryIntegration;
 exports.setupExpressErrorHandler = setupExpressErrorHandler;