@cartbase/storefront 0.21.0 → 0.22.0

package/src/tracking/once.ts

@@ -0,0 +1,137 @@
+"use client"
+
+/**
+ * once — "fire this tracking event at most once per cart" guard.
+ *
+ * Why this exists:
+ *
+ *   The mid-funnel checkout events (add_shipping_info, add_payment_info)
+ *   are driven by FORM STATE, not by a one-shot user action. A shopper
+ *   can switch courier, toggle card and cash on delivery, correct a typo
+ *   in their address or refresh the page, and each of those re-runs the
+ *   effect that would fire the event. Without a guard one shopper emits a
+ *   dozen add_payment_info events, which wrecks the funnel ratios in GA4
+ *   and Rybbit and teaches Meta's optimizer that the event is worthless.
+ *
+ *   A `useRef` guard is NOT enough: it lives in React memory and resets on
+ *   every remount, so a refresh or a walk back into the checkout re-fires.
+ *   The guard has to outlive the component.
+ *
+ * Design:
+ *
+ *   - Keyed by `${event}:${cartId}` so a genuinely NEW cart (the shopper
+ *     bought, then started a second order) fires its own events. The same
+ *     cart never fires twice.
+ *   - `sessionStorage`, not `localStorage`: the guard should expire when
+ *     the browsing session does. A shopper returning tomorrow to the same
+ *     abandoned cart is a new session and legitimately re-enters the
+ *     funnel.
+ *   - An in-memory Set mirrors the store, so repeated calls within one
+ *     page never touch sessionStorage (Safari throws on quota and in
+ *     private mode; we degrade to memory-only rather than fire twice).
+ *
+ * Belt and braces: callers pair this with a DETERMINISTIC `event_id` (see
+ * `checkoutStepEventId`) so that even if the guard is defeated, by two
+ * tabs on one cart or by storage cleared mid-session, Meta still collapses
+ * the duplicates server-side by event_id, exactly as it does for
+ * Purchase's `purchase_${display_id}`.
+ */
+
+const STORAGE_KEY = "cartbase:fired-events"
+
+/** Mirrors sessionStorage so repeat calls in one page skip storage I/O. */
+const memory = new Set<string>()
+
+function readStore(): Set<string> {
+  if (memory.size > 0) return memory
+  if (typeof window === "undefined") return memory
+  try {
+    const raw = window.sessionStorage.getItem(STORAGE_KEY)
+    if (raw) {
+      const parsed = JSON.parse(raw) as unknown
+      if (Array.isArray(parsed)) {
+        for (const k of parsed) if (typeof k === "string") memory.add(k)
+      }
+    }
+  } catch {
+    // Private mode, quota, corrupt JSON: memory-only from here.
+  }
+  return memory
+}
+
+function persist(): void {
+  if (typeof window === "undefined") return
+  try {
+    window.sessionStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify(Array.from(memory))
+    )
+  } catch {
+    // Storage unavailable: the in-memory Set still dedupes this page.
+  }
+}
+
+/**
+ * Returns true the FIRST time it is called for a given (event, cartId)
+ * pair and false every time after, marking the pair as fired.
+ *
+ * Callers treat it as the gate itself:
+ *
+ *   if (!markFiredOnce("add_payment_info", cart.id)) return
+ *   trackCheckoutPaymentInfo(...)
+ *
+ * Returns false when `cartId` is missing: a checkout-step event with no
+ * cart to key on cannot be deduped, and firing an undedupable event is
+ * worse than dropping it.
+ */
+export function markFiredOnce(
+  event: string,
+  cartId: string | undefined | null
+): boolean {
+  if (!cartId) return false
+  if (typeof window === "undefined") return false
+
+  const key = `${event}:${cartId}`
+  const store = readStore()
+  if (store.has(key)) return false
+
+  store.add(key)
+  persist()
+  return true
+}
+
+/** Read-only check, does not mark. For conditional UI and debugging. */
+export function hasFired(
+  event: string,
+  cartId: string | undefined | null
+): boolean {
+  if (!cartId || typeof window === "undefined") return false
+  return readStore().has(`${event}:${cartId}`)
+}
+
+/**
+ * Deterministic Meta `event_id` for a checkout-step event.
+ *
+ * Unlike `generateEventId()` (random, for events with no natural key),
+ * this derives the id from the cart, so the SAME logical action always
+ * produces the SAME id. That gives Meta a server-side dedup key: two tabs,
+ * a restored session or a retried request all collapse into one event
+ * instead of inflating the count. Same principle as Purchase's
+ * `purchase_${display_id}`.
+ */
+export function checkoutStepEventId(event: string, cartId: string): string {
+  return `${event}_${cartId}`
+}
+
+/**
+ * Forget every guard for one cart. Called when the order is placed, so a
+ * shopper who starts a second order in the same session is not silenced by
+ * the keys of the cart they just bought.
+ */
+export function forgetFiredEvents(cartId: string | undefined | null): void {
+  if (!cartId) return
+  for (const key of Array.from(memory)) {
+    if (key.endsWith(`:${cartId}`)) memory.delete(key)
+  }
+  persist()
+}

package/src/tracking/rybbit-events.ts

@@ -179,6 +179,22 @@ export type RybbitBeginCheckoutData = {
   value: number
 }
 
+export type RybbitAddShippingInfoData = {
+  item_ids: string[]
+  num_items: number
+  currency: string
+  value: number
+  shipping_tier?: string
+}
+
+export type RybbitAddPaymentInfoData = {
+  item_ids: string[]
+  num_items: number
+  currency: string
+  value: number
+  payment_type?: string
+}
+
 export type RybbitPurchaseData = {
   transaction_id: string
   item_ids: string[]
@@ -217,6 +233,32 @@ export function trackRybbitBeginCheckout(
   })
 }
 
+export function trackRybbitAddShippingInfo(
+  data: RybbitAddShippingInfoData
+): void {
+  fireEvent("add_shipping_info", {
+    item_ids: joinIds(data.item_ids),
+    num_items: data.num_items,
+    currency: data.currency,
+    value: data.value,
+    // Rybbit accepts string and number only, so an empty tier is omitted
+    // rather than sent as "".
+    ...(data.shipping_tier ? { shipping_tier: data.shipping_tier } : {}),
+  })
+}
+
+export function trackRybbitAddPaymentInfo(
+  data: RybbitAddPaymentInfoData
+): void {
+  fireEvent("add_payment_info", {
+    item_ids: joinIds(data.item_ids),
+    num_items: data.num_items,
+    currency: data.currency,
+    value: data.value,
+    ...(data.payment_type ? { payment_type: data.payment_type } : {}),
+  })
+}
+
 /**
  * Purchase event — fired client-side on the order-confirmed page.
  *

package/src/tracking/ttq.ts

@@ -141,6 +141,30 @@ export function trackTikTokInitiateCheckout(data: {
   })
 }
 
+/**
+ * AddPaymentInfo — TikTok's own standard event, fired when the shopper has
+ * settled how they will pay. There is no TikTok equivalent of
+ * `add_shipping_info`, so the shipping step reaches Meta, GA4 and Rybbit
+ * and stops there; inventing a custom event on this vendor would optimise
+ * nothing and report nowhere.
+ */
+export function trackTikTokAddPaymentInfo(data: {
+  contents: TikTokContentItem[]
+  currency: string
+  value: number
+  paymentType?: string
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("AddPaymentInfo", {
+    contents: data.contents,
+    content_type: "product",
+    currency: data.currency,
+    value: data.value,
+    ...(data.paymentType ? { payment_type: data.paymentType } : {}),
+  })
+}
+
 export function trackTikTokPurchase(data: {
   contents: TikTokContentItem[]
   currency: string

package/src/tracking/types.ts

@@ -93,6 +93,40 @@ export type InitiateCheckoutData = {
   contents: MetaContentItem[]
 }
 
+/**
+ * AddShippingInfo. Not one of Meta's standard events, so the Pixel takes
+ * it through `trackCustom`; GA4 and Rybbit both name it
+ * `add_shipping_info`. `shipping_tier` is the courier the shopper chose,
+ * omitted while they have filled the address but picked nobody yet.
+ */
+export type AddShippingInfoData = {
+  content_ids: string[]
+  content_type: "product" | "product_group"
+  currency: string
+  value: number
+  num_items: number
+  contents: MetaContentItem[]
+  shipping_tier?: string
+}
+
+/**
+ * AddPaymentInfo, a Meta standard event. Cash on delivery counts: Meta
+ * defines the event as "payment information is added in the checkout
+ * flow" and GA4 defines `payment_type` as "the chosen method of payment",
+ * so choosing to pay the courier completes the step, it just involves no
+ * card. Carrying `payment_type` is what keeps the two paths separable in
+ * reporting.
+ */
+export type AddPaymentInfoData = {
+  content_ids: string[]
+  content_type: "product" | "product_group"
+  currency: string
+  value: number
+  num_items: number
+  contents: MetaContentItem[]
+  payment_type?: string
+}
+
 export type PurchaseData = {
   content_ids: string[]
   content_type: "product" | "product_group"