posthog-node 4.14.0 → 4.16.0

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

@@ -3,6 +3,7 @@ import { RetriableOptions } from './utils';
 import { LZString } from './lz-string';
 import { SimpleEventEmitter } from './eventemitter';
 export * as utils from './utils';
+export declare function logFlushError(err: any): Promise<void>;
 export declare abstract class PostHogCoreStateless {
     readonly apiKey: string;
     readonly host: string;
@@ -13,6 +14,7 @@ export declare abstract class PostHogCoreStateless {
     private maxQueueSize;
     private flushInterval;
     private flushPromise;
+    private shutdownPromise;
     private requestTimeout;
     private featureFlagsRequestTimeoutMs;
     private remoteConfigRequestTimeoutMs;
@@ -52,12 +54,19 @@ export declare abstract class PostHogCoreStateless {
      *** TRACKING
      ***/
     protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    protected identifyStatelessImmediate(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
     }, options?: PostHogCaptureOptions): void;
+    protected captureStatelessImmediate(distinctId: string, event: string, properties?: {
+        [key: string]: any;
+    }, options?: PostHogCaptureOptions): Promise<void>;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
     }, options?: PostHogCaptureOptions): void;
+    protected aliasStatelessImmediate(alias: string, distinctId: string, properties?: {
+        [key: string]: any;
+    }, options?: PostHogCaptureOptions): Promise<void>;
     /***
      *** GROUPS
      ***/
@@ -106,6 +115,8 @@ export declare abstract class PostHogCoreStateless {
      *** QUEUEING AND FLUSHING
      ***/
     protected enqueue(type: string, _message: any, options?: PostHogCaptureOptions): void;
+    protected sendImmediate(type: string, _message: any, options?: PostHogCaptureOptions): Promise<void>;
+    private prepareMessage;
     private clearFlushTimer;
     /**
      * Helper for flushing the queue in the background
@@ -118,6 +129,12 @@ export declare abstract class PostHogCoreStateless {
     };
     private _flush;
     private fetchWithRetry;
+    _shutdown(shutdownTimeoutMs?: number): Promise<void>;
+    /**
+     *  Call shutdown() once before the node process exits, so ensure that all events have been sent and all promises
+     *  have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it.
+     * @param shutdownTimeoutMs
+     */
     shutdown(shutdownTimeoutMs?: number): Promise<void>;
 }
 export declare abstract class PostHogCore extends PostHogCoreStateless {

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

@@ -1,12 +1,13 @@
 import { FetchLike } from './types';
 export declare const NEW_FLAGS_ROLLOUT_PERCENTAGE = 1;
 export declare const NEW_FLAGS_EXCLUDED_HASHES: Set<string>;
+export declare const STRING_FORMAT = "utf8";
 export declare function assert(truthyValue: any, message: string): void;
 export declare function removeTrailingSlash(url: string): string;
 export interface RetriableOptions {
     retryCount: number;
     retryDelay: number;
-    retryCheck: (err: any) => boolean;
+    retryCheck: (err: unknown) => boolean;
 }
 export declare function retriable<T>(fn: () => Promise<T>, props: RetriableOptions): Promise<T>;
 export declare function currentTimestamp(): number;

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

@@ -32,12 +32,19 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     disable(): Promise<void>;
     debug(enabled?: boolean): void;
     capture(props: EventMessage): void;
+    captureImmediate(props: EventMessage): Promise<void>;
     identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void;
+    identifyImmediate({ distinctId, properties, disableGeoip }: IdentifyMessage): Promise<void>;
     alias(data: {
         distinctId: string;
         alias: string;
         disableGeoip?: boolean;
     }): void;
+    aliasImmediate(data: {
+        distinctId: string;
+        alias: string;
+        disableGeoip?: boolean;
+    }): Promise<void>;
     isLocalEvaluationReady(): boolean;
     waitForLocalEvaluationReady(timeoutMs?: number): Promise<boolean>;
     getFeatureFlag(key: string, distinctId: string, options?: {
@@ -85,7 +92,7 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
      * This is useful to call if you want to ensure that the feature flags are up to date before calling getFeatureFlag.
      */
     reloadFeatureFlags(): Promise<void>;
-    shutdown(shutdownTimeoutMs?: number): Promise<void>;
+    _shutdown(shutdownTimeoutMs?: number): Promise<void>;
     private addLocalPersonAndGroupProperties;
     captureException(error: unknown, distinctId?: string, additionalProperties?: Record<string | number, any>): void;
 }

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

@@ -70,6 +70,15 @@ export type PostHogNodeV1 = {
      * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
      */
     capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): void;
+    /**
+     * @description Capture an event immediately. Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+     * @param distinctId which uniquely identifies your user
+     * @param event We recommend using [verb] [noun], like movie played or movie updated to easily identify what your events mean later on.
+     * @param properties OPTIONAL | which can be a object with any information you'd like to add
+     * @param groups OPTIONAL | object of what groups are related to this event, example: { company: 'id:5' }. Can be used to analyze companies instead of users.
+     * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
+     */
+    captureImmediate({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): Promise<void>;
     /**
      * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog,
      * and even do things like segment users by these properties.
@@ -78,6 +87,13 @@ export type PostHogNodeV1 = {
      * @param properties with a dict with any key: value pairs
      */
     identify({ distinctId, properties }: IdentifyMessage): void;
+    /**
+     * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog.
+     * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+     * @param distinctId which uniquely identifies your user
+     * @param properties with a dict with any key: value pairs
+     */
+    identifyImmediate({ distinctId, properties }: IdentifyMessage): Promise<void>;
     /**
      * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
      * This will allow you to answer questions like "Which marketing channels leads to users churning after a month?"
@@ -93,6 +109,16 @@ export type PostHogNodeV1 = {
         distinctId: string;
         alias: string;
     }): void;
+    /**
+     * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
+     * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+     * @param distinctId the current unique id
+     * @param alias the unique ID of the user before
+     */
+    aliasImmediate(data: {
+        distinctId: string;
+        alias: string;
+    }): Promise<void>;
     /**
      * @description PostHog feature flags (https://posthog.com/docs/features/feature-flags)
      * allow you to safely deploy and roll back new features. Once you've created a feature flag in PostHog,

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

@@ -14,4 +14,5 @@ export declare const apiImplementation: ({ localFlags, decideFlags, decideFlagPa
 }) => (url: any) => Promise<any>;
 export declare const anyLocalEvalCall: any[];
 export declare const anyDecideCall: any[];
+export declare const isPending: (promise: Promise<any>) => boolean;
 export {};

package/package.json

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

package/src/posthog-node.ts

@@ -199,6 +199,84 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     this.addPendingPromise(capturePromise)
   }
 
+  async captureImmediate(props: EventMessage): Promise<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']): Promise<void> => {
+      return super.captureStatelessImmediate(distinctId, event, props, { timestamp, disableGeoip, uuid })
+    }
+
+    const _getFlags = async (
+      distinctId: EventMessage['distinctId'],
+      groups: EventMessage['groups'],
+      disableGeoip: EventMessage['disableGeoip']
+    ): Promise<PostHogDecideResponse['featureFlags'] | undefined> => {
+      return (await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)).flags
+    }
+
+    const capturePromise = Promise.resolve()
+      .then(async () => {
+        if (sendFeatureFlags) {
+          // If we are sending feature flags, we need to make sure we have the latest flags
+          // return await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)
+          return await _getFlags(distinctId, groups, disableGeoip)
+        }
+
+        if (event === '$feature_flag_called') {
+          // If we're capturing a $feature_flag_called event, we don't want to enrich the event with cached flags that may be out of date.
+          return {}
+        }
+
+        if ((this.featureFlagsPoller?.featureFlags?.length || 0) > 0) {
+          // Otherwise we may as well check for the flags locally and include them if they are already loaded
+          const groupsWithStringValues: Record<string, string> = {}
+          for (const [key, value] of Object.entries(groups || {})) {
+            groupsWithStringValues[key] = String(value)
+          }
+
+          return await this.getAllFlags(distinctId, {
+            groups: groupsWithStringValues,
+            disableGeoip,
+            onlyEvaluateLocally: true,
+          })
+        }
+        return {}
+      })
+      .then((flags) => {
+        // Derive the relevant flag properties to add
+        const additionalProperties: Record<string, any> = {}
+        if (flags) {
+          for (const [feature, variant] of Object.entries(flags)) {
+            additionalProperties[`$feature/${feature}`] = variant
+          }
+        }
+        const activeFlags = Object.keys(flags || {})
+          .filter((flag) => flags?.[flag] !== false)
+          .sort()
+        if (activeFlags.length > 0) {
+          additionalProperties['$active_feature_flags'] = activeFlags
+        }
+
+        return additionalProperties
+      })
+      .catch(() => {
+        // Something went wrong getting the flag info - we should capture the event anyways
+        return {}
+      })
+      .then((additionalProperties) => {
+        // No matter what - capture the event
+        _capture({ ...additionalProperties, ...properties, $groups: groups })
+      })
+
+    await capturePromise
+  }
+
   identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void {
     // Catch properties passed as $set and move them to the top level
 
@@ -219,10 +297,32 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     )
   }
 
+  async identifyImmediate({ distinctId, properties, disableGeoip }: IdentifyMessage): Promise<void> {
+    // promote $set and $set_once to top level
+    const userPropsOnce = properties?.$set_once
+    delete properties?.$set_once
+
+    // if no $set is provided we assume all properties are $set
+    const userProps = properties?.$set || properties
+
+    await super.identifyStatelessImmediate(
+      distinctId,
+      {
+        $set: userProps,
+        $set_once: userPropsOnce,
+      },
+      { disableGeoip }
+    )
+  }
+
   alias(data: { distinctId: string; alias: string; disableGeoip?: boolean }): void {
     super.aliasStateless(data.alias, data.distinctId, undefined, { disableGeoip: data.disableGeoip })
   }
 
+  async aliasImmediate(data: { distinctId: string; alias: string; disableGeoip?: boolean }): Promise<void> {
+    await super.aliasStatelessImmediate(data.alias, data.distinctId, undefined, { disableGeoip: data.disableGeoip })
+  }
+
   isLocalEvaluationReady(): boolean {
     return this.featureFlagsPoller?.isLocalEvaluationReady() ?? false
   }
@@ -535,9 +635,9 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     await this.featureFlagsPoller?.loadFeatureFlags(true)
   }
 
-  async shutdown(shutdownTimeoutMs?: number): Promise<void> {
+  async _shutdown(shutdownTimeoutMs?: number): Promise<void> {
     this.featureFlagsPoller?.stopPoller()
-    return super.shutdown(shutdownTimeoutMs)
+    return super._shutdown(shutdownTimeoutMs)
   }
 
   private addLocalPersonAndGroupProperties(

package/src/types.ts

@@ -79,6 +79,16 @@ export type PostHogNodeV1 = {
    */
   capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): void
 
+  /**
+   * @description Capture an event immediately. Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+   * @param distinctId which uniquely identifies your user
+   * @param event We recommend using [verb] [noun], like movie played or movie updated to easily identify what your events mean later on.
+   * @param properties OPTIONAL | which can be a object with any information you'd like to add
+   * @param groups OPTIONAL | object of what groups are related to this event, example: { company: 'id:5' }. Can be used to analyze companies instead of users.
+   * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
+   */
+  captureImmediate({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): Promise<void>
+
   /**
    * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog,
    * and even do things like segment users by these properties.
@@ -88,6 +98,14 @@ export type PostHogNodeV1 = {
    */
   identify({ distinctId, properties }: IdentifyMessage): void
 
+  /**
+   * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog.
+   * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+   * @param distinctId which uniquely identifies your user
+   * @param properties with a dict with any key: value pairs
+   */
+  identifyImmediate({ distinctId, properties }: IdentifyMessage): Promise<void>
+
   /**
    * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
    * This will allow you to answer questions like "Which marketing channels leads to users churning after a month?"
@@ -101,6 +119,14 @@ export type PostHogNodeV1 = {
    */
   alias(data: { distinctId: string; alias: string }): void
 
+  /**
+   * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
+   * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+   * @param distinctId the current unique id
+   * @param alias the unique ID of the user before
+   */
+  aliasImmediate(data: { distinctId: string; alias: string }): Promise<void>
+
   /**
    * @description PostHog feature flags (https://posthog.com/docs/features/feature-flags)
    * allow you to safely deploy and roll back new features. Once you've created a feature flag in PostHog,

package/test/posthog-node.spec.ts

@@ -1,6 +1,6 @@
 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 { anyDecideCall, anyLocalEvalCall, apiImplementation, isPending } from './test-utils'
 import { waitForPromises, wait } from '../../posthog-core/test/test-utils/test-utils'
 import { randomUUID } from 'crypto'
 jest.mock('../src/fetch')
@@ -381,33 +381,31 @@ describe('PostHog Node.js', () => {
       })
       ph.debug(true)
 
-      // using debug mode to check console.log output
-      // which tells us when the flush is complete
+      ph.capture({ event: 'test-event-1', distinctId: '123' })
 
-      ph.capture({ event: 'test-event', distinctId: '123' })
-      await wait(100)
-      expect(logSpy).toHaveBeenCalledTimes(1)
+      // start flushing, but don't wait for promise to resolve before resuming events
+      const flushPromise = ph.flush()
+      expect(isPending(flushPromise)).toEqual(true)
 
-      ph.capture({ event: 'test-event', distinctId: '123' })
-      ph.capture({ event: 'test-event', distinctId: '123' })
-      await wait(100)
-      expect(logSpy).toHaveBeenCalledTimes(3)
-      await wait(400) // The flush will resolve in this time
-      ph.capture({ event: 'test-event', distinctId: '123' })
-      ph.capture({ event: 'test-event', distinctId: '123' })
-      await wait(100)
-      expect(logSpy).toHaveBeenCalledTimes(6) // 5 captures and 1 flush
-      expect(5).toEqual(logSpy.mock.calls.filter((call) => call[1].includes('capture')).length)
-      expect(1).toEqual(logSpy.mock.calls.filter((call) => call[1].includes('flush')).length)
+      ph.capture({ event: 'test-event-2', distinctId: '123' })
 
-      logSpy.mockClear()
-      expect(logSpy).toHaveBeenCalledTimes(0)
+      // start shutdown, but don't wait for promise to resolve before resuming events
+      const shutdownPromise = ph.shutdown()
 
-      console.warn('YOO!!')
+      ph.capture({ event: 'test-event-3', distinctId: '123' })
+
+      // wait for shutdown to finish
+      await shutdownPromise
+      expect(isPending(flushPromise)).toEqual(false)
+
+      expect(3).toEqual(logSpy.mock.calls.filter((call) => call[1].includes('capture')).length)
+      const flushedEvents = logSpy.mock.calls.filter((call) => call[1].includes('flush')).flatMap((flush) => flush[2])
+      expect(flushedEvents).toMatchObject([
+        { event: 'test-event-1' },
+        { event: 'test-event-2' },
+        { event: 'test-event-3' },
+      ])
 
-      await ph.shutdown()
-      // 1 final flush for the events that were queued during shutdown
-      expect(1).toEqual(logSpy.mock.calls.filter((call) => call[1].includes('flush')).length)
       logSpy.mockRestore()
       warnSpy.mockRestore()
     })

package/test/test-utils.ts

@@ -1,4 +1,5 @@
 import { PostHogV4DecideResponse } from 'posthog-core/src/types'
+import util from 'util'
 
 type ErrorResponse = {
   status: number
@@ -104,3 +105,7 @@ export const anyLocalEvalCall = [
   expect.any(Object),
 ]
 export const anyDecideCall = ['http://example.com/flags/?v=2', expect.any(Object)]
+
+export const isPending = (promise: Promise<any>): boolean => {
+  return util.inspect(promise).includes('pending')
+}