@cartbase/storefront 0.20.0 → 0.21.0

package/src/tracking/events.ts

@@ -1,348 +1,348 @@
-"use client"
-
-import {
-  trackAddToCart,
-  trackInitiateCheckout,
-  trackPurchase,
-  trackViewContent,
-} from "./fbq"
-import {
-  trackGAAddToCart,
-  trackGABeginCheckout,
-  trackGAPurchase,
-  trackGAViewItem,
-} from "./gtag"
-import {
-  trackRybbitAddToCart,
-  trackRybbitBeginCheckout,
-  trackRybbitPurchase,
-  trackRybbitViewItem,
-} from "./rybbit-events"
-import {
-  trackTikTokAddToCart,
-  trackTikTokInitiateCheckout,
-  trackTikTokPurchase,
-  trackTikTokViewContent,
-} from "./ttq"
-import {
-  minorUnits,
-  trackOpenAiCheckoutStarted,
-  trackOpenAiContentsViewed,
-  trackOpenAiItemsAdded,
-  trackOpenAiOrderCreated,
-  type OpenAiContentItem,
-} from "./oaiq"
-import { googleAdsPurchaseSendTo, trackGoogleAdsPurchase } from "./google-ads"
-import type { TrackingConfig } from "./types"
-
-/**
- * ONE call per commerce moment, every vendor at once.
- *
- * The per-vendor helpers beside this file stay exported and stay usable.
- * This is the door a storefront should reach for anyway, because the
- * failure these functions prevent is the most common one in tracking and
- * it is invisible: a store adds a fifth vendor, updates four call sites,
- * misses the fifth, and nobody notices until an ad account has been
- * optimising on partial data for a month. We have watched it happen to a
- * product page whose buy box predated a shared helper: ViewContent and
- * InitiateCheckout were present, AddToCart was missing from the single
- * most-used add path in the store.
- *
- * With one function per moment, a vendor is added HERE, once, and every
- * surface that already calls it gains the vendor for free.
- *
- * Every helper underneath no-ops when its tag is absent, so passing a
- * config with only two vendors configured fires exactly those two.
- *
- * Identifier discipline, and it is not cosmetic:
- *   - `productId` is the catalogue key. Meta's content_ids, TikTok's
- *     content_id and the feed's <g:id> must be the SAME value or the
- *     event matches no catalogue entry, which costs dynamic ads and
- *     product-level reporting on both platforms.
- *   - GA4 is the exception on purpose: its items are keyed by VARIANT,
- *     because GA4 reports on what was actually bought rather than
- *     matching an ads catalogue.
- *   - Purchase dedup keys are derived from `displayId` inside the
- *     helpers, never passed in, so the browser and the server cannot
- *     drift apart.
- */
-
-/** One line, in the shape every vendor is derived from. */
-export type TrackedLine = {
-  /** Catalogue key. Meta + TikTok content ids, and the feed's <g:id>. */
-  productId: string
-  /** What was actually bought. GA4 item_id. */
-  variantId?: string
-  title: string
-  quantity: number
-  /** Unit price, in `currency`. */
-  price: number
-}
-
-export type TrackedOrder = {
-  /** THE dedup key across every vendor and both sides of the wire. */
-  displayId: string | number
-  currency: string
-  /** Order total actually collected. */
-  value: number
-  tax?: number
-  shipping?: number
-  coupon?: string
-  lines: TrackedLine[]
-  /**
-   * First order for this buyer. Computed server-side by the order.placed
-   * forwarder and persisted on the order as `metadata.customer_type`;
-   * read it from there rather than deriving it in the browser, so the two
-   * sides tell the ad platforms the same thing. Omit when unknown.
-   */
-  customerType?: "new" | "returning"
-}
-
-const gaItems = (lines: TrackedLine[], currency: string) =>
-  lines.map((line, index) => ({
-    item_id: line.variantId || line.productId,
-    item_name: line.title,
-    quantity: line.quantity,
-    price: line.price,
-    currency,
-    index,
-  }))
-
-const metaContents = (lines: TrackedLine[]) =>
-  lines.map((line) => ({
-    id: line.productId,
-    quantity: line.quantity,
-    item_price: line.price,
-  }))
-
-const tiktokContents = (lines: TrackedLine[]) =>
-  lines.map((line) => ({
-    content_id: line.productId,
-    content_name: line.title,
-    quantity: line.quantity,
-    price: line.price,
-  }))
-
-const unitCount = (lines: TrackedLine[]) =>
-  lines.reduce((sum, line) => sum + (Number(line.quantity) || 0), 0)
-
-/**
- * ChatGPT Ads contents. The shape is close to TikTok's, but every amount
- * is an INTEGER IN MINOR UNITS on this vendor, which is why the mapping
- * cannot be shared with `tiktokContents` above: the same numbers in the
- * same field names would be a hundredfold under-report.
- */
-const openAiContents = (
-  lines: TrackedLine[],
-  currency: string
-): OpenAiContentItem[] =>
-  lines.map((line) => ({
-    id: line.productId,
-    name: line.title,
-    content_type: "product",
-    quantity: line.quantity,
-    amount: minorUnits(line.price),
-    currency,
-  }))
-
-/** Product page view. */
-export function trackProductView(input: {
-  line: TrackedLine
-  currency: string
-  value: number
-}): void {
-  const { line, currency, value } = input
-  trackViewContent({
-    content_ids: [line.productId],
-    content_type: "product",
-    currency,
-    value,
-  })
-  trackTikTokViewContent({
-    contentId: line.productId,
-    contentName: line.title,
-    currency,
-    value,
-  })
-  trackOpenAiContentsViewed({
-    contentId: line.productId,
-    contentName: line.title,
-    currency,
-    value,
-  })
-  trackGAViewItem({ currency, value, items: gaItems([line], currency) })
-  trackRybbitViewItem({
-    item_id: line.variantId || line.productId,
-    item_name: line.title,
-    currency,
-    value,
-  })
-}
-
-/** Add to cart, from ANY surface — listing card, buy box, upsell rail. */
-export function trackCartAdd(input: {
-  line: TrackedLine
-  currency: string
-  value: number
-}): void {
-  const { line, currency, value } = input
-  trackAddToCart({
-    content_ids: [line.productId],
-    content_type: "product",
-    currency,
-    value,
-    contents: metaContents([line]),
-  })
-  trackTikTokAddToCart({
-    contentId: line.productId,
-    contentName: line.title,
-    quantity: line.quantity,
-    price: line.price,
-    currency,
-    value,
-  })
-  trackOpenAiItemsAdded({
-    contentId: line.productId,
-    contentName: line.title,
-    quantity: line.quantity,
-    price: line.price,
-    currency,
-    value,
-  })
-  trackGAAddToCart({ currency, value, items: gaItems([line], currency) })
-  trackRybbitAddToCart({
-    item_id: line.variantId || line.productId,
-    item_name: line.title,
-    quantity: line.quantity,
-    currency,
-    value,
-  })
-}
-
-/** Checkout started. */
-export function trackCheckoutStart(input: {
-  lines: TrackedLine[]
-  currency: string
-  value: number
-  coupon?: string
-}): void {
-  const { lines, currency, value, coupon } = input
-  trackInitiateCheckout({
-    content_ids: lines.map((line) => line.productId),
-    content_type: "product",
-    currency,
-    value,
-    num_items: unitCount(lines),
-    contents: metaContents(lines),
-  })
-  trackTikTokInitiateCheckout({
-    contents: tiktokContents(lines),
-    currency,
-    value,
-  })
-  trackOpenAiCheckoutStarted({
-    contents: openAiContents(lines, currency),
-    currency,
-    value,
-  })
-  trackGABeginCheckout({
-    currency,
-    value,
-    items: gaItems(lines, currency),
-    ...(coupon ? { coupon } : {}),
-  })
-  trackRybbitBeginCheckout({
-    item_ids: lines.map((line) => line.variantId || line.productId),
-    num_items: unitCount(lines),
-    currency,
-    value,
-  })
-}
-
-/**
- * Order confirmed — the money event.
- *
- * Google Ads only fires when the store configured BOTH the account id
- * and the purchase conversion label, which is why the config is a
- * parameter here: `googleAdsPurchaseSendTo` returns null otherwise, and a
- * malformed `send_to` is accepted by Google and silently dropped.
- *
- * Everything here is deduped against the server: Meta on
- * `purchase_<displayId>`, TikTok on `tt_purchase_<displayId>`, ChatGPT Ads
- * on `oai_order_<displayId>`, GA4 and Google Ads on the transaction id,
- * which is `displayId` itself.
- */
-export function trackOrderPurchase(
-  order: TrackedOrder,
-  config?: TrackingConfig
-): void {
-  const {
-    displayId,
-    currency,
-    value,
-    lines,
-    tax,
-    shipping,
-    coupon,
-    customerType,
-  } = order
-  const transactionId = String(displayId)
-
-  trackPurchase(
-    {
-      content_ids: lines.map((line) => line.productId),
-      content_type: "product",
-      currency,
-      value,
-      num_items: unitCount(lines),
-      contents: metaContents(lines),
-    },
-    displayId
-  )
-
-  trackTikTokPurchase({
-    contents: tiktokContents(lines),
-    currency,
-    value,
-    displayId,
-    customerType,
-  })
-
-  trackOpenAiOrderCreated({
-    contents: openAiContents(lines, currency),
-    currency,
-    value,
-    displayId,
-  })
-
-  trackGAPurchase({
-    transaction_id: transactionId,
-    currency,
-    value,
-    items: gaItems(lines, currency),
-    ...(typeof tax === "number" ? { tax } : {}),
-    ...(typeof shipping === "number" ? { shipping } : {}),
-    ...(coupon ? { coupon } : {}),
-  })
-
-  trackRybbitPurchase({
-    transaction_id: transactionId,
-    item_ids: lines.map((line) => line.variantId || line.productId),
-    num_items: unitCount(lines),
-    currency,
-    value,
-  })
-
-  const sendTo = config ? googleAdsPurchaseSendTo(config) : null
-  if (sendTo) {
-    trackGoogleAdsPurchase({
-      sendTo,
-      value,
-      currency,
-      transactionId,
-      ...(customerType
-        ? { newCustomer: customerType === "new" }
-        : {}),
-    })
-  }
-}
+"use client"
+
+import {
+  trackAddToCart,
+  trackInitiateCheckout,
+  trackPurchase,
+  trackViewContent,
+} from "./fbq"
+import {
+  trackGAAddToCart,
+  trackGABeginCheckout,
+  trackGAPurchase,
+  trackGAViewItem,
+} from "./gtag"
+import {
+  trackRybbitAddToCart,
+  trackRybbitBeginCheckout,
+  trackRybbitPurchase,
+  trackRybbitViewItem,
+} from "./rybbit-events"
+import {
+  trackTikTokAddToCart,
+  trackTikTokInitiateCheckout,
+  trackTikTokPurchase,
+  trackTikTokViewContent,
+} from "./ttq"
+import {
+  minorUnits,
+  trackOpenAiCheckoutStarted,
+  trackOpenAiContentsViewed,
+  trackOpenAiItemsAdded,
+  trackOpenAiOrderCreated,
+  type OpenAiContentItem,
+} from "./oaiq"
+import { googleAdsPurchaseSendTo, trackGoogleAdsPurchase } from "./google-ads"
+import type { TrackingConfig } from "./types"
+
+/**
+ * ONE call per commerce moment, every vendor at once.
+ *
+ * The per-vendor helpers beside this file stay exported and stay usable.
+ * This is the door a storefront should reach for anyway, because the
+ * failure these functions prevent is the most common one in tracking and
+ * it is invisible: a store adds a fifth vendor, updates four call sites,
+ * misses the fifth, and nobody notices until an ad account has been
+ * optimising on partial data for a month. We have watched it happen to a
+ * product page whose buy box predated a shared helper: ViewContent and
+ * InitiateCheckout were present, AddToCart was missing from the single
+ * most-used add path in the store.
+ *
+ * With one function per moment, a vendor is added HERE, once, and every
+ * surface that already calls it gains the vendor for free.
+ *
+ * Every helper underneath no-ops when its tag is absent, so passing a
+ * config with only two vendors configured fires exactly those two.
+ *
+ * Identifier discipline, and it is not cosmetic:
+ *   - `productId` is the catalogue key. Meta's content_ids, TikTok's
+ *     content_id and the feed's <g:id> must be the SAME value or the
+ *     event matches no catalogue entry, which costs dynamic ads and
+ *     product-level reporting on both platforms.
+ *   - GA4 is the exception on purpose: its items are keyed by VARIANT,
+ *     because GA4 reports on what was actually bought rather than
+ *     matching an ads catalogue.
+ *   - Purchase dedup keys are derived from `displayId` inside the
+ *     helpers, never passed in, so the browser and the server cannot
+ *     drift apart.
+ */
+
+/** One line, in the shape every vendor is derived from. */
+export type TrackedLine = {
+  /** Catalogue key. Meta + TikTok content ids, and the feed's <g:id>. */
+  productId: string
+  /** What was actually bought. GA4 item_id. */
+  variantId?: string
+  title: string
+  quantity: number
+  /** Unit price, in `currency`. */
+  price: number
+}
+
+export type TrackedOrder = {
+  /** THE dedup key across every vendor and both sides of the wire. */
+  displayId: string | number
+  currency: string
+  /** Order total actually collected. */
+  value: number
+  tax?: number
+  shipping?: number
+  coupon?: string
+  lines: TrackedLine[]
+  /**
+   * First order for this buyer. Computed server-side by the order.placed
+   * forwarder and persisted on the order as `metadata.customer_type`;
+   * read it from there rather than deriving it in the browser, so the two
+   * sides tell the ad platforms the same thing. Omit when unknown.
+   */
+  customerType?: "new" | "returning"
+}
+
+const gaItems = (lines: TrackedLine[], currency: string) =>
+  lines.map((line, index) => ({
+    item_id: line.variantId || line.productId,
+    item_name: line.title,
+    quantity: line.quantity,
+    price: line.price,
+    currency,
+    index,
+  }))
+
+const metaContents = (lines: TrackedLine[]) =>
+  lines.map((line) => ({
+    id: line.productId,
+    quantity: line.quantity,
+    item_price: line.price,
+  }))
+
+const tiktokContents = (lines: TrackedLine[]) =>
+  lines.map((line) => ({
+    content_id: line.productId,
+    content_name: line.title,
+    quantity: line.quantity,
+    price: line.price,
+  }))
+
+const unitCount = (lines: TrackedLine[]) =>
+  lines.reduce((sum, line) => sum + (Number(line.quantity) || 0), 0)
+
+/**
+ * ChatGPT Ads contents. The shape is close to TikTok's, but every amount
+ * is an INTEGER IN MINOR UNITS on this vendor, which is why the mapping
+ * cannot be shared with `tiktokContents` above: the same numbers in the
+ * same field names would be a hundredfold under-report.
+ */
+const openAiContents = (
+  lines: TrackedLine[],
+  currency: string
+): OpenAiContentItem[] =>
+  lines.map((line) => ({
+    id: line.productId,
+    name: line.title,
+    content_type: "product",
+    quantity: line.quantity,
+    amount: minorUnits(line.price),
+    currency,
+  }))
+
+/** Product page view. */
+export function trackProductView(input: {
+  line: TrackedLine
+  currency: string
+  value: number
+}): void {
+  const { line, currency, value } = input
+  trackViewContent({
+    content_ids: [line.productId],
+    content_type: "product",
+    currency,
+    value,
+  })
+  trackTikTokViewContent({
+    contentId: line.productId,
+    contentName: line.title,
+    currency,
+    value,
+  })
+  trackOpenAiContentsViewed({
+    contentId: line.productId,
+    contentName: line.title,
+    currency,
+    value,
+  })
+  trackGAViewItem({ currency, value, items: gaItems([line], currency) })
+  trackRybbitViewItem({
+    item_id: line.variantId || line.productId,
+    item_name: line.title,
+    currency,
+    value,
+  })
+}
+
+/** Add to cart, from ANY surface — listing card, buy box, upsell rail. */
+export function trackCartAdd(input: {
+  line: TrackedLine
+  currency: string
+  value: number
+}): void {
+  const { line, currency, value } = input
+  trackAddToCart({
+    content_ids: [line.productId],
+    content_type: "product",
+    currency,
+    value,
+    contents: metaContents([line]),
+  })
+  trackTikTokAddToCart({
+    contentId: line.productId,
+    contentName: line.title,
+    quantity: line.quantity,
+    price: line.price,
+    currency,
+    value,
+  })
+  trackOpenAiItemsAdded({
+    contentId: line.productId,
+    contentName: line.title,
+    quantity: line.quantity,
+    price: line.price,
+    currency,
+    value,
+  })
+  trackGAAddToCart({ currency, value, items: gaItems([line], currency) })
+  trackRybbitAddToCart({
+    item_id: line.variantId || line.productId,
+    item_name: line.title,
+    quantity: line.quantity,
+    currency,
+    value,
+  })
+}
+
+/** Checkout started. */
+export function trackCheckoutStart(input: {
+  lines: TrackedLine[]
+  currency: string
+  value: number
+  coupon?: string
+}): void {
+  const { lines, currency, value, coupon } = input
+  trackInitiateCheckout({
+    content_ids: lines.map((line) => line.productId),
+    content_type: "product",
+    currency,
+    value,
+    num_items: unitCount(lines),
+    contents: metaContents(lines),
+  })
+  trackTikTokInitiateCheckout({
+    contents: tiktokContents(lines),
+    currency,
+    value,
+  })
+  trackOpenAiCheckoutStarted({
+    contents: openAiContents(lines, currency),
+    currency,
+    value,
+  })
+  trackGABeginCheckout({
+    currency,
+    value,
+    items: gaItems(lines, currency),
+    ...(coupon ? { coupon } : {}),
+  })
+  trackRybbitBeginCheckout({
+    item_ids: lines.map((line) => line.variantId || line.productId),
+    num_items: unitCount(lines),
+    currency,
+    value,
+  })
+}
+
+/**
+ * Order confirmed — the money event.
+ *
+ * Google Ads only fires when the store configured BOTH the account id
+ * and the purchase conversion label, which is why the config is a
+ * parameter here: `googleAdsPurchaseSendTo` returns null otherwise, and a
+ * malformed `send_to` is accepted by Google and silently dropped.
+ *
+ * Everything here is deduped against the server: Meta on
+ * `purchase_<displayId>`, TikTok on `tt_purchase_<displayId>`, ChatGPT Ads
+ * on `oai_order_<displayId>`, GA4 and Google Ads on the transaction id,
+ * which is `displayId` itself.
+ */
+export function trackOrderPurchase(
+  order: TrackedOrder,
+  config?: TrackingConfig
+): void {
+  const {
+    displayId,
+    currency,
+    value,
+    lines,
+    tax,
+    shipping,
+    coupon,
+    customerType,
+  } = order
+  const transactionId = String(displayId)
+
+  trackPurchase(
+    {
+      content_ids: lines.map((line) => line.productId),
+      content_type: "product",
+      currency,
+      value,
+      num_items: unitCount(lines),
+      contents: metaContents(lines),
+    },
+    displayId
+  )
+
+  trackTikTokPurchase({
+    contents: tiktokContents(lines),
+    currency,
+    value,
+    displayId,
+    customerType,
+  })
+
+  trackOpenAiOrderCreated({
+    contents: openAiContents(lines, currency),
+    currency,
+    value,
+    displayId,
+  })
+
+  trackGAPurchase({
+    transaction_id: transactionId,
+    currency,
+    value,
+    items: gaItems(lines, currency),
+    ...(typeof tax === "number" ? { tax } : {}),
+    ...(typeof shipping === "number" ? { shipping } : {}),
+    ...(coupon ? { coupon } : {}),
+  })
+
+  trackRybbitPurchase({
+    transaction_id: transactionId,
+    item_ids: lines.map((line) => line.variantId || line.productId),
+    num_items: unitCount(lines),
+    currency,
+    value,
+  })
+
+  const sendTo = config ? googleAdsPurchaseSendTo(config) : null
+  if (sendTo) {
+    trackGoogleAdsPurchase({
+      sendTo,
+      value,
+      currency,
+      transactionId,
+      ...(customerType
+        ? { newCustomer: customerType === "new" }
+        : {}),
+    })
+  }
+}