first commit

docs/identity/auth/jwt-tenant/src/errors/jwt-tenant-error.md

@@ -0,0 +1,65 @@
+# jwt-tenant-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Defines the structured error hierarchy for `@suaveplan/jwt-tenant`. All thrown errors extend `SuaveplanError` with a stable code registry under the `JWT.*` namespace. Using `defineCodes` ensures code strings are deduplicated at module load time and are inspectable programmatically without string matching.
+
+## Features
+
+- `JWT_TENANT_CODES` registry with 9 distinct error codes
+- `JwtTenantError` class extending `SuaveplanError<JwtTenantErrorCode>`
+- Cause-chain forwarding: non-Error causes are swallowed, Error causes preserved
+- Machine-inspectable error codes for upstream routing and logging
+
+## Usage: Basic Example
+
+```ts
+import { JwtTenantError, JWT_TENANT_CODES } from "@suaveplan/jwt-tenant";
+
+throw new JwtTenantError(
+  JWT_TENANT_CODES.EXPIRED,
+  "Token has expired"
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { JwtTenantError, JWT_TENANT_CODES } from "@suaveplan/jwt-tenant";
+
+try {
+  await verifyToken(token, key);
+} catch (raw) {
+  if (raw instanceof Error) {
+    throw new JwtTenantError(
+      JWT_TENANT_CODES.INVALID_SIGNATURE,
+      "Signature verification failed",
+      { cause: raw }
+    );
+  }
+}
+```
+
+## API Reference
+
+### `JWT_TENANT_CODES`
+
+Object mapping each error name to its fully qualified code string (e.g., `JWT.EXPIRED`). Produced by `defineCodes("JWT", [...])`.
+
+### `JwtTenantError`
+
+- **constructor(code, message, options?)** — Creates a structured error.
+  - `code` — `JwtTenantErrorCode`
+  - `message` — human-readable description
+  - `options.cause` — optional underlying `Error` for cause-chain
+
+### `JwtTenantErrorCode`
+
+Union type of all code keys: `"JWT_INVALID_SIGNATURE" | "JWT_EXPIRED" | ... | "JWT_SERIALIZATION_FAILED"`.
+
+## Implementation Notes
+
+`JwtTenantError` wraps the `SuaveplanError` constructor pattern established across Suaveplan. Non-Error causes are dropped rather than coerced because `SuaveplanError` only accepts `Error` in its cause chain — this prevents accidental serialisation of arbitrary objects.