# `ReactAuthWhitelabelError`

## Purpose

`ReactAuthWhitelabelError` is the canonical error class for every error thrown
by `@suaveplan/react-auth-whitelabel`. It extends `SuaveplanError` so the
error participates in the project-wide error substrate (cause-chain traversal,
redaction-aware wire format, OTel span-event adapter, i18n message resolver).
Every instance is stamped with `context.tier === "react-auth-whitelabel"` so
log sinks and dashboards can group white-label auth failures without
inspecting `error.constructor.name`, which is unstable across minified
bundles. Construction always carries a `messageKey` so the i18n resolver can
localise the user-visible error string at the boundary.

## Features

- Type-narrowed `.code` of `ReactAuthWhitelabelCode`.
- Auto-injected `context.tier` for log/dashboard grouping.
- Carries a translation key, not a baked English string.
- Compatible with `SuaveplanError`'s cause-chain walker, wire serialiser,
  and OTel span-event adapter.

## Usage: Basic

```ts
import { ReactAuthWhitelabelError } from "@suaveplan/react-auth-whitelabel/errors";
import { REACT_AUTH_WL_CODES } from "@suaveplan/react-auth-whitelabel/errors";

throw new ReactAuthWhitelabelError(
    REACT_AUTH_WL_CODES.PROVIDER_OUTSIDE_TREE,
    "react_auth_wl.error.provider_outside_tree",
    { context: { hook: "useAuth" } }
);
```

## Usage: Advanced

```ts
try {
    await login(email, password);
} catch (cause) {
    throw new ReactAuthWhitelabelError(
        REACT_AUTH_WL_CODES.AUTH_NETWORK_FAILED,
        "react_auth_wl.error.network",
        { cause, context: { authUrl: config.authUrl } }
    );
}
```

The thrown error retains the original `cause` chain so monitoring sinks can
correlate transport errors with the user-facing failure.

## API Reference

- `new ReactAuthWhitelabelError(code, messageKey, options?)` — constructs an
  error. `options.context.tier` is always set to `"react-auth-whitelabel"`,
  even if the caller passes a different value (the helper merges, then
  overrides `tier`).
- `.code` — `ReactAuthWhitelabelCode` literal.
- `.message` — short English description sourced from `messageKey` (the i18n
  resolver substitutes a localised translation when available).

## Implementation Notes

The constructor merges caller-supplied `context` with the canonical `tier`
stamp. Callers must NOT pass a different `tier` — it will silently win at
merge time, but the contract is that this package's errors are always
tagged `"react-auth-whitelabel"`.