create-cartbase 0.1.24 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/checkout.md

@@ -147,10 +147,12 @@ curl -sf -X POST "$BASE/api/store/shipping-options/$SO_ID/calculate" \
 
 - **Purpose** — render the payment-method picker.
 - **Auth** — anon `x-client-id`.
-- **Request** — `GET ?region_id=…&cart_id=…`, both optional. Without
+- **Request** — `GET ?region_id=…&cart_id=…&shipping_option_id=…`, all optional. Without
   `region_id`: the tenant's enabled providers (global catalog ∩ tenant
   enablement). With it: providers linked to that region. `cart_id` feeds
   the rules engine — storefronts SHOULD pass it during checkout.
+  `shipping_option_id` evaluates a prospective delivery click immediately,
+  before its separate cart-preference write finishes.
 - **Response** — list envelope, full filtered list. Two entry shapes share
   the array: connected PROCESSORS (`{id}` — pp_stripe) and merchant
   payment METHODS (`{payment_method_id, name, kind, instructions,
@@ -174,6 +176,13 @@ curl -sf -X POST "$BASE/api/store/shipping-options/$SO_ID/calculate" \
       "fee_amount": 4.99, "fee_label": "COD fee" }
     // pp_giftcard is INTERNAL tender and is never listed
   ],
+  "payment_providers_by_shipping_option": {
+    "so_boxnow": [{ "id": "pp_stripe", "is_enabled": true }],
+    "so_speedy": [
+      { "id": "pp_stripe", "is_enabled": true },
+      { "payment_method_id": "pm_cod", "name": "Cash on delivery", "kind": "cod" }
+    ]
+  },
   "count": 3, "offset": 0, "limit": 3
 }
 ```
@@ -191,7 +200,16 @@ curl -sf -X POST "$BASE/api/store/shipping-options/$SO_ID/calculate" \
 - **Errors** — none beyond the standard envelope (empty list when nothing
   is enabled); initiate 400s on unknown/disabled/foreign method ids and
   `payment_method_not_in_region` for an unclaimed region.
-- **SDK** — `checkout.listPaymentProviders(client, {region_id, cart_id})`.
+- **SDK** — `checkout.listPaymentProviders(client, {region_id, cart_id,
+  shipping_option_id})`.
+- **Delivery-dependent payment rules** — selecting a delivery option is
+  remembered on the cart before the atomic Buy call. The initial listing's
+  `payment_providers_by_shipping_option` map is evaluated by the server from
+  the same cart context and live rules. `CheckoutClient` selects the mapped
+  list synchronously on every carrier click; older fallback responses are
+  discarded, and remembered choices are serialized with latest-intent wins.
+  The completion guard repeats the decision against the attached shipping
+  method.
 - **Components** — payment picker.
 - **Settings** — Stripe connects in Settings, Payments (provisions
   `pp_stripe` + credentials); payment methods live in the same screen

package/template/app/docs/components.md

@@ -433,11 +433,15 @@ code-first through the error-copy maps, never raw API strings.
   `customers.updateMe` (best-effort profile sync incl. Cartbase's first-class
   `company_name`/`company_eik`), `checkout.calculateShippingOption`
   (calculated-rate forward-compat), `checkout.prepareCheckout`,
-  `checkout.syncPaymentAmount` (exposed + fired on payment-tab switch with
-  the new `provider_id`), `checkout.refreshPaymentIfTerminal` (exposed —
-  call REACTIVELY from Elements `loaderror` only), `carts.completeCart`.
-- **Props contract** — `{client, cart, customer, availableShippingMethods,
-  availablePaymentMethods, countryCode?, countries?, paymentMethodFilter?,
+  `checkout.syncPaymentAmount` (exposed + fired on payment-tab switch with
+  the new `provider_id`), `checkout.refreshPaymentIfTerminal` (exposed —
+  call REACTIVELY from Elements `loaderror` only),
+  the server-evaluated payment availability map from
+  `checkout.listPaymentProviders` so delivery-option payment rules update
+  synchronously; a prospective-option request is the fallback for older hosts,
+  `carts.completeCart`.
+- **Props contract** — `{client, cart, customer, availableShippingMethods,
+  availablePaymentMethods, paymentMethodsByShippingOption?, countryCode?, countries?, paymentMethodFilter?,
   orderConfirmedPath?, onOrderPlaced?,
   resolveTrackingMetadata?, logError?}`. `countries` is OPTIONAL and is an
   override: omit it and the hook calls `GET /api/store/countries` itself, so
@@ -471,7 +475,8 @@ code-first through the error-copy maps, never raw API strings.
   fetches `listShippingOptions`/`listPaymentProviders` (+ customer, +
   `getIntegrationsConfig().cod`) and passes them down.
 - **Props contract** — hook options + `showGiftCards?`,
-  `logoByFulfillmentOptionId?`, Stripe `appearance`/`fonts`, `onCartChange?`
+  `showSecureCheckout?`, `paymentMarks?`, `termsContent?`,
+  `logoByFulfillmentOptionId?`, Stripe `appearance`/`fonts`, `onCartChange?`
   (receives every decorated cart from summary mutations; the layout also
   re-runs `syncPaymentAmount` on those).
 - **Mount rules** — `"use client"`; inside `CheckoutProvider`; redirect
@@ -528,9 +533,13 @@ code-first through the error-copy maps, never raw API strings.
 
 ### `<CheckoutShippingMethodList />` — `checkout/shipping-method-list`
 
-- **Purpose** — radio list of shipping options with inline carrier-picker
-  expansion, free-shipping label, optional per-carrier logos, optional
-  read-only price preview pre-address (`previewWhenAddressNotReady`).
+- **Purpose** — radio list of shipping options with inline carrier-picker
+  expansion, free-shipping label, optional per-carrier logos, optional
+  read-only price preview pre-address (`previewWhenAddressNotReady`).
+- **Presentation** — visible shipping-option titles are uppercase so merchant
+  and carrier naming conventions do not create mixed capitalization in one
+  list. An unselected option keeps its card background and uses the primary
+  border color on hover.
 - **SDK calls** — renders `checkout.listShippingOptions(client, {cart_id})`
   rows AS SERVED (rule-filtering + `checkout_method_order` are server-side).
 - **Props contract** — hook state + `logoByFulfillmentOptionId?` as an
@@ -560,8 +569,11 @@ code-first through the error-copy maps, never raw API strings.
 - **Purpose** — THE pickup picker, every carrier, mounted by
   `CheckoutClient` when the option's adapter says its destination is an
   office or locker. Nearest three by haversine distance to the typed address, each
-  with its distance, and a door to search the whole catalogue. The shape
-  Alenika's checkout has carried since it was built.
+  with its distance, and a door to search the whole catalogue. The shape
+  Alenika's checkout has carried since it was built. Primary office and locker
+  names render uppercase across carriers; secondary addresses retain their
+  source casing. Point rows stay on the card surface and show only a primary
+  border on hover.
 - **SDK calls** — `integrations.listPickupPoints(client, provider, {mode,
   catalogue: true, locale})`, one door for all carriers. The complete eligible
   catalogue is cached per SDK client, carrier, mode and language for ten
@@ -630,7 +642,12 @@ code-first through the error-copy maps, never raw API strings.
   is on screen from arrival and the Buy button carries the gate, naming the
   missing step; pass true for the older dimmed-until-delivery flow),
   `beforePaymentButton?` slot, `total` (pass `optimisticTotal`),
-  `nothingToPay?` (pass the hook's), `logError?`.
+  `nothingToPay?` (pass the hook's), `paymentMarks?` (the ordered result of
+  `getPaymentMarks`), `termsContent?` (the store's own linked policy notice),
+  `logError?`. Payment tabs follow the server's checkout-method order. The
+  offline tab prints the configured method name and instructions; the
+  connected processor tab shows up to three enabled payment marks and a
+  `+N` remainder.
 - **An order that asks for no money** (2026-09-18) — with `nothingToPay` the
   rail is replaced by one line saying the order is covered and the button
   becomes **Complete order**, carrying no amount and waiting on no card
@@ -663,7 +680,7 @@ code-first through the error-copy maps, never raw API strings.
 
 - **Purpose** — items (flat rows, READ-ONLY), promo + gift-card widgets,
   totals breakdown (subtotal / shipping / COD fee / discount / total +
-  gift-card tender rows UNDER the unchanged total), secure badge.
+  gift-card tender rows UNDER the unchanged total), optional secure badge.
   `LineItemCard` is the standalone card variant.
 - **A CHECKOUT IS A CHECKOUT** (2026-09-18) — the rows carry no quantity
   control and call no cart endpoint. The order is stated here and changed in
@@ -686,7 +703,8 @@ code-first through the error-copy maps, never raw API strings.
   `tax_total`, `total`, `gift_card_total`, `gift_card_remainder`.
 - **Props contract** — `{client, cart, optimisticShippingCost,
   onOptimisticShippingClear?, optimisticMethodFee?,
-  onOptimisticMethodFeeClear?, methodFeeLabel?, showGiftCards?,
+  onOptimisticMethodFeeClear?, methodFeeLabel?, showGiftCards?,
+  showSecureCheckout?,
   onCartChange?}`. Optimistic values clear automatically once the server
   cart catches up.
 - **The numbers** — every figure comes from `checkoutTotals`
@@ -713,7 +731,9 @@ code-first through the error-copy maps, never raw API strings.
   `<MobileOrderSummaryBody />`: the items with their quantity pills, the
   code and gift-card doors, then subtotal, shipping, the method fee,
   discount, VAT and the gift-card tender pair. The grand total is not
-  repeated inside, because the bar's own row carries it open or closed.
+  repeated inside, because the bar's own row carries it open or closed.
+  The top bar and its open body use the normal card surface, preserving the
+  contrast of item copy, widgets and totals on small screens.
 - **Mount rules** — `CheckoutClient` mounts both (the bottom one through
   `beforePaymentButton`, with `hideDiscount`, beside an always-open
   `DiscountSection`, because a code field two taps deep inside a closed bar
@@ -731,10 +751,11 @@ code-first through the error-copy maps, never raw API strings.
 
 ### `<DiscountSection />` — `checkout/discount-section`
 
-- **Purpose** — promo-code input + applied-promotion list (percentage or
-  fixed amount display). Collapsed behind its own door by default;
-  `alwaysOpen` renders the field itself, which is what the checkout passes
-  on a phone.
+- **Purpose** — promo-code input + applied-promotion list (percentage or
+  fixed amount display). Collapsed behind its own door by default;
+  `alwaysOpen` renders the field itself, which is what the checkout passes
+  on a phone. The door and open field use bounded grids: the action never
+  wraps or escapes the card, and the supporting line is hidden below 380px.
 - **SDK calls** — `POST /api/store/carts/:id/promotions {promo_codes}`
   via the client transport (additive apply; the carts SDK module ships no
   wrapper for this route yet — see [carts.md](carts.md) for the cart
@@ -748,9 +769,10 @@ code-first through the error-copy maps, never raw API strings.
 
 ### `<GiftCardSection />` — `checkout/gift-card-section`
 
-- **Purpose** — gift-card code input + applied-cards chips (masked
-  `••••last4`, per-card live coverage, remove). Cartbase-new — no legacy
-  equivalent.
+- **Purpose** — gift-card code input + applied-cards chips (masked
+  `••••last4`, per-card live coverage, remove). Cartbase-new — no legacy
+  equivalent. Its narrow-screen door follows the same bounded grid as the
+  promo door, so the label cannot turn the action into a four-line row.
 - **SDK calls** — `giftCards.applyGiftCard` / `giftCards.removeGiftCard`
   ([gift-cards.md](gift-cards.md)). Renders `cart.gift_cards[]` /
   `gift_card_total` / `gift_card_remainder` — server truth, no client

package/template/app/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.23.0",
+    "@cartbase/storefront": "^0.24.1",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/src/app/checkout/checkout-page-client.tsx

@@ -17,10 +17,12 @@ export function CheckoutPageClient({
   cart,
   shippingOptions,
   paymentProviders,
+  paymentMethodsByShippingOption,
 }: {
   cart: Cart
   shippingOptions: StoreShippingOption[]
   paymentProviders: StorePaymentEntry[]
+  paymentMethodsByShippingOption?: Record<string, StorePaymentEntry[]>
 }) {
   const router = useRouter()
 
@@ -32,6 +34,7 @@ export function CheckoutPageClient({
         customer={null}
         availableShippingMethods={shippingOptions}
         availablePaymentMethods={paymentProviders}
+        paymentMethodsByShippingOption={paymentMethodsByShippingOption}
         // NO COUNTRY LIST HERE, on purpose (2026-09-13). This file is the
         // seed for every scaffolded store, and it used to pass
         // `countries={[{iso_2:"bg", display_name:"Bulgaria"}]}` with

package/template/app/src/app/checkout/page.tsx

@@ -61,8 +61,11 @@ async function Checkout() {
   return (
     <CheckoutPageClient
       cart={cart}
-      shippingOptions={shippingOptions.shipping_options}
-      paymentProviders={paymentProviders.payment_providers}
+      shippingOptions={shippingOptions.shipping_options}
+      paymentProviders={paymentProviders.payment_providers}
+      paymentMethodsByShippingOption={
+        paymentProviders.payment_providers_by_shipping_option
+      }
     />
   )
 }