posthog-node 4.6.0 → 4.8.0

package/lib/posthog-core/src/index.d.ts

@@ -186,9 +186,22 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     /***
      *** ERROR TRACKING
      ***/
-    captureException(error: Error, additionalProperties?: {
+    captureException(error: unknown, additionalProperties?: {
         [key: string]: any;
     }): void;
+    /**
+     * Capture written user feedback for a LLM trace. Numeric values are converted to strings.
+     * @param traceId The trace ID to capture feedback for.
+     * @param userFeedback The feedback to capture.
+     */
+    captureTraceFeedback(traceId: string | number, userFeedback: string): void;
+    /**
+     * Capture a metric for a LLM trace. Numeric values are converted to strings.
+     * @param traceId The trace ID to capture the metric for.
+     * @param metricName The name of the metric to capture.
+     * @param metricValue The value of the metric to capture.
+     */
+    captureTraceMetric(traceId: string | number, metricName: string, metricValue: string | number | boolean): void;
 }
 export * from './types';
 export { LZString };

package/lib/posthog-core/src/utils.d.ts

@@ -11,4 +11,5 @@ export declare function currentTimestamp(): number;
 export declare function currentISOTime(): string;
 export declare function safeSetTimeout(fn: () => void, timeout: number): any;
 export declare const isPromise: (obj: any) => obj is Promise<any>;
+export declare const isError: (x: unknown) => x is Error;
 export declare function getFetch(): FetchLike | undefined;

package/lib/posthog-node/src/feature-flags.d.ts

@@ -37,6 +37,8 @@ declare class FeatureFlagsPoller {
     customHeaders?: {
         [key: string]: string;
     };
+    lastRequestWasAuthenticationError: boolean;
+    authenticationErrorCount: number;
     constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host, customHeaders, ...options }: FeatureFlagsPollerOptions);
     debug(enabled?: boolean): void;
     private logMsgIfDebug;
@@ -57,6 +59,13 @@ declare class FeatureFlagsPoller {
         key: string;
     }[];
     loadFeatureFlags(forceReload?: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    private getPollingInterval;
     _loadFeatureFlags(): Promise<void>;
     private getPersonalApiKeyRequestOptions;
     _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse>;

package/lib/posthog-node/src/posthog-node.d.ts

@@ -10,6 +10,9 @@ export type PostHogOptions = PostHogCoreOptions & {
     maxCacheSize?: number;
     fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
 };
+export declare const MINIMUM_POLLING_INTERVAL = 100;
+export declare const THIRTY_SECONDS: number;
+export declare const SIXTY_SECONDS: number;
 export declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     private _memoryStorage;
     private featureFlagsPoller?;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",

package/src/feature-flags.ts

@@ -3,6 +3,7 @@ import { FeatureFlagCondition, FlagProperty, PostHogFeatureFlag, PropertyGroup }
 import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src'
 import { safeSetTimeout } from 'posthog-core/src/utils'
 import fetch from './fetch'
+import { SIXTY_SECONDS } from './posthog-node'
 
 // eslint-disable-next-line
 const LONG_SCALE = 0xfffffffffffffff
@@ -57,6 +58,8 @@ class FeatureFlagsPoller {
   debugMode: boolean = false
   onError?: (error: Error) => void
   customHeaders?: { [key: string]: string }
+  lastRequestWasAuthenticationError: boolean = false
+  authenticationErrorCount: number = 0
 
   constructor({
     pollingInterval,
@@ -78,7 +81,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
     this.onError = options.onError
     this.customHeaders = customHeaders
@@ -375,19 +377,44 @@ class FeatureFlagsPoller {
     }
   }
 
+  /**
+   * 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.
+   */
+  private getPollingInterval(): number {
+    if (!this.lastRequestWasAuthenticationError) {
+      return this.pollingInterval
+    }
+
+    return Math.min(SIXTY_SECONDS, this.pollingInterval * 2 ** this.authenticationErrorCount)
+  }
+
   async _loadFeatureFlags(): Promise<void> {
     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) {
+        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 personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview`
+          `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`
         )
       }
 
@@ -410,6 +437,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

package/src/posthog-node.ts

@@ -28,7 +28,11 @@ export type PostHogOptions = PostHogCoreOptions & {
   fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>
 }
 
-const THIRTY_SECONDS = 30 * 1000
+// Standard local evaluation rate limit is 600 per minute (10 per second),
+// so the fastest a poller should ever be set is 100ms.
+export const MINIMUM_POLLING_INTERVAL = 100
+export const THIRTY_SECONDS = 30 * 1000
+export const SIXTY_SECONDS = 60 * 1000
 const MAX_CACHE_SIZE = 50 * 1000
 
 // The actual exported Nodejs API.
@@ -47,12 +51,20 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
 
     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, // 10 seconds

package/test/posthog-node.spec.ts

@@ -1,9 +1,9 @@
-import { PostHog as PostHog } from '../src/posthog-node'
-jest.mock('../src/fetch')
+import { MINIMUM_POLLING_INTERVAL, PostHog as PostHog, THIRTY_SECONDS } from '../src/posthog-node'
 import fetch from '../src/fetch'
 import { anyDecideCall, anyLocalEvalCall, apiImplementation } from './test-utils'
 import { waitForPromises, wait } from '../../posthog-core/test/test-utils/test-utils'
 import { randomUUID } from 'crypto'
+jest.mock('../src/fetch')
 
 jest.mock('../package.json', () => ({ version: '1.2.3' }))
 
@@ -666,6 +666,38 @@ describe('PostHog Node.js', () => {
       )
     })
 
+    it('should use minimum featureFlagsPollingInterval of 100ms if set less to less than 100', async () => {
+      posthog = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        fetchRetryCount: 0,
+        personalApiKey: 'TEST_PERSONAL_API_KEY',
+        featureFlagsPollingInterval: 98,
+      })
+
+      expect(posthog.options.featureFlagsPollingInterval).toEqual(MINIMUM_POLLING_INTERVAL)
+    })
+
+    it('should use default featureFlagsPollingInterval of 30000ms if none provided', async () => {
+      posthog = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        fetchRetryCount: 0,
+        personalApiKey: 'TEST_PERSONAL_API_KEY',
+      })
+
+      expect(posthog.options.featureFlagsPollingInterval).toEqual(THIRTY_SECONDS)
+    })
+
+    it('should throw an error when creating SDK if a project key is passed in as personalApiKey', async () => {
+      expect(() => {
+        posthog = new PostHog('TEST_API_KEY', {
+          host: 'http://example.com',
+          fetchRetryCount: 0,
+          personalApiKey: 'phc_abc123',
+          featureFlagsPollingInterval: 100,
+        })
+      }).toThrow(Error)
+    })
+
     it('captures feature flags with locally evaluated flags', async () => {
       mockedFetch.mockClear()
       mockedFetch.mockClear()