posthog-node 3.4.0 → 3.6.0

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

@@ -1,4 +1,4 @@
-import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PosthogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PosthogCaptureOptions, JsonType } from './types';
+import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PosthogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType } from './types';
 import { RetriableOptions } from './utils';
 export * as utils from './utils';
 import { LZString } from './lz-string';
@@ -12,9 +12,9 @@ export declare abstract class PostHogCoreStateless {
     private captureMode;
     private removeDebugCallback?;
     private debugMode;
-    private pendingPromises;
     private disableGeoip;
     private _optoutOverride;
+    private pendingPromises;
     protected _events: SimpleEventEmitter;
     protected _flushTimer?: any;
     protected _retryOptions: RetriableOptions;
@@ -32,20 +32,21 @@ export declare abstract class PostHogCoreStateless {
     on(event: string, cb: (...args: any[]) => void): () => void;
     debug(enabled?: boolean): void;
     private buildPayload;
+    protected addPendingPromise(promise: Promise<any>): void;
     /***
      *** TRACKING
      ***/
-    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PosthogCaptureOptions): this;
+    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
-    }, options?: PosthogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): this;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
-    }, options?: PosthogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): this;
     /***
      *** GROUPS
      ***/
-    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PosthogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): this;
+    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): this;
     /***
      *** FEATURE FLAGS
      ***/
@@ -62,7 +63,7 @@ export declare abstract class PostHogCoreStateless {
     /***
      *** QUEUEING AND FLUSHING
      ***/
-    protected enqueue(type: string, _message: any, options?: PosthogCaptureOptions): void;
+    protected enqueue(type: string, _message: any, options?: PostHogCaptureOptions): void;
     flushAsync(): Promise<any>;
     flush(callback?: (err?: any, data?: any) => void): void;
     private fetchWithRetry;
@@ -100,20 +101,20 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     /***
      *** TRACKING
      ***/
-    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PosthogCaptureOptions): this;
+    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
     capture(event: string, properties?: {
         [key: string]: any;
-    }, options?: PosthogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): this;
     alias(alias: string): this;
-    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PosthogCaptureOptions): this;
+    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
     /***
      *** GROUPS
      ***/
     groups(groups: {
         [type: string]: string | number;
     }): this;
-    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PosthogCaptureOptions): this;
-    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PosthogCaptureOptions): this;
+    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
     /***
      * PROPERTIES
      ***/

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

@@ -45,7 +45,10 @@ export declare type PostHogFetchOptions = {
     body?: string;
     signal?: AbortSignal;
 };
-export declare type PosthogCaptureOptions = {
+export declare type PostHogCaptureOptions = {
+    /** If provided overrides the auto-generated event ID */
+    uuid?: string;
+    /** If provided overrides the auto-generated timestamp */
     timestamp?: Date;
     disableGeoip?: boolean;
 };

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

@@ -1,5 +1,5 @@
 import { JsonType, PosthogCoreOptions, PostHogCoreStateless, PostHogFetchOptions, PostHogFetchResponse, PosthogFlagsAndPayloadsResponse, PostHogPersistedProperty } from '../../posthog-core/src';
-import { EventMessageV1, GroupIdentifyMessage, IdentifyMessageV1, PostHogNodeV1 } from './types';
+import { EventMessage, GroupIdentifyMessage, IdentifyMessage, PostHogNodeV1 } from './types';
 export declare type PostHogOptions = PosthogCoreOptions & {
     persistence?: 'memory';
     personalApiKey?: string;
@@ -24,8 +24,8 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     enable(): void;
     disable(): void;
     debug(enabled?: boolean): void;
-    capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip }: EventMessageV1): void;
-    identify({ distinctId, properties, disableGeoip }: IdentifyMessageV1): void;
+    capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip, uuid, }: EventMessage): void;
+    identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void;
     alias(data: {
         distinctId: string;
         alias: string;
@@ -73,4 +73,5 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     reloadFeatureFlags(): Promise<void>;
     shutdown(): void;
     shutdownAsync(): Promise<void>;
+    private addLocalPersonAndGroupProperties;
 }

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

@@ -1,14 +1,15 @@
 import { JsonType } from '../../posthog-core/src';
-export interface IdentifyMessageV1 {
+export interface IdentifyMessage {
     distinctId: string;
     properties?: Record<string | number, any>;
     disableGeoip?: boolean;
 }
-export interface EventMessageV1 extends IdentifyMessageV1 {
+export interface EventMessage extends IdentifyMessage {
     event: string;
     groups?: Record<string, string | number>;
     sendFeatureFlags?: boolean;
     timestamp?: Date;
+    uuid?: string;
 }
 export interface GroupIdentifyMessage {
     groupType: string;
@@ -67,7 +68,7 @@ export declare type PostHogNodeV1 = {
      * @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.
      */
-    capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessageV1): void;
+    capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): 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.
@@ -75,7 +76,7 @@ export declare type PostHogNodeV1 = {
      * @param distinctId which uniquely identifies your user
      * @param properties with a dict with any key: value pairs
      */
-    identify({ distinctId, properties }: IdentifyMessageV1): void;
+    identify({ distinctId, properties }: IdentifyMessage): 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?"

package/package.json

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

package/src/feature-flags.ts

@@ -121,7 +121,7 @@ class FeatureFlagsPoller {
             console.debug(`InconclusiveMatchError when computing flag locally: ${key}: ${e}`)
           }
         } else if (e instanceof Error) {
-          console.error(`Error computing flag locally: ${key}: ${e}`)
+          this.onError?.(new Error(`Error computing flag locally: ${key}: ${e}`))
         }
       }
     }
@@ -211,14 +211,18 @@ class FeatureFlagsPoller {
       const groupName = this.groupTypeMapping[String(aggregation_group_type_index)]
 
       if (!groupName) {
-        console.warn(
-          `[FEATURE FLAGS] Unknown group type index ${aggregation_group_type_index} for feature flag ${flag.key}`
-        )
+        if (this.debugMode) {
+          console.warn(
+            `[FEATURE FLAGS] Unknown group type index ${aggregation_group_type_index} for feature flag ${flag.key}`
+          )
+        }
         throw new InconclusiveMatchError('Flag has unknown group type index')
       }
 
       if (!(groupName in groups)) {
-        console.warn(`[FEATURE FLAGS] Can't compute group feature flag: ${flag.key} without group names passed in`)
+        if (this.debugMode) {
+          console.warn(`[FEATURE FLAGS] Can't compute group feature flag: ${flag.key} without group names passed in`)
+        }
         return false
       }
 
@@ -383,7 +387,7 @@ class FeatureFlagsPoller {
 
       const responseJson = await res.json()
       if (!('flags' in responseJson)) {
-        console.error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`)
+        this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`))
       }
 
       this.featureFlags = responseJson.flags || []

package/src/posthog-node.ts

@@ -10,7 +10,7 @@ import {
   PostHogPersistedProperty,
 } from '../../posthog-core/src'
 import { PostHogMemoryStorage } from '../../posthog-core/src/storage-memory'
-import { EventMessageV1, GroupIdentifyMessage, IdentifyMessageV1, PostHogNodeV1 } from './types'
+import { EventMessage, GroupIdentifyMessage, IdentifyMessage, PostHogNodeV1 } from './types'
 import { FeatureFlagsPoller } from './feature-flags'
 import fetch from './fetch'
 
@@ -100,34 +100,71 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     this.featureFlagsPoller?.debug(enabled)
   }
 
-  capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip }: EventMessageV1): void {
-    const _capture = (props: EventMessageV1['properties']): void => {
-      super.captureStateless(distinctId, event, props, { timestamp, disableGeoip })
+  capture({
+    distinctId,
+    event,
+    properties,
+    groups,
+    sendFeatureFlags,
+    timestamp,
+    disableGeoip,
+    uuid,
+  }: EventMessage): void {
+    const _capture = (props: EventMessage['properties']): void => {
+      super.captureStateless(distinctId, event, props, { timestamp, disableGeoip, uuid })
     }
 
-    if (sendFeatureFlags) {
-      super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip).then((flags) => {
-        const featureVariantProperties: Record<string, string | boolean> = {}
+    // :TRICKY: If we flush, or need to shut down, to not lose events we want this promise to resolve before we flush
+    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)
+        }
+
+        if ((this.featureFlagsPoller?.featureFlags?.length || 0) > 0) {
+          // Otherwise we may as well check for the flags locally and include them if there
+          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)) {
-            if (variant !== false) {
-              featureVariantProperties[`$feature/${feature}`] = variant
-            }
+            additionalProperties[`$feature/${feature}`] = variant
           }
         }
         const activeFlags = Object.keys(flags || {}).filter((flag) => flags?.[flag] !== false)
-        const flagProperties = {
-          $active_feature_flags: activeFlags || undefined,
-          ...featureVariantProperties,
+        if (activeFlags.length > 0) {
+          additionalProperties['$active_feature_flags'] = activeFlags
         }
-        _capture({ ...properties, $groups: groups, ...flagProperties })
+
+        return additionalProperties
       })
-    } else {
-      _capture({ ...properties, $groups: groups })
-    }
+      .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 })
+      })
+
+    this.addPendingPromise(capturePromise)
   }
 
-  identify({ distinctId, properties, disableGeoip }: IdentifyMessageV1): void {
+  identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void {
     // Catch properties passed as $set and move them to the top level
     const personProperties = properties?.$set || properties
 
@@ -156,8 +193,18 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       disableGeoip?: boolean
     }
   ): Promise<string | boolean | undefined> {
-    const { groups, personProperties, groupProperties, disableGeoip } = options || {}
-    let { onlyEvaluateLocally, sendFeatureFlagEvents } = options || {}
+    const { groups, disableGeoip } = options || {}
+    let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {}
+
+    const adjustedProperties = this.addLocalPersonAndGroupProperties(
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+
+    personProperties = adjustedProperties.allPersonProperties
+    groupProperties = adjustedProperties.allGroupProperties
 
     // set defaults
     if (onlyEvaluateLocally == undefined) {
@@ -232,8 +279,19 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       disableGeoip?: boolean
     }
   ): Promise<JsonType | undefined> {
-    const { groups, personProperties, groupProperties, disableGeoip } = options || {}
-    let { onlyEvaluateLocally, sendFeatureFlagEvents } = options || {}
+    const { groups, disableGeoip } = options || {}
+    let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {}
+
+    const adjustedProperties = this.addLocalPersonAndGroupProperties(
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+
+    personProperties = adjustedProperties.allPersonProperties
+    groupProperties = adjustedProperties.allGroupProperties
+
     let response = undefined
 
     // Try to get match value locally if not provided
@@ -324,8 +382,18 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       disableGeoip?: boolean
     }
   ): Promise<PosthogFlagsAndPayloadsResponse> {
-    const { groups, personProperties, groupProperties, disableGeoip } = options || {}
-    let { onlyEvaluateLocally } = options || {}
+    const { groups, disableGeoip } = options || {}
+    let { onlyEvaluateLocally, personProperties, groupProperties } = options || {}
+
+    const adjustedProperties = this.addLocalPersonAndGroupProperties(
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+
+    personProperties = adjustedProperties.allPersonProperties
+    groupProperties = adjustedProperties.allGroupProperties
 
     // set defaults
     if (onlyEvaluateLocally == undefined) {
@@ -385,4 +453,25 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     this.featureFlagsPoller?.stopPoller()
     return super.shutdownAsync()
   }
+
+  private addLocalPersonAndGroupProperties(
+    distinctId: string,
+    groups?: Record<string, string>,
+    personProperties?: Record<string, string>,
+    groupProperties?: Record<string, Record<string, string>>
+  ): { allPersonProperties: Record<string, string>; allGroupProperties: Record<string, Record<string, string>> } {
+    const allPersonProperties = { $current_distinct_id: distinctId, ...(personProperties || {}) }
+
+    const allGroupProperties: Record<string, Record<string, string>> = {}
+    if (groups) {
+      for (const groupName of Object.keys(groups)) {
+        allGroupProperties[groupName] = {
+          $group_key: groups[groupName],
+          ...(groupProperties?.[groupName] || {}),
+        }
+      }
+    }
+
+    return { allPersonProperties, allGroupProperties }
+  }
 }

package/src/types.ts

@@ -1,16 +1,17 @@
 import { JsonType } from '../../posthog-core/src'
 
-export interface IdentifyMessageV1 {
+export interface IdentifyMessage {
   distinctId: string
   properties?: Record<string | number, any>
   disableGeoip?: boolean
 }
 
-export interface EventMessageV1 extends IdentifyMessageV1 {
+export interface EventMessage extends IdentifyMessage {
   event: string
   groups?: Record<string, string | number> // Mapping of group type to group id
   sendFeatureFlags?: boolean
   timestamp?: Date
+  uuid?: string
 }
 
 export interface GroupIdentifyMessage {
@@ -75,7 +76,7 @@ export type PostHogNodeV1 = {
    * @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.
    */
-  capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessageV1): void
+  capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): void
 
   /**
    * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog,
@@ -84,7 +85,7 @@ export type PostHogNodeV1 = {
    * @param distinctId which uniquely identifies your user
    * @param properties with a dict with any key: value pairs
    */
-  identify({ distinctId, properties }: IdentifyMessageV1): void
+  identify({ distinctId, properties }: IdentifyMessage): 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.

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

@@ -3,6 +3,7 @@ import { PostHog as PostHog } from '../../src/posthog-node'
 import { PostHogSentryIntegration } from '../../src/extensions/sentry-integration'
 jest.mock('../../src/fetch')
 import fetch from '../../src/fetch'
+import { waitForPromises } from 'posthog-core/test/test-utils/test-utils'
 
 jest.mock('../../package.json', () => ({ version: '1.2.3' }))
 
@@ -108,6 +109,7 @@ describe('PostHogSentryIntegration', () => {
 
     processorFunction(createMockSentryException())
 
+    await waitForPromises()
     jest.runOnlyPendingTimers()
     const batchEvents = getLastBatchEvents()
 
@@ -144,6 +146,7 @@ describe('PostHogSentryIntegration', () => {
         library: 'posthog-node',
         library_version: '1.2.3',
         timestamp: expect.any(String),
+        uuid: expect.any(String),
       },
     ])
   })

package/test/feature-flags.spec.ts

@@ -50,6 +50,17 @@ export const apiImplementation = ({
       }) as any
     }
 
+    if ((url as any).includes('batch/')) {
+      return Promise.resolve({
+        status: 200,
+        text: () => Promise.resolve('ok'),
+        json: () =>
+          Promise.resolve({
+            status: 'ok',
+          }),
+      }) as any
+    }
+
     return Promise.resolve({
       status: 400,
       text: () => Promise.resolve('ok'),
@@ -342,7 +353,11 @@ describe('local evaluation', () => {
           token: 'TEST_API_KEY',
           distinct_id: 'some-distinct-id_outside_rollout?',
           groups: {},
-          person_properties: { region: 'USA', email: 'a@b.com' },
+          person_properties: {
+            $current_distinct_id: 'some-distinct-id_outside_rollout?',
+            region: 'USA',
+            email: 'a@b.com',
+          },
           group_properties: {},
           geoip_disable: true,
         }),
@@ -361,7 +376,7 @@ describe('local evaluation', () => {
           token: 'TEST_API_KEY',
           distinct_id: 'some-distinct-id',
           groups: {},
-          person_properties: { doesnt_matter: '1' },
+          person_properties: { $current_distinct_id: 'some-distinct-id', doesnt_matter: '1' },
           group_properties: {},
           geoip_disable: true,
         }),