@drip-apex/sdk 0.1.0

package/src/commerce-shipping.ts

@@ -0,0 +1,447 @@
+import type { Assignment, CommerceShippingSettings } from "./types";
+import { onShopifyCartMutation } from "./shopify-cart-events";
+import {
+  findCartDrawerContainer,
+  installCartDrawerOpenListener,
+} from "./surface-signals";
+
+type ShopifyWindow = Window & {
+  Shopify?: {
+    currency?: { active?: string };
+    routes?: { root?: string };
+  };
+};
+
+type ActiveShipping = {
+  experimentId: string;
+  currency: string;
+  variant: CommerceShippingSettings["experiments"][number]["variants"][string];
+  eligibilityTarget: { productGids: string[]; variantGids: string[] };
+  renderEnabled: boolean;
+  thresholdCents: number | null;
+  minorUnits: number;
+};
+
+let current: ActiveShipping | null = null;
+let stopCartMutationListener: (() => void) | null = null;
+let stopDrawerListener: (() => void) | null = null;
+let placementObserver: MutationObserver | null = null;
+let placementCheckTimer: number | null = null;
+
+function removeRenderedElement(): void {
+  element?.remove();
+  element = null;
+}
+let element: HTMLElement | null = null;
+let lastSubtotal: number | null = null;
+let refreshSequence = 0;
+let cartAbortController: AbortController | null = null;
+const cartEligibility = new Map<string, boolean>();
+
+export function isShippingCartEligible(experimentId: string): boolean {
+  // Fail closed: until a cart read proves the target is absent, an enforced
+  // experiment stays charge-affecting — an unevaluated (e.g. unsigned-plane)
+  // experiment must not silently downgrade to advisory stamping.
+  return cartEligibility.get(experimentId) ?? true;
+}
+
+type ShippingVariantLike = {
+  treatment: string;
+  threshold: string | null;
+  target?: { productGids: string[]; variantGids: string[] };
+};
+
+/** Shared exposure classification for the sync loop and the exposure fence.
+ * Treatments prove eligibility on their OWN target; controls mirror the
+ * treatment set — any-targeted for scope (an unscoped sibling keeps the
+ * control universal), every-bound for currency (a thresholdless percent
+ * sibling keeps the control cross-currency eligible). */
+export function classifyShippingExposure(
+  variants: Record<string, ShippingVariantLike>,
+  isControl: boolean,
+  ownVariant: ShippingVariantLike | undefined,
+): {
+  eligibilityTarget: { productGids: string[]; variantGids: string[] };
+  needsTargetProof: boolean;
+  isCurrencyBound: boolean;
+} {
+  const empty = { productGids: [] as string[], variantGids: [] as string[] };
+  const scoped = (candidate: ShippingVariantLike | undefined) =>
+    (candidate?.target?.productGids.length ?? 0) > 0 ||
+    (candidate?.target?.variantGids.length ?? 0) > 0;
+  const bound = (candidate: ShippingVariantLike | undefined) =>
+    candidate != null &&
+    candidate.treatment !== "none" &&
+    (candidate.threshold !== null || candidate.treatment !== "percent_off");
+  const treatments = Object.values(variants).filter(
+    (candidate) => candidate.treatment !== "none",
+  );
+  if (!isControl) {
+    return {
+      eligibilityTarget: ownVariant?.target ?? empty,
+      needsTargetProof: scoped(ownVariant),
+      isCurrencyBound: bound(ownVariant),
+    };
+  }
+  const hasUnscopedTreatment = treatments.some((candidate) => !scoped(candidate));
+  return {
+    eligibilityTarget: hasUnscopedTreatment
+      ? empty
+      : treatments.reduce(
+          (target, candidate) => ({
+            productGids: [...target.productGids, ...(candidate.target?.productGids ?? [])],
+            variantGids: [...target.variantGids, ...(candidate.target?.variantGids ?? [])],
+          }),
+          empty,
+        ),
+    needsTargetProof: treatments.some(scoped),
+    isCurrencyBound: treatments.length > 0 && treatments.every(bound),
+  };
+}
+
+/** True only after shipping setup or a successful cart read proves eligibility. */
+export function isShippingCartEligibilityConfirmed(
+  experimentId: string,
+): boolean {
+  return cartEligibility.get(experimentId) === true;
+}
+
+function currencyMinorUnits(currency: string): number | null {
+  try {
+    const units = new Intl.NumberFormat("en", {
+      style: "currency",
+      currency,
+    }).resolvedOptions().maximumFractionDigits;
+    return typeof units === "number" &&
+      Number.isInteger(units) &&
+      units >= 0 &&
+      // ISO 4217 tops out at exponent 4 (CLF, UYW).
+      units <= 4
+      ? units
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function thresholdCents(value: string, minorUnits: number): number | null {
+  const fractionPattern =
+    minorUnits === 0 ? "" : `(?:\\.(\\d{1,${minorUnits}}))?`;
+  const match = new RegExp(`^(\\d+)${fractionPattern}$`).exec(value);
+  if (!match) return null;
+  const cents = Number(match[1] + (match[2] ?? "").padEnd(minorUnits, "0"));
+  return Number.isSafeInteger(cents) && cents > 0 ? cents : null;
+}
+
+function shopifyRoot(): string {
+  const root = (window as ShopifyWindow).Shopify?.routes?.root;
+  if (typeof root !== "string") return "/";
+  try {
+    const parsed = new URL(root, location.origin);
+    if (parsed.origin !== location.origin || parsed.search || parsed.hash)
+      return "/";
+    return parsed.pathname.endsWith("/")
+      ? parsed.pathname
+      : `${parsed.pathname}/`;
+  } catch {
+    return "/";
+  }
+}
+
+function cartPath(resource: string): string {
+  return `${shopifyRoot()}${resource}`;
+}
+
+function activeShipping(
+  settings: CommerceShippingSettings,
+  assignments: Assignment[],
+): ActiveShipping | null {
+  if (typeof window === "undefined") return null;
+  const shopify = (window as ShopifyWindow).Shopify;
+  if (!shopify) return null;
+  const currency = shopify.currency?.active;
+  if (typeof currency !== "string" || !/^[A-Z]{3}$/.test(currency)) return null;
+  const minorUnits = currencyMinorUnits(currency);
+  if (minorUnits === null) return null;
+  const candidates: ActiveShipping[] = [];
+  for (const experiment of settings.experiments) {
+    const assignment = assignments.find(
+      (item) => item.experimentId === experiment.experiment_id,
+    );
+    const variant = assignment
+      ? experiment.variants[assignment.variationId]
+      : undefined;
+    const exposure = classifyShippingExposure(
+      experiment.variants,
+      Boolean(assignment?.isControl),
+      variant,
+    );
+    const eligibilityTarget = exposure.eligibilityTarget;
+    const isExperimentTargeted = exposure.needsTargetProof;
+    const isCurrencyBound = exposure.isCurrencyBound;
+    if (
+      !variant ||
+      (experiment.assignment_epoch != null &&
+        experiment.assignment_epoch !== assignment?.assignmentEpoch) ||
+      (isCurrencyBound && currency !== experiment.currency) ||
+      // Controls stay as eligibility candidates (renderEnabled excludes them
+      // from the banner): an untargeted threshold control must confirm cart
+      // currency the same way its treatment sibling would, or it never exposes.
+      (variant.treatment === "none" && !assignment?.isControl)
+    ) {
+      continue;
+    }
+    const threshold =
+      variant.threshold === null
+        ? null
+        : thresholdCents(variant.threshold, minorUnits);
+    if (variant.threshold !== null && threshold === null) continue;
+    // Controls use the treatment union for symmetric eligibility; treatments
+    // use only their own arm's target.
+    cartEligibility.set(
+      experiment.experiment_id,
+      false,
+    );
+    candidates.push({
+      experimentId: experiment.experiment_id,
+      currency,
+      variant,
+      eligibilityTarget,
+      renderEnabled: !assignment?.isControl && variant.treatment !== "none",
+      thresholdCents: threshold,
+      minorUnits,
+    });
+  }
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+function money(cents: number, currency: string, minorUnits: number): string {
+  return new Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+  }).format(cents / 10 ** minorUnits);
+}
+
+function resolveCopy(
+  template: string,
+  subtotal: number,
+  active: ActiveShipping,
+): string {
+  return template
+    .split("{remaining}")
+    .join(
+      money(
+        Math.max(0, (active.thresholdCents ?? 0) - subtotal),
+        active.currency,
+        active.minorUnits,
+      ),
+    )
+    .split("{threshold}")
+    .join(
+      money(active.thresholdCents ?? 0, active.currency, active.minorUnits),
+    );
+}
+
+function render(subtotal: number, active: ActiveShipping): boolean {
+  removeRenderedElement();
+  const reached =
+    active.thresholdCents !== null && subtotal >= active.thresholdCents;
+  const copy = resolveCopy(
+    active.thresholdCents === null
+      ? active.variant.bannerCopy
+      : reached
+        ? active.variant.reachedCopy
+        : active.variant.progressCopy,
+    subtotal,
+    active,
+  );
+  if (!copy.trim()) return false;
+
+  const wrapper = document.createElement("div");
+  wrapper.dataset.apexShipping = "";
+  wrapper.setAttribute("role", "status");
+  wrapper.setAttribute("aria-live", "polite");
+  wrapper.setAttribute("aria-atomic", "true");
+  wrapper.style.cssText =
+    "box-sizing:border-box;padding:10px 12px;background:#f4f4f0;color:#1a1a1a;font:500 13px/1.4 system-ui,sans-serif;z-index:2147483646";
+  const line = document.createElement("div");
+  line.textContent = copy;
+  wrapper.appendChild(line);
+  if (
+    active.variant.treatment === "progress_bar" &&
+    active.thresholdCents !== null
+  ) {
+    const track = document.createElement("div");
+    const progress = Math.min(
+      100,
+      Math.max(0, (subtotal / active.thresholdCents) * 100),
+    );
+    track.setAttribute("role", "progressbar");
+    track.setAttribute("aria-label", "Free shipping progress");
+    track.setAttribute("aria-valuemin", "0");
+    track.setAttribute("aria-valuemax", "100");
+    track.setAttribute("aria-valuenow", String(Math.round(progress)));
+    track.style.cssText =
+      "height:6px;margin-top:8px;overflow:hidden;border-radius:999px;background:#d9d9d2";
+    const fill = document.createElement("div");
+    fill.style.cssText = `height:100%;width:${progress}%;border-radius:inherit;background:#1a1a1a`;
+    track.appendChild(fill);
+    wrapper.appendChild(track);
+  }
+  const drawer = findCartDrawerContainer();
+  if (drawer) {
+    drawer.prepend(wrapper);
+  } else {
+    wrapper.style.position = "fixed";
+    wrapper.style.inset = "0 0 auto";
+    document.body.prepend(wrapper);
+  }
+  element = wrapper;
+  return true;
+}
+
+function cartMatchesTarget(
+  items: unknown,
+  target: { productGids: string[]; variantGids: string[] },
+): boolean {
+  if (target.productGids.length === 0 && target.variantGids.length === 0)
+    return true;
+  if (!Array.isArray(items)) return false;
+  const products = new Set(target.productGids);
+  const variants = new Set(target.variantGids);
+  return items.some((item) => {
+    if (!item || typeof item !== "object") return false;
+    const line = item as { product_id?: unknown; variant_id?: unknown };
+    const product =
+      typeof line.product_id === "number" || typeof line.product_id === "string"
+        ? `gid://shopify/Product/${line.product_id}`
+        : null;
+    const variant =
+      typeof line.variant_id === "number" || typeof line.variant_id === "string"
+        ? `gid://shopify/ProductVariant/${line.variant_id}`
+        : null;
+    return (
+      (product !== null && products.has(product)) ||
+      (variant !== null && variants.has(variant))
+    );
+  });
+}
+
+async function refreshCart(
+  active: ActiveShipping,
+  onEligibilityConfirmed?: () => void,
+): Promise<void> {
+  const sequence = ++refreshSequence;
+  cartAbortController?.abort();
+  const controller =
+    typeof AbortController === "function" ? new AbortController() : null;
+  cartAbortController = controller;
+  const timeout = controller
+    ? window.setTimeout(() => controller.abort(), 5_000)
+    : null;
+  lastSubtotal = null;
+  element?.remove();
+  element = null;
+  try {
+    const response = await window.fetch(cartPath("cart.js"), {
+      headers: { Accept: "application/json" },
+      ...(controller ? { signal: controller.signal } : {}),
+    });
+    if (!response.ok) return;
+    const cart = (await response.json()) as {
+      currency?: unknown;
+      items_subtotal_price?: unknown;
+      items?: unknown;
+    };
+    const subtotal = cart.items_subtotal_price;
+    const targetEligible = cartMatchesTarget(
+      cart.items,
+      active.eligibilityTarget,
+    );
+    if (sequence !== refreshSequence || current !== active) return;
+    const currencyEligible = cart.currency === active.currency;
+    cartEligibility.set(active.experimentId, targetEligible && currencyEligible);
+    if (!targetEligible || !currencyEligible) {
+      lastSubtotal = null;
+      removeRenderedElement();
+    }
+    if (
+      !currencyEligible ||
+      typeof subtotal !== "number" ||
+      !Number.isSafeInteger(subtotal) ||
+      subtotal < 0 ||
+      !targetEligible
+    )
+      return;
+    lastSubtotal = subtotal;
+    onEligibilityConfirmed?.();
+    if (active.renderEnabled) render(subtotal, active);
+  } catch {
+    // Shipping messaging is additive; storefront cart behavior must never fail with it.
+  } finally {
+    if (timeout !== null) window.clearTimeout(timeout);
+    if (cartAbortController === controller) cartAbortController = null;
+  }
+}
+
+function installPlacementObserver(active: ActiveShipping): void {
+  placementObserver = new MutationObserver(() => {
+    if (placementCheckTimer !== null) return;
+    placementCheckTimer = window.setTimeout(() => {
+      placementCheckTimer = null;
+      if (
+        current !== active ||
+        lastSubtotal === null ||
+        cartEligibility.get(active.experimentId) !== true
+      )
+        return;
+      const parent = findCartDrawerContainer() ?? document.body;
+      if (!element?.isConnected || element.parentElement !== parent) {
+        render(lastSubtotal, active);
+      }
+    }, 80);
+  });
+  placementObserver.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+  });
+}
+
+export function applyCommerceShipping(
+  settings: CommerceShippingSettings | undefined,
+  assignments: Assignment[],
+  onEligibilityConfirmed?: () => void,
+): void {
+  cleanupCommerceShipping();
+  if (!settings) return;
+  const active = activeShipping(settings, assignments);
+  if (!active) return;
+  current = active;
+  stopCartMutationListener = onShopifyCartMutation(() => {
+    if (current === active) void refreshCart(active, onEligibilityConfirmed);
+  });
+  installPlacementObserver(active);
+  stopDrawerListener = installCartDrawerOpenListener((open) => {
+    if (open) void refreshCart(active, onEligibilityConfirmed);
+  });
+  void refreshCart(active, onEligibilityConfirmed);
+}
+
+export function cleanupCommerceShipping(): void {
+  refreshSequence += 1;
+  cartAbortController?.abort();
+  cartAbortController = null;
+  current = null;
+  cartEligibility.clear();
+  lastSubtotal = null;
+  element?.remove();
+  element = null;
+  stopDrawerListener?.();
+  stopDrawerListener = null;
+  placementObserver?.disconnect();
+  placementObserver = null;
+  if (placementCheckTimer !== null) window.clearTimeout(placementCheckTimer);
+  placementCheckTimer = null;
+  stopCartMutationListener?.();
+  stopCartMutationListener = null;
+}