# `error-codes`

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

## Purpose

Provides the stable error-code registry and the typed `WsBunError` subclass for `@suaveplan/api-ws-bun`. Every production failure path in the package routes through one of the ten `WS_BUN.*` codes defined here, which means a downstream consumer can branch on `error.code === WS_BUN_CODES.TENANT_CAP_EXCEEDED` without importing implementation modules.

The constants are frozen at module load time by `defineCodes` from `@suaveplan/error`, so consumers can compare against the namespaced literal string (`"WS_BUN.HANDSHAKE_REJECTED"`) directly when that is convenient — for example inside a JSON-serialised error wire format or a Hono error handler.

## Features

- Ten-entry registry covering handshake, tenant caps, backpressure, heartbeat, reconnect token validation, reconnect-buffer wiring, subprotocols, close timeouts and principal expiry.
- `WsBunError` extends `SuaveplanError<WsBunErrorCode>` so `instanceof` narrows the `code` field to the registry's literal union.
- One `raise*` helper per code so every entry has a production throw-site (CI checklist 6.3).
- Helpers attach a stable message prefix per code so logs stay grep-able.

## Usage: Basic

```ts
import { raiseTenantCapExceeded, WS_BUN_CODES } from "@suaveplan/api-ws-bun";

try {
    raiseTenantCapExceeded("tenant-a", 1000);
} catch (err) {
    if ((err as { code?: string }).code === WS_BUN_CODES.TENANT_CAP_EXCEEDED) {
        // surface 429 to the caller
    }
}
```

## Usage: Advanced

```ts
import {
    WS_BUN_CODES,
    WsBunError,
    type WsBunErrorCode,
} from "@suaveplan/api-ws-bun";

function logIfWsBun(error: unknown, logger: { error: (m: string) => void }) {
    if (error instanceof WsBunError) {
        const code: WsBunErrorCode = error.wsBunCode;
        logger.error(`${code}: ${error.message}`);
        return code === WS_BUN_CODES.HEARTBEAT_FAILED;
    }
    return false;
}
```

## API Reference

- `WS_BUN_CODES` — frozen `Record<LiteralName, "WS_BUN.<LiteralName>">` produced by `defineCodes`. Keys: `HANDSHAKE_REJECTED`, `TENANT_CAP_EXCEEDED`, `BACKPRESSURE_EVICTED`, `HEARTBEAT_FAILED`, `RECONNECT_TOKEN_INVALID`, `RECONNECT_TOKEN_EXPIRED`, `RECONNECT_BUFFER_MISS`, `SUBPROTOCOL_UNSUPPORTED`, `CLOSE_TIMEOUT`, `PRINCIPAL_EXPIRED`.
- `WsBunError` — concrete subclass of `SuaveplanError<WsBunErrorCode>` with a `wsBunCode` mirror property.
- `raise*` helpers — one per code, all return `never`, all throw `WsBunError` with a pre-formatted message.

## Implementation Notes

The `raise*` helpers exist not only as ergonomic shortcuts but as a forcing-function: CI rule §6.3 demands every code in the registry have at least one production raise-site. Concentrating the raise calls in this module guarantees that property regardless of how the engine internals evolve.

Codes are intentionally namespaced (`WS_BUN.*` rather than `WS.*`) so error reports never confuse this engine adapter with the abstract `@suaveplan/api-ws` contract package, which owns the parallel `WS.*` namespace.