@cartbase/storefront 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {

package/src/api/integrations.ts

@@ -177,9 +177,11 @@ export interface StorePickupPoint {
   provider: string
   mode: "office" | "locker"
   /** THEIR id, exactly as the order will carry it. */
-  id: string
-  name: string
-  city: string
+  id: string
+  name: string
+  /** Alternate script/transliteration supplied by the carrier. */
+  secondary_name?: string
+  city: string
   address: string
   postal_code: string
   phone: string

package/src/checkout/checkout-client.tsx

@@ -5,7 +5,8 @@ import type { Appearance, StripeElementsOptions } from "@stripe/stripe-js"
 import type { StorefrontClient } from "../api/http"
 import type { Cart } from "../api/carts"
 import type { StoreShippingOption } from "../api/checkout"
-import type { StoreCustomer } from "../api/customers"
+import type { StoreCustomer } from "../api/customers"
+import type { PaymentMethod } from "../common/payment-icons"
 import { CheckoutAddressForm } from "./address-form"
 import { DiscountSection } from "./discount-section"
 import { MobileCheckoutBottomBar } from "./mobile-checkout-bottom-bar"
@@ -59,7 +60,11 @@ type CheckoutClientProps = {
   cart: Cart
   customer: StoreCustomer | null
   availableShippingMethods: StoreShippingOption[] | null
-  availablePaymentMethods: PaymentProviderLike[] | null
+  availablePaymentMethods: PaymentProviderLike[] | null
+  /** Card and wallet marks returned by `GET /api/store/payment-marks`. */
+  paymentMarks?: readonly PaymentMethod[]
+  /** Store-owned terms notice, including links to its content pages. */
+  termsContent?: React.ReactNode
   /**
    * The country to PRESELECT when the cart has no shipping address yet.
    * Optional, like the hook's own: the offer comes from the store
@@ -76,8 +81,10 @@ type CheckoutClientProps = {
     methods: PaymentProviderLike[] | null,
     selectedShippingOption: StoreShippingOption | null
   ) => PaymentProviderLike[] | null
-  /** Show the gift-card widget in the summary (default true). */
-  showGiftCards?: boolean
+  /** Show the gift-card widget in the summary (default true). */
+  showGiftCards?: boolean
+  /** Show the security reassurance below the desktop total (default true). */
+  showSecureCheckout?: boolean
   logoByFulfillmentOptionId?: Record<string, { src: string; alt: string }>
   /** Stripe Elements appearance + fonts forwarded to PaymentWrapper. */
   appearance?: Appearance
@@ -107,11 +114,14 @@ export function CheckoutClient({
   cart,
   customer,
   availableShippingMethods,
-  availablePaymentMethods,
+  availablePaymentMethods,
+  paymentMarks,
+  termsContent,
   countryCode,
   countries,
   paymentMethodFilter,
-  showGiftCards = true,
+  showGiftCards = true,
+  showSecureCheckout = true,
   logoByFulfillmentOptionId,
   appearance,
   fonts,
@@ -165,9 +175,10 @@ export function CheckoutClient({
       <MobileCheckoutTopBar
         client={client}
         cart={o.summaryCart}
-        optimisticShippingCost={o.optimisticShippingCost}
-        optimisticMethodFee={o.optimisticMethodFee}
-        showGiftCards={showGiftCards}
+        optimisticShippingCost={o.optimisticShippingCost}
+        optimisticMethodFee={o.optimisticMethodFee}
+        methodFeeLabel={o.paymentTab === "cod" ? o.offlineMethod?.fee_label ?? undefined : undefined}
+        showGiftCards={showGiftCards}
         onCartChange={handleCartChange}
       />
 
@@ -218,9 +229,13 @@ export function CheckoutClient({
 
             <CheckoutPaymentMethodList
               cart={cart}
-              hasCard={o.hasCard}
-              hasCod={o.hasCod}
-              paymentTab={o.paymentTab}
+              hasCard={o.hasCard}
+              hasCod={o.hasCod}
+              offlineMethod={o.offlineMethod}
+              paymentMethodOrder={o.paymentMethodOrder}
+              paymentMarks={paymentMarks}
+              termsContent={termsContent}
+              paymentTab={o.paymentTab}
               onPaymentTab={o.handlePaymentTab}
               deliveryReady={o.deliveryReady}
               nothingToPay={o.nothingToPay}
@@ -252,9 +267,10 @@ export function CheckoutClient({
                   <MobileCheckoutBottomBar
                     client={client}
                     cart={o.summaryCart}
-                    optimisticShippingCost={o.optimisticShippingCost}
-                    optimisticMethodFee={o.optimisticMethodFee}
-                    showGiftCards={showGiftCards}
+                    optimisticShippingCost={o.optimisticShippingCost}
+                    optimisticMethodFee={o.optimisticMethodFee}
+                    methodFeeLabel={o.paymentTab === "cod" ? o.offlineMethod?.fee_label ?? undefined : undefined}
+                    showGiftCards={showGiftCards}
                     hideDiscount
                     onCartChange={handleCartChange}
                   />
@@ -273,10 +289,12 @@ export function CheckoutClient({
                 onOptimisticShippingClear={() =>
                   o.setOptimisticShippingCost(null)
                 }
-                optimisticMethodFee={o.optimisticMethodFee}
-                onOptimisticMethodFeeClear={() => o.setOptimisticMethodFee(null)}
-                showGiftCards={showGiftCards}
-                onCartChange={handleCartChange}
+                optimisticMethodFee={o.optimisticMethodFee}
+                onOptimisticMethodFeeClear={() => o.setOptimisticMethodFee(null)}
+                methodFeeLabel={o.paymentTab === "cod" ? o.offlineMethod?.fee_label ?? undefined : undefined}
+                showGiftCards={showGiftCards}
+                showSecureCheckout={showSecureCheckout}
+                onCartChange={handleCartChange}
               />
             </div>
           </div>

package/src/checkout/order-summary.tsx

@@ -168,7 +168,9 @@ type OrderSummaryProps = {
   /** Show the gift-card widget. Default true; pass false for stores that
    * haven't enabled gift cards (the widget itself is harmless either way —
    * an unknown code gets the generic refusal). */
-  showGiftCards?: boolean
+  showGiftCards?: boolean
+  /** Show the security reassurance below the total. Default true. */
+  showSecureCheckout?: boolean
   /**
    * Receives every decorated cart returned by a summary mutation
    * (quantity change, promo apply, gift-card apply/remove). Hosts update
@@ -186,9 +188,10 @@ export function OrderSummary({
   onOptimisticShippingClear,
   optimisticMethodFee,
   onOptimisticMethodFeeClear,
-  methodFeeLabel,
-  showGiftCards = true,
-  onCartChange,
+  methodFeeLabel,
+  showGiftCards = true,
+  showSecureCheckout = true,
+  onCartChange,
 }: OrderSummaryProps) {
   const labels = useCheckoutLabels()
 
@@ -377,7 +380,11 @@ export function OrderSummary({
           )}
         </div>
 
-        <div className="mx-5 sm:mx-6 mt-4 pt-4 border-t border-border">
+        <div
+          className={`mx-5 sm:mx-6 mt-4 pt-4 border-t border-border ${
+            showSecureCheckout ? "" : "pb-5"
+          }`}
+        >
           <div className="flex justify-between items-center">
             <span className="text-lg font-bold text-foreground">
               {labels.total}
@@ -420,22 +427,24 @@ export function OrderSummary({
           )}
         </div>
 
-        <div className="px-5 sm:px-6 pb-5 pt-4 flex items-center justify-center gap-2 text-xs text-muted-foreground">
-          <svg
-            className="w-3.5 h-3.5"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke="currentColor"
-            strokeWidth={2}
-          >
-            <path
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
-            />
-          </svg>
-          <span>{labels.secureCheckout}</span>
-        </div>
+        {showSecureCheckout && (
+          <div className="px-5 sm:px-6 pb-5 pt-4 flex items-center justify-center gap-2 text-xs text-muted-foreground">
+            <svg
+              className="w-3.5 h-3.5"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+              />
+            </svg>
+            <span>{labels.secureCheckout}</span>
+          </div>
+        )}
       </div>
     </div>
   )

package/src/checkout/payment-method-list.tsx

@@ -2,9 +2,11 @@
 
 import { PaymentElement } from "@stripe/react-stripe-js"
 import type { StripePaymentElementChangeEvent } from "@stripe/stripe-js"
-import { useContext, useEffect, useState } from "react"
-
-import { cn } from "../lib/utils"
+import { useContext, useEffect, useState } from "react"
+
+import type { StorePaymentMethodEntry } from "../api/checkout"
+import { PaymentIcon, type PaymentMethod } from "../common/payment-icons"
+import { cn } from "../lib/utils"
 import { useCheckoutLabels } from "./context"
 import { ErrorMessage } from "./error-message"
 import { PaymentButton } from "./payment-button"
@@ -34,9 +36,17 @@ import type { CheckoutLogError } from "./use-checkout-orchestration"
 type CheckoutPaymentMethodListProps = {
   /** Structural cart — forwarded to PaymentButton (`id`/`total`/`currency_code`). */
   cart: { id: string; total?: number | null; currency_code: string }
-  hasCard: boolean
-  hasCod: boolean
-  paymentTab: "card" | "cod"
+  hasCard: boolean
+  hasCod: boolean
+  /** The merchant-configured method shown by the offline/COD tab. */
+  offlineMethod: StorePaymentMethodEntry | null
+  /** Platform-defined order after checkout rules have been applied. */
+  paymentMethodOrder: Array<"card" | "cod">
+  /** Card and wallet marks enabled for the connected payment provider. */
+  paymentMarks?: readonly PaymentMethod[]
+  /** Store-owned terms notice. Falls back to the locale's plain text. */
+  termsContent?: React.ReactNode
+  paymentTab: "card" | "cod"
   onPaymentTab: (tab: "card" | "cod") => void
   deliveryReady: boolean
   paymentError: string | null
@@ -117,9 +127,13 @@ type CheckoutPaymentMethodListProps = {
 
 export function CheckoutPaymentMethodList({
   cart,
-  hasCard,
-  hasCod,
-  paymentTab,
+  hasCard,
+  hasCod,
+  offlineMethod,
+  paymentMethodOrder,
+  paymentMarks = [],
+  termsContent,
+  paymentTab,
   onPaymentTab,
   deliveryReady,
   paymentError,
@@ -138,7 +152,13 @@ export function CheckoutPaymentMethodList({
 
   // Which extra tab is active, if any. Selecting card/cod clears it; the
   // radio group stays single-select across built-in and extra tabs.
-  const [extraTab, setExtraTab] = useState<string | null>(null)
+  const [extraTab, setExtraTab] = useState<string | null>(null)
+  const methodPosition = (method: "card" | "cod") => {
+    const position = paymentMethodOrder.indexOf(method)
+    return position === -1 ? paymentMethodOrder.length : position
+  }
+  const visiblePaymentMarks = paymentMarks.slice(0, 3)
+  const hiddenPaymentMarkCount = Math.max(0, paymentMarks.length - visiblePaymentMarks.length)
 
   // When the store opts out of gating (gatePaymentUntilDelivery=false),
   // the payment section is always shown + interactive regardless of
@@ -212,7 +232,9 @@ export function CheckoutPaymentMethodList({
       <h2 className="text-lg font-semibold text-foreground mb-1 tracking-tight">
         {labels.paymentMethod}
       </h2>
-      <p className="text-xs text-muted-foreground mb-4">{labels.termsText}</p>
+      <p className="text-xs text-muted-foreground mb-4">
+        {termsContent ?? labels.termsText}
+      </p>
 
       {paymentGated ? (
         <div className="p-4 bg-muted rounded-lg border border-border">
@@ -239,7 +261,7 @@ export function CheckoutPaymentMethodList({
         // and tracking refs upstream are NOT torn down. That's the
         // whole point of moving away from PaymentWrapper-wraps-all.
         <StripeElementsScope passthrough>
-          <div className="space-y-2">
+          <div className="flex flex-col gap-2">
             {nothingToPay && (
               // One line instead of a tender list. The shopper owes
               // nothing, so every radio here would be a question with no
@@ -250,8 +272,9 @@ export function CheckoutPaymentMethodList({
               </div>
             )}
             {!nothingToPay && hasCard && (
-              <div
-                className={cn(
+              <div
+                style={{ order: methodPosition("card") }}
+                className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
                   paymentTab === "card" && !extraTab
                     ? "border-primary bg-primary/5"
@@ -276,10 +299,22 @@ export function CheckoutPaymentMethodList({
                       <div className="w-2 h-2 rounded-full bg-primary" />
                     )}
                   </div>
-                  <span className="text-sm font-medium text-foreground">
-                    {labels.payOnline}
-                  </span>
-                </button>
+                  <span className="text-sm font-medium text-foreground">
+                    {labels.payOnline}
+                  </span>
+                  {visiblePaymentMarks.length > 0 && (
+                    <span className="ml-auto flex items-center gap-1.5 pl-3">
+                      {visiblePaymentMarks.map((method) => (
+                        <PaymentIcon key={method} method={method} className="h-6" />
+                      ))}
+                      {hiddenPaymentMarkCount > 0 && (
+                        <span className="flex h-6 min-w-8 items-center justify-center rounded border border-border bg-card px-1.5 text-xs font-medium text-foreground">
+                          +{hiddenPaymentMarkCount}
+                        </span>
+                      )}
+                    </span>
+                  )}
+                </button>
 
                 {paymentTab === "card" && !extraTab && (
                   <div className="px-4 pb-4 pt-2">
@@ -329,8 +364,9 @@ export function CheckoutPaymentMethodList({
             )}
 
             {!nothingToPay && hasCod && (
-              <div
-                className={cn(
+              <div
+                style={{ order: methodPosition("cod") }}
+                className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
                   paymentTab === "cod" && !extraTab
                     ? "border-primary bg-primary/5"
@@ -355,23 +391,24 @@ export function CheckoutPaymentMethodList({
                       <div className="w-2 h-2 rounded-full bg-primary" />
                     )}
                   </div>
-                  <span className="text-sm font-medium text-foreground">
-                    {labels.cashOnDelivery}
-                  </span>
+                  <span className="text-sm font-medium text-foreground">
+                    {offlineMethod?.name ?? labels.cashOnDelivery}
+                  </span>
                 </button>
                 {paymentTab === "cod" && !extraTab && (
                   <div className="px-4 pb-3 pt-0">
-                    <p className="text-xs text-muted-foreground ml-[30px]">
-                      {labels.codNote}
-                    </p>
+                    <p className="text-xs text-muted-foreground ml-[30px]">
+                      {offlineMethod?.instructions ?? labels.codNote}
+                    </p>
                   </div>
                 )}
               </div>
             )}
 
-            {!nothingToPay && extraTabs?.map((tab) => (
-              <div
-                key={tab.id}
+            {!nothingToPay && extraTabs?.map((tab, index) => (
+              <div
+                key={tab.id}
+                style={{ order: paymentMethodOrder.length + index }}
                 className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
                   extraTab === tab.id

package/src/checkout/pickup-point-selector.tsx

@@ -177,10 +177,11 @@ export function PickupPointSelector({
         <div className="flex-1 min-w-0">
           <p className="text-sm font-medium text-foreground leading-tight">
             {point.name}
-          </p>
-          <p className="text-xs text-muted-foreground mt-0.5">
-            {[point.address, point.city].filter(Boolean).join(", ")}
-          </p>
+          </p>
+          <p className="text-xs text-muted-foreground mt-0.5">
+            {point.secondary_name ||
+              [point.address, point.city].filter(Boolean).join(", ")}
+          </p>
         </div>
 
         {distance !== null && distance > 0 && (

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

@@ -977,9 +977,37 @@ export function useCheckoutOrchestration({
   // The offline tab = a merchant METHOD (the COD switch, else the first
   // manual method) — sessions initiate by payment_method_id, provider NULL.
   const offlineMethod = findOfflineMethod(effectiveAvailablePaymentMethods)
-  const hasCod = !!offlineMethod
-  const codMethodId = offlineMethod?.payment_method_id
-  const offlineIsCodKind = offlineMethod?.kind === "cod"
+  const hasCod = !!offlineMethod
+  const codMethodId = offlineMethod?.payment_method_id
+  const offlineIsCodKind = offlineMethod?.kind === "cod"
+
+  // Preserve the platform listing order all the way into the checkout UI.
+  // The API has already applied checkout_method_order; collapsing the rows
+  // into card/COD booleans used to throw that order away.
+  const paymentMethodOrder = useMemo(() => {
+    const order: Array<"card" | "cod"> = []
+    for (const entry of effectiveAvailablePaymentMethods ?? []) {
+      if (
+        hasCard &&
+        "id" in entry &&
+        entry.id === cardEntry?.id &&
+        !order.includes("card")
+      ) {
+        order.push("card")
+      }
+      if (
+        hasCod &&
+        "payment_method_id" in entry &&
+        entry.payment_method_id === codMethodId &&
+        !order.includes("cod")
+      ) {
+        order.push("cod")
+      }
+    }
+    if (hasCard && !order.includes("card")) order.push("card")
+    if (hasCod && !order.includes("cod")) order.push("cod")
+    return order
+  }, [effectiveAvailablePaymentMethods, hasCard, cardEntry?.id, hasCod, codMethodId])
 
   // The store offers a card it cannot mount: reported once, to the merchant,
   // because the shopper must never be the one who discovers it. Pre-2026-09-18
@@ -996,12 +1024,12 @@ export function useCheckoutOrchestration({
     )
   }, [cardEntry, cardOffer.mountable, logError])
 
-  // Default tab: card when available, else COD. The eager-session model
-  // used to seed from the cart's pending session provider; in the
-  // deferred-intent model there is no session at mount.
-  const [paymentTab, setPaymentTab] = useState<"card" | "cod">(
-    hasCard ? "card" : "cod"
-  )
+  // Default tab: the first method in the merchant's checkout order. The eager-session model
+  // used to seed from the cart's pending session provider; in the
+  // deferred-intent model there is no session at mount.
+  const [paymentTab, setPaymentTab] = useState<"card" | "cod">(
+    paymentMethodOrder[0] ?? (hasCard ? "card" : "cod")
+  )
 
   // Optimistic method-fee state. Painted instantly on tab toggle so the
   // totals row shows the predicted fee BEFORE the server applies it (at
@@ -1789,8 +1817,9 @@ export function useCheckoutOrchestration({
     selectedPickup,
 
     // Payment
-    paymentTab,
-    hasCard,
+    paymentTab,
+    paymentMethodOrder,
+    hasCard,
     hasCod,
     cardId,
     /** The store's own Stripe, off the card entry — what `PaymentWrapper`