first commit

docs/api-stack/api/api-auth-bearer-static/src/error-codes/error-codes.md

@@ -0,0 +1,94 @@
+# 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.