@cartbase/storefront 0.1.2 → 0.3.0

package/src/api/checkout.ts

@@ -6,10 +6,10 @@
  *  1. **Orchestrated (recommended)** — `prepareCheckout()` is the atomic
  *     Buy-click: ONE call writes address (+billing mirror), shipping method
  *     (+ carrier metadata), payment collection and the payment session at
- *     the FINAL amount (real Stripe PaymentIntent, or a plain row for
- *     pp_cod/pp_manual). Then `completeCart()` (see `./carts`). Amount
- *     drift/repair between the two: `syncPaymentAmount()` and
- *     `refreshPaymentIfTerminal()`.
+ *     the FINAL amount (real Stripe PaymentIntent for a processor, or a
+ *     provider-less row for a merchant method). Then `completeCart()`
+ *     (see `./carts`). Amount drift/repair between the two:
+ *     `syncPaymentAmount()` and `refreshPaymentIfTerminal()`.
  *
  *  2. **Manual (Medusa-style)** — `listShippingOptions()` →
  *     `addShippingMethod()` → `createPaymentCollection()` →
@@ -137,28 +137,54 @@ export interface ListPaymentProvidersQuery {
   cart_id?: string
 }
 
-/** Row of GET /api/store/payment-providers. */
-export interface StorePaymentProvider {
-  /** e.g. `pp_stripe`, `pp_cod`, `pp_manual`. `pp_giftcard` is internal and never listed. */
+/** A connected PROCESSOR entry of GET /api/store/payment-providers. */
+export interface StorePaymentProcessorEntry {
+  /** e.g. `pp_stripe`. `pp_giftcard` is internal and never listed. */
   id: string
   is_enabled: boolean
   created_at?: string
 }
 
+/** A merchant PAYMENT METHOD entry (pp_* kill, 20260811250000): methods
+ * stand alone — no provider id anywhere. Initiate sessions with
+ * `payment_method_id`; `kind === "cod"` marks the pre-created
+ * collection-on-delivery method (courier cash collection); `instructions`
+ * is the merchant's checkout note, rendered under the method. */
+export interface StorePaymentMethodEntry {
+  payment_method_id: string
+  name: string
+  kind: "manual" | "cod"
+  instructions: string | null
+  /** The method's fee (any method may carry one) — predict
+   * `payment_method_fee_total` from it before a session exists. */
+  fee_amount: number | null
+  fee_label: string | null
+}
+
+/** Row of GET /api/store/payment-providers — a processor or a method. */
+export type StorePaymentEntry = StorePaymentProcessorEntry | StorePaymentMethodEntry
+
+/** True when the entry is a merchant payment method (vs a processor). */
+export const isMethodEntry = (
+  entry: StorePaymentEntry
+): entry is StorePaymentMethodEntry => "payment_method_id" in entry
+
 export interface PaymentProviderListResponse extends ListEnvelope {
-  payment_providers: StorePaymentProvider[]
+  payment_providers: StorePaymentEntry[]
 }
 
 /**
- * List enabled payment providers (rule-filtered, display-ordered). → 200
- * list envelope; `count`/`limit` = full filtered list (no pagination).
- * Without `region_id`: the tenant's enabled providers
- * (`tenant_payment_providers` ∩ enabled catalog rows). With `region_id`:
- * providers linked to that region.
+ * List everything payable (rule-filtered, display-ordered): connected
+ * processors + every ENABLED merchant method. → 200 list envelope;
+ * `count`/`limit` = full filtered list (no pagination). An empty list is
+ * honest: a fresh store cannot take money until the merchant connects a
+ * processor, flips the COD switch, or creates a manual method
+ * (no-payment-method-by-default).
  * Auth: anon `x-client-id`.
- * Settings: provider enablement (admin integrations — enabling the COD or
- * Stripe integration provisions `pp_cod`/`pp_stripe`), checkout rules
- * (`target_type=payment_method`) + `checkout_method_order`.
+ * Settings: processor enablement (admin integrations), the Payments
+ * settings methods manager, checkout rules (`target_type=payment_method`,
+ * methods participate under their `payment_method_id`) +
+ * `checkout_method_order`.
  */
 export async function listPaymentProviders(
   client: StorefrontClient,
@@ -213,12 +239,18 @@ export async function createPaymentCollection(
 }
 
 export interface InitiatePaymentSessionInput {
-  /** `pp_stripe` | `pp_cod` | `pp_manual` — NEVER `pp_giftcard` (→ 400 `invalid_provider`). */
-  provider_id: string
+  /** A connected processor (`pp_stripe`) — NEVER `pp_giftcard` (→ 400
+   * `invalid_provider`). Exactly ONE of `provider_id` /
+   * `payment_method_id` (→ 400 `invalid_data` otherwise). */
+  provider_id?: string
+  /** A merchant payment method (`payment_method_id` from the listing's
+   * method entries) — the session lands with `provider_id` NULL and the
+   * method snapshot (`payment_method_id`/`_name`/`_kind`) in `data`. */
+  payment_method_id?: string
   /**
-   * Merged into the session's `data` blob. Provider-state keys
+   * Merged into the session's `data` blob. Server-owned keys
    * (`payment_intent_id`, `client_secret`, `status`, `stripe_customer_id`,
-   * `setup_future_usage`) are server-owned and stripped.
+   * `setup_future_usage`, and the method snapshot keys) are stripped.
    */
   data?: Record<string, unknown>
   /**
@@ -233,16 +265,19 @@ export interface InitiatePaymentSessionInput {
 
 export interface StorePaymentSession {
   id: string
-  provider_id: string
-  /** `collection.amount − gift_card_total` — the remainder this provider charges. */
+  /** The processor, or NULL for a merchant-method session (the method
+   * snapshot lives in `data`). */
+  provider_id: string | null
+  /** `collection.amount − gift_card_total` — the remainder this tender charges. */
   amount: MajorUnitAmount
   currency_code: string
   /** `pending` until authorized at complete. */
   status: string
   authorized_at: string | null
   /**
-   * Provider blob. For Stripe: `payment_intent_id`, `client_secret`
-   * (mount Stripe Elements with it), `status`. Plain row for pp_cod/pp_manual.
+   * Tender blob. For Stripe: `payment_intent_id`, `client_secret`
+   * (mount Stripe Elements with it), `status`. For methods: the snapshot
+   * `payment_method_id` / `payment_method_name` / `payment_method_kind`.
    */
   data: Record<string, unknown> | null
   [key: string]: unknown
@@ -260,10 +295,11 @@ export interface InitiatePaymentSessionResponse {
  * in place; terminal PIs self-heal by rotation.
  * Auth: anon `x-client-id`.
  * Errors: 404 `payment_collection_not_found`, 400 `invalid_provider`
- * (pp_giftcard) | `stripe_not_configured` | `validation_failed`.
+ * (pp_giftcard / unknown processor) | `invalid_data` (tender XOR violated,
+ * unknown/disabled method) | `stripe_not_configured` | `validation_failed`.
  * Settings: Stripe credentials (admin integrations); gift-card tender
- * shrinks the session amount; COD fee appears on the cart the moment a live
- * pp_cod session exists.
+ * shrinks the session amount; the COD fee appears on the cart the moment a
+ * live COD-method session exists.
  */
 export async function initiatePaymentSession(
   client: StorefrontClient,
@@ -312,28 +348,37 @@ export interface PrepareCheckoutInput {
    * switching carriers never leaks stale fields into the order.
    */
   carrier_metadata?: Record<string, unknown>
-  /** `pp_stripe` | `pp_cod` | `pp_manual` — never `pp_giftcard` (→ 400 `invalid_provider`). */
-  payment_provider: string
+  /** A connected processor (`pp_stripe`) — never `pp_giftcard`. Exactly ONE
+   * of `payment_provider` / `payment_method_id`. */
+  payment_provider?: string
+  /** A merchant payment method — the session lands provider-less with the
+   * method snapshot (pp_* kill, 20260811250000). */
+  payment_method_id?: string
 }
 
 /** Response of prepare-checkout (verbatim src/lib/checkout-orchestration/prepare.ts). */
 export interface PrepareCheckoutResult {
   cart_id: string
   payment_collection_id: string | null
-  /** Stripe Elements secret; null for pp_cod/pp_manual and zero-remainder carts. */
+  /** Stripe Elements secret; null for method sessions and zero-remainder carts. */
   client_secret: string | null
-  /** The provider whose session was minted; null when zero-remainder skipped the session. */
+  /** The processor whose session was minted; null for method sessions and
+   * when zero-remainder skipped the session. */
   provider_id: string | null
+  /** The method whose session was minted; null for processor sessions and
+   * when zero-remainder skipped the session. */
+  payment_method_id: string | null
 }
 
 /**
  * Atomic Buy-click step 1 of 2. ONE call writes address (+billing mirror) +
  * carrier metadata → shipping method (priced against the new destination) →
  * payment collection at the shipped total → payment session at the FINAL
- * amount. For pp_cod the native fee applies once the session exists, so
- * amounts are re-synced after it. Zero-remainder carts (gift cards cover
- * the total) skip the provider session — `client_secret`/`provider_id`
- * come back null and the cart completes on the gift session.
+ * amount. For the COD method the native fee applies once the session
+ * exists, so amounts are re-synced after it. Zero-remainder carts (gift
+ * cards cover the total) skip the tender session — `client_secret`,
+ * `provider_id` and `payment_method_id` come back null and the cart
+ * completes on the gift session.
  *
  * Fully compensated (wire-pattern): any failure rolls back session →
  * collection → shipping method → addresses/metadata to the pre-call
@@ -341,13 +386,14 @@ export interface PrepareCheckoutResult {
  * `checkout_error_logs` (step `prepare-checkout`).
  *
  * After prepare: Stripe → `stripe.confirmPayment(client_secret)` →
- * `completeCart()`; COD/manual → `completeCart()` directly.
+ * `completeCart()`; merchant methods → `completeCart()` directly.
  *
  * Auth: anon `x-client-id`.
  * Errors: 404 `cart_not_found` | `shipping_option_not_found`, 409
  * `cart_completed`, 400 `validation_failed` | `invalid_provider` |
- * `shipping_price_missing` | `stripe_not_configured`.
- * Settings: Stripe credentials, COD integration fee, gift-card tender,
+ * `invalid_data` (tender XOR violated) | `shipping_price_missing` |
+ * `stripe_not_configured`.
+ * Settings: Stripe credentials, the COD method's fee, gift-card tender,
  * checkout rules (enforced at listings + complete, not here).
  */
 export async function prepareCheckout(
@@ -358,10 +404,14 @@ export async function prepareCheckout(
   return client.post(`/api/store/carts/${cartId}/prepare-checkout`, input)
 }
 
-/** Body of POST /api/store/carts/:id/sync-payment-amount (`.strict()`). */
+/** Body of POST /api/store/carts/:id/sync-payment-amount (`.strict()`).
+ * At most ONE of the two — the requested tender; omit both to sync
+ * whatever session is pending. */
 export interface SyncPaymentAmountInput {
-  /** Rotate to this provider when it differs from the pending session's. */
+  /** Rotate to this processor when the pending session's tender differs. */
   provider_id?: string
+  /** Rotate to this merchant method when the pending session's tender differs. */
+  payment_method_id?: string
 }
 
 /** Response matrix (verbatim src/lib/checkout-orchestration/sync.ts). */
@@ -371,6 +421,7 @@ export interface SyncPaymentAmountResult {
   rotated?: boolean
   client_secret?: string | null
   provider_id?: string | null
+  payment_method_id?: string | null
   /** No-op reasons: `cart-completed` | `no_payment_collection` | `no_pending_session`. */
   reason?: string
 }

package/src/api/consent.ts

@@ -10,7 +10,7 @@
  * fetch — resolve the config server-side (RSC) and inline it. Render the
  * built-in banner only when `enabled && mode === "builtin"`. In `external`
  * mode the merchant's CMP owns the UI and must write the same `_1c_consent`
- * cookie (or call `setConsent()`) — all barter-side tag gating works off
+ * cookie (or call `setConsent()`) — all Cartbase-side tag gating works off
  * that one seam. Choices persist 12 months.
  */
 
@@ -45,7 +45,7 @@ export interface ConsentCopy {
  */
 export interface ConsentConfig {
   enabled: boolean
-  /** `builtin` = barter renders the banner; `external` = merchant CMP owns UI. */
+  /** `builtin` = Cartbase renders the banner; `external` = merchant CMP owns UI. */
   mode: "builtin" | "external"
   /** `modal` = blocking centered modal; `banner-bottom` = non-blocking bar. */
   layout: "modal" | "banner-bottom"

package/src/api/integrations.ts

@@ -7,9 +7,10 @@
  * src/lib/tracking/store-config-block.ts.
  *
  * The config payload is COMPOSED from an ordered block registry — each
- * block owns distinct top-level keys (`carriers`, `cod`, `tracking` today;
- * future blocks append). NOT wrapped in an envelope: the blocks ARE the
- * top-level keys.
+ * block owns distinct top-level keys (`carriers`, `tracking` today; future
+ * blocks append). NOT wrapped in an envelope: the blocks ARE the top-level
+ * keys. (The `cod` block died with the 'cod' integration, 2026-08-11 —
+ * method fees now ride the payment listing entries themselves.)
  *
  * SECURITY LAW: every block is an explicit allowlist — credentials
  * (carrier API keys, CAPI access_token, GA4 api_secret, Klaviyo
@@ -33,19 +34,6 @@ export interface PublicCarrierConfig {
   lockers_url?: string
 }
 
-/** COD checkout block — null unless enabled AND fee_amount > 0 (the exact
- * gate the totals engine applies, so the optimistic fee row never disagrees
- * with the charged total). */
-export interface PublicCodConfig {
-  enabled: true
-  /** EUR major units. */
-  fee_amount: number
-  fee_currency: "eur"
-  fee_label: string
-  /** Admin's checkout note, or null. */
-  description: string | null
-}
-
 /** Public tag config — only ENABLED providers with a public id appear.
  * Secrets can never appear here (explicit allowlist). */
 export interface StoreTrackingBlock {
@@ -64,7 +52,6 @@ export interface StoreIntegrationsConfig {
   /** Keyed by provider slug (e.g. `boxnow`, `econt`). Disabled carriers are
    * ABSENT, never `enabled: false`. */
   carriers: Record<string, PublicCarrierConfig>
-  cod: PublicCodConfig | null
   tracking: StoreTrackingBlock
 }
 

package/src/api/regions.ts

@@ -10,7 +10,7 @@ import type { StorefrontClient } from "./http"
 import type { IsoDateString, ListEnvelope, PaginationQuery } from "./types"
 
 /**
- * A store region (`barter_commerce.regions` row). NOTE: barter regions carry
+ * A store region (`barter_commerce.regions` row). NOTE: Cartbase regions carry
  * NO embedded `countries` array on the store surface (divergence from
  * Medusa's Store API — tax scoping is by `tax_regions` server-side).
  */

package/src/cart-drawer/context.tsx

@@ -43,7 +43,7 @@ import { defaultCartDrawerLabels, type CartDrawerLabels } from "./labels"
  * snapshot never updated past the failed mutation. See
  * https://react.dev/reference/react/useOptimistic.
  *
- * Ported from `@1click/ui/src/cart-drawer/context.tsx` (v2.3.1). Barter
+ * Ported from `@1click/ui/src/cart-drawer/context.tsx` (v2.3.1). Cartbase
  * data seam: the Medusa server actions (`../data/cart`) are replaced by
  * `@cartbase/storefront/api/carts` calls made through a `StorefrontClient`
  * passed to the provider. Every mutation returns the FULL decorated cart
@@ -54,7 +54,7 @@ import { defaultCartDrawerLabels, type CartDrawerLabels } from "./labels"
  * is unit-agnostic and unchanged).
  *
  * The source's `logEvent` ops funnel (backend error log endpoint) has no
- * barter SDK equivalent yet — the same single-funnel discipline is kept
+ * Cartbase SDK equivalent yet — the same single-funnel discipline is kept
  * via the `onOptimisticError` prop: every failed optimistic mutation
  * (every PDP add, cross-sell add, drawer remove, drawer quantity change)
  * flows through it with per-action context. Wire it to the store's ops
@@ -158,7 +158,7 @@ type CartDrawerContextValue = {
     quantity?: number,
     display?: OptimisticAddDisplay
   ) => Promise<boolean>
-  /** POST line-items/:id with `{quantity}` — barter contract: 0 deletes. */
+  /** POST line-items/:id with `{quantity}` — Cartbase contract: 0 deletes. */
   updateQuantity: (lineId: string, quantity: number) => Promise<boolean>
   removeItem: (lineId: string) => Promise<boolean>
   /** Re-read the decorated cart (totals/gift-card tender are live per read). */
@@ -503,7 +503,7 @@ export function CartDrawerProvider({
       return runOptimistic(
         { type: "update_quantity", lineId, quantity },
         async () => {
-          // Barter contract: body is `{quantity}` only (metadata is NOT
+          // Cartbase contract: body is `{quantity}` only (metadata is NOT
           // accepted on update, only on add); quantity 0 deletes the line.
           const res = await sdkUpdateLineItem(client, id, lineId, { quantity })
           confirm(res.cart)

package/src/cart-drawer/cross-sell-carousel.tsx

@@ -14,7 +14,7 @@ import { useCartDrawer } from "./context"
  * cross-sell zone below the line items on desktop.
  *
  * Ported from `@1click/ui/src/cart-drawer/cross-sell-carousel.tsx` (v2.3.1).
- * Barter data seam: same as the sidebar — feed from
+ * Cartbase data seam: same as the sidebar — feed from
  * `@cartbase/storefront/api/products` `listProducts` or `api/search`
  * `listRelatedProducts` via `toCrossSellProduct`
  * (`./cross-sell-sidebar`; the card shapes are identical), wire `onAdd`

package/src/cart-drawer/cross-sell-sidebar.tsx

@@ -12,7 +12,7 @@ import { useCartDrawer } from "./context"
  * drawer's left sidebar.
  *
  * Ported from `@1click/ui/src/cart-drawer/cross-sell-sidebar.tsx` (v2.3.1).
- * Barter data seam: source stores fed this from Medusa product fetches —
+ * Cartbase data seam: source stores fed this from Medusa product fetches —
  * feed it from `@cartbase/storefront/api/products` `listProducts` (curated
  * collection/tag) or `@cartbase/storefront/api/search` `listRelatedProducts`
  * (anchor-product complements), mapped through `toCrossSellProduct` below.

package/src/cart-drawer/header.tsx

@@ -6,7 +6,7 @@ import { useCartDrawer } from "./context"
 /**
  * Cart drawer header — store title, item count badge, close button.
  *
- * Ported from `@1click/ui/src/cart-drawer/header.tsx` (v2.3.1). Barter
+ * Ported from `@1click/ui/src/cart-drawer/header.tsx` (v2.3.1). Cartbase
  * adjustment: the badge counts PRODUCT lines via the shared
  * `productItemCount` predicate (the source summed all lines) so a
  * backend-injected COD-fee line can never inflate the item count —

package/src/cart-drawer/item/index.tsx

@@ -15,13 +15,13 @@ import { CartItemVariant } from "./variant"
  * CartItem — a single cart line row: thumbnail, title, variant, quantity
  * stepper, price (with dual-currency + optional strikethrough), remove button.
  *
- * Ported from `@1click/ui/src/cart-drawer/item/index.tsx` (v2.3.1). Barter
+ * Ported from `@1click/ui/src/cart-drawer/item/index.tsx` (v2.3.1). Cartbase
  * data seam: `item` is the SDK's decorated `CartLineItem`
  * (`@cartbase/storefront/api/carts`) — per-line `total`/`original_total` are
  * server-computed EUR major units. Remove goes through the provider's
  * SDK-wired `removeItem` (DELETE line-items/:id, returns the full decorated
  * cart) instead of the Medusa server action. The variant row renders the
- * line's flat `variant_title` — barter cart lines carry the variant title
+ * line's flat `variant_title` — Cartbase cart lines carry the variant title
  * string, not an embedded variant object.
  *
  * `children` is rendered below the main row — intended for per-item upsell

package/src/cart-drawer/item/quantity.tsx

@@ -15,9 +15,9 @@ import { useCartDrawer } from "../context"
  * automatically (confirmed snapshot unchanged).
  *
  * Ported from `@1click/ui/src/cart-drawer/item/quantity.tsx` (v2.3.1).
- * Barter data seam: `updateQuantity` wraps
+ * Cartbase data seam: `updateQuantity` wraps
  * `POST /api/store/carts/:id/line-items/:lineId` with body `{quantity}` —
- * the barter contract accepts ONLY `quantity` (no metadata on update) and
+ * the Cartbase contract accepts ONLY `quantity` (no metadata on update) and
  * quantity 0 deletes the line (unreachable here: the stepper floor is 1;
  * removal is the dedicated remove button).
  */

package/src/cart-drawer/item/upsell.tsx

@@ -12,12 +12,12 @@ import { useCartDrawer } from "../context"
  * onAdd handler.
  *
  * Ported from `@1click/ui/src/cart-drawer/item/upsell.tsx` (v2.3.1).
- * Barter data seam: source stores fed this from Medusa product fetches —
+ * Cartbase data seam: source stores fed this from Medusa product fetches —
  * feed it from `@cartbase/storefront/api/search` `listRelatedProducts`
  * (per-anchor complements: manual admin picks + deterministic fallback)
  * mapped via `toCrossSellProduct` (`../cross-sell-sidebar`). `variantId`
  * was added to `UpsellProduct` and to the `onAdd` signature so the handler
- * can call the provider's `addItem(variantId)` directly — barter carts add
+ * can call the provider's `addItem(variantId)` directly — Cartbase carts add
  * by variant id, not product id. Prices are EUR major units.
  */
 
@@ -28,7 +28,7 @@ export type UpsellProduct = {
   thumbnail: string | null
   price: number
   currencyCode: string
-  /** Variant to add (barter add-to-cart is by variant id). */
+  /** Variant to add (Cartbase add-to-cart is by variant id). */
   variantId?: string
 }
 

package/src/cart-drawer/item/variant.tsx

@@ -5,8 +5,8 @@
  * under the product title in a cart line.
  *
  * Ported from `@1click/ui/src/cart-drawer/item/variant.tsx` (v2.3.1).
- * Barter data seam: the source rendered `variant.options[].value` from an
- * embedded Medusa variant object; barter cart lines carry the flat
+ * Cartbase data seam: the source rendered `variant.options[].value` from an
+ * embedded Medusa variant object; Cartbase cart lines carry the flat
  * `variant_title` string (SDK `CartLineItem.variant_title`) instead, so
  * that is the primary prop. Callers that fetched the full variant (PDP
  * context) can still pass structural `options` and get the original

package/src/cart-drawer/labels-bg.ts

@@ -6,7 +6,7 @@ import type { CartDrawerLabels } from "./labels"
  * Ships alongside the English defaults so Bulgarian stores get the
  * translated copy with a single import instead of hand-writing every
  * string. Strings match the originals from mindpages-storefront, plus the
- * barter summary-breakdown row additions.
+ * Cartbase summary-breakdown row additions.
  *
  * Usage in a store's layout:
  *
@@ -62,7 +62,7 @@ export const bulgarianCartDrawerLabels: CartDrawerLabels = {
 
   discount: "Отстъпка",
   tax: "ДДС",
-  codFee: "Такса наложен платеж",
+  paymentMethodFee: "Такса за плащане",
   giftCard: "Подаръчна карта",
   remainingToPay: "Остава за плащане",