first commit

docs/media/video/video-thumbnails/src/errors/video-thumbnails-error.md

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