@cartbase/storefront 0.9.0 → 0.10.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

@@ -42,7 +42,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 +267,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
@@ -578,12 +581,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 +1081,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",