`error-codes` — `AUTH_PROVIDER` error-code registry

(no submodules)

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

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.

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.

3.5 KiB Raw Blame History

error-codes — AUTH_PROVIDER error-code registry