@cartbase/storefront 0.9.0 → 0.10.0

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

@@ -1,269 +1,154 @@
-/**
- * Translates payment / order-completion errors into user-friendly
- * Bulgarian copy for the checkout payment surface.
- *
- * Ported from `@1click/ui/src/checkout/payment-error-copy.ts` (v2.3.1) and
- * adapted to the Cartbase error envelope: the store API throws `StoreApiError`
- * with a STRUCTURED `code` (docs/storefront/checkout.md lists every code per
- * endpoint), so translation is **code-first** — the substring patterns from
- * the Medusa era are kept as the fallback layer for Stripe.js browser errors
- * (which have no Cartbase code) and any legacy wire.
- *
- * Why this exists: Stripe and API errors are technical English strings
- * ("Your card's security code is incorrect.", "fetch failed"). Showing them
- * to a Bulgarian shopper at the moment of payment failure is the worst UX
- * surface possible — it looks like the site is broken, not like the customer
- * made a typo. Unknown errors get the generic fallback — showing a
- * half-translated message is worse than a clean fallback.
- */
-
-type ErrorContext = "card" | "cod"
-
-const GENERIC_CARD =
-  "Плащането не може да бъде обработено в момента. Моля, опитайте отново или изберете друг метод на плащане."
-
-const GENERIC_COD =
-  "Поръчката не може да бъде финализирана в момента. Моля, опитайте отново след малко."
-
-/**
- * Cartbase store-API error codes → BG copy. Covers EVERY code documented for
- * POST /api/store/carts/:id/complete, prepare-checkout,
- * sync-payment-amount and refresh-payment-if-terminal
- * (docs/storefront/checkout.md + carts.completeCart JSDoc). Code-first:
- * matched before any substring pattern.
- */
-export const PAYMENT_ERROR_CODE_COPY: Record<string, string> = {
-  // — complete: validation family (400) —
-  cart_email_required:
-    "Въведете имейл адрес, за да завършите поръчката.",
-  cart_empty: "Количката е празна. Добавете продукти, за да продължите.",
-  shipping_address_required:
-    "Въведете адрес за доставка, за да завършите поръчката.",
-  shipping_method_required:
-    "Изберете метод на доставка преди да продължите.",
-  payment_collection_required:
-    "Плащането не е подготвено. Моля, опитайте отново.",
-  payment_session_required:
-    "Плащането не е подготвено. Моля, опитайте отново.",
-  insufficient_inventory:
-    "Един от продуктите вече не е наличен в избраното количество. Моля, обновете количката.",
-  // — checkout-rules security boundary (400) —
-  checkout_method_hidden:
-    "Избраният метод вече не е наличен за тази поръчка. Моля, изберете друг метод и опитайте отново.",
-  // — payment family (402) —
-  requires_action:
-    "Банката изисква допълнително потвърждение. Моля, следвайте инструкциите.",
-  payment_not_authorized:
-    "Плащането не беше одобрено. Моля, опитайте отново или изберете друг метод.",
-  payment_not_initiated:
-    "Сесията за плащане е изтекла. Моля, презаредете страницата и опитайте отново.",
-  payment_incomplete:
-    "Картите за подарък вече не покриват цялата сума. Моля, изберете начин на плащане за остатъка.",
-  gift_card_insufficient_balance:
-    "Наличността по картата за подарък вече не е достатъчна. Моля, премахнете я или изберете друг начин на плащане.",
-  gift_card_not_redeemable:
-    "Картата за подарък вече не може да бъде използвана. Моля, премахнете я и опитайте отново.",
-  // — access / concurrency —
-  account_required:
-    "За да завършите поръчката, е необходимо да влезете в профила си.",
-  cart_locked:
-    "Поръчката се обработва в момента. Моля, изчакайте няколко секунди.",
-  cart_completed:
-    "Тази поръчка вече беше финализирана. Моля, проверете имейла си за потвърждение.",
-  cart_not_found: "Сесията на количката изтече. Моля, презаредете страницата.",
-  // — prepare-checkout family —
-  shipping_option_not_found:
-    "Избраният метод на доставка вече не е наличен. Моля, изберете друг.",
-  invalid_provider:
-    "Избраният начин на плащане не е валиден. Моля, изберете друг метод.",
-  shipping_price_missing:
-    "Цената за доставка не може да бъде определена. Моля, изберете друг метод на доставка.",
-  stripe_not_configured:
-    "Плащането с карта временно не е налично. Моля, изберете друг метод.",
-  validation_failed:
-    "Данните за поръчката са непълни. Моля, проверете формата и опитайте отново.",
-}
-
-/**
- * Gift-card apply/remove codes → BG copy (POST/DELETE
- * /api/store/carts/:id/gift-cards — docs/storefront/gift-cards.md).
- * The API deliberately answers unknown/disabled/expired/depleted/foreign
- * codes with ONE generic `invalid_gift_card` (no code-existence oracle) —
- * the copy mirrors that: one honest generic message.
- */
-export const GIFT_CARD_ERROR_CODE_COPY: Record<string, string> = {
-  invalid_gift_card:
-    "Кодът на картата за подарък не е валиден. Моля, проверете изписването.",
-  rate_limited:
-    "Твърде много опити. Моля, изчакайте няколко минути и опитайте отново.",
-  cart_completed:
-    "Поръчката вече е финализирана. Моля, проверете имейла си за потвърждение.",
-  cart_not_found: "Сесията на количката изтече. Моля, презаредете страницата.",
-  validation_failed:
-    "Невалиден код. Моля, проверете изписването и опитайте отново.",
-}
-
-const GIFT_CARD_GENERIC =
-  "Картата за подарък не може да бъде приложена в момента. Моля, опитайте отново."
-
-/**
- * Map of Stripe error codes / decline codes / common substrings to BG copy.
- * Substring match is case-insensitive. First match wins, so order from
- * most-specific to most-generic. Kept verbatim from the production port —
- * Stripe.js browser errors carry no Cartbase `code`, so this layer still does
- * the heavy lifting on the card path.
- *
- * Stripe error code reference:
- * https://docs.stripe.com/error-codes
- */
-const STRIPE_PATTERNS: Array<{ match: RegExp; copy: string }> = [
-  // Card declined — generic
-  {
-    match: /card[\s_-]?declined|card_declined/i,
-    copy: "Картата е отказана от банката. Моля, опитайте с друга карта или се свържете с банката си.",
-  },
-  // Insufficient funds
-  {
-    match: /insufficient[\s_]?funds/i,
-    copy: "Недостатъчна наличност по картата. Моля, опитайте с друга карта.",
-  },
-  // Expired card
-  {
-    match: /expired[\s_]?card|card[\s_]?has[\s_]?expired/i,
-    copy: "Картата е изтекла. Моля, опитайте с друга карта.",
-  },
-  // Wrong CVC / security code
-  {
-    match: /incorrect[\s_]?cvc|invalid[\s_]?cvc|cvc[\s_]?check/i,
-    copy: "Невалиден код за сигурност (CVC). Моля, проверете трите цифри на гърба на картата.",
-  },
-  // Wrong card number
-  {
-    match: /incorrect[\s_]?number|invalid[\s_]?number/i,
-    copy: "Невалиден номер на карта. Моля, проверете цифрите.",
-  },
-  // Wrong / invalid expiry
-  {
-    match: /invalid[\s_]?expir|incorrect[\s_]?expir/i,
-    copy: "Невалидна дата на изтичане. Моля, проверете месеца и годината.",
-  },
-  // 3DS / authentication required
-  {
-    match: /authentication[\s_]?required|3d[\s_]?secure/i,
-    copy: "Банката изисква допълнително потвърждение. Моля, следвайте инструкциите.",
-  },
-  // Processing error
-  {
-    match: /processing[\s_]?error/i,
-    copy: "Грешка при обработка на картата. Моля, опитайте отново след малко.",
-  },
-  // Rate limit
-  {
-    match: /rate[\s_]?limit/i,
-    copy: "Твърде много опити за плащане. Моля, изчакайте няколко минути и опитайте отново.",
-  },
-  // Terminal-state PI (the bug class refresh-payment-if-terminal heals)
-  {
-    match: /terminal[\s_]?state|payment[\s_]?intent[\s_]?(?:is|in)[\s_]?(?:a[\s_]?)?terminal/i,
-    copy: "Сесията за плащане е изтекла. Моля, презаредете страницата и опитайте отново.",
-  },
-  // Amount mismatch — happens when cart total drifts from PI amount
-  {
-    match: /amount[\s_]?mismatch|amount[\s_]?does[\s_]?not[\s_]?match/i,
-    copy: "Сумата на поръчката се промени. Моля, презаредете страницата и опитайте отново.",
-  },
-  // Network / fetch failure
-  {
-    match: /failed[\s_]?to[\s_]?fetch|network[\s_]?error|networkerror/i,
-    copy: "Няма връзка със сървъра. Моля, проверете интернет връзката и опитайте отново.",
-  },
-]
-
-/** Legacy Medusa-era API substrings — kept as the last fallback layer. */
-const API_PATTERNS: Array<{ match: RegExp; copy: string }> = [
-  // Cart already completed — likely a double-submit racing through
-  {
-    match: /cart[\s_]?(?:is[\s_]?)?already[\s_]?completed|already[\s_]?an[\s_]?order/i,
-    copy: "Тази поръчка вече беше финализирана. Моля, проверете имейла си за потвърждение.",
-  },
-  // Out of stock
-  {
-    match: /not[\s_]?enough[\s_]?stock|insufficient[\s_]?stock|out[\s_]?of[\s_]?stock|insufficient[\s_]?inventory/i,
-    copy: "Един от продуктите вече не е наличен в избраното количество. Моля, обновете количката.",
-  },
-  // Region / country mismatch
-  {
-    match: /no[\s_]?region|invalid[\s_]?region/i,
-    copy: "Регионът на доставка не е валиден. Моля, презаредете страницата.",
-  },
-  // No shipping method
-  {
-    match: /no[\s_]?shipping[\s_]?method|shipping[\s_]?method[\s_]?not[\s_]?found/i,
-    copy: "Изберете метод на доставка преди да продължите.",
-  },
-]
-
-/** Pull the structured Cartbase error code out of any thrown value. */
-function extractCode(err: unknown): string | null {
-  if (err && typeof err === "object") {
-    const code = (err as { code?: unknown }).code
-    if (typeof code === "string" && code.length > 0) return code
-  }
-  return null
-}
-
-/**
- * Translate any thrown / returned error into customer-facing Bulgarian.
- * Code-first (Cartbase `StoreApiError.code`), then Stripe substring patterns,
- * then legacy API substrings, then the per-context generic.
- *
- * @param err - the error from a try/catch or a Stripe error response
- * @param context - "card" for Stripe path, "cod" for manual path
- */
-export function translatePaymentError(
-  err: unknown,
-  context: ErrorContext
-): string {
-  const code = extractCode(err)
-  if (code && PAYMENT_ERROR_CODE_COPY[code]) return PAYMENT_ERROR_CODE_COPY[code]
-
-  const raw = extractMessage(err)
-  if (!raw) return context === "card" ? GENERIC_CARD : GENERIC_COD
-
-  for (const { match, copy } of STRIPE_PATTERNS) {
-    if (match.test(raw)) return copy
-  }
-  for (const { match, copy } of API_PATTERNS) {
-    if (match.test(raw)) return copy
-  }
-  return context === "card" ? GENERIC_CARD : GENERIC_COD
-}
-
-/**
- * Translate a gift-card apply/remove failure into customer-facing Bulgarian.
- * Consumed by `GiftCardSection`. Code-first; falls back to one clean generic
- * (the API's anti-oracle design means there is nothing more specific to say).
- */
-export function translateGiftCardError(err: unknown): string {
-  const code = extractCode(err)
-  if (code && GIFT_CARD_ERROR_CODE_COPY[code]) return GIFT_CARD_ERROR_CODE_COPY[code]
-  return GIFT_CARD_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
-      decline_code?: string
-      type?: string
-    }
-    return [e.message, e.code, e.decline_code, e.type]
-      .filter(Boolean)
-      .join(" ")
-  }
-  return String(err)
-}
+import { GIFT_CARD_CODE_KEYS, PAYMENT_CODE_KEYS } from "./error-copy-codes"
+import type { GiftCardErrorCopy, PaymentErrorCopy } from "./labels"
+
+/**
+ * Recognizes a payment or order-completion failure and picks the copy key
+ * for it.
+ *
+ * THE COPY IS NOT HERE ANY MORE. Until 2026-09-13 this file held 47
+ * hardcoded BULGARIAN sentences, so every merchant who installed the
+ * package showed Bulgarian at the exact moment a payment failed, with no
+ * override. The words now live in the checkout label pack: English by
+ * default, translated by whichever locale the store mounts.
+ *
+ * WHY THIS LAYER EXISTS AT ALL: Stripe and API errors are technical
+ * English ("Your card's security code is incorrect.", "fetch failed").
+ * Showing that to a shopper makes the site look broken rather than making
+ * it look like they mistyped a digit. Unknown errors get the per-context
+ * generic, because a half-translated technical string is worse than a
+ * clean one.
+ *
+ * Recognition is CODE-FIRST — the store API throws `StoreApiError` with a
+ * structured `code` (docs/storefront/checkout.md lists every code per
+ * endpoint) — then the Stripe substring patterns, which still do the heavy
+ * lifting on the card path because Stripe.js browser errors carry no
+ * Cartbase code, then the legacy Medusa-era substrings.
+ *
+ * The patterns stay in English on purpose: they match the wire, not the
+ * shopper.
+ */
+
+export type ErrorContext = "card" | "cod"
+
+/**
+ * Stripe error codes, decline codes and common substrings. Matched
+ * case-insensitively, first match wins, so the order runs most specific to
+ * most generic. Kept verbatim from the production port.
+ *
+ * Stripe error code reference: https://docs.stripe.com/error-codes
+ */
+const STRIPE_PATTERNS: Array<{ match: RegExp; key: keyof PaymentErrorCopy }> = [
+  { match: /card[\s_-]?declined|card_declined/i, key: "cardDeclined" },
+  { match: /insufficient[\s_]?funds/i, key: "insufficientFunds" },
+  { match: /expired[\s_]?card|card[\s_]?has[\s_]?expired/i, key: "expiredCard" },
+  { match: /incorrect[\s_]?cvc|invalid[\s_]?cvc|cvc[\s_]?check/i, key: "incorrectCvc" },
+  { match: /incorrect[\s_]?number|invalid[\s_]?number/i, key: "incorrectCardNumber" },
+  { match: /invalid[\s_]?expir|incorrect[\s_]?expir/i, key: "invalidExpiry" },
+  { match: /authentication[\s_]?required|3d[\s_]?secure/i, key: "authenticationRequired" },
+  { match: /processing[\s_]?error/i, key: "processingError" },
+  { match: /rate[\s_]?limit/i, key: "rateLimited" },
+  // Terminal-state payment intent: the bug class refresh-payment-if-terminal heals.
+  {
+    match: /terminal[\s_]?state|payment[\s_]?intent[\s_]?(?:is|in)[\s_]?(?:a[\s_]?)?terminal/i,
+    key: "paymentExpired",
+  },
+  // Amount mismatch: the cart total drifted from the payment intent's amount.
+  { match: /amount[\s_]?mismatch|amount[\s_]?does[\s_]?not[\s_]?match/i, key: "amountMismatch" },
+  { match: /failed[\s_]?to[\s_]?fetch|network[\s_]?error|networkerror/i, key: "networkError" },
+]
+
+/** Legacy Medusa-era API substrings, the last fallback layer. */
+const API_PATTERNS: Array<{ match: RegExp; key: keyof PaymentErrorCopy }> = [
+  {
+    match: /cart[\s_]?(?:is[\s_]?)?already[\s_]?completed|already[\s_]?an[\s_]?order/i,
+    key: "cartAlreadyCompleted",
+  },
+  {
+    match:
+      /not[\s_]?enough[\s_]?stock|insufficient[\s_]?stock|out[\s_]?of[\s_]?stock|insufficient[\s_]?inventory/i,
+    key: "outOfStock",
+  },
+  { match: /no[\s_]?region|invalid[\s_]?region/i, key: "invalidRegion" },
+  {
+    match: /no[\s_]?shipping[\s_]?method|shipping[\s_]?method[\s_]?not[\s_]?found/i,
+    key: "shippingMethodMissing",
+  },
+]
+
+/** Pull the structured Cartbase error code out of any thrown value. */
+function extractCode(err: unknown): string | null {
+  if (err && typeof err === "object") {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && code.length > 0) return code
+  }
+  return null
+}
+
+/** Which copy this failure asks for, independent of language. */
+export function paymentErrorKey(
+  err: unknown,
+  context: ErrorContext
+): keyof PaymentErrorCopy {
+  const generic = context === "card" ? "genericCard" : "genericCod"
+
+  const code = extractCode(err)
+  if (code && PAYMENT_CODE_KEYS[code]) return PAYMENT_CODE_KEYS[code]
+
+  const raw = extractMessage(err)
+  if (!raw) return generic
+
+  for (const { match, key } of STRIPE_PATTERNS) if (match.test(raw)) return key
+  for (const { match, key } of API_PATTERNS) if (match.test(raw)) return key
+  return generic
+}
+
+/**
+ * Turn any thrown or returned payment error into the sentence a shopper
+ * reads, in the store's own language.
+ *
+ * @param err - the error from a try/catch or a Stripe error response
+ * @param context - "card" for the Stripe path, "cod" for the manual path
+ * @param copy - the store's payment copy (`labels.paymentErrors`)
+ */
+export function translatePaymentError(
+  err: unknown,
+  context: ErrorContext,
+  copy: PaymentErrorCopy
+): string {
+  return copy[paymentErrorKey(err, context)]
+}
+
+/** Which gift-card copy this failure asks for. */
+export function giftCardErrorKey(err: unknown): keyof GiftCardErrorCopy {
+  const code = extractCode(err)
+  if (code && GIFT_CARD_CODE_KEYS[code]) return GIFT_CARD_CODE_KEYS[code]
+  return "generic"
+}
+
+/**
+ * Turn a gift-card apply or remove failure into the shopper's sentence.
+ * Code-first, falling back to one clean generic: the API's anti-oracle
+ * design means there is deliberately nothing more specific to say.
+ */
+export function translateGiftCardError(
+  err: unknown,
+  copy: GiftCardErrorCopy
+): string {
+  return copy[giftCardErrorKey(err)]
+}
+
+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
+      decline_code?: string
+      type?: string
+    }
+    return [e.message, e.code, e.decline_code, e.type].filter(Boolean).join(" ")
+  }
+  return String(err)
+}