# 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`.