# `error-codes.ts` — `EventBusError` and the 8-code registry

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

## Purpose

Declares the stable error-code registry consumed by every failure path
in `@suaveplan/api-plugin-event-bus`. The registry is built via
`defineCodes("EVENT_BUS", [...])` from `@suaveplan/error` so the
exported `EVENT_BUS_CODES` object is a frozen record whose values are
`` `EVENT_BUS.${string}` `` literal types — consumers branch on the
string value (e.g. `error.code === EVENT_BUS_CODES.INVALID_TOPIC`)
with full TypeScript narrowing.

The matching `EventBusError` class extends `SuaveplanError` and tags
the supplied code on `this.eventBusCode` for symmetric narrowing in
`instanceof` checks.

## Features

- 8 stable codes (`INVALID_INPUT`, `INVALID_TOPIC`, `SERVICE_NOT_AVAILABLE`,
  `ROUTE_PREFIX_COLLISION`, `SUBSCRIPTION_NOT_FOUND`,
  `BACKPRESSURE_DROPPED`, `TENANT_MISMATCH`, `PUBLISH_FAILED`).
- Strongly-typed registry via `defineCodes`.
- `EventBusError` extends `SuaveplanError<EventBusErrorCode>` so the
  `code` discriminator narrows to the registry literal.
- Compatible with the shared error-handler middleware in
  `@suaveplan/api` (the HTTP status code is carried on `context.statusCode`).

## Usage: Basic

```ts
import {
    EVENT_BUS_CODES,
    EventBusError,
} from "@suaveplan/api-plugin-event-bus/error-codes/error-codes";

throw new EventBusError(EVENT_BUS_CODES.INVALID_TOPIC, "topic invalid", {
    context: { topic: "Order Created", statusCode: 400 },
});
```

## Usage: Advanced

```ts
import {
    EVENT_BUS_CODES,
    EventBusError,
} from "@suaveplan/api-plugin-event-bus/error-codes/error-codes";

function handle(err: unknown): number {
    if (!(err instanceof EventBusError)) return 500;
    switch (err.eventBusCode) {
        case EVENT_BUS_CODES.INVALID_TOPIC:
        case EVENT_BUS_CODES.INVALID_INPUT:
            return 400;
        case EVENT_BUS_CODES.SUBSCRIPTION_NOT_FOUND:
        case EVENT_BUS_CODES.TENANT_MISMATCH:
            return 404;
        case EVENT_BUS_CODES.BACKPRESSURE_DROPPED:
            return 503;
        case EVENT_BUS_CODES.ROUTE_PREFIX_COLLISION:
        case EVENT_BUS_CODES.SERVICE_NOT_AVAILABLE:
        case EVENT_BUS_CODES.PUBLISH_FAILED:
            return 500;
        default:
            return 500;
    }
}
```

## API Reference

### `EVENT_BUS_CODES`

`Readonly<Record<EventBusErrorCode, ``EVENT_BUS.${EventBusErrorCode}``>>`
— frozen registry, keys listed above.

### `type EventBusErrorCode`

Union of every value in `EVENT_BUS_CODES`. Used as the discriminator
type parameter on `EventBusError`.

### `class EventBusError extends SuaveplanError<EventBusErrorCode>`

- `constructor(code: EventBusErrorCode, message: string, options?: SuaveplanErrorOptions)`.
- `eventBusCode: EventBusErrorCode` — duplicate of `this.code` retained
  for symmetric narrowing in `instanceof` checks (`SuaveplanError`'s
  `code` is typed as the generic parameter).

## Implementation Notes

- Codes are deliberately additive — removing one is a breaking change
  for consumers asserting on `error.code === "EVENT_BUS.<X>"`. New codes
  may be added at the end of the `defineCodes` array.
- The package-level `EventBusError` constructor is `public` so callers
  may construct errors directly (`SuaveplanError`'s base constructor is
  `protected`). This matches the pattern used by
  `@suaveplan/api-plugin-auth`'s `AuthError`.
- `context.statusCode` is the canonical carrier for the HTTP status the
  error-handler should emit; the table in the Advanced example mirrors
  the mapping used by `@suaveplan/api`'s default error handler.