@forgecart/cli 2.202608121449.0 → 2.202608200713.0

package/templates/storefront/src/components/checkout/CheckoutFlow.tsx

@@ -0,0 +1,543 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+import type { ExtractedError } from '@forgecart/sdk/shop';
+
+import type { ActionResult } from '../../lib/action-result';
+import type {
+  CheckoutOrderView,
+  Country,
+  EligiblePaymentProvider,
+  Order,
+  PaymentSession,
+  PaymentVariables,
+  ShippingRateGroup,
+} from '../../lib/forgecart';
+import {
+  confirmPaymentSession,
+  createPaymentSession,
+  getEligiblePaymentProviders,
+  getPaymentFormTemplate,
+  getPaymentVariables,
+  refreshShippingRates,
+  selectShippingRate,
+  setCustomer,
+  setShippingAddress,
+  transitionToPayment,
+} from '../../lib/checkout-session';
+import { formatPrice } from '../../lib/format';
+import { AddressStep, EMPTY_ADDRESS, type AddressFormValue } from './AddressStep';
+import { PaymentElementForm } from './PaymentElementForm';
+import { PaymentFormEmbed, type PaymentFormMessage } from './PaymentFormEmbed';
+import { RatesStep } from './RatesStep';
+
+type StepId = 'contact' | 'address' | 'rates' | 'payment' | 'confirmation';
+
+const STEPS: { id: StepId; label: string }[] = [
+  { id: 'contact', label: 'Contact' },
+  { id: 'address', label: 'Address' },
+  { id: 'rates', label: 'Shipping' },
+  { id: 'payment', label: 'Payment' },
+  { id: 'confirmation', label: 'Done' },
+];
+
+/**
+ * Providers whose payment UI renders DIRECTLY in the page (operator rule:
+ * our own payment chrome is never iframed — the srcdoc embed added no
+ * security boundary, PCI isolation lives in the provider's own input
+ * iframes). ONE explicit lookup, never providerCode string-matching
+ * scattered through the flow; providers absent here (redirect models,
+ * providers without an adapter) keep the hosted-template embed.
+ */
+const IN_PAGE_PAYMENT_PROVIDERS = new Set(['stripe-payment']);
+
+/**
+ * Session-envelope cache for refresh-resume. A payment session is created
+ * ONCE per order and its secret is never re-readable from the API, so a
+ * page refresh mid-payment must resume from a client-side copy or the order
+ * is stuck (prep mutations throw ORDER_STATE_TRANSITION_ERROR, a second
+ * create throws PAYMENT_SESSION_ALREADY_ACTIVE). sessionStorage is
+ * tab-scoped and origin-scoped; storage failures (privacy modes) degrade to
+ * the honest stuck notice.
+ */
+const SESSION_CACHE_PREFIX = 'forgecart-checkout-session:';
+
+function readSessionCache(orderId: string): PaymentSession | null {
+  try {
+    const raw = sessionStorage.getItem(SESSION_CACHE_PREFIX + orderId);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as PaymentSession;
+    return parsed.id && parsed.clientSecret ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeSessionCache(orderId: string, session: PaymentSession): void {
+  try {
+    sessionStorage.setItem(SESSION_CACHE_PREFIX + orderId, JSON.stringify(session));
+  } catch {
+    // Storage unavailable — refresh-resume degrades to the stuck notice.
+  }
+}
+
+function clearSessionCache(orderId: string): void {
+  try {
+    sessionStorage.removeItem(SESSION_CACHE_PREFIX + orderId);
+  } catch {
+    // Nothing to clean when storage never worked.
+  }
+}
+
+/**
+ * The reference checkout (Cycle 1): contact → address → rates → payment →
+ * confirmation, on the template's design-system vocabulary and the typed
+ * `ActionResult` error spine. Step transitions follow the ORDER's state, not
+ * local assumptions: prep mutations run while the order is AddingItems;
+ * `transitionToPayment` succeeds only once #863's gates (phone-complete
+ * address, items, a selected rate per shipment) hold; the payment step's
+ * hosted form talks back over the #865 postMessage handshake; coupon edits
+ * live in the cart — once a payment session exists the amount is frozen
+ * (PAYMENT_SESSION_ALREADY_ACTIVE guards a second session).
+ *
+ * Every failure renders in place: field-level for the coded field errors,
+ * a step-level alert otherwise — never a thrown error, never a blank page.
+ */
+export function CheckoutFlow({
+  initialOrder,
+  countries,
+}: {
+  initialOrder: Order;
+  countries: Country[];
+}) {
+  const [step, setStep] = useState<StepId>('contact');
+  const [order, setOrder] = useState<CheckoutOrderView>(initialOrder);
+  const [error, setError] = useState<ExtractedError | null>(null);
+  const [pending, setPending] = useState(false);
+
+  const [email, setEmail] = useState('');
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [address, setAddress] = useState<AddressFormValue>(EMPTY_ADDRESS);
+
+  const [rateGroups, setRateGroups] = useState<ShippingRateGroup[]>([]);
+  const [ratesRefreshing, setRatesRefreshing] = useState(false);
+
+  const [providers, setProviders] = useState<EligiblePaymentProvider[]>([]);
+  const [providersLoaded, setProvidersLoaded] = useState(false);
+  const [session, setSession] = useState<PaymentSession | null>(null);
+  const [variables, setVariables] = useState<PaymentVariables | null>(null);
+  const [formHtml, setFormHtml] = useState<string | null>(null);
+  const [confirmedCode, setConfirmedCode] = useState<string | null>(null);
+  const [resumeStuck, setResumeStuck] = useState(false);
+
+  /** Run one action; on success apply, on failure surface the typed error. */
+  const act = useCallback(async function act<T>(
+    action: () => Promise<ActionResult<T>>,
+    apply: (data: T) => void,
+  ): Promise<boolean> {
+    setPending(true);
+    setError(null);
+    const result = await action();
+    setPending(false);
+    if (!result.ok) {
+      setError(result.error);
+      return false;
+    }
+    apply(result.data);
+    return true;
+  }, []);
+
+  // ── Step entry effects ────────────────────────────────────────────────────
+
+  // Refresh-resume: a reload mid-payment arrives with the order already in
+  // ArrangingPayment — re-running the prep steps would throw
+  // ORDER_STATE_TRANSITION_ERROR and a second createPaymentSession
+  // PAYMENT_SESSION_ALREADY_ACTIVE — so the flow re-enters at the payment
+  // step and resumes the cached session envelope. No cache (new tab,
+  // privacy mode) renders the honest stuck notice instead of a doomed
+  // retry surface.
+  useEffect(() => {
+    if ((initialOrder.state ?? '').toLowerCase() !== 'arrangingpayment') return;
+    setStep('payment');
+    const cached = readSessionCache(initialOrder.id);
+    if (!cached) {
+      setResumeStuck(true);
+      return;
+    }
+    setSession(cached);
+    void (async () => {
+      const varsResult = await getPaymentVariables(initialOrder.id);
+      if (varsResult.ok) setVariables(varsResult.data);
+      // In-page providers re-mount from the cached secret + variables; only
+      // embed-lane providers need the hosted template refetched.
+      if (varsResult.ok && IN_PAGE_PAYMENT_PROVIDERS.has(varsResult.data.providerCode)) return;
+      await act(
+        () => getPaymentFormTemplate(initialOrder.id, window.location.origin),
+        (template) => setFormHtml(template.html ?? null),
+      );
+    })();
+  }, [initialOrder.id, initialOrder.state, act]);
+
+  const refreshRates = useCallback(async () => {
+    setRatesRefreshing(true);
+    setError(null);
+    const result = await refreshShippingRates();
+    setRatesRefreshing(false);
+    if (!result.ok) {
+      setError(result.error);
+      return;
+    }
+    setRateGroups(result.data);
+  }, []);
+
+  useEffect(() => {
+    if (step === 'rates') void refreshRates();
+  }, [step, refreshRates]);
+
+  useEffect(() => {
+    if (step !== 'payment' || providersLoaded) return;
+    void act(
+      () => getEligiblePaymentProviders(order.id),
+      (eligible) => {
+        setProviders(eligible);
+        setProvidersLoaded(true);
+      },
+    );
+  }, [step, providersLoaded, order.id, act]);
+
+  // ── Step handlers ─────────────────────────────────────────────────────────
+
+  async function submitContact(): Promise<void> {
+    const ok = await act(
+      () => setCustomer({ emailAddress: email, firstName, lastName }),
+      (updated) => updated && setOrder(updated),
+    );
+    if (ok) setStep('address');
+  }
+
+  async function submitAddress(): Promise<void> {
+    const ok = await act(
+      () =>
+        setShippingAddress({
+          streetLine1: address.streetLine1,
+          ...(address.streetLine2 ? { streetLine2: address.streetLine2 } : {}),
+          city: address.city,
+          ...(address.province ? { province: address.province } : {}),
+          postalCode: address.postalCode,
+          countryId: address.countryId,
+          phoneNumber: address.phoneNumber,
+        }),
+      (updated) => updated && setOrder(updated),
+    );
+    if (ok) setStep('rates');
+  }
+
+  async function pickRate(rateGroupId: string, rateId: string): Promise<void> {
+    await act(
+      () => selectShippingRate({ rateGroupId, rateId }),
+      (updated) => {
+        if (updated) setOrder(updated);
+        // Reflect the selection locally — the read-only rates query would
+        // also serve it, but the flags are already known.
+        setRateGroups((groups) =>
+          groups.map((group) =>
+            group.id === rateGroupId
+              ? {
+                  ...group,
+                  rates: group.rates.map((rate) => ({ ...rate, selected: rate.id === rateId })),
+                }
+              : group,
+          ),
+        );
+      },
+    );
+  }
+
+  async function continueToPayment(): Promise<void> {
+    const ok = await act(
+      () => transitionToPayment(),
+      (updated) => updated && setOrder(updated),
+    );
+    if (ok) setStep('payment');
+  }
+
+  async function pickProvider(providerCode?: string): Promise<void> {
+    setPending(true);
+    setError(null);
+    const varsResult = await getPaymentVariables(order.id);
+    setPending(false);
+    if (!varsResult.ok) {
+      setError(varsResult.error);
+      return;
+    }
+    const fetched = varsResult.data;
+    setVariables(fetched);
+    const created = await act(
+      () => createPaymentSession(order.id, providerCode),
+      (paymentSession) => {
+        setSession(paymentSession);
+        writeSessionCache(order.id, paymentSession);
+      },
+    );
+    if (!created) return;
+    // In-page adapter when the RESOLVED provider has one (the variables name
+    // the channel's resolved provider); everything else embeds the hosted
+    // template. An explicit pick of a different provider falls back too —
+    // the variables only describe the default resolution.
+    const resolved = providerCode ?? fetched.providerCode;
+    if (resolved === fetched.providerCode && IN_PAGE_PAYMENT_PROVIDERS.has(resolved)) return;
+    await act(
+      () => getPaymentFormTemplate(order.id, window.location.origin),
+      (template) => setFormHtml(template.html ?? null),
+    );
+  }
+
+  async function onPaymentSuccess(message: PaymentFormMessage): Promise<void> {
+    // Client-side confirmation models (Stripe Payment Element) arrive already
+    // succeeded — the webhook settles server-side. Token/redirect models post
+    // success without a settled intent; those need the explicit confirm.
+    if (session && message.status !== 'succeeded') {
+      await act(
+        () => confirmPaymentSession(session.id),
+        () => undefined,
+      );
+    }
+    clearSessionCache(order.id);
+    setConfirmedCode(order.code);
+    setStep('confirmation');
+  }
+
+  // ── Render ────────────────────────────────────────────────────────────────
+
+  const stepIndex = STEPS.findIndex((candidate) => candidate.id === step);
+  const stepError = step !== 'address' ? error : null;
+
+  return (
+    <div className="space-y-6">
+      <ul className="steps w-full">
+        {STEPS.map((candidate, index) => (
+          <li key={candidate.id} className={`step ${index <= stepIndex ? 'step-primary' : ''}`}>
+            {candidate.label}
+          </li>
+        ))}
+      </ul>
+
+      {step === 'contact' && (
+        <form
+          className="space-y-4"
+          onSubmit={(e) => {
+            e.preventDefault();
+            void submitContact();
+          }}
+        >
+          <div>
+            <label className="mb-1 block text-sm font-medium text-base-content/70" htmlFor="email">
+              Email
+            </label>
+            <input
+              id="email"
+              type="email"
+              required
+              autoComplete="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="input w-full"
+            />
+          </div>
+          <div className="grid grid-cols-2 gap-4">
+            <div>
+              <label
+                className="mb-1 block text-sm font-medium text-base-content/70"
+                htmlFor="first-name"
+              >
+                First name
+              </label>
+              <input
+                id="first-name"
+                type="text"
+                required
+                autoComplete="given-name"
+                value={firstName}
+                onChange={(e) => setFirstName(e.target.value)}
+                className="input w-full"
+              />
+            </div>
+            <div>
+              <label
+                className="mb-1 block text-sm font-medium text-base-content/70"
+                htmlFor="last-name"
+              >
+                Last name
+              </label>
+              <input
+                id="last-name"
+                type="text"
+                required
+                autoComplete="family-name"
+                value={lastName}
+                onChange={(e) => setLastName(e.target.value)}
+                className="input w-full"
+              />
+            </div>
+          </div>
+          {stepError && (
+            <div role="alert" className="alert alert-error text-sm">
+              <span>{stepError.message ?? stepError.code}</span>
+            </div>
+          )}
+          <button
+            type="submit"
+            className="btn btn-primary"
+            disabled={pending}
+            data-fc-track="checkout-contact"
+          >
+            {pending ? 'Saving…' : 'Continue to address'}
+          </button>
+        </form>
+      )}
+
+      {step === 'address' && (
+        <AddressStep
+          countries={countries}
+          value={address}
+          onChange={setAddress}
+          onSubmit={() => void submitAddress()}
+          pending={pending}
+          error={error}
+        />
+      )}
+
+      {step === 'rates' && (
+        <RatesStep
+          groups={rateGroups}
+          onSelect={(rateGroupId, rateId) => void pickRate(rateGroupId, rateId)}
+          onContinue={() => void continueToPayment()}
+          pending={pending}
+          refreshing={ratesRefreshing}
+          error={stepError}
+        />
+      )}
+
+      {step === 'payment' && (
+        <div className="space-y-4">
+          <div className="card flex flex-row items-center justify-between border border-base-300 bg-base-100 p-4">
+            <span className="text-sm text-base-content/60">Order total</span>
+            <span className="text-lg font-semibold text-base-content">
+              {formatPrice(order.totalWithTax, order.currencyCode)}
+            </span>
+          </div>
+
+          {resumeStuck && !formHtml && (
+            <div role="alert" className="alert alert-warning text-sm">
+              <span>
+                This order is already awaiting payment, and its payment form can't be recovered in
+                this tab. Continue in the tab where you started — or start a new order with a fresh
+                cart.
+              </span>
+            </div>
+          )}
+
+          {!session && !resumeStuck && (
+            <div className="space-y-2">
+              {!providersLoaded && (
+                <p className="text-sm text-base-content/60">Loading payment options…</p>
+              )}
+              {providersLoaded && providers.length === 0 && (
+                <div role="alert" className="alert alert-warning text-sm">
+                  <span>
+                    Payment isn't available for this store yet — no payment method is configured.
+                    Please contact the store.
+                  </span>
+                </div>
+              )}
+              {providers.map((provider) => (
+                <button
+                  key={provider.providerCode}
+                  type="button"
+                  onClick={() => void pickProvider(provider.providerCode)}
+                  disabled={pending || !provider.isEligible}
+                  data-fc-track="checkout-pick-provider"
+                  className="flex w-full items-center justify-between gap-3 rounded-md border border-base-300 px-3 py-2 text-left text-sm transition hover:border-primary disabled:opacity-50"
+                >
+                  <span className="font-medium text-base-content">{provider.providerName}</span>
+                  {!provider.isEligible && provider.eligibilityMessage && (
+                    <span className="text-xs text-base-content/60">
+                      {provider.eligibilityMessage}
+                    </span>
+                  )}
+                </button>
+              ))}
+            </div>
+          )}
+
+          {!formHtml &&
+            session?.clientSecret &&
+            variables?.publishableKey &&
+            variables.scriptUrl &&
+            IN_PAGE_PAYMENT_PROVIDERS.has(variables.providerCode) && (
+              <PaymentElementForm
+                publishableKey={variables.publishableKey}
+                scriptUrl={variables.scriptUrl}
+                clientSecret={session.clientSecret}
+                payLabel={`Pay ${formatPrice(
+                  variables.amount ?? order.totalWithTax,
+                  variables.currency ?? order.currencyCode,
+                )}`}
+                onSuccess={(status, paymentIntentId) =>
+                  void onPaymentSuccess({ type: 'payment-success', status, paymentIntentId })
+                }
+                onError={(message) =>
+                  setError({
+                    code: 'PAYMENT_FAILED',
+                    variables: {},
+                    classification: 'BAD_USER_INPUT',
+                    message,
+                  })
+                }
+              />
+            )}
+
+          {formHtml && (
+            <PaymentFormEmbed
+              html={formHtml}
+              clientSecret={session?.clientSecret ?? undefined}
+              onSuccess={(message) => void onPaymentSuccess(message)}
+              onError={(message) =>
+                setError({
+                  code: 'PAYMENT_FAILED',
+                  variables: {},
+                  classification: 'BAD_USER_INPUT',
+                  message,
+                })
+              }
+            />
+          )}
+
+          {stepError && (
+            <div role="alert" className="alert alert-error text-sm">
+              <span>{stepError.message ?? stepError.code}</span>
+            </div>
+          )}
+        </div>
+      )}
+
+      {step === 'confirmation' && (
+        <div className="card space-y-3 border border-base-300 bg-base-100 p-8 text-center">
+          <h2 className="text-2xl font-bold tracking-tight text-base-content">Thank you!</h2>
+          <p className="text-base-content/60">Your order is confirmed.</p>
+          {confirmedCode && (
+            <p className="text-base-content">
+              Order code: <span className="font-mono font-semibold">{confirmedCode}</span>
+            </p>
+          )}
+          <p className="text-sm text-base-content/60">
+            {order.totalQuantity} item{order.totalQuantity === 1 ? '' : 's'} ·{' '}
+            {formatPrice(order.totalWithTax, order.currencyCode)}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/storefront/src/components/checkout/CheckoutGate.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import Link from 'next/link';
+
+import { useCart } from '../../lib/cart-context';
+import type { Country } from '../../lib/forgecart';
+import { CheckoutFlow } from './CheckoutFlow';
+
+/**
+ * The client gate in front of {@link CheckoutFlow}: the cart lives on the
+ * shopper's websocket, so the server can't gate checkout anymore — this
+ * component waits for the context hydration, shows the honest empty state
+ * when there is nothing to check out, and mounts the flow with the live
+ * order once it exists. The flow's own refresh-resume effect (an order
+ * already in ArrangingPayment re-enters at the payment step) keeps working
+ * because the hydrated active order carries its real state.
+ */
+export function CheckoutGate({ countries }: { countries: Country[] }) {
+  const { cart, hydrated } = useCart();
+
+  if (!hydrated) {
+    return (
+      <div className="space-y-4" aria-busy="true" aria-label="Loading your cart">
+        <div className="skeleton h-10 w-full"></div>
+        <div className="skeleton h-40 w-full"></div>
+        <div className="skeleton h-10 w-40"></div>
+      </div>
+    );
+  }
+
+  if (!cart || cart.lines.length === 0) {
+    return (
+      <div className="space-y-4">
+        <p className="text-base-content/60">
+          Your cart is empty — add something before checking out.
+        </p>
+        <Link href="/products" className="btn btn-primary">
+          Browse products
+        </Link>
+      </div>
+    );
+  }
+
+  return <CheckoutFlow initialOrder={cart} countries={countries} />;
+}