@drip-apex/sdk 0.1.0

package/src/shopify-cart.ts

@@ -0,0 +1,1256 @@
+import { fetchWithoutShopifyCartMutationNotification } from "./shopify-cart-events";
+
+const CART_ATTRIBUTE_SYNC_KEY = "drip_cart_attr";
+
+export type CartAssignment = {
+  experimentId: string;
+  variationId: string;
+  assignmentEpoch?: number;
+  commercePriceOnly?: boolean;
+};
+
+export type CartAttributeSyncInput = {
+  assignments: CartAssignment[];
+  requiredAssignments?: CartAssignment[];
+  visitorId: string;
+  sessionId: string;
+  shopId?: string;
+  endpoint?: string;
+  ingestSignature?: string;
+  url?: string;
+  environment?: string;
+  cartToken?: string;
+  offersAuthorizationRevision?: number;
+  offersExperimentIds?: string[];
+  shippingAuthorizationRevision?: number;
+  shippingExperimentIds?: string[];
+  priceAuthorizationRevision?: number;
+  priceExperimentIds?: string[];
+  adoptOffersAssignments?: (assignments: CartAssignment[]) => boolean;
+  /** Pre-write feasibility check; must not apply anything. */
+  canAdoptOffersAssignments?: (assignments: CartAssignment[]) => boolean;
+  /** Headless capture hook: stage a validated offers adoption for {@link confirmCartAttributesWritten}. */
+  stageOffersAdoptionAssignments?: (assignments: CartAssignment[]) => void;
+  adoptPriceAssignments?: (assignments: CartAssignment[]) => boolean;
+  authorizePriceDisplayAssignments?: (assignments: CartAssignment[]) => void;
+  authorizeShippingDisplayAssignments?: (assignments: CartAssignment[]) => void;
+  authorizeOffersDisplayAssignments?: (assignments: CartAssignment[]) => void;
+  /** Receives the parsed /cart/update.js response body after a successful stamp write. */
+  onCartSnapshot?: (cart: unknown) => void;
+  exclusionGroupSelections?: Array<{
+    groupId: string;
+    experimentId: string;
+    epoch: number;
+  }>;
+};
+
+export type CartAttributeEntry = { key: string; value: string };
+
+export type CartAttributeSyncResult = {
+  status: "sent" | "skipped" | "failed";
+  reason?: string;
+};
+
+export type CartAttributeSyncOptions = {
+  /** Re-write after a real cart mutation even if this assignment was stamped earlier. */
+  force?: boolean;
+};
+
+const inFlightBySignature = new Map<string, Promise<CartAttributeSyncResult>>();
+const validatedAuthorizationSignatures = new Set<string>();
+let authorizedAssignmentsBySignature: {
+  price: Map<string, CartAssignment[]>;
+  shipping: Map<string, CartAssignment[]>;
+  offers: Map<string, CartAssignment[]>;
+} | null = null;
+let latestSyncGeneration = 0;
+
+/** Prevent an obsolete authorization response from reaching the cart write. */
+export function invalidateShopifyCartAttributeSync(): void {
+  latestSyncGeneration += 1;
+}
+
+function ensureAuthorizedAssignmentCache() {
+  return authorizedAssignmentsBySignature ??= {
+    price: new Map<string, CartAssignment[]>(),
+    shipping: new Map<string, CartAssignment[]>(),
+    offers: new Map<string, CartAssignment[]>(),
+  };
+}
+
+function requiresCommerceAuthorization(input: CartAttributeSyncInput): boolean {
+  return !!input.requiredAssignments?.length
+    || input.offersAuthorizationRevision != null
+    || input.shippingAuthorizationRevision != null
+    || input.priceAuthorizationRevision != null;
+}
+
+function hasActivePriceAuthorizationPlane(input: CartAttributeSyncInput): boolean {
+  return input.priceAuthorizationRevision != null && !!input.priceExperimentIds?.length;
+}
+
+function hasActiveOffersAuthorizationPlane(input: CartAttributeSyncInput): boolean {
+  return input.offersAuthorizationRevision != null && !!input.offersExperimentIds?.length;
+}
+
+function offersExperimentIds(input: CartAttributeSyncInput): Set<string> {
+  return new Set(input.offersExperimentIds ?? []);
+}
+
+function shippingExperimentIds(input: CartAttributeSyncInput): Set<string> {
+  if (input.shippingExperimentIds?.length) return new Set(input.shippingExperimentIds);
+  const priceExperimentIds = new Set(input.priceExperimentIds ?? []);
+  return new Set(
+    input.requiredAssignments
+      ?.filter((assignment) => !priceExperimentIds.has(assignment.experimentId))
+      .map((assignment) => assignment.experimentId) ?? [],
+  );
+}
+
+function hasActiveShippingAuthorizationPlane(input: CartAttributeSyncInput): boolean {
+  return input.shippingAuthorizationRevision != null && shippingExperimentIds(input).size > 0;
+}
+
+// Clearing a stale grant is privilege-REDUCING, so shipping- and offers-only
+// shops may clear without a signed token; the price plane always needs one.
+function isUnsignedCommerceClearCandidate(input: CartAttributeSyncInput): boolean {
+  return input.priceAuthorizationRevision == null &&
+    (input.shippingAuthorizationRevision != null ||
+      input.offersAuthorizationRevision != null) &&
+    !input.requiredAssignments?.length;
+}
+
+export function cannotRequestRequiredCommerceAuthorization(
+  input: CartAttributeSyncInput,
+): boolean {
+  return (
+    !!input.assignments[0] ||
+    input.shippingAuthorizationRevision != null ||
+    input.offersAuthorizationRevision != null ||
+    hasActivePriceAuthorizationPlane(input)
+  )
+    && requiresCommerceAuthorization(input)
+    && (!input.shopId || !input.endpoint || !input.ingestSignature);
+}
+
+export function isShopifyStorefront(): boolean {
+  return typeof window !== "undefined" && !!(window as unknown as { Shopify?: unknown }).Shopify;
+}
+
+function readStampedSignature(): string | null {
+  try {
+    return sessionStorage.getItem(CART_ATTRIBUTE_SYNC_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function writeStampedSignature(signature: string): void {
+  try {
+    sessionStorage.setItem(CART_ATTRIBUTE_SYNC_KEY, signature);
+  } catch {
+    // Storage can be unavailable in strict privacy modes; the cart write is still best-effort.
+  }
+}
+
+function normalizeTargetingUrl(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  try {
+    // The Worker evaluates targeting through URL with the same fallback base.
+    // Persist that effective value so equivalent URL spellings share a cache
+    // entry while a meaningful SPA route change requests a fresh price pin.
+    return new URL(trimmed, "https://_").href;
+  } catch {
+    // The Worker still receives invalid-but-non-empty strings and fails their
+    // URL targeting closed, so retain the trimmed value as part of the key.
+    return trimmed;
+  }
+}
+
+function syncSignature(input: CartAttributeSyncInput): string {
+  return JSON.stringify({
+    assignments: input.assignments
+      .map((assignment) => [
+        assignment.experimentId,
+        assignment.variationId,
+        assignment.assignmentEpoch ?? null,
+      ])
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    requiredAssignments: input.requiredAssignments
+      ?.map((assignment) => [
+        assignment.experimentId,
+        assignment.variationId,
+        assignment.assignmentEpoch ?? null,
+      ])
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    visitorId: input.visitorId,
+    sessionId: input.sessionId,
+    url: requiresCommerceAuthorization(input)
+      ? normalizeTargetingUrl(input.url)
+      : undefined,
+    cartToken: normalizeCartToken(input.cartToken),
+    ...(input.offersAuthorizationRevision != null || input.offersExperimentIds?.length
+      ? {
+          offersAuthorizationRevision: input.offersAuthorizationRevision ?? null,
+          offersExperimentIds: input.offersExperimentIds?.slice().sort(),
+        }
+      : {}),
+    shippingAuthorizationRevision: input.shippingAuthorizationRevision ?? null,
+    shippingExperimentIds: input.shippingExperimentIds?.slice().sort(),
+    priceAuthorizationRevision: input.priceAuthorizationRevision ?? null,
+    exclusionGroupSelections: input.exclusionGroupSelections
+      ?.map((selection) => [
+        selection.groupId,
+        selection.experimentId,
+        selection.epoch,
+      ])
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+  });
+}
+
+/** Validated locale-aware storefront root ("/fr/" on localized markets, "/" otherwise). */
+export function shopifyRoutesRoot(): string {
+  const configuredRoot = (window as Window & {
+    Shopify?: { routes?: { root?: string } };
+  }).Shopify?.routes?.root;
+  if (typeof configuredRoot !== "string") return "/";
+  try {
+    const storefrontOrigin = window.location?.origin;
+    if (!storefrontOrigin) return "/";
+    const parsed = new URL(configuredRoot, storefrontOrigin);
+    if (parsed.origin !== storefrontOrigin || parsed.search || parsed.hash) return "/";
+    return parsed.pathname.endsWith("/") ? parsed.pathname : `${parsed.pathname}/`;
+  } catch {
+    return "/";
+  }
+}
+
+export function shopifyCartPath(): string {
+  return `${shopifyRoutesRoot()}cart.js`;
+}
+
+function normalizeCartToken(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const withoutQuery = value.trim().split("?", 1)[0] ?? "";
+  const token = withoutQuery.startsWith("gid://shopify/Cart/")
+    ? withoutQuery.slice("gid://shopify/Cart/".length)
+    : withoutQuery;
+  return token.length > 0 && token.length <= 4096 ? token : null;
+}
+
+function normalizeProofCartToken(value: unknown): string | null {
+  return typeof value === "string" && normalizeCartToken(value) ? value.trim() : null;
+}
+
+async function resolveChargeAuthorizationCartToken(
+  input: CartAttributeSyncInput,
+): Promise<string | null> {
+  const supplied = normalizeProofCartToken(input.cartToken);
+  if (supplied) return supplied;
+  if (
+    input.priceAuthorizationRevision == null &&
+    input.offersAuthorizationRevision == null
+  ) return null;
+  if (!isShopifyStorefront()) return null;
+  try {
+    const response = await fetchWithoutShopifyCartMutationNotification(shopifyCartPath(), {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      cache: "no-store",
+    });
+    if (!response.ok) return null;
+    return normalizeProofCartToken(((await response.json()) as { token?: unknown }).token);
+  } catch {
+    return null;
+  }
+}
+
+export function syncShopifyCartAttributes(
+  input: CartAttributeSyncInput,
+  options: CartAttributeSyncOptions = {},
+): Promise<CartAttributeSyncResult> {
+  try {
+    if (!isShopifyStorefront()) return Promise.resolve({ status: "skipped", reason: "not_shopify" });
+    if (typeof fetch !== "function") return Promise.resolve({ status: "skipped", reason: "fetch_missing" });
+    if (!input.assignments[0] && !requiresCommerceAuthorization(input)) {
+      return Promise.resolve({ status: "skipped", reason: "no_assignments" });
+    }
+    if (cannotRequestRequiredCommerceAuthorization(input)) {
+      return Promise.resolve({ status: "failed", reason: "authorization_failed" });
+    }
+
+    const signature = syncSignature(input);
+    const existingInFlight = inFlightBySignature.get(signature);
+    if (existingInFlight) {
+      if (!options.force) return existingInFlight;
+      // A forced sync follows a real cart mutation, so cart identity may have
+      // changed underneath the pending request. Invalidate it immediately;
+      // ordinary overlaps still share the existing request.
+      latestSyncGeneration += 1;
+      return existingInFlight.then(() => syncShopifyCartAttributes(input, options));
+    }
+    const generation = ++latestSyncGeneration;
+    const requiresCurrentAssignmentProof = requiresCommerceAuthorization(input);
+    if (
+      !options.force &&
+      readStampedSignature() === signature &&
+      (!requiresCurrentAssignmentProof || validatedAuthorizationSignatures.has(signature))
+    ) {
+      if (hasActivePriceAuthorizationPlane(input)) {
+        input.authorizePriceDisplayAssignments?.(
+          authorizedAssignmentsBySignature?.price.get(signature) ?? [],
+        );
+      }
+      if (hasActiveShippingAuthorizationPlane(input)) {
+        input.authorizeShippingDisplayAssignments?.(
+          authorizedAssignmentsBySignature?.shipping.get(signature) ?? [],
+        );
+      }
+      if (hasActiveOffersAuthorizationPlane(input)) {
+        input.authorizeOffersDisplayAssignments?.(
+          authorizedAssignmentsBySignature?.offers.get(signature) ?? [],
+        );
+      }
+      return Promise.resolve({ status: "sent", reason: "already_stamped" });
+    }
+
+    if (requiresCurrentAssignmentProof) validatedAuthorizationSignatures.delete(signature);
+    let authorizedSignature = signature;
+    const pending = requestCommerceAuthorization(input, generation)
+      .then(async ({
+        completed,
+        cartWriteAllowed,
+        token,
+        assignments,
+        offersAdoptionAssignments,
+      }): Promise<{
+        response: Response | null;
+        authorizationCompleted: boolean;
+        authorizedSignature: string;
+        authorizedPriceAssignments: CartAssignment[];
+        authorizedShippingAssignments: CartAssignment[];
+        authorizedOffersAssignments: CartAssignment[];
+        offersAdoptionAssignments?: CartAssignment[];
+      }> => {
+        if (!cartWriteAllowed || generation !== latestSyncGeneration) {
+          return {
+            response: null,
+            authorizationCompleted: false,
+            authorizedSignature,
+            authorizedPriceAssignments: [],
+            authorizedShippingAssignments: [],
+            authorizedOffersAssignments: [],
+          };
+        }
+        const authorizedInput = { ...input, assignments };
+        authorizedSignature = syncSignature(authorizedInput);
+        const authorizedPriceAssignments = hasActivePriceAuthorizationPlane(input)
+          ? parseSignedPriceAuthorizationAssignments(
+              token,
+              new Set(input.priceExperimentIds ?? []),
+            ) ?? []
+          : [];
+        const authorizedShippingAssignments = hasActiveShippingAuthorizationPlane(input)
+          ? parseSignedShippingAuthorizationAssignments(
+              token,
+              shippingExperimentIds(input),
+            ) ?? []
+          : [];
+        const authorizedOffersAssignments = hasActiveOffersAuthorizationPlane(input)
+          ? parseSignedOffersAuthorizationAssignments(
+              token,
+              offersExperimentIds(input),
+            ) ?? []
+          : [];
+        const attributes = Object.fromEntries(
+          buildCartAttributeEntries(authorizedInput, token).map((entry) => [entry.key, entry.value]),
+        );
+        const response = await fetchWithoutShopifyCartMutationNotification("/cart/update.js", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ attributes }),
+          keepalive: true,
+        });
+        return {
+          response,
+          authorizationCompleted: completed,
+          authorizedSignature,
+          authorizedPriceAssignments,
+          authorizedShippingAssignments,
+          authorizedOffersAssignments,
+          offersAdoptionAssignments,
+        };
+      })
+      .then(({
+        response,
+        authorizationCompleted,
+        authorizedSignature: completedSignature,
+        authorizedPriceAssignments,
+        authorizedShippingAssignments,
+        authorizedOffersAssignments,
+        offersAdoptionAssignments,
+      }) => {
+        if (!authorizationCompleted) {
+          return { status: "failed", reason: "authorization_failed" } as const;
+        }
+        if (!response) {
+          return { status: "failed", reason: "cart_update_missing" } as const;
+        }
+        if (!response.ok) {
+          return { status: "failed", reason: `cart_update_${response.status}` } as const;
+        }
+        if (generation === latestSyncGeneration) {
+          // The stamp is on the cart; only now may the adopted offer arm reach
+          // display/persist/tracking. On failure, skip the signature records so
+          // the next sync re-reconciles instead of treating this cart as done.
+          if (
+            offersAdoptionAssignments &&
+            !input.adoptOffersAssignments?.(offersAdoptionAssignments)
+          ) {
+            return { status: "failed", reason: "offers_adoption_failed" } as const;
+          }
+          if (input.onCartSnapshot) {
+            // The stamp-write response body is the full updated cart — a free
+            // snapshot consumers use to rediscover Apex-managed lines without
+            // an extra request (best-effort; never blocks the sync result).
+            // Handed out only for the accepted generation AND after a required
+            // adoption succeeded: reconciling against local assignments the
+            // stamped envelope does not authorize could retain or insert a
+            // gift the Function will not discount.
+            void response.clone().json()
+              .then((cart) => input.onCartSnapshot?.(cart))
+              .catch(() => {});
+          }
+          writeStampedSignature(completedSignature);
+          if (requiresCurrentAssignmentProof) {
+            validatedAuthorizationSignatures.clear();
+            validatedAuthorizationSignatures.add(completedSignature);
+          }
+          if (hasActivePriceAuthorizationPlane(input)) {
+            const cache = ensureAuthorizedAssignmentCache().price;
+            cache.clear();
+            cache.set(
+              completedSignature,
+              authorizedPriceAssignments,
+            );
+            input.authorizePriceDisplayAssignments?.(authorizedPriceAssignments);
+          }
+          if (hasActiveShippingAuthorizationPlane(input)) {
+            const cache = ensureAuthorizedAssignmentCache().shipping;
+            cache.clear();
+            cache.set(
+              completedSignature,
+              authorizedShippingAssignments,
+            );
+            input.authorizeShippingDisplayAssignments?.(authorizedShippingAssignments);
+          }
+          if (hasActiveOffersAuthorizationPlane(input)) {
+            const cache = ensureAuthorizedAssignmentCache().offers;
+            cache.clear();
+            cache.set(
+              completedSignature,
+              authorizedOffersAssignments,
+            );
+            input.authorizeOffersDisplayAssignments?.(authorizedOffersAssignments);
+          }
+        }
+        return { status: "sent" } as const;
+      })
+      .catch((error) => ({
+        status: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+      }) as const)
+      .finally(() => {
+        if (inFlightBySignature.get(signature) === pending) {
+          inFlightBySignature.delete(signature);
+        }
+      });
+    inFlightBySignature.set(signature, pending);
+    return pending;
+  } catch {
+    // Shopify cart attribution must never block or break assignment rendering.
+    return Promise.resolve({ status: "failed", reason: "sync_exception" });
+  }
+}
+
+async function requestCommerceAuthorization(
+  input: CartAttributeSyncInput,
+  generation?: number,
+): Promise<{
+  completed: boolean;
+  cartWriteAllowed: boolean;
+  token: string | null;
+  assignments: CartAssignment[];
+  /** Adoption validated pre-write; the caller applies it only after the cart write is confirmed. */
+  offersAdoptionAssignments?: CartAssignment[];
+}> {
+  const priceWriteRequiresProof = hasActivePriceAuthorizationPlane(input);
+  const offersWriteRequiresProof = hasActiveOffersAuthorizationPlane(input);
+  const configuredOffersExperimentIds = offersExperimentIds(input);
+  const enforceOffersPlaneProof = input.offersAuthorizationRevision != null;
+  let requiredOffersAssignments = enforceOffersPlaneProof
+    ? input.requiredAssignments?.filter((assignment) =>
+        configuredOffersExperimentIds.has(assignment.experimentId)
+      ) ?? []
+    : [];
+  const configuredShippingExperimentIds = shippingExperimentIds(input);
+  const enforceShippingPlaneProof = input.shippingAuthorizationRevision != null &&
+    (!!input.shippingExperimentIds?.length || hasActivePriceAuthorizationPlane(input));
+  const requiredShippingAssignments = enforceShippingPlaneProof
+    ? input.requiredAssignments?.filter((assignment) =>
+        configuredShippingExperimentIds.has(assignment.experimentId)
+      ) ?? []
+    : [];
+  let hasAuthoritativePriceProof = false;
+  if (
+    !input.assignments[0] &&
+    input.shippingAuthorizationRevision == null &&
+    input.offersAuthorizationRevision == null &&
+    !hasActivePriceAuthorizationPlane(input)
+  ) {
+    return {
+      completed: true,
+      cartWriteAllowed: true,
+      token: null,
+      assignments: input.assignments,
+    };
+  }
+  if (!input.shopId || !input.endpoint || !input.ingestSignature) {
+    return {
+      completed: !requiresCommerceAuthorization(input),
+      cartWriteAllowed: true,
+      token: null,
+      assignments: input.assignments,
+    };
+  }
+  const endpoint = input.endpoint.replace(/\/+$/, "").replace(/\/events$/, "");
+  try {
+    const cartToken = await resolveChargeAuthorizationCartToken(input);
+    if (
+      (input.priceAuthorizationRevision != null ||
+        input.offersAuthorizationRevision != null) &&
+      !cartToken
+    ) {
+      return {
+        completed: false,
+        cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+        token: null,
+        assignments: input.assignments,
+      };
+    }
+    const requestedExperimentIds = [...new Set([
+      ...input.assignments.map((assignment) => assignment.experimentId),
+      ...(hasActivePriceAuthorizationPlane(input) ? input.priceExperimentIds ?? [] : []),
+      ...(hasActiveOffersAuthorizationPlane(input) ? input.offersExperimentIds ?? [] : []),
+    ])];
+    const response = await fetch(`${endpoint}/v1/assign`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Drip-Shop": input.shopId,
+        "X-Drip-Signature": input.ingestSignature,
+      },
+      body: JSON.stringify({
+        shop_id: input.shopId,
+        user_id: input.visitorId,
+        url: input.url,
+        environment: input.environment,
+        ...(cartToken ? { cart_token: cartToken } : {}),
+        experiments: requestedExperimentIds,
+        exclusion_group_selections: input.exclusionGroupSelections?.map((selection) => ({
+          group_id: selection.groupId,
+          experiment_id: selection.experimentId,
+          epoch: selection.epoch,
+        })),
+      }),
+      keepalive: true,
+    });
+    if (!response.ok) {
+      return {
+        completed: !requiresCommerceAuthorization(input),
+        cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof &&
+          !isUnsignedCommerceClearCandidate(input),
+        token: null,
+        assignments: input.assignments,
+      };
+    }
+    const payload = (await response.json()) as {
+      assignments?: unknown;
+      commerce_authorization?: unknown;
+    };
+    const token =
+      typeof payload.commerce_authorization === "string" &&
+      payload.commerce_authorization
+        ? payload.commerce_authorization
+        : null;
+    if (
+      !input.assignments[0] &&
+      isUnsignedCommerceClearCandidate(input) &&
+      // With configured offer experiments, a nonempty response is the
+      // cart-pinned offer arm returning under a new identity/off-target page —
+      // it must flow to the offers proof/adoption path below, not be rejected
+      // as a failed stale-clear. Empty-response teardown clears are unaffected.
+      !input.offersExperimentIds?.length &&
+      (!Array.isArray(payload.assignments) || payload.assignments.length !== 0)
+    ) {
+      return {
+        completed: false,
+        cartWriteAllowed: false,
+        token: null,
+        assignments: input.assignments,
+      };
+    }
+    let authorizedAssignments = input.assignments;
+    let requiredAssignments = input.requiredAssignments;
+    let resolvedPriceAssignments: ReturnType<
+      typeof resolveAuthoritativePriceAssignments
+    > = null;
+    let resolvedOffersAssignments: ReturnType<
+      typeof resolveAuthoritativeOffersAssignments
+    > = null;
+    if (input.priceAuthorizationRevision != null) {
+      const priceExperimentIds = new Set(input.priceExperimentIds ?? []);
+      const evaluatedPriceExperimentIds = parseEvaluatedPriceExperimentIds(
+        token,
+        priceExperimentIds,
+      );
+      if (!evaluatedPriceExperimentIds) {
+        return {
+          completed: false,
+          cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+          token: null,
+          assignments: input.assignments,
+        };
+      }
+      if (priceExperimentIds.size > 0) {
+        resolvedPriceAssignments = resolveAuthoritativePriceAssignments(
+          payload.assignments,
+          input.assignments,
+          evaluatedPriceExperimentIds,
+        );
+        if (!resolvedPriceAssignments) {
+          return {
+            completed: false,
+            cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+            token: null,
+            assignments: input.assignments,
+          };
+        }
+        authorizedAssignments = resolvedPriceAssignments.assignments;
+        requiredAssignments = input.requiredAssignments?.flatMap((required) => {
+          if (!priceExperimentIds.has(required.experimentId)) return [required];
+          // A browser-only price experiment outside the Worker's evaluated set
+          // cannot be signed. Keep its local assignment/cart attribution, but do
+          // not demand impossible price proof: display eligibility is separately
+          // restricted to assignments actually present in the signed price plane.
+          if (!evaluatedPriceExperimentIds.has(required.experimentId)) return [];
+          const authoritative = resolvedPriceAssignments?.priceAssignments.find(
+            (assignment) => assignment.experimentId === required.experimentId,
+          );
+          return authoritative ? [authoritative] : [];
+        });
+      }
+      const requiredPriceAssignments = requiredAssignments?.filter((assignment) =>
+        priceExperimentIds.has(assignment.experimentId)
+      ) ?? [];
+      const requiresNonPriceAssignment = requiredAssignments?.some((assignment) =>
+        !priceExperimentIds.has(assignment.experimentId)
+      );
+      const pricePlane = parsePriceAuthorizationPlane(token);
+      hasAuthoritativePriceProof =
+        resolvedPriceAssignments?.priceAssignments.length === 0
+          ? hasSignedEmptyPriceAuthorizationEnvelope(token)
+          : !!pricePlane && hasSignedAssignmentProof(
+              pricePlane.a,
+              resolvedPriceAssignments?.priceAssignments ?? [],
+            );
+      // Round 17 permits an unsigned successful response to clear shipping proof
+      // because removing a shipping grant is privilege-reducing. Price differs:
+      // replacing a signed price pin changes what checkout charges, so an active
+      // price plane must have a signed assignment or signed-empty envelope before
+      // any combined cart-attribute write can touch the existing pin.
+      if (
+        (priceWriteRequiresProof && !hasAuthoritativePriceProof) ||
+        (requiredPriceAssignments.length > 0 &&
+          (!pricePlane || !hasSignedAssignmentProof(pricePlane.a, requiredPriceAssignments))) ||
+        (resolvedPriceAssignments?.adoptionRequired &&
+          !hasAuthoritativePriceProof) ||
+        (!token && requiresNonPriceAssignment)
+      ) {
+        return {
+          completed: false,
+          cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+          token: null,
+          assignments: input.assignments,
+        };
+      }
+    } else if (requiresCommerceAuthorization(input) && !token) {
+      const isLegitimateEmptyShippingResponse =
+        isUnsignedCommerceClearCandidate(input) &&
+        Array.isArray(payload.assignments) &&
+        (!!input.assignments[0] || payload.assignments.length === 0);
+      if (!isLegitimateEmptyShippingResponse) {
+        return {
+          completed: false,
+          cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+          token: null,
+          assignments: input.assignments,
+        };
+      }
+      // Clearing a stale shipping discount grant is privilege-reducing and needs no
+      // signature; unlike conferring a grant, the successful parsed response is enough.
+    }
+    if (enforceOffersPlaneProof && configuredOffersExperimentIds.size > 0) {
+      resolvedOffersAssignments = resolveAuthoritativeOffersAssignments(
+        payload.assignments,
+        authorizedAssignments,
+        configuredOffersExperimentIds,
+      );
+      if (!resolvedOffersAssignments) {
+        return {
+          completed: false,
+          cartWriteAllowed: false,
+          token: null,
+          assignments: input.assignments,
+        };
+      }
+      authorizedAssignments = resolvedOffersAssignments.assignments;
+      requiredOffersAssignments = resolvedOffersAssignments.offersAssignments;
+      requiredAssignments = requiredAssignments?.flatMap((required) => {
+        if (!configuredOffersExperimentIds.has(required.experimentId)) return [required];
+        const authoritative = resolvedOffersAssignments?.offersAssignments.find(
+          (assignment) => assignment.experimentId === required.experimentId,
+        );
+        return authoritative ? [authoritative] : [];
+      });
+    }
+    if (requiredOffersAssignments.length > 0) {
+      const offersPlane = parseAuthorizationPlane(token, "offers");
+      const hasOffersProof = !!offersPlane && hasSignedAssignmentProof(
+        offersPlane.a,
+        requiredOffersAssignments,
+      );
+      if (!hasOffersProof) {
+        if (!priceWriteRequiresProof || !hasAuthoritativePriceProof) {
+          return {
+            completed: false,
+            cartWriteAllowed: false,
+            token: null,
+            assignments: input.assignments,
+          };
+        }
+        const configuredPriceExperimentIds = new Set(input.priceExperimentIds ?? []);
+        authorizedAssignments = authorizedAssignments.filter((assignment) =>
+          !configuredOffersExperimentIds.has(assignment.experimentId) ||
+          configuredPriceExperimentIds.has(assignment.experimentId)
+        );
+      }
+    }
+    if (requiredShippingAssignments.length > 0) {
+      const shippingPlane = parseAuthorizationPlane(token, "shipping");
+      const hasShippingProof = !!shippingPlane && hasSignedAssignmentProof(
+        shippingPlane.a,
+        requiredShippingAssignments,
+      );
+      if (!hasShippingProof) {
+        if (!priceWriteRequiresProof || !hasAuthoritativePriceProof) {
+          return {
+            completed: false,
+            cartWriteAllowed: false,
+            token: null,
+            assignments: input.assignments,
+          };
+        }
+        // A proven price plane may proceed independently. Remove shipping-only
+        // assignments from the stamp; assignments shared with price remain because
+        // checkout validates each plane from its own signature.
+        const configuredPriceExperimentIds = new Set(input.priceExperimentIds ?? []);
+        authorizedAssignments = authorizedAssignments.filter((assignment) =>
+          !configuredShippingExperimentIds.has(assignment.experimentId) ||
+          configuredPriceExperimentIds.has(assignment.experimentId)
+        );
+      }
+    }
+    if (!hasRequiredAssignmentProof(payload.assignments, requiredAssignments)) {
+      return {
+        completed: false,
+        cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+        token: null,
+        assignments: input.assignments,
+      };
+    }
+    if (
+      resolvedPriceAssignments?.adoptionRequired &&
+      ((generation !== undefined && generation !== latestSyncGeneration) ||
+        !input.adoptPriceAssignments?.(
+          authorizedAssignments.filter((assignment) =>
+            input.priceExperimentIds?.includes(assignment.experimentId)
+          ),
+        ))
+    ) {
+      return {
+        completed: false,
+        cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof,
+        token: null,
+        assignments: input.assignments,
+      };
+    }
+    let offersAdoptionAssignments: CartAssignment[] | undefined;
+    if (resolvedOffersAssignments?.adoptionRequired) {
+      const adoptable = authorizedAssignments.filter((assignment) =>
+        configuredOffersExperimentIds.has(assignment.experimentId)
+      );
+      // Only validate feasibility here. Applying the adoption (DOM, persist,
+      // tracking) before the cart write is confirmed would let the shopper see
+      // and record a treatment Shopify never stamped an authorization for —
+      // the caller applies it post-write (theme) or post-confirm (headless).
+      if (
+        (generation !== undefined && generation !== latestSyncGeneration) ||
+        !input.canAdoptOffersAssignments?.(adoptable)
+      ) {
+        return {
+          completed: false,
+          cartWriteAllowed: false,
+          token: null,
+          assignments: input.assignments,
+        };
+      }
+      offersAdoptionAssignments = adoptable;
+    }
+    return {
+      completed: true,
+      cartWriteAllowed: true,
+      token,
+      assignments: authorizedAssignments,
+      offersAdoptionAssignments,
+    };
+  } catch {
+    return {
+      completed: !requiresCommerceAuthorization(input),
+      cartWriteAllowed: !priceWriteRequiresProof && !offersWriteRequiresProof &&
+        !isUnsignedCommerceClearCandidate(input),
+      token: null,
+      assignments: input.assignments,
+    };
+  }
+}
+
+function hasSignedEmptyPriceAuthorizationEnvelope(token: string | null): boolean {
+  if (!token) return false;
+  try {
+    const envelope = JSON.parse(token) as Record<string, unknown> | null;
+    if (
+      !envelope ||
+      typeof envelope !== "object" ||
+      envelope.v !== 2 ||
+      !envelope.p ||
+      typeof envelope.p !== "object"
+    ) return false;
+    const price = (envelope.p as Record<string, unknown>).price;
+    if (!price || typeof price !== "object") return false;
+    const plane = price as Record<string, unknown>;
+    return plane.v === 1 &&
+      Number.isSafeInteger(plane.r) && (plane.r as number) > 0 &&
+      typeof plane.c === "string" && /^[a-f0-9]{64}$/.test(plane.c) &&
+      typeof plane.x === "string" && /^\d{4}-\d{2}-\d{2}$/.test(plane.x) &&
+      Array.isArray(plane.a) && plane.a.length === 0 &&
+      typeof plane.cartHash === "string" && /^[a-f0-9]{64}$/.test(plane.cartHash) &&
+      typeof plane.s === "string" && /^[a-f0-9]{64}$/.test(plane.s);
+  } catch {
+    return false;
+  }
+}
+
+function parsePriceAuthorizationPlane(
+  token: string | null,
+): Record<string, unknown> | null {
+  if (!token) return null;
+  try {
+    const candidate = JSON.parse(token) as Record<string, unknown> | null;
+    if (!candidate || typeof candidate !== "object") return null;
+    if (
+      candidate.v === 1 &&
+      typeof candidate.cartHash === "string" &&
+      candidate.cartHash
+    ) {
+      return candidate;
+    }
+    if (candidate.v !== 2 || !candidate.p || typeof candidate.p !== "object") return null;
+    const price = (candidate.p as Record<string, unknown>).price;
+    return price && typeof price === "object"
+      ? price as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseAuthorizationPlane(
+  token: string | null,
+  plane: "shipping" | "offers",
+): Record<string, unknown> | null {
+  if (!token) return null;
+  try {
+    const candidate = JSON.parse(token) as Record<string, unknown> | null;
+    if (candidate?.v !== 2 || !candidate.p || typeof candidate.p !== "object") return null;
+    const value = (candidate.p as Record<string, unknown>)[plane];
+    return value && typeof value === "object"
+      ? value as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseSignedPriceAuthorizationAssignments(
+  token: string | null,
+  configuredPriceExperimentIds: ReadonlySet<string>,
+): CartAssignment[] | null {
+  const pricePlane = parsePriceAuthorizationPlane(token);
+  if (!pricePlane || !Array.isArray(pricePlane.a)) return null;
+  const assignments: CartAssignment[] = [];
+  const seen = new Set<string>();
+  for (const candidate of pricePlane.a) {
+    if (!candidate || typeof candidate !== "object") return null;
+    const assignment = candidate as Record<string, unknown>;
+    if (
+      typeof assignment.e !== "string" ||
+      !configuredPriceExperimentIds.has(assignment.e) ||
+      seen.has(assignment.e) ||
+      typeof assignment.v !== "string" ||
+      !assignment.v ||
+      !Number.isSafeInteger(assignment.ep) ||
+      (assignment.ep as number) < 1
+    ) return null;
+    seen.add(assignment.e);
+    assignments.push({
+      experimentId: assignment.e,
+      variationId: assignment.v,
+      assignmentEpoch: assignment.ep as number,
+    });
+  }
+  return assignments;
+}
+
+function parseSignedShippingAuthorizationAssignments(
+  token: string | null,
+  configuredShippingExperimentIds: ReadonlySet<string>,
+): CartAssignment[] | null {
+  const shippingPlane = parseAuthorizationPlane(token, "shipping");
+  if (!shippingPlane || !Array.isArray(shippingPlane.a)) return null;
+  const assignments: CartAssignment[] = [];
+  const seen = new Set<string>();
+  for (const candidate of shippingPlane.a) {
+    if (!candidate || typeof candidate !== "object") return null;
+    const assignment = candidate as Record<string, unknown>;
+    if (
+      typeof assignment.e !== "string" ||
+      !configuredShippingExperimentIds.has(assignment.e) ||
+      seen.has(assignment.e) ||
+      typeof assignment.v !== "string" ||
+      !assignment.v ||
+      !Number.isSafeInteger(assignment.ep) ||
+      (assignment.ep as number) < 1
+    ) return null;
+    seen.add(assignment.e);
+    assignments.push({
+      experimentId: assignment.e,
+      variationId: assignment.v,
+      assignmentEpoch: assignment.ep as number,
+    });
+  }
+  return assignments;
+}
+
+function parseSignedOffersAuthorizationAssignments(
+  token: string | null,
+  configuredOffersExperimentIds: ReadonlySet<string>,
+): CartAssignment[] | null {
+  const offersPlane = parseAuthorizationPlane(token, "offers");
+  if (!offersPlane || !Array.isArray(offersPlane.a)) return null;
+  const assignments: CartAssignment[] = [];
+  const seen = new Set<string>();
+  for (const candidate of offersPlane.a) {
+    if (!candidate || typeof candidate !== "object") return null;
+    const assignment = candidate as Record<string, unknown>;
+    if (
+      typeof assignment.e !== "string" ||
+      !configuredOffersExperimentIds.has(assignment.e) ||
+      seen.has(assignment.e) ||
+      typeof assignment.v !== "string" ||
+      !assignment.v ||
+      !Number.isSafeInteger(assignment.ep) ||
+      (assignment.ep as number) < 1
+    ) return null;
+    seen.add(assignment.e);
+    assignments.push({
+      experimentId: assignment.e,
+      variationId: assignment.v,
+      assignmentEpoch: assignment.ep as number,
+    });
+  }
+  return assignments;
+}
+
+function parseEvaluatedPriceExperimentIds(
+  token: string | null,
+  configuredPriceExperimentIds: ReadonlySet<string>,
+): Set<string> | null {
+  const rolloutFallback = () => new Set(configuredPriceExperimentIds);
+  if (!token) return rolloutFallback();
+  try {
+    const envelope = JSON.parse(token) as Record<string, unknown> | null;
+    if (!envelope || typeof envelope !== "object" || envelope.v !== 2) {
+      return rolloutFallback();
+    }
+    if (!Object.prototype.hasOwnProperty.call(envelope, "e")) {
+      // Rollout ordering matters: deploy the Worker before this SDK. Until every
+      // response declares `e`, an older V2 envelope must retain round-14 behavior
+      // and treat every configured price experiment as evaluated.
+      return rolloutFallback();
+    }
+    if (!Array.isArray(envelope.e)) return null;
+    const evaluated = new Set<string>();
+    for (const experimentId of envelope.e) {
+      if (
+        typeof experimentId !== "string" ||
+        !experimentId ||
+        !configuredPriceExperimentIds.has(experimentId) ||
+        evaluated.has(experimentId)
+      ) return null;
+      evaluated.add(experimentId);
+    }
+    return evaluated;
+  } catch {
+    return rolloutFallback();
+  }
+}
+
+function hasSignedAssignmentProof(
+  signedAssignments: unknown,
+  requiredAssignments: NonNullable<CartAttributeSyncInput["requiredAssignments"]>,
+): boolean {
+  if (!Array.isArray(signedAssignments)) return false;
+  return requiredAssignments.every((required) =>
+    signedAssignments.some((candidate) => {
+      if (!candidate || typeof candidate !== "object") return false;
+      const assignment = candidate as Record<string, unknown>;
+      return assignment.e === required.experimentId &&
+        assignment.v === required.variationId &&
+        assignment.ep === required.assignmentEpoch;
+    })
+  );
+}
+
+function parseResponsePriceAssignments(
+  responseAssignments: unknown,
+  priceExperimentIds: ReadonlySet<string>,
+): CartAssignment[] | null {
+  if (!Array.isArray(responseAssignments)) return null;
+  const assignments: CartAssignment[] = [];
+  const seen = new Set<string>();
+  for (const candidate of responseAssignments) {
+    if (!candidate || typeof candidate !== "object") continue;
+    const assignment = candidate as Record<string, unknown>;
+    if (
+      typeof assignment.experiment_id !== "string" ||
+      !priceExperimentIds.has(assignment.experiment_id)
+    ) {
+      continue;
+    }
+    if (
+      seen.has(assignment.experiment_id) ||
+      typeof assignment.variation_id !== "string" ||
+      !assignment.variation_id ||
+      !Number.isSafeInteger(assignment.assignment_epoch) ||
+      (assignment.assignment_epoch as number) < 1
+    ) return null;
+    seen.add(assignment.experiment_id);
+    assignments.push({
+      experimentId: assignment.experiment_id,
+      variationId: assignment.variation_id,
+      assignmentEpoch: assignment.assignment_epoch as number,
+      ...(assignment.commerce_price_only === true ? { commercePriceOnly: true } : {}),
+    });
+  }
+  return assignments;
+}
+
+function resolveAuthoritativePriceAssignments(
+  responseAssignments: unknown,
+  localAssignments: CartAttributeSyncInput["assignments"],
+  evaluatedPriceExperimentIds: ReadonlySet<string>,
+): {
+  assignments: CartAssignment[];
+  priceAssignments: CartAssignment[];
+  adoptionRequired: boolean;
+} | null {
+  const priceAssignments = parseResponsePriceAssignments(
+    responseAssignments,
+    evaluatedPriceExperimentIds,
+  );
+  if (!priceAssignments) return null;
+  const localPriceAssignments = localAssignments.filter((assignment) =>
+    evaluatedPriceExperimentIds.has(assignment.experimentId)
+  );
+  const authoritativeByExperimentId = new Map(
+    priceAssignments.map((assignment) => [assignment.experimentId, assignment]),
+  );
+  const adoptionRequired = localPriceAssignments.some(
+    (assignment) => !authoritativeByExperimentId.has(assignment.experimentId),
+  ) || priceAssignments.some((assignment) => {
+    const local = localPriceAssignments.find(
+      (candidate) => candidate.experimentId === assignment.experimentId,
+    );
+    return local?.variationId !== assignment.variationId ||
+      local.assignmentEpoch !== assignment.assignmentEpoch ||
+      local.commercePriceOnly !== assignment.commercePriceOnly;
+  });
+  const remainingPriceAssignments = new Map(authoritativeByExperimentId);
+  const assignments = localAssignments.map((assignment) => {
+    if (!evaluatedPriceExperimentIds.has(assignment.experimentId)) return assignment;
+    const authoritative = remainingPriceAssignments.get(assignment.experimentId);
+    if (!authoritative) return null;
+    remainingPriceAssignments.delete(assignment.experimentId);
+    return authoritative;
+  }).filter((assignment): assignment is CartAssignment => assignment !== null);
+  for (const assignment of priceAssignments) {
+    if (remainingPriceAssignments.has(assignment.experimentId)) {
+      assignments.push(assignment);
+      remainingPriceAssignments.delete(assignment.experimentId);
+    }
+  }
+  return { assignments, priceAssignments, adoptionRequired };
+}
+
+function resolveAuthoritativeOffersAssignments(
+  responseAssignments: unknown,
+  localAssignments: CartAttributeSyncInput["assignments"],
+  configuredOffersExperimentIds: ReadonlySet<string>,
+): {
+  assignments: CartAssignment[];
+  offersAssignments: CartAssignment[];
+  adoptionRequired: boolean;
+} | null {
+  const offersAssignments = parseResponsePriceAssignments(
+    responseAssignments,
+    configuredOffersExperimentIds,
+  );
+  if (!offersAssignments) return null;
+  const resolved = resolveAuthoritativePriceAssignments(
+    responseAssignments,
+    localAssignments,
+    configuredOffersExperimentIds,
+  );
+  return resolved && {
+    assignments: resolved.assignments,
+    offersAssignments,
+    adoptionRequired: resolved.adoptionRequired,
+  };
+}
+
+export async function buildSignedCartAttributeEntries(
+  input: CartAttributeSyncInput,
+): Promise<CartAttributeEntry[]> {
+  const generation = ++latestSyncGeneration;
+  const authorization = await requestCommerceAuthorization(input, generation);
+  if (generation !== latestSyncGeneration || !authorization.completed) return [];
+  if (authorization.offersAdoptionAssignments) {
+    // Headless integrators own the cart write; hand the validated adoption to
+    // the caller so it applies only after confirmCartAttributesWritten.
+    input.stageOffersAdoptionAssignments?.(authorization.offersAdoptionAssignments);
+  }
+  if (hasActivePriceAuthorizationPlane(input)) {
+    const authorizedPriceAssignments = parseSignedPriceAuthorizationAssignments(
+      authorization.token,
+      new Set(input.priceExperimentIds ?? []),
+    );
+    if (!authorizedPriceAssignments) return [];
+    input.authorizePriceDisplayAssignments?.(authorizedPriceAssignments);
+  }
+  if (hasActiveShippingAuthorizationPlane(input)) {
+    const authorizedShippingAssignments = parseSignedShippingAuthorizationAssignments(
+      authorization.token,
+      shippingExperimentIds(input),
+    ) ?? [];
+    input.authorizeShippingDisplayAssignments?.(authorizedShippingAssignments);
+  }
+  if (hasActiveOffersAuthorizationPlane(input)) {
+    const authorizedOffersAssignments = parseSignedOffersAuthorizationAssignments(
+      authorization.token,
+      offersExperimentIds(input),
+    ) ?? [];
+    input.authorizeOffersDisplayAssignments?.(authorizedOffersAssignments);
+  }
+  return buildCartAttributeEntries(
+    { ...input, assignments: authorization.assignments },
+    authorization.token,
+  );
+}
+
+function hasRequiredAssignmentProof(
+  responseAssignments: unknown,
+  requiredAssignments: CartAttributeSyncInput["requiredAssignments"],
+): boolean {
+  if (!requiredAssignments?.length) return true;
+  if (!Array.isArray(responseAssignments)) return false;
+
+  return requiredAssignments.every((required) => {
+    if (!Number.isInteger(required.assignmentEpoch) || (required.assignmentEpoch ?? 0) < 1) {
+      return false;
+    }
+    return responseAssignments.some((candidate) => {
+      if (!candidate || typeof candidate !== "object") return false;
+      const assignment = candidate as Record<string, unknown>;
+      return assignment.experiment_id === required.experimentId
+        && assignment.variation_id === required.variationId
+        && assignment.assignment_epoch === required.assignmentEpoch;
+    });
+  });
+}
+
+export function buildCartAttributeEntries(
+  input: CartAttributeSyncInput,
+  commerceAuthorization: string | null = null,
+): CartAttributeEntry[] {
+  const primaryAssignment = input.assignments[0];
+  const entries: CartAttributeEntry[] = [
+    {
+      key: "apex_assignments",
+      value: JSON.stringify(
+        input.assignments.map((assignment) => ({
+          e: assignment.experimentId,
+          v: assignment.variationId,
+          ep: assignment.assignmentEpoch,
+        })),
+      ),
+    },
+    {
+      key: "apex_assignment_authorization",
+      value: commerceAuthorization ?? "",
+    },
+  ];
+  if (!primaryAssignment) {
+    return [
+      ...entries,
+      { key: "apex_experiment_id", value: "" },
+      { key: "apex_variation_id", value: "" },
+      { key: "apex_assignment_epoch", value: "" },
+      { key: "apex_visitor_id", value: input.visitorId },
+      { key: "apex_session_id", value: input.sessionId },
+    ];
+  }
+  return [
+    ...entries,
+    { key: "apex_experiment_id", value: primaryAssignment.experimentId },
+    { key: "apex_variation_id", value: primaryAssignment.variationId },
+    {
+      key: "apex_assignment_epoch",
+      value: String(primaryAssignment.assignmentEpoch ?? ""),
+    },
+    { key: "apex_visitor_id", value: input.visitorId },
+    { key: "apex_session_id", value: input.sessionId },
+  ];
+}