@cartbase/storefront 0.21.0 → 0.22.1

package/src/checkout/summary-math.ts

@@ -0,0 +1,152 @@
+import type { Cart, CartLineItem } from "../api/carts"
+import { isProductLine } from "../lib/cart-helpers"
+
+/**
+ * checkoutTotals — the ONE place the checkout's displayed numbers are
+ * computed. The desktop summary and both mobile bars read it, so the total
+ * a shopper sees at the top of a phone, above the Buy button and in the
+ * right column is the same number by construction, not by three copies of
+ * the same formula kept in step by hand.
+ *
+ * Cartbase's payment-method fee is CART-LEVEL decoration
+ * (`payment_method_fee_total` / `payment_method_fee_label`, already folded
+ * into `cart.total` while a live method session exists,
+ * docs/storefront/checkout.md). It is never a line item, so there is no fee
+ * row to subtract out of the item list or the subtotal. `isProductLine`
+ * stays as a defensive filter for a cart ported from a platform that did
+ * carry one.
+ *
+ * Optimistic values: the deferred-checkout architecture keeps the shipping
+ * method and the method session off the cart until the Buy click, so a
+ * shopper who picks a courier or cash on delivery would otherwise watch an
+ * unchanged total. Each override has three states: null means no
+ * prediction, 0 means predict none, positive means predict that amount.
+ * Pure function, no React: it is unit-tested on its own.
+ */
+
+export type CheckoutTotalsInput = {
+  cart: Cart
+  /** Optimistic shipping total during method selection, or null. */
+  optimisticShippingCost: number | null
+  /** Optimistic payment-method fee during tender selection, or null. */
+  optimisticMethodFee?: number | null
+}
+
+export type CheckoutTotals = {
+  /** Product rows only, newest first, as every summary lists them. */
+  productItems: CartLineItem[]
+  /** Units, not rows: two of one product count as two. */
+  itemCount: number
+  /** Products before shipping, fee and tax. */
+  productSubtotal: number
+  /** The shipping figure to print, or null when it cannot be known yet. */
+  shippingCost: number | null
+  /** True when a figure is known; false prints "calculated at checkout". */
+  shippingKnown: boolean
+  /** The method fee to print; 0 hides the row. */
+  methodFeeAmount: number
+  /** The grand total to print, optimistic values applied. */
+  displayTotal: number
+  /** Gift-card tender covering part of the total (never moves the total). */
+  giftCardTotal: number
+  /** What is left to pay after the tender. */
+  giftCardRemainder: number
+}
+
+/**
+ * What the shopper still owes after any gift-card tender, which is the
+ * number the payment section answers to and NOT the total: a gift card is
+ * a tender, so it never moves the total, it covers part of it.
+ *
+ * The same arithmetic the platform does at prepare-checkout, where the
+ * charge is the collection's amount minus the tender, floored at zero.
+ * Keeping it here as one line means the screen and the server cannot
+ * disagree about whether an order asks for money.
+ */
+export function amountDueAfterTender(
+  displayTotal: number,
+  giftCardTotal?: number | null
+): number {
+  return Math.max((displayTotal ?? 0) - (giftCardTotal ?? 0), 0)
+}
+
+/**
+ * True when the order asks the shopper for nothing.
+ *
+ * Half a cent, not an exact zero: these are major units carrying
+ * optimistic deltas, so a fully covered total can land on 0.000000001 and
+ * an `=== 0` would put a card form in front of a shopper who owes nothing.
+ */
+export function isNothingToPay(amountDue: number): boolean {
+  return amountDue < 0.005
+}
+
+/**
+ * Is this order being invoiced to a COMPANY?
+ *
+ * It decides whether the summary prints a VAT row at all. A consumer is
+ * shown the price they pay and nothing else: the VAT is inside that price,
+ * it is not a charge they can do anything about, and a row for it is noise
+ * on the screen where they are deciding to buy (Alexander, 2026-09-18). A
+ * company is the opposite case, because the buyer reclaims the VAT and has
+ * to see it.
+ *
+ * The signals are the platform's own, in the platform's own precedence
+ * (`src/lib/documents/compose.ts`, the buyer block): what the shopper typed
+ * at purchase, then the company they belong to. `metadata.company_name` is
+ * read too, because the kit's Company invoice fields land in the cart's
+ * metadata until they are moved onto the cart's own `invoice_to`.
+ */
+export function isCompanyOrder(cart: Cart): boolean {
+  const row = cart as unknown as {
+    invoice_to?: unknown
+    company_id?: string | null
+  }
+  if (row.invoice_to && typeof row.invoice_to === "object") return true
+  if (typeof row.company_id === "string" && row.company_id) return true
+  const typed = (cart.metadata as Record<string, unknown> | null)?.company_name
+  return typeof typed === "string" && typed.trim().length > 0
+}
+
+export function checkoutTotals({
+  cart,
+  optimisticShippingCost,
+  optimisticMethodFee,
+}: CheckoutTotalsInput): CheckoutTotals {
+  const productItems = (cart.items ?? [])
+    .filter(isProductLine)
+    .slice()
+    .sort((a, b) => ((a.created_at ?? "") > (b.created_at ?? "") ? -1 : 1))
+
+  const itemCount = productItems.reduce((sum, item) => sum + item.quantity, 0)
+
+  const shippingCost =
+    optimisticShippingCost !== null ? optimisticShippingCost : cart.shipping_total ?? null
+  const shippingKnown = shippingCost !== null && shippingCost !== undefined
+
+  const realMethodFeeAmount = cart.payment_method_fee_total ?? 0
+  const methodFeeAmount =
+    optimisticMethodFee !== null && optimisticMethodFee !== undefined
+      ? optimisticMethodFee
+      : realMethodFeeAmount
+
+  let displayTotal = cart.total ?? 0
+  if (optimisticShippingCost !== null) {
+    displayTotal = displayTotal - (cart.shipping_total ?? 0) + optimisticShippingCost
+  }
+  if (optimisticMethodFee !== null && optimisticMethodFee !== undefined) {
+    displayTotal = displayTotal - realMethodFeeAmount + methodFeeAmount
+  }
+
+  return {
+    productItems,
+    itemCount,
+    productSubtotal: cart.item_total ?? 0,
+    shippingCost: shippingKnown ? shippingCost : null,
+    shippingKnown,
+    methodFeeAmount,
+    displayTotal,
+    giftCardTotal: cart.gift_card_total ?? 0,
+    giftCardRemainder: cart.gift_card_remainder ?? 0,
+  }
+}

package/src/checkout/use-checkout-funnel.ts

@@ -0,0 +1,303 @@
+"use client"
+
+import { useEffect, useMemo, useRef } from "react"
+
+import { updateCart, type Cart } from "../api/carts"
+import type { StorefrontClient } from "../api/http"
+import { isProductLine } from "../lib/cart-helpers"
+import { readBrowserAttribution } from "../tracking/attribution"
+import { CONSENT_CHANGED_EVENT, consentDecision } from "../tracking/consent"
+import {
+  trackCheckoutPaymentInfo,
+  trackCheckoutShippingInfo,
+  trackCheckoutStart,
+  type TrackedLine,
+} from "../tracking/events"
+import { setEnhancedConversions } from "../tracking/gtag"
+import { updatePixelAdvancedMatching } from "../tracking/meta-pixel"
+import { markFiredOnce } from "../tracking/once"
+
+/**
+ * useCheckoutFunnel — the three checkout-step events, the ad platforms'
+ * identity signals, and where the order came from. Mounted by
+ * `useCheckoutOrchestration`, so a store gets the whole funnel by using
+ * the kit's checkout and a store with its own layout gets it by using the
+ * hook. Nobody wires an event by hand, and nobody can forget one.
+ *
+ * This is a platform guarantee rather than a merchant chore, the same
+ * ruling as the checkout error log: every vendor helper already existed in
+ * this package, and every checkout built on it fired NONE of them, because
+ * calling them was left to the store. Our own reference storefront and
+ * evoo both shipped a checkout that told Meta, GA4, TikTok and Rybbit
+ * nothing between the cart and the order.
+ *
+ * What fires, each at most once per cart:
+ *
+ *   begin_checkout / InitiateCheckout — on arrival
+ *   add_shipping_info / AddShippingInfo — contact and address complete
+ *   add_payment_info / AddPaymentInfo — delivery and payment both chosen
+ *
+ * Deduplication is layered on purpose, because these are driven by FORM
+ * STATE and not by one-shot clicks. A shopper who switches courier,
+ * toggles card and cash, fixes a typo or refreshes would otherwise emit
+ * the same event over and over, which wrecks the funnel ratios and teaches
+ * Meta's optimizer that the event is worthless. The two layers are
+ * `markFiredOnce` (sessionStorage, so it survives a refresh) and a
+ * deterministic event id per cart (so Meta collapses anything that defeats
+ * the guard).
+ *
+ * Every helper underneath no-ops when its tag is absent, so a store with
+ * one pixel configured fires exactly that one.
+ */
+
+export type UseCheckoutFunnelOptions = {
+  client: StorefrontClient
+  cart: Cart
+  /** OFF switches the whole funnel, for a store that fires its own. */
+  enabled?: boolean
+  /**
+   * The total the shopper is looking at (the hook's `optimisticTotal`),
+   * which is what the Purchase event will report once shipping and any
+   * method fee are on the cart. Reporting the raw cart total instead would
+   * understate every step by the delivery price.
+   */
+  value: number
+  /** Every required contact and address field is filled. */
+  allRequiredFilled: boolean
+  /** The address is good enough to pay against. */
+  addressReady: boolean
+  /** A delivery method, and any office or locker it needs, are chosen. */
+  deliveryReady: boolean
+  /** The chosen courier's name, for `shipping_tier`. */
+  shippingTier?: string
+  /** Which tender the shopper settled on. */
+  paymentTab: "card" | "cod"
+  /** The live address form, for the identity signals. */
+  formData: Record<string, string>
+}
+
+export function useCheckoutFunnel({
+  client,
+  cart,
+  enabled = true,
+  value,
+  allRequiredFilled,
+  addressReady,
+  deliveryReady,
+  shippingTier,
+  paymentTab,
+  formData,
+}: UseCheckoutFunnelOptions): void {
+  const cartId = cart?.id
+  const currency = (cart?.currency_code || "EUR").toUpperCase()
+
+  /**
+   * The cart as the ad platforms want it. Product rows only: a payment
+   * surcharge is not something the shopper chose to buy, and sending it as
+   * purchase intent pollutes catalogue mapping on both Meta and TikTok.
+   *
+   * `productId` is the catalogue key on purpose. Meta's content_ids,
+   * TikTok's content_id and the feed's <g:id> have to be the SAME value or
+   * the event matches no catalogue entry, which costs dynamic ads and
+   * product-level reporting. GA4 keeps variant granularity, which
+   * `trackedLines` carries alongside.
+   */
+  const lines = useMemo<TrackedLine[] | null>(() => {
+    const items = (cart?.items ?? []).filter(isProductLine)
+    if (items.length === 0) return null
+    return items.map((item) => ({
+      productId: item.product_id || item.variant_id || item.id,
+      variantId: item.variant_id || item.id,
+      title: item.product_title || item.title || "",
+      quantity: Number(item.quantity) || 1,
+      price: Number(item.unit_price) || 0,
+    }))
+  }, [cart?.items])
+
+  // The value at the moment each step fires. Held in a ref so a total that
+  // moves (a promo code, a courier) cannot re-run the effects: the guard
+  // would swallow the second fire anyway, and the dependency churn only
+  // makes the effects look like they might fire again.
+  const valueRef = useRef(value)
+  valueRef.current = value
+  const linesRef = useRef(lines)
+  linesRef.current = lines
+  const tierRef = useRef(shippingTier)
+  tierRef.current = shippingTier
+
+  // ── Step 1: arrival ────────────────────────────────────────────────
+  useEffect(() => {
+    if (!enabled || !cartId || !linesRef.current) return
+    if (!markFiredOnce("begin_checkout", cartId)) return
+
+    trackCheckoutStart({
+      lines: linesRef.current,
+      currency,
+      value: valueRef.current,
+    })
+    // Arrival fires once per cart; the refs carry the rest.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, cartId, currency])
+
+  // ── Where the order came from, onto the cart ───────────────────────
+  //
+  // The checkout is the one moment in the funnel where a cart certainly
+  // exists and the order has not been placed yet, and cart completion
+  // copies `cart.metadata` onto `order.metadata`, which the platform's
+  // `order.placed` forwarder reads to build the CAPI and Events API
+  // payloads. Before this the ad-click ids captured on the landing page
+  // reached the browser's cookie jar and stopped there: a checkout is a
+  // client component, and the reader that gathers them
+  // (`getTrackingAttribution`) runs only on a server.
+  //
+  // Consent governs the write, by the store's own rule: a banner means
+  // nothing is written until the shopper agrees, no banner means the store
+  // collects no consent and there is nothing to wait for. A shopper who
+  // accepts while standing here is heard, which is why this listens rather
+  // than reading once on arrival.
+  const cartMetadataRef = useRef(cart?.metadata)
+  cartMetadataRef.current = cart?.metadata
+
+  useEffect(() => {
+    if (!enabled || !cartId) return
+    let cancelled = false
+
+    const attempt = () => {
+      if (cancelled) return
+      const consent = consentDecision()
+      if (!consent.ads && !consent.analytics) return
+      // Once per cart, whether it lands on arrival or on a later Accept.
+      if (!markFiredOnce("attribution", cartId)) return
+
+      const attribution = readBrowserAttribution()
+      if (Object.keys(attribution).length === 0) return
+
+      const existing = (cartMetadataRef.current ?? {}) as Record<string, unknown>
+      // Skip a write that would change nothing: a cart update is a round
+      // trip and a re-render for the host.
+      const changed = Object.entries(attribution).some(
+        ([key, v]) => existing[key] !== v
+      )
+      if (!changed) return
+
+      // Best effort, always: attribution must never be able to block a
+      // checkout. Metadata is replaced wholesale by the store API, so the
+      // cart's own keys (the carrier's office, the company's invoice
+      // fields) are spread back first.
+      void updateCart(client, cartId, {
+        metadata: { ...existing, ...attribution },
+      }).catch(() => {})
+    }
+
+    attempt()
+    window.addEventListener(CONSENT_CHANGED_EVENT, attempt)
+    return () => {
+      cancelled = true
+      window.removeEventListener(CONSENT_CHANGED_EVENT, attempt)
+    }
+  }, [enabled, cartId, client])
+
+  // ── Step 2: contact and address complete ───────────────────────────
+  // `allRequiredFilled` covers email, both names, the address line, city,
+  // postcode and phone, so this fires on a genuinely complete form and
+  // never on partial typing. It is the highest match-quality event in the
+  // funnel: every identity field is known at this exact moment.
+  useEffect(() => {
+    if (!enabled || !cartId || !linesRef.current) return
+    if (!allRequiredFilled) return
+    if (!markFiredOnce("add_shipping_info", cartId)) return
+
+    trackCheckoutShippingInfo({
+      lines: linesRef.current,
+      currency,
+      value: valueRef.current,
+      cartId,
+      // Omitted when the shopper completed the address before choosing a
+      // courier, which is the usual order.
+      ...(tierRef.current ? { shippingTier: tierRef.current } : {}),
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, cartId, currency, allRequiredFilled])
+
+  // ── Step 3: everything needed to pay ───────────────────────────────
+  // The trigger is address and delivery ready, which is the moment the Buy
+  // button becomes usable, carrying the tender they settled on.
+  useEffect(() => {
+    if (!enabled || !cartId || !linesRef.current) return
+    if (!addressReady || !deliveryReady) return
+    if (!markFiredOnce("add_payment_info", cartId)) return
+
+    trackCheckoutPaymentInfo({
+      lines: linesRef.current,
+      currency,
+      value: valueRef.current,
+      cartId,
+      paymentType: paymentTab === "cod" ? "cod" : "card",
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, cartId, currency, addressReady, deliveryReady, paymentTab])
+
+  // ── Identity, as it is typed ───────────────────────────────────────
+  // Re-init Meta's Pixel with the hashed email, phone, name, city and
+  // postcode the moment they land in the form, and hand Google the same
+  // signals for Enhanced Conversions. From here on EVERY browser-side
+  // event carries advanced matching, the Purchase on the confirmation page
+  // included, and the raw values are remembered so the platform's
+  // server-side sending inherits them.
+  //
+  // Re-firing on every change is deliberate and safe: Meta's spec says a
+  // re-init MERGES advanced-matching parameters, and Google's `set`
+  // merges user_data. Waiting for blur would leave a fast typist's
+  // identity stale for the rest of the session.
+  const email = formData.email ?? cart?.email ?? ""
+  const phone = formData["shipping_address.phone"] ?? ""
+  const firstName = formData["shipping_address.first_name"] ?? ""
+  const lastName = formData["shipping_address.last_name"] ?? ""
+  const city = formData["shipping_address.city"] ?? ""
+  const postalCode = formData["shipping_address.postal_code"] ?? ""
+  const province = formData["shipping_address.province"] ?? ""
+  // The shopper's own country, never a constant: a kit that hardcoded one
+  // would mismatch every store outside it, and a wrong country is worse
+  // than none because it occupies the field the platform would otherwise
+  // fall back from.
+  const country = formData["shipping_address.country_code"] ?? ""
+
+  useEffect(() => {
+    if (!enabled) return
+    if (!email && !phone && !firstName && !lastName && !city && !postalCode) {
+      return
+    }
+    const visitor = {
+      ...(email ? { email } : {}),
+      ...(phone ? { phone } : {}),
+      ...(firstName ? { firstName } : {}),
+      ...(lastName ? { lastName } : {}),
+      ...(city ? { city } : {}),
+      ...(postalCode ? { postalCode } : {}),
+      ...(country ? { country } : {}),
+    }
+    // Meta calls the province `state`, Google calls it `region`, and each
+    // vendor is given its own name for it.
+    void updatePixelAdvancedMatching({
+      ...visitor,
+      ...(province ? { state: province } : {}),
+    })
+    // The same person, the other vendor. The phone is normalised to E.164
+    // for Google inside the helper, which is a different string from the
+    // digits-only one Meta wants; the two hashes are not interchangeable.
+    void setEnhancedConversions({
+      ...visitor,
+      ...(province ? { region: province } : {}),
+    })
+  }, [
+    enabled,
+    email,
+    phone,
+    firstName,
+    lastName,
+    city,
+    postalCode,
+    province,
+    country,
+  ])
+}