posthog-node 4.13.0 → 4.15.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;
@@ -52,12 +53,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
      ***/
@@ -92,10 +100,22 @@ export declare abstract class PostHogCoreStateless {
      *** SURVEYS
      ***/
     getSurveysStateless(): Promise<SurveyResponse['surveys']>;
+    /***
+     *** SUPER PROPERTIES
+     ***/
+    private _props;
+    protected get props(): PostHogEventProperties;
+    protected set props(val: PostHogEventProperties | undefined);
+    register(properties: {
+        [key: string]: any;
+    }): Promise<void>;
+    unregister(property: string): Promise<void>;
     /***
      *** 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,10 +138,7 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     protected sessionProps: PostHogEventProperties;
     constructor(apiKey: string, options?: PostHogCoreOptions);
     protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
-    private get props();
-    private set props(value);
     private clearProps;
-    private _props;
     on(event: string, cb: (...args: any[]) => void): () => void;
     reset(propertiesToKeep?: PostHogPersistedProperty[]): void;
     protected getCommonEventProperties(): any;
@@ -139,10 +156,6 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
      * * @returns {string} The stored distinct ID. This may be an empty string if the client is not yet fully initialized.
      */
     getDistinctId(): string;
-    unregister(property: string): Promise<void>;
-    register(properties: {
-        [key: string]: any;
-    }): Promise<void>;
     registerForSession(properties: {
         [key: string]: any;
     }): void;

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

@@ -1,6 +1,7 @@
 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 {

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?: {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "4.13.0",
+  "version": "4.15.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
   }

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,