create-cartbase 0.1.23 → 0.1.25

package/package.json

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

package/template/app/docs/checkout.md

@@ -57,9 +57,17 @@ changes the total; `refreshPaymentIfTerminal()` from Stripe Elements
 {
   "shipping_options": [{
     "id": "so_…", "name": "Standard",
-    "provider_id": null,          // the carrier, when the merchant bound one
+    "provider_id": "boxnow",     // the connected carrier adapter
     "service_zone_id": "sz_…", "shipping_profile_id": "sp_…",
-    "data": null,
+    "data": { "fulfillment_option": "boxnow-locker" },
+    "carrier": {
+      "id": "boxnow", "name": "BoxNow",
+      "mark_url": "/api/store/integrations/marks/boxnow",
+      "fulfillment_option": {
+        "id": "boxnow-locker", "mode": "locker", "label": "Locker"
+      },
+      "pickup_scope": "city"
+    },
     "type": { "label": "Express" }, // the option's display label, or null
     "amount": 5,                 // the price the cart pays; null without cart_id
     "price_type": "flat"         // calculated-rate carriers not wired yet
@@ -74,6 +82,13 @@ changes the total; `refreshPaymentIfTerminal()` from Stripe Elements
   pass; and a price must exist for the cart. Conditional rates (tiers by
   order amount, cart weight, or cart volume) resolve here — `amount` is
   always the tier the cart actually satisfies.
+- **Carrier contract** — when an option is bound to a carrier, `carrier`
+  contains the adapter identity, mark, destination mode and pickup scope.
+  Checkout renders every office/locker carrier from this contract through
+  the shared picker; it does not carry a carrier-name switch. A carrier with
+  exactly one destination mode is bound automatically, including older
+  options whose `data` was saved before this rule existed. Carriers with
+  multiple modes require the merchant to choose one.
 - **Errors** — 404 `cart_not_found` (bad `cart_id`).
 - **SDK** — `checkout.listShippingOptions(client, {cart_id})`.
 - **Components** — shipping picker, carrier/locker pickers (carrier

package/template/app/docs/components.md

@@ -471,7 +471,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
@@ -533,36 +534,33 @@ code-first through the error-copy maps, never raw API strings.
   read-only price preview pre-address (`previewWhenAddressNotReady`).
 - **SDK calls** — renders `checkout.listShippingOptions(client, {cart_id})`
   rows AS SERVED (rule-filtering + `checkout_method_order` are server-side).
-- **Props contract** — hook state + `econt?`/`boxnow?` picker configs
-  (detection by the STABLE `shipping_option.data.id` — `"econt-office"` /
-  `"boxnow-locker"` — never display names; `boxnow.client` carries the SDK
-  transport) + `logoByFulfillmentOptionId?`.
+- **Props contract** — hook state + `logoByFulfillmentOptionId?` as an
+  optional store override. The normal path needs no carrier-specific props:
+  each option carries the platform-resolved `carrier` contract.
 - **Settings** — checkout rules (`target_type=shipping_option`), method
   ordering, carrier integrations (which options exist at all).
 
 ### Which destination an option books, and the carrier's mark — `checkout/fulfillment-option`, `checkout/carrier-marks`
 
-- **`fulfillmentOptionId(option)`** — the merchant's choice on the shipping
-  option: `econt-office`, `speedy-address`, `boxnow-locker`,
-  `pigeon-office` and the rest of the carrier registry. Cartbase writes it
-  as `data.fulfillment_option` (the Shipping option drawer); `data.id` is
-  read as a fallback for a cart carried over from the ported platform.
+- **`fulfillmentOptionId(option)`** — the merchant's choice on the shipping
+  option: `econt-office`, `speedy-address`, `boxnow-locker`,
+  `pigeon-office` and the rest of the carrier registry. The platform resolves
+  it through the carrier adapter and returns it as
+  `carrier.fulfillment_option.id`; `data.fulfillment_option` and `data.id`
+  remain read fallbacks for an older platform response.
   Every picker, every mark and the hook's own readiness go through this one
   function: the kit read `data.id` alone until 2026-09-18, and since nothing
   on this side writes that key, no office or locker picker had ever opened
   on a Cartbase store.
-- **`carrierMarks(origin)`** — the default `logoByFulfillmentOptionId` for
-  the shipping list: the platform's own carrier marks
-  (`{origin}/integrations/{carrier}.png`, the files the admin wears), both
-  modes of a carrier on one mark. `CheckoutClient` passes it unless the
-  store passes a map of its own, so a store gets branded rows with no files
-  to find and a new carrier arrives already dressed.
+- **`carrierMark(option)`** — reads the mark URL returned by the carrier
+  adapter. `CheckoutClient` uses it unless the store supplies an override,
+  so a connected carrier arrives branded without a storefront asset map.
 
 ### `<PickupPointSelector />` — `checkout/pickup-point-selector`
 
-- **Purpose** — THE pickup picker, every carrier, mounted by
-  `CheckoutClient` for any option whose fulfillment option ends `-office` or
-  `-locker`. Nearest three by haversine distance to the typed address, each
+- **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.
 - **SDK calls** — `integrations.listPickupPoints(client, provider, {mode,
@@ -570,14 +568,14 @@ code-first through the error-copy maps, never raw API strings.
   catalogue is cached per SDK client, carrier, mode and language for ten
   minutes, then ranked by distance BEFORE taking three results. Search runs
   over the same complete list, matching name, city, street and postcode in
-  Latin or Cyrillic. BoxNow restricts both lists to the checkout city, as in
-  Alenika's picker; offices search the whole catalogue. Without a geocoded
+  Latin or Cyrillic. The adapter's `pickup_scope` restricts city-scoped
+  networks such as BoxNow; global office networks search the whole catalogue. Without a geocoded
   address, results fall back to the typed city without displaying distances.
   The mounted locale pack selects Speedy's BG/EN names and addresses.
   Speedy APT lockers and Econt APS stations never appear as offices.
   Pigeon's adapter reads every page. The original `{mode, q, limit}` search
   call remains available to other consumers.
-- **Props contract** — `{client, provider, mode, userCity, userAddress,
+- **Props contract** — `{client, provider, mode, scope, userCity, userAddress,
   selectedPoint, onSelect}`. `onSelect` receives the point AND the carrier's
   own key names, which arrive with the answer from the platform's
   destination registry, so the checkout writes the point under the names
@@ -590,17 +588,15 @@ code-first through the error-copy maps, never raw API strings.
   to the checkout however well the platform served its catalogue: a store
   could offer delivery to a Speedy office and give the shopper no way to
   name one. `pickupOptionOf` (`checkout/pickup-option`) reads the carrier
-  and the mode off the option's own id, so a carrier connected tomorrow
-  opens its picker with no line added anywhere.
+  and the mode from the option's carrier contract, so a carrier connected
+  tomorrow opens its picker with no line added anywhere.
 - **Settings** — the carrier integrations (connected; the market's options).
 
 ### `<EcontOfficeSelector />` / `<BoxNowLockerSelector />` / `<PigeonOfficeSelector />` — `checkout/econt-office-selector`, `checkout/boxnow-locker-selector`, `checkout/pigeon-office-selector`
 
-- **Superseded by `<PickupPointSelector />`** (2026-09-18) and no longer
-  mounted by `CheckoutClient`. Exported still, for a store that mounts its
-  own; the `econt`/`boxnow`/`pigeon` props of
-  `<CheckoutShippingMethodList />` keep working and win for their own
-  carrier when a store passes them.
+- **Superseded by `<PickupPointSelector />`** (2026-09-18) and no longer
+  mounted by `CheckoutClient`. Exported still for a store that imports one
+  directly; the default checkout has no carrier-specific branch or prop.
 - **Purpose** — Bulgarian office/locker pickers: nearest-3 by haversine
   distance (Nominatim geocode of the typed address), city-locked search
   with Cyrillic↔Latin normalization, selected pill + change.
@@ -635,7 +631,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
@@ -668,7 +669,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
@@ -691,7 +692,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`

package/template/app/package.json

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