@cartbase/storefront 0.1.2 → 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"
@@ -54,7 +55,7 @@ import type { BoxNowLocker } from "../api/integrations"
  * persistence, custom summary).
  *
  * Ported from `@1click/ui/src/checkout/use-checkout-orchestration.ts`
- * (v2.3.1, the deferred-intent architecture) with the barter data seam:
+ * (v2.3.1, the deferred-intent architecture) with the Cartbase data seam:
  *
  *  - Server actions → `@cartbase/storefront/api` calls on a caller-supplied
  *    `StorefrontClient` (`updateCart`, `prepareCheckout`,
@@ -63,24 +64,25 @@ import type { BoxNowLocker } from "../api/integrations"
  *  - `placeOrder` (server action with baked-in redirect) →
  *    `completeCart()` + template navigation (`orderConfirmedPath` with
  *    `{id}`/`{country}` substitution) or the `onOrderPlaced` callback.
- *  - **Zero-remainder gift path** (barter gift-card tender,
+ *  - **Zero-remainder gift path** (Cartbase gift-card tender,
  *    docs/storefront/checkout.md): when applied gift cards cover the whole
  *    total, `prepareCheckout` returns `client_secret: null` +
  *    `provider_id: null` and the card path SKIPS `stripe.confirmPayment`
  *    entirely — the cart completes on the gift session alone. The @1click
- *    original threw on a missing client_secret; barter treats
+ *    original threw on a missing client_secret; Cartbase treats
  *    null-secret + null-provider as the documented gift path.
- *  - COD fee: barter'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
- *    barter store endpoint — the hook takes an optional `logError` callback
+ *    Cartbase store endpoint — the hook takes an optional `logError` callback
  *    so stores wire their own sink; all production log points are kept.
- *  - Barter regions carry NO embedded countries array (api/regions.ts
+ *  - Cartbase regions carry NO embedded countries array (api/regions.ts
  *    divergence note) — the country list is a `countries` option with a
  *    `countryCode` single-entry fallback.
  *
@@ -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,
@@ -115,7 +116,7 @@ export type UseCheckoutOrchestrationOptions = {
   /** Default country code when the cart has no shipping address yet. */
   countryCode?: string
   /**
-   * Countries offered in the address form. Barter regions do NOT embed a
+   * Countries offered in the address form. Cartbase regions do NOT embed a
    * countries array (store-API divergence), so the host app supplies the
    * list; omitted → a single entry derived from `countryCode`.
    */
@@ -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
@@ -159,7 +153,7 @@ export type UseCheckoutOrchestrationOptions = {
   resolveTrackingMetadata?: () => Record<string, unknown> | undefined
   /**
    * Operational-visibility sink (successor of @1click's logCheckoutError /
-   * logEvent Supabase writers — barter has no store-side log endpoint).
+   * logEvent Supabase writers — Cartbase has no store-side log endpoint).
    * Called with (errorType, message, context). Optional; defaults to no-op.
    */
   logError?: CheckoutLogError
@@ -171,7 +165,7 @@ export type UseCheckoutOrchestrationOptions = {
  *
  * `shipping_address.phone` is required — Bulgarian carriers (Econt,
  * BoxNow) need it to contact the customer; it's the courier's primary
- * recovery channel when the address is ambiguous. (Barter's
+ * recovery channel when the address is ambiguous. (Cartbase's
  * prepare-checkout schema requires it too — docs/storefront/checkout.md.)
  */
 const REQUIRED_ADDRESS_FIELDS = [
@@ -194,12 +188,18 @@ const REQUIRED_ADDRESS_FIELDS = [
  */
 const ADDRESS_AUTO_SAVE_DEBOUNCE_MS = 600
 
-/** Barter 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,
@@ -322,7 +321,7 @@ export function useCheckoutOrchestration({
       : true
   )
 
-  // Barter regions have no embedded countries — the caller-supplied list
+  // Cartbase regions have no embedded countries — the caller-supplied list
   // (or the countryCode fallback) is the authority for both the select
   // options and the saved-address region filter.
   const regionCountries = useMemo(
@@ -500,7 +499,7 @@ export function useCheckoutOrchestration({
       lastSavedSnapshotRef.current = snapshot
 
       if (customer) {
-        // Sync the profile best-effort. Barter has first-class company
+        // Sync the profile best-effort. Cartbase has first-class company
         // fields on the customer (company_name / company_eik —
         // api/customers.ts), so the invoice data also lands on the
         // profile — an upgrade over the @1click cart-metadata-only
@@ -702,7 +701,7 @@ export function useCheckoutOrchestration({
     [paymentMethodFilter, availablePaymentMethods, selectedShippingOption]
   )
 
-  // Calculated-rate price resolution. Barter serves flat prices today
+  // Calculated-rate price resolution. Cartbase serves flat prices today
   // (`price_type: "flat"` always — api/checkout.ts), so this effect
   // normally resolves immediately; the calculated branch is kept for
   // forward-compat with calculated-rate carriers (the /calculate route
@@ -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 (barter: 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
-  //     (barter: 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,
@@ -1287,7 +1295,7 @@ export function useCheckoutOrchestration({
         provider_id: prep.provider_id,
       })
 
-      // ── Zero-remainder gift path (barter gift-card tender) ──────────
+      // ── Zero-remainder gift path (Cartbase gift-card tender) ──────────
       // When applied gift cards cover the whole total, prepare skips the
       // provider session: client_secret AND provider_id come back null
       // and the cart completes on the internal pp_giftcard session alone
@@ -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/common/cart-button-client.tsx

@@ -9,7 +9,7 @@ import { useCartDrawer } from "../cart-drawer/context"
  * Header cart button (badge + opens the cart drawer). Ported from
  * `@1click/ui/src/common/cart-button-client.tsx` (v2.3.1); seams:
  *
- *  - `cart` is the barter decorated cart (`api/carts` `Cart`).
+ *  - `cart` is the Cartbase decorated cart (`api/carts` `Cart`).
  *  - Badge count uses `productItemCount` (fee-line-aware) instead of the
  *    source's raw `reduce` — keeps the badge consistent with the cart
  *    drawer's own count, which already excludes backend-injected fee

package/src/common/cart-button.tsx

@@ -5,7 +5,7 @@ import { CartButtonClient } from "./cart-button-client"
 /**
  * Server wrapper for the header cart button. Ported from
  * `@1click/ui/src/common/cart-button.tsx` (v2.3.1); data seam: the source
- * called the cookie-reading `retrieveCart()` server action — barter takes
+ * called the cookie-reading `retrieveCart()` server action — Cartbase takes
  * the `StorefrontClient` + the app-persisted cart id explicitly (the app
  * owns the cart-id cookie, see docs/storefront/carts.md) and calls
  * `api/carts.retrieveCart`. Any fetch failure (stale id, 404) degrades to

package/src/common/country-select.tsx

@@ -9,12 +9,12 @@ import type { StoreRegion } from "../api/regions"
  * change forced by the SDK (SDK wins over the source):
  *
  *  - Medusa regions embedded a `countries[]` array and the select listed
- *    countries; barter regions carry NO countries on the store surface
+ *    countries; Cartbase regions carry NO countries on the store surface
  *    (divergence documented in `api/regions` — tax scoping is by
  *    `tax_regions` server-side). The select therefore lists the REGIONS
  *    themselves (`regions.listRegions`), valued by region id.
  *  - The source called the `updateRegion(countryCode, path)` server
- *    action bound to URL `[countryCode]` routing; barter region
+ *    action bound to URL `[countryCode]` routing; Cartbase region
  *    persistence is app-owned (usually `carts.updateCart(client, cartId,
  *    {region_id})` + a cookie) — so the change surfaces via `onChange`.
  */

package/src/common/delete-button.tsx

@@ -10,7 +10,7 @@ import { cn } from "../lib/utils"
  * Cart-line delete button with spinner. Ported from
  * `@1click/ui/src/common/delete-button.tsx` (v2.3.1); data seam: the
  * source called the cookie-scoped `deleteLineItem(id)` server action —
- * barter calls `api/carts.deleteLineItem(client, cartId, lineItemId)`
+ * Cartbase calls `api/carts.deleteLineItem(client, cartId, lineItemId)`
  * (idempotent server-side) and hands the refreshed cart to `onDeleted`
  * so the app can update its state / `router.refresh()`. The spinner
  * resets on failure exactly like the source's `.catch`.

package/src/common/index.ts

@@ -1,7 +1,7 @@
 /**
  * @cartbase/storefront/common — shared storefront chrome. Ported from
  * `@1click/ui/src/common` (v2.3.1) + `LocalizedLink` (from the
- * mindpages-storefront production component); barter data seams per
+ * mindpages-storefront production component); Cartbase data seams per
  * module JSDoc.
  */
 export { LocalizedLink, type LocalizedLinkProps } from "./localized-link"

package/src/common/language-select.tsx

@@ -7,13 +7,13 @@ import { useTransition } from "react"
  * `@1click/ui/src/common/language-select.tsx` (v2.3.1); data seam:
  *
  *  - The locale list feeds from `api/regions.listLocales(client)` — an
- *    array of bare codes, store default first (barter has no `{code,
+ *    array of bare codes, store default first (Cartbase has no `{code,
  *    name}` locale objects on the store surface; SDK wins). Display
  *    names resolve via `localeDisplayName()` below (native-language
  *    autonym through `Intl.DisplayNames`), overridable per store with
  *    the `labels` map.
  *  - The source awaited an `updateLocale(code)` server action then
- *    `router.refresh()`; barter locale persistence is app-owned (the
+ *    `router.refresh()`; Cartbase locale persistence is app-owned (the
  *    cookie read by `StorefrontClient.getLocale`) — the async `onChange`
  *    callback carries it, and the `useTransition` pending-disable UX is
  *    preserved around it.

package/src/common/localized-link.tsx

@@ -10,7 +10,7 @@ import type { ReactNode } from "react"
  * `LocalizedClientLink` (src/modules/common/components/localized-client-link)
  * — the component `@1click/ui` consumers used for the same job.
  *
- * barter seam: barter storefronts default to COOKIE-based locale
+ * Cartbase seam: Cartbase storefronts default to COOKIE-based locale
  * (`StorefrontClient.getLocale`, see docs/storefront/BUILD-A-STOREFRONT.md)
  * with no mandatory URL segment — so the prefix is applied ONLY when the
  * route actually has a `[countryCode]` (or custom `paramName`) dynamic

package/src/lib/cart-helpers.ts

@@ -4,7 +4,7 @@
  * Ported from `@1click/ui/src/lib/cart-helpers.ts` (v2.3.1) with its
  * production reasoning intact; the `@medusajs/types` generic constraint is
  * replaced by the structural `LineLike` shape so this module stays decoupled
- * from any SDK layer (barter cart/order line items are structurally
+ * from any SDK layer (Cartbase cart/order line items are structurally
  * compatible: they carry `metadata`, `total`, `quantity`).
  *
  * Why this exists. There is no native "fee" / "surcharge" primitive in the
@@ -29,7 +29,7 @@
  * `findFeeLine`. Customer SHOULD see the fee in checkout / on the
  * order; they should NOT see it in the cart drawer pre-checkout.
  *
- * Money note (barter): amounts are decimal EUR major units everywhere in
+ * Money note (Cartbase): amounts are decimal EUR major units everywhere in
  * the store API — the arithmetic below is unit-agnostic and unchanged.
  */
 

package/src/lib/cookie-names.ts

@@ -0,0 +1,41 @@
+/**
+ * Cookie names the store API + @cartbase/storefront agree on
+ * (platform-fingerprints card, fingerprint #4 — cookie names are a
+ * primary Wappalyzer/BuiltWith detection signal).
+ *
+ * The app still OWNS *setting* the cart cookie — carts.md is explicit that
+ * "the SDK never persists the cart" — this module is the single source of
+ * the NAME so every consumer emits the same wire fingerprint instead of
+ * inventing its own prefix (the reference app previously hardcoded
+ * `_barter_cart_id` locally in `examples/storefront/src/lib/config.ts`).
+ *
+ * Renamed from the `_barter_*` prefix (2026-08-04, docs/features/
+ * cartbase-rename.md). `readCartCookie` accepts the legacy name for the
+ * transition window; every write uses the new name only.
+ */
+
+/** Current cart-id cookie name. */
+export const CART_COOKIE = "_cartbase_cart"
+
+/** @deprecated Legacy name — read-only compat, never written. */
+export const LEGACY_CART_COOKIE = "_barter_cart_id"
+
+/**
+ * Reserved for a future cookie-backed customer session. Auth today is pure
+ * Bearer-JWT, persisted by the consuming app (auth.md — "the Cartbase API
+ * does not proxy token refresh"); nothing sets this cookie yet. Defined now
+ * so a future cookie-based session launches with the fingerprint-correct
+ * name from day one rather than inventing a new prefix later.
+ */
+export const SESSION_COOKIE = "_cartbase_session"
+
+/**
+ * Read a cart id given a cookie-name → value lookup, preferring the
+ * current name and falling back to the legacy `_barter_cart_id` name so an
+ * existing visitor's cart survives the rename.
+ */
+export function readCartCookie(
+  get: (name: string) => string | undefined
+): string | undefined {
+  return get(CART_COOKIE) ?? get(LEGACY_CART_COOKIE)
+}

package/src/lib/get-product-price.ts

@@ -6,11 +6,11 @@ import { convertToLocale } from "./money"
  * `@1click/ui/src/lib/get-product-price.ts` (v2.3.1). The
  * `@medusajs/types` `HttpTypes.StoreProduct` parameter is replaced by the
  * structural shapes below so this module stays decoupled from the SDK
- * domain modules (barter's `variant.calculated_price` is the b2b-v1
+ * domain modules (Cartbase's `variant.calculated_price` is the b2b-v1
  * pricing context documented in `@cartbase/storefront/api/types`
  * `CalculatedPrice`, decimal EUR major units).
  *
- * Wire-shape note (code truth, `src/lib/products/pricing.ts`): barter serves
+ * Wire-shape note (code truth, `src/lib/products/pricing.ts`): Cartbase serves
  * `calculated_price.price_list_type` FLAT on the calculated_price object.
  * The Medusa wire shape ALSO nests a `calculated_price.calculated_price`
  * detail object carrying `price_list_type` — the original library read the
@@ -71,7 +71,7 @@ export const getPricesForVariant = (
       currency_code: cp.currency_code,
     }),
     currency_code: cp.currency_code,
-    // Flat key (barter wire shape) first — an explicit null stays null;
+    // Flat key (Cartbase wire shape) first — an explicit null stays null;
     // the nested Medusa detail is the fallback only when the flat key is
     // absent entirely (the original @1click read path).
     price_type: