feat(flags): add evaluation_environments to node and react-native SDKs (#2417)

Author: dmarticus

.changeset/evaluation-environments-core.md

@@ -0,0 +1,9 @@
+---
+'@posthog/core': minor
+---
+
+feat: Add evaluation environments support for feature flags
+
+This PR adds base support for evaluation environments in the core library, allowing SDKs that extend the core to specify which environment tags their SDK instance should use when evaluating feature flags.
+
+The core library now handles sending the `evaluation_environments` parameter to the feature flags API when configured.

.changeset/evaluation-environments-node.md

@@ -0,0 +1,18 @@
+---
+'posthog-node': minor
+---
+
+feat: Add evaluation environments support for feature flags
+
+This PR implements support for evaluation environments in the posthog-node SDK, allowing users to specify which environment tags their SDK instance should use when evaluating feature flags.
+
+Users can now configure the SDK with an `evaluationEnvironments` option:
+
+```typescript
+const client = new PostHog('api-key', {
+    host: 'https://app.posthog.com',
+    evaluationEnvironments: ['production', 'backend', 'api'],
+})
+```
+
+When set, only feature flags that have at least one matching evaluation tag will be evaluated for this SDK instance. Feature flags with no evaluation tags will always be evaluated.

.changeset/evaluation-environments-react-native.md

@@ -0,0 +1,18 @@
+---
+'posthog-react-native': minor
+---
+
+feat: Add evaluation environments support for feature flags
+
+This PR implements support for evaluation environments in the posthog-react-native SDK, allowing users to specify which environment tags their SDK instance should use when evaluating feature flags.
+
+Users can now configure the SDK with an `evaluationEnvironments` option:
+
+```typescript
+const posthog = new PostHog('api-key', {
+    host: 'https://app.posthog.com',
+    evaluationEnvironments: ['production', 'mobile', 'react-native'],
+})
+```
+
+When set, only feature flags that have at least one matching evaluation tag will be evaluated for this SDK instance. Feature flags with no evaluation tags will always be evaluated.

packages/core/src/posthog-core-stateless.ts

@@ -116,6 +116,7 @@ export abstract class PostHogCoreStateless {
   private removeDebugCallback?: () => void
   private disableGeoip: boolean
   private historicalMigration: boolean
+  private evaluationEnvironments?: readonly string[]
   protected disabled
   protected disableCompression: boolean
 
@@ -166,6 +167,7 @@ export abstract class PostHogCoreStateless {
     this.disableGeoip = options.disableGeoip ?? true
     this.disabled = options.disabled ?? false
     this.historicalMigration = options?.historicalMigration ?? false
+    this.evaluationEnvironments = options?.evaluationEnvironments
     // Init promise allows the derived class to block calls until it is ready
     this._initPromise = Promise.resolve()
     this._isInitialized = true
@@ -453,17 +455,24 @@ export abstract class PostHogCoreStateless {
     await this._initPromise
 
     const url = `${this.host}/flags/?v=2&config=true`
+    const requestData: Record<string, any> = {
+      token: this.apiKey,
+      distinct_id: distinctId,
+      groups,
+      person_properties: personProperties,
+      group_properties: groupProperties,
+      ...extraPayload,
+    }
+
+    // Add evaluation environments if configured
+    if (this.evaluationEnvironments && this.evaluationEnvironments.length > 0) {
+      requestData.evaluation_environments = this.evaluationEnvironments
+    }
+
     const fetchOptions: PostHogFetchOptions = {
       method: 'POST',
       headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        token: this.apiKey,
-        distinct_id: distinctId,
-        groups,
-        person_properties: personProperties,
-        group_properties: groupProperties,
-        ...extraPayload,
-      }),
+      body: JSON.stringify(requestData),
     }
 
     this._logger.info('Flags URL', url)

packages/core/src/types.ts

@@ -55,6 +55,17 @@ export type PostHogCoreOptions = {
   disableGeoip?: boolean
   /** Special flag to indicate ingested data is for a historical migration. */
   historicalMigration?: boolean
+  /**
+   * Evaluation environments for feature flags.
+   * When set, only feature flags that have at least one matching evaluation tag
+   * will be evaluated for this SDK instance. Feature flags with no evaluation tags
+   * will always be evaluated.
+   *
+   * Examples: ['production', 'web', 'mobile']
+   *
+   * @default undefined
+   */
+  evaluationEnvironments?: readonly string[]
 }
 
 export enum PostHogPersistedProperty {

packages/node/src/__tests__/posthog-node.spec.ts

@@ -1,11 +1,15 @@
-import { PostHog } from '@/entrypoints/index.node'
+import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
 import { anyFlagsCall, anyLocalEvalCall, apiImplementation, isPending, wait, waitForPromises } from './utils'
 import { randomUUID } from 'crypto'
 
 jest.mock('../version', () => ({ version: '1.2.3' }))
 
 const mockedFetch = jest.spyOn(globalThis, 'fetch').mockImplementation()
 
+const posthogImmediateResolveOptions: PostHogOptions = {
+  fetchRetryCount: 0,
+}
+
 const waitForFlushTimer = async (): Promise<void> => {
   await waitForPromises()
   // To trigger the flush via the timer
@@ -2469,6 +2473,92 @@ describe('PostHog Node.js', () => {
     })
   })
 
+  describe('evaluation environments', () => {
+    beforeEach(() => {
+      mockedFetch.mockClear()
+    })
+
+    it('should send evaluation environments when configured', async () => {
+      mockedFetch.mockImplementation(
+        apiImplementation({
+          decideFlags: { 'test-flag': true },
+          flagsPayloads: {},
+        })
+      )
+
+      const posthogWithEnvs = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        evaluationEnvironments: ['production', 'backend'],
+        ...posthogImmediateResolveOptions,
+      })
+
+      await posthogWithEnvs.getAllFlags('some-distinct-id')
+
+      expect(mockedFetch).toHaveBeenCalledWith(
+        'http://example.com/flags/?v=2&config=true',
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.stringContaining('"evaluation_environments":["production","backend"]'),
+        })
+      )
+
+      await posthogWithEnvs.shutdown()
+    })
+
+    it('should not send evaluation environments when not configured', async () => {
+      mockedFetch.mockImplementation(
+        apiImplementation({
+          decideFlags: { 'test-flag': true },
+          flagsPayloads: {},
+        })
+      )
+
+      const posthogWithoutEnvs = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        ...posthogImmediateResolveOptions,
+      })
+
+      await posthogWithoutEnvs.getAllFlags('some-distinct-id')
+
+      expect(mockedFetch).toHaveBeenCalledWith(
+        'http://example.com/flags/?v=2&config=true',
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.not.stringContaining('evaluation_environments'),
+        })
+      )
+
+      await posthogWithoutEnvs.shutdown()
+    })
+
+    it('should not send evaluation environments when configured as empty array', async () => {
+      mockedFetch.mockImplementation(
+        apiImplementation({
+          decideFlags: { 'test-flag': true },
+          flagsPayloads: {},
+        })
+      )
+
+      const posthogWithEmptyEnvs = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        evaluationEnvironments: [],
+        ...posthogImmediateResolveOptions,
+      })
+
+      await posthogWithEmptyEnvs.getAllFlags('some-distinct-id')
+
+      expect(mockedFetch).toHaveBeenCalledWith(
+        'http://example.com/flags/?v=2&config=true',
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.not.stringContaining('evaluation_environments'),
+        })
+      )
+
+      await posthogWithEmptyEnvs.shutdown()
+    })
+  })
+
   describe('getRemoteConfigPayload', () => {
     let requestRemoteConfigPayloadSpy: jest.SpyInstance
 

packages/node/src/types.ts

@@ -78,6 +78,17 @@ export type PostHogOptions = PostHogCoreOptions & {
    * If a function returns null, the event will be dropped.
    */
   before_send?: BeforeSendFn | BeforeSendFn[]
+  /**
+   * Evaluation environments for feature flags.
+   * When set, only feature flags that have at least one matching evaluation tag
+   * will be evaluated for this SDK instance. Feature flags with no evaluation tags
+   * will always be evaluated.
+   *
+   * Examples: ['production', 'backend', 'api']
+   *
+   * @default undefined
+   */
+  evaluationEnvironments?: readonly string[]
 }
 
 export type PostHogFeatureFlag = {

packages/react-native/test/posthog.spec.ts

@@ -7,6 +7,61 @@ Linking.getInitialURL = jest.fn(() => Promise.resolve(null))
 AppState.addEventListener = jest.fn()
 
 describe('PostHog React Native', () => {
+  describe('evaluation environments', () => {
+    it('should send evaluation environments when configured', async () => {
+      posthog = new PostHog('test-token', {
+        evaluationEnvironments: ['production', 'mobile'],
+        flushInterval: 0,
+      })
+      await posthog.ready()
+
+      await posthog.reloadFeatureFlagsAsync()
+
+      expect((globalThis as any).window.fetch).toHaveBeenCalledWith(
+        expect.stringContaining('/flags/?v=2&config=true'),
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.stringContaining('"evaluation_environments":["production","mobile"]'),
+        })
+      )
+    })
+
+    it('should not send evaluation environments when not configured', async () => {
+      posthog = new PostHog('test-token', {
+        flushInterval: 0,
+      })
+      await posthog.ready()
+
+      await posthog.reloadFeatureFlagsAsync()
+
+      expect((globalThis as any).window.fetch).toHaveBeenCalledWith(
+        expect.stringContaining('/flags/?v=2&config=true'),
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.not.stringContaining('evaluation_environments'),
+        })
+      )
+    })
+
+    it('should not send evaluation environments when configured as empty array', async () => {
+      posthog = new PostHog('test-token', {
+        evaluationEnvironments: [],
+        flushInterval: 0,
+      })
+      await posthog.ready()
+
+      await posthog.reloadFeatureFlagsAsync()
+
+      expect((globalThis as any).window.fetch).toHaveBeenCalledWith(
+        expect.stringContaining('/flags/?v=2&config=true'),
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.not.stringContaining('evaluation_environments'),
+        })
+      )
+    })
+  })
+
   let mockStorage: PostHogCustomStorage
   let cache: any = {}