Initial Commit

packages/ui/react/react-auth-whitelabel/src/errors/error-codes.md

@@ -0,0 +1,65 @@
+# Error codes — `REACT_AUTH_WL`
+
+## Purpose
+
+`error-codes.ts` registers the canonical, stable error-code registry used by
+every error thrown from `@suaveplan/react-auth-whitelabel`. The codes are
+namespaced under `REACT_AUTH_WL` and registered at module load via
+`defineCodes`, which means the `@suaveplan/error` registry is wired before any
+consumer imports a hook, context, or component. The codes survive minification,
+remain stable across releases, and let consumers branch on `.code` instead of
+inspecting the constructor name or message text — both of which are unstable
+across bundles.
+
+## Features
+
+- Single source of truth for error-code identity in this package.
+- `as const` literal-string codes for type-narrowing.
+- Module-load-time registration so the wire-format adapter, redaction layer,
+  OTel span-event bridge, and i18n resolver all see the codes without an
+  explicit init call.
+- Each code is thrown by ≥1 production code path — the
+  `error-codes.test.ts` grep-test enforces the contract.
+
+## Usage: Basic
+
+```ts
+import { REACT_AUTH_WL_CODES } from "@suaveplan/react-auth-whitelabel/errors";
+
+if (err.code === REACT_AUTH_WL_CODES.BRANDING_FETCH_FAILED) {
+    showFallbackBrand();
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    REACT_AUTH_WL_CODES,
+    type ReactAuthWhitelabelCode,
+} from "@suaveplan/react-auth-whitelabel/errors";
+
+function isRecoverable(code: ReactAuthWhitelabelCode): boolean {
+    switch (code) {
+        case REACT_AUTH_WL_CODES.BRANDING_FETCH_FAILED:
+        case REACT_AUTH_WL_CODES.AUTH_NETWORK_FAILED:
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
+## API Reference
+
+- `REACT_AUTH_WL_CODES` — frozen record of literal string codes; each value is
+  prefixed with `"REACT_AUTH_WL."`.
+- `ReactAuthWhitelabelCode` — union of every `REACT_AUTH_WL_CODES[K]` value.
+
+## Implementation Notes
+
+`defineCodes("REACT_AUTH_WL", [...])` enforces uniqueness inside the namespace
+and stamps the registry with the call site for diagnostics. We intentionally
+do NOT eagerly import the registry from package code other than the error
+class — the registry side-effect runs once at module evaluation and that is
+the only required wiring.