@vercel/flags-core 1.8.0 → 1.9.0-b67dc74-20260831122711

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/flags-core
 
+## 1.9.0-b67dc74-20260831122711
+
+### Minor Changes
+
+- [#486](https://github.com/vercel/flags/pull/486) [`8505d17`](https://github.com/vercel/flags/commit/8505d179b6d1e43d3401cd7d6a7b89bf5ae92854) Thanks [@dferber90](https://github.com/dferber90)! - Add randomized experiment enrollment, assignment reasons for every experiment-managed flag outcome, readiness-aware cookie override exposure reporting, and per-evaluation exposure logging controls.
+
 ## 1.8.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,50 @@ const result = await client.evaluate<boolean>('show-new-feature', false, {
 });
 ```
 
+## Experiment exposures
+
+Flags linked to an experiment report exposures automatically, regardless of
+whether the evaluated value came from a fixed variant, target, split, rollout,
+or fallthrough. Provide a custom reporter to send them to your analytics
+system:
+
+```ts
+const client = createClient(process.env.FLAGS!, {
+  reportExposures: async (exposures, entity) => {
+    await analytics.reportExposures(exposures, entity);
+  },
+});
+```
+
+`evaluate()` reports at most one exposure. `bulkEvaluate()` reports all
+experiment exposures in one callback with the single entity object shared by
+the evaluations. The default reporter currently maps exposures to the Vercel
+Web Analytics shape and logs them through a temporary console-backed tracker.
+
+Disable exposure logging for an evaluation when evaluating speculatively or
+prefetching:
+
+```ts
+const result = await client.evaluate(
+  'show-new-feature',
+  false,
+  { user: { key: 'user-123' } },
+  { exposureLogging: false },
+);
+```
+
+The same option is supported by `bulkEvaluate()`:
+
+```ts
+await client.bulkEvaluate(
+  [{ key: 'show-new-feature', defaultValue: false }],
+  { user: { key: 'user-123' } },
+  { exposureLogging: false },
+);
+```
+
+## Evaluation Metrics
+
 To associate evaluation metrics with an environment, pass the
 `metricEnvironment` option:
 

package/dist/{chunk-ZV3PRKK2.js → chunk-6UH74J6U.js}

@@ -312,7 +312,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 {
@@ -322,32 +358,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(
@@ -420,6 +472,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") {
@@ -459,7 +524,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 */
       });
     }
@@ -493,7 +558,7 @@ function bulkEvaluate(flags, shared) {
 }
 
 // package.json
-var version = "1.8.0";
+var version = "1.9.0-b67dc74-20260831122711";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -711,6 +776,66 @@ async function bulkEvaluate2(id, flags, entities) {
   return results;
 }
 
+// src/exposure-reporting.ts
+var FAKE_DEVICE_ID = "fake-device-id";
+function getProperty2(entity, path) {
+  return path.reduce((value, key) => {
+    if (typeof value !== "object" || value === null || !(key in value)) {
+      return void 0;
+    }
+    return value[key];
+  }, entity);
+}
+function isBase(base, kind) {
+  return base.length === 2 && base[0] === kind && base[1] === "key";
+}
+function flattenBase(base) {
+  return base.map(String).map(
+    (part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
+  ).join("");
+}
+function mapExposure(exposure, entity) {
+  let unitKey;
+  let unitValue;
+  if (isBase(exposure.base, "user")) {
+    unitKey = "user";
+    unitValue = getProperty2(entity, exposure.base);
+  } else if (isBase(exposure.base, "session")) {
+    unitKey = "session";
+    unitValue = getProperty2(entity, exposure.base);
+  } else if (isBase(exposure.base, "device")) {
+    unitKey = "device";
+    unitValue = FAKE_DEVICE_ID;
+  } else if (isBase(exposure.base, "team")) {
+    unitKey = "group";
+    unitValue = getProperty2(entity, exposure.base);
+  } else {
+    const flattenedBase = flattenBase(exposure.base);
+    if (!flattenedBase) return null;
+    unitKey = `event_data.${flattenedBase}`;
+    unitValue = getProperty2(entity, exposure.base);
+  }
+  if (typeof unitValue !== "string") return null;
+  return {
+    experimentId: exposure.experimentId,
+    variantId: exposure.variantId ?? "override",
+    unitKey,
+    unitValue,
+    ...exposure.rampId === void 0 ? {} : { rampId: exposure.rampId },
+    ...exposure.rampPercentage === void 0 ? {} : { rampPercentage: exposure.rampPercentage },
+    assignmentReason: exposure.assignmentReason
+  };
+}
+function trackExposure(exposure) {
+  console.log("@vercel/flags-core: trackExposure", exposure);
+}
+var defaultReportExposures = (exposures, entity) => {
+  for (const exposure of exposures) {
+    const mapped = mapExposure(exposure, entity);
+    if (mapped) trackExposure(mapped);
+  }
+};
+
 // src/create-raw-client.ts
 var idCount = 0;
 async function performInitialize(instance, initFn) {
@@ -725,7 +850,8 @@ async function performInitialize(instance, initFn) {
 function createCreateRawClient(fns) {
   return function createRawClient({
     controller,
-    origin
+    origin,
+    reportExposures
   }) {
     const id = idCount++;
     controllerInstanceMap.set(id, {
@@ -733,6 +859,30 @@ function createCreateRawClient(fns) {
       initialized: false,
       initPromise: null
     });
+    const exposureReporter = reportExposures ?? defaultReportExposures;
+    async function report(exposures, entity) {
+      if (exposures.length === 0) return;
+      try {
+        await exposureReporter(exposures, entity);
+      } catch (error) {
+        console.error(
+          "@vercel/flags-core: Failed to report experiment exposures",
+          error
+        );
+      }
+    }
+    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 () => {
@@ -767,7 +917,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 {
@@ -775,9 +925,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 (options?.exposureLogging !== false) {
+          const exposure = getExposure(flagKey, result);
+          if (exposure) {
+            await report([exposure], entity);
+          }
+        }
+        return result;
       },
-      bulkEvaluate: async (flags, entities) => {
+      bulkEvaluate: async (flags, entities, options) => {
         const instance = controllerInstanceMap.get(id);
         if (!instance?.initialized) {
           try {
@@ -785,7 +948,57 @@ function createCreateRawClient(fns) {
           } catch {
           }
         }
-        return fns.bulkEvaluate(id, flags, entities);
+        const entity = entities ?? {};
+        const results = await fns.bulkEvaluate(id, flags, entity);
+        if (options?.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);
+          }
+          await report(exposures, entity);
+        }
+        return results;
+      },
+      reportOverride: async (flagKey, value, entities) => {
+        try {
+          const instance = controllerInstanceMap.get(id);
+          if (!instance?.initialized) await api.initialize();
+          const datafile = await fns.getDatafile(id);
+          const definition = datafile.definitions[flagKey];
+          const experiment = definition?.experiment;
+          if (!experiment) return;
+          const serializedValue = JSON.stringify(value);
+          const variantIndex = definition.variants.findIndex(
+            (variant) => Object.is(variant, value) || JSON.stringify(variant) === serializedValue
+          );
+          const variantId = variantIndex < 0 ? null : definition.variantIds?.[variantIndex] ?? null;
+          const entity = entities ?? {};
+          await report(
+            [
+              {
+                flagKey,
+                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;
@@ -2430,11 +2643,13 @@ function make(createRawClient) {
     const optionsOnly = typeof sdkKeyOrConnectionStringOrOptions === "object" && sdkKeyOrConnectionStringOrOptions !== null;
     const sdkKeyOrConnectionString = optionsOnly ? void 0 : sdkKeyOrConnectionStringOrOptions;
     const createClientOptions = optionsOnly ? sdkKeyOrConnectionStringOrOptions : options;
+    const { 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 },
+      ...reportExposures ? { reportExposures } : {}
     });
   }
   function resetDefaultFlagsClient2() {
@@ -2502,6 +2717,7 @@ var { flagsClient, resetDefaultFlagsClient, createClient } = make(
 export {
   ResolutionReason,
   evaluate,
+  defaultReportExposures,
   FallbackNotFoundError,
   FallbackEntryNotFoundError,
   Controller,
@@ -2509,4 +2725,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-ZV3PRKK2.js.map
+//# sourceMappingURL=chunk-6UH74J6U.js.map