@pithy-sh/media 0.1.0

package/src/config/config.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The media capability's configuration — the thin, user-owned surface in `pithy.config.ts`. The adopter
+ * picks a storage backend per media type and toggles AI enrichment; the package owns everything else.
+ * Every AI model is a configurable parameter with the CMS default, so an adopter swaps a model without
+ * touching package code. Every field is `.describe()`d — the descriptions feed the self-documenting CLI.
+ */
+
+/** Default Workers AI model for image-to-text (alt text and captions). */
+export const DEFAULT_IMAGE_TO_TEXT_MODEL = "@cf/llava-hf/llava-1.5-7b-hf";
+/** Default Workers AI model for speech-to-text transcription (audio and video). */
+export const DEFAULT_TRANSCRIBE_MODEL = "@cf/openai/whisper-large-v3-turbo";
+
+/** Image storage + optional alt-text/caption enrichment. */
+export const MediaImageConfig = z
+  .object({
+    store: z
+      .enum(["r2", "cf-images"])
+      .default("cf-images")
+      .describe(
+        "Where image bytes live: `cf-images` (Cloudflare Images — variants and optimized delivery) or `r2` (raw ownership).",
+      ),
+    imageToText: z
+      .boolean()
+      .default(false)
+      .describe("Generate alt text and a caption for each image with Workers AI. A no-op with no cost when off."),
+    model: z
+      .string()
+      .default(DEFAULT_IMAGE_TO_TEXT_MODEL)
+      .describe(
+        "The Workers AI vision model used for alt text and captions. Override to swap models with no code edits.",
+      ),
+  })
+  .describe("Image storage backend and optional image-to-text enrichment.");
+export type MediaImageConfig = z.output<typeof MediaImageConfig>;
+
+/** Video storage + optional transcription enrichment. */
+export const MediaVideoConfig = z
+  .object({
+    store: z
+      .enum(["r2", "cf-stream"])
+      .default("cf-stream")
+      .describe(
+        "Where video lives: `cf-stream` (Cloudflare Stream — encoding, HLS delivery, adaptive bitrate) or `r2` (raw files).",
+      ),
+    transcribe: z
+      .boolean()
+      .default(false)
+      .describe("Transcribe each video's audio with Workers AI as a Workflow. A no-op with no cost when off."),
+    model: z
+      .string()
+      .default(DEFAULT_TRANSCRIBE_MODEL)
+      .describe(
+        "The Workers AI speech-to-text model used for transcription. Override to swap models with no code edits.",
+      ),
+  })
+  .describe("Video storage backend and optional speech-to-text enrichment.");
+export type MediaVideoConfig = z.output<typeof MediaVideoConfig>;
+
+/** Audio storage (R2) + optional transcription enrichment. */
+export const MediaAudioConfig = z
+  .object({
+    store: z.literal("r2").default("r2").describe("Audio is always stored in R2; the field is fixed for symmetry."),
+    transcribe: z
+      .boolean()
+      .default(false)
+      .describe("Transcribe each audio file with Workers AI as a Workflow. A no-op with no cost when off."),
+    model: z
+      .string()
+      .default(DEFAULT_TRANSCRIBE_MODEL)
+      .describe(
+        "The Workers AI speech-to-text model used for transcription. Override to swap models with no code edits.",
+      ),
+  })
+  .describe("Audio storage (R2) and optional speech-to-text enrichment.");
+export type MediaAudioConfig = z.output<typeof MediaAudioConfig>;
+
+/** Document storage (R2) + optional text extraction. */
+export const MediaDocumentConfig = z
+  .object({
+    store: z
+      .literal("r2")
+      .default("r2")
+      .describe("Documents are always stored in R2; the field is fixed for symmetry."),
+    extractText: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Extract text (markdown) from pdf/doc/docx with Workers AI as a Workflow. A no-op with no cost when off.",
+      ),
+  })
+  .describe("Document storage (R2) and optional text extraction.");
+export type MediaDocumentConfig = z.output<typeof MediaDocumentConfig>;
+
+/**
+ * Public delivery configuration — the non-secret account values needed to build consumer URLs for stored
+ * media (see `deliver/url.ts`). These are public identifiers (they appear in delivery URLs), so they live
+ * in config, not in `@pithy-sh/secrets`.
+ */
+export const MediaDelivery = z
+  .object({
+    imagesAccountHash: z
+      .string()
+      .optional()
+      .describe(
+        "The Cloudflare Images account hash, used to build `imagedelivery.net` URLs and to read image bytes for enrichment.",
+      ),
+    streamCustomerCode: z
+      .string()
+      .optional()
+      .describe(
+        "The Cloudflare Stream customer subdomain code, used to build `customer-<code>.cloudflarestream.com` playback URLs.",
+      ),
+    r2PublicBaseUrl: z
+      .string()
+      .optional()
+      .describe(
+        "A public base URL for R2 objects when the bucket is served publicly; otherwise consumers use a presigned download URL.",
+      ),
+  })
+  .describe("Public delivery configuration for building consumer media URLs.");
+export type MediaDelivery = z.output<typeof MediaDelivery>;
+
+/**
+ * The full media configuration. `recordStore` chooses where records live (D1 by default; a KV opt-in for
+ * KV-only projects, with its query limitations documented). Each media type block picks a backend and
+ * toggles its enrichment.
+ */
+export const MediaConfig = z
+  .object({
+    recordStore: z
+      .enum(["d1", "kv"])
+      .default("d1")
+      .describe(
+        "Where media records live: `d1` (default — transcriptions and extracted text are queryable) or `kv` (key-lookup only; no text search over derived content). Duplicate detection always uses D1 either way.",
+      ),
+    delivery: MediaDelivery.prefault({}).describe("Public delivery configuration for building consumer media URLs."),
+    kvMetadata: z
+      .array(z.string())
+      .default(["type", "status", "hasTranscription", "hasExtractedText"])
+      .describe(
+        "For `recordStore: 'kv'` only: which record fields to also store as KV metadata. Metadata rides free on a KV `list` (no per-value read), so `list` filters, sorts, and renders from it — put the fields your list views need here (e.g. an owning `userId` for owner-scoped lists). KV caps metadata at 1024 bytes serialized, so keep it to small scalar fields. `type` and `createdAt` are always included (list filters by type and sorts by recency). Ignored in D1 mode.",
+      ),
+    images: MediaImageConfig.prefault({}).describe("Image storage and enrichment settings."),
+    video: MediaVideoConfig.prefault({}).describe("Video storage and enrichment settings."),
+    audio: MediaAudioConfig.prefault({}).describe("Audio storage and enrichment settings."),
+    documents: MediaDocumentConfig.prefault({}).describe("Document storage and enrichment settings."),
+  })
+  .describe("Configuration for the media capability — record store plus per-type backend and enrichment.");
+export type MediaConfig = z.output<typeof MediaConfig>;
+export type MediaConfigInput = z.input<typeof MediaConfig>;

package/src/data/enums.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The closed enums the media capability's schemas and handlers share. Each is a described Zod enum
+ * (the object model's documentation) with its inferred type exported under the same name.
+ */
+
+/** The four kinds of media the capability stores and enriches. The discriminator across every record. */
+export const MediaType = z
+  .enum(["image", "video", "audio", "document"])
+  .describe("The kind of media: image, video, audio, or document. The discriminator on every record.");
+export type MediaType = z.output<typeof MediaType>;
+
+/**
+ * A media record's lifecycle. A record is created `pending` when its upload URL is minted, flips to
+ * `stored` once the client confirms the bytes landed (finalize), and is `failed` if finalize could not
+ * verify the object.
+ */
+export const MediaStatus = z
+  .enum(["pending", "stored", "failed"])
+  .describe("A media record's lifecycle: `pending` (URL minted), `stored` (upload finalized), or `failed`.");
+export type MediaStatus = z.output<typeof MediaStatus>;
+
+/**
+ * Where a media object's bytes live. Chosen per media type by config: images to `r2` or `cf-images`,
+ * video to `r2` or `cf-stream`, audio and documents always to `r2`.
+ */
+export const StorageBackend = z
+  .enum(["r2", "cf-images", "cf-stream"])
+  .describe("The Cloudflare product a media object's bytes live in: `r2`, `cf-images`, or `cf-stream`.");
+export type StorageBackend = z.output<typeof StorageBackend>;
+
+/**
+ * The document extensions Workers AI `toMarkdown` can extract text from. Extraction is only dispatched
+ * for these — a `.txt`, `.png`, or unknown extension is never enqueued (no wasted Workflow, no cost).
+ * Matches the CMS's supported set.
+ */
+export const EXTRACTABLE_EXTENSIONS = ["pdf", "doc", "docx"] as const;
+
+/** The file extension of a filename, lowercased, or the empty string. */
+export function fileExtension(filename: string): string {
+  if (typeof filename !== "string") return "";
+  const dot = filename.lastIndexOf(".");
+  return dot >= 0 ? filename.slice(dot + 1).toLowerCase() : "";
+}
+
+/** Whether a document's filename is one text extraction supports (pdf/doc/docx). */
+export function isExtractableDocument(filename: string): boolean {
+  return (EXTRACTABLE_EXTENSIONS as readonly string[]).includes(fileExtension(filename));
+}

package/src/data/extend.ts

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import { MediaAsset } from "./mediaAsset";
+
+/**
+ * The adopter-extension mechanism, and the single reason one Zod schema can persist to either record
+ * store. An adopter extends a media type by passing a `z.ZodObject` of extra fields to `media({ extend })`
+ * — an owning `userId`, a tenant id, tags. From that one schema the mapping layer derives everything:
+ *
+ *   - D1: {@link extensionColumns} turns each field into a real column (type + nullability), which the
+ *     generated `0002_extend` migration adds to `pithy_media_assets`; the effective schema then reads and
+ *     writes those columns through the same codecs as the base fields.
+ *   - KV: the effective schema validates the extra fields as part of the stored value — no columns, no
+ *     migration, no backend-specific work.
+ *
+ * The base fields are always guaranteed; an extension field that collides with a base column name is
+ * ignored, so an adopter can never redefine or drop a base field.
+ */
+
+/** A derived SQLite column: its affinity and whether the source field is required. */
+export interface SqliteColumn {
+  /** The SQLite storage affinity — `text` for strings/JSON, `integer` for numbers/booleans/dates. */
+  type: "text" | "integer";
+  /** Whether the column is `NOT NULL` — false when the field is optional, nullable, or nullish. */
+  notNull: boolean;
+}
+
+/** A derived column plus its (camelCase) name, for the extension migration. */
+export interface ExtensionColumn extends SqliteColumn {
+  /** The column name — the extension field's key. `CamelCasePlugin` snake-cases it in the DDL. */
+  name: string;
+}
+
+interface ZodInternal {
+  def?: { type?: string; innerType?: z.ZodType; out?: z.ZodType };
+}
+
+/** Read a schema's internal def, tolerating both the `_zod.def` and `.def` shapes across Zod builds. */
+function defOf(schema: z.ZodType): ZodInternal["def"] {
+  const internal = schema as unknown as { _zod?: ZodInternal } & ZodInternal;
+  return internal._zod?.def ?? internal.def;
+}
+
+/** Unwrap `optional` / `nullable` / `default` wrappers to the underlying schema, tracking nullability. */
+function unwrap(schema: z.ZodType): { inner: z.ZodType; notNull: boolean } {
+  let current = schema;
+  let notNull = true;
+  // A wrapper nests its target under `def.innerType`; walk until we reach a concrete type.
+  for (let guard = 0; guard < 16; guard++) {
+    const def = defOf(current);
+    const kind = def?.type;
+    if ((kind === "optional" || kind === "nullable" || kind === "default") && def?.innerType) {
+      if (kind !== "default") notNull = false;
+      current = def.innerType;
+    } else {
+      break;
+    }
+  }
+  return { inner: current, notNull };
+}
+
+/** Map a concrete (unwrapped) schema — primitive or codec — to a SQLite affinity. */
+function affinityOf(schema: z.ZodType): "text" | "integer" {
+  const def = defOf(schema);
+  // A codec is a `pipe`; its stored form follows the OUTPUT type (a date/boolean stores as a number,
+  // a JSON payload stores as a string).
+  const target = def?.type === "pipe" && def.out ? defOf(def.out)?.type : def?.type;
+  switch (target) {
+    case "number":
+    case "boolean":
+    case "date":
+    case "bigint":
+      return "integer";
+    default:
+      return "text";
+  }
+}
+
+/** Derive the SQLite column (affinity + nullability) a single extension field maps to. */
+export function sqliteColumnType(schema: z.ZodType): SqliteColumn {
+  const { inner, notNull } = unwrap(schema);
+  return { type: affinityOf(inner), notNull };
+}
+
+/**
+ * The base column names. An extension may not redefine them, and the create handler treats any body key
+ * that IS a base column as server-owned — never an extension field — so a client cannot smuggle a base
+ * field (id, status, storageKey, …) in through the extension bag.
+ */
+export const BASE_COLUMN_NAMES: ReadonlySet<string> = new Set(Object.keys(MediaAsset.shape));
+
+/**
+ * A nullable D1 column returns SQLite NULL when a record omitted the field, so its schema must accept
+ * null on read. A plain `.optional()` field (undefined-only) would throw on that null, breaking every D1
+ * read of a record that omitted it. Widen such a field to also accept null (`.nullable()`), keeping the
+ * D1 and KV paths in agreement — a not-null column is left untouched.
+ */
+function reconcileNullability(field: z.ZodType): z.ZodType {
+  const { notNull } = sqliteColumnType(field);
+  if (notNull) return field;
+  // Already accepts null? (a `.nullable()`/`.nullish()` field parses null fine) — leave it. Otherwise
+  // wrap so a stored NULL round-trips. `.nullable()` composes with an existing `.optional()`.
+  return field.safeParse(null).success ? field : field.nullable();
+}
+
+/**
+ * The effective record schema: the base {@link MediaAsset} with the adopter's extension fields merged in.
+ * Returns the base schema unchanged when no extension is given, so the common case allocates nothing.
+ */
+export function extendMediaAsset(extension?: z.ZodObject): z.ZodObject {
+  if (!extension) return MediaAsset;
+  // The base owns its columns — drop any colliding extension key before merging so a base field can
+  // never be redefined or weakened. Reconcile each remaining field's nullability with its D1 column.
+  const extra: Record<string, z.ZodType> = {};
+  for (const [key, field] of Object.entries(extension.shape)) {
+    if (!BASE_COLUMN_NAMES.has(key)) extra[key] = reconcileNullability(field as z.ZodType);
+  }
+  return MediaAsset.extend(extra);
+}
+
+/**
+ * The columns the `0002_extend` migration must add for `extension`, one per non-colliding field, in
+ * declaration order. Empty when no extension is given.
+ */
+export function extensionColumns(extension?: z.ZodObject): ExtensionColumn[] {
+  if (!extension) return [];
+  const columns: ExtensionColumn[] = [];
+  for (const [name, field] of Object.entries(extension.shape)) {
+    if (BASE_COLUMN_NAMES.has(name)) continue;
+    columns.push({ name, ...sqliteColumnType(field as z.ZodType) });
+  }
+  return columns;
+}

package/src/data/mediaAsset.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { MediaStatus, MediaType, StorageBackend } from "./enums";
+
+/**
+ * One row in `pithy_media_assets` — the spine of the capability. Every uploaded file is one record: a
+ * single table with a `type` discriminator and nullable per-type derived columns, rather than a table
+ * per media type. `z.output` is the app shape (Dates, booleans); `z.input` is the SQLite row (ms-epoch,
+ * 0|1). All JS↔SQLite conversion runs through the core codecs — no raw `0/1`, epoch, or `new Date()` in
+ * query code.
+ *
+ * The base fields are guaranteed for every configured backend and type. An adopter adds their own fields
+ * (an owning `userId`, a tenant id, tags) by passing an extension schema to `media({ extend })`; the
+ * mapping layer persists those to either store from that one schema — see `data/extend.ts`.
+ *
+ * `id` is a text UUID, not an autoincrement integer: a media id is handed to clients and embedded in
+ * URLs, so it must not be enumerable (CLAUDE.md §Data layer — externally-exposed entities use a text id).
+ */
+export const MediaAsset = z
+  .object({
+    id: z
+      .string()
+      .describe("UUID primary key. Text, not autoincrement, so an externally-exposed media id cannot be enumerated."),
+    type: MediaType.describe("The kind of media this record holds; drives which derived fields apply."),
+    status: MediaStatus.describe("The record's lifecycle state — `pending`, `stored`, or `failed`."),
+    name: z.string().describe("A human-readable display name for the media, supplied by the adopter's app."),
+    filename: z.string().describe("The original client filename, retained for display and content-type inference."),
+    contentType: z.string().describe("The MIME type of the stored bytes (e.g. `image/png`, `audio/mpeg`)."),
+    size: z
+      .number()
+      .int()
+      .nullish()
+      .describe("The object's size in bytes; null until the upload is finalized with a known length."),
+    storageBackend: StorageBackend.describe("The Cloudflare product the bytes live in — resolved from config."),
+    storageKey: z
+      .string()
+      .describe("The backend-specific handle to the bytes: the R2 object key, the CF Images id, or the CF Stream uid."),
+    sha256: z
+      .string()
+      .nullish()
+      .describe("Client-computed lowercase-hex SHA-256 of the original file, for exact-match dedup; null if omitted."),
+    phash: z
+      .string()
+      .nullish()
+      .describe("Client-computed perceptual hash (16-hex blockhash) for near-duplicate images; null for non-images."),
+    width: z.number().int().nullish().describe("Original pixel width for images and video; null for audio/documents."),
+    height: z
+      .number()
+      .int()
+      .nullish()
+      .describe("Original pixel height for images and video; null for audio/documents."),
+    altText: z
+      .string()
+      .nullish()
+      .describe("Alt text for an image, written by the image-to-text enrichment when enabled; null otherwise."),
+    caption: z
+      .string()
+      .nullish()
+      .describe("A longer caption for an image, written by the image-to-text enrichment when enabled; null otherwise."),
+    transcription: z
+      .string()
+      .nullish()
+      .describe("The speech-to-text transcription for audio/video, written by the transcription Workflow; null until."),
+    hasTranscription: SQLiteBoolean.describe("Whether a transcription has been written to this record."),
+    extractedText: z
+      .string()
+      .nullish()
+      .describe("Extracted document text (markdown), written by the document-extraction Workflow; null until."),
+    hasExtractedText: SQLiteBoolean.describe("Whether extracted text has been written to this record."),
+    createdAt: SQLiteDate.describe("When the record was created (its upload URL was minted)."),
+    updatedAt: SQLiteDate.describe("When the record was last written."),
+  })
+  .describe("One media asset in `pithy_media_assets` — the record of a stored, tracked, enrichable file.");
+export type MediaAsset = z.output<typeof MediaAsset>;
+export type MediaAssetRow = z.input<typeof MediaAsset>;

package/src/data/mediaHash.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { MediaType } from "./enums";
+
+/**
+ * One row in `pithy_media_hashes` — a dedup hash decoupled from the record store. Duplicate detection is
+ * a query workload (exact `sha256` lookup, and a bounded near-duplicate `phash` scan over images), which
+ * KV cannot do; so hashes always live in D1, regardless of whether records live in D1 or KV. This is why
+ * the media capability requires the `DB` binding even in `recordStore: 'kv'` mode.
+ */
+export const MediaHash = z
+  .object({
+    id: z.number().int().describe("Auto-increment primary key."),
+    mediaId: z.string().describe("The id of the media record this hash belongs to (one row per record)."),
+    mediaType: MediaType.describe("The media type — scopes the near-duplicate scan to images."),
+    sha256: z.string().describe("Lowercase-hex SHA-256 of the original file, for exact-match dedup."),
+    phash: z.string().nullish().describe("Perceptual hash (hex) for near-duplicate images; null for other types."),
+    createdAt: SQLiteDate.describe("When the hash row was written."),
+  })
+  .describe("One dedup hash in `pithy_media_hashes` — always D1, so dedup works whatever the record store.");
+export type MediaHash = z.output<typeof MediaHash>;

package/src/data/tables.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { MediaAsset } from "./mediaAsset";
+import { MediaHash } from "./mediaHash";
+
+/** The media record table. `CamelCasePlugin` snake-cases it to `pithy_media_assets` in the DDL. */
+export const MEDIA_ASSETS_TABLE = "pithyMediaAssets";
+/** The dedup hash table. `CamelCasePlugin` snake-cases it to `pithy_media_hashes`. */
+export const MEDIA_HASHES_TABLE = "pithyMediaHashes";
+
+/**
+ * The media tables map for a given effective schema. The hash table is always present (dedup is D1-only);
+ * the record table is present for the D1 record store and omitted for `recordStore: 'kv'`.
+ */
+export function mediaTables(
+  effective: z.ZodObject = MediaAsset,
+  options: { withAssets?: boolean } = {},
+): Record<string, z.ZodObject> {
+  const tables: Record<string, z.ZodObject> = { [MEDIA_HASHES_TABLE]: MediaHash };
+  if (options.withAssets !== false) tables[MEDIA_ASSETS_TABLE] = effective;
+  return tables;
+}
+
+/** The typed Kysely database over the base media record table. Extension columns are read/written by schema. */
+export type MediaTables = { [MEDIA_ASSETS_TABLE]: typeof MediaAsset };
+export type MediaDatabase = Kysely<DatabaseSchema<MediaTables>>;
+
+/** Build the record database from the `DB` binding (CamelCasePlugin installed). */
+export function mediaDatabase(d1: D1Database, effective: z.ZodObject = MediaAsset): MediaDatabase {
+  return createDatabase(d1, { [MEDIA_ASSETS_TABLE]: effective }) as unknown as MediaDatabase;
+}
+
+/** The typed Kysely database over the dedup hash table. */
+export type MediaHashTables = { [MEDIA_HASHES_TABLE]: typeof MediaHash };
+export type MediaHashDatabase = Kysely<DatabaseSchema<MediaHashTables>>;
+
+/** Build the hash database from the `DB` binding. */
+export function mediaHashDatabase(d1: D1Database): MediaHashDatabase {
+  return createDatabase(d1, { [MEDIA_HASHES_TABLE]: MediaHash }) as unknown as MediaHashDatabase;
+}

package/src/deliver/url.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MediaDelivery } from "../config/config";
+import { MediaUnsupportedError } from "../error/errors";
+import type { MediaRecord } from "../record/store";
+
+/**
+ * Consumer URL builders — how an app turns a stored media record into a URL its clients can load. The URL
+ * differs by backend: Cloudflare Images serves from `imagedelivery.net` with named variants, Cloudflare
+ * Stream serves HLS/DASH/thumbnails from a per-account subdomain, and R2 is either a public base URL or a
+ * presigned download (async — see {@link MediaStorage.presignedDownloadUrl}). The account identifiers come
+ * from the public `delivery` config.
+ */
+
+/** Build a Cloudflare Images delivery URL: `https://imagedelivery.net/<hash>/<imageId>/<variant>`. */
+export function buildImageUrl(imageId: string, accountHash: string, variant = "public"): string {
+  return `https://imagedelivery.net/${accountHash}/${imageId}/${variant}`;
+}
+
+/** Build a Cloudflare Stream HLS manifest URL for a video uid. */
+export function buildStreamHlsUrl(uid: string, customerCode: string): string {
+  return `https://customer-${customerCode}.cloudflarestream.com/${uid}/manifest/video.m3u8`;
+}
+
+/** Build a Cloudflare Stream DASH manifest URL for a video uid. */
+export function buildStreamDashUrl(uid: string, customerCode: string): string {
+  return `https://customer-${customerCode}.cloudflarestream.com/${uid}/manifest/video.mpd`;
+}
+
+/** Build a Cloudflare Stream still-thumbnail URL for a video uid. */
+export function buildStreamThumbnailUrl(uid: string, customerCode: string): string {
+  return `https://customer-${customerCode}.cloudflarestream.com/${uid}/thumbnails/thumbnail.jpg`;
+}
+
+/** Build a Cloudflare Stream embed/iframe URL for a video uid. */
+export function buildStreamIframeUrl(uid: string, customerCode: string): string {
+  return `https://customer-${customerCode}.cloudflarestream.com/${uid}/iframe`;
+}
+
+/**
+ * Build the consumer URL for a record from the public delivery config. Synchronous for Cloudflare Images
+ * (a named variant, default `public`) and Cloudflare Stream (HLS by default). For an R2-backed record it
+ * returns the public base URL join when `r2PublicBaseUrl` is set; otherwise it throws — a private R2
+ * object needs a presigned download URL, which is async (`storage.presignedDownloadUrl(record)`).
+ *
+ * Throws `media/unsupported` when the delivery config lacks the identifier the backend needs, so a
+ * misconfiguration surfaces clearly instead of producing a broken URL.
+ */
+export function mediaUrl(
+  record: MediaRecord,
+  delivery: MediaDelivery,
+  options: { imageVariant?: string } = {},
+): string {
+  switch (record.storageBackend) {
+    case "cf-images": {
+      if (!delivery.imagesAccountHash) {
+        throw new MediaUnsupportedError({ detail: "delivery.imagesAccountHash is required to build an image URL" });
+      }
+      return buildImageUrl(record.storageKey, delivery.imagesAccountHash, options.imageVariant ?? "public");
+    }
+    case "cf-stream": {
+      if (!delivery.streamCustomerCode) {
+        throw new MediaUnsupportedError({ detail: "delivery.streamCustomerCode is required to build a video URL" });
+      }
+      return buildStreamHlsUrl(record.storageKey, delivery.streamCustomerCode);
+    }
+    case "r2": {
+      if (!delivery.r2PublicBaseUrl) {
+        throw new MediaUnsupportedError({
+          detail: "delivery.r2PublicBaseUrl is unset; use storage.presignedDownloadUrl(record) for a private R2 object",
+        });
+      }
+      const base = delivery.r2PublicBaseUrl.replace(/\/$/, "");
+      return `${base}/${record.storageKey}`;
+    }
+  }
+}

package/src/error/errors.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/media` throw sugar. The `media/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/email` and
+ * `@pithy-sh/turnstile`. Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface MediaErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+/** A requested media record does not exist (or was soft-deleted). */
+export class MediaNotFoundError extends PithyError {
+  constructor(args: MediaErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "media/not_found",
+        status: 404,
+        message: args.message ?? "That media does not exist.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The media type, extension, or backend is not supported for the requested operation. */
+export class MediaUnsupportedError extends PithyError {
+  constructor(args: MediaErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "media/unsupported",
+        status: 400,
+        message: args.message ?? "That media type or format is not supported for this operation.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A storage operation failed — minting a direct-upload URL, or reading/deleting a stored object. */
+export class MediaStorageError extends PithyError {
+  constructor(args: MediaErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "media/storage_failed",
+        status: 502,
+        message: args.message ?? "The storage backend could not complete the request.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** An AI enrichment step (image-to-text, transcription, or extraction) failed. */
+export class MediaEnrichmentError extends PithyError {
+  constructor(args: MediaErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "media/enrichment_failed",
+        status: 500,
+        message: args.message ?? "Media enrichment could not complete.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}