@cartbase/storefront 0.2.0 → 0.3.0

package/src/checkout/use-checkout-orchestration.ts

@@ -23,9 +23,11 @@ import {
   prepareCheckout,
   refreshPaymentIfTerminal as refreshPaymentIfTerminalApi,
   syncPaymentAmount as syncPaymentAmountApi,
+  isMethodEntry,
   type PrepareCheckoutInput,
   type RefreshPaymentResult,
-  type StorePaymentProvider,
+  type StorePaymentEntry,
+  type StorePaymentMethodEntry,
   type StoreShippingOption,
   type SyncPaymentAmountResult,
 } from "../api/checkout"
@@ -35,8 +37,7 @@ import {
   type StoreCustomer,
   type UpdateCustomerInput,
 } from "../api/customers"
-import type { PublicCodConfig } from "../api/integrations"
-import { isManual, isStripeLike } from "../lib/payment-constants"
+import { isStripeLike } from "../lib/payment-constants"
 import compareAddresses from "./compare-addresses"
 import { translateAddressError } from "./address-error-copy"
 import { translatePaymentError } from "./payment-error-copy"
@@ -70,13 +71,14 @@ import type { BoxNowLocker } from "../api/integrations"
  *    entirely — the cart completes on the gift session alone. The @1click
  *    original threw on a missing client_secret; Cartbase treats
  *    null-secret + null-provider as the documented gift path.
- *  - COD fee: Cartbase's fee is CART-LEVEL decoration (`cod_fee_total` /
- *    `cod_fee_label`, folded into `cart.total` while a live pp_cod session
- *    exists) — not a metadata-flagged line item. The optimistic-fee math
- *    reads `cart.cod_fee_total`; the prediction comes from the
- *    integrations config `cod` block (never hardcoded).
- *  - Provider ids: `pp_stripe` / `pp_cod` / `pp_manual` exactly
- *    (lib/payment-constants + the pp_cod resolution below).
+ *  - The payment method fee: CART-LEVEL decoration
+ *    (`payment_method_fee_total` / `payment_method_fee_label`, folded into
+ *    `cart.total` while a live method session exists) — not a
+ *    metadata-flagged line item. ANY method may carry a fee; the optimistic
+ *    prediction reads `fee_amount` off the selected LISTING entry (the
+ *    integrations `cod` block died 2026-08-11).
+ *  - Processor ids: `pp_stripe` exactly (lib/payment-constants); merchant
+ *    methods have no provider id — sessions ride `payment_method_id`.
  *  - `logCheckoutError`/`logEvent` (Supabase-side sinks in @1click) have no
  *    Cartbase store endpoint — the hook takes an optional `logError` callback
  *    so stores wire their own sink; all production log points are kept.
@@ -93,11 +95,10 @@ import type { BoxNowLocker } from "../api/integrations"
  *     class of fork-rot bug structurally impossible.
  */
 
-/** COD checkout config — the integrations `cod` block (api/integrations). */
-export type CheckoutCodConfig = PublicCodConfig | null
-
-/** Minimal provider row the hook accepts (SDK DTO or bare `{id}`). */
-export type PaymentProviderLike = StorePaymentProvider | { id: string }
+/** A payable entry the hook accepts: a processor row (`{id}`) or a
+ * merchant-method row (`{payment_method_id, name, kind}`) — the two wire
+ * shapes of GET /api/store/payment-providers since the pp_* kill. */
+export type PaymentProviderLike = StorePaymentEntry | { id: string }
 
 export type CheckoutLogError = (
   errorType: string,
@@ -128,13 +129,6 @@ export type UseCheckoutOrchestrationOptions = {
     methods: PaymentProviderLike[] | null,
     selectedShippingOption: StoreShippingOption | null
   ) => PaymentProviderLike[] | null
-  /**
-   * Optional cash-on-delivery configuration — pass the integrations config
-   * `cod` block (`getIntegrationsConfig(client).cod`). When present, the
-   * hook paints `optimisticCodFee` on tab-toggle so the totals row updates
-   * before the server-side fee (applied at prepare) arrives.
-   */
-  codConfig?: CheckoutCodConfig
   /**
    * Order-confirmed redirect path template (`{id}` → order.id,
    * `{country}` → shipping country). Falls back to the CheckoutProvider
@@ -194,12 +188,18 @@ const REQUIRED_ADDRESS_FIELDS = [
  */
 const ADDRESS_AUTO_SAVE_DEBOUNCE_MS = 600
 
-/** Cartbase COD provider resolution: `pp_cod` exactly, with the Medusa-era
- * `pp_system_default*` prefix kept as fallback (lib/payment-constants),
- * and `pp_manual` accepted as the offline tab when no true COD provider
- * is enabled. Fee prediction only ever applies via `codConfig` (pp_cod). */
-const isCodLikeId = (id?: string): boolean =>
-  !!id && (id === "pp_cod" || isManual(id))
+/** The offline tab's tender: a merchant METHOD entry (pp_* kill). The COD
+ * method (kind 'cod') wins; any manual method serves as the offline tab
+ * when no COD switch is on. The entry carries its own fee for prediction. */
+const findOfflineMethod = (
+  entries: PaymentProviderLike[] | null | undefined
+): StorePaymentMethodEntry | null => {
+  const methods = (entries ?? []).filter(
+    (m): m is Extract<PaymentProviderLike, { payment_method_id: string }> =>
+      "payment_method_id" in m && isMethodEntry(m as StorePaymentEntry)
+  )
+  return methods.find((m) => m.kind === "cod") ?? methods[0] ?? null
+}
 
 /**
  * Snapshot the address-relevant subset of formData. Used to skip
@@ -250,7 +250,6 @@ export function useCheckoutOrchestration({
   countryCode = "",
   countries,
   paymentMethodFilter,
-  codConfig,
   orderConfirmedPath: orderConfirmedPathProp,
   onOrderPlaced,
   resolveTrackingMetadata,
@@ -794,20 +793,20 @@ export function useCheckoutOrchestration({
   // ── Payment ─────────────────────────────────────────────────────────
   const [paymentError, setPaymentError] = useState<string | null>(null)
 
-  const hasCard = !!effectiveAvailablePaymentMethods?.some((m) =>
-    isStripeLike(m.id)
-  )
-  const hasCod = !!effectiveAvailablePaymentMethods?.some(
-    (m) => isCodLikeId(m.id) || m.id === "pp_manual"
+  const hasCard = !!effectiveAvailablePaymentMethods?.some(
+    (m) => "id" in m && isStripeLike(m.id)
   )
-  const cardId = effectiveAvailablePaymentMethods?.find((m) =>
-    isStripeLike(m.id)
+  const cardId = (
+    effectiveAvailablePaymentMethods?.find(
+      (m) => "id" in m && isStripeLike(m.id)
+    ) as { id: string } | undefined
   )?.id
-  // Prefer the true COD provider; fall back to pp_manual so single-
-  // provider stores still get an offline tab.
-  const codId =
-    effectiveAvailablePaymentMethods?.find((m) => isCodLikeId(m.id))?.id ??
-    effectiveAvailablePaymentMethods?.find((m) => m.id === "pp_manual")?.id
+  // The offline tab = a merchant METHOD (the COD switch, else the first
+  // manual method) — sessions initiate by payment_method_id, provider NULL.
+  const offlineMethod = findOfflineMethod(effectiveAvailablePaymentMethods)
+  const hasCod = !!offlineMethod
+  const codMethodId = offlineMethod?.payment_method_id
+  const offlineIsCodKind = offlineMethod?.kind === "cod"
 
   // Default tab: card when available, else COD. The eager-session model
   // used to seed from the cart's pending session provider; in the
@@ -816,14 +815,15 @@ export function useCheckoutOrchestration({
     hasCard ? "card" : "cod"
   )
 
-  // Optimistic COD-fee state. Painted instantly on tab toggle so the
-  // totals row shows the predicted fee BEFORE the server applies the
-  // native fee (Cartbase: at prepare, when the pp_cod session is minted).
+  // Optimistic method-fee state. Painted instantly on tab toggle so the
+  // totals row shows the predicted fee BEFORE the server applies it (at
+  // prepare, when the method session is minted). Any method may carry a
+  // fee — the prediction reads the selected entry's own fee_amount.
   // Three values:
   //   - null         → no prediction; render whatever the cart says
-  //   - 0            → predict no fee (toggling away from COD)
-  //   - positive     → predict the fee at this amount (toggling to COD)
-  const [optimisticCodFee, setOptimisticCodFee] = useState<number | null>(
+  //   - 0            → predict no fee (toggling to a fee-less tender)
+  //   - positive     → predict the fee at this amount
+  const [optimisticMethodFee, setOptimisticMethodFee] = useState<number | null>(
     null
   )
 
@@ -840,30 +840,28 @@ export function useCheckoutOrchestration({
       setPaymentTab(tab)
       setPaymentError(null)
 
-      // Optimistic COD-fee prediction so the totals row updates instantly.
-      // Currency must match the configured fee currency or the backend
-      // skips the fee at apply time, so we mirror that gate here. The
-      // prediction ONLY applies when the offline tab is the true pp_cod
-      // provider — pp_manual carries no fee.
-      if (codConfig) {
-        const codCurrencyMatches =
-          codConfig.fee_currency.toLowerCase() ===
-          (cart.currency_code || "").toLowerCase()
-        if (tab === "cod" && codCurrencyMatches && codId === "pp_cod") {
-          setOptimisticCodFee(codConfig.fee_amount)
-        } else {
-          setOptimisticCodFee(0)
-        }
+      // Optimistic fee prediction so the totals row updates instantly —
+      // the selected METHOD entry carries its own fee; processors charge
+      // none. Mirrors the server exactly (resolveMethodFee reads the same
+      // row the listing serialized).
+      if (offlineMethod) {
+        const fee = Number(offlineMethod.fee_amount ?? 0)
+        setOptimisticMethodFee(tab === "cod" && fee > 0 ? fee : 0)
       }
 
-      const provider = tab === "card" ? cardId : codId
-      if (provider) {
-        void syncPaymentAmountApi(client, cart.id, {
-          provider_id: provider,
-        }).catch(() => {})
+      const tender =
+        tab === "card"
+          ? cardId
+            ? { provider_id: cardId }
+            : null
+          : codMethodId
+            ? { payment_method_id: codMethodId }
+            : null
+      if (tender) {
+        void syncPaymentAmountApi(client, cart.id, tender).catch(() => {})
       }
     },
-    [cart.currency_code, cart.id, client, codConfig, cardId, codId]
+    [cart.id, client, cardId, codMethodId, offlineMethod]
   )
 
   // Shipping selection is client state only. No addShippingMethod call,
@@ -1088,26 +1086,26 @@ export function useCheckoutOrchestration({
   //   start = cart.total (covers subtotal + tax + any already-written
   //                       shipping/fee)
   //   if optimisticShippingCost set: replace cart.shipping_total with it
-  //   if optimisticCodFee set: replace cart.cod_fee_total with it
-  //     (Cartbase: the COD fee is CART-LEVEL decoration folded into total,
-  //      not a fee line item)
+  //   if optimisticMethodFee set: replace cart.payment_method_fee_total
+  //     with it (the fee is CART-LEVEL decoration folded into total,
+  //     not a fee line item)
   // When nothing is optimistic, this collapses to cart.total.
   const optimisticTotal = useMemo(() => {
-    const realCodFeeAmount = cart?.cod_fee_total ?? 0
+    const realMethodFeeAmount = cart?.payment_method_fee_total ?? 0
     let total = cart?.total ?? 0
     if (optimisticShippingCost !== null) {
       total = total - (cart?.shipping_total ?? 0) + optimisticShippingCost
     }
-    if (optimisticCodFee !== null && optimisticCodFee !== undefined) {
-      total = total - realCodFeeAmount + optimisticCodFee
+    if (optimisticMethodFee !== null && optimisticMethodFee !== undefined) {
+      total = total - realMethodFeeAmount + optimisticMethodFee
     }
     return total
   }, [
     cart?.total,
     cart?.shipping_total,
-    cart?.cod_fee_total,
+    cart?.payment_method_fee_total,
     optimisticShippingCost,
-    optimisticCodFee,
+    optimisticMethodFee,
   ])
 
   // ── Optimistic total in cents (for Stripe Elements deferred-intent) ─
@@ -1157,9 +1155,18 @@ export function useCheckoutOrchestration({
       if (!shippingMethodId) {
         throw new Error("No shipping method selected")
       }
-      const paymentProvider = paymentTab === "card" ? cardId : codId
-      if (!paymentProvider) {
-        throw new Error("No payment provider available")
+      // The tender: card tab → the processor; offline tab → the merchant
+      // method (provider-less session, pp_* kill).
+      const tender =
+        paymentTab === "card"
+          ? cardId
+            ? { payment_provider: cardId }
+            : null
+          : codMethodId
+            ? { payment_method_id: codMethodId }
+            : null
+      if (!tender) {
+        throw new Error("No payment method available")
       }
 
       return {
@@ -1175,7 +1182,7 @@ export function useCheckoutOrchestration({
         },
         shipping_method_id: shippingMethodId,
         carrier_metadata: carrierMetadata,
-        payment_provider: paymentProvider,
+        ...tender,
       }
     }, [
       formData,
@@ -1184,7 +1191,7 @@ export function useCheckoutOrchestration({
       selectedBoxnowLocker,
       paymentTab,
       cardId,
-      codId,
+      codMethodId,
     ])
 
   // ── Buy click ───────────────────────────────────────────────────────
@@ -1229,7 +1236,7 @@ export function useCheckoutOrchestration({
         cart_id: cart.id,
         paymentTab,
         cardId,
-        codId,
+        codMethodId,
         selectedShippingMethod,
         selectedEcontOffice: selectedEcontOffice
           ? { code: selectedEcontOffice.code, name: selectedEcontOffice.name }
@@ -1268,7 +1275,8 @@ export function useCheckoutOrchestration({
       // eslint-disable-next-line no-console
       console.log("[buy-click] PAYLOAD →", payload)
       logError?.("other", "buy_click_payload", {
-        provider_id: payload.payment_provider,
+        provider_id: payload.payment_provider ?? null,
+        payment_method_id: payload.payment_method_id ?? null,
         shipping_method_id: payload.shipping_method_id,
         carrier_metadata_keys: Object.keys(payload.carrier_metadata ?? {}),
         country_code: payload.shipping_address.country_code,
@@ -1420,7 +1428,7 @@ export function useCheckoutOrchestration({
       cart.id,
       paymentTab,
       cardId,
-      codId,
+      codMethodId,
       selectedShippingMethod,
       selectedEcontOffice,
       selectedBoxnowLocker,
@@ -1478,12 +1486,14 @@ export function useCheckoutOrchestration({
     hasCard,
     hasCod,
     cardId,
-    codId,
+    /** The offline tab's method (the COD switch or a manual method). */
+    codMethodId,
+    offlineMethod,
     paymentError,
     setPaymentError,
     deliveryReady,
-    optimisticCodFee,
-    setOptimisticCodFee,
+    optimisticMethodFee,
+    setOptimisticMethodFee,
     handlePaymentTab,
     handlePaymentElementChange,
 

package/src/lib/payment-constants.ts

@@ -1,66 +1,53 @@
-/**
- * Payment provider helpers — identifier sniffing for store payment sessions.
- *
- * Ported from `@1click/ui/src/lib/payment-constants.ts` (v2.3.1) and
- * translated to the Cartbase provider-id seam (code truth:
- * `src/lib/stripe/providers.ts isStripeProviderId` matches exactly
- * `"pp_stripe" | "stripe"`; the accepted checkout ids are
- * `pp_stripe | pp_cod | pp_manual` — docs/contracts/store-api.md).
- * `pp_system_default` is the RETIRED legacy manual twin (payments-registry
- * card): no longer provisioned, hidden from merchants, kept here only so
- * historic orders keep rendering. The Medusa-era prefixes (`pp_stripe_*`,
- * `pp_medusa-*`) are kept as fallbacks so components ported later keep
- * working against either wire.
- *
- * Intentionally ships NO icons — stores render their own icons via their
- * own icon set. The library stays free of icon-kit imports at this layer.
- */
-
-/**
- * True if the provider id is a Stripe-backed card payment provider.
- * Cartbase's canonical ids first (`pp_stripe` / `stripe`), then the
- * Medusa-era prefixes (`pp_stripe_*`, `pp_medusa-*`).
- */
-export const isStripeLike = (providerId?: string): boolean => {
-  return Boolean(
-    providerId &&
-      (providerId === "pp_stripe" ||
-        providerId === "stripe" ||
-        providerId.startsWith("pp_stripe_") ||
-        providerId.startsWith("pp_medusa-"))
-  )
-}
-
-/** True if the provider id is PayPal. */
-export const isPaypal = (providerId?: string): boolean => {
-  return Boolean(providerId?.startsWith("pp_paypal"))
-}
-
-/**
- * True if the provider id is an offline/manual provider: `pp_manual` (the
- * id checkout actually charges — payments-registry card) with the retired
- * `pp_system_default*` legacy twin as fallback for historic orders. COD is
- * NOT manual — `pp_cod` has its own id and its own fee flow.
- */
-export const isManual = (providerId?: string): boolean => {
-  return Boolean(
-    providerId &&
-      (providerId === "pp_manual" || providerId.startsWith("pp_system_default"))
-  )
-}
-
-export const paymentInfoMap: Record<
-  string,
-  { title: string; icon: React.JSX.Element | null }
-> = {
-  pp_stripe: { title: "Credit / debit card", icon: null },
-  pp_stripe_stripe: { title: "Credit / debit card", icon: null },
-  "pp_medusa-payments_default": { title: "Credit / debit card", icon: null },
-  "pp_stripe-ideal_stripe": { title: "iDeal", icon: null },
-  "pp_stripe-bancontact_stripe": { title: "Bancontact", icon: null },
-  pp_paypal_paypal: { title: "PayPal", icon: null },
-  pp_cod: { title: "Cash on delivery", icon: null },
-  pp_manual: { title: "Manual payment", icon: null },
-  // Retired legacy manual twin — historic orders only (payments-registry).
-  pp_system_default: { title: "Manual payment", icon: null },
-}
+/**
+ * Payment tender helpers — identifier sniffing for store payment sessions.
+ *
+ * The Cartbase wire has exactly TWO tender shapes since the pp_* kill
+ * (20260811250000, no-payment-method-by-default card):
+ *
+ *   - a PROCESSOR the merchant connected — `provider_id` (`pp_stripe`
+ *     today; PayPal etc. as integrations land);
+ *   - a merchant-operated PAYMENT METHOD — `payment_method_id` + `name` +
+ *     `kind` (`manual` for Bank transfer / Pay in store, `cod` for the
+ *     collection-on-delivery switch). Its session carries `provider_id`
+ *     NULL; the merchant's NAME is the display everywhere.
+ *
+ * The dead ids (`pp_cod`, `pp_manual`, `pp_system_default`) are gone from
+ * the wire and from this module. The Medusa-era Stripe prefixes
+ * (`pp_stripe_*`, `pp_medusa-*`) are kept as fallbacks so components
+ * ported later keep working against either wire.
+ *
+ * Intentionally ships NO icons — stores render their own icons via their
+ * own icon set. The library stays free of icon-kit imports at this layer.
+ */
+
+/**
+ * True if the provider id is a Stripe-backed card payment provider.
+ * Cartbase's canonical ids first (`pp_stripe` / `stripe`), then the
+ * Medusa-era prefixes (`pp_stripe_*`, `pp_medusa-*`).
+ */
+export const isStripeLike = (providerId?: string | null): boolean => {
+  return Boolean(
+    providerId &&
+      (providerId === "pp_stripe" ||
+        providerId === "stripe" ||
+        providerId.startsWith("pp_stripe_") ||
+        providerId.startsWith("pp_medusa-"))
+  )
+}
+
+/** True if the provider id is PayPal. */
+export const isPaypal = (providerId?: string | null): boolean => {
+  return Boolean(providerId?.startsWith("pp_paypal"))
+}
+
+export const paymentInfoMap: Record<
+  string,
+  { title: string; icon: React.JSX.Element | null }
+> = {
+  pp_stripe: { title: "Credit / debit card", icon: null },
+  pp_stripe_stripe: { title: "Credit / debit card", icon: null },
+  "pp_medusa-payments_default": { title: "Credit / debit card", icon: null },
+  "pp_stripe-ideal_stripe": { title: "iDeal", icon: null },
+  "pp_stripe-bancontact_stripe": { title: "Bancontact", icon: null },
+  pp_paypal_paypal: { title: "PayPal", icon: null },
+}

package/src/order/labels-bg.ts

@@ -1,39 +1,39 @@
-import type { OrderLabels } from "./labels"
-
-/**
- * Bulgarian order labels — the Alenika/mindpages production copy, ported
- * from `@1click/ui/src/order/labels-bg.ts` (v2.3.1) + `tracking`.
- */
-export const bulgarianOrderLabels: OrderLabels = {
-  orderConfirmed: "Поръчката е потвърдена",
-  confirmationSent: "Изпратихме потвърждение на",
-  orderNumber: "Поръчка",
-  orderDate: "Дата",
-  summary: "Обобщение на поръчката",
-  subtotal: "Междинна сума",
-  shipping: "Доставка",
-  discount: "Отстъпка",
-  tax: "ДДС",
-  total: "Общо",
-  codFee: "Такса наложен платеж",
-  contactInfo: "Данни за контакт",
-  delivery: "Доставка",
-  paymentMethod: "Метод на плащане",
-  paymentMethodTitles: {
-    card: "Кредитна / дебитна карта",
-    cod: "Наложен платеж",
-    manual: "Друг начин на плащане",
-    paypal: "PayPal",
-  },
-  needHelp: "Имате нужда от помощ?",
-  contactUs: "Свържете се с нас",
-  returnsExchanges: "Връщания и замени",
-  orderPlaced: "Приета",
-  processing: "Обработка",
-  shipped: "Изпратена",
-  delivered: "Доставена",
-  free: "БЕЗПЛАТНА",
-  continueShopping: "Продължи пазаруването",
-  qty: "бр.",
-  tracking: "Проследяване",
-}
+import type { OrderLabels } from "./labels"
+
+/**
+ * Bulgarian order labels — the Alenika/mindpages production copy, ported
+ * from `@1click/ui/src/order/labels-bg.ts` (v2.3.1) + `tracking`.
+ */
+export const bulgarianOrderLabels: OrderLabels = {
+  orderConfirmed: "Поръчката е потвърдена",
+  confirmationSent: "Изпратихме потвърждение на",
+  orderNumber: "Поръчка",
+  orderDate: "Дата",
+  summary: "Обобщение на поръчката",
+  subtotal: "Междинна сума",
+  shipping: "Доставка",
+  discount: "Отстъпка",
+  tax: "ДДС",
+  total: "Общо",
+  paymentMethodFee: "Такса за плащане",
+  contactInfo: "Данни за контакт",
+  delivery: "Доставка",
+  paymentMethod: "Метод на плащане",
+  paymentMethodTitles: {
+    card: "Кредитна / дебитна карта",
+    cod: "Наложен платеж",
+    manual: "Друг начин на плащане",
+    paypal: "PayPal",
+  },
+  needHelp: "Имате нужда от помощ?",
+  contactUs: "Свържете се с нас",
+  returnsExchanges: "Връщания и замени",
+  orderPlaced: "Приета",
+  processing: "Обработка",
+  shipped: "Изпратена",
+  delivered: "Доставена",
+  free: "БЕЗПЛАТНА",
+  continueShopping: "Продължи пазаруването",
+  qty: "бр.",
+  tracking: "Проследяване",
+}