@remit/web-client 0.0.280 → 0.0.282

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.280",
+  "version": "0.0.282",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/auth/BetterAuthShell.tsx

@@ -10,6 +10,7 @@ import {
 import { type FormEvent, type ReactNode, useState } from "react";
 import { AppShellSkeleton } from "@/components/layout/AppShellSkeleton";
 import { FatalErrorOverlay } from "@/components/ui/FatalErrorOverlay";
+import { openBugReport } from "@/lib/bug-report";
 import { authFooterNote } from "./account-menu-mode";
 import {
 	type AuthRequest,
@@ -22,6 +23,8 @@ import {
 	isBetterAuthEnabled,
 	isSignUpDisabledError,
 } from "./better-auth-config";
+import { SessionRateLimited } from "./SessionRateLimited";
+import { classifySessionQuery, type SessionQuery } from "./session-state";
 
 type Mode = "signIn" | "signUp";
 
@@ -189,10 +192,42 @@ export const SignInForm = () => {
 	);
 };
 
-export const BetterAuthShell = ({ children }: BetterAuthShellProps) => {
-	const { data: session, isPending } = authClient.useSession();
+interface SessionGateProps {
+	session: SessionQuery;
+	onRetry: () => void;
+	children: ReactNode;
+}
 
-	if (isPending) return <AppShellSkeleton />;
-	if (session) return <>{children}</>;
+/**
+ * What the app shows for each state the session lookup can be in, separated
+ * from the hook that feeds it so every state can be driven directly.
+ */
+export const SessionGate = ({
+	session,
+	onRetry,
+	children,
+}: SessionGateProps) => {
+	const state = classifySessionQuery(session);
+
+	if (state.kind === "active") return <>{children}</>;
+	if (state.kind === "pending") return <AppShellSkeleton />;
+	if (state.kind === "rateLimited") {
+		return <SessionRateLimited onRetry={onRetry} onReport={openBugReport} />;
+	}
 	return <SignInForm />;
 };
+
+export const BetterAuthShell = ({ children }: BetterAuthShellProps) => {
+	const { data, isPending, error, refetch } = authClient.useSession();
+
+	return (
+		<SessionGate
+			session={{ data, isPending, error }}
+			onRetry={() => {
+				void refetch();
+			}}
+		>
+			{children}
+		</SessionGate>
+	);
+};

package/src/auth/SessionRateLimited.stories.tsx

@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { SessionRateLimited } from "./SessionRateLimited";
+
+/**
+ * What a 429 on the session lookup looks like (#441). Before this state
+ * existed the gate fell through to the sign-in screen, so a throttled instance
+ * told everyone behind the address that they had been logged out.
+ */
+const meta: Meta<typeof SessionRateLimited> = {
+	title: "Screens/SessionRateLimited",
+	component: SessionRateLimited,
+	parameters: { layout: "fullscreen" },
+	args: {
+		onRetry: () => undefined,
+		onReport: () => undefined,
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof SessionRateLimited>;
+
+export const Default: Story = {};
+
+export const Dark: Story = {
+	parameters: { theme: "dark" },
+};

package/src/auth/SessionRateLimited.tsx

@@ -0,0 +1,39 @@
+import { AuthCard, AuthHero, Banner, Button } from "@remit/ui";
+
+export interface SessionRateLimitedProps {
+	onRetry: () => void;
+	onReport: () => void;
+}
+
+/**
+ * The session could not be checked because the server is throttling this
+ * address. Shown instead of the sign-in screen, which would claim a sign-out
+ * that never happened (#441). The limits are keyed by IP, so a household, an
+ * office, a VPN exit or a handful of open tabs all spend one budget — the copy
+ * says so, because otherwise a single user cannot explain what they did wrong.
+ */
+export const SessionRateLimited = ({
+	onRetry,
+	onReport,
+}: SessionRateLimitedProps) => (
+	<AuthCard>
+		<AuthHero />
+		<div className="flex flex-col gap-4 rounded-lg border border-line bg-surface p-7 shadow-lg">
+			<Banner tone="warning">
+				<p className="font-medium">Too many requests from this address</p>
+				<p className="mt-1">
+					The server is limiting requests from your network address, so it could
+					not check whether you are signed in. You have not been signed out.
+				</p>
+			</Banner>
+			<p className="text-sm text-fg-muted">
+				Wait a minute and try again. Everyone behind the same address — other
+				people on this network, and every tab you have open — shares one limit.
+			</p>
+			<Button onClick={onRetry}>Try again</Button>
+			<Button variant="ghost" size="sm" onClick={onReport}>
+				Report an issue
+			</Button>
+		</div>
+	</AuthCard>
+);

package/src/auth/auth-error.test.ts

@@ -52,6 +52,17 @@ describe("classifyAuthError", () => {
 		);
 	});
 
+	it("treats a 429 as rate limited, not as a rejected credential (#441)", () => {
+		assert.equal(
+			classifyAuthError({
+				status: 429,
+				statusText: "Too Many Requests",
+				message: "Too many requests. Please try again later.",
+			}),
+			"rateLimited",
+		);
+	});
+
 	it("treats a statusless failure as network", () => {
 		assert.equal(classifyAuthError(new Error("Failed to fetch")), "network");
 	});
@@ -82,6 +93,15 @@ describe("authInlineMessage", () => {
 	it("gives a connection hint for a network error", () => {
 		assert.match(authInlineMessage(new Error("boom"), "network"), /offline/i);
 	});
+
+	it("says the limit is shared by address, over the server's bare wording", () => {
+		const message = authInlineMessage(
+			{ status: 429, message: "Too many requests. Please try again later." },
+			"rateLimited",
+		);
+		assert.match(message, /this address/i);
+		assert.match(message, /wait a minute/i);
+	});
 });
 
 describe("buildFatalAuthMessage", () => {

package/src/auth/auth-error.ts

@@ -9,12 +9,16 @@ import { reportFatalError } from "@/lib/fatal-error";
  *  - "validation" — an expected, user-correctable rejection the server
  *                   described (email already registered, weak password, wrong
  *                   credentials). Inline, surfacing the server's own message.
+ *  - "rateLimited" — a 429. Nothing is wrong with the credentials or the
+ *                   deployment; the address has spent its budget and the same
+ *                   attempt works after a wait. Inline, and named as its own
+ *                   thing so it is never read as a rejection (#441).
  *  - "fatal"      — a 404, or any other unexpected 4xx/5xx from our own API. The
  *                   deployment or the client/server contract is broken and there
  *                   is nothing the user can retry their way out of. Escalates to
  *                   the full-screen fatal page with a bug-report link.
  */
-export type AuthErrorClass = "network" | "validation" | "fatal";
+export type AuthErrorClass = "network" | "validation" | "rateLimited" | "fatal";
 
 /** The request being attempted, for a fatal report that names method and path. */
 export interface AuthRequest {
@@ -25,6 +29,8 @@ export interface AuthRequest {
 /** better-auth's client sentinel for a fetch that never got an HTTP response. */
 const FETCH_ERROR_STATUS_TEXT = "Fetch Error";
 
+const TOO_MANY_REQUESTS = 429;
+
 const readString = (error: unknown, key: string): string | undefined => {
 	if (error && typeof error === "object" && key in error) {
 		const value = (error as Record<string, unknown>)[key];
@@ -53,6 +59,7 @@ export const classifyAuthError = (error: unknown): AuthErrorClass => {
 	if (isNetworkFailure(error)) return "network";
 	const status = getErrorStatus(error);
 	if (status === undefined) return "fatal";
+	if (status === TOO_MANY_REQUESTS) return "rateLimited";
 	if (status === 404 || status >= 500) return "fatal";
 	if (authServerMessage(error)) return "validation";
 	return "fatal";
@@ -61,12 +68,18 @@ export const classifyAuthError = (error: unknown): AuthErrorClass => {
 const NETWORK_MESSAGE =
 	"Can't reach the server. You may be offline — check your connection and try again.";
 
-/** The inline banner text for a network or validation failure. */
+// The server's own 429 body says only "Too many requests"; it cannot say what
+// the budget is shared with, and that is the part a single user needs to hear.
+const RATE_LIMITED_MESSAGE =
+	"Too many requests from this address. Everyone behind the same address — other people on this network, and every tab you have open — shares one limit. Wait a minute and try again.";
+
+/** The inline banner text for a network, rate-limited or validation failure. */
 export const authInlineMessage = (
 	error: unknown,
 	kind: AuthErrorClass,
 ): string => {
 	if (kind === "network") return NETWORK_MESSAGE;
+	if (kind === "rateLimited") return RATE_LIMITED_MESSAGE;
 	return authServerMessage(error) ?? "Please check your details and try again.";
 };
 

package/src/auth/session-gate.render.test.ts

@@ -0,0 +1,77 @@
+/**
+ * #441: a 429 on the session lookup put the sign-in screen up, so a throttled
+ * instance told everyone behind the address they had been logged out. This
+ * renders the gate the app actually mounts, one state per case.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { SessionGate } from "./BetterAuthShell";
+import type { SessionQuery } from "./session-state";
+
+const APP = "the-signed-in-app";
+
+const render = (session: SessionQuery): string =>
+	renderToString(
+		createElement(SessionGate, {
+			session,
+			onRetry: () => undefined,
+			// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+			children: APP,
+		}) as never,
+	);
+
+const tooManyRequests = {
+	status: 429,
+	statusText: "Too Many Requests",
+	error: { message: "Too many requests. Please try again later." },
+};
+
+describe("the session gate", () => {
+	it("shows the app when a session is held", () => {
+		const html = render({
+			data: { user: { id: "u1" } },
+			isPending: false,
+			error: null,
+		});
+		assert.match(html, new RegExp(APP));
+	});
+
+	it("shows the sign-in screen when the lookup answered without a session", () => {
+		const html = render({ data: null, isPending: false, error: null });
+		assert.match(html, /Sign in/);
+		assert.doesNotMatch(html, /Too many requests/i);
+	});
+
+	it("names the rate limit instead of claiming a sign-out", () => {
+		const html = render({
+			data: null,
+			isPending: false,
+			error: tooManyRequests,
+		});
+		assert.match(html, /Too many requests from this address/i);
+		assert.match(html, /have not been signed out/i);
+		assert.doesNotMatch(html, /Create account/);
+	});
+
+	it("offers a way to retry and a way to report", () => {
+		const html = render({
+			data: null,
+			isPending: false,
+			error: tooManyRequests,
+		});
+		assert.match(html, /Try again/);
+		assert.match(html, /Report an issue/);
+	});
+
+	it("announces the refusal rather than leaving it to colour", () => {
+		const html = render({
+			data: null,
+			isPending: false,
+			error: tooManyRequests,
+		});
+		assert.match(html, /role="alert"/);
+	});
+});

package/src/auth/session-state.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { classifySessionQuery } from "./session-state";
+
+const rateLimited = {
+	status: 429,
+	statusText: "Too Many Requests",
+	error: { message: "Too many requests. Please try again later." },
+};
+
+describe("classifySessionQuery", () => {
+	it("is pending only while nothing has come back", () => {
+		assert.deepEqual(
+			classifySessionQuery({ data: null, isPending: true, error: null }),
+			{ kind: "pending" },
+		);
+	});
+
+	it("is active whenever a session is held", () => {
+		assert.deepEqual(
+			classifySessionQuery({
+				data: { user: { id: "u1" } },
+				isPending: false,
+				error: null,
+			}),
+			{ kind: "active" },
+		);
+	});
+
+	it("keeps a held session through a throttled refetch", () => {
+		assert.deepEqual(
+			classifySessionQuery({
+				data: { user: { id: "u1" } },
+				isPending: false,
+				error: rateLimited,
+			}),
+			{ kind: "active" },
+		);
+	});
+
+	it("reads a 429 as rate limited, never as signed out (#441)", () => {
+		assert.deepEqual(
+			classifySessionQuery({
+				data: null,
+				isPending: false,
+				error: rateLimited,
+			}),
+			{ kind: "rateLimited" },
+		);
+	});
+
+	it("is signed out only when the lookup answered without a session", () => {
+		assert.deepEqual(
+			classifySessionQuery({ data: null, isPending: false, error: null }),
+			{ kind: "signedOut" },
+		);
+		assert.deepEqual(
+			classifySessionQuery({
+				data: null,
+				isPending: false,
+				error: { status: 401, statusText: "Unauthorized" },
+			}),
+			{ kind: "signedOut" },
+		);
+	});
+});

package/src/auth/session-state.ts

@@ -0,0 +1,41 @@
+import { getErrorStatus } from "@/lib/error-classifier";
+
+/**
+ * What the session query is actually telling the gate.
+ *
+ * "signedOut" is the only state that may put the sign-in screen up. A session
+ * lookup that failed for any other reason has not established that the user is
+ * signed out, and rendering the sign-in screen for it tells them they were
+ * logged out when they were not (#441).
+ */
+export type SessionState =
+	| { kind: "pending" }
+	| { kind: "active" }
+	| { kind: "rateLimited" }
+	| { kind: "signedOut" };
+
+/** The shape better-auth's `useSession` hands back, read structurally. */
+export interface SessionQuery {
+	data: unknown;
+	isPending: boolean;
+	error: unknown;
+}
+
+const TOO_MANY_REQUESTS = 429;
+
+/**
+ * A held session outranks everything: better-auth keeps `data` across a failed
+ * refetch unless the failure was a 401, so a throttled refresh must not evict a
+ * signed-in user.
+ */
+export const classifySessionQuery = ({
+	data,
+	isPending,
+	error,
+}: SessionQuery): SessionState => {
+	if (data) return { kind: "active" };
+	if (isPending) return { kind: "pending" };
+	if (getErrorStatus(error) === TOO_MANY_REQUESTS)
+		return { kind: "rateLimited" };
+	return { kind: "signedOut" };
+};

package/src/test-support/fixtures.ts

@@ -27,6 +27,7 @@ export const makeMailbox = (
 	lastSyncUid: 0,
 	highWaterMarkUid: 0,
 	lastMessageSyncAt: 0,
+	syncStatus: "synced",
 	createdAt: 0,
 	updatedAt: 0,
 	...overrides,