@forgecart/cli 2.202610280649.0 → 2.202610280926.0

package/templates/storefront-blank/src/lib/account/verify-state.ts

@@ -0,0 +1,56 @@
+import type { AccountLinkOutcome } from './account-link';
+
+/**
+ * What `/verify` renders, as a value (#1472).
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states. The page owns the
+ * COPY for each state; this module owns which state a given outcome is, so the
+ * decision is a table of vectors and the page is a render.
+ */
+
+/**
+ * The states of the e-mail verification page.
+ *
+ *  - `no-token`     — the URL carried no token this page may act on.
+ *  - `verified`     — the account is now verified.
+ *  - `link-invalid` — the API refused the token: already used, expired, or
+ *                     never issued. They are ONE state on purpose — the page's
+ *                     advice is identical ("request a new mail") and telling an
+ *                     unauthenticated visitor whether a token they do not hold
+ *                     once existed is an oracle with no upside.
+ *  - `wrong-store`  — the token was valid, but the account it belongs to is not
+ *                     a customer of THIS store.
+ *  - `failed`       — anything else: the shop API was unreachable, or answered
+ *                     a code this template does not model.
+ */
+export type VerifyState = 'no-token' | 'verified' | 'link-invalid' | 'wrong-store' | 'failed';
+
+/**
+ * `ErrorCode` → state, for the codes `verifyCustomerAccount` can answer with.
+ *
+ * `CUSTOMER_NOT_FOUND` is the `wrong-store` case and the reason that state
+ * exists. Verification resolves the token GLOBALLY (the platform's auth method
+ * is keyed by the token alone), and only the customer lookup that follows is
+ * scoped to the channel this storefront serves — so a token issued by another
+ * store passes the first step and fails the second. That is exactly what a
+ * shopper holding an OLD mail hits: before #1472 every store's links pointed at
+ * one platform-global host, so a stale link can still arrive at the wrong
+ * storefront. "Something went wrong" would be true and useless; naming the
+ * cause is what lets the shopper act on it.
+ *
+ * Everything absent from this table lands in `failed` by design: an
+ * unrecognised code is a state this template has not been taught, and guessing
+ * at a friendlier one would put words in the API's mouth.
+ */
+const VERIFY_ERROR_STATES: Readonly<Record<string, VerifyState>> = {
+  VERIFICATION_TOKEN_INVALID: 'link-invalid',
+  VERIFICATION_TOKEN_EXPIRED: 'link-invalid',
+  CUSTOMER_NOT_FOUND: 'wrong-store',
+};
+
+/** The state a verification render lands in. Total over the outcome union. */
+export function verifyState(outcome: AccountLinkOutcome): VerifyState {
+  if (outcome.kind === 'no-token') return 'no-token';
+  if (outcome.kind === 'ok') return 'verified';
+  return VERIFY_ERROR_STATES[outcome.code] ?? 'failed';
+}

package/templates/storefront-blank/src/lib/account-actions.ts

@@ -0,0 +1,76 @@
+'use server';
+
+import 'server-only';
+
+import { verificationResendState, type VerificationResendState } from './account/register-state';
+import {
+  passwordResetRequestState,
+  resetPasswordState,
+  type PasswordResetRequestSubmitState,
+  type ResetPasswordSubmitState,
+} from './account/reset-password-state';
+import { requestCustomerVerification, requestPasswordReset, resetPassword } from './forgecart';
+
+/**
+ * The Server Actions behind the account forms (#1472, #1471).
+ *
+ * These are the places in this template where a SHOPPER's input reaches the
+ * shop API from the server rather than over their own websocket, and that
+ * placement is deliberate: all three operations are unauthenticated by design
+ * (whoever holds the token, or the address, may call them), so putting them on
+ * the session socket would open a session for someone who has not shopped yet
+ * and attach a cart identity to a password reset. They run on the anonymous
+ * channel singleton in `lib/forgecart.ts` instead.
+ *
+ * The register SUBMIT is the one account operation that does NOT belong here,
+ * for the mirror image of that reason: it is session-scoped, and the session
+ * has to be the shopper's own. It lives in `lib/account-session.ts`, which
+ * states that argument in full.
+ *
+ * Each action returns the page STATE, not the API's envelope: the mapping from
+ * `ErrorCode` to state lives once, in `lib/account/reset-password-state.ts`,
+ * and a string union crosses the RSC boundary as itself. The client form only
+ * has to render what it is given.
+ *
+ * A Server Action is a public HTTP endpoint — a caller can reach these without
+ * ever loading the form — which is exactly why neither of them validates
+ * anything the API validates: the token and the password are judged by the
+ * shop API, and the form's own confirmation check is a UX affordance that
+ * never leaves the browser (see `checkNewPassword`). Abuse budgets (how often
+ * an address may be mailed) belong to the platform, which owns the mail — and
+ * for the verification resend it enforces one silently, which is why no state
+ * here names it (see {@link VerificationResendState}).
+ */
+
+/** Consume a reset token and set the new password. */
+export async function submitPasswordReset(input: {
+  token: string;
+  password: string;
+}): Promise<ResetPasswordSubmitState> {
+  return resetPasswordState(await resetPassword(input));
+}
+
+/**
+ * Ask for a reset link.
+ *
+ * Answers the same neutral state whether or not an account matched — see
+ * {@link passwordResetRequestState}.
+ */
+export async function submitPasswordResetRequest(
+  emailAddress: string,
+): Promise<PasswordResetRequestSubmitState> {
+  return passwordResetRequestState(await requestPasswordReset(emailAddress));
+}
+
+/**
+ * Ask for the verification mail again (#1471).
+ *
+ * Answers the same neutral state whether or not the address has anything to
+ * verify, and whether or not the platform's throttle swallowed this particular
+ * request — see {@link VerificationResendState}.
+ */
+export async function submitVerificationRequest(
+  emailAddress: string,
+): Promise<VerificationResendState> {
+  return verificationResendState(await requestCustomerVerification(emailAddress));
+}

package/templates/storefront-blank/src/lib/account-session.ts

@@ -0,0 +1,114 @@
+'use client';
+
+import type { NativeAuthInput, RegisterCustomerInput } from '@forgecart/sdk/shop';
+
+import type { AccountCallOutcome } from './account/account-link';
+import { isSessionGone, type ActiveCustomerOutcome } from './account/account-state';
+import type { RegisterOutcome } from './account/register-state';
+import { replaceShopSession, runSessionOp } from './shop-session';
+
+/**
+ * The account calls that run on the shopper's OWN websocket: registering
+ * (#1471), and signing in and out (#1093).
+ *
+ * Every other unauthenticated account call in this template is a Server Action
+ * running on the anonymous channel singleton (`lib/account-actions.ts`). These
+ * are not, and the placement is the design rather than a preference:
+ *
+ *  1. CORRECTNESS. `lib/forgecart.ts` memoizes ONE client per language for the
+ *     whole Next process, so every visitor's Server Action shares it — and
+ *     therefore shares its shop session. The shop API's register idempotency is
+ *     SESSION-scoped (a session holds one registration claim, which is what
+ *     turns a double-clicked submit into one account and one prompt instead of
+ *     a refusal), so running it on a shared session would answer one shopper
+ *     with another shopper's pending state. A sign-in on that client would be
+ *     worse still: it would sign EVERY visitor in as whoever signed in last.
+ *     These calls are only sound on a session that belongs to one person.
+ *  2. INTENT. Registering starts the shopper relationship, and the anonymous
+ *     session this socket holds IS the cart identity that signing in later
+ *     promotes — so the cart someone filled before registering, or before
+ *     signing in, follows them into their account.
+ *
+ * That is the opposite placement from `/verify` and `/reset-password`, and
+ * deliberately so: those act on a one-shot token out of a mail, where opening a
+ * session for a visitor who has not shopped yet would attach a cart identity to
+ * a password reset. The verification RESEND is in that second category too — it
+ * needs nothing but an address — so it stays a Server Action.
+ *
+ * Like `runSessionOp`, none of these throws: a refusal is a typed code in the
+ * outcome, which is the ordinary case (a mistyped password, an address already
+ * registered), and the pure state tables in `lib/account/` stay the only things
+ * that read an ErrorCode.
+ */
+
+export async function registerCustomerAccount(
+  input: RegisterCustomerInput,
+): Promise<RegisterOutcome> {
+  const result = await runSessionOp(
+    async (client) =>
+      (await client.customer.registerCustomerAccount({ input })).registerCustomerAccount,
+  );
+  if (!result.ok) return { kind: 'error', code: result.error.code };
+  return { kind: 'ok', verificationPending: result.data.verificationPending };
+}
+
+/**
+ * Sign the shopper in.
+ *
+ * Resolves only once this tab's socket AND the session cookies carry the
+ * session the sign-in minted (`replaceShopSession`), so the caller's very next
+ * operation — the greeting — runs as the signed-in shopper. Before #1093 every
+ * storefront hand-rolled this, and the one that did not rotate the socket had
+ * its next operation refused UNAUTHORIZED and reported a failed sign-in (#1089).
+ *
+ * A refusal resolves with its code — `INVALID_CREDENTIALS`, `NOT_VERIFIED`, … —
+ * and changes nothing: the socket keeps the session it had, cart included.
+ */
+export async function loginCustomer(input: NativeAuthInput): Promise<AccountCallOutcome> {
+  const result = await runSessionOp(async (client) => (await client.auth.login({ input })).login);
+  if (!result.ok) return { kind: 'error', code: result.error.code };
+  await replaceShopSession(result.data.token);
+  return { kind: 'ok' };
+}
+
+/**
+ * Sign the shopper out.
+ *
+ * Asks the shop API to end the session, then leaves this tab without one —
+ * the socket replaced by one that carries no session, both cookies cleared —
+ * WHATEVER the API answered: signing out is first a promise about this device,
+ * and a shopper on a shared computer who pressed the button must not stay
+ * signed in because the network blinked. The outcome reports the API's half:
+ * `ok` when the session is over (a session the API no longer holds included),
+ * the refusal's code when the API could not confirm it.
+ */
+export async function logoutCustomer(): Promise<AccountCallOutcome> {
+  const ended = await runSessionOp(async (client) => (await client.auth.logout()).logout);
+  await replaceShopSession(null);
+  if (ended.ok || isSessionGone(ended.error.code)) return { kind: 'ok' };
+  return { kind: 'error', code: ended.error.code };
+}
+
+/**
+ * Who this tab's session belongs to.
+ *
+ * A socket carrying no session is answered without a request — a visitor who
+ * has never shopped, or one who just signed out, belongs to nobody — and so is
+ * every page load that finds no mirror cookie, since the socket boots its
+ * session from it. Otherwise the shop API is asked, and an anonymous cart
+ * session answers `null` too.
+ */
+export async function findSignedInCustomer(): Promise<ActiveCustomerOutcome> {
+  const result = await runSessionOp(async (client) => {
+    if (client.getAuthToken() === null) return null;
+    const customer = (await client.customer.activeCustomer()).activeCustomer ?? null;
+    if (customer === null) return null;
+    return {
+      firstName: customer.firstName,
+      lastName: customer.lastName,
+      emailAddress: customer.emailAddress,
+    };
+  });
+  if (!result.ok) return { kind: 'error', code: result.error.code };
+  return { kind: 'ok', customer: result.data };
+}

package/templates/storefront-blank/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-blank/src/lib/asset-alt.ts

@@ -0,0 +1,34 @@
+/**
+ * The `alt` attribute for an asset-backed `<img>` — the one place the template
+ * decides what an undescribed image announces (#1376).
+ *
+ * Alt text is the merchant's OWN description of the image, authored in the
+ * dashboard's media library. Its absence is therefore a decision rather than a
+ * gap: an image nobody described is announced as decorative (`alt=""`) and
+ * skipped by screen readers, which is exactly right for the product shots,
+ * badges and thumbnails that repeat text already sitting next to them.
+ *
+ * It is deliberately NEVER back-filled with the product or variant name. A
+ * derived placeholder is indistinguishable from a real description to both a
+ * screen reader and a crawler, while carrying nothing the adjacent markup does
+ * not already say — so it spends a listener's attention repeating the caption
+ * they just heard, and tells a crawler the image was described when it was
+ * not. The empty string is the honest answer and the accessible one, and this
+ * function exists so that judgement is stated once instead of re-derived at
+ * every `<img>` (all four of which read `alt={product.name}` before it).
+ *
+ * A blank-but-present description collapses to the same decorative default.
+ * `alt="   "` is the worst of both worlds — not a description, and not the
+ * empty string that marks an image skippable, so a reader falls back to
+ * announcing the file name. The dashboard already trims before it writes, but
+ * the field is equally writable through the admin API, so the guarantee is
+ * made here where it is actually rendered rather than assumed upstream.
+ *
+ * The parameter is structural, not the SDK's `Asset`: every selection that
+ * renders an image picks `altText` alongside `preview`, and asking only for
+ * the field actually read keeps this module free of the SDK import — which is
+ * what lets it be unit-tested directly (see tool/storefront-template-spec).
+ */
+export function getAssetAlt(asset: { altText?: string | null }): string {
+  return asset.altText?.trim() ?? '';
+}

package/templates/storefront-blank/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-blank/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);
+  },
+});

package/templates/storefront-blank/src/lib/cart-context.tsx

@@ -0,0 +1,236 @@
+'use client';
+
+import type { ExtractedError } from '@forgecart/sdk/shop';
+import type { ShopAddItemToOrderInput } from '@forgecart/sdk/shop';
+
+import type { ActionResult } from './action-result';
+import type { Order } from './forgecart';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  useTransition,
+  type ReactNode,
+} from 'react';
+
+import {
+  initShopSession,
+  isSessionReady,
+  readMirrorSession,
+  runSessionOp,
+  type ShopSessionConfig,
+} from './shop-session';
+
+/**
+ * Cart state on the shopper's OWN shop websocket (`shop-session.ts`) — the
+ * client half of the progressive stack.
+ *
+ * PPR-compatible boot: the server shell renders with NO cart (reading the
+ * session cookie would dynamize the whole layout), so the provider hydrates
+ * client-side. On mount it arms the session singleton with the serialized
+ * channel config; when the mirror cookie says a session exists, it reads the
+ * active order over the socket (`activeOrder` is nullable and NEVER mints —
+ * carts start with the first added item). `hydrated` stays false until that
+ * first read settles, so cart surfaces can render a skeleton instead of a
+ * false "empty cart" flash.
+ *
+ * Every mutation runs on the same socket and replaces `cart` with the order
+ * from the typed `ActionResult` envelope; a failure keeps the last known
+ * cart AND surfaces the typed error on `error`. `pending` is true while a
+ * cart mutation is in flight. The first `add` on a fresh visitor mints the
+ * session client-side; `shop-session.ts` syncs the captured token back into
+ * the cookies so the next SSR pass sees this cart.
+ */
+interface CartContextValue {
+  cart: Order | null;
+  itemCount: number;
+  subtotal: number;
+  /** False until the mount-time cart read settles — render skeletons, not "empty". */
+  hydrated: boolean;
+  pending: boolean;
+  error: ExtractedError | null;
+  add: (variantId: string, quantity?: number, sellingPlanId?: string) => void;
+  setQuantity: (lineId: string, quantity: number) => void;
+  remove: (lineId: string) => void;
+  setSellingPlan: (sellingPlanId: string | null) => void;
+  applyCoupon: (code: string) => void;
+  removeCoupon: (code: string) => void;
+  clearError: () => void;
+  refresh: () => void;
+}
+
+const CartContext = createContext<CartContextValue | null>(null);
+
+export function CartProvider({
+  shopConfig,
+  children,
+}: {
+  shopConfig: ShopSessionConfig | null;
+  children: ReactNode;
+}) {
+  const [cart, setCart] = useState<Order | null>(null);
+  const [hydrated, setHydrated] = useState(false);
+  const [error, setError] = useState<ExtractedError | null>(null);
+  const [pending, startTransition] = useTransition();
+
+  const run = useCallback((op: () => Promise<ActionResult<Order | null>>) => {
+    startTransition(async () => {
+      const result = await op();
+      if (result.ok) {
+        setCart(result.data);
+        setError(null);
+        return;
+      }
+      setError(result.error);
+    });
+  }, []);
+
+  // Arm the session singleton and hydrate the cart. An unconfigured scaffold
+  // (pre-`forgecart init`) or a visitor with no session hydrates to the
+  // legitimate empty state without touching the network.
+  useEffect(() => {
+    if (!shopConfig) {
+      setHydrated(true);
+      return;
+    }
+    initShopSession(shopConfig);
+    if (!readMirrorSession()) {
+      setHydrated(true);
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      const result = await runSessionOp(
+        async (client) => (await client.order.activeOrder()).activeOrder ?? null,
+      );
+      if (cancelled) return;
+      if (result.ok) setCart(result.data);
+      setHydrated(true);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [shopConfig]);
+
+  const add = useCallback(
+    (variantId: string, quantity = 1, sellingPlanId?: string) =>
+      run(async () => {
+        const input: ShopAddItemToOrderInput = { variantId, quantity };
+        if (sellingPlanId) {
+          input.sellingPlanId = sellingPlanId;
+        }
+        return runSessionOp(
+          async (client) => (await client.cart.addItemToOrder({ input })).addItemToOrder,
+        );
+      }),
+    [run],
+  );
+  const setQuantity = useCallback(
+    (lineId: string, quantity: number) =>
+      run(() =>
+        runSessionOp(
+          async (client) =>
+            (await client.cart.adjustOrderLine({ input: { lineId, quantity } })).adjustOrderLine,
+        ),
+      ),
+    [run],
+  );
+  const remove = useCallback(
+    (lineId: string) =>
+      run(() =>
+        runSessionOp(
+          async (client) => (await client.cart.removeOrderLine({ lineId })).removeOrderLine,
+        ),
+      ),
+    [run],
+  );
+  const setSellingPlan = useCallback(
+    (sellingPlanId: string | null) =>
+      run(() =>
+        runSessionOp(
+          async (client) =>
+            (await client.cart.setOrderSellingPlan({ input: { sellingPlanId } }))
+              .setOrderSellingPlan,
+        ),
+      ),
+    [run],
+  );
+  const applyCoupon = useCallback(
+    (code: string) =>
+      run(() =>
+        runSessionOp(
+          async (client) => (await client.cart.applyCouponCode({ code })).applyCouponCode,
+        ),
+      ),
+    [run],
+  );
+  const removeCoupon = useCallback(
+    (code: string) =>
+      run(() =>
+        runSessionOp(
+          async (client) => (await client.cart.removeCouponCode({ code })).removeCouponCode,
+        ),
+      ),
+    [run],
+  );
+  const clearError = useCallback(() => setError(null), []);
+  const refresh = useCallback(
+    () =>
+      run(async () => {
+        if (!isSessionReady() || !readMirrorSession()) {
+          return { ok: true, data: null };
+        }
+        return runSessionOp(
+          async (client) => (await client.order.activeOrder()).activeOrder ?? null,
+        );
+      }),
+    [run],
+  );
+
+  const value = useMemo<CartContextValue>(
+    () => ({
+      cart,
+      itemCount: cart?.totalQuantity ?? 0,
+      subtotal: cart?.subTotalWithTax ?? 0,
+      hydrated,
+      pending,
+      error,
+      add,
+      setQuantity,
+      remove,
+      setSellingPlan,
+      applyCoupon,
+      removeCoupon,
+      clearError,
+      refresh,
+    }),
+    [
+      cart,
+      hydrated,
+      pending,
+      error,
+      add,
+      setQuantity,
+      remove,
+      setSellingPlan,
+      applyCoupon,
+      removeCoupon,
+      clearError,
+      refresh,
+    ],
+  );
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+/** Access the cart. Must be used inside a `<CartProvider>`. */
+export function useCart(): CartContextValue {
+  const ctx = useContext(CartContext);
+  if (!ctx) {
+    throw new Error('useCart must be used within a CartProvider');
+  }
+  return ctx;
+}