@devultur/convex 1.4.3 → 1.5.1

package/README.md

@@ -107,16 +107,62 @@ export const { createUploadUrl, confirmUpload, issueViewerToken, getMedia, listM
   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.
+- The guard may also return a `rewrite`, `{ name, args }`: each key of `args` replaces the caller's argument of that
+  name, on your server, before the function runs (see [Upload visibility](#upload-visibility)). `name` is the guarded
+  operation's, so `args` are typed for it; a rewrite named for another operation throws. The rewritten arguments
+  aren't validated again.
 - `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.
+- `config` takes what `Devultur.exposeApi` does (transcode preset, caption locales, upload lock and default
+  visibility).
+- Each function keeps its arguments and returns the component's result, typed: with no annotation,
+  `useQuery(api.devultur.getMedia, { key })` is a `MediaDocument | null` (a `MediaRecord` with its `_id` and
+  `_creationTime`), and `listMediaPage` and `searchMedia` are a `PaginationResult<MediaDocument>`.
+  `DevulturFunctionResults` names every function's result. `<DevulturProvider api={api.devultur}>` takes them as it
+  takes `exposeApi`'s, whose results are the same.
 
 > **`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 visibility
+
+`config.upload.visibility` sets the visibility of an upload whose caller passes none. Without it, the Worker's default
+by type applies.
+
+```typescript
+export const { createUploadUrl, confirmUpload } = defineDevulturFunctions(devultur, {
+  guard,
+  config: { upload: { visibility: "public" } }, // a site whose uploads are public unless the browser asks otherwise
+});
+```
+
+The browser can still pass `visibility` (`upload(file, { visibility })`, `useMediaUpload({ visibility })`). To decide
+it on your server instead, rewrite it in the guard: the guard's `rewrite` replaces the browser's arguments.
+
+```typescript
+guard: async (ctx, operation) => {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) throw new ConvexError("Sign in first");
+  // Members' uploads are always private, whatever the browser asked for.
+  if (operation.name === "createUploadUrl") {
+    return { userId: identity.subject, rewrite: { name: "createUploadUrl", args: { visibility: "private" } } };
+  }
+  return { userId: identity.subject };
+},
+```
+
+Which one wins, from first to last:
+
+1. The guard's `rewrite.args.visibility`.
+2. The caller's `visibility`.
+3. `config.upload.visibility`.
+4. The Worker's default by type.
+
+The guard sees the caller's arguments as they arrived (`operation.args.visibility` is `undefined` when the browser
+passed none): the config's default is applied after the guard. `config.upload.lock` isn't an argument, so neither
+the browser nor the guard's `rewrite` change it.
+
 ## Upload progress
 
 `upload(file, { onProgress, signal })` reports the PUT's progress and resolves to the stored reference:
@@ -175,7 +221,7 @@ ignored. Your action returns what the component's action returns: `{ token, expi
 ### 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:
+and, for private media, a viewer token action:
 
 ```tsx
 import { DevulturViewerProvider, Preview } from "@devultur/convex/react";
@@ -194,13 +240,64 @@ import { DevulturViewerProvider, Preview } from "@devultur/convex/react";
 that need the `api` (`useDevulturApi`, `useMediaUpload`, `<MediaLibrary>`, `<MediaPicker>`), throw a
 `DevulturCapabilityError` whose `code` is `capability_unavailable`.
 
+Like `<DevulturProvider>`, it issues the viewer token as soon as it mounts. With `lazyToken`, it issues it only when
+a private media is shown, and renews it from then on: while every media on the page is public, it calls nothing,
+`tokenStatus` stays `"idle"` and `token` stays `null`. Code that reads `token` itself then calls
+`useDevultur().requestToken()` first; the built-in components and hooks do it for private media.
+
+```tsx
+<DevulturViewerProvider baseUrl={MEDIA_URL} issueViewerToken={api.devultur.issueViewerToken} lazyToken>
+  <Gallery />
+</DevulturViewerProvider>
+```
+
+When all the media is public, leave `issueViewerToken` out. The provider then needs no Convex client and issues
+nothing:
+
+```tsx
+<DevulturViewerProvider baseUrl={MEDIA_URL}>
+  <Image media={post.cover} alt={post.title} />
+</DevulturViewerProvider>
+```
+
+A private media shown under it fails with `token_unavailable`, and `tokenError` says the provider has no
+`issueViewerToken`.
+
+### Components outside a provider
+
+`useDevultur()` throws outside `<DevulturProvider>` and `<DevulturViewerProvider>`. A component that also renders
+without one uses `useDevulturOptional()`, which returns the same value, or `null` outside both:
+
+```tsx
+function Avatar({ media, fallbackUrl }) {
+  const devultur = useDevulturOptional();
+  if (!devultur || !media) return <img src={fallbackUrl} alt="" />;
+  return <Image media={media} alt="" width={64} />;
+}
+```
+
+### Only the hooks
+
+`@devultur/convex/react/hooks` exports the contexts and the hooks that only read them, without the components or
+Convex's client: `useDevultur`, `useDevulturOptional`, `useDevulturApi`, `useDevulturProgress`, `useMediaUrl`,
+`useVideoProps`, and the `DevulturContext`, `DevulturApiContext` and `DevulturProgressContext` objects. A shared
+component that only checks for a provider adds well under 1 kB gzipped to the bundle:
+
+```tsx
+import { useDevulturOptional } from "@devultur/convex/react/hooks";
+```
+
+They're the very objects `@devultur/convex/react` exports, so a `<DevulturProvider>` or `<DevulturViewerProvider>`
+imported from there fills them. The hooks that call your Convex functions (`useDevulturMedia`, `useVideoState`,
+`useMediaUpload`, `useMediaLibrary`) stay in `@devultur/convex/react`, with the components.
+
 ### 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"
+// tokenStatus: "idle" (not asked for yet) | "loading" | "ready" | "error"
 if (tokenStatus === "error") return <button onClick={retryToken}>Try again</button>; // tokenError has why
 ```
 
@@ -210,6 +307,11 @@ there until `retryToken()`: a failed issuance isn't retried on its own. Meanwhil
 `<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 plays in `<VideoPlayer>` from `@devultur/react`, with its playback metrics on: anonymous, no
+cookies, sent to the media host (see [Playback metrics](https://github.com/devultur/devultur/blob/main/docs/guides/video-player.md#playback-metrics),
+also in `node_modules/@devultur/convex/docs/guides/video-player.md`).
+`<Preview metrics={false}>` turns them off. A private video shows `loading` until its viewer token is issued.
+
 `<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
@@ -658,8 +760,8 @@ the same name.
 
 `@devultur/convex/locales/es` addresses the reader with «tú» ("Vuelve a intentarlo"). For «usted» ("Vuelva a
 intentarlo", "No tiene permiso…"), import the same names from `@devultur/convex/locales/es-formal`: it exports exactly
-what `locales/es` does (error, attachment, preview, library and picker labels), and differs only in the strings that
-address the reader.
+what `locales/es` does (error, attachment, preview, library, picker and video player labels), and differs only in the
+strings that address the reader.
 
 ```tsx
 import { describeDevulturError } from "@devultur/convex";
@@ -685,6 +787,18 @@ Pass a partial map to change some messages and keep the rest, or a full one for
 describeDevulturError(error, { ...spanishLabels, lock_conflict: "Alguien más acaba de cambiarlo." });
 ```
 
+### Video player labels
+
+`<VideoPlayer>` from `@devultur/react` takes `labels` like the components here do. Both Spanish locales export
+`videoPlayerLabels`:
+
+```tsx
+import { VideoPlayer } from "@devultur/react";
+import { videoPlayerLabels } from "@devultur/convex/locales/es";
+
+<VideoPlayer {...useVideoProps(lesson.video)} labels={videoPlayerLabels} />;
+```
+
 ## Object lock
 
 - `devultur.createUploadUrl(ctx, { filename, contentType, lock, hold })` locks a file from its first write.
@@ -701,6 +815,8 @@ what's enforced and the caveats.
 ## Documentation
 
 Guides and API reference: [github.com/devultur/devultur/tree/main/docs](https://github.com/devultur/devultur/tree/main/docs).
+The guides this README links to ship with the package, for the installed version, in
+`node_modules/@devultur/convex/docs/guides/`: `video-player.md`, `self-host.md`, `plugins.md` and `object-lock.md`.
 
 ## License
 

package/dist/chunk-BDEO67OT.js

@@ -0,0 +1,110 @@
+// src/capability-error.ts
+var DevulturCapabilityError = class extends Error {
+  code = "capability_unavailable";
+  capability;
+  constructor(capability) {
+    super(
+      `Devultur: \`${capability}\` isn't available under <DevulturViewerProvider>. Use <DevulturProvider api> with the actions it needs.`
+    );
+    this.name = "DevulturCapabilityError";
+    this.capability = capability;
+  }
+};
+
+// src/devultur-context.ts
+import React from "react";
+var DevulturContext = /* @__PURE__ */ React.createContext(null);
+var DevulturApiContext = /* @__PURE__ */ React.createContext(null);
+function useDevultur() {
+  const context = React.use(DevulturContext);
+  if (!context) throw new Error("useDevultur must be used within <DevulturProvider> or <DevulturViewerProvider>");
+  return context;
+}
+function useDevulturOptional() {
+  return React.use(DevulturContext);
+}
+function useDevulturApi() {
+  const api = React.use(DevulturApiContext);
+  if (api) return api;
+  if (React.use(DevulturContext)) throw new DevulturCapabilityError("api");
+  throw new Error("useDevulturApi must be used within <DevulturProvider>");
+}
+
+// src/progress-context.ts
+import React2 from "react";
+var DevulturProgressContext = /* @__PURE__ */ React2.createContext(null);
+function useDevulturProgress() {
+  const context = React2.use(DevulturProgressContext);
+  if (!context) throw new Error("useDevulturProgress requires progress API in DevulturProvider");
+  return context;
+}
+
+// src/media-url-hooks.ts
+import React4 from "react";
+import {
+  buildMediaUrl,
+  CaptionLocaleLabel,
+  mediaCaptionPath,
+  mediaPath,
+  visibilityFromKey
+} from "@devultur/core";
+
+// src/request-token.ts
+import React3 from "react";
+function useRequestTokenWhen(session, isNeeded) {
+  const { requestToken, token } = session;
+  const hasToken = token !== null;
+  React3.useEffect(() => {
+    if (isNeeded && !hasToken) requestToken();
+  }, [isNeeded, hasToken, requestToken]);
+}
+
+// src/media-url-hooks.ts
+function useMediaUrl(key, options) {
+  const devultur = useDevultur();
+  const { token, baseUrl } = devultur;
+  useRequestTokenWhen(devultur, Boolean(key) && visibilityFromKey(key ?? "") !== "public");
+  return React4.useMemo(() => {
+    if (!key) return null;
+    if (!baseUrl) throw new Error("useMediaUrl requires `baseUrl` on <DevulturProvider>");
+    const isPublic = visibilityFromKey(key) === "public";
+    return buildMediaUrl(baseUrl, key, { ...options, token: isPublic ? void 0 : token ?? void 0 });
+  }, [key, baseUrl, token, options]);
+}
+function useVideoProps(media, options) {
+  const devultur = useDevultur();
+  const { token, baseUrl, sessionSecret } = devultur;
+  useRequestTokenWhen(devultur, media?.kind === "video" && media.visibility === "private");
+  const locales = options?.locales;
+  return React4.useMemo(() => {
+    if (media?.kind !== "video") return null;
+    if (!baseUrl) throw new Error("useVideoProps requires `baseUrl` on <DevulturProvider>");
+    const viewerToken = media.visibility === "private" ? token ?? void 0 : void 0;
+    const captions = (locales ?? []).flatMap((locale) => {
+      const path = mediaCaptionPath(media, locale);
+      if (!path) return [];
+      const label = CaptionLocaleLabel[locale] ?? locale;
+      return [{ locale, label, src: buildMediaUrl(baseUrl, path, { token: viewerToken }) }];
+    });
+    return {
+      src: buildMediaUrl(baseUrl, mediaPath(media), { token: viewerToken }),
+      token: viewerToken,
+      captions,
+      sessionSecret: media.visibility === "private" ? sessionSecret : void 0
+    };
+  }, [media, baseUrl, token, locales, sessionSecret]);
+}
+
+export {
+  DevulturCapabilityError,
+  DevulturContext,
+  DevulturApiContext,
+  useDevultur,
+  useDevulturOptional,
+  useDevulturApi,
+  DevulturProgressContext,
+  useDevulturProgress,
+  useRequestTokenWhen,
+  useMediaUrl,
+  useVideoProps
+};

package/dist/{chunk-JZYKPLI4.js → chunk-RDVBE3G3.js}

@@ -175,11 +175,30 @@ var mediaPickerLabels = {
   removed: (name) => `${name} se quit\xF3.`,
   cleared: "Se limpi\xF3 la selecci\xF3n."
 };
+var videoPlayerLabels = {
+  player: "Reproductor de video",
+  controls: "Controles del video",
+  play: "Reproducir",
+  pause: "Pausar",
+  seek: "Posici\xF3n del video",
+  mute: "Silenciar",
+  unmute: "Activar el sonido",
+  volume: "Volumen",
+  captions: "Subt\xEDtulos",
+  captionsOff: "Desactivados",
+  quality: "Calidad del video",
+  qualityAuto: "Autom\xE1tica",
+  speed: "Velocidad de reproducci\xF3n",
+  speedNormal: "Normal",
+  fullscreen: "Pantalla completa",
+  exitFullscreen: "Salir de pantalla completa"
+};
 
 export {
   devulturErrorLabels,
   previewLabels,
   attachmentLabels,
   mediaLibraryLabels,
-  mediaPickerLabels
+  mediaPickerLabels,
+  videoPlayerLabels
 };

package/dist/component/http.js

@@ -1,7 +1,7 @@
 import { isBearerOf } from "@devultur/core";
 import { httpRouter } from "convex/server";
-import { internal } from "./_generated/api";
-import { env, httpAction } from "./_generated/server";
+import { internal } from "./_generated/api.js";
+import { env, httpAction } from "./_generated/server.js";
 const http = httpRouter();
 http.route({
     path: "/webhook",

package/dist/component/library.d.ts

@@ -1,6 +1,6 @@
 import { type PaginationOptions, type PaginationResult } from "convex/server";
-import type { Doc } from "./_generated/dataModel";
-import type { QueryCtx } from "./_generated/server";
+import type { Doc } from "./_generated/dataModel.js";
+import type { QueryCtx } from "./_generated/server.js";
 type MediaType = Doc<"media">["type"];
 export declare const BACKFILL_BATCH_SIZE: {
     readonly default: 100;

package/dist/component/library.js

@@ -2,9 +2,9 @@
 // records from before 1.4.0 the `searchText` they were written without.
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
-import { internal } from "./_generated/api";
-import { internalMutation, mutation, query } from "./_generated/server";
-import { missingSearchText } from "./mediaMeta";
+import { internal } from "./_generated/api.js";
+import { internalMutation, mutation, query } from "./_generated/server.js";
+import { missingSearchText } from "./mediaMeta.js";
 const mediaType = v.union(v.literal("video"), v.literal("image"), v.literal("file"));
 /** Longest search kept: Convex matches at most 16 terms, so a longer query only costs. */
 const SEARCH_MAX_LENGTH = 200;

package/dist/component/lock.js

@@ -5,9 +5,9 @@
 // `lock_privilege_required`, `lock_conflict`, ...); see workerErrors.ts.
 import { HOLD_PAGE_SIZE } from "@devultur/core";
 import { v } from "convex/values";
-import { derivativesValidator, retentionModeValidator } from "./lockValidators";
-import { getMediaClient } from "./mediaClient";
-import { workerAction } from "./workerErrors";
+import { derivativesValidator, retentionModeValidator } from "./lockValidators.js";
+import { getMediaClient } from "./mediaClient.js";
+import { workerAction } from "./workerErrors.js";
 const keysValidator = v.array(v.string());
 export const getLock = workerAction({
     args: { key: v.string() },

package/dist/component/mediaClient.js

@@ -1,6 +1,6 @@
 // The component's client of the media Worker, from the env the app mounts the component with.
 import { createWorkerClient } from "@devultur/core";
-import { env } from "./_generated/server";
+import { env } from "./_generated/server.js";
 export function getMediaClient() {
     return createWorkerClient(env.DEVULTUR_SECRET, env.DEVULTUR_API_URL);
 }

package/dist/component/metadata.js

@@ -1,8 +1,8 @@
 // Editing a media record's descriptive metadata (title, alt text, tags). The upload's own facts (size, dimensions,
 // duration, page count) are recorded by `uploads.ts` and the transcode webhook, never edited here.
 import { v } from "convex/values";
-import { mutation } from "./_generated/server";
-import { mediaMetaPatch, searchTextOf } from "./mediaMeta";
+import { mutation } from "./_generated/server.js";
+import { mediaMetaPatch, searchTextOf } from "./mediaMeta.js";
 /**
  * Sets a record's `title`, `alt` and/or `tags` (only the ones passed). Trimmed; an empty title or alt clears it, and
  * tags are deduplicated. Throws `invalid_media_metadata` past the limits (title 200, alt 1000, 20 tags of 50). Returns

package/dist/component/public.js

@@ -1,15 +1,15 @@
 import { DEFAULT_TOKEN_EXPIRY_SECONDS, extractId, MediaEventName, MediaStatus } from "@devultur/core";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
-import { api, internal } from "./_generated/api";
-import { internalMutation, mutation, query } from "./_generated/server";
-import { listNewestFirst } from "./library";
-import { objectLockValidator } from "./lockValidators";
-import { getMediaClient } from "./mediaClient";
-import { missingSearchText, searchTextOf } from "./mediaMeta";
-import { transcodeOutputFields } from "./schema";
-import { UPLOAD_CONFIRM_BACKSTOP_MS } from "./uploads";
-import { workerAction } from "./workerErrors";
+import { api, internal } from "./_generated/api.js";
+import { internalMutation, mutation, query } from "./_generated/server.js";
+import { listNewestFirst } from "./library.js";
+import { objectLockValidator } from "./lockValidators.js";
+import { getMediaClient } from "./mediaClient.js";
+import { missingSearchText, searchTextOf } from "./mediaMeta.js";
+import { transcodeOutputFields } from "./schema.js";
+import { UPLOAD_CONFIRM_BACKSTOP_MS } from "./uploads.js";
+import { workerAction } from "./workerErrors.js";
 // Webhook path RELATIVE to the component. Convex gives the component a `CONVEX_SITE_URL` that ALREADY
 // includes its mount prefix (e.g. `${site}/devultur`), so `${CONVEX_SITE_URL}/webhook` resolves to the
 // mounted route (`${site}/devultur/webhook`) without duplicating the prefix. Do NOT add `/devultur/` here

package/dist/component/uploads.js

@@ -1,11 +1,11 @@
 import { extractId, sanitizeFilename } from "@devultur/core";
 import { ConvexError, v } from "convex/values";
-import { internal } from "./_generated/api";
-import { internalAction, internalMutation } from "./_generated/server";
-import { getMediaClient } from "./mediaClient";
-import { searchTextOf, validUploadHints } from "./mediaMeta";
-import { parseUploadKey } from "./uploadKeys";
-import { workerAction } from "./workerErrors";
+import { internal } from "./_generated/api.js";
+import { internalAction, internalMutation } from "./_generated/server.js";
+import { getMediaClient } from "./mediaClient.js";
+import { searchTextOf, validUploadHints } from "./mediaMeta.js";
+import { parseUploadKey } from "./uploadKeys.js";
+import { workerAction } from "./workerErrors.js";
 // Past the Worker's longest upload window (a multipart upload can run for 24 hours), so the scheduled check never runs
 // while the bytes are still on their way.
 export const UPLOAD_CONFIRM_BACKSTOP_MS = 25 * 60 * 60 * 1000;

package/dist/component/workerErrors.d.ts

@@ -1,5 +1,5 @@
 import { type Value } from "convex/values";
-import { action } from "./_generated/server";
+import { action } from "./_generated/server.js";
 /** `data` of the `ConvexError` a component action throws when the Worker refuses a request. */
 export interface DevulturErrorData {
     /** The Worker's stable code (`retention_active`, `file_too_large`, ...), or `worker_error` when it sent none. */

package/dist/component/workerErrors.js

@@ -4,7 +4,7 @@
 // (`retention_active`, `lock_conflict`, `compliance_extend_only`, ...) and `error.data.details`.
 import { DevulturApiError } from "@devultur/core";
 import { ConvexError } from "convex/values";
-import { action } from "./_generated/server";
+import { action } from "./_generated/server.js";
 function isApiError(error) {
     if (error instanceof DevulturApiError)
         return true;

package/dist/hooks-uqpBd5UF.d.ts

@@ -0,0 +1,171 @@
+import React from 'react';
+import { DevulturMedia, MediaUrlOptions, Visibility } from '@devultur/core';
+import { UploadProgress } from '@devultur/react';
+import { FunctionReference } from 'convex/server';
+import { Value } from 'convex/values';
+
+/** What a viewer token action returns: the token with its lifetime, or the bare token (default lifetime). */
+type ViewerTokenResult = {
+    token: string;
+    expiresIn: number;
+} | string;
+/** Extra arguments sent with `sessionSecret` to the viewer token action. */
+type ViewerTokenArgs = Record<string, Value>;
+/**
+ * Where the viewer token for the current `tokenArgs` stands: not requested yet, being issued (no token yet), held, or
+ * failed (the action threw or returned no token). A renewal in flight, or one that failed, keeps `"ready"`.
+ */
+type TokenStatus = "idle" | "loading" | "ready" | "error";
+
+/** Transform/delivery options for media URLs (without `token`, which the context injects). */
+type MediaRenderOptions = Omit<MediaUrlOptions, "token">;
+/**
+ * The viewer token action: the component's `issueViewerToken` (as `defineDevulturFunctions` or `exposeApi` export it,
+ * where `sessionSecret` is optional) or an app's own, which may require it. The providers always send it.
+ */
+type ViewerTokenAction = FunctionReference<"action", "public", {
+    sessionSecret?: string;
+}>;
+interface MediaSession {
+    token: string | null;
+    /** Where the viewer token stands; `"error"` makes private previews fail fast with `token_unavailable`. */
+    tokenStatus: TokenStatus;
+    /** Why the last issuance failed (the action threw or returned no token), while `tokenStatus` is `"error"`. */
+    tokenError: Error | null;
+    /** Issues the viewer token again (after a failure, for example). Resolves to the new token, or `null`. */
+    retryToken: () => Promise<string | null>;
+    /**
+     * Asks for the viewer token where it's issued lazily (`<DevulturViewerProvider lazyToken>`): the first private media
+     * shown calls it, and so must code that reads `token` itself. A no-op once asked, and where the token is issued
+     * right away (the default).
+     */
+    requestToken: () => void;
+    baseUrl: string | null;
+    /** Browser session secret → sent in `${SESSION_HEADER}` on every private delivery. */
+    sessionSecret: string;
+    /** Delivery URL from a reference (non-hook → usable in handlers and `.map`). Token-transparent. */
+    url: (media: DevulturMedia, options?: MediaRenderOptions) => string;
+    /** Downloads a video's subtitle text for a locale (auth-transparent). */
+    getCaptionsText: (media: DevulturMedia, locale: string) => Promise<string>;
+    /**
+     * Re-issues the viewer token (new session fingerprint with the current UA/IP) and updates the context.
+     * Single-flight: concurrent calls share the same issuance. Returns the new token (or null if it
+     * failed). The render uses it to transparently recover from a 401 `session_mismatch`.
+     */
+    reissueToken: () => Promise<string | null>;
+}
+
+type AnyAction = FunctionReference<"action">;
+type AnyMutation = FunctionReference<"mutation">;
+type AnyQuery = FunctionReference<"query">;
+interface DevulturApi {
+    issueViewerToken: AnyAction;
+    createUploadUrl: AnyAction;
+    /** Records an upload in the component after its PUT, so it shows in `listMedia`. Optional (uploads still work). */
+    confirmUpload?: AnyAction;
+    deleteMedia: AnyAction;
+    /** Deletes the full folder of a video (raw/hls/thumbnails/captions). Required to delete videos. */
+    deleteVideo?: AnyAction;
+    /** Requests the transcode of an uploaded video. Required by `useMediaUpload` for auto-process. */
+    processVideo?: AnyAction;
+    getMedia?: AnyQuery;
+    /** The library, newest first. Required by `useMediaLibrary` and `<MediaLibrary>`. */
+    listMediaPage?: AnyQuery;
+    /** The library matching a search. Required by `useMediaLibrary` and `<MediaLibrary>` to search. */
+    searchMedia?: AnyQuery;
+    saveProgress?: AnyMutation;
+    loadProgress?: AnyQuery;
+    markComplete?: AnyMutation;
+    resetProgress?: AnyMutation;
+}
+interface UploadOptions {
+    /**
+     * Visibility override for this resource. Omitted → `config.upload.visibility` on your server, else the Worker's
+     * default by type. Your guard can still rewrite it.
+     */
+    visibility?: Visibility;
+    /** Progress of the PUT: bytes sent, total bytes and their fraction (0 to 1). */
+    onProgress?: (progress: UploadProgress) => void;
+    /** Aborts the PUT → `upload()` rejects with an `AbortError`. */
+    signal?: AbortSignal;
+    /** A PDF's page count to record with it, a hint (`countPdfPages` from `@devultur/convex/pdfjs` counts it). */
+    pageCount?: number;
+}
+/**
+ * The reference `upload()` resolves to: a `DevulturMedia` whose `key` is always set (the uploaded object's key; a
+ * video's raw file, what `processVideo` takes). It stores as-is in a `dv.media()` field.
+ */
+type UploadedMedia = DevulturMedia & {
+    readonly key: string;
+};
+/**
+ * What `useDevultur()` returns. Under a `<DevulturViewerProvider>`, `uploadUrl`, `upload` and `deleteMedia` throw a
+ * `DevulturCapabilityError` (`capability_unavailable`).
+ */
+interface DevulturContextValue extends MediaSession {
+    uploadUrl: (file: File) => Promise<{
+        url: string;
+        key: string;
+    }>;
+    /** Uploads a file (reporting progress), records it in the component, and returns the reference ready to save. */
+    upload: (file: File, options?: UploadOptions) => Promise<UploadedMedia>;
+    /** Deletes a media by reference: video → full folder; image/file → the object. */
+    deleteMedia: (media: DevulturMedia) => void;
+}
+declare const DevulturContext: React.Context<DevulturContextValue | null>;
+declare const DevulturApiContext: React.Context<DevulturApi | null>;
+declare function useDevultur(): DevulturContextValue;
+/**
+ * `useDevultur()` for components that also render outside a provider: the same value under `<DevulturProvider>` or
+ * `<DevulturViewerProvider>`, and `null` outside both instead of throwing.
+ */
+declare function useDevulturOptional(): DevulturContextValue | null;
+/**
+ * The `api` passed to `<DevulturProvider>`: your app's exported Devultur functions. Under a `<DevulturViewerProvider>`
+ * it throws a `DevulturCapabilityError`.
+ */
+declare function useDevulturApi(): DevulturApi;
+
+/**
+ * Ready-to-use delivery URL for a key, with the context's viewer token already injected. The consumer
+ * never touches the token or the query — it only declares what it wants (download, resize, etc.).
+ *
+ * @example
+ * <img src={useMediaUrl(key)} />
+ * <a href={useMediaUrl(key, { download: true })} download>Download</a>
+ * <img src={useMediaUrl(key, { width: 512, format: "webp" })} />
+ */
+declare function useMediaUrl(key: string | null | undefined, options?: MediaRenderOptions): string | null;
+interface VideoProps {
+    src: string;
+    token: string | undefined;
+    captions: {
+        locale: string;
+        label: string;
+        src: string;
+    }[];
+    /** Session secret → `<VideoPlayer>` sends it in `${SESSION_HEADER}` on hls.js/captions requests. */
+    sessionSecret?: string;
+}
+/**
+ * Token-transparent props for `<VideoPlayer>` from a video reference: builds the HLS playlist `src`,
+ * the viewer `token` (only if private), and the `captions` for the requested locales.
+ * The consumer just does `<VideoPlayer {...useVideoProps(lesson.video, { locales })} />`.
+ */
+declare function useVideoProps(media: DevulturMedia | null | undefined, options?: {
+    locales?: string[];
+}): VideoProps | null;
+
+interface DevulturProgressContextValue {
+    save: (videoId: string, position: number) => Promise<void>;
+    load: (videoId: string) => Promise<{
+        lastPosition: number;
+        completedAt: Date | null;
+    } | null>;
+    markComplete: (videoId: string) => Promise<void>;
+    reset: (videoId: string) => Promise<void>;
+}
+declare const DevulturProgressContext: React.Context<DevulturProgressContextValue | null>;
+declare function useDevulturProgress(): DevulturProgressContextValue;
+
+export { type DevulturApi as D, type TokenStatus as T, type UploadOptions as U, type VideoProps as V, type ViewerTokenAction as a, type ViewerTokenArgs as b, DevulturApiContext as c, DevulturContext as d, type DevulturContextValue as e, DevulturProgressContext as f, type DevulturProgressContextValue as g, type UploadedMedia as h, type ViewerTokenResult as i, useDevulturApi as j, useDevulturOptional as k, useDevulturProgress as l, useMediaUrl as m, useVideoProps as n, useDevultur as u };