@forgecart/cli 2.202608300703.0 → 2.202609190800.0

package/templates/storefront/src/lib/account/account-link.ts

@@ -0,0 +1,76 @@
+import type { RouteSearchParams } from '../seo/noindex';
+
+/**
+ * The anatomy of a ONE-SHOT account link (#1472).
+ *
+ * The platform mails a shopper two kinds of link and both have the same shape:
+ * this storefront's own origin, a fixed route, and a single-use token in the
+ * query — `<origin>/verify?token=…` and `<origin>/reset-password?token=…`. The
+ * `?token=` spelling is the CONTRACT between the mail templates and these
+ * pages (a merchant may have customized the mail body, so the parameter name
+ * cannot be changed on one side alone); the platform supplies the origin, this
+ * module reads what arrives.
+ *
+ * PURE BY CONTRACT: no Next imports, no `process.env`, no fetch, no I/O — the
+ * same constraint `lib/locale/grammar.ts` and `lib/seo/noindex.ts` carry, for
+ * the same reason. `tool/storefront-template-spec` imports this file directly
+ * by relative path from OUTSIDE the scaffold, so anything reachable from here
+ * must resolve without the template's Next toolchain. A rule that decides what
+ * a shopper sees after clicking a one-shot credential has to be a table of
+ * vectors rather than something only a running server can exercise. The
+ * `RouteSearchParams` import is type-only and names another pure module, so it
+ * erases and drags nothing in.
+ */
+
+/**
+ * The query parameter every account link carries.
+ *
+ * Named once so the two pages and their vectors cannot disagree about the
+ * spelling the platform's mail templates emit.
+ */
+export const ACCOUNT_TOKEN_PARAM = 'token';
+
+/** What the shop API answered when a token was actually presented to it. */
+export type AccountCallOutcome = { kind: 'ok' } | { kind: 'error'; code: string };
+
+/**
+ * Everything a link render has to account for: the API's answer, or the fact
+ * that there was no usable token to ask about in the first place.
+ *
+ * `no-token` is not an error the API returned — it is a property of the URL —
+ * and keeping it in the same union is what lets ONE total function decide the
+ * whole page, instead of a page-level branch plus a function that covers only
+ * the half of the cases that reached the network.
+ */
+export type AccountLinkOutcome = AccountCallOutcome | { kind: 'no-token' };
+
+/**
+ * The single usable token in this URL, or null.
+ *
+ * Three ways to get null, each deliberate:
+ *
+ *  - ABSENT — the page was opened without a link (a typed URL, or a mail
+ *    client that dropped the query).
+ *  - BLANK — `?token=` or `?token=%20`. Surrounding whitespace is trimmed
+ *    because a mail client wrapping a long URL can deliver it padded and the
+ *    platform's tokens never contain whitespace; a value that is nothing but
+ *    padding is not a token.
+ *  - REPEATED — `?token=a&token=b` arrives as an array, and is REFUSED rather
+ *    than resolved to the first value. This is a one-shot credential: picking
+ *    one of two candidates would SPEND a real token on a guess about which one
+ *    the shopper meant, and the one that loses the guess is unrecoverable.
+ *    Nothing legitimate produces a repeat, so the honest answer is that this
+ *    URL carries no token the page may act on.
+ */
+export function readLinkToken(searchParams: RouteSearchParams): string | null {
+  const raw = searchParams[ACCOUNT_TOKEN_PARAM];
+  if (typeof raw === 'string') return trimmedOrNull(raw);
+  if (!Array.isArray(raw)) return null;
+  if (raw.length !== 1) return null;
+  return trimmedOrNull(raw[0]);
+}
+
+function trimmedOrNull(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+}

package/templates/storefront/src/lib/account/register-state.ts

@@ -0,0 +1,133 @@
+import type { AccountCallOutcome } from './account-link';
+
+/**
+ * What `/register` renders, as a value (#1471).
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states. The form 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 form is a render.
+ *
+ * Unlike `/verify` and `/reset-password`, this page is not reached with a
+ * credential — a shopper types into it, and may type into it twice. That is why
+ * the states below are not a success/failure pair: the same submit, repeated,
+ * is an ORDINARY thing to happen, and what it should render is a prompt rather
+ * than an error.
+ */
+
+/**
+ * The states of the register page.
+ *
+ *  - `form`               — the initial render, and every render after a
+ *                           refusal the shopper can act on.
+ *  - `verify-your-email`  — the account exists and awaits verification. This is
+ *                           the ONE state a successful registration lands in:
+ *                           registering never signs anyone in (the account is
+ *                           minted unverified and a mail is dispatched), and a
+ *                           storefront that called `login` here was refused
+ *                           NOT_VERIFIED 287 ms later (prod, 2026-09-06). A
+ *                           repeat submit of the same address from the same
+ *                           session lands here too — that is what the shop
+ *                           API's session-scoped idempotency buys: one account,
+ *                           one prompt, no error on a double-clicked button.
+ *  - `already-registered` — the address belongs to an account this session did
+ *                           not create. It carries the resend affordance, since
+ *                           a shopper who never confirmed their address cannot
+ *                           sign in and has nowhere else to go.
+ *  - `signed-in-already`  — the account is verified; nothing is pending.
+ *  - `failed`             — the shop API was unreachable, or answered a code
+ *                           this template does not model.
+ */
+export type RegisterState =
+  | 'form'
+  | 'verify-your-email'
+  | 'already-registered'
+  | 'signed-in-already'
+  | 'failed';
+
+/**
+ * The API's answer to a register submit, as a pure value.
+ *
+ * Wider than {@link AccountCallOutcome} by exactly one field, because this
+ * operation's success is not a bare yes: `verificationPending` is the shop API
+ * READING `user.verified` back, and it is the point of the #1471 contract —
+ * the two successful answers are two different screens.
+ */
+export type RegisterOutcome =
+  | { kind: 'ok'; verificationPending: boolean }
+  | { kind: 'error'; code: string };
+
+/**
+ * `ErrorCode` → state for `registerCustomerAccount`.
+ *
+ * Both refusals collapse into ONE state, and that is a correctness requirement
+ * rather than a simplification: `IDENTIFIER_ALREADY_EXISTS` is the login
+ * identity's refusal and `EMAIL_ADDRESS_CONFLICT` the customer row's, and which
+ * one a shopper receives is decided purely by TIMING — the duplicate-address
+ * pre-check runs before the identity claim, so a resubmit arriving after the
+ * winner's customer row committed gets the second code where an in-flight twin
+ * gets the first. Rendering them differently would show two screens for one
+ * situation.
+ *
+ * `NOT_VERIFIED` is deliberately absent. That is the refusal a LOGIN gets on an
+ * unverified account, and this page signs nobody in —
+ * `registerCustomerAccount` cannot answer with it, so an arm for it would be a
+ * branch no vector can reach.
+ *
+ * Everything absent lands in `failed`: an unrecognised code is a state this
+ * template has not been taught, and guessing a friendlier one would put words
+ * in the API's mouth.
+ */
+const REGISTER_ERROR_STATES: Readonly<Record<string, RegisterState>> = {
+  IDENTIFIER_ALREADY_EXISTS: 'already-registered',
+  EMAIL_ADDRESS_CONFLICT: 'already-registered',
+};
+
+/**
+ * The state a submitted registration lands in. Total over the outcome union.
+ *
+ * The successful answer splits on `verificationPending` rather than assuming
+ * it: a fresh registration carrying a password is always pending, but an
+ * idempotent repeat can find the shopper verified in the meantime (they opened
+ * the link in another tab between the two submits), and sending them to their
+ * inbox for a mail they have already used is a dead end.
+ */
+export function registerState(outcome: RegisterOutcome): RegisterState {
+  if (outcome.kind === 'ok') {
+    return outcome.verificationPending ? 'verify-your-email' : 'signed-in-already';
+  }
+  return REGISTER_ERROR_STATES[outcome.code] ?? 'failed';
+}
+
+/**
+ * The states a verification resend lands in (`idle` is pre-submit).
+ *
+ * TWO outcomes, and the missing third is the design. The shop API throttles
+ * this endpoint — it is public and it sends mail — but it throttles SILENTLY:
+ * inside the window it answers exactly what it answers outside it, and exactly
+ * what it answers for an address that has no account at all. A `throttled`
+ * state would therefore be an enumeration tell rather than a courtesy, because
+ * the only way this storefront could render one is if the API had told it that
+ * THIS address has a pending account waiting on a recently-sent mail — the one
+ * fact the neutral answer exists to withhold. A throttled resend renders as
+ * `sent`, which is also what is true for the shopper: the mail is in their
+ * inbox, from a minute ago.
+ *
+ * `sent` is neutral for the same reason `passwordResetRequestState`'s is, and
+ * `failed` means the same thing it does there: we could not ASK, which says
+ * nothing about any account and would otherwise be a sent-mail promise we know
+ * to be false.
+ */
+export type VerificationResendState = 'idle' | 'sent' | 'failed';
+
+/**
+ * The state a submitted resend lands in.
+ *
+ * Its own function rather than an alias of `passwordResetRequestState`: the two
+ * surfaces have different pre-submit members (`idle` here, `form` there), and
+ * aliasing them would make a change to one silently change the other — that
+ * these two answers have the same shape today is a fact about the platform's
+ * anti-enumeration posture, not a dependency between the pages.
+ */
+export function verificationResendState(outcome: AccountCallOutcome): VerificationResendState {
+  return outcome.kind === 'ok' ? 'sent' : 'failed';
+}

package/templates/storefront/src/lib/account/reset-password-state.ts

@@ -0,0 +1,111 @@
+import type { AccountCallOutcome } from './account-link';
+
+/**
+ * What `/reset-password` renders, as a value (#1472).
+ *
+ * One route, two modes — the URL's token decides which. WITH a token the page
+ * sets a new password; WITHOUT one it asks for an e-mail address and has a new
+ * link sent. Both modes start on their form and move to a terminal state when
+ * the API answers, so each mode gets its own union rather than one flat set
+ * that would let a request-mode render claim a reset-mode state.
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states.
+ */
+
+/** The states a SUBMITTED new password lands in (`form` is pre-submit). */
+export type ResetPasswordSubmitState = 'done' | 'link-invalid' | 'password-rejected' | 'failed';
+
+/**
+ * The set-a-new-password mode.
+ *
+ *  - `form`              — the initial render, and every render after a
+ *                          refusal the shopper can act on.
+ *  - `done`              — the password was changed.
+ *  - `link-invalid`      — the API refused the token: used, expired, or issued
+ *                          by another store. One state, same reasons as the
+ *                          verify page's.
+ *  - `password-rejected` — the API refused the PASSWORD. The form stays up:
+ *                          the token is still good and the shopper only has to
+ *                          choose again.
+ *  - `failed`            — unreachable, or a code this template does not model.
+ */
+export type ResetPasswordState = 'form' | ResetPasswordSubmitState;
+
+/** The states a SUBMITTED reset request lands in (`form` is pre-submit). */
+export type PasswordResetRequestSubmitState = 'sent' | 'failed';
+
+/**
+ * The ask-for-a-link mode.
+ *
+ * `sent` is deliberately NEUTRAL and covers both of the API's successful
+ * answers: it reports whether an account matched, and rendering that difference
+ * would turn this form into an account-enumeration oracle — type an address,
+ * read the page, learn whether that person shops here. `failed` is reserved for
+ * the case where we could not ASK at all, which tells a visitor nothing about
+ * any account and would otherwise be a lie dressed as a sent mail.
+ */
+export type PasswordResetRequestState = 'form' | PasswordResetRequestSubmitState;
+
+/** Why a new-password form cannot be submitted yet. */
+export type NewPasswordProblem = 'empty' | 'mismatch';
+
+/**
+ * `ErrorCode` → state for `resetPassword`.
+ *
+ * `CUSTOMER_NOT_FOUND` is NOT the wrong-store case here, unlike on the verify
+ * page: consuming a reset token is scoped to the principal class of the
+ * requesting store, so another store's token simply does not resolve and
+ * arrives as `PASSWORD_RESET_TOKEN_INVALID`. Reaching `CUSTOMER_NOT_FOUND`
+ * means the token DID resolve inside this store and the customer row behind it
+ * is missing — a platform-side inconsistency, not something a shopper can act
+ * on — so it belongs in `failed` with the rest of the unmodelled codes.
+ */
+const RESET_ERROR_STATES: Readonly<Record<string, ResetPasswordSubmitState>> = {
+  PASSWORD_RESET_TOKEN_INVALID: 'link-invalid',
+  PASSWORD_RESET_TOKEN_EXPIRED: 'link-invalid',
+  PASSWORD_VALIDATION_FAILED: 'password-rejected',
+};
+
+/** The state a submitted new password lands in. */
+export function resetPasswordState(outcome: AccountCallOutcome): ResetPasswordSubmitState {
+  if (outcome.kind === 'ok') return 'done';
+  return RESET_ERROR_STATES[outcome.code] ?? 'failed';
+}
+
+/**
+ * The state a submitted reset REQUEST lands in.
+ *
+ * Every answer the API gives is `sent`; only a failure to reach it is anything
+ * else. See {@link PasswordResetRequestState} for why the successful answers
+ * are collapsed.
+ */
+export function passwordResetRequestState(
+  outcome: AccountCallOutcome,
+): PasswordResetRequestSubmitState {
+  return outcome.kind === 'ok' ? 'sent' : 'failed';
+}
+
+/**
+ * Whether the two password fields may be submitted, and if not, why.
+ *
+ * A UX affordance, NOT a security boundary, and the distinction is the whole
+ * reason the confirmation never leaves the browser: the shop API is the only
+ * authority on whether a password is acceptable (it answers
+ * `PASSWORD_VALIDATION_FAILED`, which arrives here as `password-rejected`), and
+ * a Server Action is a public endpoint that a caller can reach without ever
+ * rendering this form. Checking the confirmation client-side saves a shopper a
+ * round-trip and a spent token; it decides nothing the server would not decide
+ * again.
+ *
+ * The password is compared UNTRIMMED. Leading and trailing spaces are legal
+ * characters in a password, so trimming here would silently accept two values
+ * the API will treat as different.
+ */
+export function checkNewPassword(
+  password: string,
+  confirmation: string,
+): NewPasswordProblem | null {
+  if (password.length === 0) return 'empty';
+  if (password !== confirmation) return 'mismatch';
+  return null;
+}

package/templates/storefront/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/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/src/lib/account-session.ts

@@ -0,0 +1,47 @@
+'use client';
+
+import type { RegisterCustomerInput } from '@forgecart/sdk/shop';
+
+import type { RegisterOutcome } from './account/register-state';
+import { runSessionOp } from './shop-session';
+
+/**
+ * Registering, on the shopper's OWN websocket (#1471).
+ *
+ * Every other unauthenticated account call in this template is a Server Action
+ * running on the anonymous channel singleton (`lib/account-actions.ts`). This
+ * one is 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. The guarantee is 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 logging in later
+ *     promotes — so the cart someone filled before registering 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 on this page is in that second
+ * category too — it needs nothing but an address — so it stays a Server Action.
+ */
+export async function registerCustomerAccount(
+  input: RegisterCustomerInput,
+): Promise<RegisterOutcome> {
+  const result = await runSessionOp(
+    async (client) =>
+      (await client.customer.registerCustomerAccount({ input })).registerCustomerAccount,
+  );
+  // `runSessionOp` never throws — a refusal arrives as a typed code, which is
+  // the ordinary case here (the address may already be registered) and the form
+  // renders it. The envelope is flattened into the pure outcome union so the
+  // state table stays the only thing that reads an ErrorCode.
+  if (!result.ok) return { kind: 'error', code: result.error.code };
+  return { kind: 'ok', verificationPending: result.data.verificationPending };
+}

package/templates/storefront/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() ?? '';
+}