create-cartbase 0.1.1 → 0.1.2

package/template/app/docs/components.md

@@ -1,4 +1,4 @@
-# Components — `@cartbase/storefront` UI families
+# Components
 
 The component layer of `@cartbase/storefront`: what each family ships, the SDK
 calls it requires, the admin settings that change its behavior, and its mount
@@ -20,8 +20,7 @@ app's CSS; no component hardcodes a color.
 
 ---
 
-## Family: tracking (`@cartbase/storefront/tracking/*`) — SHIPPED
-
+## Family: tracking (`@cartbase/storefront/tracking/*`)
 Meta Pixel + GA4 + Rybbit + Consent Mode v2. The Cartbase split of duties:
 **this package fires client events and writes attribution; server-side CAPI /
 GA4 Measurement Protocol sending is Cartbase-backend-owned** (the
@@ -154,8 +153,7 @@ Meta side) and `gtag('set','user_data',…)`. Call alongside
 
 ---
 
-## Family: primitives (`@cartbase/storefront/primitives/*`) — SHIPPED
-
+## Family: primitives (`@cartbase/storefront/primitives/*`)
 Generic shadcn-style building blocks. No SDK calls, no admin settings —
 pure UI over the theme tokens.
 
@@ -172,8 +170,7 @@ pure UI over the theme tokens.
 
 ---
 
-## Family: lib (`@cartbase/storefront/lib/*`) — SHIPPED
-
+## Family: lib (`@cartbase/storefront/lib/*`)
 Pure helpers — no React except `dual-price`, no fetches. The SDK never
 invents server truths: prices/totals arrive computed from the API
 (`variant.calculated_price`, `cart.total`); these helpers only select and
@@ -204,11 +201,14 @@ format.
 - `lib/sort-products` — client-side re-sort of a fetched page
   (`price_asc|price_desc|created_at`); the API's `order` param stays the
   authority for paginated listings.
-- `lib/payment-constants` — `isStripeLike` / `isPaypal` / `isManual` +
-  `paymentInfoMap`. Translated to Cartbase ids: matches `pp_stripe` exactly
-  (code truth `src/lib/stripe/providers.ts`) plus legacy provider prefixes;
-  `pp_system_default` = COD. Affected by: enabled payment providers +
-  checkout rules (which ids ever reach the client).
+- `lib/payment-constants` — `isStripeLike` / `isPaypal` +
+  `paymentInfoMap`. Two tender shapes since the pp_* kill: a processor
+  `provider_id` (`pp_stripe` exact, code truth
+  `src/lib/stripe/providers.ts`, plus legacy Medusa-era prefixes as
+  fallbacks) or a merchant METHOD rendered by its snapshot NAME — a
+  method never has a provider id to bucket. Affected by: connected
+  processors + enabled methods + checkout rules (which entries ever
+  reach the client).
 - `lib/store-api-error` — `storeApiError(err)`: display-boundary normalizer
   (capitalized message + terminal period).
   Catch `StoreApiError` directly instead when branching on `status`/`code`.
@@ -217,8 +217,7 @@ format.
 
 ---
 
-## Family: checkout (`@cartbase/storefront/checkout/*`) — SHIPPED
-
+## Family: checkout (`@cartbase/storefront/checkout/*`)
 The full checkout page family, production-proven (deferred-
 intent architecture — no payment session exists until Buy click) onto the
 Cartbase orchestration endpoints. The flow every component serves
@@ -227,7 +226,7 @@ Cartbase orchestration endpoints. The flow every component serves
 ```
 listShippingOptions(cart_id) + listPaymentProviders(cart_id)  (render pickers)
    → Buy click → prepareCheckout (ONE atomic, compensated call)
-   → pp_stripe: stripe.confirmPayment(client_secret) | pp_cod/pp_manual: skip
+   → pp_stripe: stripe.confirmPayment(client_secret) | merchant method: skip
    → completeCart → navigate to the confirmed page
 ```
 
@@ -264,21 +263,24 @@ code-first through the error-copy maps, never raw API strings.
   call REACTIVELY from Elements `loaderror` only), `carts.completeCart`.
 - **Props contract** — `{client, cart, customer, availableShippingMethods,
   availablePaymentMethods, countryCode?, countries?, paymentMethodFilter?,
-  codConfig?, orderConfirmedPath?, onOrderPlaced?,
+  orderConfirmedPath?, onOrderPlaced?,
   resolveTrackingMetadata?, logError?}`. `countries` is caller-supplied
-  (Cartbase regions embed NO countries array). `codConfig` = the
-  integrations `cod` block — the COD fee prediction is never hardcoded.
-  `logError` replaces the legacy log writers (all production log
-  points preserved). Returns the full orchestration surface
-  (`performBuyClick`, `optimisticTotal(Cents)`, `deliveryReady`, …).
+  (Cartbase regions embed NO countries array). Fee prediction is never
+  hardcoded: each method LISTING entry carries its own
+  `fee_amount`/`fee_label`. `logError` replaces the legacy log writers
+  (all production log points preserved). Returns the full orchestration
+  surface (`performBuyClick`, `optimisticTotal(Cents)`, `deliveryReady`, …).
 - **Cartbase specifics** — zero-remainder gift path: `prepareCheckout`
-  returning `client_secret:null` + `provider_id:null` SKIPS Stripe and
-  completes on the gift session ([gift-cards.md](gift-cards.md)). Provider
-  ids are `pp_stripe`/`pp_cod`/`pp_manual` exactly; `pp_manual` doubles as
-  the offline tab when no true COD provider exists (fee predicted only for
-  `pp_cod`). COD fee reads the cart-level `cod_fee_total` decoration.
+  returning `client_secret:null` + `provider_id:null` +
+  `payment_method_id:null` SKIPS Stripe and completes on the gift session
+  ([gift-cards.md](gift-cards.md)). Processors are `pp_stripe` exactly;
+  merchant methods list as `{payment_method_id, name, kind, instructions,
+  fee_amount, fee_label}` entries — the COD-kind method wins the offline
+  tab, else the first manual method. The charged fee reads the cart-level
+  `payment_method_fee_total` decoration.
 - **Settings** — checkout rules (filter the listings + complete guard),
-  COD integration (fee), Stripe credentials, gift cards, `accounts_mode`.
+  the methods' own fee configuration (Payments settings), Stripe
+  credentials, gift cards, `accounts_mode`.
 
 ### `<CheckoutClient />` — `checkout/checkout-client`
 
@@ -383,11 +385,11 @@ code-first through the error-copy maps, never raw API strings.
   badge. `LineItemCard` is the standalone card variant.
 - **SDK calls** — `carts.updateLineItem` (quantity); child widgets below.
   Totals are rendered STRAIGHT from the cart decoration: `item_total`,
-  `shipping_total`, `cod_fee_total`/`cod_fee_label`, `discount_total`,
+  `shipping_total`, `payment_method_fee_total`/`payment_method_fee_label`, `discount_total`,
   `tax_total`, `total`, `gift_card_total`, `gift_card_remainder`.
 - **Props contract** — `{client, cart, optimisticShippingCost,
   onOptimisticShippingClear?, optimisticCodFee?, onOptimisticCodFeeClear?,
-  codFeeLabel?, showGiftCards?, onCartChange?}`. Optimistic values clear
+  methodFeeLabel?, showGiftCards?, onCartChange?}`. Optimistic values clear
   automatically once the server cart catches up.
 - **Settings** — COD integration (fee row), gift cards, promotions.
 
@@ -445,8 +447,7 @@ extra modules beyond the per-file exports, imported from
 
 ---
 
-## Family: cart-drawer (`@cartbase/storefront/cart-drawer/*`) — SHIPPED
-
+## Family: cart-drawer (`@cartbase/storefront/cart-drawer/*`)
 Sliding cart UI, production-proven layout. All
 components are `"use client"`. Money is EUR decimal major units everywhere
 (cart totals are SERVER truth from the decorated cart — components render,
@@ -570,8 +571,8 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
 - **Purpose** — full totals breakdown rendered EXACTLY from the decorated
   cart: `subtotal`, `discount_total` (>0, negated for display),
   `shipping_total` (once a shipping method is set; 0 renders FREE; before
-  that "calculated at checkout"), `tax_total` (>0), `cod_fee_total` (>0,
-  labeled by the server's `cod_fee_label`), `total`, then one row per
+  that "calculated at checkout"), `tax_total` (>0), `payment_method_fee_total` (>0,
+  labeled by the server's `payment_method_fee_label`), `total`, then one row per
   applied gift card (masked `last4`, negated; a depleted card stays listed
   at 0) and `gift_card_remainder` — what the remainder provider charges.
   Row selection is the pure `selectSummaryRows(cart)` (unit-tested).
@@ -609,8 +610,7 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
 
 ---
 
-## Family: products (`@cartbase/storefront/products/*`) — SHIPPED
-
+## Family: products (`@cartbase/storefront/products/*`)
 The PDP + product-card family, production-proven. All prices
 render the SERVER-computed `variant.calculated_price` via
 `lib/get-product-price` (Cartbase's flat `price_list_type` wire shape) — no
@@ -754,8 +754,7 @@ with a legacy flat-row fallback. Unit-tested
   `ProductLabelsProvider` for i18n; `addToCart`/`openCart` seams as on
   `ProductActions`.
 
-## Family: store (`@cartbase/storefront/store/*`) — SHIPPED
-
+## Family: store (`@cartbase/storefront/store/*`)
 The listing family: paginated grids, sort, collection/category/search
 templates. Sorting discipline: the API's `order` param is the authority for
 paginated listings; client-side re-sort (`lib/sort-products`) exists ONLY
@@ -859,8 +858,7 @@ search UIs (chips, drawers) that want the same URL contract.
 
 ---
 
-## Family: order (`@cartbase/storefront/order/*`) — SHIPPED
-
+## Family: order (`@cartbase/storefront/order/*`)
 Order confirmation + account order views, production-proven. Some
 platforms ship ONE `StoreOrder` object carrying computed line
 totals, order totals, shipping methods and payments; Cartbase splits those
@@ -894,7 +892,7 @@ component also takes a `labels` prop pick.
   rybbit, deduped by `order.display_id`) is APP-OWNED: fire it from the
   confirmation route exactly once per order per the tracking family's
   dedupe contract — the template deliberately does NOT fire it.
-- **Settings** — COD settings (fee row presence + `cod_fee_label`),
+- **Settings** — COD settings (fee row presence + `payment_method_fee_label`),
   checkout rules (which provider ids appear), store locales (labels pack).
 
 ### `<OrderConfirmationHeader order />` — `order/order-confirmation-header`
@@ -917,19 +915,19 @@ component also takes a `labels` prop pick.
   COD fees are never line items, so on pure Cartbase data the filter is a
   no-op safety net. Newest-first sort by `createdAt` when present.
 
-### `<OrderTotals totals currencyCode items? codFeeLabel? />` — `order/order-totals`
+### `<OrderTotals totals currencyCode items? methodFeeLabel? />` — `order/order-totals`
 
 - **Purpose** — the money breakdown: Subtotal / Shipping (FREE badge at
   0) / COD fee / Discount (negated) / Tax / Total, all via `DualPrice`.
 - **Data seam** — `OrderTotalsSource` (the decorated cart satisfies it:
   `item_subtotal`, `shipping_subtotal`, `discount_total`, `tax_total`,
-  `total`, `cod_fee_total`, `cod_fee_label`); the summary snapshot adapts
+  `total`, `payment_method_fee_total`, `payment_method_fee_label`); the summary snapshot adapts
   via `orderTotalsFromSummary`. Row policy is the pure, unit-tested
-  `selectOrderTotalsRows`: native `cod_fee_total` wins over a legacy fee
+  `selectOrderTotalsRows`: native `payment_method_fee_total` wins over a legacy fee
   LINE; a legacy fee line's net is subtracted from the visible subtotal
-  (v2.3.1 production fix); COD label preference `codFeeLabel` prop →
-  server `cod_fee_label` → fee-line title → `labels.codFee`.
-- **Settings** — COD settings (`cod_fee_total`/`cod_fee_label`),
+  (v2.3.1 production fix); COD label preference `methodFeeLabel` prop →
+  server `payment_method_fee_label` → fee-line title → `labels.paymentMethodFee`.
+- **Settings** — COD settings (`payment_method_fee_total`/`payment_method_fee_label`),
   promotions (discount row).
 
 ### `<OrderAddressCard order />` — `order/order-address-card`
@@ -954,11 +952,13 @@ component also takes a `labels` prop pick.
 
 ### `<OrderPaymentCard providerId cardLast4? />` — `order/order-payment-card`
 
-- Payment method card; `resolvePaymentTitle` buckets the provider id via
-  `lib/payment-constants` (`pp_stripe` → card, `pp_system_default` → COD)
-  through the locale pack, falling back to `paymentInfoMap` then the raw
-  id. Payment internals never cross the Cartbase store surface — the id
-  arrives via props from checkout state.
+- Payment method card; `resolvePaymentTitle(providerId, titles,
+  methodName?)` — the method's merchant NAME wins verbatim when present
+  (the snapshot from session data); otherwise the processor id buckets
+  via `lib/payment-constants` (`pp_stripe` = card) through the locale
+  pack, falling back to `paymentInfoMap` then the raw id. Payment
+  internals never cross the Cartbase store surface — both arrive via
+  props from checkout state.
 
 ### `<OrderTimeline fulfillmentStatus? />` — `order/order-timeline`
 
@@ -975,8 +975,7 @@ component also takes a `labels` prop pick.
 
 ---
 
-## Family: common (`@cartbase/storefront/common/*`) — SHIPPED
-
+## Family: common (`@cartbase/storefront/common/*`)
 Shared storefront chrome, production-proven.
 
 ### `<LocalizedLink href … />` — `common/localized-link`
@@ -1028,8 +1027,7 @@ Shared storefront chrome, production-proven.
 
 ---
 
-## Family: reviews-ui (`@cartbase/storefront/reviews-ui`) — SHIPPED
-
+## Family: reviews-ui (`@cartbase/storefront/reviews-ui`)
 Verified-purchase review components, ported from a production storefront,
 over `api/reviews`. ONE barrel export seam: everything imports from
 `@cartbase/storefront/reviews-ui`. Endpoint truth:

package/template/app/docs/consent.md

@@ -1,4 +1,4 @@
-# Consent — Consent Mode v2 banner config
+# Consent
 
 The store's CMP configuration for the built-in Consent Mode v2 banner
 (consent-management card). Defaults are **always applied server-side**, so

package/template/app/docs/content.md

@@ -1,4 +1,4 @@
-# Content — pages + blogs
+# Content
 
 Shopify Storefront `Page` / `Article` shapes **verbatim** so storefront code
 ports 1:1. **PUBLISHED only** — drafts and deleted rows 404 (lib status

package/template/app/docs/customers.md

@@ -1,4 +1,4 @@
-# Customers — profile, addresses, documents
+# Customers
 
 The signed-in customer surface. Every endpoint here requires a **customer
 session**: `authorization: Bearer <supabase jwt>` (minted by the

package/template/app/docs/deploy.md

@@ -1,4 +1,4 @@
-# Deploy & hosting
+# Deploy
 
 Cartbase builds and hosts your storefront. You send the app's source files
 — one snapshot of the whole project — and Cartbase turns it into a

package/template/app/docs/gift-cards.md

@@ -1,4 +1,4 @@
-# Gift cards — tender on carts
+# Gift cards
 
 Gift-card redemption is a **payment tender** (`pp_giftcard`), never a
 discount: cart totals and VAT compute first and **never move**; applied

package/template/app/docs/integrations.md

@@ -1,4 +1,4 @@
-# Store integrations config — carriers, COD, tracking, lockers
+# Integrations
 
 Store-public integration configuration for render/checkout time
 (couriers-port + tracking-integrations cards). The payload is **composed**

package/template/app/docs/menus.md

@@ -1,4 +1,4 @@
-# Menus — backend-owned navigation
+# Menus
 
 Shopify Storefront `Menu` shape **verbatim** (content-navigation card).
 Items store a typed resource reference; `url` is **computed at read time**

package/template/app/docs/metaobjects.md

@@ -1,4 +1,4 @@
-# Metaobjects — merchant-defined content types
+# Metaobjects
 
 Merchant-defined structured content (size charts, brand profiles, FAQ
 blocks) served by TYPE + HANDLE (metaobjects card). **ACTIVE entries only —

package/template/app/docs/orders.md

@@ -1,4 +1,4 @@
-# Orders — customer reads + transfers
+# Orders
 
 The authenticated customer's order surface: list, detail (items +
 fulfillments with tracking + addresses) and order transfers. There is **no

package/template/app/docs/platform.md

@@ -1,4 +1,4 @@
-# Platform fingerprints — Cartbase detection
+# Platform fingerprints
 
 Every Cartbase-powered storefront emits a small, deliberate set of signals
 so platform-detection tools (Wappalyzer, BuiltWith) classify the site as

package/template/app/docs/products.md

@@ -1,4 +1,4 @@
-# Products & variants
+# Products
 
 The catalog read surface. The product object documented here is THE
 canonical shape every discovery endpoint reuses (search results, collection

package/template/app/docs/redirects.md

@@ -1,4 +1,4 @@
-# URL redirects — 404-path lookup
+# Redirects
 
 Exact-match redirect lookup (seo-listings card 21). **Hot-path rule: call
 this ONLY from the storefront's not-found handler** — never on regular page

package/template/app/docs/regions.md

@@ -1,4 +1,4 @@
-# Regions, currencies, locales
+# Regions
 
 Catalog-context primitives a storefront resolves at boot: regions feed the
 pricing context (`region_id` → region currency), currencies tell you what the

package/template/app/docs/reviews.md

@@ -1,4 +1,4 @@
-# Reviews — widget, token wizard, photo rewards
+# Reviews
 
 Verified-purchase reviews. Reviews exist **only** via a
 single-use, order-scoped, expiring **token** minted by the request scanner

package/template/app/docs/search.md

@@ -1,4 +1,4 @@
-# Search & related products
+# Search
 
 Configurable storefront search (search-discovery card) plus the PDP's
 related-products rail. Results are the SAME canonical product objects the

package/template/app/docs/subscriptions.md

@@ -1,4 +1,4 @@
-# Subscriptions — the customer portal
+# Subscriptions
 
 The "My subscriptions" surface (subscriptions-portal card): list, detail,
 schedule control, contract edits, cancel/reactivate and payment-method