@cartbase/storefront 0.1.0

package/src/tracking/index.ts

@@ -0,0 +1,133 @@
+/**
+ * @cartbase/storefront/tracking — Meta Pixel + GA4 + Rybbit + Consent Mode v2.
+ *
+ * Ported from `@1click/ui/src/tracking` (v2.3.1) with the barter seams:
+ *   - config comes from `GET /api/store/integrations` → `tracking` block
+ *     via `getTrackingConfig(client)` (never env vars)
+ *   - server-side CAPI / GA4-MP sending is barter-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"

package/src/tracking/meta-pixel.tsx

@@ -0,0 +1,166 @@
+"use client"
+
+import Script from "next/script"
+
+import {
+  normaliseEmailForHash,
+  normalisePhoneForHash,
+  rememberKnownVisitor,
+  sha256Hex,
+  type KnownVisitor,
+} from "./attribution"
+import { CONSENT_COOKIE } from "./consent"
+
+/**
+ * MetaPixel — client-side base pixel injector.
+ *
+ * Loads `https://connect.facebook.net/en_US/fbevents.js` via Next.js
+ * `<Script strategy="afterInteractive">` (the canonical strategy for
+ * third-party tags per Next.js docs). Initializes `fbq` with the given
+ * pixel ID and fires an initial `PageView`.
+ *
+ * The snippet stashes `pixelId` on `window.__1click_fb_pixel_id` so
+ * `updatePixelAdvancedMatching()` (called later from checkout / popup)
+ * can re-init the Pixel with hashed em / ph for Advanced Matching
+ * without the caller having to plumb the pixel id through.
+ *
+ * Renders nothing when `pixelId` is falsy — every consuming layout
+ * can call this unconditionally; the script is only injected when the
+ * admin has configured Facebook Pixel + CAPI.
+ *
+ * Subsequent route navigations DON'T need a manual PageView — the
+ * single base init covers the initial page; further events are fired
+ * explicitly via the helpers in `./fbq.ts`.
+ *
+ * Consent gate: fbq('consent', …) is pushed from the `_1c_consent`
+ * cookie BEFORE fbq('init') — Meta only honors a pre-init revoke, which
+ * makes the Pixel queue every event (incl. this PageView) client-side
+ * until the <ConsentBanner> grants; a later fbq('consent','grant')
+ * flushes the queue. No cookie (first visit) = revoke.
+ */
+export function MetaPixel({ pixelId }: { pixelId?: string }) {
+  if (!pixelId) return null
+
+  const initSnippet = `
+window.__1click_fb_pixel_id='${pixelId}';
+!function(f,b,e,v,n,t,s)
+{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
+n.queue=[];t=b.createElement(e);t.async=!0;
+t.src=v;s=b.getElementsByTagName(e)[0];
+s.parentNode.insertBefore(t,s)}(window, document,'script',
+'https://connect.facebook.net/en_US/fbevents.js');
+(function(){
+  var ads=false;
+  try{
+    var m=document.cookie.match(/(?:^|; )${CONSENT_COOKIE}=([^;]*)/);
+    if(m){ads=!!JSON.parse(decodeURIComponent(m[1])).ads;}
+  }catch(e){}
+  fbq('consent', ads?'grant':'revoke');
+})();
+fbq('init', '${pixelId}');
+fbq('track', 'PageView');
+`.trim()
+
+  return (
+    <>
+      <Script
+        id="meta-pixel-init"
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{ __html: initSnippet }}
+      />
+      <noscript>
+        <img
+          height="1"
+          width="1"
+          style={{ display: "none" }}
+          src={`https://www.facebook.com/tr?id=${pixelId}&ev=PageView&noscript=1`}
+          alt=""
+        />
+      </noscript>
+    </>
+  )
+}
+
+declare global {
+  interface Window {
+    __1click_fb_pixel_id?: string
+  }
+}
+
+/**
+ * Re-initialize the Pixel with Advanced Matching params so EVERY
+ * subsequent browser-side event is enriched with hashed em / ph /
+ * fn / ln / ct / zp automatically. Per Meta docs, fbq('init') with
+ * a 3rd arg merges advanced-matching values rather than replacing
+ * them — safe to call repeatedly as new fields become known.
+ *
+ * Caller passes RAW PII (we hash here using Meta's exact normalization
+ * so the resulting hash matches what backend CAPI sends — both sides
+ * of dedup compare the same digest).
+ *
+ * Also persists raw values via rememberKnownVisitor() so any future
+ * consumer of getKnownVisitor() sees them. In barter the server-side
+ * CAPI enrichment is backend-owned (the order.placed forwarder reads
+ * hashed PII from the order itself), so this call's job is the
+ * browser-side Pixel Advanced Matching.
+ *
+ * No-ops when:
+ *   - SSR (no window)
+ *   - MetaPixel hasn't mounted yet (no `window.__1click_fb_pixel_id`)
+ *   - fbevents.js hasn't loaded yet (no `window.fbq`)
+ *
+ * The localStorage write still happens in cases 2-3 so the data is
+ * available to any later getKnownVisitor() consumer.
+ */
+export async function updatePixelAdvancedMatching(
+  visitor: KnownVisitor
+): Promise<void> {
+  if (typeof window === "undefined") return
+
+  // Persist raw values regardless of Pixel state — later consumers
+  // (getKnownVisitor) use these even when Pixel isn't reachable.
+  rememberKnownVisitor(visitor)
+
+  const pixelId = window.__1click_fb_pixel_id
+  const fbq = window.fbq
+  if (!pixelId || !fbq) return
+
+  const matching: Record<string, string> = {}
+
+  if (visitor.email) {
+    matching.em = await sha256Hex(normaliseEmailForHash(visitor.email))
+  }
+  if (visitor.phone) {
+    matching.ph = await sha256Hex(normalisePhoneForHash(visitor.phone))
+  }
+  if (visitor.firstName) {
+    matching.fn = await sha256Hex(visitor.firstName.trim().toLowerCase())
+  }
+  if (visitor.lastName) {
+    matching.ln = await sha256Hex(visitor.lastName.trim().toLowerCase())
+  }
+  if (visitor.city) {
+    matching.ct = await sha256Hex(
+      visitor.city.trim().toLowerCase().replace(/\s+/g, "")
+    )
+  }
+  if (visitor.state) {
+    matching.st = await sha256Hex(
+      visitor.state.trim().toLowerCase().replace(/\s+/g, "")
+    )
+  }
+  if (visitor.postalCode) {
+    matching.zp = await sha256Hex(
+      visitor.postalCode.trim().toLowerCase().replace(/\s+/g, "")
+    )
+  }
+  if (visitor.country) {
+    matching.country = await sha256Hex(visitor.country.trim().toLowerCase())
+  }
+
+  if (Object.keys(matching).length === 0) return
+
+  fbq("init", pixelId, matching)
+}

package/src/tracking/rybbit-events.ts

@@ -0,0 +1,242 @@
+"use client"
+
+/**
+ * Typed wrappers around the global `window.rybbit.event()` from the
+ * Rybbit tracker script (`<Rybbit siteId={...} />`).
+ *
+ * Rybbit only supports STRING and NUMBER property values (no arrays,
+ * no objects, no booleans) and caps the property payload at 2KB
+ * (https://rybbit.com/docs/track-events). The helpers below stick to
+ * that contract — multi-item events flatten line ids into a
+ * comma-separated string, which is enough for aggregation in Rybbit's
+ * Custom Events view. Pixel/GA4 retain the rich item-level breakdown.
+ *
+ * Script-load race resilience (added v2.2.6):
+ *
+ *   The Rybbit tracker is loaded by `<Rybbit>` via Next.js Script with
+ *   strategy="afterInteractive" — `window.rybbit` is undefined for the
+ *   first 50-800ms after page load while the script downloads. During
+ *   that window, useEffect-mounted tracking calls would previously
+ *   silently no-op (`safeRybbit()` returned null and the caller had no
+ *   way to retry).
+ *
+ *   This file now maintains a small per-page queue: when fireEvent is
+ *   called before `window.rybbit` exists, the call is pushed onto a
+ *   module-level queue and a single drainer is scheduled that polls
+ *   for `window.rybbit` and replays everything once the script loads.
+ *
+ *   The drainer caps total wait at 10 seconds — beyond that the script
+ *   is presumed permanently blocked (ad-blocker, CSP rejection, network
+ *   failure) and the queue is discarded so we don't leak memory.
+ *
+ *   This is the canonical pattern for async tag loaders — same as
+ *   Google's `window.dataLayer` (queue → consumed by gtag.js on load)
+ *   and Segment's `analytics.js` snippet (method-stub queue → flushed
+ *   on script ready).
+ *
+ *   IMPORTANT: server-side firing (e.g. Rybbit Purchase from the
+ *   `order.placed` subscriber in medusa-mindpages) remains the truth
+ *   source for high-value conversions. This queue improves browser-side
+ *   funnel events (view_item / add_to_cart / begin_checkout) where the
+ *   server doesn't fire. Purchase still has the server flag guard.
+ *
+ * All helpers stay no-op-safe when called outside a browser (SSR) and
+ * when Rybbit is admin-disabled (the `<Rybbit>` component renders
+ * nothing for missing siteId, so `window.rybbit` simply never appears
+ * and the 10s drain timeout discards the queue silently).
+ *
+ * Event names match GA4 / industry vocabulary so the same dashboard
+ * names work across analytics tools:
+ *   view_item · add_to_cart · begin_checkout · purchase
+ */
+
+export type RybbitEventProps = Record<string, string | number>
+
+type RybbitFn = {
+  event: (eventName: string, properties?: RybbitEventProps) => void
+  pageview?: () => void
+  identify?: (userId: string, traits?: RybbitEventProps) => void
+}
+
+declare global {
+  interface Window {
+    rybbit?: RybbitFn
+  }
+}
+
+function safeRybbit(): RybbitFn | null {
+  if (typeof window === "undefined") return null
+  return window.rybbit ?? null
+}
+
+/**
+ * Truncate a comma-joined list of ids so the resulting properties
+ * payload stays under Rybbit's 2KB limit. Other props are short, so
+ * a 1500-char cap on the joined string leaves comfortable headroom.
+ */
+function joinIds(ids: string[]): string {
+  const joined = ids.join(",")
+  return joined.length <= 1500 ? joined : joined.slice(0, 1500)
+}
+
+// ── Script-load race queue ────────────────────────────────────────────
+
+type PendingEvent = { name: string; props?: RybbitEventProps }
+
+/** Calls made before `window.rybbit` exists wait here. Module-level so
+ *  every fireEvent() across the page shares the same queue. */
+const pendingQueue: PendingEvent[] = []
+
+/** Single in-flight drainer guard — prevents N parallel pollers if N
+ *  events queue during the same script-load window. */
+let drainScheduled = false
+
+const DRAIN_FIRST_DELAY_MS = 50
+const DRAIN_POLL_INTERVAL_MS = 100
+const DRAIN_MAX_WAIT_MS = 10_000
+
+/**
+ * Fire an event immediately if Rybbit is ready, or queue + schedule a
+ * drain otherwise. All public helpers below go through this so the
+ * queue covers every event type uniformly — no caller has to know
+ * whether the script has loaded yet.
+ */
+function fireEvent(name: string, props?: RybbitEventProps): void {
+  const r = safeRybbit()
+  if (r) {
+    try {
+      r.event(name, props)
+    } catch {
+      // Defensive — Rybbit's event() throwing would be unusual but
+      // tracking failures must never break the user flow.
+    }
+    return
+  }
+  if (typeof window === "undefined") return // SSR — drop silently
+  pendingQueue.push({ name, props })
+  scheduleDrain()
+}
+
+/**
+ * Poll for `window.rybbit` and drain the queue when it appears.
+ * Bounded — gives up after DRAIN_MAX_WAIT_MS so a permanently-blocked
+ * Rybbit (ad-blocker, CSP, offline) doesn't grow the queue forever.
+ */
+function scheduleDrain(): void {
+  if (drainScheduled) return
+  if (typeof window === "undefined") return
+  drainScheduled = true
+
+  const startedAt = Date.now()
+  const tick = (): void => {
+    const r = safeRybbit()
+    if (r) {
+      const drained = pendingQueue.splice(0, pendingQueue.length)
+      for (const ev of drained) {
+        try {
+          r.event(ev.name, ev.props)
+        } catch {
+          // Don't let one bad event stop the rest from draining
+        }
+      }
+      drainScheduled = false
+      return
+    }
+    if (Date.now() - startedAt > DRAIN_MAX_WAIT_MS) {
+      // Rybbit will not load (ad-blocker, CSP, network failure, admin
+      // disabled). Discard the queue so we don't leak memory if the
+      // user navigates around the SPA with the script permanently dead.
+      pendingQueue.length = 0
+      drainScheduled = false
+      return
+    }
+    setTimeout(tick, DRAIN_POLL_INTERVAL_MS)
+  }
+  setTimeout(tick, DRAIN_FIRST_DELAY_MS)
+}
+
+// ── Public event helpers ──────────────────────────────────────────────
+
+export type RybbitViewItemData = {
+  item_id: string
+  item_name: string
+  currency: string
+  value: number
+}
+
+export type RybbitAddToCartData = {
+  item_id: string
+  item_name: string
+  quantity: number
+  currency: string
+  value: number
+}
+
+export type RybbitBeginCheckoutData = {
+  item_ids: string[]
+  num_items: number
+  currency: string
+  value: number
+}
+
+export type RybbitPurchaseData = {
+  transaction_id: string
+  item_ids: string[]
+  num_items: number
+  currency: string
+  value: number
+}
+
+export function trackRybbitViewItem(data: RybbitViewItemData): void {
+  fireEvent("view_item", {
+    item_id: data.item_id,
+    item_name: data.item_name,
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackRybbitAddToCart(data: RybbitAddToCartData): void {
+  fireEvent("add_to_cart", {
+    item_id: data.item_id,
+    item_name: data.item_name,
+    quantity: data.quantity,
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackRybbitBeginCheckout(
+  data: RybbitBeginCheckoutData
+): void {
+  fireEvent("begin_checkout", {
+    item_ids: joinIds(data.item_ids),
+    num_items: data.num_items,
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+/**
+ * Purchase event — fired client-side on the order-confirmed page.
+ *
+ * Browser-side Purchase is now redundant when the server-side fire
+ * has succeeded (medusa-mindpages tracking-events.ts subscriber sets
+ * `order.metadata.rybbit_purchase_fired`). The storefront's
+ * `<TrackPurchase>` reads that flag and skips this call when true.
+ * Server-side is the truth source; this browser-side call is the
+ * realtime safety net for the very first /confirmed visit when the
+ * subscriber hasn't finished yet.
+ *
+ * Even on first-visit, the queue above means a script-load race no
+ * longer drops the event — it'll fire as soon as Rybbit loads.
+ */
+export function trackRybbitPurchase(data: RybbitPurchaseData): void {
+  fireEvent("purchase", {
+    transaction_id: data.transaction_id,
+    item_ids: joinIds(data.item_ids),
+    num_items: data.num_items,
+    currency: data.currency,
+    value: data.value,
+  })
+}

package/src/tracking/rybbit.tsx

@@ -0,0 +1,40 @@
+"use client"
+
+import Script from "next/script"
+
+/**
+ * Rybbit — privacy-friendly self-hosted analytics tracker injector.
+ *
+ * Loads `<baseUrl>/api/script.js` via Next.js `<Script
+ * strategy="afterInteractive">`. The script auto-fires pageviews on
+ * initial load and on SPA route changes, so storefronts don't need
+ * to wire route-change effects.
+ *
+ * `siteId` and `baseUrl` are platform-managed — Rybbit is the platform's
+ * self-hosted, cookieless analytics, provisioned per store from platform
+ * env, and is deliberately ABSENT from the barter store-config `tracking`
+ * block (`src/lib/tracking/store-config-block.ts`). The host app passes
+ * the values as props directly (e.g. from its own env). The merchant
+ * never sees or configures them. Rybbit needs no consent gate.
+ *
+ * Renders nothing when `siteId` is falsy — every consuming layout can
+ * call this unconditionally.
+ */
+export function Rybbit({
+  siteId,
+  baseUrl = "https://analytics.fam.social",
+}: {
+  siteId?: string
+  baseUrl?: string
+}) {
+  if (!siteId) return null
+
+  return (
+    <Script
+      id="rybbit-tracker"
+      src={`${baseUrl}/api/script.js`}
+      data-site-id={siteId}
+      strategy="afterInteractive"
+    />
+  )
+}