@cartbase/storefront 0.9.0 → 0.11.0

package/src/checkout/promotion-error-copy.ts

@@ -1,124 +1,91 @@
-/**
- * Translates promotion errors into user-friendly Bulgarian copy for the
- * checkout discount-code surface.
- *
- * Ported from `@1click/ui/src/checkout/promotion-error-copy.ts` (v2.3.1)
- * and adapted to the Cartbase error envelope: the cart-promotions route
- * (POST /api/store/carts/:id/promotions) throws structured codes —
- * `promotion_not_found`, `promotion_inactive`, `promotion_misconfigured`,
- * `promotion_unsupported_type`, plus the cart-level `cart_not_found` /
- * `cart_completed` / `validation_failed` — so translation is code-first;
- * the Medusa-era substrings stay as fallback.
- *
- * Why this exists: applying a promo code is the one checkout action a
- * shopper triggers speculatively — they type a half-remembered code and
- * hope. So it FAILS often, by design. Raw technical English at the
- * highest-intent moment reads as "the site is broken".
- */
-
-/** Generic fallback — used when we can't recognise the error at all. */
-const GENERIC =
-  "Кодът за отстъпка не може да бъде приложен в момента. Моля, проверете кода и опитайте отново."
-
-/** Campaign-budget promotions are tracked per customer, so the engine can
- * require an email on the cart before applying them. A shopper who jumps
- * straight to the promo field without filling their details hits this. */
-const NEEDS_EMAIL =
-  "Въведете имейл адрес по-горе, за да приложите този код за отстъпка."
-
-const INVALID = "Този код за отстъпка не е валиден."
-
-const EXPIRED = "Този код за отстъпка вече не е активен."
-
-const EXHAUSTED =
-  "Промоцията е изчерпана и вече не може да бъде използвана."
-
-/**
- * Cartbase promotion error codes → BG copy (POST/DELETE
- * /api/store/carts/:id/promotions + src/lib/promotions/apply.ts).
- */
-export const PROMOTION_ERROR_CODE_COPY: Record<string, string> = {
-  promotion_not_found: INVALID,
-  promotion_inactive: EXPIRED,
-  promotion_misconfigured: GENERIC,
-  promotion_unsupported_type: GENERIC,
-  cart_completed:
-    "Поръчката вече е финализирана. Моля, проверете имейла си за потвърждение.",
-  cart_not_found: "Сесията на количката изтече. Моля, презаредете страницата.",
-  validation_failed: INVALID,
-}
-
-/**
- * Known promo error substrings → BG copy. Case-insensitive, first match
- * wins, most-specific first. Kept verbatim from the production port as the
- * fallback layer.
- */
-const PROMO_PATTERNS: Array<{ match: RegExp; copy: string }> = [
-  // Campaign budget needs an email on the cart.
-  {
-    match: /customer_email|campaign[\s_]?budget/i,
-    copy: NEEDS_EMAIL,
-  },
-  // Expired / no-longer-active promotion.
-  {
-    match: /expired|no[\s_]?longer[\s_]?(?:active|valid)|inactive/i,
-    copy: EXPIRED,
-  },
-  // Budget / usage limit reached.
-  {
-    match: /reached[\s_]?its[\s_]?limit|usage[\s_]?limit|budget[\s_]?(?:exceeded|reached)/i,
-    copy: EXHAUSTED,
-  },
-  // Invalid / unknown code (keep last of the specific set — broadest).
-  {
-    match: /is[\s_]?invalid|invalid[\s_]?data|not[\s_]?found|does(?:n'?t| not)[\s_]?exist/i,
-    copy: INVALID,
-  },
-]
-
-/**
- * Translate any thrown / returned promo error into customer-facing Bulgarian.
- *
- * @param err  the error from a try/catch (a StoreApiError with a code, a
- *             Stripe-less network error, or an opaque render error)
- * @param opts.hasEmail  whether the cart currently has an email. When the
- *             error is opaque and there's no email, the overwhelmingly
- *             likely cause is a campaign-budget promo, so we give the
- *             actionable "enter your email" message instead of a vague
- *             fallback.
- */
-export function translatePromotionError(
-  err: unknown,
-  opts?: { hasEmail?: boolean }
-): string {
-  if (err && typeof err === "object") {
-    const code = (err as { code?: unknown }).code
-    if (typeof code === "string" && PROMOTION_ERROR_CODE_COPY[code]) {
-      return PROMOTION_ERROR_CODE_COPY[code]
-    }
-  }
-
-  const raw = extractMessage(err)
-
-  for (const { match, copy } of PROMO_PATTERNS) {
-    if (match.test(raw)) return copy
-  }
-
-  // Unknown / opaque error. If the cart has no email yet, the
-  // campaign-budget case is by far the most common trigger — point the
-  // shopper at the fix rather than a dead end.
-  if (opts?.hasEmail === false) return NEEDS_EMAIL
-
-  return GENERIC
-}
-
-function extractMessage(err: unknown): string {
-  if (!err) return ""
-  if (typeof err === "string") return err
-  if (err instanceof Error) return err.message
-  if (typeof err === "object" && err !== null) {
-    const e = err as { message?: string; code?: string; type?: string }
-    return [e.message, e.code, e.type].filter(Boolean).join(" ")
-  }
-  return String(err)
-}
+import { PROMOTION_CODE_KEYS } from "./error-copy-codes"
+import type { PromotionErrorCopy } from "./labels"
+
+/**
+ * Recognizes a discount-code failure and picks the copy key for it.
+ *
+ * THE COPY IS NOT HERE ANY MORE. Until 2026-09-13 this file held seven
+ * hardcoded BULGARIAN sentences that every merchant shipped and none could
+ * override; the words now live in the checkout label pack, English by
+ * default. The substring patterns stay in English because they match the
+ * API's own error text, which is wire format and never shown.
+ *
+ * Recognition is code-first (`StoreApiError.code`), then the substrings
+ * kept verbatim from the production port.
+ */
+
+/**
+ * Known promo error substrings. Case-insensitive, first match wins, most
+ * specific first.
+ */
+const PROMO_PATTERNS: Array<{ match: RegExp; key: keyof PromotionErrorCopy }> = [
+  // Campaign budget needs an email on the cart.
+  { match: /customer_email|campaign[\s_]?budget/i, key: "needsEmail" },
+  // Expired or no-longer-active promotion.
+  { match: /expired|no[\s_]?longer[\s_]?(?:active|valid)|inactive/i, key: "promotionInactive" },
+  // Budget or usage limit reached.
+  {
+    match: /reached[\s_]?its[\s_]?limit|usage[\s_]?limit|budget[\s_]?(?:exceeded|reached)/i,
+    key: "exhausted",
+  },
+  // Invalid or unknown code. Last of the specific set, because it is the
+  // broadest pattern and would otherwise swallow the ones above.
+  {
+    match: /is[\s_]?invalid|invalid[\s_]?data|not[\s_]?found|does(?:n'?t| not)[\s_]?exist/i,
+    key: "promotionNotFound",
+  },
+]
+
+/**
+ * Which promotion copy this failure asks for.
+ *
+ * @param err the error from a try/catch: a StoreApiError with a code, a
+ *            network error, or an opaque render error
+ * @param opts.hasEmail whether the cart currently has an email. When the
+ *            error is opaque and there is no email, the overwhelmingly
+ *            likely cause is a campaign-budget promotion, so the shopper
+ *            gets the actionable "enter your email" line rather than a
+ *            vague fallback.
+ */
+export function promotionErrorKey(
+  err: unknown,
+  opts?: { hasEmail?: boolean }
+): keyof PromotionErrorCopy {
+  if (err && typeof err === "object") {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && PROMOTION_CODE_KEYS[code]) {
+      return PROMOTION_CODE_KEYS[code]
+    }
+  }
+
+  const raw = extractMessage(err)
+  for (const { match, key } of PROMO_PATTERNS) if (match.test(raw)) return key
+
+  // Unknown or opaque. With no email on the cart the campaign-budget case
+  // is by far the most common trigger, so point at the fix, not a dead end.
+  if (opts?.hasEmail === false) return "needsEmail"
+  return "generic"
+}
+
+/**
+ * Turn any thrown or returned promotion error into the sentence a shopper
+ * reads, in the store's own language.
+ */
+export function translatePromotionError(
+  err: unknown,
+  copy: PromotionErrorCopy,
+  opts?: { hasEmail?: boolean }
+): string {
+  return copy[promotionErrorKey(err, opts)]
+}
+
+function extractMessage(err: unknown): string {
+  if (!err) return ""
+  if (typeof err === "string") return err
+  if (err instanceof Error) return err.message
+  if (typeof err === "object" && err !== null) {
+    const e = err as { message?: string; code?: string; type?: string }
+    return [e.message, e.code, e.type].filter(Boolean).join(" ")
+  }
+  return String(err)
+}

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

@@ -10,6 +10,7 @@ import {
 } from "react"
 
 import type { StorefrontClient } from "../api/http"
+import { listCountries, type StoreCountry } from "../api/regions"
 import {
   completeCart,
   updateCart,
@@ -42,7 +43,7 @@ import { isStripeLike } from "../lib/payment-constants"
 import compareAddresses from "./compare-addresses"
 import { translateAddressError } from "./address-error-copy"
 import { translatePaymentError } from "./payment-error-copy"
-import { useOrderConfirmedPath } from "./context"
+import { useCheckoutLabels, useOrderConfirmedPath } from "./context"
 import type { EcontOffice } from "./econt-office-selector"
 import type { BoxNowLocker } from "../api/integrations"
 
@@ -267,6 +268,9 @@ export function useCheckoutOrchestration({
   logError: logErrorProp,
   debug = false,
 }: UseCheckoutOrchestrationOptions) {
+  // The store's language, for the sentences a shopper reads when a save
+  // fails. English unless a locale pack is mounted above.
+  const checkoutLabels = useCheckoutLabels()
   // The default sink: the platform's own checkout error log. Browser money
   // failures (Stripe confirm errors, failed 3DS returns, place-order
   // rejections) land in checkout_error_logs step `browser` with no merchant
@@ -359,17 +363,54 @@ export function useCheckoutOrchestration({
       : true
   )
 
-  // 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.
+  /**
+   * The store's own country list, fetched when the app did not pass one.
+   *
+   * Until 2026-09-13 an app that passed nothing got a ONE-ENTRY list built
+   * from `countryCode`, and the address form renders a read-only box for a
+   * single entry, so every scaffolded store shipped a checkout offering
+   * exactly one country that the shopper could not change. The list is the
+   * platform's to answer (`GET /api/store/countries`: the store's Markets
+   * when it has declared any, the whole catalogue when it has not), so the
+   * hook asks instead of guessing.
+   *
+   * A failure here must never block a checkout: the `countryCode` fallback
+   * below still stands, and the error is reported through `logError`.
+   */
+  const [storeCountries, setStoreCountries] = useState<StoreCountry[] | null>(null)
+  const appSuppliedCountries = !!(countries && countries.length)
+
+  useEffect(() => {
+    if (appSuppliedCountries) return
+    let alive = true
+    listCountries(client)
+      .then((res) => {
+        if (alive) setStoreCountries(res.countries)
+      })
+      .catch((e: unknown) => {
+        logError(
+          "country_list_failed",
+          e instanceof Error ? e.message : "could not load the country list"
+        )
+      })
+    return () => {
+      alive = false
+    }
+  }, [client, appSuppliedCountries, logError])
+
+  // The app's own list wins, then the store's, then the single-country
+  // fallback. This is the authority for both the select options and the
+  // saved-address region filter.
   const regionCountries = useMemo(
     () =>
       countries && countries.length
         ? countries
-        : countryCode
-          ? [{ iso_2: countryCode, display_name: "" }]
-          : [],
-    [countries, countryCode]
+        : storeCountries && storeCountries.length
+          ? storeCountries
+          : countryCode
+            ? [{ iso_2: countryCode, display_name: "" }]
+            : [],
+    [countries, storeCountries, countryCode]
   )
 
   const countriesInRegion = useMemo(
@@ -578,12 +619,11 @@ export function useCheckoutOrchestration({
           postal_code: formData["shipping_address.postal_code"] || null,
         }
       )
-      // Translate to Bulgarian — the raw error.message is technical
-      // English (or a validation envelope). Neither is acceptable to
-      // show a Bulgarian shopper at the moment of failure. Unknown
-      // errors get the generic fallback rather than half-translated
-      // text.
-      setAddressError(translateAddressError(errObj ?? e))
+      // Into the store's own language. The raw error.message is technical
+      // English or a validation envelope, and neither is acceptable to
+      // show a shopper at the moment of failure. Unknown errors get the
+      // generic sentence rather than half-translated text.
+      setAddressError(translateAddressError(errObj ?? e, checkoutLabels.addressErrors))
     } finally {
       setAddressSaving(false)
       addressSavingRef.current = false
@@ -1079,7 +1119,7 @@ export function useCheckoutOrchestration({
 
     if (redirectStatus === "succeeded") {
       placeOrder().catch((err: unknown) => {
-        const translated = translatePaymentError(err, "card")
+        const translated = translatePaymentError(err, "card", checkoutLabels.paymentErrors)
         setPaymentError(translated)
         logError?.(
           "place_order_error",

package/src/common/country-flag.tsx

@@ -0,0 +1,52 @@
+import "flag-icons/css/flag-icons.min.css"
+
+import { cn } from "../lib/utils"
+
+/**
+ * A country's flag, from its ISO-3166 alpha-2 code.
+ *
+ * WHY A SPRITE AND NOT AN EMOJI: the emoji flag (🇧🇬) costs nothing and is
+ * the obvious choice, but Windows ships no flag glyphs in Segoe UI Emoji, so
+ * a Windows shopper reads the two letters "BG" instead of a flag. `flag-icons`
+ * is SVG under a CSS class, so it renders identically on every platform. It is
+ * also the same sprite the Cartbase admin draws its flags with, so a merchant
+ * sees one country treatment across the admin and their storefront.
+ *
+ * The aspect ratio is the sprite's own 4:3, sized in `em` so a flag matches
+ * the text it sits beside at any font size.
+ *
+ * Decorative by default: a flag never carries meaning a shopper cannot get
+ * from the name next to it, so it is `aria-hidden` and screen readers read
+ * the name. Pass `title` for a tooltip when the flag stands alone.
+ */
+export function CountryFlag({
+  code,
+  title,
+  className,
+}: {
+  /** ISO-3166 alpha-2, any case. Unknown or empty renders a neutral placeholder. */
+  code: string | null | undefined
+  title?: string
+  className?: string
+}) {
+  const iso2 = code?.trim().toLowerCase()
+
+  // A placeholder rather than nothing: the box holds its space, so a field
+  // does not jump when a shopper picks their country.
+  if (!iso2 || !/^[a-z]{2}$/.test(iso2)) {
+    return (
+      <span
+        className={cn("inline-block w-[1.33em] h-[1em] rounded-[2px] bg-muted", className)}
+        aria-hidden
+      />
+    )
+  }
+
+  return (
+    <span
+      className={cn(`fi fi-${iso2}`, "inline-block w-[1.33em] h-[1em] rounded-[2px] shrink-0", className)}
+      title={title}
+      aria-hidden
+    />
+  )
+}

package/src/common/index.ts

@@ -8,6 +8,7 @@ export { LocalizedLink, type LocalizedLinkProps } from "./localized-link"
 export { CartButton } from "./cart-button"
 export { CartButtonClient } from "./cart-button-client"
 export { DeleteButton, type DeleteButtonProps } from "./delete-button"
+export { CountryFlag } from "./country-flag"
 export { CountrySelect, type CountrySelectProps } from "./country-select"
 export {
   LanguageSelect,