@cartbase/storefront 0.2.0 → 0.4.0

package/src/order/order-totals.tsx

@@ -1,245 +1,250 @@
-import { DualPrice } from "../lib/dual-price"
-import { findFeeLine, type LineLike } from "../lib/cart-helpers"
-import { defaultOrderLabels, type OrderLabels } from "./labels"
-
-/**
- * Order totals breakdown. Ported from `@1click/ui/src/order/order-totals.tsx`
- * (v2.3.1) with the Cartbase money seam:
- *
- * Totals are SERVER truth and the Cartbase store order read
- * (`StoreOrderDetail`) carries NONE of them — they live where the server
- * computed them: the decorated cart the app holds on the confirmation page
- * (`api/carts` `Cart`: `item_subtotal`, `shipping_subtotal`,
- * `discount_total`, `tax_total`, `total`, `cod_fee_total`, `cod_fee_label`)
- * or the order's summary snapshot (`order_summaries.totals` — reachable via
- * `completeCart().order.summary`). The component takes a structural
- * `OrderTotalsSource` both of those satisfy (`orderTotalsFromSummary()`
- * adapts the summary shape) and only SELECTS + FORMATS rows — it never
- * computes money beyond the two production subtractions documented below.
- *
- * COD fee display, in preference order (production fix preserved):
- *  1. Cartbase-native fee: `cod_fee_total` > 0 (never a line item;
- *     already folded into `total` server-side), labeled by the
- *     admin-editable `cod_fee_label`.
- *  2. legacy Medusa-era fee LINE ITEM (`metadata.is_cod_fee`) found in
- *     `items` — its net is subtracted from the visible subtotal so the
- *     Subtotal row stays product-only while Tax keeps the fee's tax
- *     portion (v2.3.1 fix).
- *  3. label fallbacks: `codFeeLabel` prop → source `cod_fee_label` →
- *     fee line's own title → translated `labels.codFee`.
- */
-
-/** Structural totals source — `api/carts` `Cart` satisfies it directly. */
-export interface OrderTotalsSource {
-  /** Product-only net subtotal (cart path). Preferred. */
-  item_subtotal?: number | null
-  /** Combined items+shipping net (summary path fallback). */
-  subtotal?: number | null
-  /** Shipping net (cart path). Preferred for the Shipping row. */
-  shipping_subtotal?: number | null
-  /** Shipping gross (summary path fallback). */
-  shipping_total?: number | null
-  discount_total?: number | null
-  tax_total?: number | null
-  total?: number | null
-  /** Cartbase-native COD fee (already folded into `total`). */
-  cod_fee_total?: number | null
-  /** Admin-editable COD fee label from the server. */
-  cod_fee_label?: string | null
-  [key: string]: unknown
-}
-
-/**
- * Adapt `order_summaries.totals` (shape:
- * `{subtotal, total, tax_total, discount_total, shipping_total,
- * cod_fee_total}` — src/app/api/store/carts/[id]/complete/_copy.ts) to an
- * `OrderTotalsSource`. Accepts the raw `CompletedOrder["summary"]` value
- * (embed row, array of rows, or the totals object itself); null when no
- * totals can be found.
- */
-export function orderTotalsFromSummary(
-  summary: unknown
-): OrderTotalsSource | null {
-  if (!summary || typeof summary !== "object") return null
-  const first = Array.isArray(summary) ? summary[0] : summary
-  if (!first || typeof first !== "object") return null
-  const rec = first as Record<string, unknown>
-  const totals =
-    rec.totals && typeof rec.totals === "object"
-      ? (rec.totals as Record<string, unknown>)
-      : rec
-  if (typeof totals.total !== "number") return null
-  return totals as OrderTotalsSource
-}
-
-export type OrderTotalsRow = {
-  key: "subtotal" | "shipping" | "codFee" | "discount" | "tax"
-  /** Resolved display label (codFee row only — others use the label pack). */
-  label?: string
-  amount: number
-  /** Shipping row at 0 renders the FREE badge instead of a price. */
-  free?: boolean
-  /** Discount row renders negated. */
-  negative?: boolean
-}
-
-/**
- * Pure row selection — the entire display policy of the breakdown, kept
- * out of JSX so it is unit-testable (tests/unit/storefront-order-reviews).
- */
-export function selectOrderTotalsRows(
-  source: OrderTotalsSource,
-  opts: {
-    items?: readonly LineLike[] | null
-    codFeeLabel?: string
-    labels?: Pick<OrderLabels, "codFee">
-  } = {}
-): { rows: OrderTotalsRow[]; total: number } {
-  const l = { ...defaultOrderLabels, ...opts.labels }
-  const rows: OrderTotalsRow[] = []
-
-  // Legacy fee LINE (Medusa-era injection) — Cartbase-native carts never
-  // have one, but ported data / hybrid stores might.
-  const codFeeItem = findFeeLine(opts.items || [])
-  const nativeFee = Number(source.cod_fee_total ?? 0)
-  const lineFee = Number(codFeeItem?.total ?? 0)
-  const codFeeAmount = nativeFee > 0 ? nativeFee : lineFee
-
-  // Subtotal: prefer the product-only net; fall back to combined-minus-
-  // shipping, then combined. Subtract a legacy fee line's net so the
-  // visible Subtotal stays product-only (v2.3.1 production fix).
-  const baseSubtotal =
-    source.item_subtotal ??
-    (source.subtotal !== null &&
-    source.subtotal !== undefined &&
-    source.shipping_subtotal !== null &&
-    source.shipping_subtotal !== undefined
-      ? Number(source.subtotal) - Number(source.shipping_subtotal)
-      : source.subtotal ?? 0)
-  const feeNet = codFeeItem
-    ? Number(codFeeItem.subtotal ?? codFeeItem.total ?? 0)
-    : 0
-  rows.push({
-    key: "subtotal",
-    amount: Math.max(0, Number(baseSubtotal ?? 0) - feeNet),
-  })
-
-  const shippingAmount = Number(
-    source.shipping_subtotal ?? source.shipping_total ?? 0
-  )
-  rows.push({
-    key: "shipping",
-    amount: shippingAmount,
-    free: shippingAmount === 0,
-  })
-
-  if (codFeeAmount > 0) {
-    rows.push({
-      key: "codFee",
-      amount: codFeeAmount,
-      label:
-        opts.codFeeLabel ??
-        source.cod_fee_label ??
-        ((codFeeItem as { title?: string } | null)?.title || undefined) ??
-        l.codFee,
-    })
-  }
-
-  const discount = Number(source.discount_total ?? 0)
-  if (discount > 0) {
-    rows.push({ key: "discount", amount: discount, negative: true })
-  }
-
-  rows.push({ key: "tax", amount: Number(source.tax_total ?? 0) })
-
-  return { rows, total: Number(source.total ?? 0) }
-}
-
-type OrderTotalsProps = {
-  totals: OrderTotalsSource
-  currencyCode: string
-  /** Lines from the same source — used only to detect a legacy fee line. */
-  items?: readonly LineLike[] | null
-  labels?: Pick<
-    OrderLabels,
-    "subtotal" | "shipping" | "discount" | "tax" | "total" | "free" | "codFee"
-  >
-  /**
-   * Per-store override for the cash-on-delivery fee row label. Optional —
-   * falls back to the server's `cod_fee_label`, then the fee line's title,
-   * then the translated `labels.codFee` default.
-   */
-  codFeeLabel?: string
-}
-
-export function OrderTotals({
-  totals,
-  currencyCode,
-  items,
-  labels,
-  codFeeLabel,
-}: OrderTotalsProps) {
-  const l = { ...defaultOrderLabels, ...labels }
-  const { rows, total } = selectOrderTotalsRows(totals, {
-    items,
-    codFeeLabel,
-    labels: l,
-  })
-
-  const labelFor = (row: OrderTotalsRow): string => {
-    switch (row.key) {
-      case "subtotal":
-        return l.subtotal
-      case "shipping":
-        return l.shipping
-      case "codFee":
-        return row.label ?? l.codFee
-      case "discount":
-        return l.discount
-      case "tax":
-        return l.tax
-    }
-  }
-
-  return (
-    <div className="pt-4 border-t border-border">
-      <div className="flex flex-col gap-2 text-sm">
-        {rows.map((row) => (
-          <div key={row.key} className="flex justify-between">
-            <span className="text-muted-foreground">{labelFor(row)}</span>
-            {row.free ? (
-              <span className="text-sm font-medium text-success">{l.free}</span>
-            ) : row.negative ? (
-              <span className="text-sm text-success">
-                -{" "}
-                <DualPrice
-                  amount={row.amount}
-                  currencyCode={currencyCode}
-                  className="text-sm text-success"
-                />
-              </span>
-            ) : (
-              <DualPrice
-                amount={row.amount}
-                currencyCode={currencyCode}
-                className="text-sm text-foreground"
-              />
-            )}
-          </div>
-        ))}
-      </div>
-
-      <div className="h-px bg-border my-3" />
-      <div className="flex justify-between items-baseline">
-        <span className="text-[15px] font-bold text-foreground">{l.total}</span>
-        <DualPrice
-          amount={total}
-          currencyCode={currencyCode}
-          className="text-xl font-bold text-foreground tracking-tight"
-        />
-      </div>
-    </div>
-  )
-}
-
-export { type OrderTotalsProps }
+import { DualPrice } from "../lib/dual-price"
+import { findFeeLine, type LineLike } from "../lib/cart-helpers"
+import { defaultOrderLabels, type OrderLabels } from "./labels"
+
+/**
+ * Order totals breakdown. Ported from `@1click/ui/src/order/order-totals.tsx`
+ * (v2.3.1) with the Cartbase money seam:
+ *
+ * Totals are SERVER truth and the Cartbase store order read
+ * (`StoreOrderDetail`) carries NONE of them — they live where the server
+ * computed them: the decorated cart the app holds on the confirmation page
+ * (`api/carts` `Cart`: `item_subtotal`, `shipping_subtotal`,
+ * `discount_total`, `tax_total`, `total`, `payment_method_fee_total`, `payment_method_fee_label`)
+ * or the order's summary snapshot (`order_summaries.totals` — reachable via
+ * `completeCart().order.summary`). The component takes a structural
+ * `OrderTotalsSource` both of those satisfy (`orderTotalsFromSummary()`
+ * adapts the summary shape) and only SELECTS + FORMATS rows — it never
+ * computes money beyond the two production subtractions documented below.
+ *
+ * Method-fee display, in preference order (production fix preserved):
+ *  1. Cartbase-native fee: `payment_method_fee_total` > 0 (never a line
+ *     item; already folded into `total` server-side), labeled by the
+ *     merchant-editable `payment_method_fee_label`. Pre-rename summaries
+ *     (2026-08-11) spelled the keys cod_fee_* — read as legacy fallback.
+ *  2. legacy Medusa-era fee LINE ITEM (`metadata.is_cod_fee`) found in
+ *     `items` — its net is subtracted from the visible subtotal so the
+ *     Subtotal row stays product-only while Tax keeps the fee's tax
+ *     portion (v2.3.1 fix).
+ *  3. label fallbacks: `methodFeeLabel` prop → source label →
+ *     fee line's own title → translated `labels.paymentMethodFee`.
+ */
+
+/** Structural totals source — `api/carts` `Cart` satisfies it directly. */
+export interface OrderTotalsSource {
+  /** Product-only net subtotal (cart path). Preferred. */
+  item_subtotal?: number | null
+  /** Combined items+shipping net (summary path fallback). */
+  subtotal?: number | null
+  /** Shipping net (cart path). Preferred for the Shipping row. */
+  shipping_subtotal?: number | null
+  /** Shipping gross (summary path fallback). */
+  shipping_total?: number | null
+  discount_total?: number | null
+  tax_total?: number | null
+  total?: number | null
+  /** Cartbase-native method fee (already folded into `total`). */
+  payment_method_fee_total?: number | null
+  /** The method's fee label from the server. */
+  payment_method_fee_label?: string | null
+  /** LEGACY pre-rename summary keys (2026-08-11) — read-only fallback. */
+  cod_fee_total?: number | null
+  cod_fee_label?: string | null
+  [key: string]: unknown
+}
+
+/**
+ * Adapt `order_summaries.totals` (shape:
+ * `{subtotal, total, tax_total, discount_total, shipping_total,
+ * payment_method_fee_total}` — src/app/api/store/carts/[id]/complete/_copy.ts) to an
+ * `OrderTotalsSource`. Accepts the raw `CompletedOrder["summary"]` value
+ * (embed row, array of rows, or the totals object itself); null when no
+ * totals can be found.
+ */
+export function orderTotalsFromSummary(
+  summary: unknown
+): OrderTotalsSource | null {
+  if (!summary || typeof summary !== "object") return null
+  const first = Array.isArray(summary) ? summary[0] : summary
+  if (!first || typeof first !== "object") return null
+  const rec = first as Record<string, unknown>
+  const totals =
+    rec.totals && typeof rec.totals === "object"
+      ? (rec.totals as Record<string, unknown>)
+      : rec
+  if (typeof totals.total !== "number") return null
+  return totals as OrderTotalsSource
+}
+
+export type OrderTotalsRow = {
+  key: "subtotal" | "shipping" | "methodFee" | "discount" | "tax"
+  /** Resolved display label (methodFee row only — others use the label pack). */
+  label?: string
+  amount: number
+  /** Shipping row at 0 renders the FREE badge instead of a price. */
+  free?: boolean
+  /** Discount row renders negated. */
+  negative?: boolean
+}
+
+/**
+ * Pure row selection — the entire display policy of the breakdown, kept
+ * out of JSX so it is unit-testable (tests/unit/storefront-order-reviews).
+ */
+export function selectOrderTotalsRows(
+  source: OrderTotalsSource,
+  opts: {
+    items?: readonly LineLike[] | null
+    methodFeeLabel?: string
+    labels?: Pick<OrderLabels, "paymentMethodFee">
+  } = {}
+): { rows: OrderTotalsRow[]; total: number } {
+  const l = { ...defaultOrderLabels, ...opts.labels }
+  const rows: OrderTotalsRow[] = []
+
+  // Legacy fee LINE (Medusa-era injection) — Cartbase-native carts never
+  // have one, but ported data / hybrid stores might.
+  const feeItem = findFeeLine(opts.items || [])
+  const nativeFee = Number(source.payment_method_fee_total ?? source.cod_fee_total ?? 0)
+  const lineFee = Number(feeItem?.total ?? 0)
+  const methodFeeAmount = nativeFee > 0 ? nativeFee : lineFee
+
+  // Subtotal: prefer the product-only net; fall back to combined-minus-
+  // shipping, then combined. Subtract a legacy fee line's net so the
+  // visible Subtotal stays product-only (v2.3.1 production fix).
+  const baseSubtotal =
+    source.item_subtotal ??
+    (source.subtotal !== null &&
+    source.subtotal !== undefined &&
+    source.shipping_subtotal !== null &&
+    source.shipping_subtotal !== undefined
+      ? Number(source.subtotal) - Number(source.shipping_subtotal)
+      : source.subtotal ?? 0)
+  const feeNet = feeItem
+    ? Number(feeItem.subtotal ?? feeItem.total ?? 0)
+    : 0
+  rows.push({
+    key: "subtotal",
+    amount: Math.max(0, Number(baseSubtotal ?? 0) - feeNet),
+  })
+
+  const shippingAmount = Number(
+    source.shipping_subtotal ?? source.shipping_total ?? 0
+  )
+  rows.push({
+    key: "shipping",
+    amount: shippingAmount,
+    free: shippingAmount === 0,
+  })
+
+  if (methodFeeAmount > 0) {
+    rows.push({
+      key: "methodFee",
+      amount: methodFeeAmount,
+      label:
+        opts.methodFeeLabel ??
+        source.payment_method_fee_label ??
+        source.cod_fee_label ??
+        ((feeItem as { title?: string } | null)?.title || undefined) ??
+        l.paymentMethodFee,
+    })
+  }
+
+  const discount = Number(source.discount_total ?? 0)
+  if (discount > 0) {
+    rows.push({ key: "discount", amount: discount, negative: true })
+  }
+
+  rows.push({ key: "tax", amount: Number(source.tax_total ?? 0) })
+
+  return { rows, total: Number(source.total ?? 0) }
+}
+
+type OrderTotalsProps = {
+  totals: OrderTotalsSource
+  currencyCode: string
+  /** Lines from the same source — used only to detect a legacy fee line. */
+  items?: readonly LineLike[] | null
+  labels?: Pick<
+    OrderLabels,
+    "subtotal" | "shipping" | "discount" | "tax" | "total" | "free" | "paymentMethodFee"
+  >
+  /**
+   * Per-store override for the method-fee row label. Optional — falls back
+   * to the server's `payment_method_fee_label`, then the fee line's title,
+   * then the translated `labels.paymentMethodFee` default.
+   */
+  methodFeeLabel?: string
+}
+
+export function OrderTotals({
+  totals,
+  currencyCode,
+  items,
+  labels,
+  methodFeeLabel,
+}: OrderTotalsProps) {
+  const l = { ...defaultOrderLabels, ...labels }
+  const { rows, total } = selectOrderTotalsRows(totals, {
+    items,
+    methodFeeLabel,
+    labels: l,
+  })
+
+  const labelFor = (row: OrderTotalsRow): string => {
+    switch (row.key) {
+      case "subtotal":
+        return l.subtotal
+      case "shipping":
+        return l.shipping
+      case "methodFee":
+        return row.label ?? l.paymentMethodFee
+      case "discount":
+        return l.discount
+      case "tax":
+        return l.tax
+    }
+  }
+
+  return (
+    <div className="pt-4 border-t border-border">
+      <div className="flex flex-col gap-2 text-sm">
+        {rows.map((row) => (
+          <div key={row.key} className="flex justify-between">
+            <span className="text-muted-foreground">{labelFor(row)}</span>
+            {row.free ? (
+              <span className="text-sm font-medium text-success">{l.free}</span>
+            ) : row.negative ? (
+              <span className="text-sm text-success">
+                -{" "}
+                <DualPrice
+                  amount={row.amount}
+                  currencyCode={currencyCode}
+                  className="text-sm text-success"
+                />
+              </span>
+            ) : (
+              <DualPrice
+                amount={row.amount}
+                currencyCode={currencyCode}
+                className="text-sm text-foreground"
+              />
+            )}
+          </div>
+        ))}
+      </div>
+
+      <div className="h-px bg-border my-3" />
+      <div className="flex justify-between items-baseline">
+        <span className="text-[15px] font-bold text-foreground">{l.total}</span>
+        <DualPrice
+          amount={total}
+          currencyCode={currencyCode}
+          className="text-xl font-bold text-foreground tracking-tight"
+        />
+      </div>
+    </div>
+  )
+}
+
+export { type OrderTotalsProps }