@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/utils/analytics.js

@@ -0,0 +1,864 @@
+/**
+ * Analytics — Google Analytics 4 (gtag.js) and the Meta Pixel (fbq).
+ *
+ * One module, one vocabulary. Every storefront event goes through the methods
+ * on `analytics` below, and each method maps the SAME business fact to BOTH
+ * vendors, so the two never drift apart:
+ *
+ *   method            Google Analytics 4      Meta Pixel
+ *   ───────────────   ─────────────────────   ──────────────────────
+ *   pageView          page_view               PageView
+ *   viewItem          view_item               ViewContent
+ *   viewItemList      view_item_list          ViewCategory (custom, category pages)
+ *   selectItem        select_item             —
+ *   addToCart         add_to_cart             AddToCart
+ *   removeFromCart    remove_from_cart        —
+ *   viewCart          view_cart               —
+ *   beginCheckout     begin_checkout          InitiateCheckout
+ *   addShippingInfo   add_shipping_info       —
+ *   addPaymentInfo    add_payment_info        AddPaymentInfo
+ *   purchase          purchase                Purchase
+ *   search            search                  Search
+ *   signUp            sign_up                 CompleteRegistration
+ *   login             login                   —
+ *   addToWishlist     add_to_wishlist         AddToWishlist
+ *   lead              generate_lead           Lead
+ *   contact           generate_lead           Contact
+ *
+ * Where the IDs come from: the bootstrap response's `store` object —
+ * `google_analytics_id` and `meta_pixel_id`. plugins/analytics.client.js reads
+ * them and calls start(). A store that has neither gets no scripts and every
+ * method below is a silent no-op, so call sites never have to guard.
+ *
+ * Rules this file keeps:
+ *
+ *  * Client only. Nothing here runs during SSR, and the module state below is
+ *    therefore per-browser (one shopper, one tenant) — never shared between
+ *    tenants the way a server-side module variable would be.
+ *  * IDs are validated before they reach a <script src> or an inline snippet.
+ *    They come from a merchant-editable field; a malformed one must not become
+ *    injected markup.
+ *  * Tracking can never break the storefront. Every vendor call is wrapped, and
+ *    nothing here throws into the caller.
+ *  * Purchases are reported once per order, however often the confirmation page
+ *    is reloaded.
+ *  * Meta events carry an `eventID`, so a server-side (Conversions API)
+ *    integration added later can de-duplicate against the browser events.
+ *
+ * Items use the product id as `item_id` / Meta `content_ids` everywhere. If the
+ * store's Meta catalog is keyed by SKU instead, change contentId() — it is the
+ * only place that decides.
+ */
+
+/* ------------------------------------------------------------------ config */
+
+const GA_ID_RE = /^(G|GT|AW)-[A-Z0-9]{4,20}$/;
+const PIXEL_ID_RE = /^\d{8,20}$/;
+
+/** Query params that must never be sent to a vendor as part of a page URL. */
+const SENSITIVE_PARAMS = ["reference", "token", "code", "email", "password", "access_token", "refresh_token"];
+
+/** GA4 caps an event's payload; a long grid is cut to its first screenful. */
+const MAX_LIST_ITEMS = 25;
+
+const GTAG_SRC = "https://www.googletagmanager.com/gtag/js";
+const FBEVENTS_SRC = "https://connect.facebook.net/en_US/fbevents.js";
+
+/* ------------------------------------------------------------------- state */
+
+const state = {
+  started: false,
+  gaIds: [],
+  pixelIds: [],
+  currency: "",
+  consent: true,
+  /** Last cart the server sent, keyed by line (variant) id. */
+  cart: {},
+  /** What we know about a line beyond the cart payload: brand, category… */
+  lineContext: new Map(),
+  /** Once-per-page guards (view_item, view_item_list). Cleared on navigation. */
+  seen: new Set(),
+  /** product id -> the list it was shown in, so a click knows where it came from. */
+  listOf: new Map(),
+  seenPath: "",
+  /** Purchases already reported, for when storage is unavailable. */
+  purchased: new Set(),
+  /** When the shopper last added something (the drawer then opens itself). */
+  lastAddAt: 0,
+};
+
+const isClient = () => typeof window !== "undefined";
+const enabled = () => state.started && (state.gaIds.length > 0 || state.pixelIds.length > 0);
+
+/* ----------------------------------------------------------------- helpers */
+
+/** "G-AB12, G-CD34" / ["…"] -> validated, de-duplicated, upper-cased list. */
+export function parseIds(raw, kind) {
+  const list = Array.isArray(raw) ? raw : String(raw ?? "").split(/[\s,;]+/);
+  const re = kind === "pixel" ? PIXEL_ID_RE : GA_ID_RE;
+  const out = [];
+  for (const value of list) {
+    const id = String(value ?? "").trim();
+    const normal = kind === "pixel" ? id : id.toUpperCase();
+    if (re.test(normal) && !out.includes(normal)) out.push(normal);
+  }
+  return out;
+}
+
+/** A number out of a number or a price string ("12.50", "$12", 12). */
+function num(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+  const n = parseFloat(String(value ?? "").replace(/[^0-9.\-]/g, ""));
+  return Number.isFinite(n) ? n : 0;
+}
+const money = (value) => Math.round(num(value) * 100) / 100;
+
+/** Lowest positive price in "10", 10 or "10 - 20". */
+function lowestPrice(value) {
+  if (value === null || value === undefined || value === "") return 0;
+  const parts = String(value)
+    .split(/\s+-\s+|-(?=\d)/)
+    .map((part) => num(part))
+    .filter((n) => n > 0);
+  return parts.length ? Math.min(...parts) : 0;
+}
+
+function newEventId() {
+  try {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) return crypto.randomUUID();
+  } catch {
+    /* fall through */
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 12)}`;
+}
+
+/** Drops undefined / null / "" so vendors never see empty parameters. */
+function clean(value) {
+  if (Array.isArray(value)) return value.map(clean);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      if (v === undefined || v === null || v === "") continue;
+      out[key] = clean(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+function safely(label, fn) {
+  try {
+    return fn();
+  } catch (error) {
+    if (import.meta.dev) console.warn(`[analytics] ${label} failed:`, error);
+    return undefined;
+  }
+}
+
+/** The page URL with anything sensitive taken out of the query string. */
+function safeLocation() {
+  try {
+    const url = new URL(window.location.href);
+    for (const key of SENSITIVE_PARAMS) url.searchParams.delete(key);
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return window.location.href;
+  }
+}
+
+/** The id every event uses for a product — see the note at the top. */
+function contentId(product, variant, fallback) {
+  const id = product?.id ?? variant?.product_id ?? fallback;
+  return id === undefined || id === null ? "" : String(id);
+}
+
+/* ------------------------------------------------------------------ mapping */
+
+const variantLabel = (variant) => {
+  const values = variant?.values;
+  if (typeof values === "string") return values;
+  return (values ?? [])
+    .map((v) => (typeof v === "string" ? v : v?.name ?? v?.value))
+    .filter(Boolean)
+    .join(" / ");
+};
+
+const brandOf = (product) =>
+  typeof product?.brand === "object" ? product?.brand?.name || "" : product?.brand || "";
+
+/** [top-level, sub-category] names for GA's item_category / item_category2. */
+function categoriesOf(product) {
+  const first = product?.categories?.[0];
+  const category = first?.category ?? first;
+  if (!category) return [];
+  const names = [category.name];
+  const parent = category.parent_category;
+  if (parent && typeof parent === "object" && parent.name) names.unshift(parent.name);
+  return names.filter(Boolean);
+}
+
+/**
+ * A catalog product -> a GA4 item.
+ * @param {object} product
+ * @param {{ variant?: object, quantity?: number, index?: number,
+ *           listId?: string, listName?: string }} [opts]
+ */
+export function productToItem(product, opts = {}) {
+  if (!product) return null;
+  const { variant, quantity = 1, index, listId, listName } = opts;
+  // [top-level, sub-category] — Shoes > Sneakers — as GA's item_category / item_category2.
+  const [category, category2] = categoriesOf(product);
+
+  let price = variant ? num(variant.price) : 0;
+  if (!(price > 0)) {
+    price =
+      lowestPrice(product.discounted_price_range) ||
+      lowestPrice(product.price_range) ||
+      Math.min(
+        ...(product.product_variants ?? []).map((v) => num(v.price)).filter((n) => n > 0),
+        Number.MAX_SAFE_INTEGER
+      );
+    if (!(price > 0) || price === Number.MAX_SAFE_INTEGER) price = num(product.price);
+  }
+
+  return clean({
+    item_id: contentId(product, variant),
+    item_name: product.name || product.page_title,
+    item_brand: brandOf(product),
+    item_category: category,
+    item_category2: category2,
+    item_variant: variantLabel(variant),
+    variant_id: variant?.id !== undefined ? String(variant.id) : undefined,
+    sku: variant?.sku || product.sku,
+    price: money(price),
+    quantity,
+    index,
+    item_list_id: listId,
+    item_list_name: listName,
+  });
+}
+
+/**
+ * A cart line (the server's `cart[id]` entry, keyed by variant id) -> item.
+ * The payload doesn't repeat brand / category, so what the add-to-cart call
+ * site knew is remembered per line and laid back over it here.
+ */
+function cartLineToItem(id, line, quantity) {
+  const known = state.lineContext.get(String(id)) ?? {};
+  const productId =
+    known.item_id ?? line?.product_id ?? line?.product?.id ?? line?.product?.product?.id ?? id;
+  return clean({
+    item_id: String(productId),
+    item_name: line?.name ?? known.item_name,
+    item_brand: known.item_brand,
+    item_category: known.item_category,
+    item_category2: known.item_category2,
+    item_variant: variantLabel(line) || known.item_variant,
+    variant_id: String(id),
+    sku: line?.sku ?? known.sku,
+    price: money(line?.price ?? known.price),
+    quantity: quantity ?? Math.max(1, num(line?.quantity)),
+  });
+}
+
+/** The cart as a list of items — [{ id, ...line }] as useCart().cartItems holds it. */
+function cartToItems(lines) {
+  return (lines ?? []).map((line) => cartLineToItem(line.id, line, Math.max(1, num(line.quantity))));
+}
+
+const sumItems = (items) => money(items.reduce((total, i) => total + num(i.price) * num(i.quantity || 1), 0));
+const countItems = (items) => items.reduce((total, i) => total + num(i.quantity || 1), 0);
+
+/** The Meta product parameters for a list of items. */
+function metaProducts(items) {
+  return {
+    content_type: "product",
+    content_ids: items.map((i) => i.item_id),
+    contents: items.map((i) => ({ id: i.item_id, quantity: i.quantity || 1, item_price: i.price })),
+    num_items: countItems(items),
+  };
+}
+
+/* ----------------------------------------------------------------- vendors */
+
+function sendGA(name, params) {
+  if (!state.gaIds.length) return;
+  safely(`gtag ${name}`, () => window.gtag("event", name, clean(params)));
+}
+
+/**
+ * @param {string} name
+ * @param {object} params
+ * @param {{ custom?: boolean, eventID?: string }} [options]
+ */
+function sendMeta(name, params, { custom = false, eventID } = {}) {
+  if (!state.pixelIds.length) return;
+  safely(`fbq ${name}`, () =>
+    window.fbq(custom ? "trackCustom" : "track", name, clean(params), { eventID: eventID || newEventId() })
+  );
+}
+
+function log(name, ga, meta) {
+  if (import.meta.dev) console.debug(`[analytics] ${name}`, { ga, meta });
+}
+
+/** Installs the gtag.js stub (events queue until the library arrives) and loads it. */
+function loadGA(ids) {
+  window.dataLayer = window.dataLayer || [];
+  if (typeof window.gtag !== "function") {
+    // Must push `arguments`, not an array: gtag.js reads the Arguments object.
+    window.gtag = function gtag() {
+      window.dataLayer.push(arguments); // eslint-disable-line prefer-rest-params
+    };
+  }
+  // Consent Mode v2. Granted by default because the storefront has no consent
+  // banner; when one is added, flip these to "denied" and call setConsent().
+  window.gtag("consent", "default", {
+    ad_storage: "granted",
+    analytics_storage: "granted",
+    ad_user_data: "granted",
+    ad_personalization: "granted",
+  });
+  window.gtag("js", new Date());
+  for (const id of ids) {
+    // page_view is sent by hand: the shop is a SPA, and a config-time hit would
+    // fire before the page title is set and miss every client-side navigation.
+    window.gtag("config", id, { send_page_view: false });
+  }
+  const script = document.createElement("script");
+  script.async = true;
+  script.src = `${GTAG_SRC}?id=${encodeURIComponent(ids[0])}`;
+  document.head.appendChild(script);
+}
+
+/** Meta's base code, un-minified: queueing stub, loader, then init per pixel. */
+function loadPixel(ids) {
+  if (!window.fbq) {
+    const fbq = function fbq() {
+      if (fbq.callMethod) fbq.callMethod.apply(fbq, arguments); // eslint-disable-line prefer-rest-params
+      else fbq.queue.push(arguments); // eslint-disable-line prefer-rest-params
+    };
+    if (!window._fbq) window._fbq = fbq;
+    fbq.push = fbq;
+    fbq.loaded = true;
+    fbq.version = "2.0";
+    fbq.queue = [];
+    window.fbq = fbq;
+
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = FBEVENTS_SRC;
+    const first = document.getElementsByTagName("script")[0];
+    if (first?.parentNode) first.parentNode.insertBefore(script, first);
+    else document.head.appendChild(script);
+  }
+  // PageView is sent by hand on every route change; the pixel's own
+  // history-change PageView would double-count each navigation.
+  window.fbq.disablePushState = true;
+  for (const id of ids) window.fbq("init", id);
+}
+
+/* --------------------------------------------------------------- lifecycle */
+
+/**
+ * Loads the vendor scripts. Idempotent.
+ * @param {{ gaIds?: string[], pixelIds?: string[], currency?: string }} config
+ */
+function start({ gaIds = [], pixelIds = [], currency = "" } = {}) {
+  if (!isClient() || state.started) return false;
+  const ga = parseIds(gaIds, "ga");
+  const pixel = parseIds(pixelIds, "pixel");
+  state.currency = String(currency || "").toUpperCase();
+  if (!ga.length && !pixel.length) return false;
+
+  state.gaIds = ga;
+  state.pixelIds = pixel;
+  state.started = true;
+
+  safely("load gtag", () => ga.length && loadGA(ga));
+  safely("load pixel", () => pixel.length && loadPixel(pixel));
+  return true;
+}
+
+function setCurrency(code) {
+  if (code) state.currency = String(code).toUpperCase();
+}
+
+/**
+ * Cookie / consent banner hook. `true` grants, `false` revokes.
+ * GA honours it through Consent Mode, the pixel through fbq('consent').
+ */
+function setConsent(granted) {
+  state.consent = !!granted;
+  if (!enabled()) return;
+  const value = granted ? "granted" : "denied";
+  if (state.gaIds.length) {
+    safely("consent gtag", () =>
+      window.gtag("consent", "update", {
+        ad_storage: value,
+        analytics_storage: value,
+        ad_user_data: value,
+        ad_personalization: value,
+      })
+    );
+  }
+  if (state.pixelIds.length) {
+    safely("consent fbq", () => window.fbq("consent", granted ? "grant" : "revoke"));
+  }
+}
+
+/** A new path: events that fire once per page may fire again. */
+function routeChanged(path) {
+  if (path !== state.seenPath) {
+    state.seenPath = path;
+    state.seen.clear();
+    state.listOf.clear();
+  }
+}
+
+/** True the first time `key` is seen on this page. */
+function firstTime(key) {
+  if (state.seen.has(key)) return false;
+  state.seen.add(key);
+  return true;
+}
+
+const currencyParams = (value) => ({ currency: state.currency || undefined, value: money(value) });
+
+/* ------------------------------------------------------------------ events */
+
+function pageView() {
+  if (!enabled()) return;
+  const params = {
+    page_title: document.title,
+    page_location: safeLocation(),
+    page_path: window.location.pathname,
+  };
+  sendGA("page_view", params);
+  sendMeta("PageView", {});
+  log("page_view", params);
+}
+
+/** A product page was viewed. */
+function viewItem(product, variant) {
+  if (!enabled() || !product?.id) return;
+  if (!firstTime(`view_item:${product.id}`)) return;
+  const item = productToItem(product, { variant });
+  const ga = { ...currencyParams(item.price), items: [item] };
+  const meta = {
+    ...metaProducts([item]),
+    content_name: item.item_name,
+    content_category: item.item_category2 ? `${item.item_category} > ${item.item_category2}` : item.item_category,
+    ...currencyParams(item.price),
+  };
+  sendGA("view_item", ga);
+  sendMeta("ViewContent", meta);
+  log("view_item", ga, meta);
+}
+
+/**
+ * A list of products came into view: a category, search results, a home-page
+ * product section.
+ * @param {{ id: string, name: string, products: object[], category?: boolean }} list
+ */
+function viewItemList({ id, name, products, category = false } = {}) {
+  if (!enabled() || !products?.length) return;
+  const rows = products.filter((p) => p && !p.is_placeholder).slice(0, MAX_LIST_ITEMS);
+  if (!rows.length) return;
+  // Remembered even when the event itself is a repeat: a click still needs it.
+  rows.forEach((p, i) => state.listOf.set(String(p.id), { listId: id, listName: name, index: i }));
+  if (!firstTime(`view_item_list:${id}:${rows.map((p) => p.id).join(",")}`)) return;
+
+  const items = rows.map((p, index) =>
+    productToItem(p, { index: index + 1, listId: id, listName: name })
+  );
+  const ga = { item_list_id: id, item_list_name: name, items };
+  sendGA("view_item_list", ga);
+  if (category) {
+    sendMeta(
+      "ViewCategory",
+      { content_type: "product", content_name: name, content_category: name, content_ids: items.map((i) => i.item_id) },
+      { custom: true }
+    );
+  }
+  log("view_item_list", ga);
+}
+
+/** A product card was clicked. */
+function selectItem(product, override = {}) {
+  if (!enabled() || !product?.id || product.is_placeholder) return;
+  const from = state.listOf.get(String(product.id)) ?? {};
+  const { listId = from.listId, listName = from.listName, index = from.index } = override;
+  const ga = {
+    item_list_id: listId,
+    item_list_name: listName,
+    items: [productToItem(product, { index: index !== undefined ? index + 1 : undefined, listId, listName })],
+  };
+  sendGA("select_item", ga);
+  log("select_item", ga);
+}
+
+/** What we last heard the cart contained for this line, before an edit. */
+function peekCartLine(id) {
+  return state.cart[String(id)] ?? null;
+}
+
+/** Remembers the server's cart. Called with every cart response. */
+function rememberCart(response) {
+  if (!isClient() || !response || typeof response !== "object") return;
+  const lines = response.cart && typeof response.cart === "object" ? response.cart : {};
+  state.cart = Object.fromEntries(Object.entries(lines).map(([id, line]) => [String(id), { ...line }]));
+}
+
+/** The cart was emptied (order placed / paid). */
+function resetCart() {
+  state.cart = {};
+  state.lineContext.clear();
+}
+
+/**
+ * A cart edit the server accepted.
+ *
+ * Called from CartServices.EditCart — the one function every add / remove goes
+ * through, from product pages, cards, quick buy, the drawer and checkout — so
+ * nothing is missed and nothing is counted twice.
+ *
+ * @param {{ itemId: string|number, quantity: number, action: "add"|"remove",
+ *           before: object|null, after: object|null,
+ *           context?: { product?: object, variant?: object } }} edit
+ */
+function cartEdited({ itemId, quantity, action, before, after, context }) {
+  if (!isClient()) return;
+  const id = String(itemId);
+
+  // Remember what the call site knew, for later edits made from the drawer.
+  if (context?.product) {
+    const item = productToItem(context.product, { variant: context.variant });
+    if (item) state.lineContext.set(id, item);
+  }
+  if (!enabled()) return;
+
+  const adding = action === "add";
+  const line = (adding ? after ?? before : before ?? after) ?? null;
+  const known = state.lineContext.get(id);
+  if (!line && !known) return;
+
+  // Prefer the server's own before / after: it clamps to stock and cart limits.
+  let delta = num(quantity) || 1;
+  if (before && after) {
+    const diff = adding ? num(after.quantity) - num(before.quantity) : num(before.quantity) - num(after.quantity);
+    if (diff > 0) delta = diff;
+  } else if (!adding && before) {
+    delta = Math.min(delta, num(before.quantity) || delta);
+  }
+
+  const item = line ? cartLineToItem(id, line, delta) : { ...known, quantity: delta };
+  const total = money(num(item.price) * delta);
+  const ga = { ...currencyParams(total), items: [item] };
+
+  if (adding) {
+    state.lastAddAt = Date.now();
+    const meta = { ...metaProducts([item]), content_name: item.item_name, ...currencyParams(total) };
+    sendGA("add_to_cart", ga);
+    sendMeta("AddToCart", meta);
+    log("add_to_cart", ga, meta);
+  } else {
+    sendGA("remove_from_cart", ga);
+    log("remove_from_cart", ga);
+  }
+}
+
+/** The cart drawer / page was opened. */
+function viewCart(lines) {
+  if (!enabled() || !lines?.length) return;
+  // The drawer opens itself after an add; that isn't the shopper looking at
+  // their bag, and counting it would bury the real view_cart signal.
+  if (Date.now() - state.lastAddAt < 3000) return;
+  const items = cartToItems(lines);
+  const ga = { ...currencyParams(sumItems(items)), items };
+  sendGA("view_cart", ga);
+  log("view_cart", ga);
+}
+
+/** The checkout page opened with something in the bag. */
+function beginCheckout(lines, { coupon } = {}) {
+  if (!enabled() || !lines?.length) return;
+  const items = cartToItems(lines);
+  const value = sumItems(items);
+  const ga = { ...currencyParams(value), coupon, items };
+  const meta = { ...metaProducts(items), ...currencyParams(value) };
+  sendGA("begin_checkout", ga);
+  sendMeta("InitiateCheckout", meta);
+  log("begin_checkout", ga, meta);
+}
+
+/** A delivery destination was chosen. */
+function addShippingInfo(lines, { tier, coupon } = {}) {
+  if (!enabled() || !lines?.length) return;
+  const items = cartToItems(lines);
+  const ga = { ...currencyParams(sumItems(items)), coupon, shipping_tier: tier, items };
+  sendGA("add_shipping_info", ga);
+  log("add_shipping_info", ga);
+}
+
+/** A payment method was chosen. */
+function addPaymentInfo(lines, { paymentType, coupon } = {}) {
+  if (!enabled() || !lines?.length) return;
+  const items = cartToItems(lines);
+  const value = sumItems(items);
+  const ga = { ...currencyParams(value), coupon, payment_type: paymentType, items };
+  const meta = { ...metaProducts(items), ...currencyParams(value) };
+  sendGA("add_payment_info", ga);
+  sendMeta("AddPaymentInfo", meta);
+  log("add_payment_info", ga, meta);
+}
+
+/* --------------------------------------------------------------- purchases */
+
+const PURCHASE_KEY = (id) => `osi:purchase:${id}`;
+/** A confirmation page opened more than this long after the order isn't a sale. */
+const PURCHASE_MAX_AGE_MS = 48 * 60 * 60 * 1000;
+
+function alreadyPurchased(id) {
+  if (state.purchased.has(id)) return true;
+  try {
+    return window.localStorage.getItem(PURCHASE_KEY(id)) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function markPurchased(id) {
+  state.purchased.add(id);
+  try {
+    window.localStorage.setItem(PURCHASE_KEY(id), "1");
+  } catch {
+    /* private mode: the in-memory set still guards this tab */
+  }
+}
+
+/**
+ * Order lines -> items.
+ *
+ * `checkout_price` is read as the line total. If the lines don't add up to the
+ * order's cart price that way, it is read as a unit price instead — whichever
+ * reading reconciles with `checkout_cart_price` wins, so a unit / line-total
+ * mix-up in the payload can't inflate or shrink reported revenue.
+ */
+function orderToItems(order) {
+  const lines = order?.items ?? [];
+  const cartPrice = num(order?.checkout_cart_price);
+  const asLineTotals = lines.reduce((t, l) => t + num(l.checkout_price), 0);
+  const asUnitPrices = lines.reduce((t, l) => t + num(l.checkout_price) * Math.max(1, num(l.quantity)), 0);
+  const unitPriced =
+    cartPrice > 0 &&
+    Math.abs(asLineTotals - cartPrice) > 0.01 &&
+    Math.abs(asUnitPrices - cartPrice) <= 0.01;
+
+  return lines.map((line) => {
+    const quantity = Math.max(1, num(line.quantity));
+    const variant = line.product && line.product.product ? line.product : null;
+    const product = variant?.product ?? line.product?.product ?? null;
+    const base = product ? productToItem(product, { variant, quantity }) : {};
+    const unit = unitPriced ? num(line.checkout_price) : num(line.checkout_price) / quantity;
+    return clean({
+      ...base,
+      item_id: base.item_id || String(line.product_id ?? variant?.id ?? line.id ?? line.name),
+      item_name: line.name || base.item_name,
+      // The order payload writes "Red | 42"; everywhere else it's "Red / 42".
+      item_variant: String(line.variant_values ?? "").replace(/\s*\|\s*/g, " / ") || base.item_variant,
+      price: money(unit),
+      quantity,
+    });
+  });
+}
+
+/**
+ * The order was placed (and, for card orders, paid).
+ *
+ * Reported once per order: the confirmation page can be reloaded, bookmarked or
+ * re-opened from an email. GA's `value` leaves shipping out, as its docs ask
+ * (shipping goes in its own field); the pixel's `value` is the full amount the
+ * customer paid, which is what its ROAS reporting expects.
+ *
+ * @returns {boolean} whether an event was sent
+ */
+function purchase(order) {
+  if (!enabled() || !order?.id) return false;
+  const orderRef = String(order.order_number ?? order.id);
+  if (alreadyPurchased(orderRef)) return false;
+  // An old order opened from a bookmark or an email isn't a new sale. Only
+  // applied when the payload says when the order began.
+  const placedAt = Date.parse(
+    order.created_at ?? order.created ?? order.date_created ?? order.date ?? ""
+  );
+  if (Number.isFinite(placedAt) && Date.now() - placedAt > PURCHASE_MAX_AGE_MS) return false;
+
+  const items = orderToItems(order);
+  if (!items.length) return false;
+
+  const total = money(order.checkout_order_total ?? sumItems(items));
+  const shipping = order.freedelivery ? 0 : money(order.checkout_delivery_fees);
+  const coupon = order.promocode?.code;
+
+  const ga = {
+    transaction_id: orderRef,
+    ...currencyParams(Math.max(0, total - shipping)),
+    shipping,
+    coupon,
+    payment_type: order.order_payments?.[0]?.method_name,
+    items,
+  };
+  const meta = { ...metaProducts(items), ...currencyParams(total) };
+
+  sendGA("purchase", ga);
+  // Same event id for the browser and a future server-side event: it is the order.
+  sendMeta("Purchase", meta, { eventID: `purchase-${orderRef}` });
+  markPurchased(orderRef);
+  resetCart();
+  log("purchase", ga, meta);
+
+  identify({
+    email: order.customer?.email,
+    phone: order.customer?.mobile_number,
+    firstName: order.customer?.first_name,
+    lastName: order.customer?.last_name,
+  });
+  return true;
+}
+
+/* ----------------------------------------------------------- everything else */
+
+/** A storefront search ran. */
+function search(term, products = []) {
+  if (!enabled() || !String(term ?? "").trim()) return;
+  const query = String(term).trim();
+  if (!firstTime(`search:${query.toLowerCase()}`)) return;
+  const items = products.filter((p) => p?.id).slice(0, MAX_LIST_ITEMS).map((p) => productToItem(p));
+  sendGA("search", { search_term: query });
+  sendMeta("Search", {
+    search_string: query,
+    content_type: "product",
+    content_ids: items.map((i) => i.item_id),
+  });
+  log("search", { search_term: query });
+}
+
+function signUp(method = "email") {
+  if (!enabled()) return;
+  sendGA("sign_up", { method });
+  sendMeta("CompleteRegistration", { content_name: "Registration", status: true });
+  log("sign_up", { method });
+}
+
+function login(method = "email") {
+  if (!enabled()) return;
+  sendGA("login", { method });
+  log("login", { method });
+}
+
+function addToWishlist(product) {
+  if (!enabled() || !product?.id) return;
+  const item = productToItem(product);
+  const ga = { ...currencyParams(item.price), items: [item] };
+  const meta = { ...metaProducts([item]), content_name: item.item_name, ...currencyParams(item.price) };
+  sendGA("add_to_wishlist", ga);
+  sendMeta("AddToWishlist", meta);
+  log("add_to_wishlist", ga, meta);
+}
+
+/** A newsletter sign-up. */
+function lead(source = "newsletter") {
+  if (!enabled()) return;
+  sendGA("generate_lead", { lead_source: source });
+  sendMeta("Lead", { content_name: source });
+  log("generate_lead", { lead_source: source });
+}
+
+/** The contact form was sent. */
+function contact() {
+  if (!enabled()) return;
+  sendGA("generate_lead", { lead_source: "contact_form" });
+  sendMeta("Contact", { content_name: "contact_form" });
+  log("contact", {});
+}
+
+/* ---------------------------------------------------------- advanced matching */
+
+async function sha256(value) {
+  const bytes = new TextEncoder().encode(value);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Meta advanced matching: hashed customer details attached to the pixel so it
+ * can match events to people. Hashed in the browser (SHA-256, normalised the
+ * way Meta specifies); the raw values never leave. Called once a person is
+ * known — at purchase and at login.
+ */
+async function identify({ email, phone, firstName, lastName } = {}) {
+  if (!enabled() || !state.pixelIds.length || !state.consent) return;
+  if (typeof crypto === "undefined" || !crypto.subtle) return;
+  await safely("identify", async () => {
+    const fields = {
+      em: String(email ?? "").trim().toLowerCase(),
+      ph: String(phone ?? "").replace(/\D/g, ""),
+      fn: String(firstName ?? "").trim().toLowerCase(),
+      ln: String(lastName ?? "").trim().toLowerCase(),
+    };
+    const hashed = {};
+    for (const [key, value] of Object.entries(fields)) {
+      if (value) hashed[key] = await sha256(value);
+    }
+    if (!Object.keys(hashed).length) return;
+    for (const id of state.pixelIds) window.fbq("init", id, hashed);
+  });
+}
+
+/* ------------------------------------------------------------------- export */
+
+const api = {
+  start,
+  setCurrency,
+  setConsent,
+  routeChanged,
+  isEnabled: enabled,
+  pageView,
+  viewItem,
+  viewItemList,
+  selectItem,
+  peekCartLine,
+  rememberCart,
+  resetCart,
+  cartEdited,
+  viewCart,
+  beginCheckout,
+  addShippingInfo,
+  addPaymentInfo,
+  purchase,
+  search,
+  signUp,
+  login,
+  addToWishlist,
+  lead,
+  contact,
+  identify,
+};
+
+export const analytics = Object.fromEntries(
+  Object.entries(api).map(([name, fn]) => [
+    name,
+    (...args) => {
+      try {
+        return fn(...args);
+      } catch (error) {
+        if (import.meta.dev) console.warn(`[analytics] ${name} failed:`, error);
+        return undefined;
+      }
+    },
+  ])
+);