# Error codes — `@suaveplan/api-auth-bearer-static`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

The error-codes module defines the stable `AUTH_BEARER_STATIC.*` namespace
that every public failure path in this package surfaces. Codes are produced
by `defineCodes` from `@suaveplan/error` so the registry yields a frozen
record of fully-qualified strings (`AUTH_BEARER_STATIC.NO_TOKEN`,
`AUTH_BEARER_STATIC.UNKNOWN_TOKEN`, `AUTH_BEARER_STATIC.MTLS_REQUIRED`,
`AUTH_BEARER_STATIC.INVALID_OPTIONS`) along with a `BearerStaticAuthError`
subclass that lifts each code into a real `Error` instance.

This module is the contract a caller branches on. Catching a generic
`SuaveplanError` and reading `.code` is the supported failure-handling
pattern; the concrete subclass exists to make `instanceof` narrow the code
union for downstream code that needs the stronger typing.

## Features

- Frozen four-entry code registry keyed by reason name.
- `BearerStaticAuthError` extends `SuaveplanError<BearerStaticAuthErrorCode>`
  — `instanceof` narrows `.code`.
- Stable namespace string (`AUTH_BEARER_STATIC`) safe to log and persist.
- Every code exercised by at least one production code path (registry-vs-
  source conformance is asserted by the spec-conformance test).

## Usage: Basic

```ts
import {
    AUTH_BEARER_STATIC_CODES,
    BearerStaticAuthError,
} from "@suaveplan/api-auth-bearer-static/error-codes";

try {
    // factory call that may throw on bad options
    throw new BearerStaticAuthError(
        AUTH_BEARER_STATIC_CODES.INVALID_OPTIONS,
        "tokens table is empty"
    );
} catch (e) {
    if (e instanceof BearerStaticAuthError) {
        // e.code narrows to BearerStaticAuthErrorCode
        console.error(e.code, e.message);
    }
}
```

## Usage: Advanced

```ts
import {
    AUTH_BEARER_STATIC_CODES,
    BearerStaticAuthError,
} from "@suaveplan/api-auth-bearer-static/error-codes";

function isInvalidOptions(err: unknown): err is BearerStaticAuthError {
    return (
        err instanceof BearerStaticAuthError &&
        err.code === AUTH_BEARER_STATIC_CODES.INVALID_OPTIONS
    );
}

// Treat invalid options as a fatal config error; bubble everything else.
try {
    // build resolver
} catch (e) {
    if (isInvalidOptions(e)) {
        process.exit(78); // EX_CONFIG
    }
    throw e;
}
```

## API Reference

- `AUTH_BEARER_STATIC_CODES` — `Readonly<Record<Reason,
  "AUTH_BEARER_STATIC.<Reason>">>`. Frozen at module load.
- `BearerStaticAuthErrorCode` — string-literal union of every value.
- `class BearerStaticAuthError extends SuaveplanError<BearerStaticAuthErrorCode>`
  — constructor `(code, messageKey, options?)` matches the
  `SuaveplanError` shape.

## Implementation Notes

The registry is constructed with `defineCodes("AUTH_BEARER_STATIC", [...])`.
`defineCodes` returns a `Readonly` record whose key set is the reason names
and whose values are the fully-qualified `"AUTH_BEARER_STATIC.<reason>"`
strings — referenced via `AUTH_BEARER_STATIC_CODES.NO_TOKEN` rather than the
raw string literal so a typo at the call site fails type-check.