@cartbase/storefront 0.20.0 → 0.20.1

package/src/tracking/oaiq.ts

@@ -1,206 +1,206 @@
-"use client"
-
-/**
- * Typed wrappers around the global `oaiq` command queue from the OpenAI
- * measurement pixel — the ChatGPT Ads twin of ./ttq.ts and ./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.oaiq` is absent (pixel not configured,
- * server render, script blocked), so callers need no guards.
- *
- * The call signature is theirs, from
- * https://developers.openai.com/ads/measurement-pixel:
- *
- *     oaiq("measure", eventName, eventData, { event_id })
- *
- * Two things here are NOT like the other vendors, and both are silent when
- * wrong:
- *
- *   1. MONEY IS AN INTEGER IN MINOR UNITS. Meta, TikTok and GA4 all read
- *      `value: 25.99`; OpenAI reads `amount: 2599`. Passing a decimal
- *      under-reports revenue by a factor of a hundred with nothing to show
- *      for it, so every amount goes through `minorUnits` below and no
- *      caller passes `amount` itself.
- *   2. EVENT DATA CARRIES ITS OWN `type`. Each event name is bound to one
- *      of four data shapes; the five commerce events we fire all take
- *      `contents`, so the wrappers set it and callers cannot get it wrong.
- *
- * Event names are theirs and are not interchangeable with Meta's or
- * TikTok's: `contents_viewed`, `items_added`, `checkout_started`,
- * `order_created`, `page_viewed`.
- */
-
-/** One product line inside `contents`. */
-export type OpenAiContentItem = {
-  id: string
-  name?: string
-  content_type?: string
-  quantity?: number
-  /** Integer, minor units. */
-  amount?: number
-  currency?: string
-}
-
-type OpenAiEventData = {
-  type: "contents"
-  /** Integer, minor units. */
-  amount?: number
-  currency?: string
-  contents?: OpenAiContentItem[]
-}
-
-type OaiqFn = (
-  command: "init" | "measure" | "consent",
-  ...args: unknown[]
-) => void
-
-function safeOaiq(): OaiqFn | null {
-  if (typeof window === "undefined") return null
-  const oaiq = (window as unknown as { oaiq?: OaiqFn }).oaiq
-  return typeof oaiq === "function" ? oaiq : null
-}
-
-/**
- * Major units to their integer minor units: 25.99 becomes 2599.
- *
- * The twin of `openAiMinorUnits` in the platform's
- * src/lib/tracking/constants.ts. Duplicated rather than imported because
- * this package cannot reach into the platform, and rounded rather than
- * truncated because 0.1 + 0.2 is 0.30000000000000004 in binary floating
- * point and truncation would report 29 cents for 30.
- */
-export function minorUnits(amountInMajorUnits: number): number {
-  return Math.round((Number(amountInMajorUnits) || 0) * 100)
-}
-
-/**
- * THE order dedup key — must equal what the backend forwarder sends
- * (`openAiOrderEventId` in the platform's 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 and
- * `tiktokPurchaseEventId` for TikTok.
- *
- * OpenAI deduplicates on pixel id + event name + id, keeping the FIRST
- * event it receives, so the browser and the server collapse into one
- * conversion whichever arrives first.
- */
-export function openAiOrderEventId(displayId: string | number): string {
-  return `oai_order_${displayId}`
-}
-
-/** A page view. Their pixel fires nothing on its own at init. */
-export function trackOpenAiPageView(): void {
-  const oaiq = safeOaiq()
-  if (!oaiq) return
-  oaiq("measure", "page_viewed", { type: "contents" } satisfies OpenAiEventData)
-}
-
-export function trackOpenAiContentsViewed(data: {
-  contentId: string
-  contentName?: string
-  currency: string
-  /** Major units — converted here. */
-  value: number
-}): void {
-  const oaiq = safeOaiq()
-  if (!oaiq) return
-  oaiq("measure", "contents_viewed", {
-    type: "contents",
-    amount: minorUnits(data.value),
-    currency: data.currency,
-    contents: [
-      {
-        id: data.contentId,
-        name: data.contentName,
-        content_type: "product",
-        quantity: 1,
-      },
-    ],
-  } satisfies OpenAiEventData)
-}
-
-export function trackOpenAiItemsAdded(data: {
-  contentId: string
-  contentName?: string
-  quantity: number
-  /** Unit price, major units. */
-  price: number
-  currency: string
-  /** Line value, major units. */
-  value: number
-}): void {
-  const oaiq = safeOaiq()
-  if (!oaiq) return
-  oaiq("measure", "items_added", {
-    type: "contents",
-    amount: minorUnits(data.value),
-    currency: data.currency,
-    contents: [
-      {
-        id: data.contentId,
-        name: data.contentName,
-        content_type: "product",
-        quantity: data.quantity,
-        amount: minorUnits(data.price),
-        currency: data.currency,
-      },
-    ],
-  } satisfies OpenAiEventData)
-}
-
-export function trackOpenAiCheckoutStarted(data: {
-  contents: OpenAiContentItem[]
-  currency: string
-  /** Cart value, major units. */
-  value: number
-}): void {
-  const oaiq = safeOaiq()
-  if (!oaiq) return
-  oaiq("measure", "checkout_started", {
-    type: "contents",
-    amount: minorUnits(data.value),
-    currency: data.currency,
-    contents: data.contents,
-  } satisfies OpenAiEventData)
-}
-
-export function trackOpenAiOrderCreated(data: {
-  contents: OpenAiContentItem[]
-  currency: string
-  /** Order total, major units. */
-  value: number
-  /** The order's display id — the dedup key shared with the server. */
-  displayId: string | number
-}): void {
-  const oaiq = safeOaiq()
-  if (!oaiq) return
-  oaiq(
-    "measure",
-    "order_created",
-    {
-      type: "contents",
-      amount: minorUnits(data.value),
-      currency: data.currency,
-      contents: data.contents,
-    } satisfies OpenAiEventData,
-    { event_id: openAiOrderEventId(data.displayId) }
-  )
-}
-
-/**
- * Push a live consent decision to the pixel.
- *
- * Normally you do NOT call this: `applyConsent()` in ./consent.ts relays
- * every decision to gtag, fbq, ttq and oaiq together. Exported for a host
- * app driving the pixel from a consent layer of its own.
- *
- * Their own gate, from the measurement-pixel docs: with consent false the
- * pixel sends no measurement pings, and the default is TRUE, which is why
- * the loader closes it explicitly before init rather than trusting it.
- */
-export function applyOpenAiConsent(adsGranted: boolean): void {
-  const oaiq = safeOaiq()
-  if (!oaiq) return
-  oaiq("consent", adsGranted)
-}
+"use client"
+
+/**
+ * Typed wrappers around the global `oaiq` command queue from the OpenAI
+ * measurement pixel — the ChatGPT Ads twin of ./ttq.ts and ./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.oaiq` is absent (pixel not configured,
+ * server render, script blocked), so callers need no guards.
+ *
+ * The call signature is theirs, from
+ * https://developers.openai.com/ads/measurement-pixel:
+ *
+ *     oaiq("measure", eventName, eventData, { event_id })
+ *
+ * Two things here are NOT like the other vendors, and both are silent when
+ * wrong:
+ *
+ *   1. MONEY IS AN INTEGER IN MINOR UNITS. Meta, TikTok and GA4 all read
+ *      `value: 25.99`; OpenAI reads `amount: 2599`. Passing a decimal
+ *      under-reports revenue by a factor of a hundred with nothing to show
+ *      for it, so every amount goes through `minorUnits` below and no
+ *      caller passes `amount` itself.
+ *   2. EVENT DATA CARRIES ITS OWN `type`. Each event name is bound to one
+ *      of four data shapes; the five commerce events we fire all take
+ *      `contents`, so the wrappers set it and callers cannot get it wrong.
+ *
+ * Event names are theirs and are not interchangeable with Meta's or
+ * TikTok's: `contents_viewed`, `items_added`, `checkout_started`,
+ * `order_created`, `page_viewed`.
+ */
+
+/** One product line inside `contents`. */
+export type OpenAiContentItem = {
+  id: string
+  name?: string
+  content_type?: string
+  quantity?: number
+  /** Integer, minor units. */
+  amount?: number
+  currency?: string
+}
+
+type OpenAiEventData = {
+  type: "contents"
+  /** Integer, minor units. */
+  amount?: number
+  currency?: string
+  contents?: OpenAiContentItem[]
+}
+
+type OaiqFn = (
+  command: "init" | "measure" | "consent",
+  ...args: unknown[]
+) => void
+
+function safeOaiq(): OaiqFn | null {
+  if (typeof window === "undefined") return null
+  const oaiq = (window as unknown as { oaiq?: OaiqFn }).oaiq
+  return typeof oaiq === "function" ? oaiq : null
+}
+
+/**
+ * Major units to their integer minor units: 25.99 becomes 2599.
+ *
+ * The twin of `openAiMinorUnits` in the platform's
+ * src/lib/tracking/constants.ts. Duplicated rather than imported because
+ * this package cannot reach into the platform, and rounded rather than
+ * truncated because 0.1 + 0.2 is 0.30000000000000004 in binary floating
+ * point and truncation would report 29 cents for 30.
+ */
+export function minorUnits(amountInMajorUnits: number): number {
+  return Math.round((Number(amountInMajorUnits) || 0) * 100)
+}
+
+/**
+ * THE order dedup key — must equal what the backend forwarder sends
+ * (`openAiOrderEventId` in the platform's 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 and
+ * `tiktokPurchaseEventId` for TikTok.
+ *
+ * OpenAI deduplicates on pixel id + event name + id, keeping the FIRST
+ * event it receives, so the browser and the server collapse into one
+ * conversion whichever arrives first.
+ */
+export function openAiOrderEventId(displayId: string | number): string {
+  return `oai_order_${displayId}`
+}
+
+/** A page view. Their pixel fires nothing on its own at init. */
+export function trackOpenAiPageView(): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "page_viewed", { type: "contents" } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiContentsViewed(data: {
+  contentId: string
+  contentName?: string
+  currency: string
+  /** Major units — converted here. */
+  value: number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "contents_viewed", {
+    type: "contents",
+    amount: minorUnits(data.value),
+    currency: data.currency,
+    contents: [
+      {
+        id: data.contentId,
+        name: data.contentName,
+        content_type: "product",
+        quantity: 1,
+      },
+    ],
+  } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiItemsAdded(data: {
+  contentId: string
+  contentName?: string
+  quantity: number
+  /** Unit price, major units. */
+  price: number
+  currency: string
+  /** Line value, major units. */
+  value: number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "items_added", {
+    type: "contents",
+    amount: minorUnits(data.value),
+    currency: data.currency,
+    contents: [
+      {
+        id: data.contentId,
+        name: data.contentName,
+        content_type: "product",
+        quantity: data.quantity,
+        amount: minorUnits(data.price),
+        currency: data.currency,
+      },
+    ],
+  } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiCheckoutStarted(data: {
+  contents: OpenAiContentItem[]
+  currency: string
+  /** Cart value, major units. */
+  value: number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "checkout_started", {
+    type: "contents",
+    amount: minorUnits(data.value),
+    currency: data.currency,
+    contents: data.contents,
+  } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiOrderCreated(data: {
+  contents: OpenAiContentItem[]
+  currency: string
+  /** Order total, major units. */
+  value: number
+  /** The order's display id — the dedup key shared with the server. */
+  displayId: string | number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq(
+    "measure",
+    "order_created",
+    {
+      type: "contents",
+      amount: minorUnits(data.value),
+      currency: data.currency,
+      contents: data.contents,
+    } satisfies OpenAiEventData,
+    { event_id: openAiOrderEventId(data.displayId) }
+  )
+}
+
+/**
+ * Push a live consent decision to the pixel.
+ *
+ * Normally you do NOT call this: `applyConsent()` in ./consent.ts relays
+ * every decision to gtag, fbq, ttq and oaiq together. Exported for a host
+ * app driving the pixel from a consent layer of its own.
+ *
+ * Their own gate, from the measurement-pixel docs: with consent false the
+ * pixel sends no measurement pings, and the default is TRUE, which is why
+ * the loader closes it explicitly before init rather than trusting it.
+ */
+export function applyOpenAiConsent(adsGranted: boolean): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("consent", adsGranted)
+}

package/src/tracking/tiktok-pixel.tsx

@@ -1,91 +1,91 @@
-"use client"
-
-import Script from "next/script"
-
-import { adsConsentSnippet } from "./consent"
-import { jsStringLiteral } from "./inline-script"
-
-/**
- * TikTokPixel — client-side base pixel injector, the TikTok twin of
- * <MetaPixel>.
- *
- * Injects TikTok's own base snippet with `<Script
- * strategy="afterInteractive">`, resolves consent from the `_1c_consent`
- * cookie BEFORE the pixel is allowed to write cookies, then loads and
- * fires the initial page view.
- *
- * Consent model. TikTok's base code registers `holdConsent`,
- * `grantConsent` and `revokeConsent` on `ttq` alongside `page` and
- * `track`, and `setAndDefer` queues every call onto the `ttq` array
- * before the SDK is fetched. So the Meta pattern transfers exactly:
- *
- *     ttq.holdConsent()   // queued before load — cookies withheld
- *     ttq.load(pixelId)
- *     ttq.page()
- *     ttq.grantConsent()  // visitor accepted marketing
- *     ttq.revokeConsent() // visitor declined, or withdrew later
- *
- * HOLDING rather than withholding the script is the point, and it is the
- * same reasoning as the Meta gate above it: under load-on-consent, a
- * visitor who browses three products and only then accepts gives TikTok
- * nothing for those three pages. Holding queues them and the grant
- * releases them.
- *
- * Live decisions arrive through `applyConsent()` in ./consent.ts, which
- * relays to gtag, fbq and ttq together — there is no cookie watcher.
- * The first decision is the store's default overridden by the visitor's
- * stored choice (`adsConsentSnippet`): revoked on a store that collects
- * consent, granted on a store with no consent gate, the cookie winning
- * either way. `consentRequired` is `tracking.consent_required`, passed by
- * <StorefrontTags>, and required for the reason <ConsentInit> gives.
- *
- * One dependency outside the code: Cookie Consent Mode must be switched
- * on for this pixel in TikTok Events Manager. With it off, `holdConsent`
- * is an inert queued call and the pixel behaves like any unconsented
- * pixel — no error, no crash, and no gate. That switch belongs to whoever
- * owns the ad account.
- *
- * Renders nothing when `pixelId` is falsy, so a layout can mount it
- * unconditionally.
- */
-export function TikTokPixel({
-  pixelId,
-  consentRequired,
-}: {
-  pixelId?: string
-  /** `tracking.consent_required`: does this store collect consent before it tracks? */
-  consentRequired: boolean
-}) {
-  if (!pixelId) return null
-
-  const id = jsStringLiteral(pixelId)
-
-  const initSnippet = `
-!function (w, d, t) {
-  w.TiktokAnalyticsObject=t;
-  var ttq=w[t]=w[t]||[];
-  ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"];
-  ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
-  for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
-  ttq.instance=function(t){var e=ttq._i[t]||[];for(var n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
-  ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=d.createElement("script");o.type="text/javascript",o.async=!0,o.src=r+"?sdkid="+e+"&lib="+t;var a=d.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
-
-  ttq.holdConsent();
-  ttq.load(${id});
-  ttq.page();
-
-  (function(){
-    ${adsConsentSnippet(consentRequired, "d")}
-    if(ads){ttq.grantConsent();}else{ttq.revokeConsent();}
-  })();
-}(window, document, 'ttq');
-`.trim()
-
-  return (
-    <Script
-      id="tiktok-pixel-init"
-      strategy="afterInteractive"
-      dangerouslySetInnerHTML={{ __html: initSnippet }}
-    />
-  )
-}
+"use client"
+
+import Script from "next/script"
+
+import { adsConsentSnippet } from "./consent"
+import { jsStringLiteral } from "./inline-script"
+
+/**
+ * TikTokPixel — client-side base pixel injector, the TikTok twin of
+ * <MetaPixel>.
+ *
+ * Injects TikTok's own base snippet with `<Script
+ * strategy="afterInteractive">`, resolves consent from the `_1c_consent`
+ * cookie BEFORE the pixel is allowed to write cookies, then loads and
+ * fires the initial page view.
+ *
+ * Consent model. TikTok's base code registers `holdConsent`,
+ * `grantConsent` and `revokeConsent` on `ttq` alongside `page` and
+ * `track`, and `setAndDefer` queues every call onto the `ttq` array
+ * before the SDK is fetched. So the Meta pattern transfers exactly:
+ *
+ *     ttq.holdConsent()   // queued before load — cookies withheld
+ *     ttq.load(pixelId)
+ *     ttq.page()
+ *     ttq.grantConsent()  // visitor accepted marketing
+ *     ttq.revokeConsent() // visitor declined, or withdrew later
+ *
+ * HOLDING rather than withholding the script is the point, and it is the
+ * same reasoning as the Meta gate above it: under load-on-consent, a
+ * visitor who browses three products and only then accepts gives TikTok
+ * nothing for those three pages. Holding queues them and the grant
+ * releases them.
+ *
+ * Live decisions arrive through `applyConsent()` in ./consent.ts, which
+ * relays to gtag, fbq and ttq together — there is no cookie watcher.
+ * The first decision is the store's default overridden by the visitor's
+ * stored choice (`adsConsentSnippet`): revoked on a store that collects
+ * consent, granted on a store with no consent gate, the cookie winning
+ * either way. `consentRequired` is `tracking.consent_required`, passed by
+ * <StorefrontTags>, and required for the reason <ConsentInit> gives.
+ *
+ * One dependency outside the code: Cookie Consent Mode must be switched
+ * on for this pixel in TikTok Events Manager. With it off, `holdConsent`
+ * is an inert queued call and the pixel behaves like any unconsented
+ * pixel — no error, no crash, and no gate. That switch belongs to whoever
+ * owns the ad account.
+ *
+ * Renders nothing when `pixelId` is falsy, so a layout can mount it
+ * unconditionally.
+ */
+export function TikTokPixel({
+  pixelId,
+  consentRequired,
+}: {
+  pixelId?: string
+  /** `tracking.consent_required`: does this store collect consent before it tracks? */
+  consentRequired: boolean
+}) {
+  if (!pixelId) return null
+
+  const id = jsStringLiteral(pixelId)
+
+  const initSnippet = `
+!function (w, d, t) {
+  w.TiktokAnalyticsObject=t;
+  var ttq=w[t]=w[t]||[];
+  ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"];
+  ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
+  for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
+  ttq.instance=function(t){var e=ttq._i[t]||[];for(var n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
+  ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=d.createElement("script");o.type="text/javascript",o.async=!0,o.src=r+"?sdkid="+e+"&lib="+t;var a=d.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
+
+  ttq.holdConsent();
+  ttq.load(${id});
+  ttq.page();
+
+  (function(){
+    ${adsConsentSnippet(consentRequired, "d")}
+    if(ads){ttq.grantConsent();}else{ttq.revokeConsent();}
+  })();
+}(window, document, 'ttq');
+`.trim()
+
+  return (
+    <Script
+      id="tiktok-pixel-init"
+      strategy="afterInteractive"
+      dangerouslySetInnerHTML={{ __html: initSnippet }}
+    />
+  )
+}