# `error-codes`

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

## Purpose

`VIDEO_THUMBNAILS_CODES` is the stable, frozen registry of every failure mode raised by
`@suaveplan/video-thumbnails`. It is built with `defineCodes` from `@suaveplan/error` so the
namespace prefix (`VIDEO_THUMBNAILS.`) is encoded in the literal type — meaning consumers can
`switch` on a `VideoThumbnailsCode` and TypeScript will enforce exhaustiveness. The registry is
the single source of truth: every `throw new VideoThumbnailsError(...)` references a code from
this object, and the conformance test walks the registry to prove no code is dead.

## Features

- Frozen, namespaced registry built via `defineCodes("VIDEO_THUMBNAILS", [...])`.
- Literal union `VideoThumbnailsCode` derived from the registry values.
- Every code reachable from a real call site in `src/`, validated by `error-codes.test.ts`.
- Compatible with the project-wide `SuaveplanError` wire format, OTel span events, and
  redaction.

## Usage: Basic

```ts
import { VIDEO_THUMBNAILS_CODES } from "@suaveplan/video-thumbnails/error-codes";

console.log(VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED); // "VIDEO_THUMBNAILS.EXTRACT_FAILED"
```

## Usage: Advanced

```ts
import {
    VIDEO_THUMBNAILS_CODES,
    type VideoThumbnailsCode,
} from "@suaveplan/video-thumbnails/error-codes";

function describe(code: VideoThumbnailsCode): string {
    switch (code) {
        case VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED:
            return "ffmpeg failed mid-extract";
        case VIDEO_THUMBNAILS_CODES.PROBE_FAILED:
            return "ffprobe failed";
        case VIDEO_THUMBNAILS_CODES.VIDEO_INVALID:
            return "input is not a valid video";
        case VIDEO_THUMBNAILS_CODES.INVALID_TIMESTAMP:
            return "timestamp is not HH:MM:SS(.mmm)?";
        case VIDEO_THUMBNAILS_CODES.INVALID_DIMENSIONS:
            return "width/height/count <= 0";
        case VIDEO_THUMBNAILS_CODES.INVALID_OPTIONS:
            return "Zod boundary validation failed";
        case VIDEO_THUMBNAILS_CODES.FORMAT_UNSUPPORTED:
            return "output format not in jpg|png|webp";
        case VIDEO_THUMBNAILS_CODES.RUNNER_UNAVAILABLE:
            return "ffmpeg binary not available";
        case VIDEO_THUMBNAILS_CODES.ABORTED:
            return "AbortSignal triggered";
    }
}
```

## API Reference

- `VIDEO_THUMBNAILS_CODES` — `Readonly<Record<Reason, "VIDEO_THUMBNAILS.<Reason>">>` for the
  nine codes `EXTRACT_FAILED`, `PROBE_FAILED`, `VIDEO_INVALID`, `INVALID_TIMESTAMP`,
  `INVALID_DIMENSIONS`, `INVALID_OPTIONS`, `FORMAT_UNSUPPORTED`, `RUNNER_UNAVAILABLE`,
  `ABORTED`. Frozen at construction.
- `VideoThumbnailsCode` — literal union of every value in the registry; use as the parameter
  type for handlers that need to switch on failure mode.

## Implementation Notes

The registry is intentionally minimal — codes are added only when there is a corresponding
`throw` site in `src/`. Removing a code requires a deprecation window: keep the entry in the
registry, raise the new code from the call site, then drop the entry in a follow-up change so
external callers have one release to migrate `case` clauses. Codes never carry payload — that
lives on `SuaveplanError.context`. The frozen object means accidental mutation throws at
runtime in strict mode, which preserves the registry-as-contract invariant.