@forgecart/cli 2.202610141948.0 → 2.202610142335.0

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

@@ -1,16 +1,19 @@
 'use client';
 
-import type { RegisterCustomerInput } from '@forgecart/sdk/shop';
+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 { runSessionOp } from './shop-session';
+import { replaceShopSession, runSessionOp } from './shop-session';
 
 /**
- * Registering, on the shopper's OWN websocket (#1471).
+ * 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`). This
- * one is not, and the placement is the design rather than a preference:
+ * 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
@@ -18,19 +21,26 @@ import { runSessionOp } from './shop-session';
  *     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.
+ *     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 logging in later
- *     promotes — so the cart someone filled before registering follows them
- *     into their account.
+ *     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 on this page is in that second
- * category too — it needs nothing but an address — so it stays a Server Action.
+ * 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> {
@@ -38,10 +48,67 @@ export async function registerCustomerAccount(
     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 };
 }
+
+/**
+ * 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-shadcn/src/lib/error-messages.ts

@@ -1,24 +1,118 @@
 import type { ExtractedError } from '@forgecart/sdk/shop';
 
 /**
- * Shopper-facing messages for the typed checkout error codes.
+ * Shopper-facing copy for the typed error codes a storefront call can meet.
  *
  * The shop API's error contract ships CODES, never prose — `message` on an
  * extracted error is the code string itself, and resolving human copy is the
  * frontend's job (error-handling contract). A raw enum leaking into the UI is
  * a defect (the address step rendered SHIPPING_ADDRESS_PHONE_REQUIRED
  * verbatim, 2026-08-09).
+ *
+ * Two families live here. The checkout's address codes, and every refusal a
+ * customer ACCOUNT call can meet (#1093): signing in and out, registering, a
+ * verification or reset link, a password or e-mail change. The account family
+ * is swept against the shop's own `ErrorCode` enum by
+ * `tool/storefront-template-spec` — every member of its `Auth - Self-Service`
+ * and `Auth - Service` blocks, plus the sign-in refusal, the anonymous
+ * socket's refusal and the taken address — so a refusal added to the platform
+ * reddens that sweep until it has copy here. Before #1093 this map held the
+ * three address codes alone, and every refused sign-in rendered as the
+ * generic line: indistinguishable from the platform faults it was masking.
+ *
+ * `SHOP_API_UNREACHABLE` is not a platform code but this template's own
+ * (`lib/action-result.ts`): the answer when the API could not be asked at all,
+ * which is the one failure the generic line's "check your details" is wrong
+ * about.
+ *
+ * A Map rather than an object literal: a lookup keyed by an API-supplied
+ * string must not be able to land on `Object.prototype` (`constructor`,
+ * `toString`) and render a function as copy.
  */
-const SHOPPER_MESSAGES: Record<string, string> = {
-  SHIPPING_ADDRESS_PHONE_REQUIRED: 'A phone number is required for delivery updates.',
-  SHIPPING_ADDRESS_COUNTRY_REQUIRED: 'Please select a country.',
-  SHIPPING_ADDRESS_COUNTRY_INVALID: 'We can’t ship to the selected country yet.',
-};
+const SHOPPER_MESSAGES: ReadonlyMap<string, string> = new Map([
+  ['SHIPPING_ADDRESS_PHONE_REQUIRED', 'A phone number is required for delivery updates.'],
+  ['SHIPPING_ADDRESS_COUNTRY_REQUIRED', 'Please select a country.'],
+  ['SHIPPING_ADDRESS_COUNTRY_INVALID', 'We can’t ship to the selected country yet.'],
+  [
+    'INVALID_CREDENTIALS',
+    'That e-mail address and password do not match. Check both and try again.',
+  ],
+  ['UNAUTHORIZED', 'You are not signed in, or your session has ended. Please sign in again.'],
+  [
+    'EMAIL_ADDRESS_CONFLICT',
+    'That e-mail address already has an account. Sign in with it, or reset its password.',
+  ],
+  [
+    'IDENTIFIER_ALREADY_EXISTS',
+    'That e-mail address already has an account. Sign in with it, or reset its password.',
+  ],
+  [
+    'NOT_VERIFIED',
+    'This account is not confirmed yet. Open the link in the confirmation e-mail we sent you, then sign in.',
+  ],
+  [
+    'VERIFICATION_TOKEN_INVALID',
+    'This confirmation link is not valid — it may have been used already. Ask for a new confirmation e-mail.',
+  ],
+  [
+    'VERIFICATION_TOKEN_EXPIRED',
+    'This confirmation link has expired. Ask for a new confirmation e-mail and open the newest link.',
+  ],
+  [
+    'PASSWORD_RESET_TOKEN_INVALID',
+    'This password reset link is not valid — it may have been used already. Ask for a new one.',
+  ],
+  [
+    'PASSWORD_RESET_TOKEN_EXPIRED',
+    'This password reset link has expired. Ask for a new one and open the newest link.',
+  ],
+  [
+    'PASSWORD_VALIDATION_FAILED',
+    'That password does not meet the store’s requirements. Please choose a different one.',
+  ],
+  [
+    'PASSWORD_CHANGE_FAILED',
+    'Your password could not be changed. Check your current password and try again.',
+  ],
+  [
+    'IDENTIFIER_CHANGE_TOKEN_INVALID',
+    'This e-mail change link is not valid — it may have been used already. Ask for the change again.',
+  ],
+  [
+    'IDENTIFIER_CHANGE_TOKEN_EXPIRED',
+    'This e-mail change link has expired. Ask for the change again and open the newest link.',
+  ],
+  [
+    'CUSTOMER_NOT_FOUND',
+    'That account does not shop at this store. Sign in with the address you registered here.',
+  ],
+  ['SESSION_NOT_FOUND', 'Your session has ended. Please sign in again.'],
+  [
+    'SESSION_CACHE_READ_FAILED',
+    'We could not check your session just now. Please try again in a moment.',
+  ],
+  [
+    'SESSION_CACHE_WRITE_FAILED',
+    'We could not save your session just now. Please try again in a moment.',
+  ],
+  [
+    'SHOP_API_UNREACHABLE',
+    'We could not reach the store just now. Please check your connection and try again.',
+  ],
+]);
 
 const FALLBACK_MESSAGE = 'Something went wrong. Please check your details and try again.';
 
-/** Human copy for a typed error — never the raw enum, never undefined. */
+/**
+ * Human copy for a typed error — never undefined.
+ *
+ * A code this map has no copy for renders the generic line WITH the code
+ * appended in parentheses: an unmodelled refusal must stay distinguishable
+ * from a platform fault, by the shopper who reports it and by the merchant —
+ * or their agent — who reads the report. Only an error carrying no code at all
+ * renders the generic line bare.
+ */
 export function shopperMessage(error: Pick<ExtractedError, 'code'> | null | undefined): string {
   if (!error?.code) return FALLBACK_MESSAGE;
-  return SHOPPER_MESSAGES[error.code] ?? FALLBACK_MESSAGE;
+  return SHOPPER_MESSAGES.get(error.code) ?? `${FALLBACK_MESSAGE} (${error.code})`;
 }

package/templates/storefront-shadcn/src/lib/seo/noindex.ts

@@ -31,6 +31,10 @@ import { getPublicOrigin } from './public-origin';
  * no content of its own, identical for every visitor, so there is nothing for a
  * search result to be about. One entry covers every language: this set is
  * matched against the locale-STRIPPED path.
+ *
+ * `/account` (#1093) is here for the same funnel reason as `/register`: the
+ * server renders a skeleton, identical for every visitor, and everything the
+ * page shows is one shopper's own — sign-in form or greeting.
  */
 export const NOINDEX_PATHS: readonly string[] = [
   '/cart',
@@ -38,6 +42,7 @@ export const NOINDEX_PATHS: readonly string[] = [
   '/verify',
   '/reset-password',
   '/register',
+  '/account',
 ];
 
 /**

package/templates/storefront-shadcn/src/lib/seo/sitemap-entries.ts

@@ -49,6 +49,8 @@ export const STATIC_ROUTES: readonly StaticRoute[] = [
   // The register page (#1471). Suppressed for the same reason `/cart` is — a
   // form with no content of its own — and listed for this table's stated one.
   { path: '/register', indexable: false },
+  // The account page (#1093): sign-in form or greeting, one shopper's own.
+  { path: '/account', indexable: false },
 ];
 
 /**

package/templates/storefront-shadcn/src/lib/shop-session.ts

@@ -29,6 +29,10 @@ import { syncShopSession } from './session-actions';
  *     it from result extensions on the first mutation) is synced back into
  *     BOTH cookies via the `syncShopSession` server action — the next SSR
  *     pass sees the cart this socket built.
+ *   - A sign-in or sign-out changes WHO the session is, and that never rides
+ *     the capture: `replaceShopSession(token)` disposes the socket, opens a
+ *     fresh one on the new session (or none) and writes both cookies before
+ *     it resolves (`lib/account-session.ts` is its caller).
  *
  * Every operation returns the same `ActionResult` envelope the old Server
  * Actions used, so calling components keep their error contract: typed
@@ -96,6 +100,24 @@ export function isSessionReady(): boolean {
   return config !== null && typeof window !== 'undefined';
 }
 
+/** A client on the channel coordinates, carrying `token` — or no session when null. */
+function openClient(coordinates: ShopSessionConfig, token: string | null): ForgeCartShopClient {
+  const opened = new ForgeCartShopClient({
+    endpoint: coordinates.apiUrl,
+    channelToken: coordinates.channelToken,
+    // Fixed at handshake — the cart, checkout and every error message on
+    // this socket answer in the language the URL resolved to.
+    languageCode: coordinates.languageCode,
+    // The visitor mirror is minted by the middleware before any page can
+    // mount the provider, so it is present on every real navigation; when
+    // it is somehow absent the client simply sends no visitor header and
+    // visitor-subject goals stay unstamped (never guess — #1079).
+    visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
+  });
+  if (token) opened.setAuthToken(token);
+  return opened;
+}
+
 function ensureClient(): ForgeCartShopClient {
   if (!config) {
     throw new Error(
@@ -103,32 +125,63 @@ function ensureClient(): ForgeCartShopClient {
     );
   }
   if (!client) {
-    client = new ForgeCartShopClient({
-      endpoint: config.apiUrl,
-      channelToken: config.channelToken,
-      // Fixed at handshake — the cart, checkout and every error message on
-      // this socket answer in the language the URL resolved to.
-      languageCode: config.languageCode,
-      // The visitor mirror is minted by the middleware before any page can
-      // mount the provider, so it is present on every real navigation; when
-      // it is somehow absent the client simply sends no visitor header and
-      // visitor-subject goals stay unstamped (never guess — #1079).
-      visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
-    });
     const existing = readMirrorSession();
-    if (existing) {
-      client.setAuthToken(existing);
-      syncedToken = existing;
-    }
+    client = openClient(config, existing);
+    if (existing) syncedToken = existing;
   }
   return client;
 }
 
+/**
+ * Move this tab onto another session — the ONE path an identity change takes
+ * (#1093): a sign-in hands over the session it minted, a sign-out hands over
+ * `null`.
+ *
+ * The socket is REPLACED, never re-pointed. Its identity was fixed at its
+ * handshake, and a sign-in that left the live socket speaking for the session
+ * it opened with was refused UNAUTHORIZED on its very next operation — the
+ * greeting — and rendered as a failed sign-in (#1089). So the old client is
+ * disposed, which is terminal (nothing still in flight on it can complete
+ * under the wrong identity), and a fresh one carrying `token` takes its place;
+ * its first operation handshakes as the new session. The platform now rebinds
+ * a connection that signs in, and the SDK re-handshakes on `setAuthToken`; the
+ * replacement stays regardless, so which identity every later operation runs
+ * under is a fact of this module rather than of the platform and SDK versions
+ * a workspace happens to run.
+ *
+ * A sign-out also clears the token the SDK persists in the browser's storage.
+ * A fresh client restores that token when it is constructed, so without the
+ * clear the replacement would carry the very session it was meant to leave.
+ *
+ * Both cookies are written next, and AWAITED — unlike the capture in
+ * `runSessionOp` — so a caller that resolves after this has left the next
+ * server render and the next visit's socket on the same session as this tab.
+ * A failed write is absorbed exactly as the capture absorbs one: the socket
+ * is the authority for this tab, and a lost mirror costs the next visit its
+ * session, never this interaction.
+ *
+ * Before the cart provider has armed the singleton there is no socket to
+ * replace, and only the cookies move.
+ */
+export async function replaceShopSession(token: string | null): Promise<void> {
+  client?.dispose();
+  client = config ? openClient(config, token) : null;
+  if (token === null) client?.clearAuthToken();
+  syncedToken = token;
+  try {
+    await syncShopSession(token);
+  } catch {
+    // Absorbed by design — see above: the socket already carries `token`.
+  }
+}
+
 /**
  * Run one session operation on the shopper's socket and return the typed
  * envelope. Session capture: when the operation minted or rotated the
  * session, the new token is synced into the cookies fire-and-forget —
- * a sync failure never breaks the shopper's interaction.
+ * a sync failure never breaks the shopper's interaction. An operation whose
+ * socket was replaced while it ran captures nothing: its session is no longer
+ * this tab's, and writing it would undo the replacement.
  */
 export async function runSessionOp<T>(
   op: (client: ForgeCartShopClient) => Promise<T>,
@@ -140,7 +193,7 @@ export async function runSessionOp<T>(
   try {
     const data = await op(live);
     const token = live.getAuthToken();
-    if (token && token !== syncedToken) {
+    if (token && token !== syncedToken && live === client) {
       syncedToken = token;
       void syncShopSession(token).catch(() => undefined);
     }