@cartbase/storefront 0.6.0 → 0.7.0

package/README.md

@@ -1,58 +1,75 @@
-# @cartbase/storefront
-
-The storefront kit for the [Cartbase](https://cartbase.net) commerce
-platform: a fully-typed API client for every store endpoint, checkout
-orchestration, a production-grade cart drawer, product and catalog
-components, and consent-gated tracking — everything a storefront needs
-between your pages and your store.
-
-```bash
-npm create cartbase my-store    # scaffold with everything prewired
-# or add to an existing Next.js app:
-npm install @cartbase/storefront
-```
-
-## Setup
-
-The package is **source-shipped TypeScript** — tell Next.js to compile it:
-
-```js
-// next.config.js
-module.exports = {
-  transpilePackages: ["@cartbase/storefront"],
-}
-```
-
-Three environment values wire it to your store (all in your Cartbase
-admin under **Settings**):
-
-```bash
-NEXT_PUBLIC_CARTBASE_URL=            # your store's API origin
-NEXT_PUBLIC_CARTBASE_CLIENT_ID=      # your store's client id
-NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=  # optional, channel-scoped catalogs
-```
-
-## What's inside
-
-| Import | What you get |
-|---|---|
-| `@cartbase/storefront/api` | Typed client for the whole store API — products, carts, checkout, orders, customers, auth, content, search, reviews |
-| `@cartbase/storefront/checkout` | The complete checkout: orchestration hook, address forms, shipping/payment method lists, Stripe wrapper, carrier pickers |
-| `@cartbase/storefront/cart-drawer` | Slide-out cart with upsells, tiers, gift options, notes |
-| `@cartbase/storefront/products` | PDP building blocks: gallery, options, prices, actions |
-| `@cartbase/storefront/store` | Listing pages: pagination, sorting, collection/category/search templates |
-| `@cartbase/storefront/order` | Order confirmation surfaces |
-| `@cartbase/storefront/tracking` | Consent banner + consent-gated Meta Pixel / GA4 / analytics |
-| `@cartbase/storefront/theme` | The design system: token names plus a filled default set of values (Tailwind 4, CSS-first) |
-
-## Documentation
-
-The complete reference — every endpoint with request/response shapes and
-working examples, plus a step-by-step build runbook — is written to be
-followed by a developer **or handed to a coding agent as-is**. It ships
-inside every `npm create cartbase` scaffold under `docs/`, and online at
-your store's docs site. Start with *Build a storefront — the runbook*.
-
-## License
-
-MIT © Cartbase
+# @cartbase/storefront
+
+The storefront kit for the [Cartbase](https://cartbase.net) commerce
+platform: a fully-typed API client for every store endpoint, checkout
+orchestration, a production-grade cart drawer, product and catalog
+components, and consent-gated tracking — everything a storefront needs
+between your pages and your store.
+
+```bash
+npm create cartbase my-store    # scaffold with everything prewired
+# or add to an existing Next.js app:
+npm install @cartbase/storefront
+```
+
+## Setup
+
+The package is **source-shipped TypeScript** — tell Next.js to compile it:
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ["@cartbase/storefront"],
+}
+```
+
+Three environment values wire it to your store (all in your Cartbase
+admin under **Settings**):
+
+```bash
+NEXT_PUBLIC_CARTBASE_URL=            # your store's API origin
+NEXT_PUBLIC_CARTBASE_CLIENT_ID=      # your store's client id
+NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=  # optional, channel-scoped catalogs
+```
+
+## What's inside
+
+| Import | What you get |
+|---|---|
+| `@cartbase/storefront/api` | Typed client for the whole store API — products, carts, checkout, orders, customers, auth, content, search, reviews |
+| `@cartbase/storefront/checkout` | The complete checkout: orchestration hook, address forms, shipping/payment method lists, Stripe wrapper, carrier pickers |
+| `@cartbase/storefront/cart-drawer` | Slide-out cart with upsells, tiers, gift options, notes |
+| `@cartbase/storefront/products` | PDP building blocks: gallery, options, prices, actions |
+| `@cartbase/storefront/store` | Listing pages: pagination, sorting, collection/category/search templates |
+| `@cartbase/storefront/order` | Order confirmation surfaces |
+| `@cartbase/storefront/tracking` | Consent banner and Consent Mode v2, every marketing tag the store configured mounted from its own config (Meta Pixel, TikTok, Google Analytics 4 and Google Ads on one tag, Google Tag Manager), and one call per commerce moment that fires all of them |
+| `@cartbase/storefront/theme` | The design system: token names plus a filled default set of values (Tailwind 4, CSS-first) |
+
+### Tracking, in three lines
+
+The merchant configures their pixels in the admin; the storefront mounts
+what they configured. Nothing per vendor:
+
+```tsx
+<ConsentInit />                 // first child of <body>, sets the consent defaults
+<StorefrontTags client={client} />  // every configured tag, gated by the above
+<TrackInit />                   // captures UTMs + ad-click ids on the landing page
+```
+
+Then one call per moment (`trackProductView`, `trackCartAdd`,
+`trackCheckoutStart`) and `<TrackOrderPurchase>` on the confirmation
+page. Purchase events dedupe against the platform's own server-side
+events automatically — the ids are derived from the order number on both
+sides, so the browser event and the server event count as one conversion.
+
+## Documentation
+
+The complete reference — every endpoint with request/response shapes and
+working examples, plus a step-by-step build runbook — is written to be
+followed by a developer **or handed to a coding agent as-is**. It ships
+inside every `npm create cartbase` scaffold under `docs/`, and online at
+your store's docs site. Start with *Build a storefront — the runbook*.
+
+## License
+
+MIT © Cartbase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {
@@ -77,12 +77,22 @@
     "./tracking/consent-banner": "./src/tracking/consent-banner.tsx",
     "./tracking/meta-pixel": "./src/tracking/meta-pixel.tsx",
     "./tracking/ga4": "./src/tracking/ga4.tsx",
+    "./tracking/tiktok-pixel": "./src/tracking/tiktok-pixel.tsx",
+    "./tracking/ttq": "./src/tracking/ttq.ts",
+    "./tracking/events": "./src/tracking/events.ts",
+    "./tracking/storefront-tags": "./src/tracking/storefront-tags.tsx",
+    "./tracking/track-init": "./src/tracking/track-init.tsx",
+    "./tracking/track-order-purchase": "./src/tracking/track-order-purchase.tsx",
+    "./tracking/gtm": "./src/tracking/gtm.tsx",
+    "./tracking/inline-script": "./src/tracking/inline-script.ts",
+    "./tracking/google-ads": "./src/tracking/google-ads.ts",
     "./tracking/rybbit": "./src/tracking/rybbit.tsx",
     "./tracking/rybbit-events": "./src/tracking/rybbit-events.ts",
     "./tracking/fbq": "./src/tracking/fbq.ts",
     "./tracking/gtag": "./src/tracking/gtag.ts",
     "./tracking/attribution": "./src/tracking/attribution.ts",
     "./tracking/get-tracking-config": "./src/tracking/get-tracking-config.ts",
+    "./tracking/use-tracking-config": "./src/tracking/use-tracking-config.ts",
     "./tracking/get-tracking-attribution": "./src/tracking/get-tracking-attribution.ts",
     "./tracking/use-engagement-time": "./src/tracking/use-engagement-time.ts",
     "./checkout": "./src/checkout/index.ts",

package/src/api/integrations.ts

@@ -1,117 +1,118 @@
-/**
- * @cartbase/storefront/api/integrations — store-public integrations config
- * (couriers-port + tracking-integrations cards).
- *
- * Ground truth: src/app/api/store/integrations/{route.ts,boxnow/lockers/
- * route.ts} + src/lib/integrations/store-config.ts +
- * src/lib/tracking/store-config-block.ts.
- *
- * The config payload is COMPOSED from an ordered block registry — each
- * block owns distinct top-level keys (`carriers`, `tracking` today; future
- * blocks append). NOT wrapped in an envelope: the blocks ARE the top-level
- * keys. (The `cod` block died with the 'cod' integration, 2026-08-11 —
- * method fees now ride the payment listing entries themselves.)
- *
- * SECURITY LAW: every block is an explicit allowlist — credentials
- * (carrier API keys, CAPI access_token, GA4 api_secret, Klaviyo
- * private_key) can NEVER appear in this payload; the contract tests assert
- * it key-by-key.
- */
-
-import type { StorefrontClient } from "./http"
-
-/** Public capability flags of one ENABLED carrier. */
-export interface PublicCarrierConfig {
-  enabled: true
-  /** Carrier supports cash-on-delivery collection. */
-  cod: boolean
-  /** Office/pickup-point delivery. */
-  pickup_points: boolean
-  /** Locker/APM network. */
-  lockers: boolean
-  /** Present only when lockers=true — the public locker-directory endpoint
-   * (path relative to the API base, e.g. `/api/store/integrations/boxnow/lockers`). */
-  lockers_url?: string
-}
-
-/** Public tag config — only ENABLED providers with a public id appear.
- * Secrets can never appear here (explicit allowlist). */
-export interface StoreTrackingBlock {
-  facebookPixel?: { pixelId: string }
-  gtm?: { containerId: string }
-  ga4?: { measurementId: string }
-  klaviyo?: { publicKey: string }
-  googleAds?: { conversionId: string; conversionLabel?: string }
-  /** True when the store's consent CMP is enabled — mount tags ONLY through
-   * the consent gate (`_1c_consent` / Consent Mode v2). */
-  consent_required: boolean
-}
-
-/** The composed payload of GET /api/store/integrations. */
-export interface StoreIntegrationsConfig {
-  /** Keyed by provider slug (e.g. `boxnow`, `econt`). Disabled carriers are
-   * ABSENT, never `enabled: false`. */
-  carriers: Record<string, PublicCarrierConfig>
-  tracking: StoreTrackingBlock
-}
-
-/**
- * GET /api/store/integrations — everything a storefront needs at render/
- * checkout time about the store's integrations, secrets excluded by
- * construction.
- *
- * Auth: anon (x-client-id); `x-publishable-api-key` is VALIDATED when the
- * client sends one (unknown/revoked/foreign → 400 invalid_publishable_key)
- * and may be omitted by single-channel storefronts.
- * Errors: 400 missing_client_id · 400 invalid_publishable_key.
- * Settings: admin → Settings → Integrations (per-provider enable/config);
- * consent settings drive `tracking.consent_required`.
- *
- * Storefront wiring: mount tags from `tracking` + consent state; Purchase
- * events MUST use `eventID = "purchase_" + order.display_id` so Meta
- * dedupes browser Pixel vs server CAPI; write TrackingAttribution keys into
- * `cart.metadata` (consent-gated) so server events inherit fbp/fbc/ga
- * signals.
- */
-export async function getIntegrationsConfig(
-  client: StorefrontClient
-): Promise<StoreIntegrationsConfig> {
-  return client.get("/api/store/integrations")
-}
-
-/** One BoxNow locker (APM) for the checkout picker. */
-export interface BoxNowLocker {
-  id: string
-  title: string
-  addressLine1: string
-  addressLine2: string
-  postalCode: string
-  country: string
-  /** Numbers or null — malformed carrier coordinates coerce to null, never NaN. */
-  lat: number | null
-  lng: number | null
-  note: string
-}
-
-export interface BoxNowLockersResponse {
-  lockers: BoxNowLocker[]
-}
-
-/**
- * GET /api/store/integrations/boxnow/lockers — the BoxNow locker directory
- * for the checkout locker picker. Cached hard (in-process 10-min TTL per
- * store + `Cache-Control: public, max-age=600, stale-while-revalidate=3600`)
- * — locker locations change on a weeks timescale.
- *
- * Auth: anon (x-client-id).
- * Errors: 503 `{message, lockers: []}` when BoxNow is not configured/
- * enabled for the store · 502 `{message, lockers: []}` when the carrier
- * call fails. (Both carry the `lockers` key — a picker can always map over
- * it.) Discover availability via `carriers.boxnow.lockers_url` on the
- * integrations config instead of probing for the 503.
- */
-export async function listBoxNowLockers(
-  client: StorefrontClient
-): Promise<BoxNowLockersResponse> {
-  return client.get("/api/store/integrations/boxnow/lockers")
-}
+/**
+ * @cartbase/storefront/api/integrations — store-public integrations config
+ * (couriers-port + tracking-integrations cards).
+ *
+ * Ground truth: src/app/api/store/integrations/{route.ts,boxnow/lockers/
+ * route.ts} + src/lib/integrations/store-config.ts +
+ * src/lib/tracking/store-config-block.ts.
+ *
+ * The config payload is COMPOSED from an ordered block registry — each
+ * block owns distinct top-level keys (`carriers`, `tracking` today; future
+ * blocks append). NOT wrapped in an envelope: the blocks ARE the top-level
+ * keys. (The `cod` block died with the 'cod' integration, 2026-08-11 —
+ * method fees now ride the payment listing entries themselves.)
+ *
+ * SECURITY LAW: every block is an explicit allowlist — credentials
+ * (carrier API keys, CAPI access_token, GA4 api_secret, Klaviyo
+ * private_key) can NEVER appear in this payload; the contract tests assert
+ * it key-by-key.
+ */
+
+import type { StorefrontClient } from "./http"
+
+/** Public capability flags of one ENABLED carrier. */
+export interface PublicCarrierConfig {
+  enabled: true
+  /** Carrier supports cash-on-delivery collection. */
+  cod: boolean
+  /** Office/pickup-point delivery. */
+  pickup_points: boolean
+  /** Locker/APM network. */
+  lockers: boolean
+  /** Present only when lockers=true — the public locker-directory endpoint
+   * (path relative to the API base, e.g. `/api/store/integrations/boxnow/lockers`). */
+  lockers_url?: string
+}
+
+/** Public tag config — only ENABLED providers with a public id appear.
+ * Secrets can never appear here (explicit allowlist). */
+export interface StoreTrackingBlock {
+  facebookPixel?: { pixelId: string }
+  gtm?: { containerId: string }
+  ga4?: { measurementId: string }
+  klaviyo?: { publicKey: string }
+  googleAds?: { conversionId: string; conversionLabel?: string }
+  tiktok?: { pixelId: string }
+  /** True when the store's consent CMP is enabled — mount tags ONLY through
+   * the consent gate (`_1c_consent` / Consent Mode v2). */
+  consent_required: boolean
+}
+
+/** The composed payload of GET /api/store/integrations. */
+export interface StoreIntegrationsConfig {
+  /** Keyed by provider slug (e.g. `boxnow`, `econt`). Disabled carriers are
+   * ABSENT, never `enabled: false`. */
+  carriers: Record<string, PublicCarrierConfig>
+  tracking: StoreTrackingBlock
+}
+
+/**
+ * GET /api/store/integrations — everything a storefront needs at render/
+ * checkout time about the store's integrations, secrets excluded by
+ * construction.
+ *
+ * Auth: anon (x-client-id); `x-publishable-api-key` is VALIDATED when the
+ * client sends one (unknown/revoked/foreign → 400 invalid_publishable_key)
+ * and may be omitted by single-channel storefronts.
+ * Errors: 400 missing_client_id · 400 invalid_publishable_key.
+ * Settings: admin → Settings → Integrations (per-provider enable/config);
+ * consent settings drive `tracking.consent_required`.
+ *
+ * Storefront wiring: mount tags from `tracking` + consent state; Purchase
+ * events MUST use `eventID = "purchase_" + order.display_id` so Meta
+ * dedupes browser Pixel vs server CAPI; write TrackingAttribution keys into
+ * `cart.metadata` (consent-gated) so server events inherit fbp/fbc/ga
+ * signals.
+ */
+export async function getIntegrationsConfig(
+  client: StorefrontClient
+): Promise<StoreIntegrationsConfig> {
+  return client.get("/api/store/integrations")
+}
+
+/** One BoxNow locker (APM) for the checkout picker. */
+export interface BoxNowLocker {
+  id: string
+  title: string
+  addressLine1: string
+  addressLine2: string
+  postalCode: string
+  country: string
+  /** Numbers or null — malformed carrier coordinates coerce to null, never NaN. */
+  lat: number | null
+  lng: number | null
+  note: string
+}
+
+export interface BoxNowLockersResponse {
+  lockers: BoxNowLocker[]
+}
+
+/**
+ * GET /api/store/integrations/boxnow/lockers — the BoxNow locker directory
+ * for the checkout locker picker. Cached hard (in-process 10-min TTL per
+ * store + `Cache-Control: public, max-age=600, stale-while-revalidate=3600`)
+ * — locker locations change on a weeks timescale.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 503 `{message, lockers: []}` when BoxNow is not configured/
+ * enabled for the store · 502 `{message, lockers: []}` when the carrier
+ * call fails. (Both carry the `lockers` key — a picker can always map over
+ * it.) Discover availability via `carriers.boxnow.lockers_url` on the
+ * integrations config instead of probing for the 503.
+ */
+export async function listBoxNowLockers(
+  client: StorefrontClient
+): Promise<BoxNowLockersResponse> {
+  return client.get("/api/store/integrations/boxnow/lockers")
+}

package/src/tracking/attribution.ts

@@ -265,6 +265,38 @@ export function normalisePhoneForHash(raw: string): string {
   return digits
 }
 
+/**
+ * Normalise a phone for GOOGLE, which is not the same string as Meta's.
+ *
+ * Google requires E.164 WITH the leading plus: "must be 11 to 15 digits
+ * including a plus sign (+) prefix and country code with no dashes,
+ * parentheses, or spaces"
+ * (https://support.google.com/google-ads/answer/13258081). Meta requires
+ * digits only. Two different strings, two different digests, and a shared
+ * normaliser can only ever serve one of them.
+ *
+ * This existing as a separate function is the fix for a real defect:
+ * `setEnhancedConversions` fed Meta's digits-only value into Google's
+ * `sha256_phone_number`, which matched nobody, for as long as it shipped.
+ * It fails silently — gtag accepts the hash, no error is raised anywhere,
+ * and the only symptom is enhanced conversions recovering fewer
+ * conversions than they should. Whoever refactors these two into one
+ * "shared" helper will recreate it.
+ *
+ * Returns undefined when the result could not be a real E.164 number:
+ * hashing a malformed number is strictly worse than sending nothing,
+ * because it cannot match AND it occupies the field Google would
+ * otherwise fall back from.
+ */
+export function normalisePhoneForGoogleHash(raw: string): string | undefined {
+  const digits = normalisePhoneForHash(raw)
+  if (!digits) return undefined
+  // Google's stated range, country code included. A Bulgarian mobile is
+  // 12 digits (359 plus 9 national).
+  if (digits.length < 11 || digits.length > 15) return undefined
+  return "+" + digits
+}
+
 // ── UTM attribution capture ──────────────────────────────────────────
 //
 // Captures `utm_source / utm_medium / utm_campaign / utm_term /
@@ -416,3 +448,97 @@ export function getCapturedFirstTouchUtms(): CapturedUtms | null {
 export function getCapturedLastTouchUtms(): CapturedUtms | null {
   return readUtmsCookie(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)
+    }
+  }
+}

package/src/tracking/consent.ts

@@ -117,6 +117,20 @@ export function applyConsent(choices: ConsentChoices): void {
   if (typeof w.fbq === "function") {
     w.fbq("consent", choices.ads ? "grant" : "revoke")
   }
+
+  // TikTok. `ttq` registers grantConsent / revokeConsent alongside track
+  // and page, and `setAndDefer` queues them before the SDK is fetched, so
+  // this works whether or not the pixel script has loaded yet.
+  //
+  // The decision is relayed HERE, in the one function every consent door
+  // already goes through (the built-in banner, setConsent for an external
+  // CMP), rather than by watching the cookie from outside. A vendor added
+  // to this list is live everywhere at once; a vendor that has to poll for
+  // the decision is a vendor that will one day miss it.
+  if (w.ttq && typeof w.ttq.grantConsent === "function") {
+    if (choices.ads) w.ttq.grantConsent()
+    else w.ttq.revokeConsent()
+  }
 }
 
 /**