first commit

docs/ui/react/react-auth/src/error-codes/error-codes.md

@@ -0,0 +1,79 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`error-codes.ts` defines the stable error-code registry for `@suaveplan/react-auth` plus the ten typed `ReactAuthError` subclasses that wrap each code. Every code is registered through `@suaveplan/error`'s `defineCodes("REACT_AUTH", [...])`, which produces a frozen `{ KEY: "REACT_AUTH.KEY" }` map and forms the basis for programmatic error handling, OTel attribute tagging, and i18n key resolution. Each subclass extends `ReactAuthError` (which extends `SuaveplanError<ReactAuthErrorCode>`), carries its own constructor with structured `context` fields when appropriate, and is thrown from at least one production path. Consumers can `catch` either `ReactAuthError` for the family or a specific subclass for narrow handling.
+
+## Features
+
+- Frozen `REACT_AUTH_CODES` map with 10 stable codes.
+- Typed `ReactAuthError` base + 10 typed subclasses.
+- Structured `cause` chain support via `SuaveplanError`.
+- Optional `context` payload propagation (e.g. `permission` on `ReactAuthPermissionDeniedError`).
+- `ReactAuthErrorCode` union type for switch-narrowed handling.
+
+## Usage: Basic
+
+```ts
+import { ReactAuthError, ReactAuthConfigInvalidError } from "@suaveplan/react-auth";
+
+try {
+    createAuthClient({ baseURL: "not-a-url" });
+} catch (err) {
+    if (err instanceof ReactAuthConfigInvalidError) {
+        console.error("config invalid", err.code, err.message);
+    }
+}
+```
+
+## Usage: Advanced
+
+Switch on `error.code` for routing across the family:
+
+```ts
+import {
+    REACT_AUTH_CODES,
+    type ReactAuthErrorCode,
+    ReactAuthError,
+} from "@suaveplan/react-auth";
+
+function describe(err: unknown): string {
+    if (!(err instanceof ReactAuthError)) return "unknown";
+    const code: ReactAuthErrorCode = err.code;
+    switch (code) {
+        case REACT_AUTH_CODES.CONFIG_INVALID:
+            return "configuration failure";
+        case REACT_AUTH_CODES.CONTEXT_MISSING:
+            return "provider not mounted";
+        case REACT_AUTH_CODES.GUARD_PROPS_INVALID:
+        case REACT_AUTH_CODES.GUARD_OPTIONS_INVALID:
+            return "guard misuse";
+        default:
+            return err.code;
+    }
+}
+```
+
+## API Reference
+
+- `const REACT_AUTH_CODES` — frozen map of 10 codes (`CONFIG_INVALID`, `CONTEXT_MISSING`, `GUARD_PROPS_INVALID`, `GUARD_OPTIONS_INVALID`, `CLIENT_NOT_INITIALISED`, `BETTER_AUTH_RESPONSE_INVALID`, `SIGN_IN_FAILED`, `SIGN_UP_FAILED`, `SESSION_FETCH_FAILED`, `PERMISSION_DENIED`).
+- `type ReactAuthErrorCode` — union of every code value.
+- `class ReactAuthError extends SuaveplanError<ReactAuthErrorCode>` — base.
+- `class ReactAuthConfigInvalidError` — invalid `AuthClientConfig`.
+- `class ReactAuthContextMissingError` — `useAuth` outside `<AuthProvider>`.
+- `class ReactAuthGuardPropsInvalidError` — invalid `<AuthGuard>` props.
+- `class ReactAuthGuardOptionsInvalidError` — invalid `useAuthGuard` options.
+- `class ReactAuthClientNotInitialisedError` — client used before construction completes.
+- `class ReactAuthBetterAuthResponseInvalidError` — payload outside the union shape.
+- `class ReactAuthSignInFailedError` — wrapper for sign-in failure (carries `cause`).
+- `class ReactAuthSignUpFailedError` — wrapper for sign-up failure (carries `cause`).
+- `class ReactAuthSessionFetchFailedError` — wrapper for session-fetch failure.
+- `class ReactAuthPermissionDeniedError` — permission check denied (carries `permission` context).
+
+## Implementation Notes
+
+Every subclass takes an options object with `message` and optional `cause`/`context` fields. `cause` is normalised to `Error | undefined` (non-`Error` throwables are dropped so the cause chain never carries opaque values). The `ReactAuthPermissionDeniedError` constructor builds its message from the provided permission name when present, falling back to a generic string. The `context` object is propagated through `SuaveplanError` and surfaces both in the wire-format payload and on the OTel span event so error attribution flows through to dashboards.