@vercel/flags-core 1.8.1-9d0e81e-20260908151858 → 1.8.1

package/CHANGELOG.md

@@ -1,10 +1,28 @@
 # @vercel/flags-core
 
-## 1.8.1-9d0e81e-20260908151858
+## 1.8.1
 
 ### Patch Changes
 
-- [#490](https://github.com/vercel/flags/pull/490) [`559c1e7`](https://github.com/vercel/flags/commit/559c1e7bb14765acb234bf004c8e839fadfc2922) Thanks [@AndyBitz](https://github.com/AndyBitz)! - Use the runtime-provided ingest transport when available
+- [#486](https://github.com/vercel/flags/pull/486) [`c9d2811`](https://github.com/vercel/flags/commit/c9d28116ebca661f4e3c73f301d4b2d35310c823) Thanks [@dferber90](https://github.com/dferber90)! - Add APIs for reporting flag exposures and override values.
+  
+  - The `experimental_reportExposures` client option for supplying an exposure
+    reporter.
+  - The `experimental_reportOverride` client method for reporting values set by
+    the Flags SDK override cookie.
+  - The `experimental_exposureLogging` option on `evaluate()` and
+    `bulkEvaluate()` for disabling exposure reporting for an individual call.
+  - Experiment assignment metadata on `EvaluationResult.experiment`.
+  - The `experimental_EvaluationOptions`,
+    `experimental_ExperimentAssignment`, `experimental_Exposure`, and
+    `experimental_ReportExposures` types.
+  
+  These APIs are not supported for general use yet. Do not use them unless
+  Vercel has explicitly enabled them for you.
+
+- [#494](https://github.com/vercel/flags/pull/494) [`e0eebe6`](https://github.com/vercel/flags/commit/e0eebe6fbc296636761eb3dc31f2c4be01a398bf) Thanks [@luismeyer](https://github.com/luismeyer)! - Request an uncompressed `/v1/stream` body when running on Bun.
+  
+  Bun's `fetch` negotiates brotli or gzip by default, but its streaming decoder withholds small decoded output until more compressed input arrives. The stream's first datafile is followed by silence until the next ping, so on Bun the initial datafile never surfaced, init timed out, and every flag fell back to its default. Sending `Accept-Encoding: identity` on Bun avoids the decoder entirely; other runtimes are unchanged.
 
 ## 1.8.0
 

package/README.md

@@ -24,6 +24,8 @@ const result = await client.evaluate<boolean>('show-new-feature', false, {
 });
 ```
 
+## Evaluation Metrics
+
 To associate evaluation metrics with an environment, pass the
 `metricEnvironment` option:
 

package/dist/{chunk-YBQ6KBYF.js → chunk-5BWCBI7I.js}

@@ -327,7 +327,43 @@ function getVariant(definition, index) {
     variantId
   };
 }
-function handleOutcome(params, outcome) {
+function getWeightedVariantIndex(params, assignment, seed) {
+  const lhs = access(assignment.base, params);
+  if (typeof lhs !== "string") return assignment.defaultVariant;
+  const bucket = hashInput(lhs, seed);
+  const boundaries = getSplitBoundaries(assignment);
+  for (let index = 0; index < boundaries.length; index++) {
+    if (bucket < boundaries[index]) return index;
+  }
+  return assignment.defaultVariant;
+}
+function experimentAssignment(experiment, variantId, assignmentReason) {
+  if (variantId === null) return void 0;
+  return {
+    id: experiment.id,
+    variantId,
+    base: experiment.base,
+    rampId: experiment.rampId,
+    rampPercentage: experiment.rampPercentage,
+    assignmentReason
+  };
+}
+function outcomeAssignmentReason(outcome) {
+  if (typeof outcome === "number") return "variant";
+  switch (outcome.type) {
+    case "experiment":
+      return "experiment";
+    case "split":
+      return "split";
+    case "rollout":
+      return "rollout";
+    default: {
+      const { type } = outcome;
+      return exhaustivenessCheck(type);
+    }
+  }
+}
+function resolveOutcome(params, outcome) {
   if (typeof outcome === "number") {
     const variant = getVariant(params.definition, outcome);
     return {
@@ -337,32 +373,48 @@ function handleOutcome(params, outcome) {
   }
   switch (outcome.type) {
     case "split": {
-      const lhs = access(outcome.base, params);
-      const defaultOutcome = getVariant(
-        params.definition,
-        outcome.defaultVariant
+      const index = getWeightedVariantIndex(
+        params,
+        outcome,
+        params.definition.seed
       );
-      if (typeof lhs !== "string") {
-        return {
-          ...defaultOutcome,
-          outcomeType: "split" /* SPLIT */
-        };
-      }
-      const bucket = hashInput(lhs, params.definition.seed);
-      const boundaries = getSplitBoundaries(outcome);
-      for (let index = 0; index < boundaries.length; index++) {
-        if (bucket < boundaries[index]) {
-          return {
-            ...getVariant(params.definition, index),
-            outcomeType: "split" /* SPLIT */
-          };
-        }
-      }
       return {
-        ...defaultOutcome,
+        ...getVariant(params.definition, index),
         outcomeType: "split" /* SPLIT */
       };
     }
+    case "experiment": {
+      const experiment = params.definition.experiment;
+      if (!experiment) {
+        throw new Error("@vercel/flags-core: Experiment not found");
+      }
+      const unitValue = access(experiment.base, params);
+      const defaultVariant = getVariant(
+        params.definition,
+        experiment.defaultVariant
+      );
+      const assignment = (variant, assignmentReason) => ({
+        ...variant,
+        outcomeType: "experiment" /* EXPERIMENT */,
+        experiment: experimentAssignment(
+          experiment,
+          variant.variantId,
+          assignmentReason
+        )
+      });
+      if (typeof unitValue !== "string") {
+        return assignment(defaultVariant, "not-enrolled");
+      }
+      const rampPercentage = experiment.rampPercentage ?? 100;
+      const enrolled = rampPercentage >= 100 || rampPercentage > 0 && hashInput(unitValue, experiment.enrollmentSeed) < boundaryFor(rampPercentage, 100);
+      if (!enrolled) return assignment(defaultVariant, "not-enrolled");
+      const index = getWeightedVariantIndex(
+        params,
+        experiment,
+        params.definition.seed
+      );
+      return assignment(getVariant(params.definition, index), "experiment");
+    }
     case "rollout": {
       const lhs = access(outcome.base, params);
       const defaultOutcome = getVariant(
@@ -435,6 +487,19 @@ function handleOutcome(params, outcome) {
     }
   }
 }
+function handleOutcome(params, outcome, assignmentReason) {
+  const result = resolveOutcome(params, outcome);
+  const experiment = params.definition.experiment;
+  if (!experiment || result.experiment) return result;
+  return {
+    ...result,
+    experiment: experimentAssignment(
+      experiment,
+      result.variantId,
+      assignmentReason ?? outcomeAssignmentReason(outcome)
+    )
+  };
+}
 function evaluate(params, _visited) {
   const envConfig = params.definition.environments[params.environment];
   if (typeof envConfig === "number") {
@@ -474,7 +539,7 @@ function evaluate(params, _visited) {
       (targetList) => matchTargetList(targetList, params)
     );
     if (matchedIndex > -1) {
-      return Object.assign(handleOutcome(params, matchedIndex), {
+      return Object.assign(handleOutcome(params, matchedIndex, "targeted"), {
         reason: "target_match" /* TARGET_MATCH */
       });
     }
@@ -508,7 +573,7 @@ function bulkEvaluate(flags, shared) {
 }
 
 // package.json
-var version = "1.8.1-9d0e81e-20260908151858";
+var version = "1.8.1";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -727,6 +792,8 @@ async function bulkEvaluate2(id, flags, entities) {
 }
 
 // src/create-raw-client.ts
+import { waitUntil } from "@vercel/functions";
+import { dequal } from "dequal/lite";
 var idCount = 0;
 async function performInitialize(instance, initFn) {
   try {
@@ -740,7 +807,8 @@ async function performInitialize(instance, initFn) {
 function createCreateRawClient(fns) {
   return function createRawClient({
     controller,
-    origin
+    origin,
+    experimental_reportExposures
   }) {
     const id = idCount++;
     controllerInstanceMap.set(id, {
@@ -748,6 +816,35 @@ function createCreateRawClient(fns) {
       initialized: false,
       initPromise: null
     });
+    function report(exposures, entity) {
+      if (!experimental_reportExposures || exposures.length === 0) return;
+      const pending = (async () => {
+        try {
+          await experimental_reportExposures(exposures, entity);
+        } catch (error) {
+          console.error(
+            "@vercel/flags-core: Failed to report experiment exposures",
+            error
+          );
+        }
+      })();
+      try {
+        waitUntil(pending);
+      } catch {
+      }
+    }
+    function getExposure(flagKey, result) {
+      if (!result.experiment) return null;
+      return {
+        flagKey,
+        experimentId: result.experiment.id,
+        variantId: result.experiment.variantId,
+        base: result.experiment.base,
+        ...result.experiment.rampId === void 0 ? {} : { rampId: result.experiment.rampId },
+        ...result.experiment.rampPercentage === void 0 ? {} : { rampPercentage: result.experiment.rampPercentage },
+        assignmentReason: result.experiment.assignmentReason
+      };
+    }
     const api = {
       origin,
       initialize: async () => {
@@ -782,7 +879,7 @@ function createCreateRawClient(fns) {
       getFallbackDatafile: () => {
         return fns.getFallbackDatafile(id);
       },
-      evaluate: async (flagKey, defaultValue, entities) => {
+      evaluate: async (flagKey, defaultValue, entities, options) => {
         const instance = controllerInstanceMap.get(id);
         if (!instance?.initialized) {
           try {
@@ -790,9 +887,22 @@ function createCreateRawClient(fns) {
           } catch {
           }
         }
-        return fns.evaluate(id, flagKey, defaultValue, entities);
+        const entity = entities ?? {};
+        const result = await fns.evaluate(
+          id,
+          flagKey,
+          defaultValue,
+          entity
+        );
+        if (experimental_reportExposures && options?.experimental_exposureLogging !== false) {
+          const exposure = getExposure(flagKey, result);
+          if (exposure) {
+            report([exposure], entity);
+          }
+        }
+        return result;
       },
-      bulkEvaluate: async (flags, entities) => {
+      bulkEvaluate: async (flags, entities, options) => {
         const instance = controllerInstanceMap.get(id);
         if (!instance?.initialized) {
           try {
@@ -800,7 +910,61 @@ function createCreateRawClient(fns) {
           } catch {
           }
         }
-        return fns.bulkEvaluate(id, flags, entities);
+        const entity = entities ?? {};
+        const results = await fns.bulkEvaluate(id, flags, entity);
+        if (experimental_reportExposures && options?.experimental_exposureLogging !== false) {
+          const exposures = [];
+          const seen = /* @__PURE__ */ new Set();
+          for (const flag of flags) {
+            if (seen.has(flag.key)) continue;
+            seen.add(flag.key);
+            const result = results[flag.key];
+            if (!result) continue;
+            const exposure = getExposure(flag.key, result);
+            if (exposure) exposures.push(exposure);
+          }
+          report(exposures, entity);
+        }
+        return results;
+      },
+      experimental_reportOverride: async ({
+        key,
+        value,
+        entities
+      }) => {
+        if (!experimental_reportExposures) return;
+        try {
+          const instance = controllerInstanceMap.get(id);
+          if (!instance?.initialized) await api.initialize();
+          const datafile = await fns.getDatafile(id);
+          const definition = datafile.definitions[key];
+          const experiment = definition?.experiment;
+          if (!experiment) return;
+          const variantIndex = definition.variants.findIndex(
+            (variant) => dequal(variant, value)
+          );
+          const variantId = variantIndex < 0 ? null : definition.variantIds?.[variantIndex] ?? null;
+          const entity = entities ?? {};
+          report(
+            [
+              {
+                flagKey: key,
+                experimentId: experiment.id,
+                variantId,
+                base: experiment.base,
+                rampId: experiment.rampId,
+                rampPercentage: experiment.rampPercentage,
+                assignmentReason: "override"
+              }
+            ],
+            entity
+          );
+        } catch (error) {
+          console.error(
+            "@vercel/flags-core: Failed to report experiment override",
+            error
+          );
+        }
       }
     };
     return api;
@@ -881,17 +1045,6 @@ function getJitteredWaitMs(baseMs, ratio) {
   return Math.floor(min + Math.random() * span);
 }
 
-// src/utils/runtime-ingest.ts
-var FLAGS_CONTEXT_SYMBOL = /* @__PURE__ */ Symbol.for("@vercel/flags-context");
-function getRuntimeIngest() {
-  try {
-    const context = globalThis[FLAGS_CONTEXT_SYMBOL];
-    return typeof context?.ingest === "function" ? context.ingest : void 0;
-  } catch {
-    return void 0;
-  }
-}
-
 // src/utils/ingest.ts
 var MAX_RETRIES = 3;
 var MAX_EVENTS_PER_REQUEST = 2e3;
@@ -925,28 +1078,8 @@ async function getIngestHeaders(options, flushReason) {
     ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
   };
 }
-function getRuntimeIngestHeaders(options, flushReason) {
-  return {
-    "Content-Type": "application/json",
-    ...options.auth.sdkKey ? { Authorization: `Bearer ${options.auth.sdkKey}` } : null,
-    "User-Agent": `VercelFlagsCore/${version}`,
-    [FLUSH_REASON_HEADER]: flushReason,
-    ...options.metricEnvironment ?? process.env.VERCEL_ENV ? {
-      "X-Vercel-Env": options.metricEnvironment ?? process.env.VERCEL_ENV
-    } : null,
-    ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
-  };
-}
 async function sendIngestEvents(options, events, flushId, flushReason) {
-  let eventsToSend = events.map((event) => event.ingestEvent());
-  const runtimeIngest = getRuntimeIngest();
-  if (runtimeIngest) {
-    const headers = getRuntimeIngestHeaders(options, flushReason);
-    eventsToSend = eventsToSend.filter(
-      (event) => !runtimeIngest({ headers, body: [event] })
-    );
-    if (eventsToSend.length === 0) return;
-  }
+  const eventsToSend = events.map((event) => event.ingestEvent());
   for (let i = 0; i < eventsToSend.length; i += MAX_EVENTS_PER_REQUEST) {
     await sendIngestChunk(
       options,
@@ -1010,7 +1143,7 @@ function getRequestContext() {
 }
 
 // src/utils/scheduler.ts
-import { waitUntil } from "@vercel/functions";
+import { waitUntil as waitUntil2 } from "@vercel/functions";
 var IDLE_FLUSH_WAIT_MS = 5e3;
 var IDLE_FLUSH_JITTER_RATIO = 0.2;
 var MAX_FLUSH_WAIT_MS = 6e4;
@@ -1033,7 +1166,7 @@ var Scheduler = class {
         await this.onFlush(reason);
       })();
       try {
-        waitUntil(this.pending);
+        waitUntil2(this.pending);
       } catch {
       }
       this.maxTimeout = setTimeout(
@@ -1205,7 +1338,7 @@ var UsageTracker = class {
       if (this.trackedRequests.has(ctx)) return;
       this.trackedRequests.add(ctx);
       this.readEvents.push(new FlagsConfigReadEvent(headers, options));
-      this.requestFlush();
+      this.scheduler.scheduleFlush();
     } catch (error) {
       console.error("@vercel/flags-core: Failed to record event:", error);
     }
@@ -1229,7 +1362,7 @@ var UsageTracker = class {
           new FlagsEvaluationEvent(bucketedOptions)
         );
       }
-      this.requestFlush();
+      this.scheduler.scheduleFlush();
     } catch (error) {
       console.error(
         "@vercel/flags-core: Failed to record evaluation event:",
@@ -1237,19 +1370,6 @@ var UsageTracker = class {
       );
     }
   }
-  /**
-   * Flushes immediately when the runtime provides an ingest transport,
-   * otherwise falls back to the time-based scheduler.
-   */
-  requestFlush() {
-    if (getRuntimeIngest()) {
-      void this.flushEvents("immediate").catch((error) => {
-        console.error("@vercel/flags-core: Failed to flush events:", error);
-      });
-    } else {
-      this.scheduler.scheduleFlush();
-    }
-  }
   /**
    * Send all events to the ingest service
    */
@@ -1501,6 +1621,11 @@ var PollingSource = class extends TypedEmitter {
   }
 };
 
+// src/utils/runtime.ts
+function isBun() {
+  return typeof globalThis.Bun !== "undefined";
+}
+
 // src/utils/sleep.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -1585,6 +1710,9 @@ async function connectStream(config, callbacks) {
           "User-Agent": `VercelFlagsCore/${version}`,
           "X-Retry-Attempt": String(retryCount)
         };
+        if (isBun()) {
+          headers["Accept-Encoding"] = "identity";
+        }
         const vercelEnv = process.env.VERCEL_ENV;
         if (vercelEnv) {
           headers["X-Vercel-Env"] = vercelEnv;
@@ -2489,11 +2617,13 @@ function make(createRawClient) {
     const optionsOnly = typeof sdkKeyOrConnectionStringOrOptions === "object" && sdkKeyOrConnectionStringOrOptions !== null;
     const sdkKeyOrConnectionString = optionsOnly ? void 0 : sdkKeyOrConnectionStringOrOptions;
     const createClientOptions = optionsOnly ? sdkKeyOrConnectionStringOrOptions : options;
+    const { experimental_reportExposures, ...controllerOptions } = createClientOptions ?? {};
     const auth = new Authentication(sdkKeyOrConnectionString);
-    const controller = new Controller({ auth, ...createClientOptions });
+    const controller = new Controller({ auth, ...controllerOptions });
     return createRawClient({
       controller,
-      origin: { provider: "vercel", sdkKey: auth.sdkKey }
+      origin: { provider: "vercel", sdkKey: auth.sdkKey },
+      ...experimental_reportExposures ? { experimental_reportExposures } : {}
     });
   }
   function resetDefaultFlagsClient2() {
@@ -2543,4 +2673,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-YBQ6KBYF.js.map
+//# sourceMappingURL=chunk-5BWCBI7I.js.map