feat(flags-core): add metrics environment option

.changeset/bright-flags-environments.md

@@ -0,0 +1,5 @@
+---
+'@vercel/flags-core': minor
+---
+
+Add an `environment` client option for associating evaluation metrics with an environment when sending them to the ingestion endpoint.

packages/vercel-flags-core/CLAUDE.md

@@ -89,10 +89,16 @@ type ControllerOptions = {
   stream?: boolean | { initTimeoutMs: number };      // default: true (3000ms)
   polling?: boolean | { intervalMs: number; initTimeoutMs: number };  // default: true (30s interval, 3s timeout)
   buildStep?: boolean;  // Override build step auto-detection
+  environment?: string; // Environment attached to ingested evaluation metrics
   sources?: { stream?: StreamSource; polling?: PollingSource; bundled?: BundledSource };  // DI for testing
 };
 ```
 
+When `environment` is provided, evaluation metrics sent to `/v1/ingest` include
+it as `X-Vercel-Environment`. The option does not affect datafile or stream
+requests, or the environment used for flag evaluation. When it is omitted, the
+header is not sent.
+
 ### Data Source Priority (Fallback Chain)
 
 Behavior differs based on environment:

packages/vercel-flags-core/README.md

@@ -24,6 +24,19 @@ const result = await client.evaluate<boolean>('show-new-feature', false, {
 });
 ```
 
+To associate evaluation metrics with an environment, pass the `environment`
+option:
+
+```ts
+const client = createClient(process.env.FLAGS!, {
+  environment: 'preview',
+});
+```
+
+This option is sent only to the metrics ingestion endpoint. It does not select
+the environment used for flag evaluation. When omitted, the environment header
+is not sent.
+
 ## OpenFeature
 
 An OpenFeature-compatible provider is available at `@vercel/flags-core/openfeature`:

packages/vercel-flags-core/src/black-box.test.ts

@@ -235,6 +235,57 @@ describe('Controller (black-box)', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // Environment option
+  // ---------------------------------------------------------------------------
+  describe('environment option', () => {
+    it('should include the environment with evaluation metrics', async () => {
+      const cleanupCtx = setRequestContext({ host: 'example.com' });
+      const client = createClient(sdkKey, {
+        datafile: makeBundled(),
+        environment: 'preview',
+        fetch: fetchMock,
+        stream: false,
+        polling: false,
+      });
+
+      await client.evaluate('flagA');
+      await client.shutdown();
+      cleanupCtx();
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(fetchMock).toHaveBeenLastCalledWith(
+        'https://flags.vercel.com/v1/ingest',
+        expect.objectContaining({
+          headers: {
+            ...ingestRequestHeaders,
+            'X-Vercel-Environment': 'preview',
+          },
+        }),
+      );
+    });
+
+    it('should omit the environment from evaluation metrics when unspecified', async () => {
+      const cleanupCtx = setRequestContext({ host: 'example.com' });
+      const client = createClient(sdkKey, {
+        datafile: makeBundled(),
+        fetch: fetchMock,
+        stream: false,
+        polling: false,
+      });
+
+      await client.evaluate('flagA');
+      await client.shutdown();
+      cleanupCtx();
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(fetchMock).toHaveBeenLastCalledWith(
+        'https://flags.vercel.com/v1/ingest',
+        expect.objectContaining({ headers: ingestRequestHeaders }),
+      );
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Build step detection
   // ---------------------------------------------------------------------------

packages/vercel-flags-core/src/controller/normalized-options.ts

@@ -53,6 +53,12 @@ export type ControllerOptions = {
    */
   fetch?: typeof globalThis.fetch;
 
+  /**
+   * Environment included with evaluation metrics sent to the ingest endpoint.
+   * When omitted, the environment header is not sent.
+   */
+  environment?: string;
+
   /**
    * Custom client name included in evaluation telemetry.
    */
@@ -73,6 +79,7 @@ export type NormalizedOptions = {
   buildStep: boolean;
   fetch: typeof globalThis.fetch;
   host: string;
+  environment: string | undefined;
   clientName: string | undefined;
   disableMetrics: boolean;
 };
@@ -124,6 +131,7 @@ export function normalizeOptions(
     buildStep,
     fetch: options.fetch ?? globalThis.fetch,
     host: 'https://flags.vercel.com',
+    environment: options.environment,
     clientName: options.clientName,
     disableMetrics: options.disableMetrics ?? false,
   };

packages/vercel-flags-core/src/utils/ingest.ts

@@ -31,6 +31,7 @@ export interface IngestOptions {
   auth: Auth;
   host: string;
   fetch: typeof fetch;
+  environment?: string;
 }
 
 async function getEvaluatingOidcToken(auth: Auth): Promise<string | undefined> {
@@ -55,6 +56,9 @@ async function getIngestHeaders(
     Authorization: `Bearer ${token}`,
     'User-Agent': `VercelFlagsCore/${version}`,
     [FLUSH_REASON_HEADER]: flushReason,
+    ...(options.environment
+      ? { 'X-Vercel-Environment': options.environment }
+      : null),
     ...(process.env.VERCEL_ENV
       ? { 'X-Vercel-Env': process.env.VERCEL_ENV }
       : null),