Initial Commit

packages/api-stack/api/api-openapi-ui-swagger/src/error-codes/error-codes.md

@@ -0,0 +1,63 @@
+# `error-codes.ts` — `OPENAPI_UI_SWAGGER.*` registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module owns the stable error-code registry for `@suaveplan/api-openapi-ui-swagger`. Every public failure path raises an `OpenapiUiSwaggerError` carrying one of the two namespaced codes, so consumers can discriminate without parsing message strings. The codes survive across releases and form part of the public contract; renaming one is a breaking change.
+
+The registry is built via `defineCodes("OPENAPI_UI_SWAGGER", [...])` from `@suaveplan/error`. The resulting object freezes the code map at module load, so attempts to mutate it from outside throw immediately. The companion `OpenapiUiSwaggerError` widens the `SuaveplanError` constructor to `public` (no factory required) and re-exposes the parsed code on a `swaggerUiCode` accessor for narrowing in `instanceof` branches.
+
+## Features
+
+- Two-entry registry: `ASSETS_MISSING`, `INVALID_OPTIONS`.
+- `OpenapiUiSwaggerCode` union literal type derived from the registry.
+- `OpenapiUiSwaggerError` extending `SuaveplanError<OpenapiUiSwaggerCode>`.
+- Side-effect import from `src/index.ts` so consumers picking up the package barrel get the registry initialised.
+
+## Usage: Basic
+
+```ts
+import {
+    OPENAPI_UI_SWAGGER_CODES,
+    OpenapiUiSwaggerError,
+} from "@suaveplan/api-openapi-ui-swagger/error-codes";
+
+throw new OpenapiUiSwaggerError(
+    OPENAPI_UI_SWAGGER_CODES.INVALID_OPTIONS,
+    "theme must be one of 'light' | 'dark' | 'system'"
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { OpenapiUiSwaggerError } from "@suaveplan/api-openapi-ui-swagger/error-codes";
+
+try {
+    bootSwaggerUi(configFromOperator);
+} catch (err) {
+    if (
+        err instanceof OpenapiUiSwaggerError &&
+        err.swaggerUiCode === "ASSETS_MISSING"
+    ) {
+        // Fall back to a remote-CDN profile and report the gap.
+        return bootSwaggerUi({ ...configFromOperator, uiAssets: "cdn" });
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+- `OPENAPI_UI_SWAGGER_CODES: Readonly<Record<"ASSETS_MISSING"|"INVALID_OPTIONS", string>>`.
+- `type OpenapiUiSwaggerCode = "OPENAPI_UI_SWAGGER.ASSETS_MISSING" | "OPENAPI_UI_SWAGGER.INVALID_OPTIONS"`.
+- `class OpenapiUiSwaggerError extends SuaveplanError<OpenapiUiSwaggerCode>` — public constructor `(code, message, options?)`.
+
+## Implementation Notes
+
+Adding a new code is a public-API change: bump the package version and add a `**Verified by:**` entry in the spec for the throw site that emits it. Removing a code is a breaking change.
+
+The registry is intentionally tiny — Swagger UI is a presentation surface and most failures are configuration mistakes (caught by `INVALID_OPTIONS`) or asset-pipeline gaps (caught by `ASSETS_MISSING`). The conformance gate (`conformance.ts`) walks the registry and asserts each code is thrown from at least one non-test source file in this package.