# error-codes

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

## Purpose

Stable error-code registry for `@suaveplan/email-templates`. Every failure
raised by the package extends `SuaveplanError` with a discriminant `code`
drawn from `EMAIL_TEMPLATES_CODES`, enabling programmatic dispatch by
consumers without coupling to error-message text.

The registry is the contract: every code listed here MUST be thrown by at
least one production code path under `src/`. Removing an entry without
removing its call site is forbidden by §2c of `AGENTS.md`.

## Features

- Six stable codes registered via `defineCodes("EMAIL_TEMPLATES", [...])`.
- `EmailTemplatesError` class with public constructor (so external callers
  can synthesise an instance for re-throw / wrapping).
- `EmailTemplatesCode` discriminant union derived from the registry — every
  `code` field is statically narrowable.
- Inherits OTel span-event adaptation, redaction, cause-chain traversal,
  and i18n message-key resolution from `SuaveplanError`.

## Usage: Basic

```ts
import {
  EMAIL_TEMPLATES_CODES,
  EmailTemplatesError,
} from "@suaveplan/email-templates/errors";

throw new EmailTemplatesError(
  EMAIL_TEMPLATES_CODES.UNKNOWN_TEMPLATE,
  "email_templates.unknown_template",
);
```

## Usage: Advanced

Wrap an unexpected throwable, preserving its cause for the OTel span-event
adapter to surface in tracing:

```ts
import {
  EMAIL_TEMPLATES_CODES,
  EmailTemplatesError,
} from "@suaveplan/email-templates/errors";

try {
  renderToHtml(template, props);
} catch (cause) {
  throw new EmailTemplatesError(
    EMAIL_TEMPLATES_CODES.RENDER_FAILURE,
    "email_templates.render_failure",
    { cause: cause instanceof Error ? cause : new Error(String(cause)) },
  );
}
```

## API Reference

| Symbol                       | Kind     | Description                                         |
| ---------------------------- | -------- | --------------------------------------------------- |
| `EMAIL_TEMPLATES_CODES`      | const    | Frozen record of `EMAIL_TEMPLATES.<NAME>` strings.  |
| `EmailTemplatesCode`         | type     | Discriminant union of every registered code.        |
| `EmailTemplatesError`        | class    | `SuaveplanError<EmailTemplatesCode>` subclass.      |

Codes (six): `INVALID_TEMPLATE`, `INVALID_OPTIONS`, `RENDER_FAILURE`,
`DUPLICATE_NAME`, `UNKNOWN_TEMPLATE`, `INVALID_HEADING_LEVEL`.

## Implementation Notes

The `defineCodes` helper from `@suaveplan/error` returns a frozen
`Record<K, "EMAIL_TEMPLATES.K">` and side-steps the literal-string-typing
pitfall by inferring each key as a string-literal type. `EmailTemplatesCode`
is derived via `(typeof EMAIL_TEMPLATES_CODES)[keyof typeof ...]` so adding
or removing a code automatically widens or narrows the union — the
TypeScript compiler will refuse to throw an unknown code.

`name = "EmailTemplatesError"` is set in the constructor (not via static
class-name reflection) so that downcasting via the standard
`err.name === "EmailTemplatesError"` discriminant works under minified
production bundles. `timestamp` is supplied by `SuaveplanError`.