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