@vercel/flags-core 1.8.0 → 1.8.1-873d051-20260908100141

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @vercel/flags-core
 
+## 1.8.1-873d051-20260908100141
+
+### Patch Changes
+
+- [#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) [`873d051`](https://github.com/vercel/flags/commit/873d05196e9e0fa5c251f745cb67c067ab890337) Thanks [@luismeyer](https://github.com/luismeyer)! - Request `Accept-Encoding: gzip` on the `/v1/stream` connection.
+  
+  The stream is long-lived NDJSON and the server flushes the compressor after every message. Runtimes such as Bun advertise `br` by default but do not surface partially decoded brotli output until the response ends, so the initial datafile never arrived and every flag fell back to its default after the init timeout. gzip streams correctly on Node, Bun, and browsers.
+
 ## 1.8.0
 
 ### Minor Changes

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-ZROGU3V7.js → chunk-2KQT4NSN.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.0";
+var version = "1.8.1-873d051-20260908100141";
 
 // 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;
@@ -979,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;
@@ -1002,7 +1166,7 @@ var Scheduler = class {
         await this.onFlush(reason);
       })();
       try {
-        waitUntil(this.pending);
+        waitUntil2(this.pending);
       } catch {
       }
       this.maxTimeout = setTimeout(
@@ -1539,7 +1703,14 @@ async function connectStream(config, callbacks) {
         const headers = {
           Authorization: `Bearer ${token}`,
           "User-Agent": `VercelFlagsCore/${version}`,
-          "X-Retry-Attempt": String(retryCount)
+          "X-Retry-Attempt": String(retryCount),
+          // The stream is long-lived NDJSON; the server flushes the compressor
+          // after every message. Some runtimes (Bun) advertise `br` by default
+          // but do not surface partially decoded brotli output until the
+          // response ends, so the first datafile never arrives and init times
+          // out. gzip streams correctly everywhere, so request it explicitly.
+          // See https://github.com/oven-sh/bun/issues/41439
+          "Accept-Encoding": "gzip"
         };
         const vercelEnv = process.env.VERCEL_ENV;
         if (vercelEnv) {
@@ -2445,11 +2616,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() {
@@ -2499,4 +2672,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-ZROGU3V7.js.map
+//# sourceMappingURL=chunk-2KQT4NSN.js.map