first commit

docs/communication/emails/email-templates/src/error-codes/error-codes.md

@@ -0,0 +1,87 @@
+# 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`.