posthog-node 2.5.3 → 2.6.0

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

@@ -11,6 +11,7 @@ export declare abstract class PostHogCoreStateless {
     private requestTimeout;
     private captureMode;
     private removeDebugCallback?;
+    private debugMode;
     private pendingPromises;
     private _optoutOverride;
     protected _events: SimpleEventEmitter;

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,12 +22,15 @@ 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'];
     poller?: NodeJS.Timeout;
     fetch: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
+    debugMode: boolean;
     constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host, ...options }: FeatureFlagsPollerOptions);
+    debug(enabled?: boolean): void;
     getFeatureFlag(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<string | boolean | undefined>;
     computeFeatureFlagPayloadLocally(key: string, matchValue: string | boolean): Promise<JsonType | undefined>;
     getAllFlagsAndPayloads(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<{

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

@@ -23,6 +23,7 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     getCustomUserAgent(): string;
     enable(): void;
     disable(): void;
+    debug(enabled?: boolean): void;
     capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp }: EventMessageV1): void;
     identify({ distinctId, properties }: IdentifyMessageV1): void;
     alias(data: {

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

@@ -15,13 +15,19 @@ export interface GroupIdentifyMessage {
     properties?: Record<string | number, any>;
     distinctId?: string;
 }
+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.3",
+  "version": "2.6.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,11 +46,13 @@ class FeatureFlagsPoller {
   featureFlags: Array<PostHogFeatureFlag>
   featureFlagsByKey: Record<string, PostHogFeatureFlag>
   groupTypeMapping: Record<string, string>
+  cohorts: Record<string, PropertyGroup>
   loadedSuccessfullyOnce: boolean
   timeout?: number
   host: FeatureFlagsPollerOptions['host']
   poller?: NodeJS.Timeout
   fetch: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>
+  debugMode: boolean = false
 
   constructor({
     pollingInterval,
@@ -65,6 +67,7 @@ class FeatureFlagsPoller {
     this.featureFlags = []
     this.featureFlagsByKey = {}
     this.groupTypeMapping = {}
+    this.cohorts = {}
     this.loadedSuccessfullyOnce = false
     this.timeout = timeout
     this.projectApiKey = projectApiKey
@@ -76,6 +79,10 @@ class FeatureFlagsPoller {
     void this.loadFeatureFlags()
   }
 
+  debug(enabled: boolean = true): void {
+    this.debugMode = enabled
+  }
+
   async getFeatureFlag(
     key: string,
     distinctId: string,
@@ -102,9 +109,14 @@ class FeatureFlagsPoller {
     if (featureFlag !== undefined) {
       try {
         response = this.computeFlagLocally(featureFlag, distinctId, groups, personProperties, groupProperties)
+        if (this.debugMode) {
+          console.debug(`Successfully computed flag locally: ${key} -> ${response}`)
+        }
       } catch (e) {
         if (e instanceof InconclusiveMatchError) {
-          console.error(`InconclusiveMatchError when computing flag locally: ${key}: ${e}`)
+          if (this.debugMode) {
+            console.debug(`InconclusiveMatchError when computing flag locally: ${key}: ${e}`)
+          }
         } else if (e instanceof Error) {
           console.error(`Error computing flag locally: ${key}: ${e}`)
         }
@@ -281,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
       }
     }
@@ -368,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
@@ -379,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',
@@ -477,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

@@ -92,6 +92,11 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     return super.optOut()
   }
 
+  debug(enabled: boolean = true): void {
+    super.debug(enabled)
+    this.featureFlagsPoller?.debug(enabled)
+  }
+
   capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp }: EventMessageV1): void {
     const _capture = (props: EventMessageV1['properties']): void => {
       super.captureStateless(distinctId, event, props, { timestamp })

package/src/types.ts

@@ -19,13 +19,21 @@ export interface GroupIdentifyMessage {
   distinctId?: string // optional distinctId to associate message with a person
 }
 
+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
 }

package/test/feature-flags.spec.ts

@@ -38,7 +38,7 @@ export const apiImplementation = ({
       }) as any
     }
 
-    if ((url as any).includes('api/feature_flag/local_evaluation?token=TEST_API_KEY')) {
+    if ((url as any).includes('api/feature_flag/local_evaluation?token=TEST_API_KEY&send_cohorts')) {
       return Promise.resolve({
         status: 200,
         text: () => Promise.resolve('ok'),
@@ -58,7 +58,7 @@ export const apiImplementation = ({
 }
 
 export const anyLocalEvalCall = [
-  'http://example.com/api/feature_flag/local_evaluation?token=TEST_API_KEY',
+  'http://example.com/api/feature_flag/local_evaluation?token=TEST_API_KEY&send_cohorts',
   expect.any(Object),
 ]
 export const anyDecideCall = ['http://example.com/decide/?v=3', expect.any(Object)]
@@ -1179,6 +1179,177 @@ describe('local evaluation', () => {
     expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
   })
 
+  it('computes complex cohorts locally', async () => {
+    const flags = {
+      flags: [
+        {
+          id: 1,
+          name: 'Beta Feature',
+          key: 'beta-feature',
+          is_simple_flag: false,
+          active: true,
+          rollout_percentage: 100,
+          filters: {
+            groups: [
+              {
+                properties: [
+                  {
+                    key: 'region',
+                    operator: 'exact',
+                    value: ['USA'],
+                    type: 'person',
+                  },
+                  { key: 'id', value: 98, type: 'cohort' },
+                ],
+                rollout_percentage: 100,
+              },
+            ],
+          },
+        },
+      ],
+      cohorts: {
+        '98': {
+          type: 'OR',
+          values: [
+            { key: 'id', value: 1, type: 'cohort' },
+            {
+              key: 'nation',
+              operator: 'exact',
+              value: ['UK'],
+              type: 'person',
+            },
+          ],
+        },
+        '1': {
+          type: 'AND',
+          values: [{ key: 'other', operator: 'exact', value: ['thing'], type: 'person' }],
+        },
+      },
+    }
+    mockedFetch.mockImplementation(
+      apiImplementation({
+        localFlags: flags,
+        decideFlags: {},
+      })
+    )
+
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      personalApiKey: 'TEST_PERSONAL_API_KEY',
+    })
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', { personProperties: { region: 'UK' } })
+    ).toEqual(false)
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+
+    // # even though 'other' property is not present, the cohort should still match since it's an OR condition
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', {
+        personProperties: { region: 'USA', nation: 'UK' },
+      })
+    ).toEqual(true)
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+
+    // # even though 'other' property is not present, the cohort should still match since it's an OR condition
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', {
+        personProperties: { region: 'USA', other: 'thing' },
+      })
+    ).toEqual(true)
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+  })
+
+  it('computes complex cohorts with negation locally', async () => {
+    const flags = {
+      flags: [
+        {
+          id: 1,
+          name: 'Beta Feature',
+          key: 'beta-feature',
+          is_simple_flag: false,
+          active: true,
+          rollout_percentage: 100,
+          filters: {
+            groups: [
+              {
+                properties: [
+                  {
+                    key: 'region',
+                    operator: 'exact',
+                    value: ['USA'],
+                    type: 'person',
+                  },
+                  { key: 'id', value: 98, type: 'cohort' },
+                ],
+                rollout_percentage: 100,
+              },
+            ],
+          },
+        },
+      ],
+      cohorts: {
+        '98': {
+          type: 'OR',
+          values: [
+            { key: 'id', value: 1, type: 'cohort' },
+            {
+              key: 'nation',
+              operator: 'exact',
+              value: ['UK'],
+              type: 'person',
+            },
+          ],
+        },
+        '1': {
+          type: 'AND',
+          values: [{ key: 'other', operator: 'exact', value: ['thing'], type: 'person', negation: true }],
+        },
+      },
+    }
+    mockedFetch.mockImplementation(
+      apiImplementation({
+        localFlags: flags,
+        decideFlags: {},
+      })
+    )
+
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      personalApiKey: 'TEST_PERSONAL_API_KEY',
+    })
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', { personProperties: { region: 'UK' } })
+    ).toEqual(false)
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+
+    // # even though 'other' property is not present, the cohort should still match since it's an OR condition
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', {
+        personProperties: { region: 'USA', nation: 'UK' },
+      })
+    ).toEqual(true)
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+
+    // # since 'other' is negated, we return False. Since 'nation' is not present, we can't tell whether the flag should be true or false, so go to decide
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', {
+        personProperties: { region: 'USA', other: 'thing' },
+      })
+    ).toEqual(false)
+    expect(mockedFetch).toHaveBeenCalledWith(...anyDecideCall)
+
+    mockedFetch.mockClear()
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', {
+        personProperties: { region: 'USA', other: 'thing2' },
+      })
+    ).toEqual(true)
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+  })
+
   it('gets feature flag with variant overrides', async () => {
     const flags = {
       flags: [