@cartbase/storefront 0.1.0

package/src/checkout/payment-button.tsx

@@ -0,0 +1,373 @@
+"use client"
+
+import { useElements, useStripe } from "@stripe/react-stripe-js"
+import { useContext, useEffect, useRef, useState } from "react"
+
+import { DualPrice } from "../lib/dual-price"
+import { cn } from "../lib/utils"
+import { translatePaymentError } from "./payment-error-copy"
+import { useCheckoutLabels } from "./context"
+import { ErrorMessage } from "./error-message"
+import { StripeContext } from "./stripe-wrapper"
+import type { CheckoutLogError } from "./use-checkout-orchestration"
+
+/** Cycle interval for the processing-state messages, in ms. */
+const PROCESSING_MESSAGE_INTERVAL_MS = 1800
+
+/**
+ * PaymentButton — top-level "place order" button.
+ *
+ * Ported from `@1click/ui/src/checkout/payment-button.tsx` (v2.3.1) with
+ * the barter data seam: the `cart` prop is structural (only `id`, `total`,
+ * `currency_code` are read — any decorated barter cart satisfies it), and
+ * the `logCheckoutError` Supabase writer becomes the optional `logError`
+ * callback (barter has no store-side log endpoint; every production log
+ * point is preserved through the callback).
+ *
+ * The button delegates entirely to the orchestration hook's
+ * `performBuyClick` callback. It knows NOTHING about how the order is
+ * placed; it just gathers the local Stripe primitives (when on the card
+ * tab) and hands them off.
+ *
+ * The flow that runs on click:
+ *   1. orchestration.performBuyClick({ submit, stripe, elements })
+ *      - flushAddressSave()
+ *      - (card) elements.submit()
+ *      - prepareCheckout(...)         ← writes everything atomically
+ *      - (card) stripe.confirmPayment ← may redirect for 3DS; SKIPPED on
+ *        the zero-remainder gift path (docs/storefront/gift-cards.md)
+ *      - placeOrder()                 ← POST /api/store/carts/:id/complete
+ *
+ * The button is always rendered inside `<StripeElementsScope>` so
+ * `useStripe()`/`useElements()` resolve when the scope is active. On
+ * COD-only carts (no Stripe key) the scope passes through and the
+ * stripe/elements hooks return null — the COD path skips all Stripe
+ * work, so that's fine.
+ */
+
+type BuyClickStripeBundle = {
+  submit: () => Promise<{ error?: { message?: string } | null }>
+  stripe: {
+    confirmPayment: (args: {
+      elements: unknown
+      clientSecret: string
+      confirmParams: { return_url: string }
+      redirect: "if_required"
+    }) => Promise<{ error?: { message?: string } | null }>
+  }
+  elements: unknown
+}
+
+type PaymentButtonProps = {
+  /** Structural cart — only `id`, `total`, `currency_code` are read. */
+  cart: { id: string; total?: number | null; currency_code: string }
+  paymentTab: "card" | "cod"
+  notReady: boolean
+  performBuyClick: (stripeBundle?: BuyClickStripeBundle) => Promise<void>
+  /**
+   * Set to the live `event.complete` boolean from Stripe's
+   * `<PaymentElement onChange>`. When `false` on the card path, the Buy
+   * button stays disabled even when cart-level prerequisites are met,
+   * preventing the click → cryptic "Could not retrieve elements store"
+   * failure when the user hasn't filled in payment details.
+   *
+   * Ignored on the COD path. Defaults to `true`.
+   */
+  paymentElementComplete?: boolean
+  /**
+   * Display total in main currency units. Pass `useCheckoutOrchestration`'s
+   * `optimisticTotal` so the button reflects the same number the order
+   * summary shows, even pre-Buy when shipping & COD fee aren't on the
+   * cart yet. Falls back to `cart.total` for callers that haven't wired
+   * it up.
+   */
+  total?: number
+  /** Operational-visibility sink (successor of @1click's logCheckoutError). */
+  logError?: CheckoutLogError
+  "data-testid"?: string
+}
+
+function OrderButton({
+  onClick,
+  disabled,
+  loading,
+  total,
+  currencyCode,
+  testId,
+  label,
+}: {
+  onClick: () => void
+  disabled: boolean
+  loading: boolean
+  total?: number
+  currencyCode?: string
+  testId?: string
+  label: string
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      data-testid={testId}
+      className={cn(
+        "w-full h-14 bg-foreground text-card text-base font-semibold rounded-xl",
+        "flex items-center justify-center gap-2.5 transition-all",
+        "hover:bg-foreground/90 active:scale-[0.99]",
+        "disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-foreground"
+      )}
+    >
+      {loading ? (
+        <svg className="w-5 h-5 animate-spin" fill="none" viewBox="0 0 24 24">
+          <circle
+            className="opacity-25"
+            cx="12"
+            cy="12"
+            r="10"
+            stroke="currentColor"
+            strokeWidth="3"
+          />
+          <path
+            className="opacity-75"
+            fill="currentColor"
+            d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+          />
+        </svg>
+      ) : (
+        <>
+          <svg
+            className="w-4 h-4"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+            />
+          </svg>
+          <span className="inline-flex items-center gap-1.5">
+            {label}
+            {total !== undefined && currencyCode && (
+              <span className="inline-flex items-center gap-1">
+                <span aria-hidden="true"> · </span>
+                <DualPrice
+                  amount={total}
+                  currencyCode={currencyCode}
+                  className="font-semibold"
+                  bgnClassName="text-card/70 text-[11px] ml-1"
+                />
+              </span>
+            )}
+          </span>
+        </>
+      )}
+    </button>
+  )
+}
+
+export function PaymentButton({
+  cart,
+  paymentTab,
+  notReady,
+  performBuyClick,
+  paymentElementComplete = true,
+  total,
+  logError,
+  "data-testid": dataTestId,
+}: PaymentButtonProps) {
+  const labels = useCheckoutLabels()
+  const stripeReady = useContext(StripeContext)
+  // `useStripe()`/`useElements()` THROW when no <Elements> provider is
+  // mounted — which is the documented state on COD/pp_manual-only stores
+  // without Stripe credentials (`StripeElementsScope` passthrough mode,
+  // components.md). Tolerate the missing scope: null here is equivalent
+  // to "Stripe not ready", and the card path is additionally gated by
+  // `stripeReady`. Hook order stays stable across renders because the
+  // provider's presence is fixed per mount (module-level Stripe key).
+  let stripe: ReturnType<typeof useStripe> = null
+  let elements: ReturnType<typeof useElements> = null
+  try {
+    stripe = useStripe()
+    elements = useElements()
+  } catch {
+    // no Elements scope (COD-only store) — proceed with stripe = null
+  }
+  const [submitting, setSubmitting] = useState(false)
+  const [errorMessage, setErrorMessage] = useState<string | null>(null)
+
+  // ── Processing-state cycling messages ───────────────────────────────
+  // While `submitting` is true, cycle through a short list of messages
+  // narrating what's actually happening server-side. Loops back to 0
+  // on long flows (3DS challenges, slow networks). Card and COD have
+  // separate sequences because the card path includes a bank handshake
+  // step that doesn't apply to COD.
+  //
+  // Why this exists: a spinning button alone reads as "thinking" but
+  // not "thinking about WHAT" — customers get nervous on the 3-30s
+  // wait. Stripe / Booking.com / Apple Pay all narrate the same way.
+  // Trust > novelty during the moment money leaves the account.
+  const [messageIndex, setMessageIndex] = useState(0)
+  useEffect(() => {
+    if (!submitting) {
+      setMessageIndex(0)
+      return
+    }
+    const messages =
+      paymentTab === "card" ? labels.processingCard : labels.processingCod
+    if (!messages || messages.length === 0) return
+    const id = setInterval(() => {
+      setMessageIndex((i) => (i + 1) % messages.length)
+    }, PROCESSING_MESSAGE_INTERVAL_MS)
+    return () => clearInterval(id)
+  }, [submitting, paymentTab, labels.processingCard, labels.processingCod])
+
+  const processingMessages =
+    paymentTab === "card" ? labels.processingCard : labels.processingCod
+  const currentProcessingMessage =
+    submitting && processingMessages?.length
+      ? processingMessages[messageIndex % processingMessages.length]
+      : null
+
+  // Hard re-entry guard. `submitting` state alone isn't enough: React
+  // batches state updates so two synchronous clicks both pass the
+  // submitting check before the first one's setState commits. A ref
+  // flips synchronously and blocks the second click cold.
+  const inFlightRef = useRef(false)
+
+  const isCardPath = paymentTab === "card"
+  const cardReady = !isCardPath || (stripeReady && !!stripe && !!elements)
+  const cardComplete = !isCardPath || paymentElementComplete
+
+  const disabled = notReady || !cardReady || !cardComplete || submitting
+
+  const handleClick = async () => {
+    if (inFlightRef.current) return
+    inFlightRef.current = true
+    setSubmitting(true)
+    setErrorMessage(null)
+
+    try {
+      const stripeBundle: BuyClickStripeBundle | undefined =
+        isCardPath && stripe && elements
+          ? {
+              submit: () => elements.submit(),
+              stripe: stripe as unknown as BuyClickStripeBundle["stripe"],
+              elements,
+            }
+          : undefined
+
+      await performBuyClick(stripeBundle)
+
+      // performBuyClick navigates on success (placeOrder →
+      // window.location.assign / the host's onOrderPlaced router push).
+      // If we get here without a navigation Stripe returned a
+      // non-terminal status (processing, requires_action without
+      // auto-redirect, etc.) — release the lock so the user can retry.
+      inFlightRef.current = false
+      setSubmitting(false)
+    } catch (err: unknown) {
+      // Next.js's `redirect()` throws a NEXT_REDIRECT error — that is
+      // success, not failure. The barter default path navigates via
+      // window.location.assign (no throw), but a store routing
+      // `onOrderPlaced` through a server action still hits this; don't
+      // translate it — let it propagate so the navigation happens.
+      const e = err as {
+        digest?: string
+        message?: string
+        type?: string
+        code?: string
+        decline_code?: string
+        name?: string
+        stack?: string
+      }
+      const isNextRedirect =
+        typeof e?.digest === "string" && e.digest.startsWith("NEXT_REDIRECT")
+      if (isNextRedirect) {
+        throw err
+      }
+
+      // eslint-disable-next-line no-console
+      console.error("[buy-click] FAILED", {
+        message: e?.message,
+        raw: err,
+      })
+
+      // Operational sink so the actual error is readable without needing
+      // the customer's browser console. This is the catch-all for any
+      // error that escapes performBuyClick (stripe.confirmPayment,
+      // prepareCheckout, placeOrder).
+      let dump = ""
+      try {
+        dump = JSON.stringify(err, Object.getOwnPropertyNames(err as object)).slice(
+          0,
+          2000
+        )
+      } catch {
+        dump = String(err)
+      }
+      logError?.(
+        "place_order_error",
+        e?.message ?? String(err) ?? "unknown",
+        {
+          path: isCardPath ? "card" : "cod",
+          err_name: e?.name,
+          err_type: e?.type,
+          err_code: e?.code,
+          decline_code: e?.decline_code,
+          cart_id: cart.id,
+          full_error_json: dump,
+        }
+      )
+
+      const translated = translatePaymentError(err, isCardPath ? "card" : "cod")
+      setErrorMessage(translated)
+      inFlightRef.current = false
+      setSubmitting(false)
+    }
+  }
+
+  return (
+    <>
+      <OrderButton
+        onClick={handleClick}
+        disabled={disabled}
+        loading={submitting}
+        total={total ?? cart.total ?? undefined}
+        currencyCode={cart.currency_code}
+        testId={dataTestId}
+        label={labels.placeOrder}
+      />
+      {/*
+        Cycling processing message. Fixed-height wrapper prevents layout
+        shift when the message appears/disappears. aria-live="polite"
+        announces each message swap to screen readers.
+        `key={messageIndex}` re-mounts the span on every cycle so
+        Tailwind's animate-in fade-in fires fresh each time.
+      */}
+      <div
+        className="mt-3 h-5 flex items-center justify-center"
+        aria-live="polite"
+      >
+        {currentProcessingMessage && (
+          <span
+            key={messageIndex}
+            className="text-sm text-muted-foreground animate-in fade-in duration-500"
+          >
+            {currentProcessingMessage}
+          </span>
+        )}
+      </div>
+      <ErrorMessage
+        error={errorMessage}
+        data-testid={
+          isCardPath
+            ? "stripe-payment-error-message"
+            : "manual-payment-error-message"
+        }
+      />
+    </>
+  )
+}

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

@@ -0,0 +1,269 @@
+/**
+ * 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 barter 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 barter 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 =
+  "Поръчката не може да бъде финализирана в момента. Моля, опитайте отново след малко."
+
+/**
+ * Barter 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 barter `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 barter 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 (barter `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)
+}