@devultur/convex 1.3.2 → 1.4.1

package/README.md

@@ -12,7 +12,8 @@ pnpm exec devultur-init
 ```
 
 `devultur-init` adds the component to `convex/convex.config.ts` (mounted with `httpPrefix: "/devultur/"`, see
-[Webhook route](#webhook-route)), creates `convex/devultur.ts` with the exposed functions, and prints the Convex env
+[Webhook route](#webhook-route)), creates `convex/devultur.ts` with the exposed functions behind a sign-in guard (see
+[Guarding the component's functions](#guarding-the-components-functions)), and prints the Convex env
 vars to set (your media Worker's URL and credential).
 
 ## Webhook route
@@ -67,6 +68,55 @@ function CoverUpload({ onSaved }) {
 }
 ```
 
+## Guarding the component's functions
+
+`defineDevulturFunctions(devultur, { guard })` returns the functions your app exposes to the browser (`createUploadUrl`,
+`confirmUpload`, `updateMediaMeta`, `issueViewerToken`, `getMedia`, `listMediaPage`, `searchMedia`, `deleteMedia`,
+`deleteVideo`, `processVideo` and the progress functions), and each one awaits `guard(ctx, { name, kind, args })` before
+it runs. Throw from the guard to deny the call. `listMediaPage`, `searchMedia` and `updateMediaMeta` are library-wide:
+they read or edit every user's media, so the guard decides who may call them. Export the functions your app uses, one
+by one:
+
+```typescript
+// convex/devultur.ts
+import { Devultur, defineDevulturFunctions } from "@devultur/convex";
+import { ConvexError } from "convex/values";
+import { components } from "./_generated/api";
+
+const devultur = new Devultur(components.devultur);
+
+export const { createUploadUrl, confirmUpload, issueViewerToken, getMedia, listMediaPage, deleteMedia } =
+  defineDevulturFunctions(devultur, {
+    guard: async (ctx, operation) => {
+      const identity = await ctx.auth.getUserIdentity();
+      if (!identity) throw new ConvexError("Sign in first");
+      // `operation` narrows on `name`: its `args` are that function's arguments.
+      if (operation.name === "deleteMedia" && !(await canDelete(ctx, identity, operation.args.key))) {
+        throw new ConvexError("You can't delete this file");
+      }
+      return { userId: identity.subject };
+    },
+  });
+```
+
+- `kind` is `"query"`, `"mutation"` or `"action"`, and `ctx` is that kind's context (every one has `ctx.auth`).
+- The guard may return `{ userId }`: `issueViewerToken` then issues the viewer token for that user (its subject)
+  instead of the shared `viewer` one. The browser never names it: the exposed function only takes `sessionSecret`.
+- That `userId` is also the only user the progress functions (`saveProgress`, `loadProgress`, `markComplete`,
+  `resetProgress`) act for: a call whose `userId` is another user's is refused with `user_mismatch` (403), so a
+  signed-in user can't read or overwrite someone else's progress. Return `{ userId, canActForOthers: true }` for a
+  caller who may (an admin resetting a learner's progress). A guard that returns no `userId` keeps the browser's, as
+  `exposeApi` does: return one whenever the progress functions are exported.
+- `visibility: "internal"` registers them as internal functions, for your own actions and mutations to call.
+- `config` takes what `Devultur.exposeApi` does (transcode preset, caption locales, upload lock).
+- Each function keeps its arguments and result types, so `api.devultur.confirmUpload` is typed as before and
+  `<DevulturProvider api={api.devultur}>` takes them as it takes `exposeApi`'s.
+
+> **`Devultur.exposeApi` has no auth.** It returns the same functions with no guard: anyone who can reach your Convex
+> deployment can create upload URLs, confirm uploads, list the whole library and delete media. It keeps working, but
+> use it only for a deployment where every caller is trusted, or move to `defineDevulturFunctions`, which takes the
+> same `config`.
+
 ## Upload progress
 
 `upload(file, { onProgress, signal })` reports the PUT's progress and resolves to the stored reference:
@@ -122,6 +172,49 @@ The provider sends `{ sessionSecret, ...tokenArgs }` on the first issuance, on e
 provider drops the current token, private media wait for the new one, and a response for the previous arguments is
 ignored. Your action returns what the component's action returns: `{ token, expiresIn }` or the token string.
 
+### Display-only apps
+
+An app that only shows media (no uploads, no deletes) uses `<DevulturViewerProvider>`, which needs only the base URL
+and a viewer token action:
+
+```tsx
+import { DevulturViewerProvider, Preview } from "@devultur/convex/react";
+
+<DevulturViewerProvider
+  baseUrl={MEDIA_URL}
+  issueViewerToken={api.admin.issueWorkspaceViewerToken}
+  tokenArgs={{ workspaceId }}
+>
+  <Preview media={document.file} />
+</DevulturViewerProvider>;
+```
+
+`<Image>`, `<Preview>`, `<PdfThumbnail>`, `<DownloadLink>`, `<DocumentLink>`, `<AttachmentCard>`, `useMediaObjectUrl`,
+`useMediaUrl` and `useVideoProps` work under it. `useDevultur().upload`, `uploadUrl` and `deleteMedia`, and the hooks
+that need the `api` (`useDevulturApi`, `useMediaUpload`, `<MediaLibrary>`, `<MediaPicker>`), throw a
+`DevulturCapabilityError` whose `code` is `capability_unavailable`.
+
+### When the viewer token can't be issued
+
+`useDevultur()` tells where the viewer token stands:
+
+```tsx
+const { tokenStatus, tokenError, retryToken } = useDevultur();
+// tokenStatus: "idle" | "loading" | "ready" | "error"
+if (tokenStatus === "error") return <button onClick={retryToken}>Try again</button>; // tokenError has why
+```
+
+The status turns `"error"` when the action throws (your guard refused, for example) or returns no token, and stays
+there until `retryToken()`: a failed issuance isn't retried on its own. Meanwhile private media fails at once with the
+`MediaFetchError` code `token_unavailable` instead of loading: `useMediaObjectUrl` returns it as `error`,
+`<Preview>` passes it to its `fallback`, `<PdfThumbnail>` and `<Image>` render their `fallback` (`<Image onLoadError>`
+receives it), and `<DownloadLink onDownloadError>` receives it on click. They load once `retryToken()` gets a token.
+
+`<Preview>`'s video re-issues the token once when the delivery answers the playlist or a segment with a 401
+`session_mismatch`; after that, or on any other 401, it renders its `fallback` with `session_mismatch` or
+`token_unavailable`. `<VideoPlayer onError>` (from `@devultur/react`) reports these failures when you render the
+player yourself.
+
 ## Media library
 
 Every upload, whatever its kind, gets a record in the component's `media` table once its bytes are stored, so
@@ -162,15 +255,16 @@ export const imagesPage = query({
 // React: usePaginatedQuery(api.library.imagesPage, {}, { initialNumItems: 24 })
 ```
 
-`Devultur.exposeApi` also returns a `listMediaPage` query (`{ type?, paginationOpts }`). It lists every user's media,
-so export it only when every caller may see the whole library.
+`defineDevulturFunctions` also returns a `listMediaPage` query (`{ type?, paginationOpts }`). It lists every user's
+media, so its guard decides who may see the whole library (see
+[Guarding the component's functions](#guarding-the-components-functions)).
 
 A record is written only after the Worker confirms the object exists, so an abandoned upload never shows up:
 
 1. After its PUT, the client calls `confirmUpload({ key, filename, width, height })`. The component asks the Worker
    for the object (a `HEAD`) and records its size and content type. `useDevultur().upload()` and `useMediaUpload` do
    this for you when the `api` you pass `<DevulturProvider>` has `confirmUpload` (add it to the functions you export
-   from `Devultur.exposeApi` in `convex/devultur.ts`). From your server: `devultur.confirmUpload(ctx, { key })`.
+   from `defineDevulturFunctions` in `convex/devultur.ts`). From your server: `devultur.confirmUpload(ctx, { key })`.
 2. `createUploadUrl` also schedules the same check for 25 hours later, past the longest an upload can take. An upload
    whose client never confirmed is recorded then; one that was never stored, or was deleted, isn't.
 
@@ -178,11 +272,9 @@ A record's `key` is the media id for every kind (what `getMedia` takes), and `ob
 `confirmUpload` only accepts upload keys (`{visibility}/{image|file}/{id}/{name}`, `{visibility}/video/{id}/raw/{name}`)
 and is idempotent: a video's transcode state stays as it is.
 
-`confirmUpload`, like every function `exposeApi` returns (and the `devultur-init` template exports), has no auth of
-its own: anyone who can call your Convex deployment can call it. Wrap it with your app's auth, as you would the other
-exposed functions: export your own action that checks `ctx.auth` and then calls `devultur.confirmUpload(ctx, { key })`.
-The caller only names the key: the record's visibility, size and content type come from the Worker's `HEAD` of the
-object, never from the arguments.
+`confirmUpload` runs your guard first, like every function `defineDevulturFunctions` returns. The record's
+visibility, size and content type come from the Worker's `HEAD` of the object, never from the arguments; the only
+values a caller supplies are the hints described in [Media metadata](#media-metadata).
 
 `deleteMedia` removes an image's or a file's record once the Worker
 deleted the object (a delete refused by a lock keeps it). `deleteVideo` removes a video's.
@@ -190,6 +282,296 @@ deleted the object (a delete refused by a lock keeps it). `deleteVideo` removes
 A video only `processVideo` recorded has no `visibility` or `objectKey`, and `mediaFromRecord` returns `null` for
 it. `listMedia` doesn't report an object's lock: read it from an action with `devultur.getLock(ctx, record.objectKey)`.
 
+### Media metadata
+
+A record carries what is known about its media. All of these fields are optional, so records and `dv.media()`
+references stored before 1.4.0 stay valid without a migration.
+
+| Field | Set by |
+| --- | --- |
+| `sizeBytes` | The Worker's `HEAD` of the object, on every confirm. |
+| `width`, `height` | The Worker, which reads an image's size from its header bytes (PNG, JPEG, GIF, WebP, AVIF) on a single PUT and returns it on `HEAD` (`x-devultur-image-width` / `-height`). Otherwise, the client's hint. |
+| `duration` | The transcode, in seconds (`transcode.started` / `transcode.complete`). |
+| `pageCount` | The client's hint, recorded for PDFs only. |
+| `title`, `alt`, `tags` | Your app, with `updateMediaMeta`. |
+
+**Client hints.** `confirmUpload` accepts `width`, `height` and `pageCount` from the client. They are the uploader's
+word, not checked against the bytes: whole numbers from 1 to 100,000. Another value is dropped (with a warning in the
+logs) and the upload is recorded without it: the bytes are already stored.
+A size the Worker read wins over the client's. To record a PDF's page count at upload, count it in the browser with
+pdf.js (imported on the first call; `pdfjs-dist` must be installed):
+
+```tsx
+import { countPdfPages } from "@devultur/convex/pdfjs";
+
+const pageCount = file.type === "application/pdf" ? ((await countPdfPages(file)) ?? undefined) : undefined;
+const media = await upload(file, { pageCount });
+```
+
+**Editing.** `updateMediaMeta({ key, title?, alt?, tags? })` sets only the fields it's given. Values are trimmed, an
+empty `title` or `alt` clears it, and tags are deduplicated (case-insensitively, first spelling kept). Past a title of
+200 characters, an alt text of 1,000, or 20 tags of 50 characters each, it fails with `invalid_media_metadata` (its
+`details.field` names the field). It returns the updated record, or `null` when no record has that media id.
+
+```typescript
+// From the browser: export it from defineDevulturFunctions, so your guard decides who may edit which media.
+export const { updateMediaMeta } = defineDevulturFunctions(devultur, { guard });
+// From your server:
+await devultur.updateMediaMeta(ctx, { key: record.key, title: "Cover", alt: "A mountain at dawn", tags: ["hero"] });
+```
+
+`mediaFromRecord(record)` copies the metadata into the reference, and `<Image>` uses `media.alt` when you pass no
+`alt`. A stored reference is a copy: after an edit, read the record again (`getMedia`) or store the new reference.
+
+Each write also keeps a `searchText` field (the title and filename, lowercased) with a `search_text` search index over
+it, filterable by `type`. Records written before 1.4.0 get theirs from [the backfill](#records-from-before-140) or
+from their next write.
+
+### Searching the library
+
+`searchMedia({ search, type?, paginationOpts })` pages through the records whose title or filename matches `search`,
+best match first, optionally of one type. Convex's full-text search matches whole words, and the last word as a
+prefix (`cov` finds "Cover photo"). A blank `search` lists the library newest first, like `listMediaPage`.
+
+```typescript
+// Behind your guard: like listMediaPage, it searches every user's media.
+export const { listMediaPage, searchMedia } = defineDevulturFunctions(devultur, { guard });
+// From your server:
+await devultur.searchMedia(ctx, { search: "cover", type: "image", paginationOpts });
+```
+
+#### Records from before 1.4.0
+
+Records written before 1.4.0 have no `searchText`, so `searchMedia` doesn't find them (`listMediaPage` still lists
+them). Any write to one gives it its `searchText` (a transcode update, a confirmed upload, `updateMediaMeta`). To fill
+them all at once, run the backfill once after upgrading. It fills 100 records per mutation and schedules the next
+batch until it reaches the end of the table; running it again only fills what is still missing.
+
+```bash
+npx convex run --component devultur library:backfillSearchText '{}'
+```
+
+Or from a function of your own, for example an internal mutation you run from the dashboard:
+
+```typescript
+// convex/maintenance.ts
+import { internalMutation } from "./_generated/server";
+
+export const backfillMediaSearch = internalMutation({
+  args: {},
+  // { updated, isDone }: the first batch's count, and false while more batches are scheduled.
+  handler: async (ctx) => devultur.backfillSearchText(ctx, { batchSize: 200 }), // 1 to 1000, default 100
+});
+```
+
+### React: `useMediaLibrary` and `<MediaLibrary>`
+
+Both read the library through the `listMediaPage` and `searchMedia` you pass `<DevulturProvider api>`.
+
+`useMediaLibrary({ type?, search?, pageSize? })` wraps Convex's `usePaginatedQuery`. It waits until `search` has
+stayed the same for 250 ms before querying (clearing it applies at once), and a new search or type starts again from
+the first page.
+
+```tsx
+import { useMediaLibrary } from "@devultur/convex/react";
+
+const { items, status, loadMore, isLoading, isSearchPending } = useMediaLibrary({ type: "image", search, pageSize: 24 });
+// status: "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted"; loadMore() loads pageSize more.
+```
+
+Like `usePaginatedQuery`, a query that fails (your guard throws, for example) throws during render to the nearest
+error boundary. `<MediaLibrary>` has its own.
+
+`<MediaLibrary>` is a grid with a search box and a type filter. Images show a 160 px thumbnail (`<Image widths>`,
+`format: "auto"`); other media show an icon, and every item shows its title (or filename) and size.
+
+```tsx
+import { MediaLibrary } from "@devultur/convex/react";
+
+<MediaLibrary type="image" selectable onSelect={(record, media) => setCover(media)} />;
+```
+
+| Prop | |
+| --- | --- |
+| `onSelect(record, media)` | Called on a click, Enter or Space. `media` is `mediaFromRecord(record)`, `null` for a record without a visibility. |
+| `type` | Only this type; the type filter is hidden. |
+| `selectable` | Keeps the chosen item selected (`aria-selected`, `data-selected`), for a picker. Default `false`. |
+| `selectedKeys` | The selected records' keys (media ids), controlled: shown as selected instead of the last one chosen. Implies `selectable`. |
+| `multiple` | Several items can be selected (`aria-multiselectable`), with `selectedKeys`. |
+| `filter(record)` | Shows only the records it returns `true` for, of each loaded page (a page can then show fewer items). |
+| `renderItem(record, { media, isSelected, isActive })` | Replaces an item's content; the item stays the focusable option. |
+| `pdfThumbnails` | Draws page 1 of PDFs with `<PdfThumbnail>` (inside a `PdfPreviewProvider`). Off by default, because each thumbnail downloads its PDF. |
+| `pageSize` | Records per page. Default 24. |
+| `labels` | Any of the strings below. |
+| `className`, `classNames` | Added to the root's and each part's class. |
+
+The items are a `listbox` of `option`s with one tab stop: the arrow keys move between them (up and down by a row of the
+grid), Home and End go to the first and last. While the first page loads, the library is empty, or nothing matches,
+a `role="status"` message replaces the grid. A failed query shows `labels.error(error)` in a `role="alert"` with a
+retry button; by default, a Devultur error's message (see [Error messages](#error-messages)).
+
+The component sets only its layout. Each part has a class (`devultur-media-library`, and
+`devultur-media-library__{search,filter,list,item,thumbnail,name,size,status,more}`), and these custom properties
+tune the grid: `--devultur-library-item-width` (160px, the narrowest column), `--devultur-library-gap` (0.75rem),
+`--devultur-library-item-gap` (0.25rem), `--devultur-library-thumbnail-height` (120px) and
+`--devultur-library-accent` (`currentColor`, the selected item's ring).
+
+The strings are English by default; `@devultur/convex/locales/es` exports Spanish ones:
+
+```tsx
+import { mediaLibraryLabels } from "@devultur/convex/locales/es";
+
+<MediaLibrary labels={mediaLibraryLabels} onSelect={handleSelect} />;
+```
+
+## Media picker
+
+`<MediaPicker>` is what a content editor uses to fill a media field: it uploads new files (with progress, cancel and
+retry), browses and searches the library (`<MediaLibrary>`), and shows the selection (`<AttachmentCard>`, with an
+inline `<Preview>`). It returns `DevulturMedia` references through `onChange`, ready for a `dv.media()` field: a
+library item's reference carries its `key`, `title`, `alt`, `tags`, size and page count; a new upload's carries its
+`key`, size and page count, and is selected as soon as it uploads.
+
+It needs `createUploadUrl`, `listMediaPage` and `searchMedia` in `<DevulturProvider api>` (and `confirmUpload`, so
+uploads show in the library).
+
+```tsx
+import { MediaPicker } from "@devultur/convex/react";
+
+<MediaPicker accept={["image/*"]} value={cover} onChange={setCover} />;
+<MediaPicker multiple value={attachments} onChange={setAttachments} />; // arrays in and out
+```
+
+| Prop | |
+| --- | --- |
+| `value` | The selection, controlled: a `DevulturMedia` or `null` (an array with `multiple`). Omitted, the picker keeps its own. |
+| `onChange(value)` | Called on an upload, a pick from the library, a removal and a clear. |
+| `multiple` | Several items: uploads add to the selection, and a library item toggles. Default `false`: a new pick replaces the item. |
+| `accept` | File types, as `<input accept>` takes them (`image/*`, `application/pdf`, `.pdf`). Filters the files to upload and the library's items, and sets the library's type filter when every pattern is of one type. |
+| `type` | Only `image`, `video` or `file` in the library; without `accept`, also what can be uploaded. |
+| `labels` | Any of the picker's strings (`MediaPickerLabels`). |
+| `libraryLabels`, `attachmentLabels` | The library's and the cards' strings. |
+| `className` | Added to the root's `devultur-media-picker` class. |
+| `children` | The layout (below). Default: the upload, the library and the selection. |
+
+Under a `PdfPreviewProvider` with `pdfjs`, the picker reads a PDF's page count before it uploads it and records it
+with the upload (`pageCount`). Without one, PDFs upload without it.
+
+### Layout
+
+The picker renders inline and has no dialog of its own. Its parts are `<MediaPicker.Upload>`, `<MediaPicker.Library>`
+and `<MediaPicker.Selection>`; put them in any markup of yours, or pass a function as `children` to get the picker's
+state (`selected`, `uploads`, `select`, `remove`, `clear`, `openFileDialog`, ...). `useMediaPicker()` returns the same
+state, to build a part of your own.
+
+```tsx
+<MediaPicker multiple value={files} onChange={setFiles}>
+  {(picker) => (
+    <div className="grid grid-cols-[2fr_1fr] gap-4">
+      <MediaPicker.Library pageSize={12} />
+      <aside>
+        <MediaPicker.Upload />
+        <MediaPicker.Selection headingLevel={2} />
+        <p>{picker.selected.length} selected</p>
+      </aside>
+    </div>
+  )}
+</MediaPicker>
+```
+
+### In a dialog, for a form field
+
+A form keeps the reference in its state and saves it with the rest; the dialog only edits a draft of it. Here with a
+native `<dialog>` (it traps focus and closes on Escape); any dialog component works the same way.
+
+```tsx
+import type { DevulturMedia } from "@devultur/core";
+import { MediaPicker } from "@devultur/convex/react";
+import { useMutation } from "convex/react";
+import { api } from "../convex/_generated/api";
+
+function CoverField({ value, onChange }: { value: DevulturMedia | null; onChange: (cover: DevulturMedia | null) => void }) {
+  const dialogRef = React.useRef<HTMLDialogElement>(null);
+  const [draft, setDraft] = React.useState(value);
+
+  const handleOpen = () => {
+    setDraft(value);
+    dialogRef.current?.showModal();
+  };
+  const handleConfirm = () => {
+    onChange(draft);
+    dialogRef.current?.close();
+  };
+
+  return (
+    <>
+      <span>{value?.title ?? value?.filename ?? "No cover"}</span>
+      <button type="button" onClick={handleOpen}>Choose a cover</button>
+      <dialog ref={dialogRef} aria-labelledby="cover-dialog-title">
+        <h2 id="cover-dialog-title">Cover</h2>
+        <MediaPicker accept={["image/*"]} value={draft} onChange={setDraft} />
+        <button type="button" onClick={() => dialogRef.current?.close()}>Cancel</button>
+        <button type="button" onClick={handleConfirm}>Use this image</button>
+      </dialog>
+    </>
+  );
+}
+
+function ArticleForm({ article }: { article: { _id: string; title: string; cover: DevulturMedia | null } }) {
+  const save = useMutation(api.articles.update); // args: { id, title, cover: dv.media("image").optional() }
+  const [title, setTitle] = React.useState(article.title);
+  const [cover, setCover] = React.useState(article.cover);
+
+  const handleSubmit = (event: React.FormEvent) => {
+    event.preventDefault();
+    save({ id: article._id, title, cover: cover ?? undefined });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={title} onChange={(event) => setTitle(event.target.value)} aria-label="Title" />
+      <CoverField value={cover} onChange={setCover} />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+Inside a `<form>`, every button of the picker is `type="button"`, so none of them submits it.
+
+### Accessibility
+
+The upload button opens the file chooser; dropping files on the upload area is the pointer shortcut. Each upload
+shows a labelled `<progress>`, a cancel button and, when it fails, its error in a `role="alert"` (by default a
+Devultur error's message, see [Error messages](#error-messages)), with retry and dismiss. A polite live region
+announces an upload's start, end and cancellation, and each selection and removal. After an upload, a removal and a
+clear, focus moves to the selection's region (`<section>` named by its heading), so a keyboard user lands on the
+result. The library keeps its keyboard navigation, with `aria-multiselectable` under `multiple`.
+
+### Labels
+
+The strings are English by default (`defaultMediaPickerLabels`). Spanish:
+
+```tsx
+import { attachmentLabels, mediaLibraryLabels, mediaPickerLabels } from "@devultur/convex/locales/es";
+
+<MediaPicker
+  labels={mediaPickerLabels}
+  libraryLabels={mediaLibraryLabels}
+  attachmentLabels={attachmentLabels}
+  value={cover}
+  onChange={setCover}
+/>;
+```
+
+### Styling
+
+The picker sets no styles but the library's layout. Each part has a class (`devultur-media-picker`,
+`devultur-media-picker__upload`, `devultur-media-picker__selection`, and the library's own) and its elements have
+`data-part` attributes (`upload`, `drop-hint`, `uploads`, `filename`, `percent`, `error`, `items`, `empty`,
+`actions`, `replace`, `clear`); the upload area has `data-dragging` while files are dragged over it, and each upload
+`data-status` (`uploading` or `failed`).
+
 ## Using a self-hosted Worker
 
 The component talks to any Worker built with `createWorker()` from
@@ -263,6 +645,41 @@ try {
 `isDevulturError(error)` is the matching type guard. Errors that aren't Worker refusals, such as a network failure,
 are rethrown unchanged.
 
+### Error messages
+
+`describeDevulturError(error, labels?)` turns an error into a message for your users: a component action's refusal,
+a `DevulturApiError` from `@devultur/core`, or a `MediaFetchError` from a preview or download. It returns `null` for
+any other error, so your app keeps its own fallback. A code it doesn't know gets the generic `worker_error` message.
+
+`devulturErrorLabels` is the English map, typed `Record<DevulturErrorCode, string | ((details) => string)>`:
+`DevulturErrorCode` is the union of every stable code (`DEVULTUR_ERROR_CODES` lists them), and a function label reads
+the error's details, such as `file_too_large`'s `limit`. `@devultur/convex/locales/es` exports the Spanish map under
+the same name:
+
+```tsx
+import { describeDevulturError } from "@devultur/convex";
+import { devulturErrorLabels as spanishLabels } from "@devultur/convex/locales/es";
+
+const deleteMedia = useAction(api.devultur.deleteMedia);
+
+try {
+  await deleteMedia({ key });
+} catch (error) {
+  // "Este archivo está protegido hasta el 15 jun 2030 y no se puede modificar ni eliminar antes de esa fecha."
+  setMessage(describeDevulturError(error, spanishLabels) ?? "Algo salió mal.");
+}
+```
+
+A failed browser PUT (`upload()`, `useMediaUpload`) rejects with `UploadHttpError`, which carries the HTTP status
+only: match on its `status` for those.
+
+Pass a partial map to change some messages and keep the rest, or a full one for another language (typed
+`DevulturErrorLabels`, so a missing code fails to compile):
+
+```ts
+describeDevulturError(error, { ...spanishLabels, lock_conflict: "Alguien más acaba de cambiarlo." });
+```
+
 ## Object lock
 
 - `devultur.createUploadUrl(ctx, { filename, contentType, lock, hold })` locks a file from its first write.

package/dist/bin/init.js

@@ -3,6 +3,49 @@
 // src/bin/init.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+
+// src/bin/devultur-module-template.ts
+var DEVULTUR_MODULE_TEMPLATE = `import { CaptionLocale, Devultur, defineDevulturFunctions, TranscodePreset } from "@devultur/convex";
+import { ConvexError } from "convex/values";
+import { components } from "./_generated/api";
+
+const devultur = new Devultur(components.devultur);
+
+// Every function below runs this guard first. Adjust it to your app's auth and rules (narrow on \`operation.name\`).
+export const {
+	issueViewerToken,
+	createUploadUrl,
+	confirmUpload,
+	deleteMedia,
+	deleteVideo,
+	processVideo,
+	getMedia,
+	// The library lists and searches every user's media: the guard decides who may read it.
+	listMediaPage,
+	searchMedia,
+	// Editing a title, alt text or tags is library-wide too: authorize it in the guard before exporting it.
+	// updateMediaMeta,
+	saveProgress,
+	loadProgress,
+	markComplete,
+	resetProgress,
+} = defineDevulturFunctions(devultur, {
+	guard: async (ctx, operation) => {
+		const identity = await ctx.auth.getUserIdentity();
+		if (!identity) throw new ConvexError(\`Sign in to call \${operation.name}\`);
+		// The progress functions act only for this user: another \`userId\` in their arguments is refused.
+		return { userId: identity.subject };
+	},
+	config: {
+		video: {
+			transcodePreset: TranscodePreset.HLS_720P,
+			captionLocales: [CaptionLocale.EN],
+		},
+	},
+});
+`;
+
+// src/bin/init.ts
 var CONVEX_DIR = findConvexDir();
 function findConvexDir() {
   const cwd = process.cwd();
@@ -70,29 +113,7 @@ function createDevulturModule() {
     log("\u23ED\uFE0F  convex/devultur.ts already exists \u2014 skipping");
     return;
   }
-  const content = `import { CaptionLocale, Devultur, TranscodePreset } from "@devultur/convex";
-import { components } from "./_generated/api";
-
-export const {
-	issueViewerToken,
-	createUploadUrl,
-	confirmUpload,
-	deleteMedia,
-	deleteVideo,
-	processVideo,
-	getMedia,
-	saveProgress,
-	loadProgress,
-	markComplete,
-	resetProgress,
-} = Devultur.exposeApi(components.devultur, {
-	video: {
-		transcodePreset: TranscodePreset.HLS_720P,
-		captionLocales: [CaptionLocale.EN],
-	},
-});
-`;
-  writeFileSync(modulePath, content);
+  writeFileSync(modulePath, DEVULTUR_MODULE_TEMPLATE);
   log("\u2705 Created convex/devultur.ts");
 }
 console.log("\n\u{1F527} @devultur/convex init\n");