@cartbase/storefront 0.1.2 → 0.2.0

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

@@ -54,7 +54,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,14 +63,14 @@ 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: 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
@@ -78,9 +78,9 @@ import type { BoxNowLocker } from "../api/integrations"
  *  - Provider ids: `pp_stripe` / `pp_cod` / `pp_manual` exactly
  *    (lib/payment-constants + the pp_cod resolution below).
  *  - `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.
  *
@@ -115,7 +115,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`.
    */
@@ -159,7 +159,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 +171,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,7 +194,7 @@ const REQUIRED_ADDRESS_FIELDS = [
  */
 const ADDRESS_AUTO_SAVE_DEBOUNCE_MS = 600
 
-/** Barter COD provider resolution: `pp_cod` exactly, with the Medusa-era
+/** 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). */
@@ -322,7 +322,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 +500,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 +702,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
@@ -818,7 +818,7 @@ export function useCheckoutOrchestration({
 
   // 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).
+  // native fee (Cartbase: at prepare, when the pp_cod session is minted).
   // Three values:
   //   - null         → no prediction; render whatever the cart says
   //   - 0            → predict no fee (toggling away from COD)
@@ -1089,7 +1089,7 @@ export function useCheckoutOrchestration({
   //                       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,
+  //     (Cartbase: the COD 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(() => {
@@ -1287,7 +1287,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

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:

package/src/lib/payment-constants.ts

@@ -2,7 +2,7 @@
  * 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 barter provider-id seam (code truth:
+ * 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).
@@ -18,7 +18,7 @@
 
 /**
  * True if the provider id is a Stripe-backed card payment provider.
- * Barter's canonical ids first (`pp_stripe` / `stripe`), then the
+ * Cartbase's canonical ids first (`pp_stripe` / `stripe`), then the
  * Medusa-era prefixes (`pp_stripe_*`, `pp_medusa-*`).
  */
 export const isStripeLike = (providerId?: string): boolean => {

package/src/lib/store-api-error.ts

@@ -6,7 +6,7 @@ import { StoreApiError } from "../api/types"
  * Normalizes any error thrown by the `@cartbase/storefront` SDK layer into a
  * clean, user-presentable `Error` whose message starts with a capital and
  * ends with a period — the same normalization contract the Medusa-era
- * helper enforced, adapted to the barter error contract (`StoreApiError`
+ * helper enforced, adapted to the Cartbase error contract (`StoreApiError`
  * with `status` + `code` + raw `body`, see `../api/types`).
  *
  * Always throws — never returns. Use in `.catch()` chains:

package/src/order/index.ts

@@ -1,6 +1,6 @@
 /**
  * @cartbase/storefront/order — order confirmation + account order views.
- * Ported from `@1click/ui/src/order` (v2.3.1) with barter data seams; see
+ * Ported from `@1click/ui/src/order` (v2.3.1) with Cartbase data seams; see
  * per-module JSDoc and docs/storefront/components.md for the contracts.
  */
 export { OrderLabelsProvider, useOrderLabels } from "./context"

package/src/order/labels.ts

@@ -1,7 +1,7 @@
 /**
  * Order family label pack. Ported from `@1click/ui/src/order/labels.ts`
- * (v2.3.1) unchanged, plus `tracking` — new in the barter port because the
- * barter order surface exposes fulfillment tracking labels
+ * (v2.3.1) unchanged, plus `tracking` — new in the Cartbase port because the
+ * Cartbase order surface exposes fulfillment tracking labels
  * (`StoreOrderDetail.fulfillments[].fulfillment.labels`) that
  * `OrderDeliveryCard` now renders.
  */
@@ -40,7 +40,7 @@ export type OrderLabels = {
   free: string
   continueShopping: string
   qty: string
-  /** Heading for the fulfillment tracking-numbers block (barter addition). */
+  /** Heading for the fulfillment tracking-numbers block (Cartbase addition). */
   tracking: string
 }
 

package/src/order/order-address-card.tsx

@@ -3,7 +3,7 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 /**
  * Contact-info card (name, phone, email). Ported from
  * `@1click/ui/src/order/order-address-card.tsx` (v2.3.1); data seam:
- * structural pick — barter's `StoreOrderDetail` (with its embedded
+ * structural pick — Cartbase's `StoreOrderDetail` (with its embedded
  * `order_addresses` row) satisfies it directly.
  */
 export interface OrderContactData {

package/src/order/order-completed-template.tsx

@@ -25,11 +25,11 @@ import { OrderHelpSection } from "./order-help-section"
 /**
  * Full order-confirmation page. Ported from
  * `@1click/ui/src/order/order-completed-template.tsx` (v2.3.1) with the
- * barter data seam: Medusa's `StoreOrder` was one object carrying items
- * with totals, order totals, shipping methods and payments — barter splits
+ * Cartbase data seam: Medusa's `StoreOrder` was one object carrying items
+ * with totals, order totals, shipping methods and payments — Cartbase splits
  * those across surfaces, so the template takes them as separate props:
  *
- *  - `order` — barter `StoreOrderDetail` (or any structural equivalent:
+ *  - `order` — Cartbase `StoreOrderDetail` (or any structural equivalent:
  *    id/display_id/email/created_at/currency_code/metadata/addresses/
  *    fulfillments). The fulfillment timeline is derived from
  *    `order.fulfillments` internally.

package/src/order/order-confirmation-header.tsx

@@ -4,7 +4,7 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 /**
  * Confirmation hero (check mark + order number + date). Ported from
  * `@1click/ui/src/order/order-confirmation-header.tsx` (v2.3.1); data
- * seam: structural pick instead of Medusa's `StoreOrder` — both barter's
+ * seam: structural pick instead of Medusa's `StoreOrder` — both Cartbase's
  * `StoreOrderDetail` and `completeCart()`'s `CompletedOrder` satisfy it.
  */
 export interface OrderHeaderData {

package/src/order/order-delivery-card.tsx

@@ -5,17 +5,17 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 
 /**
  * Delivery card: pickup point / address, shipping method row, and — new in
- * the barter port — the fulfillment tracking labels. Ported from
+ * the Cartbase port — the fulfillment tracking labels. Ported from
  * `@1click/ui/src/order/order-delivery-card.tsx` (v2.3.1) with these seam
  * translations:
  *
- *  - Medusa's `order.shipping_methods[0]` embed does not exist on barter's
+ *  - Medusa's `order.shipping_methods[0]` embed does not exist on Cartbase's
  *    `StoreOrderDetail`; the method comes via the `shippingMethod` prop
  *    (structural — `api/carts` `CartShippingMethod` from the decorated
  *    cart on the confirmation page satisfies it; `data` still carries the
  *    fulfillment-option id used for the pickup detection below).
  *  - `order.fulfillments[].fulfillment.labels` (tracking_number /
- *    tracking_url) ARE on the barter surface (docs/storefront/orders.md);
+ *    tracking_url) ARE on the Cartbase surface (docs/storefront/orders.md);
  *    `pickTrackingLabels()` selects the renderable ones and the card shows
  *    them under a `labels.tracking` heading.
  *  - Pickup detection preserved verbatim: `metadata.econt_office_code` (the

package/src/order/order-item.tsx

@@ -6,10 +6,10 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 
 /**
  * Order line row. Ported from `@1click/ui/src/order/order-item.tsx`
- * (v2.3.1) with the data seam translated to barter:
+ * (v2.3.1) with the data seam translated to Cartbase:
  *
  * Medusa's `StoreOrderLineItem` carried per-line computed totals
- * (`total` / `original_total`). Barter's store order surface does NOT —
+ * (`total` / `original_total`). Cartbase's store order surface does NOT —
  * `StoreOrderDetail.items` are version-pivot rows (`{quantity, line_item}`)
  * whose embedded `order_line_items` row carries only `unit_price` (see
  * docs/storefront/orders.md). The component therefore renders a normalized

package/src/order/order-items-list.tsx

@@ -5,7 +5,7 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 /**
  * Order items list. Ported from `@1click/ui/src/order/order-items-list.tsx`
  * (v2.3.1); data seam: takes normalized `OrderDisplayItem[]` (see
- * `order-item.tsx` converters) + the currency, since barter's
+ * `order-item.tsx` converters) + the currency, since Cartbase's
  * `StoreOrderDetail` carries no order-level computed fields beyond
  * `currency_code`.
  */
@@ -23,9 +23,9 @@ export function OrderItemsList({
   const l = { ...defaultOrderLabels, ...labels }
   // Render product lines only — backend-injected fee lines (legacy COD-fee
   // line items tagged `metadata.is_cod_fee`) are hidden here and surfaced
-  // as a dedicated row in OrderTotals instead. barter's NATIVE COD fee is
+  // as a dedicated row in OrderTotals instead. Cartbase's NATIVE COD fee is
   // never a line item (order_summaries.totals.cod_fee_total), so on pure
-  // barter data this filter is a no-op safety net.
+  // Cartbase data this filter is a no-op safety net.
   const visible = (items || []).filter((i) => isProductLine(i))
 
   return (

package/src/order/order-payment-card.tsx

@@ -11,7 +11,7 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
  * Payment-method card. Ported from
  * `@1click/ui/src/order/order-payment-card.tsx` (v2.3.1); data seam:
  * Medusa's `order.payment_collections[0].payments[0]` embed does not exist
- * on barter's `StoreOrderDetail` (payment internals never cross the store
+ * on Cartbase's `StoreOrderDetail` (payment internals never cross the store
  * surface) — the provider id arrives via props instead: from
  * `prepareCheckout().payment_provider`, the decorated cart's
  * `payment_collection` sessions, or the app's checkout state.
@@ -33,7 +33,7 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
  *
  * The bucket is determined by the same `isStripeLike` / `isManual` /
  * `isPaypal` predicates used everywhere else in the library (translated to
- * barter ids in `lib/payment-constants`), so a single change to those
+ * Cartbase ids in `lib/payment-constants`), so a single change to those
  * propagates here automatically.
  */
 export function resolvePaymentTitle(

package/src/order/order-timeline.tsx

@@ -6,14 +6,14 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 /**
  * Fulfillment progress timeline. Ported from
  * `@1click/ui/src/order/order-timeline.tsx` (v2.3.1) — the step state
- * machine and rendering are unchanged. Barter seam: there is no
+ * machine and rendering are unchanged. Cartbase seam: there is no
  * `order.fulfillment_status` column on the store surface; derive the
  * status from the fulfillments' lifecycle timestamps with
  * `deriveFulfillmentStatus(order.fulfillments)` and pass it in.
  */
 
 /**
- * Derive a Medusa-style fulfillment status from barter's fulfillment
+ * Derive a Medusa-style fulfillment status from Cartbase's fulfillment
  * lifecycle timestamps (packed_at → fulfilled, shipped_at → shipped,
  * delivered_at → delivered; canceled fulfillments are ignored). Returns
  * `undefined` for "not fulfilled yet" (timeline shows "Placed"). Partial

package/src/order/order-totals.tsx

@@ -4,9 +4,9 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 
 /**
  * Order totals breakdown. Ported from `@1click/ui/src/order/order-totals.tsx`
- * (v2.3.1) with the barter money seam:
+ * (v2.3.1) with the Cartbase money seam:
  *
- * Totals are SERVER truth and the barter store order read
+ * Totals are SERVER truth and the Cartbase store order read
  * (`StoreOrderDetail`) carries NONE of them — they live where the server
  * computed them: the decorated cart the app holds on the confirmation page
  * (`api/carts` `Cart`: `item_subtotal`, `shipping_subtotal`,
@@ -18,7 +18,7 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
  * computes money beyond the two production subtractions documented below.
  *
  * COD fee display, in preference order (production fix preserved):
- *  1. barter-native fee: `cod_fee_total` > 0 (never a line item;
+ *  1. Cartbase-native fee: `cod_fee_total` > 0 (never a line item;
  *     already folded into `total` server-side), labeled by the
  *     admin-editable `cod_fee_label`.
  *  2. legacy Medusa-era fee LINE ITEM (`metadata.is_cod_fee`) found in
@@ -42,7 +42,7 @@ export interface OrderTotalsSource {
   discount_total?: number | null
   tax_total?: number | null
   total?: number | null
-  /** barter-native COD fee (already folded into `total`). */
+  /** Cartbase-native COD fee (already folded into `total`). */
   cod_fee_total?: number | null
   /** Admin-editable COD fee label from the server. */
   cod_fee_label?: string | null
@@ -98,7 +98,7 @@ export function selectOrderTotalsRows(
   const l = { ...defaultOrderLabels, ...opts.labels }
   const rows: OrderTotalsRow[] = []
 
-  // Legacy fee LINE (Medusa-era injection) — barter-native carts never
+  // Legacy fee LINE (Medusa-era injection) — Cartbase-native carts never
   // have one, but ported data / hybrid stores might.
   const codFeeItem = findFeeLine(opts.items || [])
   const nativeFee = Number(source.cod_fee_total ?? 0)

package/src/platform/identity.ts

@@ -0,0 +1,18 @@
+/**
+ * Platform identity — MIRROR of `src/lib/platform/identity.ts` in the main
+ * app (docs/cards/platform-fingerprints.md). This library publishes to npm
+ * independently, so it cannot import the app's root `package.json` across
+ * the package boundary — it reads its OWN `package.json` instead.
+ *
+ * Sync obligation: if `PLATFORM_NAME` ever changes, update BOTH copies in
+ * the same commit. There is no automated link between them.
+ *
+ * Emitters that consume this: `./metadata.ts` (generator meta tag),
+ * `./platform-init.tsx` (window.Cartbase).
+ */
+import pkg from "../../package.json"
+
+export const PLATFORM_NAME = "Cartbase"
+
+/** This package's own published version. */
+export const PLATFORM_VERSION: string = pkg.version

package/src/platform/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @cartbase/storefront/platform — platform-fingerprint emitters
+ * (docs/cards/platform-fingerprints.md). Same barrel discipline as every
+ * other feature folder (tracking, checkout, cart-drawer, ...).
+ */
+export { PLATFORM_NAME, PLATFORM_VERSION } from "./identity"
+export { createStorefrontMetadata } from "./metadata"
+export { PlatformInit, type PlatformInitProps, type CartbaseWindowGlobal } from "./platform-init"

package/src/platform/metadata.ts

@@ -0,0 +1,26 @@
+import type { Metadata } from "next"
+import { PLATFORM_NAME } from "./identity"
+
+/**
+ * createStorefrontMetadata — root-layout metadata helper
+ * (platform-fingerprints card, fingerprint #1). Every storefront built on
+ * `@cartbase/storefront` calls this instead of hand-writing
+ * `export const metadata`, so `<meta name="generator" content="Cartbase" />`
+ * ships by construction on every storefront-rendered page.
+ *
+ * Usage:
+ *
+ *   export const metadata: Metadata = createStorefrontMetadata({
+ *     title: "My Store",
+ *     description: "...",
+ *   })
+ *
+ * `generator` always resolves to the platform name — it is not
+ * overridable from `overrides` (a stray key there is simply shadowed).
+ */
+export function createStorefrontMetadata(overrides: Metadata = {}): Metadata {
+  return {
+    ...overrides,
+    generator: PLATFORM_NAME,
+  }
+}

package/src/platform/platform-init.tsx

@@ -0,0 +1,46 @@
+import { PLATFORM_VERSION } from "./identity"
+
+/**
+ * The shape of `window.Cartbase` — the strongest platform-detection signal
+ * (same mechanism as `window.Shopify`). No PII: store id + platform
+ * version only.
+ */
+export interface CartbaseWindowGlobal {
+  version: string
+  storeId: string
+}
+
+declare global {
+  interface Window {
+    Cartbase?: CartbaseWindowGlobal
+  }
+}
+
+export interface PlatformInitProps {
+  /** The store's client id — the ONLY identifying value exposed. */
+  storeId: string
+}
+
+/**
+ * PlatformInit — mounts `window.Cartbase = { version, storeId }`
+ * (platform-fingerprints card, fingerprint #3). Same shape as
+ * `<ConsentInit />` (`../tracking/consent-init.tsx`): a server component
+ * rendering one synchronous inline `<script>`, mounted once near the top
+ * of `<body>` — no hydration wait, no client bundle cost.
+ *
+ * Storefront-surface only. Never mount this in an admin bundle — admin is
+ * not a storefront (category discipline: Cartbase exists ONLY as
+ * Ecommerce, and `window.Cartbase` must only ever appear where commerce
+ * actually happens).
+ */
+export function PlatformInit({ storeId }: PlatformInitProps) {
+  const payload: CartbaseWindowGlobal = { version: PLATFORM_VERSION, storeId }
+  return (
+    <script
+      id="cartbase-platform-init"
+      dangerouslySetInnerHTML={{
+        __html: `window.Cartbase=${JSON.stringify(payload)};`,
+      }}
+    />
+  )
+}

package/src/products/image-gallery.tsx

@@ -1,7 +1,7 @@
 /**
  * PDP image gallery — ported from
  * `@1click/ui/src/products/image-gallery.tsx` (v2.3.1). Data seam:
- * `HttpTypes.StoreProductImage[]` → barter `StoreProductImage[]`
+ * `HttpTypes.StoreProductImage[]` → Cartbase `StoreProductImage[]`
  * (`@cartbase/storefront/api/products`; images arrive rank-ordered from the
  * API). Server-safe.
  */