@cartbase/storefront 0.7.0 → 0.8.0

package/src/api/http.ts

@@ -4,9 +4,11 @@
  * Every SDK function in this package is a thin typed wrapper over
  * `storeFetch()` from a `StorefrontClient`. Auth model (store-api.md):
  *
- *  - `x-client-id`      — required for anon reads (RLS scope)
- *  - `x-publishable-api-key` — optional; scopes catalog/carts to the key's
- *                              sales channels when set
+ *  - `x-publishable-api-key` — THE store's key: names the store on its own
+ *                              (one key, 2026-09-07) and scopes catalog and
+ *                              carts to the key's sales channels
+ *  - `x-client-id`      — the platform's own door (hosted builds carry it);
+ *                          optional, wins over the key when both are sent
  *  - `authorization: Bearer <jwt>` — customer session (passwordless code
  *                              flow or supabase password login)
  *  - `x-locale`         — optional storefront locale hint
@@ -19,12 +21,16 @@
 import { StoreApiError } from "./types"
 
 export interface StorefrontClientConfig {
-  /** Deployment origin, e.g. `https://admin.mindpages.bg` */
+  /** Deployment origin, e.g. `https://admin.cartbase.ai` */
   baseUrl: string
-  /** Tenant id — required for anon reads. */
-  clientId: string
-  /** Publishable API key (channel scope). Optional for single-channel stores. */
+  /**
+   * The store's publishable key: names the store and scopes the catalog to
+   * the key's sales channels. The one input a merchant hands out; at least
+   * one of `publishableKey` and `clientId` is required.
+   */
   publishableKey?: string
+  /** Tenant id — the platform's own door. Optional when a key is given. */
+  clientId?: string
   /** Called per request; return the customer JWT or null for guests. */
   getAuthToken?: () => string | null | Promise<string | null>
   /** Called per request; return the active locale code or null. */
@@ -50,7 +56,9 @@ export interface RequestOptions {
 export class StorefrontClient {
   constructor(private readonly config: StorefrontClientConfig) {
     if (!config.baseUrl) throw new Error("StorefrontClient: baseUrl is required")
-    if (!config.clientId) throw new Error("StorefrontClient: clientId is required")
+    if (!config.publishableKey && !config.clientId) {
+      throw new Error("StorefrontClient: publishableKey (or clientId) is required")
+    }
   }
 
   /** The low-level typed request. Domain modules call this — apps rarely should. */
@@ -72,7 +80,7 @@ export class StorefrontClient {
     }
 
     const headers: Record<string, string> = {
-      "x-client-id": this.config.clientId,
+      ...(this.config.clientId ? { "x-client-id": this.config.clientId } : {}),
       ...(this.config.publishableKey
         ? { "x-publishable-api-key": this.config.publishableKey }
         : {}),

package/src/api/index.ts

@@ -13,6 +13,7 @@ export * as products from "./products"
 export * as collections from "./collections"
 export * as categories from "./categories"
 export * as regions from "./regions"
+export * as store from "./store"
 export * as carts from "./carts"
 export * as giftCards from "./gift-cards"
 export * as checkout from "./checkout"

package/src/api/store.ts

@@ -0,0 +1,35 @@
+/**
+ * @cartbase/storefront/api/store — the store's identity.
+ *
+ * Name, slug and brand (the merchant's Settings → Brand): what a
+ * storefront needs to title, head and foot itself without hardcoding a
+ * name. One anonymous read at layout level. Docs: docs/storefront/store.md.
+ */
+import type { StorefrontClient } from "./http"
+
+export interface StoreBrand {
+  /** Primary logo, public URL, or null. */
+  logo_url: string | null
+  /** Square mark, public URL, or null. */
+  logo_square_url: string | null
+  /** `#rrggbb` or null. */
+  color_primary: string | null
+  /** `#rrggbb` or null. */
+  color_secondary: string | null
+  slogan: string | null
+}
+
+export interface StoreIdentity {
+  /** The store's public id: what `<PlatformInit storeId>` mounts. */
+  id: string
+  /** The store's display name. */
+  name: string
+  /** The store's slug; its address is `{slug}.cartbase.net` until a custom domain. */
+  slug: string
+  brand: StoreBrand
+}
+
+/** GET /api/store/store — anon. */
+export function getStore(client: StorefrontClient): Promise<{ store: StoreIdentity }> {
+  return client.request<{ store: StoreIdentity }>("/api/store/store")
+}

package/src/checkout/geocode.ts

@@ -141,7 +141,7 @@ export async function geocodeAddress(
     url.searchParams.set("limit", "1")
 
     const res = await fetch(url.toString(), {
-      headers: { "User-Agent": "barter-storefront/1.0" },
+      headers: { "User-Agent": "cartbase-storefront/1.0" },
     })
     const data = await res.json()
     if (data?.[0]) {

package/src/lib/cookie-names.ts

@@ -39,3 +39,48 @@ export function readCartCookie(
 ): string | undefined {
   return get(CART_COOKIE) ?? get(LEGACY_CART_COOKIE)
 }
+
+/**
+ * THE VISITOR ID — our own per-browser id and the join key between browsing
+ * and money (ecommerce-analytics §3.1). It is OURS deliberately: the
+ * analytics engine is swappable, so a key owned by the engine would couple
+ * the whole platform to it.
+ *
+ * Written by the injected storefront proxy in a `Set-Cookie` header, never
+ * by `document.cookie`, and that is not a style preference: Safari's ITP
+ * caps JavaScript-written cookies at 7 days while server-set first-party
+ * cookies live up to 400. A JS-written id makes every returning Safari
+ * visitor read as new after a week.
+ */
+export const VISITOR_COOKIE = "_cartbase_visitor"
+
+/** @deprecated Pre-rename name — read-only compat, never written. */
+export const LEGACY_VISITOR_COOKIE = "_1c_anon"
+
+/** First-touch UTM tuple, written once, 365 days. */
+export const UTM_FIRST_COOKIE = "_cartbase_utm_first"
+/** @deprecated Pre-rename name — read-only compat, never written. */
+export const LEGACY_UTM_FIRST_COOKIE = "_1c_utm_first"
+
+/** Last-touch UTM tuple, rewritten on every UTM-bearing visit, 90 days. */
+export const UTM_LAST_COOKIE = "_cartbase_utm_last"
+/** @deprecated Pre-rename name — read-only compat, never written. */
+export const LEGACY_UTM_LAST_COOKIE = "_1c_utm_last"
+
+/** Known-visitor marker (localStorage, not a cookie). */
+export const KNOWN_VISITOR_KEY = "_cartbase_visitor_v1"
+/** @deprecated Pre-rename key — read-only compat, never written. */
+export const LEGACY_KNOWN_VISITOR_KEY = "_1c_visitor_v1"
+
+/**
+ * Read a value preferring the current name and falling back to the legacy
+ * one, so a visitor who arrived before the rename keeps their identity and
+ * their attribution instead of being counted as somebody new.
+ */
+export function readRenamedCookie(
+  get: (name: string) => string | undefined,
+  current: string,
+  legacy: string
+): string | undefined {
+  return get(current) ?? get(legacy)
+}

package/src/lib/platform.ts

@@ -0,0 +1,13 @@
+/**
+ * The platform's origin (one key, store-birth-and-doors item 6, 2026-09-07):
+ * a constant, not an input. Every Cartbase store's API lives here; a
+ * storefront overrides it only to point at a local or staging platform
+ * (`NEXT_PUBLIC_CARTBASE_URL`), never to find its own store, which the
+ * publishable key does.
+ */
+export const CARTBASE_API_ORIGIN = "https://admin.cartbase.ai"
+
+/** The origin to call: the override when set, else the platform. */
+export function cartbaseApiOrigin(override?: string | null): string {
+  return (override && override.trim()) || CARTBASE_API_ORIGIN
+}

package/src/lib/visitor.ts

@@ -0,0 +1,74 @@
+import { VISITOR_COOKIE, LEGACY_VISITOR_COOKIE } from "./cookie-names"
+
+/**
+ * THE VISITOR'S TWO IDS. One module, because three copies of a cookie read
+ * had already appeared across the package and a fourth was about to.
+ *
+ *  - The VISITOR id is the durable one. It is written by the platform's
+ *    injected proxy as a `Set-Cookie` on the very first request, which is
+ *    what makes it survive: Safari caps a cookie written by JavaScript at
+ *    seven days, so a returning visitor read from a JS-written id looks new
+ *    every week. It is the join key between a browsing session and the cart
+ *    and order it becomes.
+ *  - The TAB SESSION id is per tab and dies with it. Two tabs are two
+ *    sessions, which is what a merchant counting live visitors sees on
+ *    their own screen.
+ */
+
+/**
+ * Reads the platform's first-party visitor cookie, preferring the current
+ * name and falling back to the pre-rename one. Server-side there is no
+ * document, and callers pass the value explicitly instead.
+ */
+export function readVisitorId(): string | undefined {
+  if (typeof document === "undefined") return undefined
+  for (const name of [VISITOR_COOKIE, LEGACY_VISITOR_COOKIE]) {
+    const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`))
+    if (match) return decodeURIComponent(match[1])
+  }
+  return undefined
+}
+
+const TAB_SESSION_KEY = "_cartbase_live_session"
+
+function randomId(): string {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * One id per tab, shared by the heartbeat and the pageview tracker so the
+ * live count and the traffic report are talking about the same sessions.
+ */
+export function getTabSessionId(): string {
+  try {
+    const existing = window.sessionStorage.getItem(TAB_SESSION_KEY)
+    if (existing) return existing
+    const id = randomId()
+    window.sessionStorage.setItem(TAB_SESSION_KEY, id)
+    return id
+  } catch {
+    // Private mode with storage blocked: a per-mount id still produces an
+    // honest count, it just does not survive a reload.
+    return randomId()
+  }
+}
+
+/**
+ * True when the platform's injected collector is already running on this
+ * page. It claims the flag synchronously, before hydration, so any React
+ * component that checks this on mount sees a settled answer.
+ *
+ * Why it exists: every deployed storefront gets the collector injected at
+ * deploy time, and the scaffold ALSO mounts <StorefrontTags>. Without this
+ * check every store built from the scaffold would count every pageview
+ * twice, which is the kind of defect that looks like growth.
+ */
+export function platformCollectorPresent(): boolean {
+  try {
+    return Boolean((window as unknown as { __cartbase_collector?: unknown }).__cartbase_collector)
+  } catch {
+    return false
+  }
+}

package/src/tracking/attribution.ts

@@ -1,5 +1,16 @@
 "use client"
 
+import {
+  KNOWN_VISITOR_KEY,
+  LEGACY_KNOWN_VISITOR_KEY,
+  LEGACY_UTM_FIRST_COOKIE,
+  LEGACY_UTM_LAST_COOKIE,
+  LEGACY_VISITOR_COOKIE,
+  UTM_FIRST_COOKIE,
+  UTM_LAST_COOKIE,
+  VISITOR_COOKIE,
+} from "../lib/cookie-names"
+
 /**
  * Self-managed Facebook attribution helpers.
  *
@@ -29,10 +40,13 @@
 
 const FBP_COOKIE = "_fbp"
 const FBC_COOKIE = "_fbc"
-const ANON_ID_COOKIE = "_1c_anon"
-const KNOWN_VISITOR_LS = "_1c_visitor_v1"
-const UTM_FIRST_COOKIE = "_1c_utm_first"
-const UTM_LAST_COOKIE = "_1c_utm_last"
+
+// The visitor id and the UTM tuples moved into THE cookie registry
+// (cookie-names.ts) with the platform prefix, 2026-09-04. Every read
+// prefers the new name and falls back to the pre-rename one, so a visitor
+// who arrived earlier keeps their identity instead of being counted as new.
+const ANON_ID_COOKIE = VISITOR_COOKIE
+const KNOWN_VISITOR_LS = KNOWN_VISITOR_KEY
 
 /** _fbp / _fbc TTL per Meta spec — 90 days first-party. */
 const FB_COOKIE_TTL_DAYS = 90
@@ -157,7 +171,7 @@ export function getOrCreateFbc(): string | undefined {
  * it to cart.metadata for the order.placed subscriber.
  */
 export function getOrCreateAnonId(): string | undefined {
-  const existing = getCookie(ANON_ID_COOKIE)
+  const existing = getCookie(ANON_ID_COOKIE) ?? getCookie(LEGACY_VISITOR_COOKIE)
   if (existing) return existing
   if (!isBrowser()) return undefined
 
@@ -192,7 +206,9 @@ export function getKnownVisitor(): KnownVisitor {
   let stored: KnownVisitor = {}
   if (isBrowser()) {
     try {
-      const raw = window.localStorage.getItem(KNOWN_VISITOR_LS)
+      const raw =
+        window.localStorage.getItem(KNOWN_VISITOR_LS) ??
+        window.localStorage.getItem(LEGACY_KNOWN_VISITOR_KEY)
       if (raw) stored = JSON.parse(raw) as KnownVisitor
     } catch {
       // localStorage unavailable / parse error — return empty
@@ -373,8 +389,8 @@ function readUtmsFromSearch(search: string): CapturedUtms | null {
 /** Read + parse one of the two UTM cookies. Defensive — malformed JSON
  *  or shape drift returns null so the caller treats it as missing
  *  instead of crashing. */
-function readUtmsCookie(name: string): CapturedUtms | null {
-  const raw = getCookie(name)
+function readUtmsCookie(name: string, legacy?: string): CapturedUtms | null {
+  const raw = getCookie(name) ?? (legacy ? getCookie(legacy) : undefined)
   if (!raw) return null
   try {
     const parsed = JSON.parse(decodeURIComponent(raw)) as Partial<CapturedUtms>
@@ -420,7 +436,7 @@ export function captureUtmsFromUrl(): void {
   // First-touch: write only when the cookie is currently absent.
   // Re-arriving with a fresh UTM does NOT overwrite the original
   // acquisition record — that's the whole point of "first-touch".
-  if (!readUtmsCookie(UTM_FIRST_COOKIE)) {
+  if (!readUtmsCookie(UTM_FIRST_COOKIE, LEGACY_UTM_FIRST_COOKIE)) {
     writeUtmsCookie(UTM_FIRST_COOKIE, utms, UTM_FIRST_TTL_DAYS)
   }
   // Last-touch: always overwrite when the URL carries UTMs. Refreshes
@@ -436,7 +452,7 @@ export function captureUtmsFromUrl(): void {
  * cookies() API) instead — this function is browser-only.
  */
 export function getCapturedFirstTouchUtms(): CapturedUtms | null {
-  return readUtmsCookie(UTM_FIRST_COOKIE)
+  return readUtmsCookie(UTM_FIRST_COOKIE, LEGACY_UTM_FIRST_COOKIE)
 }
 
 /**
@@ -446,99 +462,99 @@ export function getCapturedFirstTouchUtms(): CapturedUtms | null {
  * this is browser-only.
  */
 export function getCapturedLastTouchUtms(): CapturedUtms | null {
-  return readUtmsCookie(UTM_LAST_COOKIE)
+  return readUtmsCookie(UTM_LAST_COOKIE, LEGACY_UTM_LAST_COOKIE)
+}
+
+// ── Ad-click identifiers ─────────────────────────────────────────────
+//
+// Meta's `fbclid` is folded into the `_fbc` cookie above by Meta's own
+// format. TikTok's and Google's click ids have no such carrier, and both
+// platforms need them:
+//
+//   ttclid  appended by TikTok to the landing URL on an ad click.
+//           Without it TikTok cannot tie a conversion back to the click
+//           that caused it, which is the reporting an advertiser checks
+//           first. Forwarded to the Events API as `user.ttclid`.
+//   _ttp    a first-party cookie the TikTok pixel writes ITSELF once
+//           first-party cookies are enabled in pixel settings. We never
+//           write it, only read it; forwarded as `user.ttp`.
+//   gclid   Google's standard click id.
+//   gbraid  iOS app-to-web variant.
+//   wbraid  iOS web-to-web variant.
+//
+// A Google campaign can deliver any one of those three, so capturing
+// gclid alone silently loses iOS traffic — the traffic most likely to be
+// missing a cookie in the first place.
+//
+// Write-once semantics deliberately do NOT apply: a newer click of the
+// same kind overwrites, because the most recent click is what the ad
+// platforms attribute to. What must never happen is a later ORGANIC
+// visit clearing the click that acquired the visitor, and that is why
+// each cookie is only touched when its parameter is actually present.
+
+const TTCLID_COOKIE = "_1c_ttclid"
+const GCLID_COOKIE = "_1c_gclid"
+const GBRAID_COOKIE = "_1c_gbraid"
+const WBRAID_COOKIE = "_1c_wbraid"
+
+/** TikTok's ttclid lifetime follows the CTA window in Attribution
+ *  Manager; Google's conversion window tops out at 90 days. One TTL
+ *  covers both, and each platform applies its own window on top and
+ *  ignores anything older. */
+const CLICK_ID_TTL_DAYS = 90
+
+/** Cookie name → the URL parameter it is captured from. */
+const CLICK_ID_CAPTURE: ReadonlyArray<readonly [string, string]> = [
+  [TTCLID_COOKIE, "ttclid"],
+  [GCLID_COOKIE, "gclid"],
+  [GBRAID_COOKIE, "gbraid"],
+  [WBRAID_COOKIE, "wbraid"],
+]
+
+/**
+ * The cookies the click ids live in, and the flat `order.metadata` keys
+ * the checkout writeback maps them onto. `ttp` is in the list because it
+ * is READ from TikTok's own cookie; it is never written here.
+ */
+export const CLICK_ID_COOKIES = {
+  ttclid: TTCLID_COOKIE,
+  gclid: GCLID_COOKIE,
+  gbraid: GBRAID_COOKIE,
+  wbraid: WBRAID_COOKIE,
+  ttp: "_ttp",
+} as const
+
+/** cookie name → order.metadata key (code truth for the server side:
+ *  `TrackingAttributionMeta` in src/lib/tracking/constants.ts). */
+export const CLICK_ID_METADATA_KEYS: ReadonlyArray<readonly [string, string]> = [
+  [CLICK_ID_COOKIES.ttclid, "tt_ttclid"],
+  [CLICK_ID_COOKIES.ttp, "tt_ttp"],
+  [CLICK_ID_COOKIES.gclid, "google_gclid"],
+  [CLICK_ID_COOKIES.gbraid, "google_gbraid"],
+  [CLICK_ID_COOKIES.wbraid, "google_wbraid"],
+]
+
+/**
+ * Capture every ad-click identifier present on the current URL.
+ *
+ * Idempotent and safe to call on every mount, next to
+ * `captureUtmsFromUrl()`: a URL carrying no click id leaves every
+ * existing cookie untouched.
+ */
+export function captureClickIdsFromUrl(): void {
+  if (!isBrowser()) return
+
+  let params: URLSearchParams
+  try {
+    params = new URLSearchParams(window.location.search)
+  } catch {
+    return
+  }
+
+  for (const [cookieName, param] of CLICK_ID_CAPTURE) {
+    const raw = params.get(param)
+    if (raw && raw.trim().length > 0) {
+      setCookie(cookieName, encodeURIComponent(raw.trim()), CLICK_ID_TTL_DAYS)
+    }
+  }
 }
-
-// ── Ad-click identifiers ─────────────────────────────────────────────
-//
-// Meta's `fbclid` is folded into the `_fbc` cookie above by Meta's own
-// format. TikTok's and Google's click ids have no such carrier, and both
-// platforms need them:
-//
-//   ttclid  appended by TikTok to the landing URL on an ad click.
-//           Without it TikTok cannot tie a conversion back to the click
-//           that caused it, which is the reporting an advertiser checks
-//           first. Forwarded to the Events API as `user.ttclid`.
-//   _ttp    a first-party cookie the TikTok pixel writes ITSELF once
-//           first-party cookies are enabled in pixel settings. We never
-//           write it, only read it; forwarded as `user.ttp`.
-//   gclid   Google's standard click id.
-//   gbraid  iOS app-to-web variant.
-//   wbraid  iOS web-to-web variant.
-//
-// A Google campaign can deliver any one of those three, so capturing
-// gclid alone silently loses iOS traffic — the traffic most likely to be
-// missing a cookie in the first place.
-//
-// Write-once semantics deliberately do NOT apply: a newer click of the
-// same kind overwrites, because the most recent click is what the ad
-// platforms attribute to. What must never happen is a later ORGANIC
-// visit clearing the click that acquired the visitor, and that is why
-// each cookie is only touched when its parameter is actually present.
-
-const TTCLID_COOKIE = "_1c_ttclid"
-const GCLID_COOKIE = "_1c_gclid"
-const GBRAID_COOKIE = "_1c_gbraid"
-const WBRAID_COOKIE = "_1c_wbraid"
-
-/** TikTok's ttclid lifetime follows the CTA window in Attribution
- *  Manager; Google's conversion window tops out at 90 days. One TTL
- *  covers both, and each platform applies its own window on top and
- *  ignores anything older. */
-const CLICK_ID_TTL_DAYS = 90
-
-/** Cookie name → the URL parameter it is captured from. */
-const CLICK_ID_CAPTURE: ReadonlyArray<readonly [string, string]> = [
-  [TTCLID_COOKIE, "ttclid"],
-  [GCLID_COOKIE, "gclid"],
-  [GBRAID_COOKIE, "gbraid"],
-  [WBRAID_COOKIE, "wbraid"],
-]
-
-/**
- * The cookies the click ids live in, and the flat `order.metadata` keys
- * the checkout writeback maps them onto. `ttp` is in the list because it
- * is READ from TikTok's own cookie; it is never written here.
- */
-export const CLICK_ID_COOKIES = {
-  ttclid: TTCLID_COOKIE,
-  gclid: GCLID_COOKIE,
-  gbraid: GBRAID_COOKIE,
-  wbraid: WBRAID_COOKIE,
-  ttp: "_ttp",
-} as const
-
-/** cookie name → order.metadata key (code truth for the server side:
- *  `TrackingAttributionMeta` in src/lib/tracking/constants.ts). */
-export const CLICK_ID_METADATA_KEYS: ReadonlyArray<readonly [string, string]> = [
-  [CLICK_ID_COOKIES.ttclid, "tt_ttclid"],
-  [CLICK_ID_COOKIES.ttp, "tt_ttp"],
-  [CLICK_ID_COOKIES.gclid, "google_gclid"],
-  [CLICK_ID_COOKIES.gbraid, "google_gbraid"],
-  [CLICK_ID_COOKIES.wbraid, "google_wbraid"],
-]
-
-/**
- * Capture every ad-click identifier present on the current URL.
- *
- * Idempotent and safe to call on every mount, next to
- * `captureUtmsFromUrl()`: a URL carrying no click id leaves every
- * existing cookie untouched.
- */
-export function captureClickIdsFromUrl(): void {
-  if (!isBrowser()) return
-
-  let params: URLSearchParams
-  try {
-    params = new URLSearchParams(window.location.search)
-  } catch {
-    return
-  }
-
-  for (const [cookieName, param] of CLICK_ID_CAPTURE) {
-    const raw = params.get(param)
-    if (raw && raw.trim().length > 0) {
-      setCookie(cookieName, encodeURIComponent(raw.trim()), CLICK_ID_TTL_DAYS)
-    }
-  }
-}

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

@@ -4,6 +4,14 @@ 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
@@ -73,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`.

package/src/tracking/index.ts

@@ -18,6 +18,10 @@
  *     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> —
@@ -55,6 +59,13 @@ 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"

package/src/tracking/live-heartbeat.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+import { useEffect } from "react"
+
+import { getTabSessionId, platformCollectorPresent, readVisitorId } from "../lib/visitor"
+
+/**
+ * The live-visitor heartbeat.
+ *
+ * While this tab is open it pings the store's own domain every 15 seconds.
+ * The platform counts a visitor as present while their last ping is inside
+ * a 30 second window, so a closed tab, a killed browser, a dropped network
+ * or a locked phone all disappear within half a minute with nothing to
+ * detect them — no unload handler, which browsers do not guarantee anyway,
+ * especially on mobile.
+ *
+ * Why a heartbeat instead of counting recent events: a shopper reading one
+ * product page for four minutes sends nothing in between, so an
+ * event-window count either forgets them or keeps counting people who left.
+ * A ping answers "who is on the store right now" literally.
+ *
+ * The path is first-party (`/_cb/heartbeat` on the merchant's own domain),
+ * which is what keeps it out of ad blockers and away from third-party
+ * cookie rules. The platform's injected proxy forwards it.
+ *
+ * Costs nothing when it fails: every call is fire-and-forget with keepalive,
+ * a dropped ping is one missing dot on a chart.
+ */
+const HEARTBEAT_MS = 15_000
+const ENDPOINT = "/_cb/heartbeat"
+
+export function LiveHeartbeat() {
+  useEffect(() => {
+    // The deploy-injected collector already does this on every page.
+    if (platformCollectorPresent()) return
+    const session = getTabSessionId()
+
+    const ping = () => {
+      const body = JSON.stringify({
+        session_id: session,
+        device_id: readVisitorId(),
+        // Path only. The platform drops query strings as well, because
+        // signed document links and login codes travel in them.
+        path: window.location.pathname,
+      })
+      void fetch(ENDPOINT, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true,
+      }).catch(() => undefined)
+    }
+
+    ping()
+    // No visibility handling on purpose (the live-polling law): browsers
+    // already throttle timers in a hidden tab, and anything that guesses at
+    // attention will eventually guess wrong.
+    const timer = setInterval(ping, HEARTBEAT_MS)
+    return () => clearInterval(timer)
+  }, [])
+
+  return null
+}