# `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.