@cartbase/storefront 0.1.0

package/src/tracking/fbq.ts

@@ -0,0 +1,168 @@
+"use client"
+
+import type {
+  AddToCartData,
+  InitiateCheckoutData,
+  LeadData,
+  PurchaseData,
+  ViewContentData,
+} from "./types"
+
+/**
+ * Typed wrappers around the global `fbq()` from Meta Pixel.
+ *
+ * Ported from `@1click/ui/src/tracking/fbq.ts` (v2.3.1) with ONE deliberate
+ * seam change: the browser-side `fireCapiEvent` dual-fire is REMOVED —
+ * in barter, server-side Conversions API sending is backend-owned (the
+ * `order.placed` forwarder, `src/lib/tracking/forward.ts` + admin-api.md
+ * §34). This package fires CLIENT Pixel events only; the ad-blocked /
+ * iOS-ATT recovery the dual-fire provided is covered by the backend CAPI
+ * Purchase, which inherits fbp/fbc/anon-id from the attribution keys the
+ * storefront writes into `cart.metadata` (see get-tracking-attribution.ts).
+ *
+ * Event-id contract (unchanged — the part that must never drift):
+ *   - Purchase: `eventID = "purchase_" + order.display_id`, built by
+ *     `trackPurchase()` from the caller's `order.display_id` so the format
+ *     can never drift. The backend CAPI Purchase uses the SAME id
+ *     (`purchaseEventId()` in `src/lib/tracking/constants.ts`); Meta
+ *     dedupes browser Pixel + server CAPI by event_name + event_id
+ *     within ~3 days.
+ *   - Everything else: `<eventname>_<unixSeconds>_<6 hex>` via
+ *     `generateEventId()` (the exact @1click capi.ts format, mirrored
+ *     by `src/lib/tracking/constants.ts generateEventId`).
+ *
+ * All helpers no-op when `window.fbq` is undefined (pixel not loaded —
+ * SSR, ad-blocker, admin disabled). Storefronts can call them freely
+ * without guards.
+ */
+
+type FbqFn = {
+  (command: "init", pixelId: string): void
+  /** Re-init with Advanced Matching params (em / ph / fn / ln / ct / zp,
+   *  pre-hashed). Per Meta docs the Pixel merges these with any prior
+   *  init values and applies them to ALL subsequent track() calls. */
+  (
+    command: "init",
+    pixelId: string,
+    advancedMatching: Record<string, string>
+  ): void
+  (
+    command: "track",
+    eventName: string,
+    data?: Record<string, unknown>,
+    options?: { eventID?: string }
+  ): void
+  (
+    command: "trackCustom",
+    eventName: string,
+    data?: Record<string, unknown>,
+    options?: { eventID?: string }
+  ): void
+  callMethod?: (...args: unknown[]) => void
+  queue: unknown[]
+  loaded: boolean
+  version: string
+}
+
+declare global {
+  interface Window {
+    fbq?: FbqFn
+  }
+}
+
+function safeFbq(): FbqFn | null {
+  if (typeof window === "undefined") return null
+  return window.fbq ?? null
+}
+
+/**
+ * Random event_id for events without a natural stable id —
+ * `<eventName.toLowerCase()>_<unixSeconds>_<6 hex chars>`, the exact
+ * @1click capi.ts:188-201 format (mirrored server-side by
+ * `src/lib/tracking/constants.ts generateEventId`). Exported so callers
+ * that hand the id to a backend route (e.g. Lead → subscribe endpoint)
+ * can share it across browser + server fires.
+ */
+export function generateEventId(eventName: string): string {
+  const ts = Math.floor(Date.now() / 1000)
+  const rand = (() => {
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+      const buf = new Uint8Array(3)
+      crypto.getRandomValues(buf)
+      return Array.from(buf)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("")
+    }
+    return Math.random().toString(16).slice(2, 8)
+  })()
+  return `${eventName.toLowerCase()}_${ts}_${rand}`
+}
+
+export function trackViewContent(data: ViewContentData): void {
+  const fbq = safeFbq()
+  if (!fbq) return
+  fbq("track", "ViewContent", data as unknown as Record<string, unknown>, {
+    eventID: generateEventId("ViewContent"),
+  })
+}
+
+export function trackAddToCart(data: AddToCartData): void {
+  const fbq = safeFbq()
+  if (!fbq) return
+  fbq("track", "AddToCart", data as unknown as Record<string, unknown>, {
+    eventID: generateEventId("AddToCart"),
+  })
+}
+
+export function trackInitiateCheckout(data: InitiateCheckoutData): void {
+  const fbq = safeFbq()
+  if (!fbq) return
+  fbq("track", "InitiateCheckout", data as unknown as Record<string, unknown>, {
+    eventID: generateEventId("InitiateCheckout"),
+  })
+}
+
+/**
+ * Purchase event — eventID MUST equal `purchase_${order.display_id}`
+ * to dedupe with the barter backend's order.placed CAPI Purchase.
+ * Caller passes `order.display_id`; this helper builds the id so the
+ * format can never drift between the two sides.
+ */
+export function trackPurchase(
+  data: PurchaseData,
+  orderDisplayId: string | number
+): void {
+  const fbq = safeFbq()
+  if (!fbq) return
+  fbq("track", "Purchase", data as unknown as Record<string, unknown>, {
+    eventID: `purchase_${orderDisplayId}`,
+  })
+}
+
+export type LeadContext = {
+  /** Override the auto-generated event id. Used by callers that need
+   *  to send the same id to a backend route so server-side CAPI can
+   *  dedupe with the browser-fired Pixel event. */
+  eventId?: string
+}
+
+/**
+ * Lead event — fired when a visitor submits the marketing popup or
+ * any newsletter signup form. Highest-intent pre-purchase signal.
+ * Without this Meta has no way to optimize ad delivery for "likely
+ * subscribers" or build a Lead lookalike audience from our funnel.
+ *
+ * Returns the eventId so the caller can pass it to a backend route —
+ * a server-side CAPI Lead with the same id dedupes against this
+ * browser fire.
+ */
+export function trackLead(data: LeadData = {}, context: LeadContext = {}): string {
+  const eventId = context.eventId ?? generateEventId("Lead")
+  const fbq = safeFbq()
+  if (fbq) {
+    fbq("track", "Lead", data as unknown as Record<string, unknown>, {
+      eventID: eventId,
+    })
+  }
+  return eventId
+}

package/src/tracking/ga4.tsx

@@ -0,0 +1,49 @@
+"use client"
+
+import Script from "next/script"
+
+/**
+ * GA4 — Google Analytics 4 base script loader.
+ *
+ * Loads `https://www.googletagmanager.com/gtag/js?id=<measurementId>` via
+ * Next.js `<Script strategy="afterInteractive">` and initialises gtag with
+ * the given measurement ID. Once loaded, gtag automatically sets the
+ * `_ga` and `_ga_<MEASUREMENT_ID>` first-party cookies, which the server
+ * action `getTrackingAttribution` then reads on cart completion to
+ * forward `ga_client_id` / `ga_session_id` into the order metadata for
+ * GA4 Measurement Protocol Purchase events.
+ *
+ * Renders nothing when `measurementId` is falsy — every consuming layout
+ * can call this unconditionally; the script is only injected when the
+ * admin has configured GA4.
+ *
+ * `send_page_view: true` (default) — initial page_view fires automatically
+ * on script load. Subsequent SPA route changes are NOT auto-tracked by
+ * gtag; storefronts that need per-route page_views should call
+ * `gtag('event', 'page_view', { page_path })` from a route-change effect.
+ */
+export function GA4({ measurementId }: { measurementId?: string }) {
+  if (!measurementId) return null
+
+  const initSnippet = `
+window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+gtag('config', '${measurementId}');
+`.trim()
+
+  return (
+    <>
+      <Script
+        id="ga4-loader"
+        strategy="afterInteractive"
+        src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
+      />
+      <Script
+        id="ga4-init"
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{ __html: initSnippet }}
+      />
+    </>
+  )
+}

package/src/tracking/get-tracking-attribution.ts

@@ -0,0 +1,224 @@
+import { cookies, headers } from "next/headers"
+
+import { getTrackingConfig } from "./get-tracking-config"
+import type { StorefrontClient } from "../api/http"
+import type { TrackingAttribution, TrackingClientHints } from "./types"
+
+/**
+ * Reads Meta + GA4 attribution signals from the current Next.js server
+ * request and returns the payload to write into `cart.metadata` before
+ * completion (consent-gated — only capture when the visitor's `_1c_consent`
+ * choice allows it; see store-api.md "Tracking block" wiring contract).
+ * Cart completion copies the keys onto `order.metadata`
+ * (`src/lib/carts/complete/_order.ts`) and the barter `order.placed`
+ * forwarder reads exactly these keys to build the CAPI Purchase event's
+ * `user_data` and the GA4 Measurement Protocol Purchase's `client_id` /
+ * `session_id`.
+ *
+ * SERVER-ONLY: imports `next/headers` — call it from RSC / server actions
+ * only (the @1click original carried a `server-only` import; this package
+ * keeps the constraint by construction since `next/headers` throws outside
+ * a request scope).
+ *
+ * Adaptation vs `@1click/ui`: resolving the `_ga_<MEASUREMENT_ID>` session
+ * cookie needs the GA4 measurement id, which the original fetched from env
+ * config. Pass either `opts.ga4MeasurementId` (when the layout already
+ * fetched the tracking config) or `opts.client` (a `StorefrontClient`; the
+ * config fetch is cached 5 min). With neither, the fb_* / utm_* keys and
+ * `ga_client_id` still resolve — only `ga_session_id` is skipped.
+ *
+ * Server-readable (this function reads from cookies/headers):
+ *   - fb_fbp, fb_fbc            — _fbp / _fbc cookies (set by fbq init)
+ *   - fb_anon_id                — _1c_anon cookie (attribution.ts)
+ *   - fb_user_agent             — User-Agent request header
+ *   - fb_client_ip              — x-forwarded-for / x-real-ip header
+ *   - fb_event_source_url       — Referer header
+ *   - ga_client_id              — _ga cookie, schema prefix stripped
+ *   - ga_session_id             — _ga_<MEASUREMENT_ID> cookie, session segment
+ *   - utm_first_* / utm_last_*  — _1c_utm_first / _1c_utm_last cookies
+ *
+ * Client-only (passed via `clientHints` because the browser computes it):
+ *   - ga_engagement_time_msec   — accumulated time-on-session in ms
+ *
+ * Returns an object with only the fields that resolved (no undefined
+ * keys), so spreading into existing metadata won't clobber other values.
+ */
+export async function getTrackingAttribution(
+  clientHints?: TrackingClientHints,
+  opts?: {
+    /** SDK client used to fetch the tracking config (for the GA4 id). */
+    client?: StorefrontClient
+    /** Skip the config fetch by passing the GA4 measurement id directly. */
+    ga4MeasurementId?: string
+  }
+): Promise<TrackingAttribution> {
+  const result: TrackingAttribution = {}
+
+  // Cookies (best-effort — throws outside a request context)
+  let fbp: string | undefined
+  let fbc: string | undefined
+  let anonId: string | undefined
+  let gaCookieRaw: string | undefined
+  let gaSessionCookieRaw: string | undefined
+
+  let utmFirstRaw: string | undefined
+  let utmLastRaw: string | undefined
+
+  try {
+    const cookieStore = await cookies()
+    fbp = cookieStore.get("_fbp")?.value
+    fbc = cookieStore.get("_fbc")?.value
+    // _1c_anon — our self-managed per-browser visitor id, written by
+    // attribution.ts on first tracking call. Surfaces server-side here
+    // so the order.placed CAPI Purchase can include it as external_id
+    // (alongside customer_id when both exist — Meta accepts an array).
+    anonId = cookieStore.get("_1c_anon")?.value
+    gaCookieRaw = cookieStore.get("_ga")?.value
+    // _1c_utm_first / _1c_utm_last — JSON-encoded UTM tuples written
+    // by browser-side captureUtmsFromUrl(). First-touch records the
+    // acquisition campaign (365-day TTL); last-touch records the
+    // closer (90-day TTL, refreshed on each UTM-bearing visit).
+    utmFirstRaw = cookieStore.get("_1c_utm_first")?.value
+    utmLastRaw = cookieStore.get("_1c_utm_last")?.value
+
+    // _ga_<MEASUREMENT_ID> uses the GA4 measurementId (e.g., G-ABCDEF1234)
+    // with the "G-" prefix stripped: cookie name = `_ga_ABCDEF1234`.
+    // Look it up only if we can learn the measurementId.
+    let measurementId = opts?.ga4MeasurementId
+    if (!measurementId && opts?.client) {
+      const config = await getTrackingConfig(opts.client)
+      measurementId = config.ga4?.measurementId
+    }
+    if (measurementId) {
+      const cookieName = `_ga_${measurementId.replace(/^G-/, "")}`
+      gaSessionCookieRaw = cookieStore.get(cookieName)?.value
+    }
+  } catch {
+    // best-effort — fall through with what we have
+  }
+
+  if (fbp) result.fb_fbp = fbp
+  if (fbc) result.fb_fbc = fbc
+  if (anonId) result.fb_anon_id = anonId
+
+  // Flatten UTM cookies into utm_first_* / utm_last_* keys so the
+  // backend (and the order.metadata writeback that follows) can read
+  // them with simple JSON path queries — no jsonb_path_query needed.
+  // Missing keys are dropped from `result` (not set to undefined) so a
+  // partial-touch (e.g. utm_source only) doesn't pollute metadata with
+  // null fields.
+  applyUtmCookie(utmFirstRaw, "utm_first", result)
+  applyUtmCookie(utmLastRaw, "utm_last", result)
+
+  // _ga cookie format: "GA1.1.<client_id>.<timestamp>" — backend wants
+  // the full <client_id>.<timestamp> portion (the canonical GA client_id).
+  if (gaCookieRaw) {
+    const parts = gaCookieRaw.split(".")
+    // GA1 / GS1 schemas: cookie is "<schema>.<sequence>.<id>.<ts>" — the
+    // canonical client_id is the last two segments joined with a dot.
+    if (parts.length >= 4) {
+      result.ga_client_id = `${parts[2]}.${parts[3]}`
+    } else {
+      result.ga_client_id = gaCookieRaw
+    }
+  }
+
+  // _ga_<MEASUREMENT_ID> format: "GS1.1.<session_id>.<count>.<engaged>.<session_start>.<scroll>.<engagement_time>.0"
+  // session_id is at index 2.
+  if (gaSessionCookieRaw) {
+    const parts = gaSessionCookieRaw.split(".")
+    if (parts.length >= 3 && parts[2]) {
+      result.ga_session_id = parts[2]
+    }
+  }
+
+  // Headers (best-effort)
+  try {
+    const headerStore = await headers()
+    const ua = headerStore.get("user-agent")
+    if (ua) result.fb_user_agent = ua
+
+    // x-forwarded-for can be a chain of proxies; leftmost is the original client.
+    const xff = headerStore.get("x-forwarded-for")
+    const xri = headerStore.get("x-real-ip")
+    const ip = xff?.split(",")[0]?.trim() || xri || undefined
+    if (ip) result.fb_client_ip = ip
+
+    const referer = headerStore.get("referer")
+    if (referer) result.fb_event_source_url = referer
+  } catch {
+    // best-effort
+  }
+
+  // Client hints (engagement time — browser only)
+  if (
+    clientHints?.engagementTimeMsec !== undefined &&
+    clientHints.engagementTimeMsec >= 0
+  ) {
+    result.ga_engagement_time_msec = clientHints.engagementTimeMsec
+  }
+
+  return result
+}
+
+// ── UTM cookie parsing ───────────────────────────────────────────────
+
+type ParsedUtmCookie = {
+  utm_source?: string
+  utm_medium?: string
+  utm_campaign?: string
+  utm_term?: string
+  utm_content?: string
+  captured_at?: number
+}
+
+/**
+ * Decode a `_1c_utm_first` or `_1c_utm_last` cookie value (URI-encoded
+ * JSON) and flatten its fields onto the attribution result with the
+ * given prefix ("utm_first" or "utm_last"). Missing/blank UTM fields
+ * are dropped from `out` rather than written as undefined so a
+ * partial-touch never pollutes order.metadata with empty keys.
+ *
+ * Defensive against:
+ *   - Missing cookie (raw=undefined) → no-op
+ *   - Invalid URI encoding → caught + no-op
+ *   - Invalid JSON → caught + no-op
+ *   - Schema drift (captured_at missing or non-number) → no-op
+ *
+ * Treating malformed cookies as missing is the right call: a hostile
+ * or stale cookie shouldn't be able to inject keys into order.metadata
+ * via the type cast at the writeback boundary.
+ */
+function applyUtmCookie(
+  raw: string | undefined,
+  prefix: "utm_first" | "utm_last",
+  out: TrackingAttribution
+): void {
+  if (!raw) return
+  let parsed: ParsedUtmCookie | null = null
+  try {
+    parsed = JSON.parse(decodeURIComponent(raw)) as ParsedUtmCookie
+  } catch {
+    return
+  }
+  if (!parsed || typeof parsed.captured_at !== "number") return
+
+  // Spelling-out each field keeps the type system honest (rather than
+  // a string-keyed loop that would require `as any`).
+  if (parsed.utm_source) {
+    out[`${prefix}_source` as const] = parsed.utm_source
+  }
+  if (parsed.utm_medium) {
+    out[`${prefix}_medium` as const] = parsed.utm_medium
+  }
+  if (parsed.utm_campaign) {
+    out[`${prefix}_campaign` as const] = parsed.utm_campaign
+  }
+  if (parsed.utm_term) {
+    out[`${prefix}_term` as const] = parsed.utm_term
+  }
+  if (parsed.utm_content) {
+    out[`${prefix}_content` as const] = parsed.utm_content
+  }
+  out[`${prefix}_captured_at` as const] = parsed.captured_at
+}

package/src/tracking/get-tracking-config.ts

@@ -0,0 +1,50 @@
+import type { StorefrontClient } from "../api/http"
+import type { TrackingConfig, TrackingConfigResponse } from "./types"
+
+/**
+ * Fetch the store's public tracking config — the `tracking` block of
+ * `GET /api/store/integrations` (contract: store-api.md "Tracking block";
+ * code truth: `src/lib/tracking/store-config-block.ts` mounted by the
+ * block-builder registry in `src/lib/integrations/store-config.ts`).
+ *
+ * CRITICAL ADAPTATION vs `@1click/ui`: the original read
+ * `{MEDUSA_BACKEND_URL}/store/integrations` from env vars; the barter
+ * version goes through the `StorefrontClient` (x-client-id + optional
+ * publishable key + locale handled by the ONE http seam). Only ENABLED
+ * integrations contribute keys, and only non-sensitive IDs appear
+ * (pixelId, containerId, measurementId, publicKey, conversionId) —
+ * secrets (CAPI access_token, GA4 api_secret, Klaviyo private_key) can
+ * never traverse this surface (allowlist-mapped server-side).
+ *
+ * The @1click predecessor once called `/store/integrations/tracking`,
+ * which 404'd and silently returned `{}` — pixel never loaded. The path
+ * here is the registered barter route (`src/app/api/store/integrations/
+ * route.ts`); the contract tests execute this exact call.
+ *
+ * Response is cached for 5 minutes when running inside Next.js
+ * (`next.revalidate: 300` rides through the client's fetch passthrough)
+ * — these IDs change rarely (admin → Settings → Integrations).
+ *
+ * Returns an empty config on any error so storefront layouts can always
+ * call this and just render nothing if there's no pixel.
+ *
+ * Auth: anon `x-client-id` (client-required); publishable key optional.
+ * Errors: `400 invalid_publishable_key` when a bad key header is sent —
+ * swallowed here into `{}` by design (tags are best-effort chrome).
+ * Settings that change behavior: admin Integrations hub rows
+ * (facebook_capi / gtm / ga4 / klaviyo / google-ads `enabled` +
+ * credentials) and the consent card's `enabled` → `consent_required`.
+ */
+export async function getTrackingConfig(
+  client: StorefrontClient
+): Promise<TrackingConfig> {
+  try {
+    const data = await client.get<TrackingConfigResponse>(
+      "/api/store/integrations",
+      { next: { revalidate: 300, tags: ["tracking-config"] } }
+    )
+    return data.tracking ?? {}
+  } catch {
+    return {}
+  }
+}

package/src/tracking/gtag.ts

@@ -0,0 +1,200 @@
+"use client"
+
+import { sha256Hex, normaliseEmailForHash, normalisePhoneForHash } from "./attribution"
+
+/**
+ * Typed wrappers around the global `gtag()` from GA4 (gtag.js).
+ *
+ * Follows Google's GA4 Enhanced Ecommerce event spec:
+ * https://developers.google.com/analytics/devguides/collection/ga4/ecommerce
+ *
+ * All helpers no-op when `window.gtag` is undefined (GA4 not loaded —
+ * e.g., admin disabled it, or SSR). Storefronts can call these freely
+ * without guards.
+ *
+ * Purchase dedup: GA4 deduplicates Purchase events by `transaction_id`
+ * automatically — no need to coordinate event IDs across client + server.
+ * Pass the same `transaction_id = String(order.display_id)` on both
+ * sides and GA4 collapses them into a single conversion.
+ *
+ * Enhanced Conversions for Web (setEnhancedConversions below) sends
+ * hashed user-provided data through the same gtag.js so Google Ads —
+ * via the GA4 ↔ Ads link — can recover conversions that cookies miss
+ * (iOS / Safari ITP / ad-blockers). Spec:
+ * https://support.google.com/google-ads/answer/13258081
+ */
+
+type GA4Item = {
+  item_id: string
+  item_name: string
+  quantity: number
+  price: number
+  currency?: string
+  index?: number
+}
+
+type GA4ViewItemData = {
+  currency: string
+  value: number
+  items: GA4Item[]
+}
+
+type GA4AddToCartData = {
+  currency: string
+  value: number
+  items: GA4Item[]
+}
+
+type GA4BeginCheckoutData = {
+  currency: string
+  value: number
+  items: GA4Item[]
+  coupon?: string
+}
+
+type GA4PurchaseData = {
+  transaction_id: string
+  currency: string
+  value: number
+  items: GA4Item[]
+  tax?: number
+  shipping?: number
+  coupon?: string
+}
+
+type GtagFn = (
+  command: "event" | "config" | "set" | "get" | "js",
+  ...args: unknown[]
+) => void
+
+declare global {
+  interface Window {
+    gtag?: GtagFn
+    dataLayer?: unknown[]
+  }
+}
+
+function safeGtag(): GtagFn | null {
+  if (typeof window === "undefined") return null
+  return window.gtag ?? null
+}
+
+export function trackGAViewItem(data: GA4ViewItemData): void {
+  const gtag = safeGtag()
+  if (!gtag) return
+  gtag("event", "view_item", data)
+}
+
+export function trackGAAddToCart(data: GA4AddToCartData): void {
+  const gtag = safeGtag()
+  if (!gtag) return
+  gtag("event", "add_to_cart", data)
+}
+
+export function trackGABeginCheckout(data: GA4BeginCheckoutData): void {
+  const gtag = safeGtag()
+  if (!gtag) return
+  gtag("event", "begin_checkout", data)
+}
+
+/**
+ * Purchase event — GA4 deduplicates by `transaction_id`. Pass the SAME
+ * `String(order.display_id)` here AND in the backend Measurement Protocol
+ * payload so the two events collapse into one conversion.
+ */
+export function trackGAPurchase(data: GA4PurchaseData): void {
+  const gtag = safeGtag()
+  if (!gtag) return
+  gtag("event", "purchase", data)
+}
+
+/**
+ * Enhanced Conversions for Web — sends hashed user-provided PII via
+ * the gtag user_data channel. Google Ads (linked via GA4) consumes
+ * these signals to recover conversions that browser cookies miss
+ * (Safari ITP, iOS, ad-blockers).
+ *
+ * Hashing strategy mirrors the Meta side (attribution.ts):
+ *   - email / phone / first_name / last_name → SHA-256 hex, lowercase
+ *     normalised, phone E.164-style digits-only with country code
+ *   - city / region / postal_code / country / street → raw plain text
+ *     (Google's spec only documents sha256 variants for name fields
+ *     within the address block; geo fields are accepted as plain)
+ *
+ * Same input on both sides produces same digest → both vendors' match
+ * engines see identical hashes for the same user. Storefront callers
+ * pass RAW values; this function does the normalize+hash inline.
+ *
+ * Idempotent — safe to call repeatedly as new fields become known
+ * (gtag.set merges user_data per Google's spec).
+ *
+ * No-ops when window.gtag is undefined (GA4 not loaded, SSR, etc).
+ *
+ * Spec: https://support.google.com/google-ads/answer/13258081
+ */
+export type EnhancedConversionsInput = {
+  email?: string
+  phone?: string
+  firstName?: string
+  lastName?: string
+  street?: string
+  city?: string
+  /** GA4 spec uses "region" for state / province / oblast. */
+  region?: string
+  postalCode?: string
+  /** 2-letter ISO country code (lowercase or upper — Google normalises). */
+  country?: string
+}
+
+export async function setEnhancedConversions(
+  input: EnhancedConversionsInput
+): Promise<void> {
+  const gtag = safeGtag()
+  if (!gtag) return
+
+  const userData: Record<string, unknown> = {}
+
+  if (input.email) {
+    userData.sha256_email_address = await sha256Hex(
+      normaliseEmailForHash(input.email)
+    )
+  }
+  if (input.phone) {
+    userData.sha256_phone_number = await sha256Hex(
+      normalisePhoneForHash(input.phone)
+    )
+  }
+
+  const address: Record<string, unknown> = {}
+  if (input.firstName) {
+    address.sha256_first_name = await sha256Hex(
+      input.firstName.trim().toLowerCase()
+    )
+  }
+  if (input.lastName) {
+    address.sha256_last_name = await sha256Hex(
+      input.lastName.trim().toLowerCase()
+    )
+  }
+  if (input.street) address.street = input.street.trim()
+  if (input.city) address.city = input.city.trim()
+  if (input.region) address.region = input.region.trim()
+  if (input.postalCode) address.postal_code = input.postalCode.trim()
+  if (input.country) address.country = input.country.trim().toUpperCase()
+
+  if (Object.keys(address).length > 0) {
+    userData.address = address
+  }
+
+  if (Object.keys(userData).length === 0) return
+
+  gtag("set", "user_data", userData)
+}
+
+export type {
+  GA4Item,
+  GA4ViewItemData,
+  GA4AddToCartData,
+  GA4BeginCheckoutData,
+  GA4PurchaseData,
+}