# `VideoThumbnailsError`

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

## Purpose

`VideoThumbnailsError` is the single error class raised by every public surface of
`@suaveplan/video-thumbnails`. It extends `SuaveplanError<VideoThumbnailsCode>` so it inherits
the project-wide wire format (`toJSON` / `fromJSON`), the OTel span-event adapter, the
redaction pipeline, the cause-chain walker, and the i18n resolver hook. Every constructor call
must reference a code from `VIDEO_THUMBNAILS_CODES`, which keeps the registry and the call
sites in lock-step.

## Features

- Single class for the entire failure surface — no parallel hierarchies to keep in sync.
- Code is parameterised, so TypeScript narrows on `error.code` at catch sites.
- Carries `context` (Zod issues, ffmpeg stderr, abort reason) without bloating the message.
- Compatible with `walkCauses`, `toSpanEvent`, and the JSON / binary serializers exported by
  `@suaveplan/error`.

## Usage: Basic

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

throw new VideoThumbnailsError(
    VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED,
    "videoThumbnails.errors.extractFailed",
);
```

## Usage: Advanced

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

try {
    await generator.generate("/missing.mp4");
} catch (error) {
    if (error instanceof VideoThumbnailsError) {
        if (error.code === VIDEO_THUMBNAILS_CODES.PROBE_FAILED) {
            await reportMetric("probe-failed", error.context);
            return;
        }
        if (error.code === VIDEO_THUMBNAILS_CODES.ABORTED) {
            return;
        }
    }
    throw error;
}
```

## API Reference

- `class VideoThumbnailsError extends SuaveplanError<VideoThumbnailsCode>`
  - `constructor(code, messageKey, options?)`
    - `code` — one of `VIDEO_THUMBNAILS_CODES.*`
    - `messageKey` — i18n key (caller resolves the human-readable string)
    - `options` — `SuaveplanErrorOptions` (`{ cause?, context?, severity?, retryable?, httpStatus? }`)
  - Inherited members: `code`, `messageKey`, `context`, `cause`, `severity`, `retryable`,
    `httpStatus`, `toJSON()`, `toSpanEvent()`.

## Implementation Notes

The class sets `this.name = "VideoThumbnailsError"` so structured logs identify the class
even when prototypes are stripped (some test runners walk `name` rather than the prototype
chain). It does not override `toJSON` — the base `SuaveplanError` serializer already covers
the wire format. When a Zod validation fails the schema layer attaches the `ZodError.issues`
array under `context.issues`, which the redactor passes through unmodified because Zod issues
do not contain sensitive material in this package's option space.