@cartbase/storefront 0.1.0

package/src/tracking/types.ts

@@ -0,0 +1,185 @@
+/**
+ * Shared tracking types — Meta Pixel + Google Analytics 4 + consent.
+ *
+ * Ported from `@1click/ui/src/tracking/types.ts` (v2.3.1) and re-seated on
+ * the barter contract:
+ *
+ *   - `TrackingConfig` mirrors the barter store-config `tracking` block
+ *     served by `GET /api/store/integrations` (code truth:
+ *     `src/lib/tracking/constants.ts` `StoreTrackingBlock` +
+ *     `src/lib/tracking/store-block.ts`; contract: store-api.md "Tracking
+ *     block"). Differences vs the @1click shape: `googleAds` is a barter
+ *     extension, `consent_required` is new (consent-management card), and
+ *     `rybbit` is deliberately ABSENT — Rybbit is platform analytics,
+ *     provisioned from platform env, never a tenant integration; the
+ *     `<Rybbit>` component takes its props directly from the host app.
+ *
+ *   - Server-side CAPI + GA4 Measurement Protocol sending is
+ *     barter-backend-owned (the `order.placed` forwarder,
+ *     `src/lib/tracking/forward.ts`) — this package fires CLIENT events
+ *     only and writes attribution for the server to inherit.
+ *
+ * Purchase dedupe contract (THE invariant — admin-api.md §34,
+ * `src/lib/tracking/constants.ts:32-40`):
+ *   - Meta: the backend CAPI Purchase uses
+ *     `event_id = "purchase_" + order.display_id`. The client Pixel MUST
+ *     pass the same value as `eventID` on `fbq('track', 'Purchase', …)` —
+ *     `trackPurchase()` (fbq.ts) builds the id from `order.display_id` so
+ *     the format can never drift. Meta dedupes by event_name + event_id
+ *     within ~3 days.
+ *   - GA4: Measurement Protocol uses
+ *     `transaction_id = String(order.display_id)`; pass the same value in
+ *     `trackGAPurchase()` and GA4 dedupes automatically.
+ */
+
+export type TrackingConfig = {
+  facebookPixel?: { pixelId: string }
+  gtm?: { containerId: string }
+  ga4?: { measurementId: string }
+  klaviyo?: { publicKey: string }
+  /** Barter extension over the @1click TrackingConfig — explicit Google
+   *  Ads tag config (the @1click engine wired Ads through GTM). */
+  googleAds?: { conversionId: string; conversionLabel?: string }
+  /** True when the store's consent CMP is enabled — client tags must
+   *  mount through the consent gate (`_1c_consent` / Consent Mode v2). */
+  consent_required?: boolean
+}
+
+/** Envelope of `GET /api/store/integrations` (tracking key only — the
+ *  endpoint also serves carriers/COD blocks owned by other cards). */
+export type TrackingConfigResponse = {
+  tracking?: TrackingConfig
+}
+
+/** A single line item passed in `contents`. Meta requires `id` + `quantity`. */
+export type MetaContentItem = {
+  id: string
+  quantity: number
+  item_price?: number
+}
+
+export type ViewContentData = {
+  content_ids: string[]
+  content_type: "product" | "product_group"
+  currency: string
+  value: number
+}
+
+export type AddToCartData = {
+  content_ids: string[]
+  content_type: "product" | "product_group"
+  currency: string
+  value: number
+  contents: MetaContentItem[]
+}
+
+export type InitiateCheckoutData = {
+  content_ids: string[]
+  content_type: "product" | "product_group"
+  currency: string
+  value: number
+  num_items: number
+  contents: MetaContentItem[]
+}
+
+export type PurchaseData = {
+  content_ids: string[]
+  content_type: "product" | "product_group"
+  currency: string
+  value: number
+  num_items: number
+  contents: MetaContentItem[]
+}
+
+/**
+ * Lead event payload — shape per Meta's Lead standard event spec.
+ * All fields optional (Meta accepts an empty Lead). Storefront wraps
+ * popup signups + newsletter forms in a Lead event so Meta can
+ * optimize ad delivery for "likely subscribers" and build Lead
+ * lookalike audiences from our funnel.
+ */
+export type LeadData = {
+  /** Optional lead value (e.g. expected LTV for a subscriber). */
+  value?: number
+  currency?: string
+  /** Free-text label describing what the visitor signed up for —
+   *  e.g. "newsletter_popup", "newsletter_footer". */
+  content_name?: string
+  content_category?: string
+}
+
+/**
+ * Attribution payload written to `cart.metadata` before completion
+ * (consent-gated — see store-api.md "Tracking block" wiring contract).
+ * Cart completion copies these keys onto `order.metadata` and the barter
+ * `order.placed` forwarder reads exactly them to build the CAPI Purchase
+ * `user_data` and the GA4 MP Purchase `client_id` / `session_id`
+ * (code truth: `src/lib/tracking/constants.ts` TrackingAttributionMeta).
+ *
+ * - fb_fbp / fb_fbc: from _fbp / _fbc cookies (set by fbq init, or
+ *   defensively by attribution.ts before the Pixel loads)
+ * - fb_user_agent: from request User-Agent header
+ * - fb_client_ip: from request x-forwarded-for / x-real-ip
+ * - fb_event_source_url: from request Referer
+ * - ga_client_id: from _ga cookie value, schema prefix stripped
+ * - ga_session_id: parsed from _ga_<MEASUREMENT_ID> cookie's session segment
+ * - ga_engagement_time_msec: client-tracked time-on-session in ms
+ *   (passed in via clientHints on order placement, not derivable server-side)
+ */
+export type TrackingAttribution = {
+  fb_fbp?: string
+  fb_fbc?: string
+  fb_user_agent?: string
+  fb_client_ip?: string
+  fb_event_source_url?: string
+  /** Per-browser anonymous visitor id (cookie `_1c_anon`). Backend
+   *  uses this as `external_id` on the Purchase CAPI when no
+   *  customer_id is available, AND alongside customer_id when both
+   *  are known (Meta accepts external_id as an array, so dedup +
+   *  cross-session attribution both improve). */
+  fb_anon_id?: string
+  ga_client_id?: string
+  ga_session_id?: string
+  ga_engagement_time_msec?: number
+
+  // ── UTM attribution ────────────────────────────────────────────────
+  // Captured by browser-side `captureUtmsFromUrl()` (attribution.ts)
+  // into `_1c_utm_first` / `_1c_utm_last` cookies, then read here at
+  // checkout completion. Flat keys (instead of nested objects) so a
+  // raw `SELECT metadata->>'utm_first_source' FROM orders` query
+  // works without `jsonb_path_query`. Each tuple's `captured_at` is
+  // Unix seconds — `attribution_window_days = (order.created_at_unix
+  // - captured_at) / 86400`.
+
+  /** Acquisition (first-touch) UTM source — the campaign that
+   *  originally brought this visitor in. 365-day TTL. Stable across
+   *  multiple ad-click revisits. */
+  utm_first_source?: string
+  utm_first_medium?: string
+  utm_first_campaign?: string
+  utm_first_term?: string
+  utm_first_content?: string
+  utm_first_captured_at?: number
+
+  /** Closer (last-touch) UTM source — the campaign whose click
+   *  immediately preceded this order. 90-day TTL, refreshed on every
+   *  UTM-bearing visit. Aligns with Meta / Google Ads attribution
+   *  windows. */
+  utm_last_source?: string
+  utm_last_medium?: string
+  utm_last_campaign?: string
+  utm_last_term?: string
+  utm_last_content?: string
+  utm_last_captured_at?: number
+}
+
+/**
+ * Client-only attribution data — must be passed through to order
+ * placement by the storefront because it can't be read from
+ * cookies/headers on the server (the browser computes it during the
+ * session).
+ */
+export type TrackingClientHints = {
+  /** Accumulated time-on-session in ms (Date.now() - sessionStart). */
+  engagementTimeMsec?: number
+}

package/src/tracking/use-engagement-time.ts

@@ -0,0 +1,58 @@
+"use client"
+
+/**
+ * Engagement-time helpers (client only).
+ *
+ * The GA4 Measurement Protocol Purchase event needs
+ * `ga_engagement_time_msec` — how long the user spent in the session
+ * before placing the order. This can't be read from a cookie; it has
+ * to be tracked by the browser.
+ *
+ * Strategy: store `sessionStartTs` in `sessionStorage` on first read.
+ * On every subsequent call, return `Date.now() - sessionStartTs`.
+ * sessionStorage scopes to the tab — closing the tab resets the
+ * session, which is the desired behaviour.
+ *
+ * Cap at 30 minutes to filter out idle/dead-tab sessions. GA4's own
+ * session timeout default is 30 minutes, so this matches.
+ */
+
+const SESSION_KEY = "tracking_session_start"
+const MAX_ENGAGEMENT_MS = 30 * 60 * 1000 // 30 minutes
+
+/**
+ * Returns the current engagement time in milliseconds for this session.
+ * Returns 0 in non-browser contexts. Always returns a number ≥ 0.
+ */
+export function getEngagementTimeMsec(): number {
+  if (typeof window === "undefined") return 0
+  try {
+    let start = window.sessionStorage.getItem(SESSION_KEY)
+    if (!start) {
+      start = String(Date.now())
+      window.sessionStorage.setItem(SESSION_KEY, start)
+    }
+    const elapsed = Date.now() - Number(start)
+    if (!Number.isFinite(elapsed) || elapsed < 0) return 0
+    return Math.min(elapsed, MAX_ENGAGEMENT_MS)
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Initialise the session start timestamp now (no return value). Call
+ * from the root layout's MetaPixel/GA4 wrapper so the timer starts on
+ * first page view of the session, not on first checkout.
+ */
+export function initEngagementTime(): void {
+  if (typeof window === "undefined") return
+  try {
+    if (!window.sessionStorage.getItem(SESSION_KEY)) {
+      window.sessionStorage.setItem(SESSION_KEY, String(Date.now()))
+    }
+  } catch {
+    // sessionStorage unavailable — Safari private mode etc. Engagement
+    // time will be 0 in that case, which the backend treats as "unknown".
+  }
+}

package/tailwind-preset.cjs

@@ -0,0 +1,72 @@
+/**
+ * @cartbase/storefront Tailwind preset — shadcn/ui standard token structure
+ * (ported verbatim from @1click/ui tailwind-preset.cjs v2.3.1)
+ *
+ * Uses oklch color space (modern CSS standard, matches shadcn/ui Create output).
+ * CSS variables store raw oklch channels so Tailwind's opacity modifiers work:
+ *   --primary: 0.553 0.195 38.402;
+ *   → bg-primary    = oklch(0.553 0.195 38.402)
+ *   → bg-primary/50 = oklch(0.553 0.195 38.402 / 50%)
+ */
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        background: "oklch(var(--background) / <alpha-value>)",
+        foreground: "oklch(var(--foreground) / <alpha-value>)",
+        card: {
+          DEFAULT: "oklch(var(--card) / <alpha-value>)",
+          foreground: "oklch(var(--card-foreground) / <alpha-value>)",
+        },
+        popover: {
+          DEFAULT: "oklch(var(--popover) / <alpha-value>)",
+          foreground: "oklch(var(--popover-foreground) / <alpha-value>)",
+        },
+        primary: {
+          DEFAULT: "oklch(var(--primary) / <alpha-value>)",
+          foreground: "oklch(var(--primary-foreground) / <alpha-value>)",
+        },
+        secondary: {
+          DEFAULT: "oklch(var(--secondary) / <alpha-value>)",
+          foreground: "oklch(var(--secondary-foreground) / <alpha-value>)",
+        },
+        muted: {
+          DEFAULT: "oklch(var(--muted) / <alpha-value>)",
+          foreground: "oklch(var(--muted-foreground) / <alpha-value>)",
+        },
+        accent: {
+          DEFAULT: "oklch(var(--accent) / <alpha-value>)",
+          foreground: "oklch(var(--accent-foreground) / <alpha-value>)",
+        },
+        destructive: {
+          DEFAULT: "oklch(var(--destructive) / <alpha-value>)",
+          foreground: "oklch(var(--destructive-foreground) / <alpha-value>)",
+        },
+        border: "oklch(var(--border) / <alpha-value>)",
+        input: "oklch(var(--input) / <alpha-value>)",
+        ring: "oklch(var(--ring) / <alpha-value>)",
+        success: {
+          DEFAULT: "oklch(var(--success) / <alpha-value>)",
+          foreground: "oklch(var(--success-foreground) / <alpha-value>)",
+        },
+        warning: {
+          DEFAULT: "oklch(var(--warning) / <alpha-value>)",
+          foreground: "oklch(var(--warning-foreground) / <alpha-value>)",
+        },
+      },
+      fontFamily: {
+        display: ["var(--font-display)", "serif"],
+        body: ["var(--font-body)", "system-ui", "sans-serif"],
+        mono: ["var(--font-mono)", "ui-monospace", "monospace"],
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+    },
+  },
+  plugins: [],
+}