@cartbase/storefront 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.2.0",
+  "version": "0.4.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/carts.ts

@@ -200,9 +200,11 @@ export interface Cart {
   credit_line_total: MajorUnitAmount
   credit_line_subtotal: MajorUnitAmount
   credit_line_tax_total: MajorUnitAmount
-  /** Native COD fee — non-zero only when a live pp_cod session exists AND the cod integration is enabled. Folded into `total`. */
-  cod_fee_total: MajorUnitAmount
-  cod_fee_label: string | null
+  /** The payment method fee — the chosen method's fee_amount (any method
+   * may carry one); non-zero only while a live method session is selected.
+   * Folded into `total`; its own totals row, never a line item. */
+  payment_method_fee_total: MajorUnitAmount
+  payment_method_fee_label: string | null
   // — gift-card tender decoration (totals NEVER move; see gift-cards.ts) —
   gift_cards: AppliedGiftCard[]
   /** Σ of applied-card coverage (= the pp_giftcard session amount). */

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()` →
@@ -47,11 +47,10 @@ export interface StoreShippingOption {
   name: string
   provider_id: string | null
   service_zone_id: string | null
-  shipping_option_type_id: string | null
   shipping_profile_id: string | null
   data: Record<string, unknown> | null
-  /** Embedded `shipping_option_types` row (label/description/code) or null. */
-  type: Record<string, unknown> | null
+  /** The option's display label (e.g. "Express") as `{ label }`, or null. */
+  type: { label: string } | null
   /** Flat price in the cart currency; null without `cart_id` or when no price row matches. */
   amount: MajorUnitAmount | null
   /** Always "flat" today — calculated-rate carriers are not wired yet. */
@@ -137,28 +136,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 +238,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 +264,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 +294,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 +347,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 +385,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 +403,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 +420,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/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/cart-drawer/labels-bg.ts

@@ -62,7 +62,7 @@ export const bulgarianCartDrawerLabels: CartDrawerLabels = {
 
   discount: "Отстъпка",
   tax: "ДДС",
-  codFee: "Такса наложен платеж",
+  paymentMethodFee: "Такса за плащане",
   giftCard: "Подаръчна карта",
   remainingToPay: "Остава за плащане",
 

package/src/cart-drawer/labels.ts

@@ -1,119 +1,119 @@
-/**
- * Cart drawer labels — default English copy.
- *
- * Every user-facing string in the cart drawer comes from a `CartDrawerLabels`
- * object. Stores override strings by passing a partial labels object to
- * `CartDrawerProvider`. English is the baseline; stores wanting Bulgarian,
- * German, etc. pass their own translations.
- *
- * Ported from `@1click/ui/src/cart-drawer/labels.ts` (v2.3.1). Cartbase
- * additions: the summary-breakdown row labels (`discount`, `tax`, `codFee`,
- * `giftCard`, `remainingToPay`) — the decorated cart carries
- * discount/tax/COD-fee/gift-card tender fields that the breakdown renders,
- * so the copy for those rows lives here too.
- */
-
-export type CartDrawerLabels = {
-  // Header
-  yourCart: string
-  item: string
-  items: string
-  closeCart: string
-
-  // Empty state
-  emptyCartTitle: string
-  emptyCartMessage: string
-  browseProducts: string
-
-  // Tiered progress
-  awayFromFreeShipping: string
-  allRewardsUnlocked: string
-
-  // Gift wrap / notes
-  addGiftWrap: string
-  giftNote: string
-  orderNote: string
-  giftNotePlaceholder: string
-  orderNotePlaceholder: string
-
-  // Rewards
-  estimatedRewardPoints: string
-
-  // Cross-sell
-  pairsWellWith: string
-  youllLoveThis: string
-  youMightAlsoLike: string
-  addToCart: string
-
-  // Summary / footer
-  subtotal: string
-  taxAndShipping: string
-  shipping: string
-  free: string
-  calculatedAtCheckout: string
-  total: string
-  secureCheckout: string
-  shippingAndTaxCalculatedAtCheckout: string
-
-  // Summary breakdown rows (Cartbase decorated-cart fields)
-  discount: string
-  tax: string
-  /** Fallback only — the server's `cod_fee_label` wins when present. */
-  codFee: string
-  /** Prefix for an applied gift-card row; rendered as `<giftCard> ••1234`. */
-  giftCard: string
-  /** Label for `gift_card_remainder` — what the remainder provider charges. */
-  remainingToPay: string
-
-  // Continue shopping
-  continueShopping: string
-
-  // A11y / buttons
-  remove: string
-}
-
-export const defaultCartDrawerLabels: CartDrawerLabels = {
-  yourCart: "Your cart",
-  item: "item",
-  items: "items",
-  closeCart: "Close cart",
-
-  emptyCartTitle: "Your cart is empty",
-  emptyCartMessage: "You haven't added any products yet.",
-  browseProducts: "Browse products",
-
-  awayFromFreeShipping: "away from free shipping",
-  allRewardsUnlocked: "All rewards unlocked",
-
-  addGiftWrap: "Add gift wrapping",
-  giftNote: "Gift note",
-  orderNote: "Order note",
-  giftNotePlaceholder: "Add a personal message...",
-  orderNotePlaceholder: "Special instructions for this order...",
-
-  estimatedRewardPoints: "Estimated reward points",
-
-  pairsWellWith: "Pairs well with",
-  youllLoveThis: "You'll love this",
-  youMightAlsoLike: "You might also like",
-  addToCart: "Add",
-
-  subtotal: "Subtotal",
-  taxAndShipping: "VAT included. Shipping calculated at checkout.",
-  shipping: "Shipping",
-  free: "FREE",
-  calculatedAtCheckout: "Calculated at checkout",
-  total: "Total",
-  secureCheckout: "Checkout",
-  shippingAndTaxCalculatedAtCheckout: "Shipping and tax calculated at checkout",
-
-  discount: "Discount",
-  tax: "VAT",
-  codFee: "Cash on delivery fee",
-  giftCard: "Gift card",
-  remainingToPay: "Remaining to pay",
-
-  continueShopping: "Continue shopping",
-
-  remove: "Remove",
-}
+/**
+ * Cart drawer labels — default English copy.
+ *
+ * Every user-facing string in the cart drawer comes from a `CartDrawerLabels`
+ * object. Stores override strings by passing a partial labels object to
+ * `CartDrawerProvider`. English is the baseline; stores wanting Bulgarian,
+ * German, etc. pass their own translations.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/labels.ts` (v2.3.1). Cartbase
+ * additions: the summary-breakdown row labels (`discount`, `tax`, `paymentMethodFee`,
+ * `giftCard`, `remainingToPay`) — the decorated cart carries
+ * discount/tax/COD-fee/gift-card tender fields that the breakdown renders,
+ * so the copy for those rows lives here too.
+ */
+
+export type CartDrawerLabels = {
+  // Header
+  yourCart: string
+  item: string
+  items: string
+  closeCart: string
+
+  // Empty state
+  emptyCartTitle: string
+  emptyCartMessage: string
+  browseProducts: string
+
+  // Tiered progress
+  awayFromFreeShipping: string
+  allRewardsUnlocked: string
+
+  // Gift wrap / notes
+  addGiftWrap: string
+  giftNote: string
+  orderNote: string
+  giftNotePlaceholder: string
+  orderNotePlaceholder: string
+
+  // Rewards
+  estimatedRewardPoints: string
+
+  // Cross-sell
+  pairsWellWith: string
+  youllLoveThis: string
+  youMightAlsoLike: string
+  addToCart: string
+
+  // Summary / footer
+  subtotal: string
+  taxAndShipping: string
+  shipping: string
+  free: string
+  calculatedAtCheckout: string
+  total: string
+  secureCheckout: string
+  shippingAndTaxCalculatedAtCheckout: string
+
+  // Summary breakdown rows (Cartbase decorated-cart fields)
+  discount: string
+  tax: string
+  /** Fallback only — the server's `payment_method_fee_label` wins when present. */
+  paymentMethodFee: string
+  /** Prefix for an applied gift-card row; rendered as `<giftCard> ••1234`. */
+  giftCard: string
+  /** Label for `gift_card_remainder` — what the remainder provider charges. */
+  remainingToPay: string
+
+  // Continue shopping
+  continueShopping: string
+
+  // A11y / buttons
+  remove: string
+}
+
+export const defaultCartDrawerLabels: CartDrawerLabels = {
+  yourCart: "Your cart",
+  item: "item",
+  items: "items",
+  closeCart: "Close cart",
+
+  emptyCartTitle: "Your cart is empty",
+  emptyCartMessage: "You haven't added any products yet.",
+  browseProducts: "Browse products",
+
+  awayFromFreeShipping: "away from free shipping",
+  allRewardsUnlocked: "All rewards unlocked",
+
+  addGiftWrap: "Add gift wrapping",
+  giftNote: "Gift note",
+  orderNote: "Order note",
+  giftNotePlaceholder: "Add a personal message...",
+  orderNotePlaceholder: "Special instructions for this order...",
+
+  estimatedRewardPoints: "Estimated reward points",
+
+  pairsWellWith: "Pairs well with",
+  youllLoveThis: "You'll love this",
+  youMightAlsoLike: "You might also like",
+  addToCart: "Add",
+
+  subtotal: "Subtotal",
+  taxAndShipping: "VAT included. Shipping calculated at checkout.",
+  shipping: "Shipping",
+  free: "FREE",
+  calculatedAtCheckout: "Calculated at checkout",
+  total: "Total",
+  secureCheckout: "Checkout",
+  shippingAndTaxCalculatedAtCheckout: "Shipping and tax calculated at checkout",
+
+  discount: "Discount",
+  tax: "VAT",
+  paymentMethodFee: "Payment method fee",
+  giftCard: "Gift card",
+  remainingToPay: "Remaining to pay",
+
+  continueShopping: "Continue shopping",
+
+  remove: "Remove",
+}