posthog-node 2.1.0 → 2.2.0

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

@@ -26,6 +26,7 @@ export declare abstract class PostHogCore {
     private _optoutOverride;
     constructor(apiKey: string, options?: PosthogCoreOptions);
     protected getCommonEventProperties(): any;
+    protected setupBootstrap(options?: Partial<PosthogCoreOptions>): void;
     private get props();
     private set props(value);
     private clearProps;
@@ -76,6 +77,7 @@ export declare abstract class PostHogCore {
      ***/
     private decideAsync;
     private _decideAsync;
+    private setKnownFeatureFlags;
     getFeatureFlag(key: string): boolean | string | undefined;
     getFeatureFlags(): PostHogDecideResponse['featureFlags'] | undefined;
     isFeatureEnabled(key: string): boolean | undefined;

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

@@ -6,6 +6,11 @@ export declare type PosthogCoreOptions = {
     enable?: boolean;
     sendFeatureFlagEvent?: boolean;
     preloadFeatureFlags?: boolean;
+    bootstrap?: {
+        distinctId?: string;
+        isIdentifiedId?: boolean;
+        featureFlags?: Record<string, boolean | string>;
+    };
     fetchRetryCount?: number;
     fetchRetryDelay?: number;
     sessionExpirationTimeSeconds?: number;

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

@@ -20,6 +20,7 @@ export declare type FeatureFlagCondition = {
         operator?: string;
     }[];
     rollout_percentage?: number;
+    variant?: string;
 };
 export declare type PostHogFeatureFlag = {
     id: number;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "posthog-node",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "PostHog Node.js integration",
   "repository": "PostHog/posthog-node",
   "scripts": {
-    "prepublish": "cd .. && yarn build"
+    "prepublishOnly": "cd .. && yarn build"
   },
   "engines": {
     "node": ">=14.17.0"

package/src/feature-flags.ts

@@ -190,10 +190,34 @@ class FeatureFlagsPoller {
     let isInconclusive = false
     let result = undefined
 
-    flagConditions.forEach((condition) => {
+    // # Stable sort conditions with variant overrides to the top. This ensures that if overrides are present, they are
+    // # evaluated first, and the variant override is applied to the first matching condition.
+    const sortedFlagConditions = [...flagConditions].sort((conditionA, conditionB) => {
+      const AHasVariantOverride = !!conditionA.variant
+      const BHasVariantOverride = !!conditionB.variant
+
+      if (AHasVariantOverride && BHasVariantOverride) {
+        return 0
+      } else if (AHasVariantOverride) {
+        return -1
+      } else if (BHasVariantOverride) {
+        return 1
+      } else {
+        return 0
+      }
+    })
+
+    for (const condition of sortedFlagConditions) {
       try {
         if (this.isConditionMatch(flag, distinctId, condition, properties)) {
-          result = this.getMatchingVariant(flag, distinctId) || true
+          const variantOverride = condition.variant
+          const flagVariants = flagFilters.multivariate?.variants || []
+          if (variantOverride && flagVariants.some((variant) => variant.key === variantOverride)) {
+            result = variantOverride
+          } else {
+            result = this.getMatchingVariant(flag, distinctId) || true
+          }
+          break
         }
       } catch (e) {
         if (e instanceof InconclusiveMatchError) {
@@ -202,7 +226,7 @@ class FeatureFlagsPoller {
           throw e
         }
       }
-    })
+    }
 
     if (result !== undefined) {
       return result
@@ -394,6 +418,14 @@ function matchProperty(
       return typeof overrideValue == typeof value && overrideValue < value
     case 'lte':
       return typeof overrideValue == typeof value && overrideValue <= value
+    case 'is_date_after':
+    case 'is_date_before':
+      const parsedDate = convertToDateTime(value)
+      const overrideDate = convertToDateTime(overrideValue)
+      if (operator === 'is_date_before') {
+        return overrideDate < parsedDate
+      }
+      return overrideDate > parsedDate
     default:
       console.error(`Unknown operator: ${operator}`)
       return false
@@ -409,4 +441,18 @@ function isValidRegex(regex: string): boolean {
   }
 }
 
+function convertToDateTime(value: string | number | (string | number)[] | Date): Date {
+  if (value instanceof Date) {
+    return value
+  } else if (typeof value === 'string' || typeof value === 'number') {
+    const date = new Date(value)
+    if (!isNaN(date.valueOf())) {
+      return date
+    }
+    throw new InconclusiveMatchError(`${value} is in an invalid date format`)
+  } else {
+    throw new InconclusiveMatchError(`The date provided ${value} must be a string, number, or date object`)
+  }
+}
+
 export { FeatureFlagsPoller, matchProperty, InconclusiveMatchError, ClientError }

package/src/types.ts

@@ -23,6 +23,7 @@ export type FeatureFlagCondition = {
     operator?: string
   }[]
   rollout_percentage?: number
+  variant?: string
 }
 
 export type PostHogFeatureFlag = {

package/test/feature-flags.spec.ts

@@ -929,6 +929,299 @@ describe('local evaluation', () => {
     expect(await posthog.getAllFlags('distinct-id')).toEqual({ 'beta-feature': false, 'disabled-feature': true })
     expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
   })
+
+  it('gets feature flag with variant overrides', async () => {
+    const flags = {
+      flags: [
+        {
+          id: 1,
+          name: 'Beta Feature',
+          key: 'beta-feature',
+          is_simple_flag: true,
+          active: true,
+          filters: {
+            groups: [
+              {
+                properties: [
+                  {
+                    key: 'email',
+                    operator: 'exact',
+                    value: 'test@posthog.com',
+                    type: 'person',
+                  },
+                ],
+                rollout_percentage: 100,
+                variant: 'second-variant',
+              },
+              {
+                rollout_percentage: 50,
+                variant: 'first-variant',
+              },
+            ],
+            multivariate: {
+              variants: [
+                {
+                  key: 'first-variant',
+                  name: 'First Variant',
+                  rollout_percentage: 50,
+                },
+                {
+                  key: 'second-variant',
+                  name: 'Second Variant',
+                  rollout_percentage: 25,
+                },
+                {
+                  key: 'third-variant',
+                  name: 'Third Variant',
+                  rollout_percentage: 25,
+                },
+              ],
+            },
+          },
+        },
+      ],
+    }
+    mockedFetch.mockImplementation(apiImplementation({ localFlags: flags }))
+
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      personalApiKey: 'TEST_PERSONAL_API_KEY',
+    })
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'test_id', { personProperties: { email: 'test@posthog.com' } })
+    ).toEqual('second-variant')
+    expect(await posthog.getFeatureFlag('beta-feature', 'example_id')).toEqual('first-variant')
+
+    expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
+    // decide not called
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+  })
+
+  it('gets feature flag with clashing variant overrides', async () => {
+    const flags = {
+      flags: [
+        {
+          id: 1,
+          name: 'Beta Feature',
+          key: 'beta-feature',
+          is_simple_flag: true,
+          active: true,
+          filters: {
+            groups: [
+              {
+                properties: [
+                  {
+                    key: 'email',
+                    operator: 'exact',
+                    value: 'test@posthog.com',
+                    type: 'person',
+                  },
+                ],
+                rollout_percentage: 100,
+                variant: 'second-variant',
+              },
+              // # since second-variant comes first in the list, it will be the one that gets picked
+              {
+                properties: [
+                  {
+                    key: 'email',
+                    operator: 'exact',
+                    value: 'test@posthog.com',
+                    type: 'person',
+                  },
+                ],
+                rollout_percentage: 100,
+                variant: 'first-variant',
+              },
+              {
+                rollout_percentage: 50,
+                variant: 'first-variant',
+              },
+            ],
+            multivariate: {
+              variants: [
+                {
+                  key: 'first-variant',
+                  name: 'First Variant',
+                  rollout_percentage: 50,
+                },
+                {
+                  key: 'second-variant',
+                  name: 'Second Variant',
+                  rollout_percentage: 25,
+                },
+                {
+                  key: 'third-variant',
+                  name: 'Third Variant',
+                  rollout_percentage: 25,
+                },
+              ],
+            },
+          },
+        },
+      ],
+    }
+    mockedFetch.mockImplementation(apiImplementation({ localFlags: flags }))
+
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      personalApiKey: 'TEST_PERSONAL_API_KEY',
+    })
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'test_id', { personProperties: { email: 'test@posthog.com' } })
+    ).toEqual('second-variant')
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'example_id', { personProperties: { email: 'test@posthog.com' } })
+    ).toEqual('second-variant')
+    expect(await posthog.getFeatureFlag('beta-feature', 'example_id')).toEqual('first-variant')
+
+    expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
+    // decide not called
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+  })
+
+  it('gets feature flag with invalid variant overrides', async () => {
+    const flags = {
+      flags: [
+        {
+          id: 1,
+          name: 'Beta Feature',
+          key: 'beta-feature',
+          is_simple_flag: true,
+          active: true,
+          filters: {
+            groups: [
+              {
+                properties: [
+                  {
+                    key: 'email',
+                    operator: 'exact',
+                    value: 'test@posthog.com',
+                    type: 'person',
+                  },
+                ],
+                rollout_percentage: 100,
+                variant: 'second???',
+              },
+              {
+                rollout_percentage: 50,
+                variant: 'first???',
+              },
+            ],
+            multivariate: {
+              variants: [
+                {
+                  key: 'first-variant',
+                  name: 'First Variant',
+                  rollout_percentage: 50,
+                },
+                {
+                  key: 'second-variant',
+                  name: 'Second Variant',
+                  rollout_percentage: 25,
+                },
+                {
+                  key: 'third-variant',
+                  name: 'Third Variant',
+                  rollout_percentage: 25,
+                },
+              ],
+            },
+          },
+        },
+      ],
+    }
+    mockedFetch.mockImplementation(apiImplementation({ localFlags: flags }))
+
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      personalApiKey: 'TEST_PERSONAL_API_KEY',
+    })
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'test_id', { personProperties: { email: 'test@posthog.com' } })
+    ).toEqual('third-variant')
+    expect(await posthog.getFeatureFlag('beta-feature', 'example_id')).toEqual('second-variant')
+
+    expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
+    // decide not called
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+  })
+
+  it('gets feature flag with multiple variant overrides', async () => {
+    const flags = {
+      flags: [
+        {
+          id: 1,
+          name: 'Beta Feature',
+          key: 'beta-feature',
+          is_simple_flag: true,
+          active: true,
+          filters: {
+            groups: [
+              {
+                rollout_percentage: 100,
+                // # The override applies even if the first condition matches all and gives everyone their default group
+              },
+              {
+                properties: [
+                  {
+                    key: 'email',
+                    operator: 'exact',
+                    value: 'test@posthog.com',
+                    type: 'person',
+                  },
+                ],
+                rollout_percentage: 100,
+                variant: 'second-variant',
+              },
+              {
+                rollout_percentage: 50,
+                variant: 'third-variant',
+              },
+            ],
+            multivariate: {
+              variants: [
+                {
+                  key: 'first-variant',
+                  name: 'First Variant',
+                  rollout_percentage: 50,
+                },
+                {
+                  key: 'second-variant',
+                  name: 'Second Variant',
+                  rollout_percentage: 25,
+                },
+                {
+                  key: 'third-variant',
+                  name: 'Third Variant',
+                  rollout_percentage: 25,
+                },
+              ],
+            },
+          },
+        },
+      ],
+    }
+    mockedFetch.mockImplementation(apiImplementation({ localFlags: flags }))
+
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      personalApiKey: 'TEST_PERSONAL_API_KEY',
+    })
+
+    expect(
+      await posthog.getFeatureFlag('beta-feature', 'test_id', { personProperties: { email: 'test@posthog.com' } })
+    ).toEqual('second-variant')
+    expect(await posthog.getFeatureFlag('beta-feature', 'example_id')).toEqual('third-variant')
+    expect(await posthog.getFeatureFlag('beta-feature', 'another_id')).toEqual('second-variant')
+
+    expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
+    // decide not called
+    expect(mockedFetch).not.toHaveBeenCalledWith(...anyDecideCall)
+  })
 })
 
 describe('match properties', () => {
@@ -1098,6 +1391,42 @@ describe('match properties', () => {
     expect(matchProperty(property_d, { key: '44' })).toBe(false)
     expect(matchProperty(property_d, { key: 44 })).toBe(false)
   })
+
+  it('with date operators', () => {
+    // is date before
+    const property_a = { key: 'key', value: '2022-05-01', operator: 'is_date_before' }
+    expect(matchProperty(property_a, { key: '2022-03-01' })).toBe(true)
+    expect(matchProperty(property_a, { key: '2022-04-30' })).toBe(true)
+    expect(matchProperty(property_a, { key: new Date(2022, 3, 30) })).toBe(true)
+    expect(matchProperty(property_a, { key: new Date(2022, 3, 30, 1, 2, 3) })).toBe(true)
+    expect(matchProperty(property_a, { key: new Date('2022-04-30T00:00:00+02:00') })).toBe(true) // europe/madrid
+    expect(matchProperty(property_a, { key: new Date('2022-04-30') })).toBe(true)
+    expect(matchProperty(property_a, { key: '2022-05-30' })).toBe(false)
+
+    // is date after
+    const property_b = { key: 'key', value: '2022-05-01', operator: 'is_date_after' }
+    expect(matchProperty(property_b, { key: '2022-05-02' })).toBe(true)
+    expect(matchProperty(property_b, { key: '2022-05-30' })).toBe(true)
+    expect(matchProperty(property_b, { key: new Date(2022, 4, 30) })).toBe(true)
+    expect(matchProperty(property_b, { key: new Date('2022-05-30') })).toBe(true)
+    expect(matchProperty(property_b, { key: '2022-04-30' })).toBe(false)
+
+    // can't be an invalid number or invalid string
+    expect(() => matchProperty(property_a, { key: parseInt('62802180000012345') })).toThrow(InconclusiveMatchError)
+    expect(() => matchProperty(property_a, { key: 'abcdef' })).toThrow(InconclusiveMatchError)
+    // invalid flag property
+    const property_c = { key: 'key', value: 'abcd123', operator: 'is_date_before' }
+    expect(() => matchProperty(property_c, { key: '2022-05-30' })).toThrow(InconclusiveMatchError)
+
+    // Timezone
+    const property_d = { key: 'key', value: '2022-04-05 12:34:12 +01:00', operator: 'is_date_before' }
+    expect(matchProperty(property_d, { key: '2022-05-30' })).toBe(false)
+
+    expect(matchProperty(property_d, { key: '2022-03-30' })).toBe(true)
+    expect(matchProperty(property_d, { key: '2022-04-05 12:34:11+01:00' })).toBe(true)
+    expect(matchProperty(property_d, { key: '2022-04-05 11:34:11 +00:00' })).toBe(true)
+    expect(matchProperty(property_d, { key: '2022-04-05 11:34:13 +00:00' })).toBe(false)
+  })
 })
 
 describe('consistency tests', () => {