refactor: deal with misc todo comments in frontend

apps/website/src/api/error.ts

@@ -1,13 +1,34 @@
+/**
+ * Mirrors zod v4's `treeifyError()` output shape (see `services/api/src/util/sendBoom.ts`, which spreads it
+ * into the JSON body of any 400 raised from failed body/query/params validation in `core/server.ts`).
+ */
+export interface ZodFieldErrorNode {
+	readonly errors: string[];
+	readonly properties?: Record<string, ZodFieldErrorNode>;
+}
+
 export class APIError extends Error {
 	public readonly statusCode: number;
 
 	public readonly error: string;
 
-	public constructor(statusCode: number, error: string, message: string) {
+	/**
+	 * Per-field validation detail, present only on a 400 raised by `mountRoute`'s zod validation step. `undefined`
+	 * for every other error (domain errors like "not found", auth failures, 5xxs, ...).
+	 */
+	public readonly fieldErrors: Record<string, ZodFieldErrorNode> | undefined;
+
+	public constructor(
+		statusCode: number,
+		error: string,
+		message: string,
+		fieldErrors?: Record<string, ZodFieldErrorNode>,
+	) {
 		super(message);
 		this.name = 'APIError';
 		this.statusCode = statusCode;
 		this.error = error;
+		this.fieldErrors = fieldErrors;
 	}
 
 	/**
@@ -16,4 +37,20 @@ export class APIError extends Error {
 	public isClientError(): boolean {
 		return this.statusCode >= 400 && this.statusCode < 500;
 	}
+
+	/**
+	 * First validation message for a (possibly nested) field, e.g. `error.fieldError('prompt', 'description')`.
+	 * `undefined` if this wasn't a validation error, or the given path had no error.
+	 */
+	public fieldError(...path: string[]): string | undefined {
+		let node: ZodFieldErrorNode | undefined = this.fieldErrors && { errors: [], properties: this.fieldErrors };
+		for (const key of path) {
+			node = node?.properties?.[key];
+			if (!node) {
+				return undefined;
+			}
+		}
+
+		return node?.errors[0];
+	}
 }

apps/website/src/api/errorBanner.ts

@@ -0,0 +1,23 @@
+import { atom, getDefaultStore } from 'jotai';
+
+export interface ErrorBannerMessage {
+	readonly id: number;
+	readonly message: string;
+}
+
+export const errorBannerMessagesAtom = atom<ErrorBannerMessage[]>([]);
+
+let nextId = 0;
+
+/**
+ * Queues a dismissible global error banner (`ErrorBanner`, mounted in `Providers`). Called from outside React
+ * (`queryClient.ts`'s `QueryCache.onError`), hence writing through jotai's default store rather than a hook.
+ */
+export function pushErrorBanner(message: string): void {
+	const id = nextId++;
+	getDefaultStore().set(errorBannerMessagesAtom, (prev) => [...prev, { id, message }]);
+}
+
+export function dismissErrorBanner(id: number): void {
+	getDefaultStore().set(errorBannerMessagesAtom, (prev) => prev.filter((banner) => banner.id !== id));
+}

apps/website/src/api/fetch.ts

@@ -1,6 +1,7 @@
 import { NewAccessTokenHeader, RefreshTokenCookie } from '@chatsift/core';
 import type { DehydratedState } from '@tanstack/react-query';
 import { getDefaultStore } from 'jotai';
+import type { ZodFieldErrorNode } from './error';
 import { APIError } from './error';
 import { clearCachedAccessToken, getCachedAccessToken, setCachedAccessToken } from './serverTokenCache';
 import { accessTokenAtom } from './token';
@@ -30,8 +31,14 @@ function buildURL(path: string, query?: FetchOptions['query']): string {
 
 async function parseError(response: Response): Promise<APIError> {
 	try {
-		const data = (await response.json()) as { error: string; message: string; statusCode: number };
-		return new APIError(data.statusCode, data.error, data.message);
+		const data = (await response.json()) as {
+			error: string;
+			message: string;
+			// Present (via `sendBoom`'s `treeifyError` spread) only on a zod-validation 400
+			properties?: Record<string, ZodFieldErrorNode>;
+			statusCode: number;
+		};
+		return new APIError(data.statusCode, data.error, data.message, data.properties);
 	} catch (error) {
 		console.error('failed to parse error response', {
 			status: response.status,

apps/website/src/api/queryClient.ts

@@ -1,16 +1,29 @@
 import { isServer, QueryCache, QueryClient } from '@tanstack/react-query';
 import { APIError } from './error';
+import { pushErrorBanner } from './errorBanner';
 
 export function makeQueryClient(): QueryClient {
 	return new QueryClient({
 		queryCache: new QueryCache({
-			// TODO: Handle in some way
-			onError: (error) => {
+			onError: (error, query) => {
 				if (error instanceof APIError) {
 					console.error('Query error:', { statusCode: error.statusCode, error: error.error, message: error.message });
+
+					// 401s mean the session expired — `NavGateProvider` already redirects to Discord OAuth off the same
+					// error, so a banner here would just flash right before that navigation happens.
+					if (error.statusCode === 401) {
+						return;
+					}
 				} else {
 					console.error('Network error:', error);
 				}
+
+				// Only bother the user for a *background* refetch failure (stale data is still on screen, and they'd
+				// otherwise have no idea the refresh silently failed). A first-load failure (no cached data yet) is
+				// already surfaced in-place by whichever component renders `UserErrorHandler` for that query's `error`.
+				if (query.state.data !== undefined) {
+					pushErrorBanner(error instanceof APIError ? error.message : 'Something went wrong. Please try again.');
+				}
 			},
 		}),
 		defaultOptions: {

apps/website/src/app/dashboard/[id]/ama/amas/[amaId]/_components/AMADetails.tsx

@@ -2,6 +2,7 @@
 
 import { useParams, useRouter } from 'next/navigation';
 import { useState } from 'react';
+import { APIError } from '@/api/error';
 import type { PossiblyMissingChannelInfo } from '@/api/routes/ama';
 import { useAMA, useRepostPrompt, useUpdateAMA } from '@/api/routes/ama';
 import type { GuildChannelInfo } from '@/api/routes/guilds';
@@ -24,6 +25,7 @@ export function AMADetails() {
 	const params = useParams<{ amaId: string; id: string }>();
 	const router = useRouter();
 	const [showEndConfirm, setShowEndConfirm] = useState(false);
+	const [actionError, setActionError] = useState<string | null>(null);
 
 	const { data: ama, isLoading } = useAMA(params.id, params.amaId);
 	const updateAMA = useUpdateAMA(params.id, params.amaId);
@@ -51,26 +53,38 @@ export function AMADetails() {
 			return;
 		}
 
+		setActionError(null);
+
 		try {
 			await updateAMA.mutateAsync({ ended: true });
 			router.push(`/dashboard/${params.id}/ama/amas`);
 		} catch (error) {
+			setActionError(error instanceof APIError ? error.message : 'Failed to end AMA. Please try again.');
 			console.error('Failed to end AMA:', error);
 		} finally {
 			setShowEndConfirm(false);
 		}
 	};
 
 	const handleRepostPrompt = async () => {
+		setActionError(null);
+
 		try {
 			await repostPrompt.mutateAsync();
 		} catch (error) {
+			setActionError(error instanceof APIError ? error.message : 'Failed to repost the prompt. Please try again.');
 			console.error('Failed to repost prompt:', error);
 		}
 	};
 
 	return (
 		<div className="grid gap-6 lg:grid-cols-2">
+			{actionError && (
+				<p className="rounded-lg border border-misc-danger bg-misc-danger/10 p-3 text-sm text-misc-danger lg:col-span-2">
+					{actionError}
+				</p>
+			)}
+
 			{/* Session Information Card */}
 			<div className="rounded-lg border border-on-secondary bg-card p-6 dark:border-on-secondary-dark dark:bg-card-dark">
 				<h2 className="text-xl font-medium text-primary dark:text-primary-dark mb-4">Session Information</h2>

apps/website/src/app/dashboard/[id]/ama/amas/new/_components/CreateAMAForm.tsx

@@ -155,14 +155,37 @@ export function CreateAMAForm() {
 			router.replace(`/dashboard/${guildId}/ama/amas`);
 		} catch (error) {
 			if (error instanceof APIError && error.statusCode === 422) {
-				if (promptMode === 'raw') {
-					setGeneralError('Invalid prompt data. Please check your JSON data and try again.');
-				} else {
-					setGeneralError(
-						'An unknown validation error occured. Please contact support in regards to this error. For the tech savvy, the request response includes more information.',
-					);
-				}
+				// `badData` from createAMA.ts — Discord rejected the composed message (only reachable in raw mode,
+				// since normal-mode prompts are always well-formed by construction).
+				setGeneralError('Invalid prompt data. Please check your JSON data and try again.');
+				return;
+			}
 
+			// A 400 here means the server's zod schema rejected the request even though our own client-side
+			// `validateForm` passed — map whatever field-level detail it returned back onto the same `errors` state
+			// `validateForm` uses, so it renders exactly like a client-side validation failure.
+			if (error instanceof APIError && error.statusCode === 400) {
+				const promptField = promptMode === 'raw' ? 'prompt_raw' : 'prompt';
+				const candidates: [keyof FormData, string | undefined][] = [
+					['title', error.fieldError('title')],
+					['answersChannelId', error.fieldError('answersChannelId')],
+					['promptChannelId', error.fieldError('promptChannelId')],
+					['modQueueId', error.fieldError('modQueueId')],
+					['flaggedQueueId', error.fieldError('flaggedQueueId')],
+					['guestQueueId', error.fieldError('guestQueueId')],
+					['allowedQuestionUploads', error.fieldError('allowedQuestionUploads')],
+					['description', error.fieldError(promptField, 'description')],
+					['plainText', error.fieldError(promptField, 'plainText')],
+					['imageURL', error.fieldError(promptField, 'imageURL')],
+					['thumbnailURL', error.fieldError(promptField, 'thumbnailURL')],
+				];
+
+				const newErrors: FormErrors = Object.fromEntries(
+					candidates.filter((entry): entry is [keyof FormData, string] => entry[1] !== undefined),
+				);
+
+				setErrors(newErrors);
+				setGeneralError(Object.keys(newErrors).length > 0 ? null : error.message);
 				return;
 			}
 

apps/website/src/app/dashboard/[id]/ama/page.tsx

@@ -1,6 +1,7 @@
 import Link from 'next/link';
 import { DashboardCrumbs } from '../../_components/DashboardCrumbs';
 import { Heading } from '@/components/common/Heading';
+import { SvgAMA } from '@/components/icons/SvgAMA';
 
 export default async function AMAPage({ params }: PageProps<'/dashboard/[id]/ama/amas'>) {
 	const { id } = await params;
@@ -15,9 +16,8 @@ export default async function AMAPage({ params }: PageProps<'/dashboard/[id]/ama
 					href={`/dashboard/${id}/ama/amas`}
 					prefetch
 				>
-					{/* TODO */}
-					<div className="flex h-12 w-12 items-center justify-center rounded-lg bg-misc-accent text-2xl font-bold text-primary-dark">
-						Q
+					<div className="flex h-12 w-12 items-center justify-center rounded-lg bg-on-tertiary dark:bg-on-tertiary-dark">
+						<SvgAMA height={28} width={28} />
 					</div>
 					<div className="flex flex-col">
 						<p className="text-lg font-medium text-primary dark:text-primary-dark">Manage AMAs</p>

apps/website/src/app/dashboard/[id]/page.tsx

@@ -73,7 +73,6 @@ export default function GuildPage() {
 				<div className="flex flex-col gap-3">
 					<SectionCard
 						href={`/dashboard/${guild.id}/settings`}
-						// TODO
 						icon={<FaWrench className="text-misc-accent h-6 w-6" />}
 						subtext="View and modify general settings related to your community"
 						text="General settings"

apps/website/src/app/dashboard/[id]/settings/_components/AddGrantCard.tsx

@@ -27,13 +27,15 @@ export function AddGrantCard({ guildId }: AddGrantCardProps) {
 			await createGrant.mutateAsync({ userId: userId.trim() });
 			setUserId('');
 		} catch (error) {
+			// Route sends 404 (user doesn't exist on Discord), 422 (`badData`, grant already exists), or 400
+			// (zod validation failed on `userId` itself, e.g. not a valid snowflake) — see createGrant.ts.
 			if (error instanceof APIError) {
 				if (error.statusCode === 404) {
 					setError('User not found');
-				} else if (error.statusCode === 400) {
-					setError('Grant already exists for this user');
 				} else if (error.statusCode === 422) {
-					setError('Invalid User ID');
+					setError('Grant already exists for this user');
+				} else if (error.statusCode === 400) {
+					setError(error.fieldError('userId') ?? 'Invalid User ID');
 				}
 
 				return;

apps/website/src/components/common/ErrorBanner.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { useAtomValue } from 'jotai';
+import { useEffect } from 'react';
+import { FaExclamationTriangle, FaTimes } from 'react-icons/fa';
+import { dismissErrorBanner, errorBannerMessagesAtom } from '@/api/errorBanner';
+
+const AUTO_DISMISS_MS = 8_000;
+
+function Banner({ id, message }: { readonly id: number; readonly message: string }) {
+	useEffect(() => {
+		const timeout = setTimeout(() => dismissErrorBanner(id), AUTO_DISMISS_MS);
+		return () => clearTimeout(timeout);
+	}, [id]);
+
+	return (
+		<div className="flex items-center gap-3 rounded-lg border-[1px] border-misc-danger bg-card p-3 shadow-lg dark:bg-card-dark">
+			<FaExclamationTriangle className="h-4 w-4 shrink-0 text-misc-danger" />
+			<p className="text-sm text-primary dark:text-primary-dark">{message}</p>
+			<button
+				aria-label="Dismiss"
+				className="ml-auto text-secondary hover:text-primary dark:text-secondary-dark dark:hover:text-primary-dark"
+				onClick={() => dismissErrorBanner(id)}
+				type="button"
+			>
+				<FaTimes className="h-3.5 w-3.5" />
+			</button>
+		</div>
+	);
+}
+
+/**
+ * Surfaces background query failures (a refetch that failed while stale data is still on screen — see
+ * `queryClient.ts`'s `onError`). First-load errors are handled locally by `UserErrorHandler` instead, so this
+ * only needs to catch the "user is already looking at data and something broke quietly" case.
+ */
+export function ErrorBanner() {
+	const banners = useAtomValue(errorBannerMessagesAtom);
+
+	if (banners.length === 0) {
+		return null;
+	}
+
+	return (
+		<div className="fixed bottom-4 right-4 z-50 flex w-full max-w-sm flex-col gap-2">
+			{banners.map((banner) => (
+				<Banner id={banner.id} key={banner.id} message={banner.message} />
+			))}
+		</div>
+	);
+}

apps/website/src/components/common/Providers.tsx

@@ -6,6 +6,7 @@ import { Provider as JotaiProvider } from 'jotai';
 import { ThemeProvider } from 'next-themes';
 import type { PropsWithChildren } from 'react';
 import { getBrowserQueryClient } from '@/api/queryClient';
+import { ErrorBanner } from '@/components/common/ErrorBanner';
 
 export function Providers({ children }: PropsWithChildren) {
 	const queryClient = getBrowserQueryClient();
@@ -14,6 +15,7 @@ export function Providers({ children }: PropsWithChildren) {
 		<QueryClientProvider client={queryClient}>
 			<JotaiProvider>
 				<ThemeProvider attribute="class">{children}</ThemeProvider>
+				<ErrorBanner />
 			</JotaiProvider>
 			<ReactQueryDevtools buttonPosition="bottom-right" initialIsOpen={false} />
 		</QueryClientProvider>

apps/website/src/components/user/UserErrorHandler.tsx

@@ -1,12 +1,25 @@
+import { FaExclamationTriangle } from 'react-icons/fa';
 import { LoginButton } from './LoginButton';
 import { APIError } from '@/api/error';
 
-// TODO?
+/**
+ * Handles the first-load error state for `useMe()` consumers (`NavGateProvider`, `UserDesktop`, `UserMobile`) —
+ * no cached user data exists yet, so there's nothing to keep showing underneath. Background refetch failures
+ * (data already on screen) go through the global `ErrorBanner` instead (see `queryClient.ts`'s `onError`).
+ */
 export function UserErrorHandler({ error }: { readonly error: Error }) {
 	if (error instanceof APIError && error.statusCode === 401) {
 		return <LoginButton />;
 	}
 
 	console.error(error);
-	return <>Error</>;
+	return (
+		<div className="flex w-full flex-col items-center gap-2 rounded-lg border-[1px] border-misc-danger bg-card p-8 text-center dark:bg-card-dark">
+			<FaExclamationTriangle className="h-8 w-8 text-misc-danger" />
+			<p className="text-lg font-medium text-primary dark:text-primary-dark">Something went wrong</p>
+			<p className="text-sm text-secondary dark:text-secondary-dark">
+				{error instanceof APIError ? error.message : 'Please try refreshing the page.'}
+			</p>
+		</div>
+	);
 }