@cartbase/storefront 0.20.0 → 0.21.0

package/src/cart-drawer/summary-breakdown.tsx

@@ -1,197 +1,197 @@
-"use client"
-
-import type { AppliedGiftCard } from "../api/carts"
-import { convertToLocale } from "../lib/money"
-import { useCartDrawer } from "./context"
-
-/**
- * CartSummaryBreakdown — full totals breakdown for the drawer (or a cart
- * page): subtotal, discount, shipping, tax, COD fee, total, applied
- * gift-card tender and the remainder. Alternative to the compact
- * `CartStickyFooter` (which deliberately shows a product-only subtotal in
- * pre-checkout context).
- *
- * Ported from `@1click/ui/src/cart-drawer/summary-breakdown.tsx` (v2.3.1)
- * and EXPANDED for Cartbase: the source rendered a client-summed product
- * subtotal only; Cartbase's decorated cart carries server-computed totals on
- * every read (`subtotal`, `discount_total`, `shipping_total`, `tax_total`,
- * `payment_method_fee_total`/`payment_method_fee_label`, `gift_cards[]`, `gift_card_total`,
- * `gift_card_remainder`, `total` — all EUR major units), so this component
- * renders EXACTLY what the server returns and computes no money. The only
- * client-side transformation is the display sign on deductions.
- *
- * Row rules (see `selectSummaryRows`):
- * - discount / tax / method-fee rows appear only when their total is > 0.
- * - the method fee renders the server's `payment_method_fee_label`
- *   (labels.paymentMethodFee fallback).
- * - shipping renders the amount once a shipping method is set (0 → FREE);
- *   before that it shows "calculated at checkout".
- * - gift-card tender renders one row per applied card (masked `last4`,
- *   negative display) plus the `gift_card_remainder` row — the amount the
- *   remainder provider actually charges. A depleted card stays listed at 0
- *   (server keeps it in `gift_cards` at amount 0).
- */
-
-/** The decorated-cart fields the breakdown consumes (structural subset). */
-export type SummaryCartTotals = {
-  subtotal: number
-  discount_total: number
-  shipping_total: number
-  tax_total: number
-  total: number
-  payment_method_fee_total?: number
-  payment_method_fee_label?: string | null
-  gift_cards?: AppliedGiftCard[]
-  gift_card_total?: number
-  gift_card_remainder?: number
-  shipping_methods?: ReadonlyArray<unknown>
-}
-
-export type SummaryRow =
-  | { kind: "subtotal"; amount: number }
-  | { kind: "discount"; amount: number }
-  | { kind: "shipping"; amount: number }
-  | { kind: "shipping_pending" }
-  | { kind: "tax"; amount: number }
-  | { kind: "payment_method_fee"; amount: number; label: string | null }
-  | { kind: "total"; amount: number }
-  | { kind: "gift_card"; last4: string; amount: number }
-  | { kind: "remainder"; amount: number }
-
-/**
- * Pure row selection over the decorated-cart totals — exported for unit
- * tests. Amounts pass through verbatim (server truth); deduction rows
- * (discount, gift cards) carry a negated amount for display only.
- */
-export function selectSummaryRows(cart: SummaryCartTotals): SummaryRow[] {
-  const rows: SummaryRow[] = []
-  rows.push({ kind: "subtotal", amount: cart.subtotal })
-
-  if ((cart.discount_total ?? 0) > 0) {
-    rows.push({ kind: "discount", amount: -cart.discount_total })
-  }
-
-  if (cart.shipping_methods && cart.shipping_methods.length > 0) {
-    rows.push({ kind: "shipping", amount: cart.shipping_total })
-  } else {
-    rows.push({ kind: "shipping_pending" })
-  }
-
-  if ((cart.tax_total ?? 0) > 0) {
-    rows.push({ kind: "tax", amount: cart.tax_total })
-  }
-
-  if ((cart.payment_method_fee_total ?? 0) > 0) {
-    rows.push({
-      kind: "payment_method_fee",
-      amount: cart.payment_method_fee_total!,
-      label: cart.payment_method_fee_label ?? null,
-    })
-  }
-
-  rows.push({ kind: "total", amount: cart.total })
-
-  if (cart.gift_cards && cart.gift_cards.length > 0) {
-    for (const card of cart.gift_cards) {
-      // `|| 0` normalizes -0 (a depleted card at amount 0) so Intl never
-      // renders a stray "-€0.00".
-      rows.push({ kind: "gift_card", last4: card.last4, amount: -card.amount || 0 })
-    }
-    rows.push({ kind: "remainder", amount: cart.gift_card_remainder ?? 0 })
-  }
-
-  return rows
-}
-
-export function CartSummaryBreakdown() {
-  const { cart, labels } = useCartDrawer()
-  if (!cart) return null
-
-  const currencyCode = cart.currency_code
-  const money = (amount: number) =>
-    convertToLocale({ amount, currency_code: currencyCode })
-  const rows = selectSummaryRows(cart)
-
-  return (
-    <div className="px-6 py-5 space-y-2">
-      {rows.map((row, i) => {
-        switch (row.kind) {
-          case "subtotal":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
-                <span>{labels.subtotal}</span>
-                <span className="tabular-nums">{money(row.amount)}</span>
-              </div>
-            )
-          case "discount":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-success">
-                <span>{labels.discount}</span>
-                <span className="tabular-nums">{money(row.amount)}</span>
-              </div>
-            )
-          case "shipping":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
-                <span>{labels.shipping}</span>
-                <span className="tabular-nums">
-                  {row.amount === 0 ? labels.free : money(row.amount)}
-                </span>
-              </div>
-            )
-          case "shipping_pending":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
-                <span>{labels.shipping}</span>
-                <span>{labels.calculatedAtCheckout}</span>
-              </div>
-            )
-          case "tax":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
-                <span>{labels.tax}</span>
-                <span className="tabular-nums">{money(row.amount)}</span>
-              </div>
-            )
-          case "payment_method_fee":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
-                <span>{row.label ?? labels.paymentMethodFee}</span>
-                <span className="tabular-nums">{money(row.amount)}</span>
-              </div>
-            )
-          case "total":
-            return (
-              <div
-                key={i}
-                className="flex justify-between items-center pt-2 mt-1 border-t border-border"
-              >
-                <span className="text-[15px] font-bold text-foreground">
-                  {labels.total}
-                </span>
-                <span className="text-[17px] font-bold text-foreground tracking-tight tabular-nums">
-                  {money(row.amount)}
-                </span>
-              </div>
-            )
-          case "gift_card":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] text-success">
-                <span>
-                  {labels.giftCard} ••{row.last4}
-                </span>
-                <span className="tabular-nums">{money(row.amount)}</span>
-              </div>
-            )
-          case "remainder":
-            return (
-              <div key={i} className="flex justify-between items-center text-[13px] font-semibold text-foreground">
-                <span>{labels.remainingToPay}</span>
-                <span className="tabular-nums">{money(row.amount)}</span>
-              </div>
-            )
-        }
-      })}
-    </div>
-  )
-}
+"use client"
+
+import type { AppliedGiftCard } from "../api/carts"
+import { convertToLocale } from "../lib/money"
+import { useCartDrawer } from "./context"
+
+/**
+ * CartSummaryBreakdown — full totals breakdown for the drawer (or a cart
+ * page): subtotal, discount, shipping, tax, COD fee, total, applied
+ * gift-card tender and the remainder. Alternative to the compact
+ * `CartStickyFooter` (which deliberately shows a product-only subtotal in
+ * pre-checkout context).
+ *
+ * Ported from `@1click/ui/src/cart-drawer/summary-breakdown.tsx` (v2.3.1)
+ * and EXPANDED for Cartbase: the source rendered a client-summed product
+ * subtotal only; Cartbase's decorated cart carries server-computed totals on
+ * every read (`subtotal`, `discount_total`, `shipping_total`, `tax_total`,
+ * `payment_method_fee_total`/`payment_method_fee_label`, `gift_cards[]`, `gift_card_total`,
+ * `gift_card_remainder`, `total` — all EUR major units), so this component
+ * renders EXACTLY what the server returns and computes no money. The only
+ * client-side transformation is the display sign on deductions.
+ *
+ * Row rules (see `selectSummaryRows`):
+ * - discount / tax / method-fee rows appear only when their total is > 0.
+ * - the method fee renders the server's `payment_method_fee_label`
+ *   (labels.paymentMethodFee fallback).
+ * - shipping renders the amount once a shipping method is set (0 → FREE);
+ *   before that it shows "calculated at checkout".
+ * - gift-card tender renders one row per applied card (masked `last4`,
+ *   negative display) plus the `gift_card_remainder` row — the amount the
+ *   remainder provider actually charges. A depleted card stays listed at 0
+ *   (server keeps it in `gift_cards` at amount 0).
+ */
+
+/** The decorated-cart fields the breakdown consumes (structural subset). */
+export type SummaryCartTotals = {
+  subtotal: number
+  discount_total: number
+  shipping_total: number
+  tax_total: number
+  total: number
+  payment_method_fee_total?: number
+  payment_method_fee_label?: string | null
+  gift_cards?: AppliedGiftCard[]
+  gift_card_total?: number
+  gift_card_remainder?: number
+  shipping_methods?: ReadonlyArray<unknown>
+}
+
+export type SummaryRow =
+  | { kind: "subtotal"; amount: number }
+  | { kind: "discount"; amount: number }
+  | { kind: "shipping"; amount: number }
+  | { kind: "shipping_pending" }
+  | { kind: "tax"; amount: number }
+  | { kind: "payment_method_fee"; amount: number; label: string | null }
+  | { kind: "total"; amount: number }
+  | { kind: "gift_card"; last4: string; amount: number }
+  | { kind: "remainder"; amount: number }
+
+/**
+ * Pure row selection over the decorated-cart totals — exported for unit
+ * tests. Amounts pass through verbatim (server truth); deduction rows
+ * (discount, gift cards) carry a negated amount for display only.
+ */
+export function selectSummaryRows(cart: SummaryCartTotals): SummaryRow[] {
+  const rows: SummaryRow[] = []
+  rows.push({ kind: "subtotal", amount: cart.subtotal })
+
+  if ((cart.discount_total ?? 0) > 0) {
+    rows.push({ kind: "discount", amount: -cart.discount_total })
+  }
+
+  if (cart.shipping_methods && cart.shipping_methods.length > 0) {
+    rows.push({ kind: "shipping", amount: cart.shipping_total })
+  } else {
+    rows.push({ kind: "shipping_pending" })
+  }
+
+  if ((cart.tax_total ?? 0) > 0) {
+    rows.push({ kind: "tax", amount: cart.tax_total })
+  }
+
+  if ((cart.payment_method_fee_total ?? 0) > 0) {
+    rows.push({
+      kind: "payment_method_fee",
+      amount: cart.payment_method_fee_total!,
+      label: cart.payment_method_fee_label ?? null,
+    })
+  }
+
+  rows.push({ kind: "total", amount: cart.total })
+
+  if (cart.gift_cards && cart.gift_cards.length > 0) {
+    for (const card of cart.gift_cards) {
+      // `|| 0` normalizes -0 (a depleted card at amount 0) so Intl never
+      // renders a stray "-€0.00".
+      rows.push({ kind: "gift_card", last4: card.last4, amount: -card.amount || 0 })
+    }
+    rows.push({ kind: "remainder", amount: cart.gift_card_remainder ?? 0 })
+  }
+
+  return rows
+}
+
+export function CartSummaryBreakdown() {
+  const { cart, labels } = useCartDrawer()
+  if (!cart) return null
+
+  const currencyCode = cart.currency_code
+  const money = (amount: number) =>
+    convertToLocale({ amount, currency_code: currencyCode })
+  const rows = selectSummaryRows(cart)
+
+  return (
+    <div className="px-6 py-5 space-y-2">
+      {rows.map((row, i) => {
+        switch (row.kind) {
+          case "subtotal":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
+                <span>{labels.subtotal}</span>
+                <span className="tabular-nums">{money(row.amount)}</span>
+              </div>
+            )
+          case "discount":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-success">
+                <span>{labels.discount}</span>
+                <span className="tabular-nums">{money(row.amount)}</span>
+              </div>
+            )
+          case "shipping":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
+                <span>{labels.shipping}</span>
+                <span className="tabular-nums">
+                  {row.amount === 0 ? labels.free : money(row.amount)}
+                </span>
+              </div>
+            )
+          case "shipping_pending":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
+                <span>{labels.shipping}</span>
+                <span>{labels.calculatedAtCheckout}</span>
+              </div>
+            )
+          case "tax":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
+                <span>{labels.tax}</span>
+                <span className="tabular-nums">{money(row.amount)}</span>
+              </div>
+            )
+          case "payment_method_fee":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-muted-foreground">
+                <span>{row.label ?? labels.paymentMethodFee}</span>
+                <span className="tabular-nums">{money(row.amount)}</span>
+              </div>
+            )
+          case "total":
+            return (
+              <div
+                key={i}
+                className="flex justify-between items-center pt-2 mt-1 border-t border-border"
+              >
+                <span className="text-[15px] font-bold text-foreground">
+                  {labels.total}
+                </span>
+                <span className="text-[17px] font-bold text-foreground tracking-tight tabular-nums">
+                  {money(row.amount)}
+                </span>
+              </div>
+            )
+          case "gift_card":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] text-success">
+                <span>
+                  {labels.giftCard} ••{row.last4}
+                </span>
+                <span className="tabular-nums">{money(row.amount)}</span>
+              </div>
+            )
+          case "remainder":
+            return (
+              <div key={i} className="flex justify-between items-center text-[13px] font-semibold text-foreground">
+                <span>{labels.remainingToPay}</span>
+                <span className="tabular-nums">{money(row.amount)}</span>
+              </div>
+            )
+        }
+      })}
+    </div>
+  )
+}

package/src/checkout/address-error-copy.ts

@@ -1,117 +1,117 @@
-import type { AddressErrorCopy } from "./labels"
-
-/**
- * Recognizes an address-save failure and picks the copy for it.
- *
- * THE COPY IS NOT HERE. Until 2026-09-13 this file held thirteen hardcoded
- * BULGARIAN sentences, so every merchant who installed the package showed
- * Bulgarian on the one screen where a shopper is about to pay, with no way
- * to override it. The copy now lives in the checkout label pack like all
- * other copy, which means it is English by default and translated by
- * whichever locale the store mounts.
- *
- * WHAT STAYS HERE IS THE RECOGNITION, and it stays on purpose: the codes
- * and the patterns match the API's own error text, which is English wire
- * format, not user-facing copy. Translating the matcher would break it.
- *
- * Ported from `@1click/ui/src/checkout/address-error-copy.ts` (v2.3.1) and
- * adapted to the Cartbase error envelope: `StoreApiError` carries a
- * structured `code` (POST /api/store/carts/:id, docs/storefront/carts.md),
- * so recognition is code-first and the substring patterns are the fallback
- * for network failures and any legacy wire.
- *
- * The mapping is deliberately narrow: only failures we recognize get their
- * own sentence, and everything else gets the generic one rather than
- * half-translated technical text.
- */
-
-/** Cartbase cart-update error codes, mapped to a copy key. Code-first. */
-export const ADDRESS_CODE_KEYS: Record<string, keyof AddressErrorCopy> = {
-  validation_failed: "validationFailed",
-  invalid_region: "invalidRegion",
-  region_required: "regionRequired",
-  cart_completed: "cartCompleted",
-  cart_not_found: "cartNotFound",
-}
-
-/**
- * Patterns matched in order, first match wins: most specific first,
- * generic last. Case-insensitive. Kept verbatim from the production port.
- */
-const PATTERNS: Array<{ match: RegExp; key: keyof AddressErrorCopy }> = [
-  // Email validation — confirmed (in @1click production) as the most common
-  // address-save failure shape.
-  {
-    match: /invalid[\s_]?(?:request:?\s*)?invalid[\s_]?email|invalid[\s_]?email/i,
-    key: "invalidEmail",
-  },
-  {
-    match:
-      /invalid[\s_]?postal|invalid[\s_]?post(?:code|al[\s_]?code)|postal[\s_]?code[\s_]?(?:is[\s_]?)?invalid/i,
-    key: "invalidPostalCode",
-  },
-  {
-    match: /invalid[\s_]?phone|phone[\s_]?(?:number[\s_]?)?(?:is[\s_]?)?invalid/i,
-    key: "invalidPhone",
-  },
-  {
-    match:
-      /invalid[\s_]?country|country[\s_]?(?:code[\s_]?)?(?:is[\s_]?)?invalid|no[\s_]?region|invalid[\s_]?region/i,
-    key: "invalidCountry",
-  },
-  // Cart already completed — race with order placement.
-  {
-    match:
-      /cart[\s_]?(?:is[\s_]?)?already[\s_]?completed|already[\s_]?an[\s_]?order|completed[\s_]?cart/i,
-    key: "cartCompleted",
-  },
-  {
-    match: /cart[\s_]?(?:not[\s_]?found|does[\s_]?not[\s_]?exist|expired)/i,
-    key: "cartNotFound",
-  },
-  {
-    match: /failed[\s_]?to[\s_]?fetch|network[\s_]?error|networkerror|econnreset|etimedout/i,
-    key: "network",
-  },
-  // The Next.js canned Server Components production message — surface a
-  // clean fallback instead of the English placeholder. (The Cartbase SDK
-  // throws from the browser, so this only fires for stores that proxy the
-  // save through a server action.)
-  {
-    match: /server[\s_]?components[\s_]?render|digest property is included/i,
-    key: "generic",
-  },
-]
-
-/** Which copy an error asks for, independent of language. */
-export function addressErrorKey(err: unknown): keyof AddressErrorCopy {
-  if (err && typeof err === "object") {
-    const code = (err as { code?: unknown }).code
-    if (typeof code === "string" && ADDRESS_CODE_KEYS[code]) return ADDRESS_CODE_KEYS[code]
-  }
-  const raw = extractMessage(err)
-  if (!raw) return "generic"
-  for (const { match, key } of PATTERNS) {
-    if (match.test(raw)) return key
-  }
-  return "generic"
-}
-
-/**
- * Turn any thrown or returned address-save error into the sentence a
- * shopper reads, in the store's own language.
- */
-export function translateAddressError(err: unknown, copy: AddressErrorCopy): string {
-  return copy[addressErrorKey(err)]
-}
-
-function extractMessage(err: unknown): string {
-  if (!err) return ""
-  if (typeof err === "string") return err
-  if (err instanceof Error) return err.message
-  if (typeof err === "object" && err !== null) {
-    const e = err as { message?: string; code?: string; type?: string }
-    return [e.message, e.code, e.type].filter(Boolean).join(" ")
-  }
-  return String(err)
-}
+import type { AddressErrorCopy } from "./labels"
+
+/**
+ * Recognizes an address-save failure and picks the copy for it.
+ *
+ * THE COPY IS NOT HERE. Until 2026-09-13 this file held thirteen hardcoded
+ * BULGARIAN sentences, so every merchant who installed the package showed
+ * Bulgarian on the one screen where a shopper is about to pay, with no way
+ * to override it. The copy now lives in the checkout label pack like all
+ * other copy, which means it is English by default and translated by
+ * whichever locale the store mounts.
+ *
+ * WHAT STAYS HERE IS THE RECOGNITION, and it stays on purpose: the codes
+ * and the patterns match the API's own error text, which is English wire
+ * format, not user-facing copy. Translating the matcher would break it.
+ *
+ * Ported from `@1click/ui/src/checkout/address-error-copy.ts` (v2.3.1) and
+ * adapted to the Cartbase error envelope: `StoreApiError` carries a
+ * structured `code` (POST /api/store/carts/:id, docs/storefront/carts.md),
+ * so recognition is code-first and the substring patterns are the fallback
+ * for network failures and any legacy wire.
+ *
+ * The mapping is deliberately narrow: only failures we recognize get their
+ * own sentence, and everything else gets the generic one rather than
+ * half-translated technical text.
+ */
+
+/** Cartbase cart-update error codes, mapped to a copy key. Code-first. */
+export const ADDRESS_CODE_KEYS: Record<string, keyof AddressErrorCopy> = {
+  validation_failed: "validationFailed",
+  invalid_region: "invalidRegion",
+  region_required: "regionRequired",
+  cart_completed: "cartCompleted",
+  cart_not_found: "cartNotFound",
+}
+
+/**
+ * Patterns matched in order, first match wins: most specific first,
+ * generic last. Case-insensitive. Kept verbatim from the production port.
+ */
+const PATTERNS: Array<{ match: RegExp; key: keyof AddressErrorCopy }> = [
+  // Email validation — confirmed (in @1click production) as the most common
+  // address-save failure shape.
+  {
+    match: /invalid[\s_]?(?:request:?\s*)?invalid[\s_]?email|invalid[\s_]?email/i,
+    key: "invalidEmail",
+  },
+  {
+    match:
+      /invalid[\s_]?postal|invalid[\s_]?post(?:code|al[\s_]?code)|postal[\s_]?code[\s_]?(?:is[\s_]?)?invalid/i,
+    key: "invalidPostalCode",
+  },
+  {
+    match: /invalid[\s_]?phone|phone[\s_]?(?:number[\s_]?)?(?:is[\s_]?)?invalid/i,
+    key: "invalidPhone",
+  },
+  {
+    match:
+      /invalid[\s_]?country|country[\s_]?(?:code[\s_]?)?(?:is[\s_]?)?invalid|no[\s_]?region|invalid[\s_]?region/i,
+    key: "invalidCountry",
+  },
+  // Cart already completed — race with order placement.
+  {
+    match:
+      /cart[\s_]?(?:is[\s_]?)?already[\s_]?completed|already[\s_]?an[\s_]?order|completed[\s_]?cart/i,
+    key: "cartCompleted",
+  },
+  {
+    match: /cart[\s_]?(?:not[\s_]?found|does[\s_]?not[\s_]?exist|expired)/i,
+    key: "cartNotFound",
+  },
+  {
+    match: /failed[\s_]?to[\s_]?fetch|network[\s_]?error|networkerror|econnreset|etimedout/i,
+    key: "network",
+  },
+  // The Next.js canned Server Components production message — surface a
+  // clean fallback instead of the English placeholder. (The Cartbase SDK
+  // throws from the browser, so this only fires for stores that proxy the
+  // save through a server action.)
+  {
+    match: /server[\s_]?components[\s_]?render|digest property is included/i,
+    key: "generic",
+  },
+]
+
+/** Which copy an error asks for, independent of language. */
+export function addressErrorKey(err: unknown): keyof AddressErrorCopy {
+  if (err && typeof err === "object") {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && ADDRESS_CODE_KEYS[code]) return ADDRESS_CODE_KEYS[code]
+  }
+  const raw = extractMessage(err)
+  if (!raw) return "generic"
+  for (const { match, key } of PATTERNS) {
+    if (match.test(raw)) return key
+  }
+  return "generic"
+}
+
+/**
+ * Turn any thrown or returned address-save error into the sentence a
+ * shopper reads, in the store's own language.
+ */
+export function translateAddressError(err: unknown, copy: AddressErrorCopy): string {
+  return copy[addressErrorKey(err)]
+}
+
+function extractMessage(err: unknown): string {
+  if (!err) return ""
+  if (typeof err === "string") return err
+  if (err instanceof Error) return err.message
+  if (typeof err === "object" && err !== null) {
+    const e = err as { message?: string; code?: string; type?: string }
+    return [e.message, e.code, e.type].filter(Boolean).join(" ")
+  }
+  return String(err)
+}