Initial Commit

packages/api-stack/api/api-auth-provider/src/error-codes/error-codes.md

@@ -0,0 +1,91 @@
+# `error-codes` — `AUTH_PROVIDER` error-code registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module centralises the four stable error codes the auth-provider
+contract emits — `PATH_COLLISION`, `MULTIPLE_PROVIDERS_REGISTERED`,
+`PROVIDER_LIFECYCLE_FAILED`, `OAUTH_CALLBACK_INVALID_STATE` — and pairs each
+with HTTP / severity / retry metadata so downstream consumers (problem-detail
+mappers, log routers, retry wrappers) classify failures without
+string-matching messages. The registry is built with `defineCodes` from
+`@suaveplan/error`, which preserves the literal-typed union through the
+public surface so exhaustive `switch (err.code)` blocks report unhandled
+reasons at type-check time.
+
+## Features
+
+- `AUTH_PROVIDER_CODES` — frozen `{ REASON: "AUTH_PROVIDER.REASON" }` record.
+- `AuthProviderErrorCode` union of fully-qualified codes.
+- `AuthProviderErrorKey` union of short keys (`"PATH_COLLISION"`).
+- `AUTH_PROVIDER_ERROR_METADATA` — per-code HTTP status / severity / retryable
+    flag / human description.
+- `AuthProviderError` — concrete `SuaveplanError` subclass with a public
+    constructor.
+- `authProviderError(key, opts)` — factory that defaults `messageKey` to
+    `auth_provider.errors.<lower_case_key>`.
+- `getAuthProviderCodeMetadata(code)` — lookup helper used by adapters.
+
+## Usage: Basic
+
+```ts
+import { authProviderError } from "@suaveplan/api-auth-provider/error-codes";
+
+throw authProviderError("OAUTH_CALLBACK_INVALID_STATE", {
+    context: { state: requestState },
+});
+```
+
+## Usage: Advanced
+
+A problem-detail mapper turns any thrown `AuthProviderError` into an HTTP
+response with the correct status, retry hint, and severity-driven log level.
+
+```ts
+import {
+    AUTH_PROVIDER_ERROR_METADATA,
+    AuthProviderError,
+} from "@suaveplan/api-auth-provider/error-codes";
+
+function mapToProblem(err: AuthProviderError): Response {
+    const meta = AUTH_PROVIDER_ERROR_METADATA[err.code];
+    return new Response(
+        JSON.stringify({
+            type: `https://errors.suaveplan/${err.code}`,
+            title: err.message,
+            status: meta.httpStatus,
+            retryable: meta.retryable,
+        }),
+        { status: meta.httpStatus }
+    );
+}
+```
+
+## API Reference
+
+- `const AUTH_PROVIDER_CODES`
+- `type AuthProviderErrorCode`
+- `type AuthProviderErrorKey`
+- `interface AuthProviderCodeMetadata`
+- `const AUTH_PROVIDER_ERROR_METADATA: Readonly<Record<AuthProviderErrorCode, AuthProviderCodeMetadata>>`
+- `class AuthProviderError extends SuaveplanError<AuthProviderErrorCode>` —
+    public constructor `(code, messageKey, opts?)`.
+- `function authProviderError(key, opts?): AuthProviderError`
+- `function getAuthProviderCodeMetadata(code: string): AuthProviderCodeMetadata | undefined`
+
+## Implementation Notes
+
+`SuaveplanError`'s base constructor is `protected`; the subclass exposes a
+public constructor so callers outside this package — including the
+conformance harness — can build typed errors without going through the
+factory. The factory is preferred for everyday use because it derives the
+i18n message key from the short reason key, keeping the call site dense. The
+metadata record is frozen with `Object.freeze` (not just `as const`) so a
+runtime caller cannot mutate the table; `satisfies` keeps the table
+exhaustive at type-check time. `PATH_COLLISION` maps to HTTP 409 because the
+host refuses the install rather than overwriting an existing route; an
+adapter that needs a different status should override the mapper rather than
+re-shape the registry.