first commit

docs/communication/emails/delivery-tracking/src/errors/delivery-tracking-error.md

@@ -0,0 +1,67 @@
+# delivery-tracking-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`DeliveryTrackingError` is the stable typed error class raised by every code path inside `@suaveplan/delivery-tracking`. It extends `@suaveplan/error`'s `SuaveplanError` with a discriminant `code` drawn from the `DELIVERY_TRACKING_CODES` registry, giving consumers `instanceof` + code branching without inspecting the i18n-keyed `message` string.
+
+The codes are stable across versions: each entry exists because at least one production code path can produce it (lifecycle dedupe, store I/O, token parsing, webhook routing). Consumers can build exhaustive switches over the union derived from the registry and rely on TypeScript's exhaustiveness check to flag any future addition.
+
+## Features
+
+- Code registry generated via `defineCodes("DELIVERY_TRACKING", […])`.
+- Five stable codes: `INVALID_INPUT`, `INVALID_TOKEN`, `UNSUPPORTED_PROVIDER`, `STORE_FAILURE`, `QUERY_FAILURE`.
+- Subclass of `SuaveplanError` preserving cause chains, context bags, and i18n message keys.
+- Type-safe `DeliveryTrackingCode` union derived from the registry — no manual sync.
+
+## Usage: Basic
+
+```ts
+import {
+    DELIVERY_TRACKING_CODES,
+    DeliveryTrackingError,
+} from "@suaveplan/delivery-tracking/errors";
+
+throw new DeliveryTrackingError(
+    DELIVERY_TRACKING_CODES.INVALID_INPUT,
+    "error.delivery_tracking.invalid_input",
+    { context: { field: "tenantId" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    DELIVERY_TRACKING_CODES,
+    DeliveryTrackingError,
+    type DeliveryTrackingCode,
+} from "@suaveplan/delivery-tracking/errors";
+
+function classify(err: unknown): "client" | "server" | "other" {
+    if (!(err instanceof DeliveryTrackingError)) return "other";
+    const code: DeliveryTrackingCode = err.code;
+    switch (code) {
+        case DELIVERY_TRACKING_CODES.INVALID_INPUT:
+        case DELIVERY_TRACKING_CODES.INVALID_TOKEN:
+        case DELIVERY_TRACKING_CODES.UNSUPPORTED_PROVIDER:
+            return "client";
+        case DELIVERY_TRACKING_CODES.STORE_FAILURE:
+        case DELIVERY_TRACKING_CODES.QUERY_FAILURE:
+            return "server";
+    }
+}
+```
+
+## API Reference
+
+- `DELIVERY_TRACKING_CODES` — frozen record of stable codes, each value prefixed `DELIVERY_TRACKING.*`.
+- `type DeliveryTrackingCode` — union of the registry's values.
+- `class DeliveryTrackingError extends SuaveplanError<DeliveryTrackingCode>` — accepts `(code, messageKey, options?)` and exposes `code`, `messageKey`, `cause`, and `context` on the resulting instance.
+
+## Implementation Notes
+
+The registry is `defineCodes("DELIVERY_TRACKING", [...] as const)`; the `as const` is what keeps the resulting object literal-typed so the union can be derived. The class only widens the protected constructor to public and sets `this.name = "DeliveryTrackingError"` — every other behaviour (cause chains, redaction, OTel span enrichment) is inherited from `SuaveplanError`.