@cartbase/storefront 0.20.0 → 0.21.0

package/src/lib/country-name.ts

@@ -1,59 +1,59 @@
-/**
- * The name of a country, from its ISO-3166 alpha-2 code.
- *
- * A code is a machine string: "bg" is how a cart address stores a country,
- * never how a shopper reads it. The catalogue from
- * `GET /api/store/countries` carries real names, so this is for the one case
- * where a code arrives WITHOUT one: the checkout hook's fallback when the
- * country list cannot be loaded. It used to hand the address form
- * `{iso_2: "bg", display_name: ""}`, and the form rendered an EMPTY country
- * field (found on evoo, 2026-09-13).
- *
- * `Intl.DisplayNames` is in the runtime, so this needs no bundled table and
- * knows every country in every language the browser does.
- *
- * THE LOCALE IS EXPLICIT AND DEFAULTS TO ENGLISH ON PURPOSE. Letting Intl
- * pick the runtime default would name the country in the SERVER's language
- * during a server render and in the BROWSER's language after hydration,
- * which is a hydration mismatch on any store whose visitors are not in the
- * server's locale. Pass the store's own language to translate it:
- *
- *   const locale = useStorefrontLocale()
- *   countryName("bg", locale.code)   // "България"
- *
- * Three behaviours verified against the runtime rather than assumed
- * (2026-09-13): a LOWERCASE code returns itself unchanged, so the code is
- * uppercased here; a malformed code throws `RangeError`, so it is shape
- * checked and wrapped; and an unknown-but-well-formed code resolves to
- * "Unknown Region" unless `fallback: "none"` is set, which is why it is set
- * and why the uppercase code is the last resort.
- */
-
-const cache = new Map<string, Intl.DisplayNames>()
-
-function namer(locale: string): Intl.DisplayNames | null {
-  const hit = cache.get(locale)
-  if (hit) return hit
-  try {
-    const made = new Intl.DisplayNames([locale], { type: "region", fallback: "none" })
-    cache.set(locale, made)
-    return made
-  } catch {
-    return null
-  }
-}
-
-export function countryName(
-  code: string | null | undefined,
-  locale: string = "en"
-): string {
-  const iso2 = code?.trim()
-  if (!iso2 || !/^[a-z]{2}$/i.test(iso2)) return ""
-
-  const upper = iso2.toUpperCase()
-  try {
-    return namer(locale)?.of(upper) || upper
-  } catch {
-    return upper
-  }
-}
+/**
+ * The name of a country, from its ISO-3166 alpha-2 code.
+ *
+ * A code is a machine string: "bg" is how a cart address stores a country,
+ * never how a shopper reads it. The catalogue from
+ * `GET /api/store/countries` carries real names, so this is for the one case
+ * where a code arrives WITHOUT one: the checkout hook's fallback when the
+ * country list cannot be loaded. It used to hand the address form
+ * `{iso_2: "bg", display_name: ""}`, and the form rendered an EMPTY country
+ * field (found on evoo, 2026-09-13).
+ *
+ * `Intl.DisplayNames` is in the runtime, so this needs no bundled table and
+ * knows every country in every language the browser does.
+ *
+ * THE LOCALE IS EXPLICIT AND DEFAULTS TO ENGLISH ON PURPOSE. Letting Intl
+ * pick the runtime default would name the country in the SERVER's language
+ * during a server render and in the BROWSER's language after hydration,
+ * which is a hydration mismatch on any store whose visitors are not in the
+ * server's locale. Pass the store's own language to translate it:
+ *
+ *   const locale = useStorefrontLocale()
+ *   countryName("bg", locale.code)   // "България"
+ *
+ * Three behaviours verified against the runtime rather than assumed
+ * (2026-09-13): a LOWERCASE code returns itself unchanged, so the code is
+ * uppercased here; a malformed code throws `RangeError`, so it is shape
+ * checked and wrapped; and an unknown-but-well-formed code resolves to
+ * "Unknown Region" unless `fallback: "none"` is set, which is why it is set
+ * and why the uppercase code is the last resort.
+ */
+
+const cache = new Map<string, Intl.DisplayNames>()
+
+function namer(locale: string): Intl.DisplayNames | null {
+  const hit = cache.get(locale)
+  if (hit) return hit
+  try {
+    const made = new Intl.DisplayNames([locale], { type: "region", fallback: "none" })
+    cache.set(locale, made)
+    return made
+  } catch {
+    return null
+  }
+}
+
+export function countryName(
+  code: string | null | undefined,
+  locale: string = "en"
+): string {
+  const iso2 = code?.trim()
+  if (!iso2 || !/^[a-z]{2}$/i.test(iso2)) return ""
+
+  const upper = iso2.toUpperCase()
+  try {
+    return namer(locale)?.of(upper) || upper
+  } catch {
+    return upper
+  }
+}

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

@@ -1,133 +1,133 @@
-import { getPercentageDiff } from "./get-percentage-diff"
-import { convertToLocale } from "./money"
-
-/**
- * Product price extraction — ported from
- * `@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 (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`): 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
- * nested path. `getPricesForVariant` reads the flat key first and falls
- * back to the nested path so both shapes produce the same result.
- */
-
-/** Structural `variant.calculated_price` shape (see api/types CalculatedPrice). */
-export type CalculatedPriceLike = {
-  calculated_amount: number
-  original_amount: number
-  currency_code: string
-  price_list_type?: string | null
-  /** Medusa-wire nested detail object (fallback path). */
-  calculated_price?: { price_list_type?: string | null } | null
-}
-
-/** Structural variant shape — any richer product-variant DTO satisfies it. */
-export type VariantWithPrice = {
-  id?: string
-  sku?: string | null
-  calculated_price?: CalculatedPriceLike | null
-}
-
-/** Structural product shape — any richer product DTO satisfies it. */
-export type ProductWithVariants = {
-  id?: string
-  variants?: VariantWithPrice[] | null
-}
-
-export type VariantPrice = {
-  calculated_price_number: number
-  calculated_price: string
-  original_price_number: number
-  original_price: string
-  currency_code: string
-  price_type: string | null | undefined
-  percentage_diff: string
-}
-
-export const getPricesForVariant = (
-  variant: VariantWithPrice | null | undefined
-): VariantPrice | null => {
-  if (!variant?.calculated_price?.calculated_amount) {
-    return null
-  }
-
-  const cp = variant.calculated_price
-  return {
-    calculated_price_number: cp.calculated_amount,
-    calculated_price: convertToLocale({
-      amount: cp.calculated_amount,
-      currency_code: cp.currency_code,
-    }),
-    original_price_number: cp.original_amount,
-    original_price: convertToLocale({
-      amount: cp.original_amount,
-      currency_code: cp.currency_code,
-    }),
-    currency_code: cp.currency_code,
-    // 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:
-      cp.price_list_type !== undefined
-        ? cp.price_list_type
-        : cp.calculated_price?.price_list_type,
-    percentage_diff: getPercentageDiff(cp.original_amount, cp.calculated_amount),
-  }
-}
-
-export function getProductPrice({
-  product,
-  variantId,
-}: {
-  product: ProductWithVariants
-  variantId?: string
-}) {
-  if (!product || !product.id) {
-    throw new Error("No product provided")
-  }
-
-  const cheapestPrice = (): VariantPrice | null => {
-    if (!product || !product.variants?.length) {
-      return null
-    }
-
-    const cheapestVariant = product.variants
-      .filter((v) => !!v.calculated_price)
-      .sort(
-        (a, b) =>
-          (a.calculated_price?.calculated_amount ?? 0) -
-          (b.calculated_price?.calculated_amount ?? 0)
-      )[0]
-
-    return getPricesForVariant(cheapestVariant)
-  }
-
-  const variantPrice = (): VariantPrice | null => {
-    if (!product || !variantId) {
-      return null
-    }
-
-    const variant = product.variants?.find(
-      (v) => v.id === variantId || v.sku === variantId
-    )
-
-    if (!variant) {
-      return null
-    }
-
-    return getPricesForVariant(variant)
-  }
-
-  return {
-    product,
-    cheapestPrice: cheapestPrice(),
-    variantPrice: variantPrice(),
-  }
-}
+import { getPercentageDiff } from "./get-percentage-diff"
+import { convertToLocale } from "./money"
+
+/**
+ * Product price extraction — ported from
+ * `@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 (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`): 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
+ * nested path. `getPricesForVariant` reads the flat key first and falls
+ * back to the nested path so both shapes produce the same result.
+ */
+
+/** Structural `variant.calculated_price` shape (see api/types CalculatedPrice). */
+export type CalculatedPriceLike = {
+  calculated_amount: number
+  original_amount: number
+  currency_code: string
+  price_list_type?: string | null
+  /** Medusa-wire nested detail object (fallback path). */
+  calculated_price?: { price_list_type?: string | null } | null
+}
+
+/** Structural variant shape — any richer product-variant DTO satisfies it. */
+export type VariantWithPrice = {
+  id?: string
+  sku?: string | null
+  calculated_price?: CalculatedPriceLike | null
+}
+
+/** Structural product shape — any richer product DTO satisfies it. */
+export type ProductWithVariants = {
+  id?: string
+  variants?: VariantWithPrice[] | null
+}
+
+export type VariantPrice = {
+  calculated_price_number: number
+  calculated_price: string
+  original_price_number: number
+  original_price: string
+  currency_code: string
+  price_type: string | null | undefined
+  percentage_diff: string
+}
+
+export const getPricesForVariant = (
+  variant: VariantWithPrice | null | undefined
+): VariantPrice | null => {
+  if (!variant?.calculated_price?.calculated_amount) {
+    return null
+  }
+
+  const cp = variant.calculated_price
+  return {
+    calculated_price_number: cp.calculated_amount,
+    calculated_price: convertToLocale({
+      amount: cp.calculated_amount,
+      currency_code: cp.currency_code,
+    }),
+    original_price_number: cp.original_amount,
+    original_price: convertToLocale({
+      amount: cp.original_amount,
+      currency_code: cp.currency_code,
+    }),
+    currency_code: cp.currency_code,
+    // 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:
+      cp.price_list_type !== undefined
+        ? cp.price_list_type
+        : cp.calculated_price?.price_list_type,
+    percentage_diff: getPercentageDiff(cp.original_amount, cp.calculated_amount),
+  }
+}
+
+export function getProductPrice({
+  product,
+  variantId,
+}: {
+  product: ProductWithVariants
+  variantId?: string
+}) {
+  if (!product || !product.id) {
+    throw new Error("No product provided")
+  }
+
+  const cheapestPrice = (): VariantPrice | null => {
+    if (!product || !product.variants?.length) {
+      return null
+    }
+
+    const cheapestVariant = product.variants
+      .filter((v) => !!v.calculated_price)
+      .sort(
+        (a, b) =>
+          (a.calculated_price?.calculated_amount ?? 0) -
+          (b.calculated_price?.calculated_amount ?? 0)
+      )[0]
+
+    return getPricesForVariant(cheapestVariant)
+  }
+
+  const variantPrice = (): VariantPrice | null => {
+    if (!product || !variantId) {
+      return null
+    }
+
+    const variant = product.variants?.find(
+      (v) => v.id === variantId || v.sku === variantId
+    )
+
+    if (!variant) {
+      return null
+    }
+
+    return getPricesForVariant(variant)
+  }
+
+  return {
+    product,
+    cheapestPrice: cheapestPrice(),
+    variantPrice: variantPrice(),
+  }
+}

package/src/lib/media-image.tsx

@@ -1,39 +1,39 @@
-import NextImage, { type ImageProps } from "next/image"
-
-/**
- * The store's picture element (store-speed-law card, step 3, 2026-09-15).
- *
- * Product pictures live on the Cartbase media CDN, and Next resizes them on
- * the store's own project, per device and in the modern formats, which the
- * scaffold allows through `images.remotePatterns` (next.config.ts). The
- * scaffold used to ship `images.unoptimized: true` instead, so no picture
- * was ever resized: a phone downloaded the merchant's full upload.
- *
- * A picture from any other host (a catalogue not yet rehosted, a demo
- * placeholder, a merchant's own asset host) renders as it is instead of
- * failing the page: Next refuses to resize a host the config does not
- * list, so this element switches resizing off for those. A merchant who
- * adds their host to `remotePatterns` gets resizing there too by passing
- * `unoptimized={false}` where they render it, or by using `next/image`
- * directly.
- */
-
-/** The public base of the media CDN (REGISTRY.md, CDN domain). */
-export const MEDIA_HOST = "cartbase.cloud"
-
-/** Is this picture served by the media CDN (or by the app itself)? */
-export function isResizableSrc(src: ImageProps["src"]): boolean {
-  if (typeof src !== "string") return true
-  if (src.startsWith("/")) return true
-  try {
-    const host = new URL(src).hostname
-    return host === MEDIA_HOST || host.endsWith(`.${MEDIA_HOST}`)
-  } catch {
-    return false
-  }
-}
-
-export function StoreImage(props: ImageProps) {
-  const unoptimized = props.unoptimized ?? !isResizableSrc(props.src)
-  return <NextImage {...props} unoptimized={unoptimized} />
-}
+import NextImage, { type ImageProps } from "next/image"
+
+/**
+ * The store's picture element (store-speed-law card, step 3, 2026-09-15).
+ *
+ * Product pictures live on the Cartbase media CDN, and Next resizes them on
+ * the store's own project, per device and in the modern formats, which the
+ * scaffold allows through `images.remotePatterns` (next.config.ts). The
+ * scaffold used to ship `images.unoptimized: true` instead, so no picture
+ * was ever resized: a phone downloaded the merchant's full upload.
+ *
+ * A picture from any other host (a catalogue not yet rehosted, a demo
+ * placeholder, a merchant's own asset host) renders as it is instead of
+ * failing the page: Next refuses to resize a host the config does not
+ * list, so this element switches resizing off for those. A merchant who
+ * adds their host to `remotePatterns` gets resizing there too by passing
+ * `unoptimized={false}` where they render it, or by using `next/image`
+ * directly.
+ */
+
+/** The public base of the media CDN (REGISTRY.md, CDN domain). */
+export const MEDIA_HOST = "cartbase.cloud"
+
+/** Is this picture served by the media CDN (or by the app itself)? */
+export function isResizableSrc(src: ImageProps["src"]): boolean {
+  if (typeof src !== "string") return true
+  if (src.startsWith("/")) return true
+  try {
+    const host = new URL(src).hostname
+    return host === MEDIA_HOST || host.endsWith(`.${MEDIA_HOST}`)
+  } catch {
+    return false
+  }
+}
+
+export function StoreImage(props: ImageProps) {
+  const unoptimized = props.unoptimized ?? !isResizableSrc(props.src)
+  return <NextImage {...props} unoptimized={unoptimized} />
+}

package/src/lib/payment-constants.ts

@@ -1,53 +1,53 @@
-/**
- * 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 },
-}
+/**
+ * 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/lib/platform.ts

@@ -1,13 +1,13 @@
-/**
- * The platform's origin (one key, store-birth-and-doors item 6, 2026-09-07):
- * a constant, not an input. Every Cartbase store's API lives here; a
- * storefront overrides it only to point at a local or staging platform
- * (`NEXT_PUBLIC_CARTBASE_URL`), never to find its own store, which the
- * publishable key does.
- */
-export const CARTBASE_API_ORIGIN = "https://admin.cartbase.ai"
-
-/** The origin to call: the override when set, else the platform. */
-export function cartbaseApiOrigin(override?: string | null): string {
-  return (override && override.trim()) || CARTBASE_API_ORIGIN
-}
+/**
+ * The platform's origin (one key, store-birth-and-doors item 6, 2026-09-07):
+ * a constant, not an input. Every Cartbase store's API lives here; a
+ * storefront overrides it only to point at a local or staging platform
+ * (`NEXT_PUBLIC_CARTBASE_URL`), never to find its own store, which the
+ * publishable key does.
+ */
+export const CARTBASE_API_ORIGIN = "https://admin.cartbase.ai"
+
+/** The origin to call: the override when set, else the platform. */
+export function cartbaseApiOrigin(override?: string | null): string {
+  return (override && override.trim()) || CARTBASE_API_ORIGIN
+}