@cartbase/storefront 0.17.0 → 0.18.0

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

@@ -1,154 +1,154 @@
-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)
-}
+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)
+}

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

@@ -1,91 +1,91 @@
-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)
-}
+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)
+}