# 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.