create-brainerce-store 1.62.0 → 1.64.0

package/templates/nextjs/base/src/core/lib/product-options.ts

@@ -1,121 +1,121 @@
-/**
- * Pure product-option logic (zero markup) shared by `core/hooks/use-product-page`
- * and the `ui/product` option components. Moved verbatim from
- * `customization-fields.tsx` / `modifier-group-selector.tsx` so that core
- * never depends on `ui/` — the UI components re-export these for
- * backward compatibility.
- */
-
-import type { ModifierGroup, ModifierSelection, ProductCustomizationField } from 'brainerce';
-
-export type CustomizationValues = Record<string, unknown>;
-
-export function validateCustomization(
-  fields: ProductCustomizationField[],
-  values: CustomizationValues
-): Record<string, string> {
-  const errors: Record<string, string> = {};
-  for (const field of fields) {
-    const value = values[field.key];
-    const empty =
-      value === undefined ||
-      value === null ||
-      value === '' ||
-      (Array.isArray(value) && value.length === 0);
-
-    if (field.required && empty) {
-      errors[field.key] = 'required';
-      continue;
-    }
-    if (empty) continue;
-
-    if (field.type === 'SELECT') {
-      const allowed = (field.enumValues ?? []).map((o) => o.value);
-      if (typeof value !== 'string' || !allowed.includes(value)) {
-        errors[field.key] = 'invalidOption';
-      }
-    }
-    if (field.type === 'MULTI_SELECT') {
-      const allowed = (field.enumValues ?? []).map((o) => o.value);
-      if (
-        !Array.isArray(value) ||
-        !(value as unknown[]).every((v) => typeof v === 'string' && allowed.includes(v as string))
-      ) {
-        errors[field.key] = 'invalidOption';
-      }
-    }
-  }
-  return errors;
-}
-
-/**
- * Lightweight client-side validation that mirrors the server's checks. Use
- * this to gate the add-to-cart button — but always treat the server's 400
- * (`MODIFIER_VALIDATION_FAILED`) as the authoritative answer.
- */
-export function validateSelections(
-  groups: ModifierGroup[],
-  selections: Record<string, string[]>
-): string | null {
-  for (const group of groups) {
-    if (group.max === 0) continue; // disabled-for-variant — skip
-    const picks = selections[group.id] ?? [];
-    if (group.required && picks.length === 0) {
-      return `${group.name} is required`;
-    }
-    if (picks.length < group.min) {
-      return `Pick at least ${group.min} from ${group.name}`;
-    }
-    if (group.max != null && picks.length > group.max) {
-      return `Pick at most ${group.max} from ${group.name}`;
-    }
-    if (group.selectionType === 'SINGLE' && picks.length > 1) {
-      return `Only one option allowed in ${group.name}`;
-    }
-  }
-  return null;
-}
-
-/**
- * Adapter: convert the local Record<groupId, modifierIds> shape used by the
- * selector component into the wire-format `ModifierSelection[]` array the SDK
- * expects on `addToCart` / `updateCartItem`.
- */
-export function toModifierSelections(
-  groups: ModifierGroup[],
-  selections: Record<string, string[]>
-): ModifierSelection[] {
-  const out: ModifierSelection[] = [];
-  for (const group of groups) {
-    if (group.max === 0) continue;
-    const picks = selections[group.id] ?? [];
-    if (picks.length === 0) continue;
-    out.push({ modifierGroupId: group.id, modifierIds: picks });
-  }
-  return out;
-}
-
-/**
- * Build the initial selection map from the group's defaults — call once on
- * first render for each group. Honors `defaultModifierIds` first (per-attach
- * defaults), falling back to per-modifier `isDefault` flags. Sold-out
- * modifiers are filtered out so the user doesn't start with an invalid pick.
- */
-export function buildInitialSelections(groups: ModifierGroup[]): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
-  for (const group of groups) {
-    if (group.max === 0) continue;
-    const fromDefaults = group.defaultModifierIds ?? [];
-    const fromIsDefault = group.modifiers
-      .filter((m) => m.isDefault && m.available)
-      .map((m) => m.id);
-    const merged =
-      fromDefaults.length > 0
-        ? fromDefaults.filter((id) => group.modifiers.some((m) => m.id === id && m.available))
-        : fromIsDefault;
-    // Cap by max for SINGLE groups — defaults can't violate selection rules.
-    const capped = group.selectionType === 'SINGLE' ? merged.slice(0, 1) : merged;
-    if (capped.length > 0) out[group.id] = capped;
-  }
-  return out;
-}
+/**
+ * Pure product-option logic (zero markup) shared by `core/hooks/use-product-page`
+ * and the `ui/product` option components. Moved verbatim from
+ * `customization-fields.tsx` / `modifier-group-selector.tsx` so that core
+ * never depends on `ui/` — the UI components re-export these for
+ * backward compatibility.
+ */
+
+import type { ModifierGroup, ModifierSelection, ProductCustomizationField } from 'brainerce';
+
+export type CustomizationValues = Record<string, unknown>;
+
+export function validateCustomization(
+  fields: ProductCustomizationField[],
+  values: CustomizationValues
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const field of fields) {
+    const value = values[field.key];
+    const empty =
+      value === undefined ||
+      value === null ||
+      value === '' ||
+      (Array.isArray(value) && value.length === 0);
+
+    if (field.required && empty) {
+      errors[field.key] = 'required';
+      continue;
+    }
+    if (empty) continue;
+
+    if (field.type === 'SELECT') {
+      const allowed = (field.enumValues ?? []).map((o) => o.value);
+      if (typeof value !== 'string' || !allowed.includes(value)) {
+        errors[field.key] = 'invalidOption';
+      }
+    }
+    if (field.type === 'MULTI_SELECT') {
+      const allowed = (field.enumValues ?? []).map((o) => o.value);
+      if (
+        !Array.isArray(value) ||
+        !(value as unknown[]).every((v) => typeof v === 'string' && allowed.includes(v as string))
+      ) {
+        errors[field.key] = 'invalidOption';
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Lightweight client-side validation that mirrors the server's checks. Use
+ * this to gate the add-to-cart button — but always treat the server's 400
+ * (`MODIFIER_VALIDATION_FAILED`) as the authoritative answer.
+ */
+export function validateSelections(
+  groups: ModifierGroup[],
+  selections: Record<string, string[]>
+): string | null {
+  for (const group of groups) {
+    if (group.max === 0) continue; // disabled-for-variant — skip
+    const picks = selections[group.id] ?? [];
+    if (group.required && picks.length === 0) {
+      return `${group.name} is required`;
+    }
+    if (picks.length < group.min) {
+      return `Pick at least ${group.min} from ${group.name}`;
+    }
+    if (group.max != null && picks.length > group.max) {
+      return `Pick at most ${group.max} from ${group.name}`;
+    }
+    if (group.selectionType === 'SINGLE' && picks.length > 1) {
+      return `Only one option allowed in ${group.name}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Adapter: convert the local Record<groupId, modifierIds> shape used by the
+ * selector component into the wire-format `ModifierSelection[]` array the SDK
+ * expects on `addToCart` / `updateCartItem`.
+ */
+export function toModifierSelections(
+  groups: ModifierGroup[],
+  selections: Record<string, string[]>
+): ModifierSelection[] {
+  const out: ModifierSelection[] = [];
+  for (const group of groups) {
+    if (group.max === 0) continue;
+    const picks = selections[group.id] ?? [];
+    if (picks.length === 0) continue;
+    out.push({ modifierGroupId: group.id, modifierIds: picks });
+  }
+  return out;
+}
+
+/**
+ * Build the initial selection map from the group's defaults — call once on
+ * first render for each group. Honors `defaultModifierIds` first (per-attach
+ * defaults), falling back to per-modifier `isDefault` flags. Sold-out
+ * modifiers are filtered out so the user doesn't start with an invalid pick.
+ */
+export function buildInitialSelections(groups: ModifierGroup[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const group of groups) {
+    if (group.max === 0) continue;
+    const fromDefaults = group.defaultModifierIds ?? [];
+    const fromIsDefault = group.modifiers
+      .filter((m) => m.isDefault && m.available)
+      .map((m) => m.id);
+    const merged =
+      fromDefaults.length > 0
+        ? fromDefaults.filter((id) => group.modifiers.some((m) => m.id === id && m.available))
+        : fromIsDefault;
+    // Cap by max for SINGLE groups — defaults can't violate selection rules.
+    const capped = group.selectionType === 'SINGLE' ? merged.slice(0, 1) : merged;
+    if (capped.length > 0) out[group.id] = capped;
+  }
+  return out;
+}

package/templates/nextjs/base/src/core/lib/resolve-currency.ts

@@ -1,20 +1,20 @@
-import type { PublicStoreInfo } from '@/core/lib/store-info';
-
-/**
- * Server-side twin of `useCurrency()` — call from Server Components,
- * `generateMetadata`, route handlers, and anywhere outside React render
- * (where the client `useStoreInfo()` hook isn't available).
- *
- * Keeps the fallback chain in one place across both client and server.
- *
- * @param storeInfo result of `fetchStoreInfo()` — may be null if the SSR
- *                  fetch failed transiently
- * @param override  pass when the caller already has a specific currency
- *                  (e.g. order-level currency that should win over store)
- */
-export function resolveCurrency(
-  storeInfo: PublicStoreInfo | null | undefined,
-  override?: string | null
-): string {
-  return override || storeInfo?.currency || process.env.NEXT_PUBLIC_STORE_CURRENCY || 'USD';
-}
+import type { PublicStoreInfo } from '@/core/lib/store-info';
+
+/**
+ * Server-side twin of `useCurrency()` — call from Server Components,
+ * `generateMetadata`, route handlers, and anywhere outside React render
+ * (where the client `useStoreInfo()` hook isn't available).
+ *
+ * Keeps the fallback chain in one place across both client and server.
+ *
+ * @param storeInfo result of `fetchStoreInfo()` — may be null if the SSR
+ *                  fetch failed transiently
+ * @param override  pass when the caller already has a specific currency
+ *                  (e.g. order-level currency that should win over store)
+ */
+export function resolveCurrency(
+  storeInfo: PublicStoreInfo | null | undefined,
+  override?: string | null
+): string {
+  return override || storeInfo?.currency || process.env.NEXT_PUBLIC_STORE_CURRENCY || 'USD';
+}

package/templates/nextjs/base/src/core/lib/safe-redirect.ts

@@ -1,38 +1,38 @@
-// Re-export the platform-maintained payment URL allowlist from the SDK.
-//
-// Why a re-export and not a direct import everywhere: keeping a stable
-// `@/core/lib/safe-redirect` import path means future SDK API changes (e.g. an
-// `extraHosts` rename) only need editing here, and merchants don't have to
-// touch every component that does payment redirects. It also leaves a clear
-// place to plug in store-specific extras (custom self-hosted PSP) without
-// scattering option objects across components.
-//
-// The allowlist itself now lives in the `brainerce` package — running
-// `npm update brainerce` picks up new payment providers and platform
-// embed domains automatically.
-
-import {
-  isAllowedPaymentUrl as sdkIsAllowedPaymentUrl,
-  safePaymentRedirect as sdkSafePaymentRedirect,
-} from 'brainerce';
-
-// Dev-only: allow http://localhost|127.0.0.1 so the local storefront can
-// iframe the local backend's embed proxy. Inlined to a literal at build time
-// by Next.js, so the allow path is stripped from production bundles.
-const allowLocalhost = process.env.NODE_ENV !== 'production';
-
-export function isAllowedPaymentUrl(url: string): boolean {
-  return sdkIsAllowedPaymentUrl(url, { allowLocalhost });
-}
-
-export function safePaymentRedirect(url: string): void {
-  sdkSafePaymentRedirect(url, { allowLocalhost });
-}
-
-// CUID format used by Prisma for Checkout.id — c + 24 lowercase alphanumeric chars.
-// Allow a small range to tolerate cuid2 (slightly different length).
-const CHECKOUT_ID_RE = /^c[a-z0-9]{20,30}$/;
-
-export function isValidCheckoutId(id: unknown): id is string {
-  return typeof id === 'string' && CHECKOUT_ID_RE.test(id);
-}
+// Re-export the platform-maintained payment URL allowlist from the SDK.
+//
+// Why a re-export and not a direct import everywhere: keeping a stable
+// `@/core/lib/safe-redirect` import path means future SDK API changes (e.g. an
+// `extraHosts` rename) only need editing here, and merchants don't have to
+// touch every component that does payment redirects. It also leaves a clear
+// place to plug in store-specific extras (custom self-hosted PSP) without
+// scattering option objects across components.
+//
+// The allowlist itself now lives in the `brainerce` package — running
+// `npm update brainerce` picks up new payment providers and platform
+// embed domains automatically.
+
+import {
+  isAllowedPaymentUrl as sdkIsAllowedPaymentUrl,
+  safePaymentRedirect as sdkSafePaymentRedirect,
+} from 'brainerce';
+
+// Dev-only: allow http://localhost|127.0.0.1 so the local storefront can
+// iframe the local backend's embed proxy. Inlined to a literal at build time
+// by Next.js, so the allow path is stripped from production bundles.
+const allowLocalhost = process.env.NODE_ENV !== 'production';
+
+export function isAllowedPaymentUrl(url: string): boolean {
+  return sdkIsAllowedPaymentUrl(url, { allowLocalhost });
+}
+
+export function safePaymentRedirect(url: string): void {
+  sdkSafePaymentRedirect(url, { allowLocalhost });
+}
+
+// CUID format used by Prisma for Checkout.id — c + 24 lowercase alphanumeric chars.
+// Allow a small range to tolerate cuid2 (slightly different length).
+const CHECKOUT_ID_RE = /^c[a-z0-9]{20,30}$/;
+
+export function isValidCheckoutId(id: unknown): id is string {
+  return typeof id === 'string' && CHECKOUT_ID_RE.test(id);
+}

package/templates/nextjs/base/src/core/lib/seo.ts

@@ -1,46 +1,46 @@
-// SEO helpers for meta tags and JSON-LD. Strips HTML and decodes common
-// entities so seller-authored rich-text descriptions don't leak markup into
-// <meta name="description">, og:description, twitter:description, or
-// schema.org Product.description.
-
-const NAMED_ENTITIES: Record<string, string> = {
-  nbsp: ' ',
-  amp: '&',
-  lt: '<',
-  gt: '>',
-  quot: '"',
-  apos: "'",
-};
-
-function decodeEntities(text: string): string {
-  return text
-    .replace(/&(nbsp|amp|lt|gt|quot|apos);/g, (_, name: string) => NAMED_ENTITIES[name] ?? '')
-    .replace(/&#(\d+);/g, (_, code: string) => String.fromCodePoint(Number(code)))
-    .replace(/&#x([0-9a-f]+);/gi, (_, code: string) => String.fromCodePoint(parseInt(code, 16)));
-}
-
-// Strip HTML tags, decode entities, collapse whitespace. Idempotent on plain text.
-export function stripHtmlForSeo(input: string | null | undefined): string {
-  if (!input) return '';
-  return decodeEntities(input.replace(/<[^>]*>/g, ' '))
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-// Build a meta description from raw HTML/text.
-// Truncates at the nearest word boundary so we never cut mid-word, and
-// appends a Unicode ellipsis. Returns '' for null/empty input so callers
-// can fall back cleanly.
-export function buildMetaDescription(input: string | null | undefined, maxLength = 160): string {
-  const stripped = stripHtmlForSeo(input);
-  if (!stripped) return '';
-  if (stripped.length <= maxLength) return stripped;
-
-  const room = maxLength - 1; // leave room for ellipsis
-  const cut = stripped.slice(0, room);
-  const lastSpace = cut.lastIndexOf(' ');
-  // Only break on word boundary when it's reasonably close to the cap — otherwise
-  // a single very long word would shrink the description to almost nothing.
-  const safeCut = lastSpace > room * 0.7 ? cut.slice(0, lastSpace) : cut;
-  return `${safeCut.trim()}…`;
-}
+// SEO helpers for meta tags and JSON-LD. Strips HTML and decodes common
+// entities so seller-authored rich-text descriptions don't leak markup into
+// <meta name="description">, og:description, twitter:description, or
+// schema.org Product.description.
+
+const NAMED_ENTITIES: Record<string, string> = {
+  nbsp: ' ',
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+};
+
+function decodeEntities(text: string): string {
+  return text
+    .replace(/&(nbsp|amp|lt|gt|quot|apos);/g, (_, name: string) => NAMED_ENTITIES[name] ?? '')
+    .replace(/&#(\d+);/g, (_, code: string) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code: string) => String.fromCodePoint(parseInt(code, 16)));
+}
+
+// Strip HTML tags, decode entities, collapse whitespace. Idempotent on plain text.
+export function stripHtmlForSeo(input: string | null | undefined): string {
+  if (!input) return '';
+  return decodeEntities(input.replace(/<[^>]*>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// Build a meta description from raw HTML/text.
+// Truncates at the nearest word boundary so we never cut mid-word, and
+// appends a Unicode ellipsis. Returns '' for null/empty input so callers
+// can fall back cleanly.
+export function buildMetaDescription(input: string | null | undefined, maxLength = 160): string {
+  const stripped = stripHtmlForSeo(input);
+  if (!stripped) return '';
+  if (stripped.length <= maxLength) return stripped;
+
+  const room = maxLength - 1; // leave room for ellipsis
+  const cut = stripped.slice(0, room);
+  const lastSpace = cut.lastIndexOf(' ');
+  // Only break on word boundary when it's reasonably close to the cap — otherwise
+  // a single very long word would shrink the description to almost nothing.
+  const safeCut = lastSpace > room * 0.7 ? cut.slice(0, lastSpace) : cut;
+  return `${safeCut.trim()}…`;
+}

package/templates/nextjs/base/src/core/lib/store-info.ts

@@ -25,6 +25,21 @@ export interface PublicStoreInfo {
   i18n?: StoreInfo['i18n'];
   /** Real flat-rate/free shipping zones — feeds Product JSON-LD `shippingDetails`. Public by design (merchants display shipping rates openly). */
   shipping?: StoreInfo['shipping'];
+  /**
+   * Marketing tag ids (GA4 / GTM / Meta / TikTok) resolved from the apps the
+   * merchant connected in the Brainerce dashboard. Public by design — these
+   * ids appear in the page source of every storefront that runs a tag, and the
+   * backend format-validates them before serving. Consumed by
+   * `<TrackingBootstrap>`; nothing else should read them.
+   */
+  tracking?: StoreInfo['tracking'];
+  /**
+   * SEO surface: IndexNow key (served at /indexnow-key.txt) and the Google
+   * site-verification token (rendered as a meta tag in the root layout so the
+   * merchant can verify the domain in Search Console / claim it in Merchant
+   * Center). Both public by protocol design.
+   */
+  seo?: StoreInfo['seo'];
 }
 
 /**
@@ -47,5 +62,7 @@ export function pickPublicStoreInfo(raw: StoreInfo): PublicStoreInfo {
     upsell: raw.upsell,
     i18n: raw.i18n,
     shipping: raw.shipping,
+    tracking: raw.tracking,
+    seo: raw.seo,
   };
 }

package/templates/nextjs/base/src/core/lib/tracking.ts

@@ -0,0 +1,171 @@
+import type { Cart, Order, Product, ProductVariant, TrackingEventItem } from 'brainerce';
+import { getCartTotals } from 'brainerce';
+
+import { getClient } from './brainerce';
+
+/**
+ * E-commerce event reporting for the merchant's marketing tags.
+ *
+ * `<TrackingBootstrap>` loads whichever tags the merchant connected; these
+ * helpers describe what the shopper did. Both halves are needed: a Google Tag
+ * Manager container with no events is an empty container, and Meta cannot
+ * optimize a campaign it never sees a `Purchase` for.
+ *
+ * Every function is a no-op when no tag is loaded, so calling them is always
+ * safe and never needs a feature check at the call site.
+ *
+ * ## Item ids
+ *
+ * `itemId` is always the **SKU**. That is the id Brainerce publishes to the
+ * Google Merchant Center and Meta catalog feeds, so it is the only id the ad
+ * platforms can match a pixel event against. Sending a product or variant id
+ * instead breaks attribution and dynamic remarketing silently — the events
+ * arrive, the platform reports an id its catalog has never seen, and the
+ * remarketing audience never builds.
+ */
+
+/** Parse a Brainerce decimal string (`"29.99"`) into a number. */
+function toNumber(value: string | number | null | undefined): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  const parsed = typeof value === 'number' ? value : parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Resolve the SKU for a product/variant pair, falling back to the variant then
+ * product id only when the catalog has no SKU at all — a feed-less product
+ * can't be attributed either way, and dropping the event entirely would hide
+ * real shopper behaviour from GA4 too.
+ */
+function resolveItemId(product: Product, variant?: ProductVariant | null): string {
+  return variant?.sku || product.sku || variant?.id || product.id;
+}
+
+/** The shopper opened a product detail page. */
+export function trackProductView(
+  product: Product,
+  variant: ProductVariant | null | undefined,
+  price: number | undefined,
+  currency: string | undefined
+): void {
+  getClient().trackMarketingEvent('view_item', {
+    currency,
+    value: price,
+    items: [
+      {
+        itemId: resolveItemId(product, variant),
+        itemName: product.name,
+        price,
+        quantity: 1,
+        ...(variant?.name ? { itemVariant: variant.name } : {}),
+      },
+    ],
+  });
+}
+
+/** The shopper added a line to the cart. */
+export function trackAddToCart(
+  product: Product,
+  variant: ProductVariant | null | undefined,
+  quantity: number,
+  price: number | undefined,
+  currency: string | undefined
+): void {
+  getClient().trackMarketingEvent('add_to_cart', {
+    currency,
+    value: price !== undefined ? price * quantity : undefined,
+    items: [
+      {
+        itemId: resolveItemId(product, variant),
+        itemName: product.name,
+        price,
+        quantity,
+        ...(variant?.name ? { itemVariant: variant.name } : {}),
+      },
+    ],
+  });
+}
+
+/** Map cart lines onto tracking items. */
+function cartItems(cart: Cart): TrackingEventItem[] {
+  return (cart.items ?? []).map((item) => ({
+    // The cart line carries product + variant snapshots; prefer the variant's
+    // SKU for the same catalog-parity reason as `resolveItemId`.
+    itemId: item.variant?.sku || item.product?.sku || item.variantId || item.productId,
+    itemName: item.product?.name,
+    price: toNumber(item.currentUnitPrice ?? item.unitPrice),
+    quantity: item.quantity,
+    ...(item.variant?.name ? { itemVariant: item.variant.name } : {}),
+  }));
+}
+
+/**
+ * The shopper landed on the checkout page.
+ *
+ * Shipping is not known at this point (no address yet), so the value is the
+ * cart total without it — which is what GA4's `begin_checkout` expects.
+ */
+export function trackBeginCheckout(cart: Cart, currency: string | undefined): void {
+  getClient().trackMarketingEvent('begin_checkout', {
+    currency,
+    value: getCartTotals(cart).total,
+    items: cartItems(cart),
+  });
+}
+
+/**
+ * Key under which a reported order id is remembered for this tab.
+ *
+ * Prefixed per order rather than a single "last order" slot so a shopper who
+ * places two orders in one session gets both reported exactly once.
+ */
+const PURCHASE_KEY_PREFIX = 'brainerce_purchase_tracked:';
+
+/**
+ * The order is paid — report the conversion, at most once per order.
+ *
+ * Two independent guards, because double-counted revenue is the failure that
+ * quietly ruins a merchant's ROAS reporting:
+ *
+ *   1. `sessionStorage` stops a page refresh or a back-button return from
+ *      re-firing the event at all.
+ *   2. The order id travels as GA4's `transaction_id`, Meta's `eventID` and
+ *      TikTok's `event_id`, so even a send that slips past guard 1 (new tab,
+ *      cleared storage) de-duplicates on the vendor's side.
+ *
+ * Note the event fires on the confirmation page, which a shopper can always
+ * fail to reach — closing the tab after paying, or an iframe provider that
+ * lands them on `/payment-complete`. Browser-side conversion tracking is
+ * lossy by nature; Brainerce's server-side GA4 purchase event (sent from the
+ * backend when the order is paid) is what covers that gap for Google.
+ */
+export function trackPurchase(order: Order): void {
+  if (typeof window === 'undefined' || !order?.id) return;
+
+  const key = `${PURCHASE_KEY_PREFIX}${order.id}`;
+  try {
+    if (window.sessionStorage.getItem(key)) return;
+    window.sessionStorage.setItem(key, '1');
+  } catch {
+    // Private mode / storage disabled — fall through and rely on the
+    // vendor-side transaction id de-dupe rather than skipping the conversion.
+  }
+
+  getClient().trackMarketingEvent('purchase', {
+    transactionId: order.id,
+    currency: order.currency,
+    value: toNumber(order.total ?? order.totalAmount),
+    shipping: toNumber(order.shippingAmount),
+    // In inclusive (VAT) pricing `taxAmount` is "0" and the real VAT lives in
+    // the frozen breakdown — reporting the 0 would understate tax on every
+    // order for every VAT-region merchant.
+    tax: toNumber(order.taxBreakdown?.totalTax) ?? toNumber(order.taxAmount),
+    coupon: order.couponCode ?? undefined,
+    items: (order.items ?? []).map((item) => ({
+      itemId: item.sku || item.variantId || item.productId,
+      itemName: item.name,
+      price: toNumber(item.price),
+      quantity: item.quantity,
+    })),
+  });
+}