posthog-node 4.10.0 → 4.10.2

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

@@ -1,18 +1,22 @@
-import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PostHogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType } from './types';
+import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PostHogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType, PostHogRemoteConfig } from './types';
 import { RetriableOptions } from './utils';
 import { LZString } from './lz-string';
 import { SimpleEventEmitter } from './eventemitter';
+import { SurveyResponse } from './surveys-types';
 export * as utils from './utils';
 export declare abstract class PostHogCoreStateless {
     readonly apiKey: string;
     readonly host: string;
     readonly flushAt: number;
+    readonly preloadFeatureFlags: boolean;
+    readonly disableSurveys: boolean;
     private maxBatchSize;
     private maxQueueSize;
     private flushInterval;
     private flushPromise;
     private requestTimeout;
     private featureFlagsRequestTimeoutMs;
+    private remoteConfigRequestTimeoutMs;
     private captureMode;
     private removeDebugCallback?;
     private disableGeoip;
@@ -25,6 +29,7 @@ export declare abstract class PostHogCoreStateless {
     protected _retryOptions: RetriableOptions;
     protected _initPromise: Promise<void>;
     protected _isInitialized: boolean;
+    protected _remoteConfigResponsePromise?: Promise<PostHogRemoteConfig | undefined>;
     abstract fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse>;
     abstract getLibraryId(): string;
     abstract getLibraryVersion(): string;
@@ -58,6 +63,7 @@ export declare abstract class PostHogCoreStateless {
      *** GROUPS
      ***/
     protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): void;
+    protected getRemoteConfig(): Promise<PostHogRemoteConfig | undefined>;
     /***
      *** FEATURE FLAGS
      ***/
@@ -79,6 +85,10 @@ export declare abstract class PostHogCoreStateless {
         payloads: PostHogDecideResponse['featureFlagPayloads'] | undefined;
         requestId: PostHogDecideResponse['requestId'] | undefined;
     }>;
+    /***
+     *** SURVEYS
+     ***/
+    getSurveysStateless(): Promise<SurveyResponse['surveys']>;
     /***
      *** QUEUEING AND FLUSHING
      ***/
@@ -170,10 +180,13 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     groupProperties(properties: {
         [type: string]: Record<string, string>;
     }): void;
+    private remoteConfigAsync;
     /***
      *** FEATURE FLAGS
      ***/
     private decideAsync;
+    private cacheSessionReplay;
+    private _remoteConfigAsync;
     private _decideAsync;
     private setKnownFeatureFlags;
     private setKnownFeatureFlagPayloads;
@@ -187,6 +200,7 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     };
     isFeatureEnabled(key: string): boolean | undefined;
     reloadFeatureFlags(cb?: (err?: Error, flags?: PostHogDecideResponse['featureFlags']) => void): void;
+    reloadRemoteConfigAsync(): Promise<PostHogRemoteConfig | undefined>;
     reloadFeatureFlagsAsync(sendAnonDistinctId?: boolean): Promise<PostHogDecideResponse['featureFlags'] | undefined>;
     onFeatureFlags(cb: (flags: PostHogDecideResponse['featureFlags']) => void): () => void;
     onFeatureFlag(key: string, cb: (value: string | boolean) => void): () => void;

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

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import { Survey } from './surveys-types';
 export type PostHogCoreOptions = {
     /** PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' */
     host?: string;
@@ -20,6 +21,18 @@ export type PostHogCoreOptions = {
     sendFeatureFlagEvent?: boolean;
     /** Whether to load feature flags when initialized or not */
     preloadFeatureFlags?: boolean;
+    /**
+     * Whether to load remote config when initialized or not
+     * Experimental support
+     * Default: false - Remote config is loaded by default
+     */
+    disableRemoteConfig?: boolean;
+    /**
+     * Whether to load surveys when initialized or not
+     * Experimental support
+     * Default: false - Surveys are loaded by default, but requires the `PostHogSurveyProvider` to be used
+     */
+    disableSurveys?: boolean;
     /** Option to bootstrap the library with given distinctId and feature flags */
     bootstrap?: {
         distinctId?: string;
@@ -35,6 +48,8 @@ export type PostHogCoreOptions = {
     requestTimeout?: number;
     /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */
     featureFlagsRequestTimeoutMs?: number;
+    /** Timeout in milliseconds for remote config calls. Defaults to 3 seconds. */
+    remoteConfigRequestTimeoutMs?: number;
     /** For Session Analysis how long before we expire a session (defaults to 30 mins) */
     sessionExpirationTimeSeconds?: number;
     /** Whether to post events to PostHog in JSON or compressed format. Defaults to 'json' */
@@ -61,7 +76,11 @@ export declare enum PostHogPersistedProperty {
     InstalledAppBuild = "installed_app_build",
     InstalledAppVersion = "installed_app_version",
     SessionReplay = "session_replay",
-    DecideEndpointWasHit = "decide_endpoint_was_hit"
+    DecideEndpointWasHit = "decide_endpoint_was_hit",
+    SurveyLastSeenDate = "survey_last_seen_date",
+    SurveysSeen = "surveys_seen",
+    Surveys = "surveys",
+    RemoteConfig = "remote_config"
 }
 export type PostHogFetchOptions = {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH';
@@ -102,16 +121,20 @@ export type PostHogAutocaptureElement = {
 } & {
     [key: string]: any;
 };
-export type PostHogDecideResponse = {
-    config: {
-        enable_collect_everything: boolean;
-    };
-    editorParams: {
-        toolbarVersion: string;
-        jsURL: string;
+export interface PostHogRemoteConfig {
+    sessionRecording?: boolean | {
+        [key: string]: JsonType;
     };
-    isAuthenticated: true;
-    supportedCompression: string[];
+    /**
+     * Whether surveys are enabled
+     */
+    surveys?: boolean | Survey[];
+    /**
+     * Indicates if the team has any flags enabled (if not we don't need to load them)
+     */
+    hasFeatureFlags?: boolean;
+}
+export interface PostHogDecideResponse extends Omit<PostHogRemoteConfig, 'surveys' | 'hasFeatureFlags'> {
     featureFlags: {
         [key: string]: string | boolean;
     };
@@ -119,12 +142,12 @@ export type PostHogDecideResponse = {
         [key: string]: JsonType;
     };
     errorsWhileComputingFlags: boolean;
-    quotaLimited?: string[];
     sessionRecording?: boolean | {
         [key: string]: JsonType;
     };
+    quotaLimited?: string[];
     requestId?: string;
-};
+}
 export type PostHogFlagsAndPayloadsResponse = {
     featureFlags: PostHogDecideResponse['featureFlags'];
     featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];

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

@@ -37,8 +37,8 @@ declare class FeatureFlagsPoller {
     customHeaders?: {
         [key: string]: string;
     };
-    lastRequestWasAuthenticationError: boolean;
-    authenticationErrorCount: number;
+    shouldBeginExponentialBackoff: boolean;
+    backOffCount: number;
     constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host, customHeaders, ...options }: FeatureFlagsPollerOptions);
     debug(enabled?: boolean): void;
     private logMsgIfDebug;

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

@@ -30,7 +30,7 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     enable(): Promise<void>;
     disable(): Promise<void>;
     debug(enabled?: boolean): void;
-    capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip, uuid, }: EventMessage): void;
+    capture(props: EventMessage): void;
     identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void;
     alias(data: {
         distinctId: string;

package/lib/posthog-node/test/test-utils.d.ts

@@ -1,9 +1,10 @@
-export declare const apiImplementation: ({ localFlags, decideFlags, decideFlagPayloads, decideStatus, localFlagsStatus, }: {
+export declare const apiImplementation: ({ localFlags, decideFlags, decideFlagPayloads, decideStatus, localFlagsStatus, errorsWhileComputingFlags, }: {
     localFlags?: any;
     decideFlags?: any;
     decideFlagPayloads?: any;
     decideStatus?: number | undefined;
     localFlagsStatus?: number | undefined;
+    errorsWhileComputingFlags?: boolean | undefined;
 }) => (url: any) => Promise<any>;
 export declare const anyLocalEvalCall: any[];
 export declare const anyDecideCall: any[];

package/package.json

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

package/src/extensions/sentry-integration.ts

@@ -101,11 +101,18 @@ export function createEventProcessor(
 
     const exceptions: _SentryException[] = event.exception?.values || []
 
-    exceptions.map((exception) => {
-      if (exception.stacktrace) {
-        exception.stacktrace.type = 'raw'
-      }
-    })
+    const exceptionList = exceptions.map((exception) => ({
+      ...exception,
+      stacktrace: exception.stacktrace
+        ? {
+            ...exception.stacktrace,
+            type: 'raw',
+            frames: (exception.stacktrace.frames || []).map((frame: any) => {
+              return { ...frame, platform: 'node:javascript' }
+            }),
+          }
+        : undefined,
+    }))
 
     const properties: SentryExceptionProperties & {
       // two properties added to match any exception auto-capture
@@ -121,7 +128,7 @@ export function createEventProcessor(
       $exception_type: exceptions[0]?.type,
       $exception_personURL: personUrl,
       $exception_level: event.level,
-      $exception_list: exceptions,
+      $exception_list: exceptionList,
       // Sentry Exception Properties
       $sentry_event_id: event.event_id,
       $sentry_exception: event.exception,

package/src/feature-flags.ts

@@ -58,8 +58,8 @@ class FeatureFlagsPoller {
   debugMode: boolean = false
   onError?: (error: Error) => void
   customHeaders?: { [key: string]: string }
-  lastRequestWasAuthenticationError: boolean = false
-  authenticationErrorCount: number = 0
+  shouldBeginExponentialBackoff: boolean = false
+  backOffCount: number = 0
 
   constructor({
     pollingInterval,
@@ -384,11 +384,11 @@ class FeatureFlagsPoller {
    * @returns The polling interval to use for the next request.
    */
   private getPollingInterval(): number {
-    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(): Promise<void> {
@@ -402,59 +402,86 @@ class FeatureFlagsPoller {
     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`
-        )
+      // 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
       }
 
-      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`
-        )
-      }
+      // 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`
+          )
 
-      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
-      }
+        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`
+          )
 
-      if (res && res.status !== 200) {
-        // something else went wrong, or the server is down.
-        // In this case, don't override existing flags
-        return
-      }
+        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`
+          )
 
-      const responseJson = await res.json()
-      if (!('flags' in responseJson)) {
-        this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`))
-      }
+        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),
-        <Record<string, PostHogFeatureFlag>>{}
-      )
-      this.groupTypeMapping = responseJson.group_type_mapping || {}
-      this.cohorts = responseJson.cohorts || []
-      this.loadedSuccessfullyOnce = true
-      this.lastRequestWasAuthenticationError = false
-      this.authenticationErrorCount = 0
+          this.featureFlags = responseJson.flags || []
+          this.featureFlagsByKey = this.featureFlags.reduce(
+            (acc, curr) => ((acc[curr.key] = curr), acc),
+            <Record<string, PostHogFeatureFlag>>{}
+          )
+          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
+      }
     } 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)
       }

package/src/posthog-node.ts

@@ -116,16 +116,14 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     this.featureFlagsPoller?.debug(enabled)
   }
 
-  capture({
-    distinctId,
-    event,
-    properties,
-    groups,
-    sendFeatureFlags,
-    timestamp,
-    disableGeoip,
-    uuid,
-  }: EventMessage): void {
+  capture(props: EventMessage): void {
+    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 }: EventMessage =
+      props
     const _capture = (props: EventMessage['properties']): void => {
       super.captureStateless(distinctId, event, props, { timestamp, disableGeoip, uuid })
     }

package/test/extensions/sentry-integration.spec.ts

@@ -138,7 +138,7 @@ describe('PostHogSentryIntegration', () => {
               {
                 type: 'Error',
                 value: 'example error',
-                stacktrace: { frames: [], type: 'raw' },
+                stacktrace: { frames: [] },
                 mechanism: { type: 'generic', handled: true },
               },
             ],

package/test/posthog-node.spec.ts

@@ -328,6 +328,17 @@ describe('PostHog Node.js', () => {
 
       await client.shutdown()
     })
+
+    it('should warn if capture is called with a string', () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      posthog.debug(true)
+      // @ts-expect-error - Testing the warning when passing a string instead of an object
+      posthog.capture('test-event')
+      expect(warnSpy).toHaveBeenCalledWith(
+        'Called capture() with a string as the first argument when an object was expected.'
+      )
+      warnSpy.mockRestore()
+    })
   })
 
   describe('shutdown', () => {
@@ -1308,5 +1319,25 @@ describe('PostHog Node.js', () => {
         })
       )
     })
+
+    it('should log error when decide response has errors', async () => {
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+
+      mockedFetch.mockImplementation(
+        apiImplementation({
+          decideFlags: { 'feature-1': true },
+          decideFlagPayloads: {},
+          errorsWhileComputingFlags: true,
+        })
+      )
+
+      await posthog.getFeatureFlag('feature-1', '123')
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[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'
+      )
+
+      errorSpy.mockRestore()
+    })
   })
 })

package/test/test-utils.ts

@@ -4,12 +4,14 @@ export const apiImplementation = ({
   decideFlagPayloads,
   decideStatus = 200,
   localFlagsStatus = 200,
+  errorsWhileComputingFlags = false,
 }: {
   localFlags?: any
   decideFlags?: any
   decideFlagPayloads?: any
   decideStatus?: number
   localFlagsStatus?: number
+  errorsWhileComputingFlags?: boolean
 }) => {
   return (url: any): Promise<any> => {
     if ((url as any).includes('/decide/')) {
@@ -25,6 +27,7 @@ export const apiImplementation = ({
               featureFlagPayloads: Object.fromEntries(
                 Object.entries(decideFlagPayloads || {}).map(([k, v]) => [k, JSON.stringify(v)])
               ),
+              errorsWhileComputingFlags,
             })
           }
         },