@replohq/sdk 2.10.1 → 2.11.0

package/_vendor/schemas/routing/experimentCookie.d.ts

@@ -0,0 +1,24 @@
+/** The cookie that records which variant of each experiment a visitor saw. */
+export declare const EXPERIMENTS_COOKIE = "replo_experiments";
+/** Marks a counted visit's response (`experimentKey:variantKey`); the pixel turns it into one `replo.experiment_exposure` and clears it. */
+export declare const EXPERIMENT_EXPOSURE_COOKIE = "replo_experiment_exposure";
+/** The durable visitor ID experiments hash to pick a variant. */
+export declare const VISITOR_ID_COOKIE = "replo_visitor_id";
+/** `?experiment=<experimentKey>:<variantKey>` pins a variant for QA; forced visits are left out of results. */
+export declare const EXPERIMENT_OVERRIDE_PARAM = "experiment";
+export declare const EXPERIMENT_KEY_PATTERN: RegExp;
+export type ExperimentAssignment = {
+    variantKey: string;
+    /** Pinned with `?experiment=`, so the visit is QA rather than a sample. */
+    forced: boolean;
+};
+/** Assignments keyed by experiment key. */
+export type ExperimentAssignments = Record<string, ExperimentAssignment>;
+/** Reads a `replo_experiments` value (`bold-hero:bold!|pricing:control`), dropping malformed entries. */
+export declare function parseExperimentCookie(value: string | null | undefined): ExperimentAssignments;
+export declare function serializeExperimentCookie(assignments: ExperimentAssignments): string;
+/** Reads a `?experiment=` value (`bold-hero:bold`); null when it isn't one experiment key and one variant key. */
+export declare function parseExperimentOverride(value: string): {
+    experimentKey: string;
+    variantKey: string;
+} | null;

package/_vendor/schemas/routing/experimentCookie.mjs

@@ -0,0 +1 @@
+export { EXPERIMENTS_COOKIE, EXPERIMENT_EXPOSURE_COOKIE, EXPERIMENT_KEY_PATTERN, EXPERIMENT_OVERRIDE_PARAM, VISITOR_ID_COOKIE, parseExperimentCookie, parseExperimentOverride, serializeExperimentCookie } from '../../../chunk-PH6IR743.mjs';

package/_vendor/schemas/routing/experiments.d.ts

@@ -0,0 +1,73 @@
+import * as z from "zod";
+export declare const experimentKeySchema: z.ZodString;
+export declare const experimentRouteSchema: z.ZodString;
+export declare const experimentVariantSchema: z.ZodObject<{
+    variantKey: z.ZodString;
+    route: z.ZodString;
+    rolloutPercentage: z.ZodNumber;
+}, z.core.$strip>;
+export declare const experimentStatusSchema: z.ZodEnum<{
+    running: "running";
+    draft: "draft";
+    stopped: "stopped";
+}>;
+/** The routing view of one `agent_experiment` row, as the site's KV and `experiments.json` store it. */
+export declare const experimentSchema: z.ZodObject<{
+    experimentKey: z.ZodString;
+    route: z.ZodString;
+    status: z.ZodEnum<{
+        running: "running";
+        draft: "draft";
+        stopped: "stopped";
+    }>;
+    variants: z.ZodArray<z.ZodObject<{
+        variantKey: z.ZodString;
+        route: z.ZodString;
+        rolloutPercentage: z.ZodNumber;
+    }, z.core.$strip>>;
+    shippedVariantKey: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const experimentsFileSchema: z.ZodObject<{
+    experiments: z.ZodArray<z.ZodObject<{
+        experimentKey: z.ZodString;
+        route: z.ZodString;
+        status: z.ZodEnum<{
+            running: "running";
+            draft: "draft";
+            stopped: "stopped";
+        }>;
+        variants: z.ZodArray<z.ZodObject<{
+            variantKey: z.ZodString;
+            route: z.ZodString;
+            rolloutPercentage: z.ZodNumber;
+        }, z.core.$strip>>;
+        shippedVariantKey: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    liveRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** The binding a published site's worker reads its own KV namespace through. */
+export declare const SITE_KV_BINDING = "SITE_KV";
+/** The site KV key holding the site's live experiment routing, an `ExperimentsFile` without `liveRoutes`. */
+export declare const SITE_KV_EXPERIMENTS_KEY = "experiments";
+export type ExperimentVariant = z.infer<typeof experimentVariantSchema>;
+export type ExperimentStatus = z.infer<typeof experimentStatusSchema>;
+export type Experiment = z.infer<typeof experimentSchema>;
+export type ExperimentsFile = z.infer<typeof experimentsFileSchema>;
+/** Hashes experiment key + visitor ID, so a visitor keeps one variant and each experiment shuffles independently. */
+export declare function assignVariant({ visitorId, experiment, }: {
+    visitorId: string;
+    experiment: Pick<Experiment, "experimentKey" | "variants">;
+}): ExperimentVariant;
+/** The experiment that routes `pathname`: a running one, else one that shipped a non-control variant. */
+export declare function findActiveExperiment({ experiments, pathname, }: {
+    experiments: readonly Experiment[];
+    pathname: string;
+}): Experiment | null;
+/** Whether a stopped experiment still routes every visitor to its shipped variant. */
+export declare function hasNonControlShippedVariant(experiment: Experiment): boolean;
+/** Whether the experiment routes traffic, and so belongs in the site's routing. */
+export declare function isRoutingExperiment(experiment: Experiment): boolean;
+/** The variants visitors are sent to: all of them while running, else the shipped one. */
+export declare function findServedVariants(experiment: Experiment): ExperimentVariant[];
+/** Trailing slashes carry no meaning, so `/landing` and `/landing/` are one route. */
+export declare function normalizeRoute(pathname: string): string;

package/_vendor/schemas/routing/experiments.mjs

@@ -0,0 +1,164 @@
+import { EXPERIMENT_KEY_PATTERN } from '../../../chunk-PH6IR743.mjs';
+import * as z from 'zod';
+
+var MIN_VARIANTS = 2;
+var MAX_VARIANTS = 5;
+var TOTAL_ROLLOUT_PERCENTAGE = 100;
+var ASSIGNMENT_BUCKETS = 1e4;
+var experimentKeySchema = z.string().regex(EXPERIMENT_KEY_PATTERN, {
+  message: "must be lowercase kebab-case, e.g. bold-hero"
+});
+var experimentRouteSchema = z.string().min(1).refine((route) => route.startsWith("/"), { message: "must start with /" });
+var experimentVariantSchema = z.object({
+  variantKey: experimentKeySchema.describe(
+    "Stable identifier stored in the visitor's cookie and on every event"
+  ),
+  route: experimentRouteSchema.describe("The page this variant renders"),
+  rolloutPercentage: z.number().int().min(0).max(TOTAL_ROLLOUT_PERCENTAGE).describe("Share of traffic, in percent")
+});
+var experimentStatusSchema = z.enum(["draft", "running", "stopped"]);
+var experimentSchema = z.object({
+  experimentKey: experimentKeySchema.describe(
+    "The experiment's key; changing it reassigns every visitor"
+  ),
+  route: experimentRouteSchema.describe(
+    "The shared URL visitors land on; the control variant renders it"
+  ),
+  status: experimentStatusSchema.describe(
+    "Only running experiments, and stopped ones with a shipped variant, route traffic"
+  ),
+  variants: z.array(experimentVariantSchema).min(MIN_VARIANTS).max(MAX_VARIANTS).describe("The control first, then up to four challengers"),
+  shippedVariantKey: experimentKeySchema.nullable().describe(
+    "Variant key every visitor gets once the experiment has stopped; null keeps the control"
+  )
+}).superRefine((experiment, context) => {
+  const [control] = experiment.variants;
+  if (control && normalizeRoute(control.route) !== normalizeRoute(experiment.route)) {
+    context.addIssue({
+      code: "custom",
+      path: ["variants", 0, "route"],
+      message: "the first variant is the control and must use the experiment's route"
+    });
+  }
+  const totalRolloutPercentage = experiment.variants.reduce(
+    (sum, variant) => sum + variant.rolloutPercentage,
+    0
+  );
+  if (totalRolloutPercentage !== TOTAL_ROLLOUT_PERCENTAGE) {
+    context.addIssue({
+      code: "custom",
+      path: ["variants"],
+      message: `variant rollout percentages must add up to ${TOTAL_ROLLOUT_PERCENTAGE}, not ${totalRolloutPercentage}`
+    });
+  }
+  addDuplicateIssues({
+    context,
+    values: experiment.variants.map((variant) => variant.variantKey),
+    path: ["variants"],
+    describe: (key) => `duplicate variantKey "${key}"`
+  });
+  addDuplicateIssues({
+    context,
+    values: experiment.variants.map((variant) => {
+      return normalizeRoute(variant.route);
+    }),
+    path: ["variants"],
+    describe: (route) => `duplicate route "${route}"`
+  });
+  if (experiment.shippedVariantKey !== null && !experiment.variants.some((variant) => {
+    return variant.variantKey === experiment.shippedVariantKey;
+  })) {
+    context.addIssue({
+      code: "custom",
+      path: ["shippedVariantKey"],
+      message: `"${experiment.shippedVariantKey}" is not one of this experiment's variant keys`
+    });
+  }
+});
+var experimentsFileSchema = z.object({
+  experiments: z.array(experimentSchema).describe("Every running or stopped experiment on the site"),
+  liveRoutes: z.array(experimentRouteSchema).optional().describe(
+    "Pages live in this build; the middleware never sends a visitor to a page outside this list"
+  )
+}).superRefine(({ experiments }, context) => {
+  addDuplicateIssues({
+    context,
+    values: experiments.map((experiment) => experiment.experimentKey),
+    path: ["experiments"],
+    describe: (key) => `duplicate experimentKey "${key}"`
+  });
+  addDuplicateIssues({
+    context,
+    values: experiments.filter((experiment) => experiment.status === "running").map((experiment) => normalizeRoute(experiment.route)),
+    path: ["experiments"],
+    describe: (route) => `two running experiments share the route "${route}"`
+  });
+});
+var SITE_KV_BINDING = "SITE_KV";
+var SITE_KV_EXPERIMENTS_KEY = "experiments";
+function assignVariant({
+  visitorId,
+  experiment
+}) {
+  const bucket = fnv1a32(`${experiment.experimentKey}:${visitorId}`) % ASSIGNMENT_BUCKETS;
+  const bucketsPerPercent = ASSIGNMENT_BUCKETS / TOTAL_ROLLOUT_PERCENTAGE;
+  let cumulative = 0;
+  for (const variant of experiment.variants) {
+    cumulative += variant.rolloutPercentage * bucketsPerPercent;
+    if (bucket < cumulative) {
+      return variant;
+    }
+  }
+  return experiment.variants.at(-1);
+}
+function findActiveExperiment({
+  experiments,
+  pathname
+}) {
+  const route = normalizeRoute(pathname);
+  const onRoute = experiments.filter((experiment) => {
+    return normalizeRoute(experiment.route) === route;
+  });
+  return onRoute.find((experiment) => experiment.status === "running") ?? onRoute.find(hasNonControlShippedVariant) ?? null;
+}
+function hasNonControlShippedVariant(experiment) {
+  return experiment.status === "stopped" && experiment.shippedVariantKey !== null && experiment.shippedVariantKey !== experiment.variants[0]?.variantKey;
+}
+function isRoutingExperiment(experiment) {
+  return experiment.status === "running" || hasNonControlShippedVariant(experiment);
+}
+function findServedVariants(experiment) {
+  return experiment.status === "running" ? experiment.variants : experiment.variants.filter((variant) => {
+    return variant.variantKey === experiment.shippedVariantKey;
+  });
+}
+function normalizeRoute(pathname) {
+  const trimmed = pathname.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed;
+}
+var FNV_OFFSET_BASIS = 2166136261;
+var FNV_PRIME = 16777619;
+function fnv1a32(value) {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}
+function addDuplicateIssues({
+  context,
+  values,
+  path,
+  describe
+}) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      context.addIssue({ code: "custom", path, message: describe(value) });
+    }
+    seen.add(value);
+  }
+}
+
+export { SITE_KV_BINDING, SITE_KV_EXPERIMENTS_KEY, assignVariant, experimentKeySchema, experimentRouteSchema, experimentSchema, experimentStatusSchema, experimentVariantSchema, experimentsFileSchema, findActiveExperiment, findServedVariants, hasNonControlShippedVariant, isRoutingExperiment, normalizeRoute };

package/cart/cart-actions.js

@@ -1,6 +1,7 @@
 "use server";
 import { cookies } from "next/headers";
 import { getCheckoutProvider } from "../lib/integration-utils";
+import { REPLO_ATTRIBUTION_PROPERTY } from "./cart-types";
 import {
   getCartCookieOptions,
   REPLO_CART_COOKIE_NAME
@@ -116,7 +117,17 @@ async function createCartAction(options) {
 }
 async function addToCartAction(lines, cartId) {
   const cartGateway = await getCartGateway();
-  return await cartGateway.addToCart({ lines, cartId });
+  const cart = await cartGateway.addToCart({ lines, cartId });
+  if (!cart || await getCheckoutProvider() !== "shopify" || cart.attributes?.some(
+    (attribute) => attribute.key === REPLO_ATTRIBUTION_PROPERTY.key
+  )) {
+    return cart;
+  }
+  const attributedCart = await cartGateway.replaceCartAttributes({
+    cartId: cart.id,
+    attributes: [...cart.attributes ?? [], REPLO_ATTRIBUTION_PROPERTY]
+  });
+  return attributedCart ?? cart;
 }
 async function updateCartLineItemAction(line, cartId) {
   const cartGateway = await getCartGateway();

package/cart/cart-types.d.ts

@@ -29,7 +29,10 @@ export interface CartLineAttribute {
     key: string;
     value: string | number | boolean;
 }
-/** Replo attribution property added to cart/buy-now line items for order attribution in Shopify. */
+/**
+ * Replo order attribution. Shopify carts the SDK adds to carry it as a cart
+ * attribute; buy-now and Stripe checkout lines carry it as a line property.
+ */
 export declare const REPLO_ATTRIBUTION_PROPERTY: CartLineAttribute;
 export interface SellingPlanPriceAdjustment {
     compareAtPrice: {

package/cart/hooks/use-add-to-cart.js

@@ -4,7 +4,6 @@ import { useQueryClient } from "@tanstack/react-query";
 import { fromMajorUnitsToMinorUnits } from "../../_vendor/schemas/moneyFormat.mjs";
 import { DATA_LOADER_KEYS } from "../../loaders/loader-keys";
 import { useCartInternal } from "../cart-provider";
-import { REPLO_ATTRIBUTION_PROPERTY } from "../cart-types";
 import { toCartError } from "../utils/cart-error";
 const PRODUCT_LOADER_KEYS = [
   DATA_LOADER_KEYS.SHOPIFY_PRODUCT,
@@ -90,10 +89,6 @@ function useAddToCart() {
       setIsAdding(true);
       try {
         const cartLines = items.map((item) => {
-          const hasReploAttribution = item.properties?.some(
-            (prop) => prop.key === REPLO_ATTRIBUTION_PROPERTY.key
-          );
-          const properties = hasReploAttribution ? item.properties ?? [] : [REPLO_ATTRIBUTION_PROPERTY, ...item.properties ?? []];
           const merchandise = item.merchandise ?? findMerchandiseInQueryCache({
             queryClient,
             merchandiseId: item.merchandiseId
@@ -102,7 +97,7 @@ function useAddToCart() {
             id: item.merchandiseId,
             quantity: item.quantity ?? 1,
             sellingPlanId: item.sellingPlanId ?? void 0,
-            properties,
+            properties: item.properties,
             merchandise
           };
         });

package/chunk-PH6IR743.mjs

@@ -0,0 +1,50 @@
+var EXPERIMENTS_COOKIE = "replo_experiments";
+var EXPERIMENT_EXPOSURE_COOKIE = "replo_experiment_exposure";
+var VISITOR_ID_COOKIE = "replo_visitor_id";
+var EXPERIMENT_OVERRIDE_PARAM = "experiment";
+var EXPERIMENT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var ENTRY_SEPARATOR = "|";
+var KEY_SEPARATOR = ":";
+var FORCED_SUFFIX = "!";
+function parseExperimentCookie(value) {
+  const assignments = {};
+  if (!value) {
+    return assignments;
+  }
+  for (const entry of decodeCookieValue(value).split(ENTRY_SEPARATOR)) {
+    const forced = entry.endsWith(FORCED_SUFFIX);
+    const parsed = parseExperimentOverride(
+      forced ? entry.slice(0, -FORCED_SUFFIX.length) : entry
+    );
+    if (parsed) {
+      assignments[parsed.experimentKey] = {
+        variantKey: parsed.variantKey,
+        forced
+      };
+    }
+  }
+  return assignments;
+}
+function serializeExperimentCookie(assignments) {
+  return Object.entries(assignments).map(([experimentKey, { variantKey, forced }]) => {
+    return `${experimentKey}${KEY_SEPARATOR}${variantKey}${forced ? FORCED_SUFFIX : ""}`;
+  }).join(ENTRY_SEPARATOR);
+}
+function parseExperimentOverride(value) {
+  const separatorIndex = value.indexOf(KEY_SEPARATOR);
+  const experimentKey = value.slice(0, separatorIndex);
+  const variantKey = value.slice(separatorIndex + 1);
+  return separatorIndex !== -1 && EXPERIMENT_KEY_PATTERN.test(experimentKey) && EXPERIMENT_KEY_PATTERN.test(variantKey) ? { experimentKey, variantKey } : null;
+}
+function decodeCookieValue(value) {
+  if (!value.includes("%")) {
+    return value;
+  }
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export { EXPERIMENTS_COOKIE, EXPERIMENT_EXPOSURE_COOKIE, EXPERIMENT_KEY_PATTERN, EXPERIMENT_OVERRIDE_PARAM, VISITOR_ID_COOKIE, parseExperimentCookie, parseExperimentOverride, serializeExperimentCookie };

package/consent/cookie.d.ts

@@ -36,4 +36,15 @@ export declare function serializeConsentCookieValue({ categories, decidedAt, con
     decidedAt: number;
     consentId?: string;
 }): string;
+/** A consent category a feature waits for; `null` when it needs none. */
+export type RequiredConsent = Exclude<ConsentCategory, "necessary"> | null;
+/** Whether the visitor's consent cookie grants `requiredConsent`. */
+export declare function isConsentGranted({ cookies, requiredConsent, }: {
+    cookies: {
+        get: (name: string) => {
+            value: string;
+        } | undefined;
+    };
+    requiredConsent: RequiredConsent;
+}): boolean;
 export {};

package/consent/cookie.js

@@ -70,12 +70,23 @@ function serializeConsentCookieValue({
   };
   return encodeURIComponent(JSON.stringify(payload));
 }
+function isConsentGranted({
+  cookies,
+  requiredConsent
+}) {
+  if (requiredConsent === null) {
+    return true;
+  }
+  const consent = parseConsentCookie(cookies.get(CONSENT_COOKIE_NAME)?.value);
+  return consent?.categories[requiredConsent] ?? false;
+}
 export {
   CONSENT_COOKIE_MAX_AGE_SECONDS,
   CONSENT_COOKIE_NAME,
   CONSENT_COOKIE_VERSION,
   DENIED_CATEGORIES,
   GRANTED_CATEGORIES,
+  isConsentGranted,
   parseConsentCookie,
   serializeConsentCookieValue
 };

package/env.d.ts

@@ -6,5 +6,14 @@ type Env = {
     REPLO_SITE_VERSION?: string;
     CHECKOUT_PROVIDER?: "shopify" | "stripe" | "none";
 };
+/** The read side of a Workers KV binding, as much as the SDK uses. */
+export type SiteKV = {
+    get(key: string, options: {
+        type: "json";
+        cacheTtl: number;
+    }): Promise<unknown>;
+};
+/** The site's own KV namespace; null outside the deployed worker or on a build publish didn't bind one to. */
+export declare const getSiteKV: () => Promise<SiteKV | null>;
 export declare const getEnv: () => Promise<Env>;
 export {};

package/env.js

@@ -1,4 +1,5 @@
 import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { SITE_KV_BINDING } from "./_vendor/schemas/routing/experiments.mjs";
 import JSONC from "tiny-jsonc";
 import * as z from "zod";
 import { CanopyError } from "./lib/canopy-error";
@@ -16,6 +17,17 @@ class MissingWranglerConfigError extends CanopyError {
 const isDeployedWorker = () => {
   return process.env.NODE_ENV === "production" && process.env.BUILD_ENV !== "build" && process.env.NEXT_PHASE !== "phase-production-build";
 };
+function isSiteKV(value) {
+  return typeof value === "object" && value !== null && "get" in value && typeof value.get === "function";
+}
+const getSiteKV = async () => {
+  if (globalThis.navigator?.userAgent !== "Cloudflare-Workers") {
+    return null;
+  }
+  const { env } = await getCloudflareContext({ async: true });
+  const binding = Reflect.get(env, SITE_KV_BINDING);
+  return isSiteKV(binding) ? binding : null;
+};
 const getEnv = async () => {
   if (isDeployedWorker()) {
     const { env } = await getCloudflareContext({ async: true });
@@ -38,5 +50,6 @@ const getEnv = async () => {
   return wranglerConfigSchema.parse(JSONC.parse(raw)).vars;
 };
 export {
-  getEnv
+  getEnv,
+  getSiteKV
 };

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "branch": "HEAD",
-  "commit": "65e727be083f9c9b51cc9aa247d471777050f32c",
-  "builtAt": "2026-10-26T23:28:14.346Z"
+  "commit": "a6f8205ab3f0f29d31f2c5f4301a1f9fd81c179f",
+  "builtAt": "2026-10-28T03:16:19.137Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "2.10.1",
+    "version": "2.11.0",
     "branch": "HEAD",
-    "commit": "65e727be083f9c9b51cc9aa247d471777050f32c",
-    "builtAt": "2026-10-26T23:28:14.346Z"
+    "commit": "a6f8205ab3f0f29d31f2c5f4301a1f9fd81c179f",
+    "builtAt": "2026-10-28T03:16:19.137Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",
@@ -313,6 +313,10 @@
       "types": "./routing/visitor-id.d.ts",
       "default": "./routing/visitor-id.js"
     },
+    "./routing/live-experiments": {
+      "types": "./routing/live-experiments.d.ts",
+      "default": "./routing/live-experiments.js"
+    },
     "./_vendor/schemas/loaderKeys": {
       "types": "./_vendor/schemas/loaderKeys.d.ts",
       "default": "./_vendor/schemas/loaderKeys.mjs"

package/routing/evaluate.d.ts

@@ -1,9 +1,37 @@
 import type { NextRequest } from "next/server";
 import type { LocaleRoutingConfig } from "../_vendor/schemas/routing/locale";
 import type { RedirectRule } from "../_vendor/schemas/routing/rules";
+import type { RequiredConsent } from "../consent/cookie";
 import { NextResponse } from "next/server";
-export declare function evaluateRouting({ request, rules, localeRouting, }: {
+/**
+ * Routes a request in the site's `middleware.ts`: redirect rules first, then
+ * experiments, then locale routing.
+ *
+ * Pass the site's imported `experiments.json` through `liveExperiments` as
+ * `experiments`, so experiments start and stop without a publish; Replo's
+ * publish generates the file from the site's experiments. On a running
+ * experiment's route, each visitor is bucketed by a hash of their
+ * `replo_visitor_id` cookie, so they see the same variant on every visit, and
+ * the request is rewritten to their variant's page while the address bar keeps
+ * the shared URL. The assignment is recorded in the `replo_experiments` cookie
+ * for the analytics pixel and kept for the browser session, even if the
+ * rollout percentages change, and each counted visit sets a short-lived
+ * `replo_experiment_exposure` cookie that the pixel turns into a
+ * `replo.experiment_exposure` event. `?experiment=<experiment key>:<variant key>`
+ * pins a variant for QA for the browser session; pinned visits are left out of
+ * results. A stopped
+ * experiment with a shipped variant sends every visitor to that page. A
+ * challenger page under `/v/` is served with `X-Robots-Tag: noindex`. An
+ * invalid `experiments.json` is ignored, so every page renders as if no
+ * experiment existed.
+ *
+ * With an `experimentConsent` category, a visitor who hasn't granted it in
+ * Replo's consent banner sees the control and gets no experiment cookies.
+ */
+export declare function evaluateRouting({ request, rules, localeRouting, experiments, experimentConsent, }: {
     request: NextRequest;
     rules: readonly RedirectRule[];
     localeRouting?: LocaleRoutingConfig;
+    experiments?: unknown;
+    experimentConsent?: RequiredConsent;
 }): NextResponse;

package/routing/evaluate.js

@@ -7,20 +7,39 @@ import {
   withLocalePrefix
 } from "../_vendor/schemas/routing/localeNegotiation.mjs";
 import { applyParams, matchSource } from "../_vendor/schemas/routing/match.mjs";
+import { applyExperimentDecision, decideExperiment } from "./experiments";
 import { ipCountry } from "./geo";
 function evaluateRouting({
   request,
   rules,
-  localeRouting
+  localeRouting,
+  experiments,
+  experimentConsent = null
 }) {
   const localeContext = localeRouting ? getLocaleContext({ request, config: localeRouting }) : null;
   for (const rule of rules) {
-    const response = evaluateRedirect({ request, rule, localeContext });
-    if (response) {
-      return response;
+    const response2 = evaluateRedirect({ request, rule, localeContext });
+    if (response2) {
+      return response2;
     }
   }
-  return evaluateLocalePhase({ request, localeContext });
+  const experimentDecision = experiments === void 0 || isLocaleExemptPath(request.nextUrl.pathname) ? null : decideExperiment({
+    request,
+    experiments,
+    logicalPath: localeContext?.pathLocale?.logicalPath ?? request.nextUrl.pathname,
+    requiredConsent: experimentConsent
+  });
+  const response = evaluateLocalePhase({
+    request,
+    localeContext,
+    servedPath: experimentDecision?.servedPath ?? null
+  });
+  return experimentDecision ? applyExperimentDecision({
+    request,
+    response,
+    decision: experimentDecision,
+    requiredConsent: experimentConsent
+  }) : response;
 }
 function getLocaleContext({
   request,
@@ -114,10 +133,11 @@ function applyLocaleToDestination({
 }
 function evaluateLocalePhase({
   request,
-  localeContext
+  localeContext,
+  servedPath
 }) {
   if (!localeContext) {
-    return NextResponse.next();
+    return servedPath === null ? NextResponse.next() : rewriteTo({ request, pathname: servedPath });
   }
   const { pathname } = request.nextUrl;
   if (isLocaleExemptPath(pathname)) {
@@ -126,42 +146,57 @@ function evaluateLocalePhase({
   const { urlMode, pathLocale, negotiated, scope, config } = localeContext;
   if (urlMode === "prefixed") {
     if (!pathLocale) {
-      const url2 = request.nextUrl.clone();
-      url2.pathname = withLocalePrefix({
+      const url = request.nextUrl.clone();
+      url.pathname = withLocalePrefix({
         locale: negotiated.locale,
         path: pathname
       });
-      return NextResponse.redirect(url2, 307);
+      return NextResponse.redirect(url, 307);
     }
     const canonicalPath = canonicalPrefixedPathname({
       pathLocale,
       locales: config.locales
     });
     if (canonicalPath !== pathname) {
-      const url2 = request.nextUrl.clone();
-      url2.pathname = canonicalPath;
-      return NextResponse.redirect(url2, 308);
+      const url = request.nextUrl.clone();
+      url.pathname = canonicalPath;
+      return NextResponse.redirect(url, 308);
     }
-    const response = NextResponse.next();
+    const response = servedPath === null ? NextResponse.next() : rewriteTo({
+      request,
+      pathname: withLocalePrefix({
+        locale: pathLocale.locale,
+        path: servedPath
+      })
+    });
     if (pathLocale.locale !== negotiated.locale && request.cookies.get(REPLO_LOCALE_COOKIE)?.value !== pathLocale.locale && scope.locales.includes(pathLocale.locale)) {
       setLocaleCookie({ response, locale: pathLocale.locale });
     }
     return response;
   }
   if (pathLocale) {
-    const url2 = request.nextUrl.clone();
-    url2.pathname = pathLocale.logicalPath;
-    const response = NextResponse.redirect(url2, 307);
+    const url = request.nextUrl.clone();
+    url.pathname = pathLocale.logicalPath;
+    const response = NextResponse.redirect(url, 307);
     if (scope.locales.includes(pathLocale.locale)) {
       setLocaleCookie({ response, locale: pathLocale.locale });
     }
     return response;
   }
-  const url = request.nextUrl.clone();
-  url.pathname = withLocalePrefix({
-    locale: negotiated.locale,
-    path: pathname
+  return rewriteTo({
+    request,
+    pathname: withLocalePrefix({
+      locale: negotiated.locale,
+      path: servedPath ?? pathname
+    })
   });
+}
+function rewriteTo({
+  request,
+  pathname
+}) {
+  const url = request.nextUrl.clone();
+  url.pathname = pathname;
   return NextResponse.rewrite(url);
 }
 function canonicalPrefixedPathname({

package/routing/experiments.d.ts

@@ -0,0 +1,35 @@
+import type { NextRequest, NextResponse } from "next/server";
+import type { ExperimentAssignments } from "../_vendor/schemas/routing/experimentCookie";
+import type { RequiredConsent } from "../consent/cookie";
+/** The experiment phase's decision; `servedPath` is the locale-free route to render instead, or null for the requested page. */
+export type ExperimentDecision = {
+    type: "assigned";
+    servedPath: string | null;
+    visitorId: string;
+    assignments: ExperimentAssignments;
+    /** `experimentKey:variantKey` of the counted exposure this response is; null for a pinned QA visit. */
+    exposure: string | null;
+} | {
+    type: "shippedVariant";
+    servedPath: string | null;
+} | {
+    type: "variantRoute";
+    servedPath: null;
+} | {
+    type: "consentWithdrawn";
+    servedPath: null;
+};
+/** The variant to serve on an experiment's route; null when none applies, including for an invalid file, so it never takes the site down. */
+export declare function decideExperiment({ request, experiments: rawExperiments, logicalPath, requiredConsent, }: {
+    request: NextRequest;
+    experiments: unknown;
+    logicalPath: string;
+    requiredConsent: RequiredConsent;
+}): ExperimentDecision | null;
+/** Stamps the decision onto the routed response; redirects are left alone, since the rendering request buckets. */
+export declare function applyExperimentDecision({ request, response, decision, requiredConsent, }: {
+    request: NextRequest;
+    response: NextResponse;
+    decision: ExperimentDecision;
+    requiredConsent: RequiredConsent;
+}): NextResponse;

package/routing/experiments.js

@@ -0,0 +1,215 @@
+import {
+  EXPERIMENT_EXPOSURE_COOKIE,
+  EXPERIMENT_OVERRIDE_PARAM,
+  EXPERIMENTS_COOKIE,
+  parseExperimentCookie,
+  parseExperimentOverride,
+  serializeExperimentCookie,
+  VISITOR_ID_COOKIE
+} from "../_vendor/schemas/routing/experimentCookie.mjs";
+import {
+  assignVariant,
+  experimentsFileSchema,
+  findActiveExperiment,
+  findServedVariants,
+  isRoutingExperiment,
+  normalizeRoute
+} from "../_vendor/schemas/routing/experiments.mjs";
+import { isConsentGranted } from "../consent/cookie";
+import { ensureVisitorId } from "./visitor-id";
+const parsedFiles = /* @__PURE__ */ new WeakMap();
+function decideExperiment({
+  request,
+  experiments: rawExperiments,
+  logicalPath,
+  requiredConsent
+}) {
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    return null;
+  }
+  const experiments = parseExperiments(rawExperiments);
+  if (!experiments) {
+    return null;
+  }
+  const isPreview = process.env.NODE_ENV === "development";
+  if (isPreview && !request.nextUrl.searchParams.has(EXPERIMENT_OVERRIDE_PARAM)) {
+    return null;
+  }
+  const experiment = findActiveExperiment({
+    experiments,
+    pathname: logicalPath
+  });
+  if (!experiment) {
+    return logicalPath.startsWith("/v/") && isChallengerRoute({ experiments, logicalPath }) ? { type: "variantRoute", servedPath: null } : null;
+  }
+  if (experiment.status === "stopped") {
+    const shippedVariant = experiment.variants.find((variant2) => {
+      return variant2.variantKey === experiment.shippedVariantKey;
+    });
+    return shippedVariant ? {
+      type: "shippedVariant",
+      servedPath: servedPathFor({ variant: shippedVariant, logicalPath })
+    } : null;
+  }
+  if (!isConsentGranted({ cookies: request.cookies, requiredConsent })) {
+    return request.cookies.has(EXPERIMENTS_COOKIE) || request.cookies.has(EXPERIMENT_EXPOSURE_COOKIE) ? { type: "consentWithdrawn", servedPath: null } : null;
+  }
+  const existingVisitorId = request.cookies.get(VISITOR_ID_COOKIE)?.value;
+  const visitorId = existingVisitorId ? existingVisitorId : crypto.randomUUID();
+  const existing = isPreview ? {} : parseExperimentCookie(request.cookies.get(EXPERIMENTS_COOKIE)?.value);
+  const override = readOverride({ request, experiment });
+  const stored = existing[experiment.experimentKey];
+  const pinnedKey = stored?.forced ? stored.variantKey : null;
+  const forcedKey = override === void 0 ? pinnedKey : override;
+  const forcedVariant = experiment.variants.find((variant2) => variant2.variantKey === forcedKey) ?? null;
+  const keptVariant = stored && !stored.forced && override === void 0 ? experiment.variants.find((candidate) => {
+    return candidate.variantKey === stored.variantKey;
+  }) : void 0;
+  const variant = forcedVariant ?? keptVariant ?? assignVariant({ visitorId, experiment });
+  return {
+    type: "assigned",
+    servedPath: servedPathFor({ variant, logicalPath }),
+    visitorId,
+    assignments: {
+      ...keepRunningAssignments({ experiments, assignments: existing }),
+      [experiment.experimentKey]: {
+        variantKey: variant.variantKey,
+        forced: Boolean(forcedVariant)
+      }
+    },
+    exposure: forcedVariant ? null : `${experiment.experimentKey}:${variant.variantKey}`
+  };
+}
+function applyExperimentDecision({
+  request,
+  response,
+  decision,
+  requiredConsent
+}) {
+  if (response.status >= 300 && response.status < 400) {
+    return response;
+  }
+  if (decision.type === "variantRoute") {
+    response.headers.set("X-Robots-Tag", "noindex");
+    return response;
+  }
+  if (decision.type === "shippedVariant") {
+    return response;
+  }
+  if (decision.type === "consentWithdrawn") {
+    response.cookies.delete(EXPERIMENTS_COOKIE);
+    response.cookies.delete(EXPERIMENT_EXPOSURE_COOKIE);
+    return response;
+  }
+  const value = serializeExperimentCookie(decision.assignments);
+  if (value !== request.cookies.get(EXPERIMENTS_COOKIE)?.value) {
+    response.cookies.set({
+      name: EXPERIMENTS_COOKIE,
+      value,
+      path: "/",
+      sameSite: "lax",
+      secure: request.nextUrl.protocol === "https:",
+      httpOnly: false
+    });
+  }
+  if (decision.exposure !== null) {
+    response.cookies.set({
+      name: EXPERIMENT_EXPOSURE_COOKIE,
+      value: decision.exposure,
+      path: "/",
+      sameSite: "lax",
+      secure: request.nextUrl.protocol === "https:",
+      httpOnly: false,
+      maxAge: 60
+    });
+  }
+  ensureVisitorId({
+    request,
+    response,
+    cookieName: VISITOR_ID_COOKIE,
+    cookieDomain: null,
+    requiredConsent,
+    visitorId: decision.visitorId
+  });
+  response.headers.set("Cache-Control", "private, no-store");
+  return response;
+}
+function parseExperiments(rawExperiments) {
+  const isObject = typeof rawExperiments === "object" && rawExperiments !== null;
+  if (isObject && parsedFiles.has(rawExperiments)) {
+    return parsedFiles.get(rawExperiments) ?? null;
+  }
+  const parsed = experimentsFileSchema.safeParse(rawExperiments);
+  const experiments = parsed.success ? withLivePagesOnly({
+    experiments: parsed.data.experiments,
+    liveRoutes: parsed.data.liveRoutes
+  }) : null;
+  if (isObject) {
+    parsedFiles.set(rawExperiments, experiments);
+  }
+  return experiments;
+}
+function withLivePagesOnly({
+  experiments,
+  liveRoutes
+}) {
+  if (!liveRoutes) {
+    return experiments;
+  }
+  const live = new Set(liveRoutes.map(normalizeRoute));
+  return experiments.filter((experiment) => {
+    return findServedVariants(experiment).every((variant) => {
+      return live.has(normalizeRoute(variant.route));
+    });
+  });
+}
+function readOverride({
+  request,
+  experiment
+}) {
+  const value = request.nextUrl.searchParams.get(EXPERIMENT_OVERRIDE_PARAM);
+  if (value === null) {
+    return void 0;
+  }
+  const override = parseExperimentOverride(value);
+  if (override && override.experimentKey !== experiment.experimentKey) {
+    return void 0;
+  }
+  return override?.variantKey ?? null;
+}
+function keepRunningAssignments({
+  experiments,
+  assignments
+}) {
+  const runningKeys = new Set(
+    experiments.filter((experiment) => experiment.status === "running").map((experiment) => experiment.experimentKey)
+  );
+  const kept = {};
+  for (const [experimentKey, assignment] of Object.entries(assignments)) {
+    if (runningKeys.has(experimentKey)) {
+      kept[experimentKey] = assignment;
+    }
+  }
+  return kept;
+}
+function isChallengerRoute({
+  experiments,
+  logicalPath
+}) {
+  const route = normalizeRoute(logicalPath);
+  return experiments.filter(isRoutingExperiment).some((experiment) => {
+    return experiment.variants.slice(1).some((variant) => {
+      return normalizeRoute(variant.route) === route;
+    });
+  });
+}
+function servedPathFor({
+  variant,
+  logicalPath
+}) {
+  return normalizeRoute(variant.route) === normalizeRoute(logicalPath) ? null : variant.route;
+}
+export {
+  applyExperimentDecision,
+  decideExperiment
+};

package/routing/live-experiments.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Returns the site's experiment routing as it is in Replo right now, so
+ * launching, ending or re-splitting an experiment reaches visitors without a
+ * publish. Pass the site's imported `experiments.json` and hand the result to
+ * `evaluateRouting` as `experiments`.
+ *
+ * On a published site the routing is read from the site's own KV store and
+ * kept in memory for 30 seconds; the first request after that rereads it,
+ * waiting up to 800ms before using the copy it has. The first request in a
+ * fresh worker waits the same way, and if the store can't be read, no experiment
+ * runs and every visitor gets the original page. In local development and the Site Builder preview, which
+ * have no store, the imported file is used as is, so `?experiment=` previews work.
+ * Either way, only pages listed in the file's `liveRoutes` are ever served,
+ * so an experiment never sends a visitor to a page this build doesn't have.
+ */
+export declare function liveExperiments(experiments: unknown): Promise<unknown>;

package/routing/live-experiments.js

@@ -0,0 +1,59 @@
+import {
+  experimentsFileSchema,
+  SITE_KV_EXPERIMENTS_KEY
+} from "../_vendor/schemas/routing/experiments.mjs";
+import { getSiteKV } from "../env";
+const REFRESH_AFTER_MS = 3e4;
+const KV_CACHE_TTL_SECONDS = 60;
+const READ_TIMEOUT_MS = 800;
+const RETRY_AFTER_MS = 5e3;
+let cache = null;
+async function liveExperiments(experiments) {
+  const bundled = experimentsFileSchema.safeParse(experiments);
+  if (!bundled.success) {
+    return experiments;
+  }
+  const kv = await getSiteKV().catch(() => null);
+  if (!kv) {
+    return experiments;
+  }
+  const { experiments: _bundledExperiments, ...build } = bundled.data;
+  const now = Date.now();
+  if (cache) {
+    const isStale = now - cache.fetchedAt > REFRESH_AFTER_MS;
+    const isRefreshing = cache.refreshStartedAt !== null && now - cache.refreshStartedAt < RETRY_AFTER_MS;
+    if (!isStale || isRefreshing) {
+      return cache.value;
+    }
+    const stale = cache.value;
+    cache.refreshStartedAt = now;
+    return await readWithinTimeout({ kv, build }) ?? stale;
+  }
+  const noTests = { ...build, experiments: [] };
+  cache = { value: noTests, fetchedAt: 0, refreshStartedAt: now };
+  return await readWithinTimeout({ kv, build }) ?? noTests;
+}
+function readWithinTimeout(args) {
+  return Promise.race([
+    refresh(args).catch(() => null),
+    new Promise((resolve) => {
+      setTimeout(() => resolve(null), READ_TIMEOUT_MS);
+    })
+  ]);
+}
+async function refresh({
+  kv,
+  build
+}) {
+  const stored = await kv.get(SITE_KV_EXPERIMENTS_KEY, {
+    type: "json",
+    cacheTtl: KV_CACHE_TTL_SECONDS
+  });
+  const experiments = stored === null ? [] : experimentsFileSchema.parse(stored).experiments;
+  const value = { ...build, experiments };
+  cache = { value, fetchedAt: Date.now(), refreshStartedAt: null };
+  return value;
+}
+export {
+  liveExperiments
+};

package/routing/visitor-id.d.ts

@@ -1,5 +1,5 @@
 import type { NextRequest, NextResponse } from "next/server";
-import type { ConsentCategory } from "../consent/types";
+import type { RequiredConsent } from "../consent/cookie";
 /**
  * Gives a first-time visitor a durable visitor ID (a UUID) in the `cookieName`
  * cookie, so experiments bucket every page view of theirs the same way. Call it
@@ -16,13 +16,17 @@ import type { ConsentCategory } from "../consent/types";
  * With a `requiredConsent` category, the ID is only created once the visitor
  * has granted that category in Replo's consent banner. Pass `null` when the
  * site needs no consent for it.
+ *
+ * Pass `visitorId` when the middleware already bucketed this request with a
+ * freshly generated ID, so the cookie stores the ID the response was built for.
  */
-export declare function ensureVisitorId({ request, response, cookieName, cookieDomain, requiredConsent, }: {
+export declare function ensureVisitorId({ request, response, cookieName, cookieDomain, requiredConsent, visitorId, }: {
     request: NextRequest;
     response: NextResponse;
     cookieName: string;
     cookieDomain: string | null;
-    requiredConsent: VisitorIdConsent;
+    requiredConsent: RequiredConsent;
+    visitorId?: string;
 }): NextResponse;
 /**
  * Reads the visitor ID for an experiment evaluation, or `null` when the
@@ -34,8 +38,7 @@ export declare function ensureVisitorId({ request, response, cookieName, cookieD
 export declare function findVisitorId({ cookies, cookieName, requiredConsent, }: {
     cookies: VisitorIdCookies;
     cookieName: string;
-    requiredConsent: VisitorIdConsent;
+    requiredConsent: RequiredConsent;
 }): string | null;
 type VisitorIdCookies = Pick<NextRequest["cookies"], "get">;
-type VisitorIdConsent = Exclude<ConsentCategory, "necessary"> | null;
 export {};

package/routing/visitor-id.js

@@ -1,4 +1,4 @@
-import { CONSENT_COOKIE_NAME, parseConsentCookie } from "../consent/cookie";
+import { isConsentGranted } from "../consent/cookie";
 const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
 const SHARED_REPLO_DOMAINS = /* @__PURE__ */ new Set([
   "reploshops.com",
@@ -22,7 +22,8 @@ function ensureVisitorId({
   response,
   cookieName,
   cookieDomain,
-  requiredConsent
+  requiredConsent,
+  visitorId = crypto.randomUUID()
 }) {
   const isRedirect = response.status >= 300 && response.status < 400;
   const isAlreadySet = response.headers.getSetCookie().some((setCookie) => {
@@ -40,7 +41,7 @@ function ensureVisitorId({
   });
   response.cookies.set({
     name: cookieName,
-    value: crypto.randomUUID(),
+    value: visitorId,
     path: "/",
     maxAge: ONE_YEAR_SECONDS,
     sameSite: "lax",
@@ -65,16 +66,6 @@ function findVisitorId({
   }
   return visitorId;
 }
-function isConsentGranted({
-  cookies,
-  requiredConsent
-}) {
-  if (requiredConsent === null) {
-    return true;
-  }
-  const consent = parseConsentCookie(cookies.get(CONSENT_COOKIE_NAME)?.value);
-  return consent?.categories[requiredConsent] ?? false;
-}
 function findCookieDomain({
   hostname,
   cookieDomain