@cartbase/storefront 0.6.0 → 0.8.0

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

@@ -3,6 +3,15 @@ import { cookies, headers } from "next/headers"
 import { getTrackingConfig } from "./get-tracking-config"
 import type { StorefrontClient } from "../api/http"
 import type { TrackingAttribution, TrackingClientHints } from "./types"
+import { CLICK_ID_METADATA_KEYS } from "./attribution"
+import {
+  LEGACY_UTM_FIRST_COOKIE,
+  LEGACY_UTM_LAST_COOKIE,
+  LEGACY_VISITOR_COOKIE,
+  UTM_FIRST_COOKIE,
+  UTM_LAST_COOKIE,
+  VISITOR_COOKIE,
+} from "../lib/cookie-names"
 
 /**
  * Reads Meta + GA4 attribution signals from the current Next.js server
@@ -72,14 +81,19 @@ export async function getTrackingAttribution(
     // 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
+    anonId =
+      cookieStore.get(VISITOR_COOKIE)?.value ?? cookieStore.get(LEGACY_VISITOR_COOKIE)?.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
+    utmFirstRaw =
+      cookieStore.get(UTM_FIRST_COOKIE)?.value ??
+      cookieStore.get(LEGACY_UTM_FIRST_COOKIE)?.value
+    utmLastRaw =
+      cookieStore.get(UTM_LAST_COOKIE)?.value ??
+      cookieStore.get(LEGACY_UTM_LAST_COOKIE)?.value
 
     // _ga_<MEASUREMENT_ID> uses the GA4 measurementId (e.g., G-ABCDEF1234)
     // with the "G-" prefix stripped: cookie name = `_ga_ABCDEF1234`.
@@ -110,6 +124,35 @@ export async function getTrackingAttribution(
   applyUtmCookie(utmFirstRaw, "utm_first", result)
   applyUtmCookie(utmLastRaw, "utm_last", result)
 
+  // Ad-click identifiers — TikTok's ttclid / _ttp and Google's gclid /
+  // gbraid / wbraid, captured into cookies by captureClickIdsFromUrl().
+  // They travel the same road as the UTMs: cart.metadata at checkout,
+  // order.metadata at completion, and from there into the TikTok Events
+  // API `user` block. Without ttclid TikTok cannot tie a conversion back
+  // to the click that produced it, which is the number the advertiser
+  // looks at first.
+  try {
+    const cookieStore = await cookies()
+    // The key map is a plain tuple list (attribution.ts owns the cookie
+    // names), so the write goes through one narrow cast rather than a
+    // per-key branch that would have to be edited for every new platform.
+    const sink = result as Record<string, unknown>
+    for (const [cookieName, metadataKey] of CLICK_ID_METADATA_KEYS) {
+      const value = cookieStore.get(cookieName)?.value
+      if (value) {
+        // Written encoded by the capture; decoded once here so the wire
+        // carries the id the platform actually issued.
+        try {
+          sink[metadataKey] = decodeURIComponent(value)
+        } catch {
+          sink[metadataKey] = value
+        }
+      }
+    }
+  } catch {
+    // best-effort — attribution never blocks a checkout
+  }
+
   // _ga cookie format: "GA1.1.<client_id>.<timestamp>" — backend wants
   // the full <client_id>.<timestamp> portion (the canonical GA client_id).
   if (gaCookieRaw) {

package/src/tracking/google-ads.ts

@@ -0,0 +1,84 @@
+"use client"
+
+import type { TrackingConfig } from "./types"
+
+/**
+ * Google Ads conversion tracking — browser side.
+ *
+ * Rides the SAME gtag instance <GoogleTag> loads for GA4; there is
+ * deliberately no loader in this file (see the comment block in ./ga4.tsx
+ * and https://support.google.com/google-ads/answer/2476688).
+ *
+ * DEDUP, and it is the whole reason this file is careful. Google Ads
+ * collapses two conversions that share a conversion action AND a
+ * `transaction_id` (https://support.google.com/google-ads/answer/6386790).
+ * Every vendor snippet ships `'transaction_id': ''`, and an empty value
+ * dedupes nothing — so every re-open of the confirmation page counts
+ * another purchase. That is not a hypothetical: order emails link back to
+ * the confirmation page, so the page is re-opened days after the sale, by
+ * the same buyer, routinely. We always send `String(order.display_id)`,
+ * the same key GA4's Measurement Protocol already uses.
+ *
+ * No-ops when gtag is absent (Ads not configured, server render, blocked
+ * script), so callers need no guards.
+ */
+
+type GtagFn = (...args: unknown[]) => void
+
+function safeGtag(): GtagFn | null {
+  if (typeof window === "undefined") return null
+  const fn = (window as unknown as { gtag?: GtagFn }).gtag
+  return typeof fn === "function" ? fn : null
+}
+
+/**
+ * Build the `send_to` Google Ads expects for the purchase conversion:
+ * "AW-XXXXXXXXXX/Label".
+ *
+ * Returns null when either half is missing, so callers skip the
+ * conversion entirely instead of firing a malformed `send_to` that Google
+ * accepts and silently drops. The label is genuinely optional in the
+ * admin: a merchant can save the account id before creating the
+ * conversion action.
+ */
+export function googleAdsPurchaseSendTo(config: TrackingConfig): string | null {
+  const conversionId = config.googleAds?.conversionId?.trim()
+  const label = config.googleAds?.conversionLabel?.trim()
+  if (!conversionId || !label) return null
+  return `${conversionId}/${label}`
+}
+
+export type GoogleAdsPurchaseInput = {
+  /** Full send_to value from `googleAdsPurchaseSendTo`. */
+  sendTo: string
+  /** Order total actually collected, in `currency`. */
+  value: number
+  /** ISO 4217, e.g. "EUR". */
+  currency: string
+  /** THE dedup key. Always `String(order.display_id)`. */
+  transactionId: string
+  /**
+   * Whether this order is the buyer's first. Computed once server-side by
+   * the order.placed forwarder and persisted on the order, so the browser
+   * and the server cannot disagree. Omitted entirely when unknown: a
+   * wrong value is worse than an absent one for new-customer bidding.
+   */
+  newCustomer?: boolean
+}
+
+export function trackGoogleAdsPurchase(input: GoogleAdsPurchaseInput): void {
+  const gtag = safeGtag()
+  if (!gtag || !input.sendTo) return
+
+  const payload: Record<string, unknown> = {
+    send_to: input.sendTo,
+    value: input.value,
+    currency: input.currency,
+    transaction_id: input.transactionId,
+  }
+  if (typeof input.newCustomer === "boolean") {
+    payload.new_customer = input.newCustomer
+  }
+
+  gtag("event", "conversion", payload)
+}

package/src/tracking/gtag.ts

@@ -1,6 +1,10 @@
 "use client"
 
-import { sha256Hex, normaliseEmailForHash, normalisePhoneForHash } from "./attribution"
+import {
+  sha256Hex,
+  normaliseEmailForHash,
+  normalisePhoneForGoogleHash,
+} from "./attribution"
 
 /**
  * Typed wrappers around the global `gtag()` from GA4 (gtag.js).
@@ -114,16 +118,23 @@ export function trackGAPurchase(data: GA4PurchaseData): void {
  * 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)
+ * Hashing:
+ *   - email / first_name / last_name: SHA-256 hex of the trimmed,
+ *     lowercased value, which is what both vendors want
+ *   - phone: SHA-256 hex of E.164 WITH the leading plus, which is what
+ *     GOOGLE wants and is NOT what Meta wants
+ *   - city / region / postal_code / country / street: plain text
+ *     (Google documents sha256 variants only for the name fields inside
+ *     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.
+ * The phone line is the one to read twice. This function used to reuse
+ * Meta's digits-only normaliser on the reasoning that both vendors should
+ * see identical digests for the same person. That was the bug: Google
+ * requires the plus, so the digest matched nobody, and nothing failed
+ * loudly enough to notice. Two vendors, two normalisers, on purpose.
+ *
+ * Storefront callers pass RAW values; this function normalises and hashes
+ * inline.
  *
  * Idempotent — safe to call repeatedly as new fields become known
  * (gtag.set merges user_data per Google's spec).
@@ -160,9 +171,11 @@ export async function setEnhancedConversions(
     )
   }
   if (input.phone) {
-    userData.sha256_phone_number = await sha256Hex(
-      normalisePhoneForHash(input.phone)
-    )
+    // Undefined for anything that could not be a real E.164 number: a
+    // hash of a malformed phone cannot match, and it costs the field
+    // Google would otherwise fall back from.
+    const e164 = normalisePhoneForGoogleHash(input.phone)
+    if (e164) userData.sha256_phone_number = await sha256Hex(e164)
   }
 
   const address: Record<string, unknown> = {}

package/src/tracking/gtm.tsx

@@ -0,0 +1,60 @@
+"use client"
+
+import Script from "next/script"
+
+import { jsStringLiteral, urlParam } from "./inline-script"
+
+/**
+ * Gtm — Google Tag Manager container.
+ *
+ * The hub has served `tracking.gtm.containerId` to storefronts since the
+ * tracking card shipped, and until now nothing in this package mounted
+ * it, so a merchant who configured GTM got a container id in their page
+ * data and no container. Same shape of defect as Google Ads was.
+ *
+ * GTM is the merchant's own escape hatch: whatever tag we have not built
+ * a first-class integration for, they can deploy through their container
+ * without waiting for us. That makes it worth mounting properly rather
+ * than treating it as a lesser vendor.
+ *
+ * Consent: <ConsentInit> sets the Consent Mode v2 defaults synchronously
+ * before this loads, so tags inside the container inherit the gate, and
+ * `applyConsent()` pushes the visitor's decision to the same dataLayer.
+ * Nothing extra to wire here.
+ *
+ * The <noscript> iframe is part of Google's documented snippet and is
+ * what makes the container work for a scriptless visitor. Next renders
+ * it in <body>, which is where Google puts it.
+ *
+ * Renders nothing when `containerId` is falsy.
+ */
+export function Gtm({ containerId }: { containerId?: string }) {
+  if (!containerId) return null
+
+  const initSnippet = `
+(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+})(window,document,'script','dataLayer',${jsStringLiteral(containerId)});
+`.trim()
+
+  return (
+    <>
+      <Script
+        id="gtm-init"
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{ __html: initSnippet }}
+      />
+      <noscript>
+        <iframe
+          src={`https://www.googletagmanager.com/ns.html?id=${urlParam(containerId)}`}
+          height="0"
+          width="0"
+          style={{ display: "none", visibility: "hidden" }}
+          title="Google Tag Manager"
+        />
+      </noscript>
+    </>
+  )
+}

package/src/tracking/index.ts

@@ -1,133 +1,187 @@
-/**
- * @cartbase/storefront/tracking — Meta Pixel + GA4 + Rybbit + Consent Mode v2.
- *
- * Ported from `@1click/ui/src/tracking` (v2.3.1) with the Cartbase seams:
- *   - config comes from `GET /api/store/integrations` → `tracking` block
- *     via `getTrackingConfig(client)` (never env vars)
- *   - server-side CAPI / GA4-MP sending is Cartbase-backend-owned (the
- *     `order.placed` forwarder) — this package fires CLIENT events only
- *     and writes attribution for the server to inherit
- *   - Purchase dedupe: Pixel `eventID = "purchase_" + order.display_id`
- *     (trackPurchase builds it); GA4 `transaction_id =
- *     String(order.display_id)`
- *
- * Public surface:
- *   - <ConsentInit> / <ConsentBanner> / <ConsentSettingsLink> — Consent
- *     Mode v2 (config from GET /api/store/consent; `_1c_consent` seam)
- *   - <MetaPixel pixelId> / <GA4 measurementId> / <Rybbit siteId> — layout tags
- *   - Meta Pixel client helpers: trackViewContent / trackAddToCart /
- *     trackInitiateCheckout / trackPurchase / trackLead
- *   - GA4 client helpers: trackGAViewItem / trackGAAddToCart /
- *     trackGABeginCheckout / trackGAPurchase / setEnhancedConversions
- *   - Rybbit client helpers: trackRybbit* (queue-buffered)
- *   - getTrackingConfig(client) — the public tag config
- *   - getTrackingAttribution(clientHints?, opts?) — server-side signal
- *     gathering for the cart.metadata writeback (consent-gated)
- *   - getEngagementTimeMsec() / initEngagementTime() — time-on-session
- *
- * Server vs client split (per Next.js App Router rules):
- *   - get-tracking-attribution.ts imports `next/headers` (server-only by
- *     construction); get-tracking-config.ts is isomorphic
- *   - meta-pixel.tsx, ga4.tsx, rybbit.tsx, fbq.ts, gtag.ts,
- *     rybbit-events.ts, attribution.ts, use-engagement-time.ts,
- *     consent-banner.tsx are `"use client"`
- *   - types.ts, consent.ts, consent-init.tsx are universal
- *
- * Importers should usually pull from the subpath that matches their
- * environment. The barrel re-exports everything, but tree-shaking and
- * Next.js's RSC boundary detection both work better with subpaths.
- */
-
-export { MetaPixel, updatePixelAdvancedMatching } from "./meta-pixel"
-export { GA4 } from "./ga4"
-export { Rybbit } from "./rybbit"
-export { ConsentInit } from "./consent-init"
-export { ConsentBanner, ConsentBannerCard, ConsentSettingsLink } from "./consent-banner"
-export {
-  applyConsent,
-  setConsent,
-  openConsentSettings,
-  readConsentCookie,
-  writeConsentCookie,
-  shouldRenderBanner,
-  pickConsentCopy,
-  CONSENT_COOKIE,
-  CONSENT_MAX_AGE_SECONDS,
-  CONSENT_OPEN_EVENT,
-  CONSENT_INIT_SNIPPET,
-  type ConsentChoices,
-  type ConsentCopy,
-  type ConsentLayout,
-  type ConsentMode,
-  type ConsentSettings,
-} from "./consent"
-export {
-  trackViewContent,
-  trackAddToCart,
-  trackInitiateCheckout,
-  trackPurchase,
-  trackLead,
-  generateEventId,
-  type LeadContext,
-} from "./fbq"
-export {
-  setTrackingDefaults,
-  getOrCreateAnonId,
-  getOrCreateFbp,
-  getOrCreateFbc,
-  getKnownVisitor,
-  rememberKnownVisitor,
-  captureUtmsFromUrl,
-  getCapturedFirstTouchUtms,
-  getCapturedLastTouchUtms,
-  sha256Hex,
-  normaliseEmailForHash,
-  normalisePhoneForHash,
-  type KnownVisitor,
-  type CapturedUtms,
-} from "./attribution"
-export {
-  trackGAViewItem,
-  trackGAAddToCart,
-  trackGABeginCheckout,
-  trackGAPurchase,
-  setEnhancedConversions,
-  type EnhancedConversionsInput,
-} from "./gtag"
-export {
-  trackRybbitViewItem,
-  trackRybbitAddToCart,
-  trackRybbitBeginCheckout,
-  trackRybbitPurchase,
-  type RybbitViewItemData,
-  type RybbitAddToCartData,
-  type RybbitBeginCheckoutData,
-  type RybbitPurchaseData,
-} from "./rybbit-events"
-export { getTrackingConfig } from "./get-tracking-config"
-export { getTrackingAttribution } from "./get-tracking-attribution"
-export {
-  getEngagementTimeMsec,
-  initEngagementTime,
-} from "./use-engagement-time"
-
-export type {
-  TrackingConfig,
-  TrackingConfigResponse,
-  TrackingAttribution,
-  TrackingClientHints,
-  MetaContentItem,
-  ViewContentData,
-  AddToCartData,
-  InitiateCheckoutData,
-  PurchaseData,
-  LeadData,
-} from "./types"
-
-export type {
-  GA4Item,
-  GA4ViewItemData,
-  GA4AddToCartData,
-  GA4BeginCheckoutData,
-  GA4PurchaseData,
-} from "./gtag"
+/**
+ * @cartbase/storefront/tracking — Meta Pixel + GA4 + Rybbit + Consent Mode v2.
+ *
+ * Ported from `@1click/ui/src/tracking` (v2.3.1) with the Cartbase seams:
+ *   - config comes from `GET /api/store/integrations` → `tracking` block
+ *     via `getTrackingConfig(client)` (never env vars)
+ *   - server-side CAPI / GA4-MP sending is Cartbase-backend-owned (the
+ *     `order.placed` forwarder) — this package fires CLIENT events only
+ *     and writes attribution for the server to inherit
+ *   - Purchase dedupe: Pixel `eventID = "purchase_" + order.display_id`
+ *     (trackPurchase builds it); GA4 `transaction_id =
+ *     String(order.display_id)`
+ *
+ * Public surface:
+ *   - <ConsentInit> / <ConsentBanner> / <ConsentSettingsLink> — Consent
+ *     Mode v2 (config from GET /api/store/consent; `_1c_consent` seam)
+ *   - <StorefrontTags client> — EVERY tag the store configured, mounted
+ *     from its own config. This is the one a storefront should mount;
+ *     the individual tags below are for a layout that needs control.
+ *   - <TrackInit /> — captures UTMs and ad-click ids on the landing page
+ *   - <PageViews /> — one pageview per navigation, client-side ones
+ *     included; the platform derives page type + entity id from the path
+ *   - <LiveHeartbeat /> — pings while a tab is open, so the merchant's live
+ *     visitor count means "right now" rather than "recently active"
+ *     (they exist only there) and starts the engagement clock.
+ *   - <MetaPixel pixelId> / <GoogleTag measurementId adsConversionId> /
+ *     <TikTokPixel pixelId> / <Gtm containerId> / <Rybbit siteId> —
+ *     individual layout tags (<GA4> is <GoogleTag> with only the
+ *     analytics destination)
+ *   - ONE call per commerce moment, every vendor at once (prefer these):
+ *     trackProductView / trackCartAdd / trackCheckoutStart /
+ *     trackOrderPurchase
+ *   - Meta Pixel client helpers: trackViewContent / trackAddToCart /
+ *     trackInitiateCheckout / trackPurchase / trackLead
+ *   - GA4 client helpers: trackGAViewItem / trackGAAddToCart /
+ *     trackGABeginCheckout / trackGAPurchase / setEnhancedConversions
+ *   - Rybbit client helpers: trackRybbit* (queue-buffered)
+ *   - getTrackingConfig(client) — the public tag config
+ *   - getTrackingAttribution(clientHints?, opts?) — server-side signal
+ *     gathering for the cart.metadata writeback (consent-gated)
+ *   - getEngagementTimeMsec() / initEngagementTime() — time-on-session
+ *
+ * Server vs client split (per Next.js App Router rules):
+ *   - get-tracking-attribution.ts imports `next/headers` (server-only by
+ *     construction); get-tracking-config.ts is isomorphic
+ *   - meta-pixel.tsx, ga4.tsx, rybbit.tsx, fbq.ts, gtag.ts,
+ *     rybbit-events.ts, attribution.ts, use-engagement-time.ts,
+ *     consent-banner.tsx are `"use client"`
+ *   - types.ts, consent.ts, consent-init.tsx are universal
+ *
+ * Importers should usually pull from the subpath that matches their
+ * environment. The barrel re-exports everything, but tree-shaking and
+ * Next.js's RSC boundary detection both work better with subpaths.
+ */
+
+export { MetaPixel, updatePixelAdvancedMatching } from "./meta-pixel"
+export { GA4, GoogleTag } from "./ga4"
+export { Gtm } from "./gtm"
+export { TikTokPixel } from "./tiktok-pixel"
+export { StorefrontTags } from "./storefront-tags"
+export { TrackInit } from "./track-init"
+// The live-visitor heartbeat. Mounted by <StorefrontTags> so a storefront
+// gets it without knowing it exists.
+export { LiveHeartbeat } from "./live-heartbeat"
+// Every navigation, automatically. Mounted by <StorefrontTags>; the page
+// type and the record it was about are derived by the platform, never
+// declared here.
+export { PageViews } from "./page-views"
+export { TrackOrderPurchase } from "./track-order-purchase"
+export { Rybbit } from "./rybbit"
+export { ConsentInit } from "./consent-init"
+export { ConsentBanner, ConsentBannerCard, ConsentSettingsLink } from "./consent-banner"
+export {
+  applyConsent,
+  setConsent,
+  openConsentSettings,
+  readConsentCookie,
+  writeConsentCookie,
+  shouldRenderBanner,
+  pickConsentCopy,
+  CONSENT_COOKIE,
+  CONSENT_MAX_AGE_SECONDS,
+  CONSENT_OPEN_EVENT,
+  CONSENT_INIT_SNIPPET,
+  type ConsentChoices,
+  type ConsentCopy,
+  type ConsentLayout,
+  type ConsentMode,
+  type ConsentSettings,
+} from "./consent"
+export {
+  trackViewContent,
+  trackAddToCart,
+  trackInitiateCheckout,
+  trackPurchase,
+  trackLead,
+  generateEventId,
+  type LeadContext,
+} from "./fbq"
+export {
+  setTrackingDefaults,
+  getOrCreateAnonId,
+  getOrCreateFbp,
+  getOrCreateFbc,
+  getKnownVisitor,
+  rememberKnownVisitor,
+  captureUtmsFromUrl,
+  captureClickIdsFromUrl,
+  getCapturedFirstTouchUtms,
+  getCapturedLastTouchUtms,
+  sha256Hex,
+  normaliseEmailForHash,
+  normalisePhoneForHash,
+  normalisePhoneForGoogleHash,
+  CLICK_ID_COOKIES,
+  CLICK_ID_METADATA_KEYS,
+  type KnownVisitor,
+  type CapturedUtms,
+} from "./attribution"
+export {
+  trackProductView,
+  trackCartAdd,
+  trackCheckoutStart,
+  trackOrderPurchase,
+  type TrackedLine,
+  type TrackedOrder,
+} from "./events"
+export {
+  trackTikTokViewContent,
+  trackTikTokAddToCart,
+  trackTikTokInitiateCheckout,
+  trackTikTokPurchase,
+  applyTikTokConsent,
+  tiktokPurchaseEventId,
+  type TikTokContentItem,
+} from "./ttq"
+export {
+  trackGoogleAdsPurchase,
+  googleAdsPurchaseSendTo,
+  type GoogleAdsPurchaseInput,
+} from "./google-ads"
+export {
+  trackGAViewItem,
+  trackGAAddToCart,
+  trackGABeginCheckout,
+  trackGAPurchase,
+  setEnhancedConversions,
+  type EnhancedConversionsInput,
+} from "./gtag"
+export {
+  trackRybbitViewItem,
+  trackRybbitAddToCart,
+  trackRybbitBeginCheckout,
+  trackRybbitPurchase,
+  type RybbitViewItemData,
+  type RybbitAddToCartData,
+  type RybbitBeginCheckoutData,
+  type RybbitPurchaseData,
+} from "./rybbit-events"
+export { getTrackingConfig } from "./get-tracking-config"
+export { useTrackingConfig } from "./use-tracking-config"
+export { getTrackingAttribution } from "./get-tracking-attribution"
+export {
+  getEngagementTimeMsec,
+  initEngagementTime,
+} from "./use-engagement-time"
+
+export type {
+  TrackingConfig,
+  TrackingConfigResponse,
+  TrackingAttribution,
+  TrackingClientHints,
+  MetaContentItem,
+  ViewContentData,
+  AddToCartData,
+  InitiateCheckoutData,
+  PurchaseData,
+  LeadData,
+} from "./types"
+
+export type {
+  GA4Item,
+  GA4ViewItemData,
+  GA4AddToCartData,
+  GA4BeginCheckoutData,
+  GA4PurchaseData,
+} from "./gtag"

package/src/tracking/inline-script.ts

@@ -0,0 +1,49 @@
+/**
+ * Safe interpolation of a configured id into a vendor's inline snippet.
+ *
+ * Every tag component here injects the vendor's own bootstrap through
+ * `dangerouslySetInnerHTML`, with the merchant's pixel / measurement /
+ * conversion id written into it. Those ids arrive from the store's
+ * integration settings, which means they are typed by a person in the
+ * admin, and a value carrying a quote would close the string literal and
+ * run whatever follows it on every page of that storefront.
+ *
+ * On a single-merchant site that is only self-inflicted. On a platform it
+ * is one tenant's admin user writing script into that tenant's public
+ * storefront, so the escape is not optional.
+ *
+ * Returns the value as a COMPLETE single-quoted JavaScript literal,
+ * quotes included, so callers cannot forget to quote it themselves:
+ *
+ *     `fbq('init', ${jsStringLiteral(pixelId)});`
+ */
+const LINE_SEPARATORS = new RegExp("[\u2028\u2029]", "g")
+
+export function jsStringLiteral(value: string): string {
+  const escaped = String(value)
+    .replace(/\\/g, "\\\\")
+    .replace(/'/g, "\\'")
+    .replace(/\r/g, "\\r")
+    .replace(/\n/g, "\\n")
+    // `</script` inside an inline script closes the element wherever it
+    // appears, quoted or not.
+    .replace(/<\//g, "<\\/")
+    // U+2028 and U+2029 are line terminators to a JavaScript parser, so
+    // they break a string literal exactly like a newline does. The class
+    // is built from escapes rather than written literally, because a
+    // source file carrying those characters raw is its own version of
+    // this problem (it breaks the file that fixes it).
+    .replace(LINE_SEPARATORS, (ch) =>
+      ch.charCodeAt(0) === 0x2028 ? "\\u2028" : "\\u2029"
+    )
+  return `'${escaped}'`
+}
+
+/**
+ * The same value for a URL query parameter (the loader `src`), where the
+ * hazard is a crafted id breaking out of the parameter rather than out of
+ * a string literal.
+ */
+export function urlParam(value: string): string {
+  return encodeURIComponent(String(value))
+}