feat(#417): create auth-errors.ts with PDA error parsing and mapping

Adds AuthErrorCode type, ParsedAuthError interface, parseAuthError() classifier,
and getErrorMessage() helper. All messages use PDA-friendly language.

Refs #417

apps/web/src/lib/auth/auth-errors.ts

@@ -0,0 +1,173 @@
+/**
+ * Auth error codes, PDA-friendly message mapping, and error parsing utilities.
+ *
+ * All user-facing messages follow PDA-friendly language guidelines:
+ * no alarming words like OVERDUE, URGENT, MUST, CRITICAL, REQUIRED, ERROR, FAILED.
+ */
+
+/** Union of all recognised auth error codes. */
+export type AuthErrorCode =
+  | "access_denied"
+  | "invalid_credentials"
+  | "server_error"
+  | "network_error"
+  | "rate_limited"
+  | "session_expired"
+  | "unknown";
+
+/** A parsed, UI-ready representation of an auth error. */
+export interface ParsedAuthError {
+  code: AuthErrorCode;
+  /** PDA-friendly message suitable for display to the user. */
+  message: string;
+  /** Whether the operation that caused this can be retried. */
+  retryable: boolean;
+}
+
+/**
+ * PDA-friendly error messages keyed by error code.
+ * Uses calm, informational language throughout.
+ */
+const ERROR_MESSAGES: Record<AuthErrorCode, string> = {
+  access_denied: "Authentication paused. Please try again when ready.",
+  invalid_credentials: "The email and password combination wasn't recognized.",
+  server_error: "The service is taking a break. Please try again in a moment.",
+  network_error: "Unable to connect. Check your network and try again.",
+  rate_limited: "You've tried a few times. Take a moment and try again shortly.",
+  session_expired: "Your session ended. Please sign in again when ready.",
+  unknown: "Authentication didn't complete. Please try again when ready.",
+};
+
+/** Error codes that are safe to retry automatically. */
+const RETRYABLE_CODES: ReadonlySet<AuthErrorCode> = new Set<AuthErrorCode>([
+  "network_error",
+  "server_error",
+]);
+
+/** Set of recognised error code strings for fast membership testing. */
+const KNOWN_CODES: ReadonlySet<string> = new Set<string>([
+  "access_denied",
+  "invalid_credentials",
+  "server_error",
+  "network_error",
+  "rate_limited",
+  "session_expired",
+  "unknown",
+]);
+
+/**
+ * Type-guard: checks whether a string value is a known {@link AuthErrorCode}.
+ */
+function isAuthErrorCode(value: string): value is AuthErrorCode {
+  return KNOWN_CODES.has(value);
+}
+
+/**
+ * Type-guard: checks whether a value looks like an HTTP response object
+ * with a numeric `status` property.
+ */
+function isHttpResponseLike(value: unknown): value is { status: number } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    typeof (value as { status: unknown }).status === "number"
+  );
+}
+
+/**
+ * Map an HTTP status code to an {@link AuthErrorCode}.
+ */
+function httpStatusToCode(status: number): AuthErrorCode {
+  if (status === 401 || status === 403) {
+    return "invalid_credentials";
+  }
+  if (status === 429) {
+    return "rate_limited";
+  }
+  if (status >= 500) {
+    return "server_error";
+  }
+  return "unknown";
+}
+
+/**
+ * Build a {@link ParsedAuthError} for the given code.
+ */
+function buildParsedError(code: AuthErrorCode): ParsedAuthError {
+  return {
+    code,
+    message: ERROR_MESSAGES[code],
+    retryable: RETRYABLE_CODES.has(code),
+  };
+}
+
+/**
+ * Parse an unknown error value into a structured, PDA-friendly
+ * {@link ParsedAuthError}.
+ *
+ * Handles:
+ * - `TypeError` whose message contains "fetch" -> `network_error`
+ * - Generic `Error` objects with keyword-based message matching
+ * - HTTP-response-shaped objects with a numeric `status` field
+ * - Plain strings that match a known error code
+ * - Anything else falls back to `unknown`
+ */
+export function parseAuthError(error: unknown): ParsedAuthError {
+  // 1. TypeError with "fetch" in message -> network error
+  if (error instanceof TypeError && error.message.toLowerCase().includes("fetch")) {
+    return buildParsedError("network_error");
+  }
+
+  // 2. Generic Error objects — match on message keywords
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+
+    if (msg.includes("unauthorized") || msg.includes("forbidden")) {
+      return buildParsedError("invalid_credentials");
+    }
+    if (msg.includes("rate limit") || msg.includes("too many")) {
+      return buildParsedError("rate_limited");
+    }
+    if (
+      msg.includes("internal server") ||
+      msg.includes("service unavailable") ||
+      msg.includes("bad gateway") ||
+      msg.includes("gateway timeout")
+    ) {
+      return buildParsedError("server_error");
+    }
+    if (msg.includes("session") && msg.includes("expired")) {
+      return buildParsedError("session_expired");
+    }
+    if (msg.includes("network") || msg.includes("connection")) {
+      return buildParsedError("network_error");
+    }
+
+    return buildParsedError("unknown");
+  }
+
+  // 3. HTTP response-like objects (e.g. { status: 429 })
+  if (isHttpResponseLike(error)) {
+    return buildParsedError(httpStatusToCode(error.status));
+  }
+
+  // 4. Plain string matching a known error code (e.g. from URL query params)
+  if (typeof error === "string") {
+    if (isAuthErrorCode(error)) {
+      return buildParsedError(error);
+    }
+    return buildParsedError("unknown");
+  }
+
+  // 5. Fallback
+  return buildParsedError("unknown");
+}
+
+/**
+ * Look up the PDA-friendly message for a given {@link AuthErrorCode}.
+ * Returns the `unknown` message for any unrecognised code.
+ */
+export function getErrorMessage(code: AuthErrorCode): string {
+  return ERROR_MESSAGES[code] ?? ERROR_MESSAGES.unknown;
+}