@cartbase/storefront 0.1.0

package/src/checkout/payment-method-list.tsx

@@ -0,0 +1,365 @@
+"use client"
+
+import { PaymentElement } from "@stripe/react-stripe-js"
+import type { StripePaymentElementChangeEvent } from "@stripe/stripe-js"
+import { useContext, useEffect, useState } from "react"
+
+import { cn } from "../lib/utils"
+import { useCheckoutLabels } from "./context"
+import { ErrorMessage } from "./error-message"
+import { PaymentButton } from "./payment-button"
+import { StripeContext, StripeElementsScope } from "./stripe-wrapper"
+import type { CheckoutLogError } from "./use-checkout-orchestration"
+
+/**
+ * CheckoutPaymentMethodList — online-payment vs cash-on-delivery radio
+ * list. The online tab hosts Stripe's `<PaymentElement />` in accordion
+ * layout, which renders every payment method enabled in the Stripe
+ * Dashboard (card, Apple Pay, Google Pay, Link, etc.) without any
+ * per-method code here.
+ *
+ * Ported from `@1click/ui/src/checkout/payment-method-list.tsx` (v2.3.1)
+ * with the barter data seam: the `cart` prop is structural, and the
+ * `logCheckoutError` Supabase writer becomes the optional `logError`
+ * callback. Provider semantics on the barter wire: the "card" tab is
+ * `pp_stripe`, the "cod" tab is `pp_cod` (native fee via the integrations
+ * `cod` block) or `pp_manual` (offline, no fee) — the orchestration hook
+ * resolves the ids (`hasCard`/`hasCod`/`cardId`/`codId`); both listings
+ * arrive rule-filtered server-side (`checkout.listPaymentProviders`,
+ * docs/storefront/checkout.md). COD stays a separate rail — it's a plain
+ * provider session, not a Stripe payment method.
+ */
+
+type CheckoutPaymentMethodListProps = {
+  /** Structural cart — forwarded to PaymentButton (`id`/`total`/`currency_code`). */
+  cart: { id: string; total?: number | null; currency_code: string }
+  hasCard: boolean
+  hasCod: boolean
+  paymentTab: "card" | "cod"
+  onPaymentTab: (tab: "card" | "cod") => void
+  deliveryReady: boolean
+  paymentError: string | null
+  /** Fired when the Stripe PaymentElement's completion state changes.
+   * `complete === true` means the user has filled in valid details for
+   * the currently selected method and the Place Order button can enable. */
+  onPaymentElementChange: (event: {
+    complete: boolean
+    selectedMethod: string | null
+  }) => void
+  /** Buy-click flow from `useCheckoutOrchestration`. Wraps prepareCheckout
+   * → stripe.confirmPayment (card; skipped on the zero-remainder gift
+   * path) → placeOrder. The button collects the local Stripe primitives
+   * and passes them in. */
+  performBuyClick: (stripeBundle?: {
+    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
+  }) => Promise<void>
+  /** True when address + shipping + carrier-destination are all filled.
+   * Needed to gate the Buy button alongside Stripe-element completion. */
+  buyButtonNotReady: boolean
+  /** Why the Buy button is still disabled — drives a short hint under it
+   * so a shopper who's looking at a live, interactive payment section
+   * (see `gatePaymentUntilDelivery={false}`) understands what's missing
+   * instead of reading a greyed button as broken. Only rendered while
+   * `buyButtonNotReady`. Omit / null to show no hint. */
+  buyButtonNotReadyReason?: "address" | "delivery" | null
+  /** Gate the whole payment section behind delivery-readiness (the
+   * classic flow: payment stays dimmed + hidden until a shipping method
+   * is chosen). Default `true` keeps that behavior. Pass `false` to keep
+   * the payment section ALWAYS visible + interactive (Shopify-style
+   * "everything on screen"); the Buy button still can't fire because
+   * `buyButtonNotReady` gates it independently. */
+  gatePaymentUntilDelivery?: boolean
+  /** Optional content rendered directly above the Place Order button. */
+  beforePaymentButton?: React.ReactNode
+  /** Display total in main currency units. Forwarded to `PaymentButton`.
+   * Pass `useCheckoutOrchestration`'s `optimisticTotal` so the button
+   * shows the same number as the order summary. Falls back to
+   * `cart.total` when omitted. */
+  total?: number
+  /** Operational-visibility sink (successor of @1click's logCheckoutError). */
+  logError?: CheckoutLogError
+}
+
+export function CheckoutPaymentMethodList({
+  cart,
+  hasCard,
+  hasCod,
+  paymentTab,
+  onPaymentTab,
+  deliveryReady,
+  paymentError,
+  onPaymentElementChange,
+  performBuyClick,
+  buyButtonNotReady,
+  buyButtonNotReadyReason,
+  gatePaymentUntilDelivery = true,
+  beforePaymentButton,
+  total,
+  logError,
+}: CheckoutPaymentMethodListProps) {
+  const labels = useCheckoutLabels()
+
+  // When the store opts out of gating (gatePaymentUntilDelivery=false),
+  // the payment section is always shown + interactive regardless of
+  // delivery readiness. The Buy button remains independently gated by
+  // `buyButtonNotReady`, so nothing can be submitted early — this only
+  // changes visibility, not the order-placement guard.
+  const paymentGated = gatePaymentUntilDelivery && !deliveryReady
+  // Boolean context — true when Stripe.js is loaded. In deferred-intent
+  // mode, the iframe mounts as soon as Stripe is ready (no PI required).
+  const stripeReady = useContext(StripeContext)
+
+  // Local copy of Stripe's PaymentElement completion flag. Forwarded
+  // to the parent via `onPaymentElementChange` AND used here to gate
+  // the Buy button on the card path.
+  const [paymentElementComplete, setPaymentElementComplete] = useState(false)
+
+  // Reset completion flag on tab change. PaymentElement is unmounted
+  // when paymentTab !== "card" so a re-mount starts empty — without
+  // this reset, switching away then back would leave the button
+  // erroneously enabled from a previous fill.
+  useEffect(() => {
+    setPaymentElementComplete(false)
+  }, [paymentTab])
+
+  const handlePaymentElementChange = (event: StripePaymentElementChangeEvent) => {
+    setPaymentElementComplete(event.complete)
+    onPaymentElementChange({
+      complete: event.complete,
+      selectedMethod: event.value?.type ?? null,
+    })
+  }
+
+  // PaymentElement load error handler — log only.
+  //
+  // In the eager-session model this used to call `refreshPaymentIfTerminal`
+  // because the cart could hold a stale client_secret pointing at a
+  // terminal Stripe PaymentIntent. In the deferred-intent model the PI
+  // is created at Buy click, so there's no stale-PI failure mode at
+  // mount time. We keep the logger to capture any other load issues
+  // (key misconfiguration, network, etc). Stores that mount Elements on
+  // an EXISTING client_secret (retry flows) should call the hook's
+  // `refreshPaymentIfTerminal` from this handler instead — reactively,
+  // never per render (docs/storefront/checkout.md).
+  const handlePaymentElementLoadError = (event: {
+    error?: { message?: string }
+  }) => {
+    const message = event?.error?.message ?? ""
+    if (typeof console !== "undefined") {
+      // eslint-disable-next-line no-console
+      console.warn("[PaymentElement] load error:", message || event)
+    }
+    logError?.("elements_load_error", message, {})
+  }
+
+  return (
+    <div
+      className={cn(
+        "mt-8 transition-opacity duration-300",
+        paymentGated && "opacity-30 pointer-events-none select-none"
+      )}
+    >
+      <h2 className="text-lg font-semibold text-foreground mb-1 tracking-tight">
+        {labels.paymentMethod}
+      </h2>
+      <p className="text-xs text-muted-foreground mb-4">{labels.termsText}</p>
+
+      {paymentGated ? (
+        <div className="p-4 bg-muted rounded-lg border border-border">
+          <p className="text-sm text-muted-foreground">{labels.paymentDisabled}</p>
+        </div>
+      ) : (
+        // ── Stripe Elements scope ──────────────────────────────────────
+        // Wraps the entire interactive payment section (radio cards +
+        // PaymentElement + PaymentButton) so `<PaymentButton>`'s
+        // useStripe()/useElements() hooks find an <Elements> ancestor.
+        //
+        // `passthrough` matters: COD-only carts have no Stripe key, so
+        // <Elements> can't mount. Without passthrough the wrapper would
+        // render `null` (its default fallback) and the COD radio +
+        // PaymentButton would disappear entirely — checkout dead for COD
+        // users. With passthrough, when Stripe isn't ready we render
+        // children directly (no <Elements>); the COD path doesn't use
+        // Stripe hooks so it works fine without context.
+        //
+        // Critically, this scope is INSIDE CheckoutPaymentMethodList,
+        // not at the checkout root. When the payment session rotates
+        // and a new client_secret arrives, only this section remounts
+        // — the orchestration tree, address form, shipping selector,
+        // and tracking refs upstream are NOT torn down. That's the
+        // whole point of moving away from PaymentWrapper-wraps-all.
+        <StripeElementsScope passthrough>
+          <div className="space-y-2">
+            {hasCard && (
+              <div
+                className={cn(
+                  "rounded-lg border overflow-hidden transition-colors duration-150",
+                  paymentTab === "card"
+                    ? "border-primary bg-primary/5"
+                    : "border-border bg-card hover:border-muted-foreground"
+                )}
+              >
+                <button
+                  type="button"
+                  onClick={() => onPaymentTab("card")}
+                  className="flex items-center w-full px-4 py-3.5 text-left"
+                >
+                  <div
+                    className={cn(
+                      "w-[18px] h-[18px] rounded-full border-2 flex items-center justify-center flex-shrink-0 mr-3 transition-colors",
+                      paymentTab === "card" ? "border-primary" : "border-border"
+                    )}
+                  >
+                    {paymentTab === "card" && (
+                      <div className="w-2 h-2 rounded-full bg-primary" />
+                    )}
+                  </div>
+                  <span className="text-sm font-medium text-foreground">
+                    {labels.payOnline}
+                  </span>
+                </button>
+
+                {paymentTab === "card" && (
+                  <div className="px-4 pb-4 pt-2">
+                    {/*
+                      Skeleton vs PaymentElement gated by stripeReady.
+                      When ready=true we're inside <Elements> (outer
+                      passthrough scope mounted it) and PaymentElement
+                      can render. When ready=false (Stripe still
+                      initialising) we show the skeleton — rendering
+                      PaymentElement without an <Elements> ancestor
+                      throws.
+                    */}
+                    {stripeReady ? (
+                      <PaymentElement
+                        onChange={handlePaymentElementChange}
+                        onLoadError={handlePaymentElementLoadError}
+                        options={{
+                          layout: "accordion",
+                          // Intentionally NO `fields.billingDetails.address`
+                          // override. Setting it to "never" puts Stripe into
+                          // strict-completeness mode — every billing-details
+                          // sub-field MUST be passed in confirmParams or it
+                          // throws an IntegrationError naming the first
+                          // missing one (country → state → next). For card-
+                          // only payment methods (Card / Apple Pay / Google
+                          // Pay), Stripe doesn't show address fields by
+                          // default, so dropping the override has zero UI
+                          // impact and eliminates the IntegrationError class
+                          // entirely (production fix 2026-05-06). We still
+                          // pass full billing_details to
+                          // stripe.confirmPayment for AVS / Radar / 3DS
+                          // risk scoring / dispute defense.
+                        }}
+                      />
+                    ) : (
+                      <div className="space-y-2.5 animate-pulse">
+                        <div className="h-[44px] rounded-lg bg-muted" />
+                        <div className="grid grid-cols-2 gap-2.5">
+                          <div className="h-[44px] rounded-lg bg-muted" />
+                          <div className="h-[44px] rounded-lg bg-muted" />
+                        </div>
+                      </div>
+                    )}
+                  </div>
+                )}
+              </div>
+            )}
+
+            {hasCod && (
+              <div
+                className={cn(
+                  "rounded-lg border overflow-hidden transition-colors duration-150",
+                  paymentTab === "cod"
+                    ? "border-primary bg-primary/5"
+                    : "border-border bg-card hover:border-muted-foreground"
+                )}
+              >
+                <button
+                  type="button"
+                  onClick={() => onPaymentTab("cod")}
+                  className="flex items-center w-full px-4 py-3.5 text-left"
+                >
+                  <div
+                    className={cn(
+                      "w-[18px] h-[18px] rounded-full border-2 flex items-center justify-center flex-shrink-0 mr-3 transition-colors",
+                      paymentTab === "cod" ? "border-primary" : "border-border"
+                    )}
+                  >
+                    {paymentTab === "cod" && (
+                      <div className="w-2 h-2 rounded-full bg-primary" />
+                    )}
+                  </div>
+                  <span className="text-sm font-medium text-foreground">
+                    {labels.cashOnDelivery}
+                  </span>
+                </button>
+                {paymentTab === "cod" && (
+                  <div className="px-4 pb-3 pt-0">
+                    <p className="text-xs text-muted-foreground ml-[30px]">
+                      {labels.codNote}
+                    </p>
+                  </div>
+                )}
+              </div>
+            )}
+          </div>
+
+          <ErrorMessage
+            error={paymentError}
+            data-testid="payment-error-message"
+          />
+
+          {beforePaymentButton && (
+            <div className="mt-5">{beforePaymentButton}</div>
+          )}
+
+          {buyButtonNotReady && buyButtonNotReadyReason && (
+            <div className="mt-4 flex items-center justify-center gap-1.5 text-muted-foreground">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth={2}
+                className="w-3.5 h-3.5 flex-shrink-0"
+                aria-hidden="true"
+              >
+                <rect x="5" y="11" width="14" height="10" rx="2" />
+                <path d="M8 11V7a4 4 0 0 1 8 0v4" />
+              </svg>
+              <span className="text-xs font-medium">
+                {buyButtonNotReadyReason === "address"
+                  ? labels.buyNeedsAddress
+                  : labels.buyNeedsDelivery}
+              </span>
+            </div>
+          )}
+
+          <div className="mt-5">
+            <PaymentButton
+              cart={cart}
+              paymentTab={paymentTab}
+              notReady={buyButtonNotReady}
+              performBuyClick={performBuyClick}
+              paymentElementComplete={
+                paymentTab === "cod" ? true : paymentElementComplete
+              }
+              total={total}
+              logError={logError}
+              data-testid="submit-order-button"
+            />
+          </div>
+        </StripeElementsScope>
+      )}
+    </div>
+  )
+}

package/src/checkout/payment-wrapper.tsx

@@ -0,0 +1,102 @@
+"use client"
+
+import type { Appearance, StripeElementsOptions } from "@stripe/stripe-js"
+import { loadStripe } from "@stripe/stripe-js"
+import type { ReactNode } from "react"
+
+import { StripeScopeProvider } from "./stripe-wrapper"
+
+/**
+ * PaymentWrapper — provides Stripe Elements scope context to descendants.
+ *
+ * Ported from `@1click/ui/src/checkout/payment-wrapper.tsx` (v2.3.1).
+ * Barter adaptations: the `cart` prop is the barter `Cart` DTO (only
+ * `currency_code` is read — typed structurally so any decorated cart
+ * satisfies it); env var naming gains `NEXT_PUBLIC_STRIPE_KEY` as the
+ * canonical name, with the Medusa-era fallbacks kept so ported storefronts
+ * keep working unchanged.
+ *
+ * As of the deferred-checkout architecture, this wrapper supplies an
+ * optimistic `amount` + `currency` (computed by the orchestration hook)
+ * to `<Elements>` so the iframe can mount and stay mounted across
+ * shipping/payment toggles. `elements.update({ amount })` keeps the
+ * displayed total in sync without remounting — see stripe-wrapper.tsx
+ * for the deferred-intent rationale.
+ *
+ * Stores mount this at the top of their checkout page:
+ *
+ *   <PaymentWrapper cart={cart} amount={...} appearance={...} fonts={...}>
+ *     <CheckoutClient ... />
+ *   </PaymentWrapper>
+ *
+ * Environment variables (read at module load time):
+ *   - NEXT_PUBLIC_STRIPE_KEY  OR
+ *     NEXT_PUBLIC_MEDUSA_PAYMENTS_PUBLISHABLE_KEY (legacy fallback)
+ *   - NEXT_PUBLIC_MEDUSA_PAYMENTS_ACCOUNT_ID (optional, connect accounts)
+ */
+
+const stripeKey =
+  process.env.NEXT_PUBLIC_STRIPE_KEY ||
+  process.env.NEXT_PUBLIC_MEDUSA_PAYMENTS_PUBLISHABLE_KEY
+
+const stripeAccountId = process.env.NEXT_PUBLIC_MEDUSA_PAYMENTS_ACCOUNT_ID
+
+const stripePromise = stripeKey
+  ? loadStripe(
+      stripeKey,
+      stripeAccountId ? { stripeAccount: stripeAccountId } : undefined
+    )
+  : null
+
+type PaymentWrapperProps = {
+  /** The decorated cart — only `currency_code` is read. */
+  cart: { currency_code?: string | null }
+  /**
+   * Optimistic total in the smallest currency unit (cents/stotinki).
+   * Computed by `useCheckoutOrchestration` (`optimisticTotalCents`) from
+   * the server cart total + optimistic shipping + optimistic COD fee.
+   * Changes to this prop propagate via `elements.update({ amount })`
+   * without remounting.
+   */
+  amount: number
+  /**
+   * Optional per-store Stripe Elements appearance — brand colors, font,
+   * radius, etc. Forwarded to the StripeElementsScope so the
+   * `<Elements>` mount picks it up.
+   */
+  appearance?: Appearance
+  /**
+   * Optional custom fonts for the Stripe Elements iframe. Required
+   * whenever `appearance.variables.fontFamily` references a custom
+   * font — the iframe cannot see the parent document's loaded fonts.
+   */
+  fonts?: StripeElementsOptions["fonts"]
+  children: ReactNode
+}
+
+export function PaymentWrapper({
+  cart,
+  amount,
+  appearance,
+  fonts,
+  children,
+}: PaymentWrapperProps) {
+  // "Ready" simply means: Stripe.js loadable. We no longer wait for a
+  // backend payment_session — deferred-intent mode mounts straight away.
+  const ready = !!stripePromise
+
+  return (
+    <StripeScopeProvider
+      value={{
+        ready,
+        stripePromise,
+        amount,
+        currency: cart.currency_code || "eur",
+        appearance,
+        fonts,
+      }}
+    >
+      {children}
+    </StripeScopeProvider>
+  )
+}

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

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