posthog-node 4.7.0 → 4.8.1

package/lib/index.d.ts

@@ -108,6 +108,7 @@ type PostHogDecideResponse = {
         [key: string]: JsonType;
     };
     errorsWhileComputingFlags: boolean;
+    quotaLimited?: string[];
     sessionRecording?: boolean | {
         [key: string]: JsonType;
     };
@@ -406,6 +407,9 @@ type PostHogOptions = PostHogCoreOptions & {
     maxCacheSize?: number;
     fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
 };
+declare const MINIMUM_POLLING_INTERVAL = 100;
+declare const THIRTY_SECONDS: number;
+declare const SIXTY_SECONDS: number;
 declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     private _memoryStorage;
     private featureFlagsPoller?;
@@ -520,4 +524,4 @@ declare function setupExpressErrorHandler(_posthog: PostHog, app: {
     use: (middleware: ExpressMiddleware | ExpressErrorMiddleware) => unknown;
 }): void;
 
-export { PostHog, PostHogOptions, PostHogSentryIntegration, SentryIntegrationOptions, createEventProcessor, sentryIntegration, setupExpressErrorHandler };
+export { MINIMUM_POLLING_INTERVAL, PostHog, PostHogOptions, PostHogSentryIntegration, SIXTY_SECONDS, SentryIntegrationOptions, THIRTY_SECONDS, createEventProcessor, sentryIntegration, setupExpressErrorHandler };

package/lib/index.esm.js

@@ -3,7 +3,7 @@ import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { posix, dirname, sep } from 'node:path';
 
-var version = "4.7.0";
+var version = "4.8.1";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -954,6 +954,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;
@@ -1197,6 +1202,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;
@@ -1491,6 +1504,8 @@ class FeatureFlagsPoller {
     ...options
   }) {
     this.debugMode = false;
+    this.lastRequestWasAuthenticationError = false;
+    this.authenticationErrorCount = 0;
     this.pollingInterval = pollingInterval;
     this.personalApiKey = personalApiKey;
     this.featureFlags = [];
@@ -1502,7 +1517,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;
@@ -1722,16 +1736,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.
@@ -1747,6 +1790,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
@@ -2935,7 +2980,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 {
@@ -2943,9 +2992,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,
@@ -3400,5 +3453,5 @@ function setupExpressErrorHandler(_posthog, app) {
   });
 }
 
-export { PostHog, PostHogSentryIntegration, createEventProcessor, sentryIntegration, setupExpressErrorHandler };
+export { MINIMUM_POLLING_INTERVAL, PostHog, PostHogSentryIntegration, SIXTY_SECONDS, THIRTY_SECONDS, createEventProcessor, sentryIntegration, setupExpressErrorHandler };
 //# sourceMappingURL=index.esm.js.map