posthog-node 2.5.4 → 3.0.0

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

@@ -13,6 +13,7 @@ export declare abstract class PostHogCoreStateless {
     private removeDebugCallback?;
     private debugMode;
     private pendingPromises;
+    private disableGeoip;
     private _optoutOverride;
     protected _events: SimpleEventEmitter;
     protected _flushTimer?: any;
@@ -40,7 +41,7 @@ export declare abstract class PostHogCoreStateless {
     }, options?: PosthogCaptureOptions): this;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
-    }): this;
+    }, options?: PosthogCaptureOptions): this;
     /***
      *** GROUPS
      ***/
@@ -49,12 +50,12 @@ export declare abstract class PostHogCoreStateless {
      *** FEATURE FLAGS
      ***/
     protected getDecide(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, extraPayload?: Record<string, any>): Promise<PostHogDecideResponse | undefined>;
-    protected getFeatureFlagStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<boolean | string | undefined>;
-    protected getFeatureFlagPayloadStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<JsonType | undefined>;
-    protected getFeatureFlagPayloadsStateless(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<PostHogDecideResponse['featureFlagPayloads'] | undefined>;
+    protected getFeatureFlagStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<boolean | string | undefined>;
+    protected getFeatureFlagPayloadStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<JsonType | undefined>;
+    protected getFeatureFlagPayloadsStateless(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<PostHogDecideResponse['featureFlagPayloads'] | undefined>;
     protected _parsePayload(response: any): any;
-    protected getFeatureFlagsStateless(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<PostHogDecideResponse['featureFlags'] | undefined>;
-    protected getFeatureFlagsAndPayloadsStateless(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<{
+    protected getFeatureFlagsStateless(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<PostHogDecideResponse['featureFlags'] | undefined>;
+    protected getFeatureFlagsAndPayloadsStateless(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<{
         flags: PostHogDecideResponse['featureFlags'] | undefined;
         payloads: PostHogDecideResponse['featureFlagPayloads'] | undefined;
     }>;

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

@@ -17,6 +17,7 @@ export declare type PosthogCoreOptions = {
     requestTimeout?: number;
     sessionExpirationTimeSeconds?: number;
     captureMode?: 'json' | 'form';
+    disableGeoip?: boolean;
 };
 export declare enum PostHogPersistedProperty {
     AnonymousId = "anonymous_id",
@@ -44,6 +45,7 @@ export declare type PostHogFetchOptions = {
 };
 export declare type PosthogCaptureOptions = {
     timestamp?: Date;
+    disableGeoip?: boolean;
 };
 export declare type PostHogFetchResponse = {
     status: number;

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

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { FeatureFlagCondition, PostHogFeatureFlag } from './types';
+import { FeatureFlagCondition, PostHogFeatureFlag, PropertyGroup } from './types';
 import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src';
 declare class ClientError extends Error {
     constructor(message: string);
@@ -22,6 +22,7 @@ declare class FeatureFlagsPoller {
     featureFlags: Array<PostHogFeatureFlag>;
     featureFlagsByKey: Record<string, PostHogFeatureFlag>;
     groupTypeMapping: Record<string, string>;
+    cohorts: Record<string, PropertyGroup>;
     loadedSuccessfullyOnce: boolean;
     timeout?: number;
     host: FeatureFlagsPollerOptions['host'];

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

@@ -24,11 +24,12 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     enable(): void;
     disable(): void;
     debug(enabled?: boolean): void;
-    capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp }: EventMessageV1): void;
-    identify({ distinctId, properties }: IdentifyMessageV1): void;
+    capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip }: EventMessageV1): void;
+    identify({ distinctId, properties, disableGeoip }: IdentifyMessageV1): void;
     alias(data: {
         distinctId: string;
         alias: string;
+        disableGeoip?: boolean;
     }): void;
     getFeatureFlag(key: string, distinctId: string, options?: {
         groups?: Record<string, string>;
@@ -36,6 +37,7 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
+        disableGeoip?: boolean;
     }): Promise<string | boolean | undefined>;
     getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
         groups?: Record<string, string>;
@@ -43,6 +45,7 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
+        disableGeoip?: boolean;
     }): Promise<JsonType | undefined>;
     isFeatureEnabled(key: string, distinctId: string, options?: {
         groups?: Record<string, string>;
@@ -50,20 +53,23 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
+        disableGeoip?: boolean;
     }): Promise<boolean | undefined>;
     getAllFlags(distinctId: string, options?: {
         groups?: Record<string, string>;
         personProperties?: Record<string, string>;
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
+        disableGeoip?: boolean;
     }): Promise<Record<string, string | boolean>>;
     getAllFlagsAndPayloads(distinctId: string, options?: {
         groups?: Record<string, string>;
         personProperties?: Record<string, string>;
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
+        disableGeoip?: boolean;
     }): Promise<PosthogFlagsAndPayloadsResponse>;
-    groupIdentify({ groupType, groupKey, properties, distinctId }: GroupIdentifyMessage): void;
+    groupIdentify({ groupType, groupKey, properties, distinctId, disableGeoip }: GroupIdentifyMessage): void;
     reloadFeatureFlags(): Promise<void>;
     shutdown(): void;
     shutdownAsync(): Promise<void>;

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

@@ -2,6 +2,7 @@ import { JsonType } from '../../posthog-core/src';
 export interface IdentifyMessageV1 {
     distinctId: string;
     properties?: Record<string | number, any>;
+    disableGeoip?: boolean;
 }
 export interface EventMessageV1 extends IdentifyMessageV1 {
     event: string;
@@ -14,14 +15,21 @@ export interface GroupIdentifyMessage {
     groupKey: string;
     properties?: Record<string | number, any>;
     distinctId?: string;
+    disableGeoip?: boolean;
 }
+export declare type PropertyGroup = {
+    type: 'AND' | 'OR';
+    values: PropertyGroup[] | FlagProperty[];
+};
+export declare type FlagProperty = {
+    key: string;
+    type?: string;
+    value: string | number | (string | number)[];
+    operator?: string;
+    negation?: boolean;
+};
 export declare type FeatureFlagCondition = {
-    properties: {
-        key: string;
-        type?: string;
-        value: string | number | (string | number)[];
-        operator?: string;
-    }[];
+    properties: FlagProperty[];
     rollout_percentage?: number;
     variant?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "2.5.4",
+  "version": "3.0.0",
   "description": "PostHog Node.js integration",
   "repository": "PostHog/posthog-node",
   "scripts": {

package/src/feature-flags.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto'
-import { FeatureFlagCondition, PostHogFeatureFlag } from './types'
+import { FeatureFlagCondition, FlagProperty, PostHogFeatureFlag, PropertyGroup } from './types'
 import { version } from '../package.json'
 import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src'
 import { safeSetTimeout } from 'posthog-core/src/utils'
@@ -46,6 +46,7 @@ class FeatureFlagsPoller {
   featureFlags: Array<PostHogFeatureFlag>
   featureFlagsByKey: Record<string, PostHogFeatureFlag>
   groupTypeMapping: Record<string, string>
+  cohorts: Record<string, PropertyGroup>
   loadedSuccessfullyOnce: boolean
   timeout?: number
   host: FeatureFlagsPollerOptions['host']
@@ -66,6 +67,7 @@ class FeatureFlagsPoller {
     this.featureFlags = []
     this.featureFlagsByKey = {}
     this.groupTypeMapping = {}
+    this.cohorts = {}
     this.loadedSuccessfullyOnce = false
     this.timeout = timeout
     this.projectApiKey = projectApiKey
@@ -291,13 +293,22 @@ class FeatureFlagsPoller {
     const rolloutPercentage = condition.rollout_percentage
 
     if ((condition.properties || []).length > 0) {
-      const matchAll = condition.properties.every((property) => {
-        return matchProperty(property, properties)
-      })
-      if (!matchAll) {
-        return false
-      } else if (rolloutPercentage == undefined) {
-        // == to include `null` as a match, not just `undefined`
+      for (const prop of condition.properties) {
+        const propertyType = prop.type
+        let matches = false
+
+        if (propertyType === 'cohort') {
+          matches = matchCohort(prop, properties, this.cohorts)
+        } else {
+          matches = matchProperty(prop, properties)
+        }
+
+        if (!matches) {
+          return false
+        }
+      }
+
+      if (rolloutPercentage == undefined) {
         return true
       }
     }
@@ -378,6 +389,7 @@ class FeatureFlagsPoller {
         <Record<string, PostHogFeatureFlag>>{}
       )
       this.groupTypeMapping = responseJson.group_type_mapping || {}
+      this.cohorts = responseJson.cohorts || []
       this.loadedSuccessfullyOnce = true
     } catch (err) {
       // if an error that is not an instance of ClientError is thrown
@@ -389,7 +401,7 @@ class FeatureFlagsPoller {
   }
 
   async _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse> {
-    const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}`
+    const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}&send_cohorts`
 
     const options: PostHogFetchOptions = {
       method: 'GET',
@@ -487,6 +499,117 @@ function matchProperty(
   }
 }
 
+function matchCohort(
+  property: FeatureFlagCondition['properties'][number],
+  propertyValues: Record<string, any>,
+  cohortProperties: FeatureFlagsPoller['cohorts']
+): boolean {
+  const cohortId = String(property.value)
+  if (!(cohortId in cohortProperties)) {
+    throw new InconclusiveMatchError("can't match cohort without a given cohort property value")
+  }
+
+  const propertyGroup = cohortProperties[cohortId]
+  return matchPropertyGroup(propertyGroup, propertyValues, cohortProperties)
+}
+
+function matchPropertyGroup(
+  propertyGroup: PropertyGroup,
+  propertyValues: Record<string, any>,
+  cohortProperties: FeatureFlagsPoller['cohorts']
+): boolean {
+  if (!propertyGroup) {
+    return true
+  }
+
+  const propertyGroupType = propertyGroup.type
+  const properties = propertyGroup.values
+
+  if (!properties || properties.length === 0) {
+    // empty groups are no-ops, always match
+    return true
+  }
+
+  let errorMatchingLocally = false
+
+  if ('values' in properties[0]) {
+    // a nested property group
+    for (const prop of properties as PropertyGroup[]) {
+      try {
+        const matches = matchPropertyGroup(prop, propertyValues, cohortProperties)
+        if (propertyGroupType === 'AND') {
+          if (!matches) {
+            return false
+          }
+        } else {
+          // OR group
+          if (matches) {
+            return true
+          }
+        }
+      } catch (err) {
+        if (err instanceof InconclusiveMatchError) {
+          console.debug(`Failed to compute property ${prop} locally: ${err}`)
+          errorMatchingLocally = true
+        } else {
+          throw err
+        }
+      }
+    }
+
+    if (errorMatchingLocally) {
+      throw new InconclusiveMatchError("Can't match cohort without a given cohort property value")
+    }
+    // if we get here, all matched in AND case, or none matched in OR case
+    return propertyGroupType === 'AND'
+  } else {
+    for (const prop of properties as FlagProperty[]) {
+      try {
+        let matches: boolean
+        if (prop.type === 'cohort') {
+          matches = matchCohort(prop, propertyValues, cohortProperties)
+        } else {
+          matches = matchProperty(prop, propertyValues)
+        }
+
+        const negation = prop.negation || false
+
+        if (propertyGroupType === 'AND') {
+          // if negated property, do the inverse
+          if (!matches && !negation) {
+            return false
+          }
+          if (matches && negation) {
+            return false
+          }
+        } else {
+          // OR group
+          if (matches && !negation) {
+            return true
+          }
+          if (!matches && negation) {
+            return true
+          }
+        }
+      } catch (err) {
+        if (err instanceof InconclusiveMatchError) {
+          console.debug(`Failed to compute property ${prop} locally: ${err}`)
+          errorMatchingLocally = true
+        } else {
+          throw err
+        }
+      }
+    }
+
+    if (errorMatchingLocally) {
+      throw new InconclusiveMatchError("can't match cohort without a given cohort property value")
+    }
+
+    // if we get here, all matched in AND case, or none matched in OR case
+    return propertyGroupType === 'AND'
+  }
+}
+
 function isValidRegex(regex: string): boolean {
   try {
     new RegExp(regex)

package/src/posthog-node.ts

@@ -97,13 +97,13 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     this.featureFlagsPoller?.debug(enabled)
   }
 
-  capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp }: EventMessageV1): void {
+  capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip }: EventMessageV1): void {
     const _capture = (props: EventMessageV1['properties']): void => {
-      super.captureStateless(distinctId, event, props, { timestamp })
+      super.captureStateless(distinctId, event, props, { timestamp, disableGeoip })
     }
 
     if (sendFeatureFlags) {
-      super.getFeatureFlagsStateless(distinctId, groups).then((flags) => {
+      super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip).then((flags) => {
         const featureVariantProperties: Record<string, string | boolean> = {}
         if (flags) {
           for (const [feature, variant] of Object.entries(flags)) {
@@ -124,17 +124,21 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     }
   }
 
-  identify({ distinctId, properties }: IdentifyMessageV1): void {
+  identify({ distinctId, properties, disableGeoip }: IdentifyMessageV1): void {
     // Catch properties passed as $set and move them to the top level
     const personProperties = properties?.$set || properties
 
-    super.identifyStateless(distinctId, {
-      $set: personProperties,
-    })
+    super.identifyStateless(
+      distinctId,
+      {
+        $set: personProperties,
+      },
+      { disableGeoip }
+    )
   }
 
-  alias(data: { distinctId: string; alias: string }): void {
-    super.aliasStateless(data.alias, data.distinctId)
+  alias(data: { distinctId: string; alias: string; disableGeoip?: boolean }): void {
+    super.aliasStateless(data.alias, data.distinctId, undefined, { disableGeoip: data.disableGeoip })
   }
 
   async getFeatureFlag(
@@ -146,9 +150,10 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       groupProperties?: Record<string, Record<string, string>>
       onlyEvaluateLocally?: boolean
       sendFeatureFlagEvents?: boolean
+      disableGeoip?: boolean
     }
   ): Promise<string | boolean | undefined> {
-    const { groups, personProperties, groupProperties } = options || {}
+    const { groups, personProperties, groupProperties, disableGeoip } = options || {}
     let { onlyEvaluateLocally, sendFeatureFlagEvents } = options || {}
 
     // set defaults
@@ -170,7 +175,14 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     const flagWasLocallyEvaluated = response !== undefined
 
     if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
-      response = await super.getFeatureFlagStateless(key, distinctId, groups, personProperties, groupProperties)
+      response = await super.getFeatureFlagStateless(
+        key,
+        distinctId,
+        groups,
+        personProperties,
+        groupProperties,
+        disableGeoip
+      )
     }
 
     const featureFlagReportedKey = `${key}_${response}`
@@ -197,6 +209,7 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
           locally_evaluated: flagWasLocallyEvaluated,
         },
         groups,
+        disableGeoip,
       })
     }
     return response
@@ -212,9 +225,10 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       groupProperties?: Record<string, Record<string, string>>
       onlyEvaluateLocally?: boolean
       sendFeatureFlagEvents?: boolean
+      disableGeoip?: boolean
     }
   ): Promise<JsonType | undefined> {
-    const { groups, personProperties, groupProperties } = options || {}
+    const { groups, personProperties, groupProperties, disableGeoip } = options || {}
     let { onlyEvaluateLocally, sendFeatureFlagEvents } = options || {}
     let response = undefined
 
@@ -246,7 +260,14 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     const payloadWasLocallyEvaluated = response !== undefined
 
     if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) {
-      response = await super.getFeatureFlagPayloadStateless(key, distinctId, groups, personProperties, groupProperties)
+      response = await super.getFeatureFlagPayloadStateless(
+        key,
+        distinctId,
+        groups,
+        personProperties,
+        groupProperties,
+        disableGeoip
+      )
     }
 
     try {
@@ -265,6 +286,7 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       groupProperties?: Record<string, Record<string, string>>
       onlyEvaluateLocally?: boolean
       sendFeatureFlagEvents?: boolean
+      disableGeoip?: boolean
     }
   ): Promise<boolean | undefined> {
     const feat = await this.getFeatureFlag(key, distinctId, options)
@@ -281,6 +303,7 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       personProperties?: Record<string, string>
       groupProperties?: Record<string, Record<string, string>>
       onlyEvaluateLocally?: boolean
+      disableGeoip?: boolean
     }
   ): Promise<Record<string, string | boolean>> {
     const response = await this.getAllFlagsAndPayloads(distinctId, options)
@@ -294,9 +317,10 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       personProperties?: Record<string, string>
       groupProperties?: Record<string, Record<string, string>>
       onlyEvaluateLocally?: boolean
+      disableGeoip?: boolean
     }
   ): Promise<PosthogFlagsAndPayloadsResponse> {
-    const { groups, personProperties, groupProperties } = options || {}
+    const { groups, personProperties, groupProperties, disableGeoip } = options || {}
     let { onlyEvaluateLocally } = options || {}
 
     // set defaults
@@ -325,7 +349,8 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
         distinctId,
         groups,
         personProperties,
-        groupProperties
+        groupProperties,
+        disableGeoip
       )
       featureFlags = {
         ...featureFlags,
@@ -340,8 +365,8 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     return { featureFlags, featureFlagPayloads }
   }
 
-  groupIdentify({ groupType, groupKey, properties, distinctId }: GroupIdentifyMessage): void {
-    super.groupIdentifyStateless(groupType, groupKey, properties, undefined, distinctId)
+  groupIdentify({ groupType, groupKey, properties, distinctId, disableGeoip }: GroupIdentifyMessage): void {
+    super.groupIdentifyStateless(groupType, groupKey, properties, { disableGeoip }, distinctId)
   }
 
   async reloadFeatureFlags(): Promise<void> {

package/src/types.ts

@@ -3,6 +3,7 @@ import { JsonType } from '../../posthog-core/src'
 export interface IdentifyMessageV1 {
   distinctId: string
   properties?: Record<string | number, any>
+  disableGeoip?: boolean
 }
 
 export interface EventMessageV1 extends IdentifyMessageV1 {
@@ -17,15 +18,24 @@ export interface GroupIdentifyMessage {
   groupKey: string // Unique identifier for the group
   properties?: Record<string | number, any>
   distinctId?: string // optional distinctId to associate message with a person
+  disableGeoip?: boolean
+}
+
+export type PropertyGroup = {
+  type: 'AND' | 'OR'
+  values: PropertyGroup[] | FlagProperty[]
+}
+
+export type FlagProperty = {
+  key: string
+  type?: string
+  value: string | number | (string | number)[]
+  operator?: string
+  negation?: boolean
 }
 
 export type FeatureFlagCondition = {
-  properties: {
-    key: string
-    type?: string
-    value: string | number | (string | number)[]
-    operator?: string
-  }[]
+  properties: FlagProperty[]
   rollout_percentage?: number
   variant?: string
 }