@forgecart/cli 2.202608121449.0 → 2.202608200713.0

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

@@ -0,0 +1,138 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * In-page Stripe Payment Element — the direct-render adapter for
+ * Stripe-model providers (operator decision 2026-08-01: our own payment
+ * chrome is never iframed; the srcdoc embed provided no security boundary —
+ * it is same-origin, and PCI isolation comes from Stripe's OWN nested
+ * input iframes, which apply identically here). The page owns the button
+ * and all visible chrome, so the payment step inherits the design system;
+ * only the card inputs are Stripe's.
+ *
+ * Everything this component needs arrives as data from the shop API
+ * (`getSessionVariables` + the created session's secret) — no keys and no
+ * provider configuration live in the template source. Providers without an
+ * in-page adapter keep the hosted-template embed (`PaymentFormEmbed`).
+ */
+
+/** Minimal structural surface of Stripe.js v3 — the template ships no SDK dep. */
+interface StripeElementsHandle {
+  create: (kind: 'payment') => { mount: (node: HTMLElement) => void; unmount: () => void };
+}
+interface StripeHandle {
+  elements: (options: { clientSecret: string }) => StripeElementsHandle;
+  confirmPayment: (options: {
+    elements: StripeElementsHandle;
+    redirect: 'if_required';
+  }) => Promise<{
+    error?: { message?: string };
+    paymentIntent?: { id: string; status: string };
+  }>;
+}
+declare global {
+  interface Window {
+    Stripe?: (publishableKey: string) => StripeHandle;
+  }
+}
+
+/** Load the provider script once; concurrent callers share the same promise. */
+let scriptPromise: Promise<void> | null = null;
+function loadProviderScript(scriptUrl: string): Promise<void> {
+  if (window.Stripe) return Promise.resolve();
+  scriptPromise ??= new Promise<void>((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = scriptUrl;
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = () => {
+      scriptPromise = null;
+      reject(new Error('Payment provider script failed to load'));
+    };
+    document.head.appendChild(script);
+  });
+  return scriptPromise;
+}
+
+export function PaymentElementForm({
+  publishableKey,
+  scriptUrl,
+  clientSecret,
+  payLabel,
+  onSuccess,
+  onError,
+}: {
+  publishableKey: string;
+  scriptUrl: string;
+  clientSecret: string;
+  /** Themed button label, e.g. `Pay €42.00` — the PAGE owns the chrome. */
+  payLabel: string;
+  onSuccess: (status: string, paymentIntentId: string) => void;
+  onError: (message: string) => void;
+}) {
+  const mountRef = useRef<HTMLDivElement | null>(null);
+  const stripeRef = useRef<StripeHandle | null>(null);
+  const elementsRef = useRef<StripeElementsHandle | null>(null);
+  const [mounted, setMounted] = useState(false);
+  const [paying, setPaying] = useState(false);
+  // Callbacks ride a ref so the mount effect binds once per secret.
+  const handlersRef = useRef({ onError });
+  handlersRef.current = { onError };
+
+  useEffect(() => {
+    let cancelled = false;
+    let element: { unmount: () => void } | null = null;
+    void loadProviderScript(scriptUrl)
+      .then(() => {
+        if (cancelled || !window.Stripe || !mountRef.current) return;
+        const stripe = window.Stripe(publishableKey);
+        const elements = stripe.elements({ clientSecret });
+        const paymentElement = elements.create('payment');
+        paymentElement.mount(mountRef.current);
+        stripeRef.current = stripe;
+        elementsRef.current = elements;
+        element = paymentElement;
+        setMounted(true);
+      })
+      .catch((error: Error) => {
+        if (!cancelled) handlersRef.current.onError(error.message);
+      });
+    return () => {
+      cancelled = true;
+      element?.unmount();
+    };
+  }, [scriptUrl, publishableKey, clientSecret]);
+
+  async function pay(): Promise<void> {
+    const stripe = stripeRef.current;
+    const elements = elementsRef.current;
+    if (!stripe || !elements || paying) return;
+    setPaying(true);
+    const result = await stripe.confirmPayment({ elements, redirect: 'if_required' });
+    setPaying(false);
+    if (result.error) {
+      onError(result.error.message ?? 'Payment failed');
+      return;
+    }
+    if (result.paymentIntent) {
+      onSuccess(result.paymentIntent.status, result.paymentIntent.id);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      {!mounted && <p className="text-sm text-base-content/60">Loading payment form…</p>}
+      <div ref={mountRef} />
+      <button
+        type="button"
+        onClick={() => void pay()}
+        disabled={!mounted || paying}
+        data-fc-track="checkout-pay"
+        className="btn btn-primary btn-block"
+      >
+        {paying ? 'Processing…' : payLabel}
+      </button>
+    </div>
+  );
+}

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

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Provider-agnostic host for the shop API's hosted payment form
+ * (`PaymentFormTemplate.html` — Stripe, Mollie, … the template carries all
+ * provider code; this component contains none).
+ *
+ * The handshake is the #865 contract, extended with in-band secret delivery:
+ * the hosted form posts `iframe-ready`, `payment-success` and
+ * `payment-error` to its embedder, and the embedder answers `iframe-ready`
+ * by posting `client-secret` back INTO the frame — the session's secret
+ * never rides the rendered HTML (which may be logged or cached
+ * server-side); the provider template mounts its payment element only once
+ * the secret arrives. Every message in both directions is pinned to the
+ * page's own origin: the srcdoc iframe is same-origin with this page (no
+ * sandbox), so legitimate traffic carries `window.location.origin` — any
+ * other origin (another iframe, an extension, a foreign embed) is ignored.
+ */
+export interface PaymentFormMessage {
+  type: 'iframe-ready' | 'payment-success' | 'payment-error';
+  error?: string;
+  paymentIntentId?: string;
+  status?: string;
+}
+
+export function PaymentFormEmbed({
+  html,
+  clientSecret,
+  onSuccess,
+  onError,
+}: {
+  html: string;
+  /** The payment session's secret, delivered to the frame post-`iframe-ready`. */
+  clientSecret?: string;
+  onSuccess: (message: PaymentFormMessage) => void;
+  onError: (message: string) => void;
+}) {
+  const [ready, setReady] = useState(false);
+  const frameRef = useRef<HTMLIFrameElement | null>(null);
+  // Callbacks ride a ref so the message listener binds once per html.
+  const handlersRef = useRef({ onSuccess, onError });
+  handlersRef.current = { onSuccess, onError };
+
+  useEffect(() => {
+    function onMessage(event: MessageEvent<PaymentFormMessage>): void {
+      if (event.origin !== window.location.origin) return;
+      const data = event.data;
+      if (!data || typeof data !== 'object') return;
+      if (data.type === 'iframe-ready') {
+        setReady(true);
+        return;
+      }
+      if (data.type === 'payment-success') {
+        handlersRef.current.onSuccess(data);
+        return;
+      }
+      if (data.type === 'payment-error') {
+        handlersRef.current.onError(data.error ?? 'Payment failed');
+      }
+    }
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [html]);
+
+  // Deliver the secret once the frame is listening. Embedded-confirm
+  // templates (Stripe's Payment Element) mount on receipt; templates with no
+  // client-side secret (redirect models) simply never consume the message.
+  useEffect(() => {
+    if (!ready || !clientSecret) return;
+    frameRef.current?.contentWindow?.postMessage(
+      { type: 'client-secret', clientSecret },
+      window.location.origin,
+    );
+  }, [ready, clientSecret]);
+
+  return (
+    <div className="space-y-2">
+      {!ready && <p className="text-sm text-base-content/60">Loading payment form…</p>}
+      <iframe
+        ref={frameRef}
+        title="Payment form"
+        srcDoc={html}
+        className="min-h-96 w-full rounded border border-base-300 bg-base-100"
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,113 @@
+'use client';
+
+import type { ExtractedError } from '@forgecart/sdk/shop';
+
+import type { ShippingRateGroup } from '../../lib/forgecart';
+import { formatPrice } from '../../lib/format';
+
+/**
+ * Shipping-rate selection: one card group per shipment (rates arrive grouped
+ * by stock location), radio-cards per rate, per-group `lastRateErrors`
+ * alerts (a refusing carrier never hides its siblings' quotes). The CUSTOMER
+ * picks — nothing auto-selects; the ArrangingPayment transition requires a
+ * selection in every group (#863's `hasSelectedRates` gate).
+ */
+export function RatesStep({
+  groups,
+  onSelect,
+  onContinue,
+  pending,
+  refreshing,
+  error,
+}: {
+  groups: ShippingRateGroup[];
+  onSelect: (rateGroupId: string, rateId: string) => void;
+  onContinue: () => void;
+  pending: boolean;
+  refreshing: boolean;
+  error: ExtractedError | null;
+}) {
+  if (refreshing) {
+    return <p className="text-sm text-base-content/60">Fetching shipping rates…</p>;
+  }
+
+  const allSelected =
+    groups.length > 0 && groups.every((group) => group.rates.some((rate) => rate.selected));
+
+  return (
+    <div className="space-y-4">
+      {groups.length === 0 && (
+        <div role="alert" className="alert alert-warning text-sm">
+          <span>No shipping rates are available for this address yet.</span>
+        </div>
+      )}
+
+      {groups.map((group, index) => (
+        <div key={group.id} className="card space-y-2 border border-base-300 bg-base-100 p-4">
+          <h3 className="text-sm font-medium text-base-content/70">
+            {groups.length > 1 ? `Shipment ${index + 1}` : 'Shipping method'}
+            {group.stockLocationName ? ` — ships from ${group.stockLocationName}` : ''}
+          </h3>
+
+          {group.lastRateErrors.length > 0 && (
+            <div role="alert" className="alert alert-warning text-sm">
+              <span>
+                {group.lastRateErrors
+                  .map((failure) => `${failure.providerName}: quotes unavailable`)
+                  .join(' · ')}
+              </span>
+            </div>
+          )}
+
+          <div className="flex flex-col gap-2">
+            {group.rates.map((rate) => (
+              <button
+                key={rate.id}
+                type="button"
+                onClick={() => onSelect(group.id, rate.id)}
+                disabled={pending}
+                aria-pressed={rate.selected}
+                data-fc-track="checkout-select-rate"
+                className={`flex items-center justify-between gap-3 rounded-md border px-3 py-2 text-left text-sm transition disabled:opacity-50 ${
+                  rate.selected
+                    ? 'border-primary ring-1 ring-primary'
+                    : 'border-base-300 hover:border-primary'
+                }`}
+              >
+                <span className="min-w-0">
+                  <span className="block font-medium text-base-content">
+                    {rate.carrier} {rate.service}
+                  </span>
+                  {rate.estimatedDays !== null && rate.estimatedDays !== undefined && (
+                    <span className="block text-xs text-base-content/60">
+                      ~{rate.estimatedDays} day{rate.estimatedDays === 1 ? '' : 's'}
+                    </span>
+                  )}
+                </span>
+                <span className="shrink-0 font-medium text-base-content">
+                  {formatPrice(rate.amount, rate.currency)}
+                </span>
+              </button>
+            ))}
+          </div>
+        </div>
+      ))}
+
+      {error && (
+        <div role="alert" className="alert alert-error text-sm">
+          <span>{error.message ?? error.code}</span>
+        </div>
+      )}
+
+      <button
+        type="button"
+        className="btn btn-primary"
+        onClick={onContinue}
+        disabled={pending || !allSelected}
+        data-fc-track="checkout-to-payment"
+      >
+        {pending ? 'Saving…' : 'Continue to payment'}
+      </button>
+    </div>
+  );
+}

package/templates/storefront/src/instrumentation.ts

@@ -31,6 +31,40 @@
 
 const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
 
+/**
+ * Server-start hook: warm-boot the embedded NestJS backend (`src/server/`)
+ * so the first `sdk.backend` invocation doesn't pay the context creation.
+ *
+ * Warm-up ONLY — correctness never depends on it: the dispatch path's lazy
+ * `getBackend()` is what re-boots the context after dev-mode (HMR) edits,
+ * and a boot failure here is deliberately swallowed so a drifted api-map
+ * can never crash the server start — the first invocation (and the dev
+ * methods route) reports the same error as a typed envelope instead. The
+ * dynamic import keeps the Edge bundle inert (Nest is Node-only), and a
+ * no-env boot (image pre-warm) succeeds because clients are only built at
+ * invocation time.
+ */
+export async function register(): Promise<void> {
+  // POSITIVE if-block, never an early return: webpack's parser dead-code-
+  // eliminates a statically-false `if` BODY (NEXT_RUNTIME is DefinePlugin-
+  // substituted per bundle), but it does NOT track reachability past a
+  // `return` — with the guard inverted, the EDGE instrumentation bundle
+  // (compiled because middleware.ts exists) chases this import into
+  // @nestjs/*'s node-builtin requires and `next build --webpack` dies with
+  // five Module-not-found errors ('stream', 'os', 'perf_hooks'; every
+  // publish-button CI run since this import landed). Turbopack prunes the
+  // dead branch either way — only the webpack publish build sees the
+  // difference.
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const { getBackend } = await import('./server/bootstrap');
+      await getBackend();
+    } catch {
+      // Surfaced by the first sdk.backend invocation and /api/__backend/methods.
+    }
+  }
+}
+
 interface OnRequestErrorRequest {
   path: string;
   method: string;

package/templates/storefront/src/lib/action-result.ts

@@ -0,0 +1,30 @@
+import type { ExtractedError } from '@forgecart/sdk/shop';
+
+/**
+ * Typed result envelope for every Server Action in this template.
+ *
+ * Server Actions NEVER throw across the RSC boundary: Next.js production
+ * redacts a thrown action error to an opaque digest, so the client would see
+ * a generic failure with no code to render. Instead each action catches,
+ * translates the failure with the SDK's `extractError` (the shop API's
+ * `{ code, variables, classification, message }` extensions — `message`
+ * arrives server-localized), and returns it in-band. Callers switch on
+ * `ok`; error UIs render `error.message` and key field targeting off
+ * `error.code`.
+ *
+ * The `import type` above erases, so this module is safe for client
+ * components — it is the one shape both sides of the action boundary share.
+ */
+export type ActionResult<T> = { ok: true; data: T } | { ok: false; error: ExtractedError };
+
+/**
+ * Fallback envelope error for failures that carry no GraphQL extensions
+ * (network refused, DNS, a non-GraphQL throw). `extractError` returns `null`
+ * for those; actions substitute this so the client always receives a code it
+ * can key on.
+ */
+export const UNREACHABLE_ERROR: ExtractedError = {
+  code: 'SHOP_API_UNREACHABLE',
+  variables: {},
+  classification: 'INTERNAL_ERROR',
+};

package/templates/storefront/src/lib/backend-actions.ts

@@ -0,0 +1,20 @@
+'use server';
+
+import 'server-only';
+
+import { invokeBackendMethod } from '../server/runner';
+import type { ActionResult } from './action-result';
+
+/**
+ * The ONE Server Action bridging the browser into the embedded NestJS
+ * backend (`src/server/`) — Next's native RPC is the transport, the booted
+ * registry is the authority. Components never import this directly: they
+ * call through `backend` (`lib/backend-client.ts`), which types the surface
+ * off `backend-api.ts` and guards the proxy's magic keys.
+ */
+export async function invokeBackend(
+  method: string,
+  input: unknown,
+): Promise<ActionResult<unknown>> {
+  return invokeBackendMethod(method, input);
+}

package/templates/storefront/src/lib/backend-client.ts

@@ -0,0 +1,47 @@
+import type { BackendApi } from '../server/backend-api';
+import type { ActionResult } from './action-result';
+import { invokeBackend } from './backend-actions';
+
+/**
+ * `sdk.backend` — the typed browser gate onto the storefront's embedded
+ * NestJS backend.
+ *
+ * Compile time: the mapped type below projects `backend-api.ts` onto the
+ * proxy, so editors autocomplete exactly the registered methods and an
+ * unknown name fails the build. (The import is type-only — it erases, so no
+ * server code reaches the client bundle; the `server-only` guards enforce
+ * it.)
+ *
+ * Runtime: the proxy fabricates an invoker for ANY string key — the
+ * server-side registry is the real authority, answering
+ * BACKEND_METHOD_NOT_FOUND in the normal envelope for unknown or
+ * stale-bundle names. Magic keys are excluded so the object never
+ * masquerades as a thenable (`await backend` must not fire a wire call
+ * named "then").
+ *
+ * Usage, any client component:
+ *   const result = await backend.assignCustomerHash({});
+ *   if (!result.ok) return renderError(result.error);
+ */
+type BackendGate = {
+  [K in keyof BackendApi]: (
+    input: Parameters<BackendApi[K]>[0],
+  ) => Promise<ActionResult<Awaited<ReturnType<BackendApi[K]>>>>;
+};
+
+const RESERVED_KEYS = new Set([
+  'then',
+  'catch',
+  'finally',
+  'toJSON',
+  'valueOf',
+  'constructor',
+  '$$typeof',
+]);
+
+export const backend: BackendGate = new Proxy({} as BackendGate, {
+  get(_target, key) {
+    if (typeof key !== 'string' || RESERVED_KEYS.has(key)) return undefined;
+    return (input: unknown) => invokeBackend(key, input);
+  },
+});