@cartbase/storefront 0.19.0 → 0.20.1

package/src/tracking/ttq.ts

@@ -1,180 +1,180 @@
-"use client"
-
-/**
- * Typed wrappers around the global `ttq` from the TikTok Pixel — the
- * TikTok twin of ./fbq.ts, and deliberately the same shape so a surface
- * that fires one can fire the other on the line below.
- *
- * Every helper no-ops when `window.ttq` is absent (pixel not configured,
- * server render, script blocked), so callers need no guards.
- *
- * Event names are case-sensitive and taken from TikTok's supported pixel
- * events table:
- * https://business-api.tiktok.com/portal/docs/supported-pixel-events/v1.3
- * `Purchase` is the current name; `CompletePayment` and `PlaceAnOrder` do
- * not appear in the current tables at all.
- *
- * `event_id` is the THIRD argument, a separate object after the
- * properties, per TikTok's own implementation guide:
- *
- *     ttq.track('Purchase', { ...properties }, { event_id: 'tt_purchase_1044' })
- *
- * TikTok deduplicates on event_source_id + event + event_id and discards
- * duplicates for 48 hours from the first event, which is how the browser
- * Purchase and the server-side Events API Purchase collapse into one.
- *
- * `content_id` must be the SAME identifier the product catalogue uses,
- * which on Cartbase is the PRODUCT id — the value the feed emits as
- * <g:id> and the value Meta already receives. A variant id here matches
- * no catalogue entry at all.
- */
-
-/** One product line inside `contents`. */
-export type TikTokContentItem = {
-  content_id: string
-  content_name?: string
-  content_category?: string
-  brand?: string
-  quantity?: number
-  price?: number
-}
-
-type TikTokProperties = {
-  contents?: TikTokContentItem[]
-  content_id?: string
-  content_name?: string
-  content_type?: "product" | "product_group"
-  currency?: string
-  value?: number
-  quantity?: number
-  description?: string
-  order_id?: string
-  /** TikTok's new-versus-returning signal. Same computed fact the backend
-   *  persists on the order and sends to Google Ads as `new_customer`. */
-  customer_type?: "new" | "returning"
-}
-
-type TtqFn = {
-  track: (
-    event: string,
-    properties?: TikTokProperties,
-    options?: { event_id?: string }
-  ) => void
-  page: () => void
-  identify: (data: Record<string, unknown>) => void
-  grantConsent: () => void
-  revokeConsent: () => void
-  holdConsent: () => void
-}
-
-function safeTtq(): TtqFn | null {
-  if (typeof window === "undefined") return null
-  const ttq = (window as unknown as { ttq?: Partial<TtqFn> }).ttq
-  if (!ttq || typeof ttq.track !== "function") return null
-  return ttq as TtqFn
-}
-
-/**
- * THE purchase dedup key — must equal what the backend forwarder sends
- * (`tiktokPurchaseEventId` in src/lib/tracking/constants.ts). Built from
- * display_id here so the format cannot drift between the two sides, the
- * same guarantee `trackPurchase` gives for Meta.
- */
-export function tiktokPurchaseEventId(displayId: string | number): string {
-  return `tt_purchase_${displayId}`
-}
-
-export function trackTikTokViewContent(data: {
-  contentId: string
-  contentName?: string
-  currency: string
-  value: number
-}): void {
-  const ttq = safeTtq()
-  if (!ttq) return
-  ttq.track("ViewContent", {
-    content_id: data.contentId,
-    content_type: "product",
-    content_name: data.contentName,
-    currency: data.currency,
-    value: data.value,
-  })
-}
-
-export function trackTikTokAddToCart(data: {
-  contentId: string
-  contentName?: string
-  quantity: number
-  price: number
-  currency: string
-  value: number
-}): void {
-  const ttq = safeTtq()
-  if (!ttq) return
-  ttq.track("AddToCart", {
-    contents: [
-      {
-        content_id: data.contentId,
-        content_name: data.contentName,
-        quantity: data.quantity,
-        price: data.price,
-      },
-    ],
-    content_type: "product",
-    currency: data.currency,
-    value: data.value,
-  })
-}
-
-export function trackTikTokInitiateCheckout(data: {
-  contents: TikTokContentItem[]
-  currency: string
-  value: number
-}): void {
-  const ttq = safeTtq()
-  if (!ttq) return
-  ttq.track("InitiateCheckout", {
-    contents: data.contents,
-    content_type: "product",
-    currency: data.currency,
-    value: data.value,
-  })
-}
-
-export function trackTikTokPurchase(data: {
-  contents: TikTokContentItem[]
-  currency: string
-  value: number
-  /** The order's display id — the dedup key and the order_id TikTok shows. */
-  displayId: string | number
-  customerType?: "new" | "returning"
-}): void {
-  const ttq = safeTtq()
-  if (!ttq) return
-  ttq.track(
-    "Purchase",
-    {
-      contents: data.contents,
-      content_type: "product",
-      currency: data.currency,
-      value: data.value,
-      order_id: String(data.displayId),
-      ...(data.customerType ? { customer_type: data.customerType } : {}),
-    },
-    { event_id: tiktokPurchaseEventId(data.displayId) }
-  )
-}
-
-/**
- * Push a live consent decision to the pixel.
- *
- * Normally you do NOT call this: `applyConsent()` in ./consent.ts already
- * relays every decision to gtag, fbq and ttq together. It is exported for
- * a host app driving the pixel from a consent layer of its own.
- */
-export function applyTikTokConsent(adsGranted: boolean): void {
-  const ttq = safeTtq()
-  if (!ttq) return
-  if (adsGranted) ttq.grantConsent()
-  else ttq.revokeConsent()
-}
+"use client"
+
+/**
+ * Typed wrappers around the global `ttq` from the TikTok Pixel — the
+ * TikTok twin of ./fbq.ts, and deliberately the same shape so a surface
+ * that fires one can fire the other on the line below.
+ *
+ * Every helper no-ops when `window.ttq` is absent (pixel not configured,
+ * server render, script blocked), so callers need no guards.
+ *
+ * Event names are case-sensitive and taken from TikTok's supported pixel
+ * events table:
+ * https://business-api.tiktok.com/portal/docs/supported-pixel-events/v1.3
+ * `Purchase` is the current name; `CompletePayment` and `PlaceAnOrder` do
+ * not appear in the current tables at all.
+ *
+ * `event_id` is the THIRD argument, a separate object after the
+ * properties, per TikTok's own implementation guide:
+ *
+ *     ttq.track('Purchase', { ...properties }, { event_id: 'tt_purchase_1044' })
+ *
+ * TikTok deduplicates on event_source_id + event + event_id and discards
+ * duplicates for 48 hours from the first event, which is how the browser
+ * Purchase and the server-side Events API Purchase collapse into one.
+ *
+ * `content_id` must be the SAME identifier the product catalogue uses,
+ * which on Cartbase is the PRODUCT id — the value the feed emits as
+ * <g:id> and the value Meta already receives. A variant id here matches
+ * no catalogue entry at all.
+ */
+
+/** One product line inside `contents`. */
+export type TikTokContentItem = {
+  content_id: string
+  content_name?: string
+  content_category?: string
+  brand?: string
+  quantity?: number
+  price?: number
+}
+
+type TikTokProperties = {
+  contents?: TikTokContentItem[]
+  content_id?: string
+  content_name?: string
+  content_type?: "product" | "product_group"
+  currency?: string
+  value?: number
+  quantity?: number
+  description?: string
+  order_id?: string
+  /** TikTok's new-versus-returning signal. Same computed fact the backend
+   *  persists on the order and sends to Google Ads as `new_customer`. */
+  customer_type?: "new" | "returning"
+}
+
+type TtqFn = {
+  track: (
+    event: string,
+    properties?: TikTokProperties,
+    options?: { event_id?: string }
+  ) => void
+  page: () => void
+  identify: (data: Record<string, unknown>) => void
+  grantConsent: () => void
+  revokeConsent: () => void
+  holdConsent: () => void
+}
+
+function safeTtq(): TtqFn | null {
+  if (typeof window === "undefined") return null
+  const ttq = (window as unknown as { ttq?: Partial<TtqFn> }).ttq
+  if (!ttq || typeof ttq.track !== "function") return null
+  return ttq as TtqFn
+}
+
+/**
+ * THE purchase dedup key — must equal what the backend forwarder sends
+ * (`tiktokPurchaseEventId` in src/lib/tracking/constants.ts). Built from
+ * display_id here so the format cannot drift between the two sides, the
+ * same guarantee `trackPurchase` gives for Meta.
+ */
+export function tiktokPurchaseEventId(displayId: string | number): string {
+  return `tt_purchase_${displayId}`
+}
+
+export function trackTikTokViewContent(data: {
+  contentId: string
+  contentName?: string
+  currency: string
+  value: number
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("ViewContent", {
+    content_id: data.contentId,
+    content_type: "product",
+    content_name: data.contentName,
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackTikTokAddToCart(data: {
+  contentId: string
+  contentName?: string
+  quantity: number
+  price: number
+  currency: string
+  value: number
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("AddToCart", {
+    contents: [
+      {
+        content_id: data.contentId,
+        content_name: data.contentName,
+        quantity: data.quantity,
+        price: data.price,
+      },
+    ],
+    content_type: "product",
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackTikTokInitiateCheckout(data: {
+  contents: TikTokContentItem[]
+  currency: string
+  value: number
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("InitiateCheckout", {
+    contents: data.contents,
+    content_type: "product",
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackTikTokPurchase(data: {
+  contents: TikTokContentItem[]
+  currency: string
+  value: number
+  /** The order's display id — the dedup key and the order_id TikTok shows. */
+  displayId: string | number
+  customerType?: "new" | "returning"
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track(
+    "Purchase",
+    {
+      contents: data.contents,
+      content_type: "product",
+      currency: data.currency,
+      value: data.value,
+      order_id: String(data.displayId),
+      ...(data.customerType ? { customer_type: data.customerType } : {}),
+    },
+    { event_id: tiktokPurchaseEventId(data.displayId) }
+  )
+}
+
+/**
+ * Push a live consent decision to the pixel.
+ *
+ * Normally you do NOT call this: `applyConsent()` in ./consent.ts already
+ * relays every decision to gtag, fbq and ttq together. It is exported for
+ * a host app driving the pixel from a consent layer of its own.
+ */
+export function applyTikTokConsent(adsGranted: boolean): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  if (adsGranted) ttq.grantConsent()
+  else ttq.revokeConsent()
+}

package/src/tracking/use-tracking-config.ts

@@ -1,54 +1,54 @@
-"use client"
-
-import { useEffect, useState } from "react"
-
-import type { StorefrontClient } from "../api/http"
-import { getTrackingConfig } from "./get-tracking-config"
-import type { TrackingConfig } from "./types"
-
-/**
- * The store's public tag config, from a client component.
- *
- * `<StorefrontTags>` reads the same config on the SERVER, which is right
- * for mounting tags in a layout. This hook exists for the one place that
- * genuinely cannot: a client page that needs the config to decide what to
- * send, the order confirmation being the case that matters, because
- * Google Ads needs the account id and the purchase label to build a valid
- * `send_to`.
- *
- * Cached per browser session in module scope: the config changes only
- * when a merchant edits Settings → Integrations, and re-fetching it on
- * every mount would put a request in front of the purchase event.
- *
- * Returns undefined until the fetch resolves, and `{}` if it fails, so a
- * caller renders and fires the vendors that need no config either way.
- */
-
-let cached: TrackingConfig | undefined
-let inFlight: Promise<TrackingConfig> | undefined
-
-export function useTrackingConfig(
-  client: StorefrontClient
-): TrackingConfig | undefined {
-  const [config, setConfig] = useState<TrackingConfig | undefined>(cached)
-
-  useEffect(() => {
-    if (cached) return
-    let active = true
-    inFlight =
-      inFlight ??
-      getTrackingConfig(client).then((value) => {
-        cached = value
-        inFlight = undefined
-        return value
-      })
-    inFlight.then((value) => {
-      if (active) setConfig(value)
-    })
-    return () => {
-      active = false
-    }
-  }, [client])
-
-  return config
-}
+"use client"
+
+import { useEffect, useState } from "react"
+
+import type { StorefrontClient } from "../api/http"
+import { getTrackingConfig } from "./get-tracking-config"
+import type { TrackingConfig } from "./types"
+
+/**
+ * The store's public tag config, from a client component.
+ *
+ * `<StorefrontTags>` reads the same config on the SERVER, which is right
+ * for mounting tags in a layout. This hook exists for the one place that
+ * genuinely cannot: a client page that needs the config to decide what to
+ * send, the order confirmation being the case that matters, because
+ * Google Ads needs the account id and the purchase label to build a valid
+ * `send_to`.
+ *
+ * Cached per browser session in module scope: the config changes only
+ * when a merchant edits Settings → Integrations, and re-fetching it on
+ * every mount would put a request in front of the purchase event.
+ *
+ * Returns undefined until the fetch resolves, and `{}` if it fails, so a
+ * caller renders and fires the vendors that need no config either way.
+ */
+
+let cached: TrackingConfig | undefined
+let inFlight: Promise<TrackingConfig> | undefined
+
+export function useTrackingConfig(
+  client: StorefrontClient
+): TrackingConfig | undefined {
+  const [config, setConfig] = useState<TrackingConfig | undefined>(cached)
+
+  useEffect(() => {
+    if (cached) return
+    let active = true
+    inFlight =
+      inFlight ??
+      getTrackingConfig(client).then((value) => {
+        cached = value
+        inFlight = undefined
+        return value
+      })
+    inFlight.then((value) => {
+      if (active) setConfig(value)
+    })
+    return () => {
+      active = false
+    }
+  }, [client])
+
+  return config
+}

package/theme/index.css

@@ -1,25 +1,25 @@
-/*
- * Cartbase storefront theme — the one line a storefront imports.
- *
- *   @import "tailwindcss";
- *   @import "@cartbase/storefront/theme";
- *
- * That is the whole setup. There is no Tailwind config file, no preset to
- * register, and no list of token names to copy: Tailwind 4 reads the theme
- * from CSS, and this ships filled, so a fresh install renders as a designed
- * store rather than grey boxes.
- *
- * To retheme, override the values from tokens.css in your own stylesheet
- * AFTER this import. Never edit the vocabulary — components reference those
- * names, and changing one moves every storefront at once.
- */
-@import "./tokens.css";
-@import "./theme.css";
-
-/* The page's own ground. Without this the body inherits the browser default
-   and every surface token above renders against white regardless of theme. */
-body {
-  background-color: var(--background);
-  color: var(--foreground);
-  font-family: var(--font-body-family);
-}
+/*
+ * Cartbase storefront theme — the one line a storefront imports.
+ *
+ *   @import "tailwindcss";
+ *   @import "@cartbase/storefront/theme";
+ *
+ * That is the whole setup. There is no Tailwind config file, no preset to
+ * register, and no list of token names to copy: Tailwind 4 reads the theme
+ * from CSS, and this ships filled, so a fresh install renders as a designed
+ * store rather than grey boxes.
+ *
+ * To retheme, override the values from tokens.css in your own stylesheet
+ * AFTER this import. Never edit the vocabulary — components reference those
+ * names, and changing one moves every storefront at once.
+ */
+@import "./tokens.css";
+@import "./theme.css";
+
+/* The page's own ground. Without this the body inherits the browser default
+   and every surface token above renders against white regardless of theme. */
+body {
+  background-color: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-body-family);
+}