@devultur/convex 1.3.1 → 1.3.2

package/README.md

@@ -86,6 +86,42 @@ The PUT goes through `XMLHttpRequest` (`fetch` reports no upload progress), in p
 optional field of `DevulturMedia` and of `dv.media()`. It is informational: delivery URLs are derived from `id`,
 `kind`, `visibility` and `filename`.
 
+## Multiple workspaces
+
+An app that shows private media from several workspaces (an admin console that previews each one, for example) can
+send extra arguments with every viewer token request. Pass them in `tokenArgs`, and pass your own action in
+`issueViewerToken`: the component's `issueViewerToken` accepts only `sessionSecret`.
+
+```typescript
+// convex/admin.ts
+import { v } from "convex/values";
+import { components } from "./_generated/api";
+import { action } from "./_generated/server";
+
+export const issueWorkspaceViewerToken = action({
+  args: { sessionSecret: v.string(), workspaceId: v.id("workspaces") },
+  handler: async (ctx, { sessionSecret, workspaceId }) => {
+    await assertWorkspaceAccess(ctx, workspaceId); // your own check
+    return ctx.runAction(components.devultur.public.issueViewerToken, { sessionSecret });
+  },
+});
+```
+
+```tsx
+<DevulturProvider
+  api={api.devultur}
+  issueViewerToken={api.admin.issueWorkspaceViewerToken}
+  tokenArgs={{ workspaceId }}
+>
+  <WorkspaceMedia />
+</DevulturProvider>
+```
+
+The provider sends `{ sessionSecret, ...tokenArgs }` on the first issuance, on each renewal and on each re-issue.
+`tokenArgs` are compared by value, so a new object with the same values changes nothing. When they change, the
+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.
+
 ## Media library
 
 Every upload, whatever its kind, gets a record in the component's `media` table once its bytes are stored, so

package/dist/react.d.ts

@@ -3,9 +3,18 @@ import { Visibility, DevulturMedia, MediaUrlOptions, ProcessingPhase, FailureRea
 import { BakeOutputFormat, MediaUploadState, MediaUploadError, UploadProgress } from '@devultur/react';
 export { MediaUploadError, MediaUploadState, UploadProgress } from '@devultur/react';
 import { FunctionReference } from 'convex/server';
+import { Value } from 'convex/values';
 import { a as PdfjsLoader } from './pdf-render-CiCK6V1X.js';
 export { P as PdfjsModule } from './pdf-render-CiCK6V1X.js';
 
+/** 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>;
+
 interface CropUploadRenderProps {
     /** The state machine of the full cycle (idle → uploading → ready / failed). */
     state: MediaUploadState;
@@ -304,9 +313,23 @@ interface DevulturProviderProps {
     api: DevulturApi;
     /** Media worker base (e.g. `https://media.your-domain.com`). Required for `useMediaUrl`. */
     baseUrl?: string;
+    /**
+     * Extra arguments sent with `sessionSecret` on every viewer token issuance (first, renewal and re-issue), for
+     * example `{ workspaceId }`. Compared by value: when they change, the current token is dropped and a new one is
+     * issued. The component's own `issueViewerToken` accepts only `sessionSecret`, so pass your own action in
+     * `issueViewerToken` that takes these arguments.
+     */
+    tokenArgs?: ViewerTokenArgs;
+    /**
+     * Your own viewer token action, used instead of `api.issueViewerToken`. It receives `{ sessionSecret, ...tokenArgs }`
+     * and returns what the component's `issueViewerToken` returns.
+     */
+    issueViewerToken?: FunctionReference<"action", "public", {
+        sessionSecret: string;
+    }>;
     children: React.ReactNode;
 }
-declare function DevulturProvider({ api, baseUrl, children }: DevulturProviderProps): React.JSX.Element;
+declare function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children }: DevulturProviderProps): React.JSX.Element;
 declare function useDevultur(): DevulturContextValue;
 declare function useDevulturProgress(): ProgressContextValue;
 /**
@@ -471,4 +494,4 @@ interface UseMediaUploadReturn {
  */
 declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
 
-export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, MediaFetchError, type MediaFetchErrorCode, type MediaObjectUrl, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewLabels, type PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, defaultPreviewLabels, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };
+export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, MediaFetchError, type MediaFetchErrorCode, type MediaObjectUrl, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewLabels, type PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, type ViewerTokenArgs, type ViewerTokenResult, defaultPreviewLabels, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };

package/dist/react.js

@@ -1,11 +1,10 @@
 "use client";
 
 // src/react.tsx
-import React7 from "react";
+import React8 from "react";
 import {
   buildMediaUrl,
   CaptionLocaleLabel,
-  DEFAULT_TOKEN_EXPIRY_SECONDS,
   MediaStatus,
   mediaCaptionPath,
   mediaPath as mediaPath2,
@@ -214,8 +213,76 @@ function deriveUploadState(local, videoState, retry) {
   }
 }
 
-// src/crop-upload.tsx
+// src/viewer-token.ts
 import React from "react";
+import { DEFAULT_TOKEN_EXPIRY_SECONDS } from "@devultur/core";
+import { convexToJson } from "convex/values";
+var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
+var MIN_REFRESH_MS = 6e4;
+var DEFAULT_TTL_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
+function extractTokenResult(result) {
+  const tokenValue = typeof result === "string" ? result : result.token;
+  const ttlMs = typeof result === "string" ? DEFAULT_TTL_MS : result.expiresIn * 1e3;
+  return { tokenValue, ttlMs };
+}
+function sortKeys(json) {
+  if (Array.isArray(json)) return json.map(sortKeys);
+  if (json === null || typeof json !== "object") return json;
+  return Object.fromEntries(
+    Object.keys(json).sort().map((name) => [name, sortKeys(json[name])])
+  );
+}
+function tokenArgsKey(tokenArgs) {
+  return JSON.stringify(sortKeys(convexToJson(tokenArgs ?? {})));
+}
+function useViewerToken({ issueViewerToken, sessionSecret, tokenArgs }) {
+  const argsKey = tokenArgsKey(tokenArgs);
+  const stableArgs = React.useMemo(() => tokenArgs ?? {}, [argsKey]);
+  const [issued, setIssued] = React.useState(null);
+  const token = issued?.argsKey === argsKey ? issued.token : null;
+  const currentArgsKeyRef = React.useRef(argsKey);
+  const refreshTimerRef = React.useRef(null);
+  const inFlightRef = React.useRef(null);
+  React.useEffect(() => {
+    currentArgsKeyRef.current = argsKey;
+  }, [argsKey]);
+  React.useEffect(() => {
+    return () => {
+      if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+    };
+  }, []);
+  const request = React.useCallback(() => {
+    const renew = () => void request();
+    return issueViewerToken({ ...stableArgs, sessionSecret }).then((result) => {
+      if (currentArgsKeyRef.current !== argsKey) return null;
+      const { tokenValue, ttlMs } = extractTokenResult(result);
+      setIssued({ token: tokenValue, argsKey });
+      if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+      refreshTimerRef.current = setTimeout(renew, Math.max(ttlMs - REFRESH_BUFFER_MS, MIN_REFRESH_MS));
+      return tokenValue;
+    });
+  }, [issueViewerToken, stableArgs, argsKey, sessionSecret]);
+  const issueOnce = React.useCallback(() => {
+    const inFlight = inFlightRef.current;
+    if (inFlight?.argsKey === argsKey) return inFlight.promise;
+    const promise = request();
+    const settle = () => {
+      if (inFlightRef.current?.promise === promise) inFlightRef.current = null;
+    };
+    promise.then(settle, settle);
+    inFlightRef.current = { argsKey, promise };
+    return promise;
+  }, [request, argsKey]);
+  React.useEffect(() => {
+    if (token) return;
+    issueOnce();
+  }, [token, issueOnce]);
+  const reissueToken = React.useCallback(() => issueOnce().catch(() => null), [issueOnce]);
+  return { token, reissueToken };
+}
+
+// src/crop-upload.tsx
+import React2 from "react";
 import { ImageCropper } from "@devultur/react";
 import { jsx, jsxs } from "react/jsx-runtime";
 var DEFAULT_LABELS = {
@@ -239,18 +306,18 @@ function CropUpload({
   children
 }) {
   const text = { ...DEFAULT_LABELS, ...labels };
-  const [pendingFile, setPendingFile] = React.useState(null);
-  const inputRef = React.useRef(null);
+  const [pendingFile, setPendingFile] = React2.useState(null);
+  const inputRef = React2.useRef(null);
   const { upload, state, cancel, reset } = useMediaUpload({ visibility, replaces, onComplete });
-  const pickFile = React.useCallback(() => inputRef.current?.click(), []);
-  const handleCrop = React.useCallback(
+  const pickFile = React2.useCallback(() => inputRef.current?.click(), []);
+  const handleCrop = React2.useCallback(
     (baked) => {
       setPendingFile(null);
       upload(baked);
     },
     [upload]
   );
-  const resetAll = React.useCallback(() => {
+  const resetAll = React2.useCallback(() => {
     setPendingFile(null);
     reset();
   }, [reset]);
@@ -303,7 +370,7 @@ function CropUpload({
 }
 
 // src/media-resource.ts
-import React2 from "react";
+import React3 from "react";
 import { mediaPath, mediaUrl } from "@devultur/core";
 var IDLE = { value: null, contentType: null, isLoading: false, error: null };
 var LOADING = { value: null, contentType: null, isLoading: true, error: null };
@@ -313,12 +380,12 @@ function useMediaResource(media, options) {
   const isPrivate = media?.visibility === "private";
   const isReady = !isPrivate || devultur.token !== null;
   const requestKey = media && isEnabled ? [devultur.baseUrl, media.visibility, mediaPath(media), contentType ?? "", maxBytes ?? ""].join("|") : null;
-  const [settled, setSettled] = React2.useState(null);
-  const inputsRef = React2.useRef({ media, devultur, options });
-  React2.useEffect(() => {
+  const [settled, setSettled] = React3.useState(null);
+  const inputsRef = React3.useRef({ media, devultur, options });
+  React3.useEffect(() => {
     inputsRef.current = { media, devultur, options };
   });
-  React2.useEffect(() => {
+  React3.useEffect(() => {
     if (!requestKey || !isReady) return;
     const { media: target, devultur: context, options: current } = inputsRef.current;
     if (!target || !context.baseUrl) return;
@@ -380,7 +447,7 @@ function useMediaObjectUrl(media, options) {
 }
 
 // src/pdf-context.tsx
-import React3 from "react";
+import React4 from "react";
 
 // src/preview-labels.ts
 var ERROR_TEXT = {
@@ -412,14 +479,14 @@ function mergePreviewLabels(...sources) {
 
 // src/pdf-context.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
-var PdfPreviewContext = React3.createContext({});
+var PdfPreviewContext = React4.createContext({});
 function PdfPreviewProvider({
   pdfjs,
   workerSrc,
   labels,
   children
 }) {
-  const config = React3.useMemo(() => ({ pdfjs, workerSrc, labels }), [pdfjs, workerSrc, labels]);
+  const config = React4.useMemo(() => ({ pdfjs, workerSrc, labels }), [pdfjs, workerSrc, labels]);
   return /* @__PURE__ */ jsx2(PdfPreviewContext.Provider, { value: config, children });
 }
 var loadedModules = /* @__PURE__ */ new WeakMap();
@@ -431,9 +498,9 @@ function loadOnce(loader) {
   return loading;
 }
 function usePdfjs(workerSrcOverride) {
-  const { pdfjs: loader, workerSrc } = React3.useContext(PdfPreviewContext);
-  const [loaded, setLoaded] = React3.useState(null);
-  React3.useEffect(() => {
+  const { pdfjs: loader, workerSrc } = React4.useContext(PdfPreviewContext);
+  const [loaded, setLoaded] = React4.useState(null);
+  React4.useEffect(() => {
     if (!loader) return;
     let isCurrent = true;
     loadOnce(loader).then((pdfjs) => {
@@ -449,15 +516,15 @@ function usePdfjs(workerSrcOverride) {
   return { status: "ready", pdfjs: loaded.pdfjs, workerSrc: workerSrcOverride ?? workerSrc };
 }
 function usePreviewLabels(labels) {
-  const providerLabels = React3.useContext(PdfPreviewContext).labels;
+  const providerLabels = React4.useContext(PdfPreviewContext).labels;
   return mergePreviewLabels(providerLabels, labels);
 }
 
 // src/pdf-thumbnail.tsx
-import React6 from "react";
+import React7 from "react";
 
 // src/pdf-hooks.ts
-import React4 from "react";
+import React5 from "react";
 
 // src/pdf-render.ts
 var MOBILE_MAX_CANVAS_PIXELS = 5242880;
@@ -501,8 +568,8 @@ var isRenderCancelled = (error) => error instanceof Error && error.name === "Ren
 
 // src/pdf-hooks.ts
 function useIsVisible(ref, rootMargin = "200px") {
-  const [isVisible, setIsVisible] = React4.useState(false);
-  React4.useEffect(() => {
+  const [isVisible, setIsVisible] = React5.useState(false);
+  React5.useEffect(() => {
     const element = ref.current;
     if (isVisible || !element) return;
     if (typeof IntersectionObserver === "undefined") {
@@ -523,12 +590,12 @@ function useIsVisible(ref, rootMargin = "200px") {
   return isVisible;
 }
 function usePdfDocument({ pdfjs, bytes, workerSrc }) {
-  const [state, setState] = React4.useState({
+  const [state, setState] = React5.useState({
     bytes: null,
     document: null,
     error: null
   });
-  React4.useEffect(() => {
+  React5.useEffect(() => {
     let isCurrent = true;
     const loadingTask = openPdf(pdfjs, bytes, workerSrc);
     loadingTask.promise.then((document2) => {
@@ -547,8 +614,8 @@ function usePdfDocument({ pdfjs, bytes, workerSrc }) {
 }
 function usePageRender(options) {
   const { document: document2, pageNumber, canvasRef, width, isEnabled, shouldExtractText = false } = options;
-  const [state, setState] = React4.useState({ isRendered: false, text: "" });
-  React4.useEffect(() => {
+  const [state, setState] = React5.useState({ isRendered: false, text: "" });
+  React5.useEffect(() => {
     const canvas = canvasRef.current;
     if (!document2 || !isEnabled || !canvas) return;
     let isCurrent = true;
@@ -578,7 +645,7 @@ function usePageRender(options) {
 }
 
 // src/pdf-preview.tsx
-import React5 from "react";
+import React6 from "react";
 import { Fragment, jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
 var VISUALLY_HIDDEN = {
   position: "absolute",
@@ -624,9 +691,9 @@ function PdfPreview(props) {
 function PdfCanvasDocument(props) {
   const { pdfjs, workerSrc, bytes, label, className, renderFallback, loading, labels, maxPages } = props;
   const { document: document2, error } = usePdfDocument({ pdfjs, bytes, workerSrc });
-  const containerRef = React5.useRef(null);
-  const [width, setWidth] = React5.useState(null);
-  React5.useLayoutEffect(() => {
+  const containerRef = React6.useRef(null);
+  const [width, setWidth] = React6.useState(null);
+  React6.useLayoutEffect(() => {
     if (document2) setWidth(containerRef.current?.clientWidth ?? 0);
   }, [document2]);
   if (error) return /* @__PURE__ */ jsx3(Fragment, { children: renderFallback(error) });
@@ -662,8 +729,8 @@ function PdfCanvasDocument(props) {
   );
 }
 function PdfPageView({ document: document2, pageNumber, width, label }) {
-  const pageRef = React5.useRef(null);
-  const canvasRef = React5.useRef(null);
+  const pageRef = React6.useRef(null);
+  const canvasRef = React6.useRef(null);
   const isVisible = useIsVisible(pageRef);
   const { isRendered, text } = usePageRender({
     document: document2,
@@ -680,8 +747,8 @@ function PdfPageView({ document: document2, pageNumber, width, label }) {
   ] });
 }
 function PdfFrame({ bytes, label, className }) {
-  const [objectUrl, setObjectUrl] = React5.useState(null);
-  React5.useEffect(() => {
+  const [objectUrl, setObjectUrl] = React6.useState(null);
+  React6.useEffect(() => {
     const url = URL.createObjectURL(new Blob([bytes], { type: "application/pdf" }));
     setObjectUrl(url);
     return () => URL.revokeObjectURL(url);
@@ -696,7 +763,7 @@ var DEFAULT_THUMBNAIL_WIDTH = 96;
 var DEFAULT_THUMBNAIL_MAX_BYTES = 50 * 1024 * 1024;
 function PdfThumbnail(props) {
   const { media, contentType, width = DEFAULT_THUMBNAIL_WIDTH, fallback = null, loading = null } = props;
-  const containerRef = React6.useRef(null);
+  const containerRef = React7.useRef(null);
   const isVisible = useIsVisible(containerRef);
   const pdfjsState = usePdfjs(props.pdfWorkerSrc);
   const labels = usePreviewLabels(props.labels);
@@ -729,7 +796,7 @@ function PdfThumbnail(props) {
   return /* @__PURE__ */ jsx4("div", { ref: containerRef, className: props.className, style: { width }, children: content() });
 }
 function ThumbnailCanvas({ pdfjs, workerSrc, bytes, width, label, fallback, loading }) {
-  const canvasRef = React6.useRef(null);
+  const canvasRef = React7.useRef(null);
   const { document: document2, error } = usePdfDocument({ pdfjs, bytes, workerSrc });
   const { isRendered } = usePageRender({ document: document2, pageNumber: 1, canvasRef, width, isEnabled: true });
   if (error) return /* @__PURE__ */ jsx4(Fragment2, { children: fallback });
@@ -821,77 +888,29 @@ function TextPreview({
 
 // src/react.tsx
 import { Fragment as Fragment4, jsx as jsx6 } from "react/jsx-runtime";
-var DevulturContext = React7.createContext(null);
-var DevulturApiContext = React7.createContext(null);
-var ProgressContext = React7.createContext(null);
-var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
-var MIN_REFRESH_MS = 6e4;
-var DEFAULT_TTL_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
-function extractTokenResult(result) {
-  const tokenValue = typeof result === "string" ? result : result.token;
-  const ttlMs = typeof result === "string" ? DEFAULT_TTL_MS : result.expiresIn * 1e3;
-  return { tokenValue, ttlMs };
-}
-function DevulturProvider({ api, baseUrl, children }) {
-  const [token, setToken] = React7.useState(null);
-  const [sessionSecret] = React7.useState(() => typeof crypto !== "undefined" ? crypto.randomUUID() : "");
-  const issueViewerToken = useAction(api.issueViewerToken);
+var DevulturContext = React8.createContext(null);
+var DevulturApiContext = React8.createContext(null);
+var ProgressContext = React8.createContext(null);
+function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children }) {
+  const [sessionSecret] = React8.useState(() => typeof crypto !== "undefined" ? crypto.randomUUID() : "");
+  const issueViewerTokenAction = useAction(issueViewerToken ?? api.issueViewerToken);
+  const { token, reissueToken } = useViewerToken({
+    issueViewerToken: issueViewerTokenAction,
+    sessionSecret,
+    tokenArgs
+  });
   const createUploadUrlAction = useAction(api.createUploadUrl);
   const deleteMediaAction = useAction(api.deleteMedia);
   const confirmUploadAction = useAction(api.confirmUpload ?? api.createUploadUrl);
   const deleteVideoAction = useAction(api.deleteVideo ?? api.deleteMedia);
-  const refreshTimerRef = React7.useRef(null);
-  const reissueInFlightRef = React7.useRef(null);
-  const scheduleRefresh = React7.useCallback(
-    (ttlMs) => {
-      if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
-      const refreshIn = Math.max(ttlMs - REFRESH_BUFFER_MS, MIN_REFRESH_MS);
-      refreshTimerRef.current = setTimeout(() => {
-        issueViewerToken({ sessionSecret }).then((result) => {
-          const { tokenValue, ttlMs: nextTtl } = extractTokenResult(result);
-          setToken(tokenValue);
-          scheduleRefresh(nextTtl);
-        });
-      }, refreshIn);
-    },
-    [issueViewerToken, sessionSecret]
-  );
-  React7.useEffect(() => {
-    if (token) return;
-    issueViewerToken({ sessionSecret }).then((result) => {
-      const { tokenValue, ttlMs } = extractTokenResult(result);
-      setToken(tokenValue);
-      scheduleRefresh(ttlMs);
-    });
-  }, [token, issueViewerToken, scheduleRefresh, sessionSecret]);
-  const reissueToken = React7.useCallback(() => {
-    if (reissueInFlightRef.current) return reissueInFlightRef.current;
-    const pending = issueViewerToken({ sessionSecret }).then((result) => {
-      const { tokenValue, ttlMs } = extractTokenResult(result);
-      setToken(tokenValue);
-      scheduleRefresh(ttlMs);
-      reissueInFlightRef.current = null;
-      return tokenValue;
-    }).catch(() => {
-      reissueInFlightRef.current = null;
-      return null;
-    });
-    reissueInFlightRef.current = pending;
-    return pending;
-  }, [issueViewerToken, scheduleRefresh, sessionSecret]);
-  React7.useEffect(() => {
-    return () => {
-      if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
-    };
-  }, []);
-  const uploadUrl = React7.useCallback(
+  const uploadUrl = React8.useCallback(
     async (file) => {
       const result = await createUploadUrlAction({ filename: file.name, contentType: file.type });
       return { url: result.url, key: result.key };
     },
     [createUploadUrlAction]
   );
-  const upload = React7.useCallback(
+  const upload = React8.useCallback(
     async (file, options) => {
       const dimensions = await readImageDimensions(file);
       const target = await createUploadUrlAction({
@@ -912,14 +931,14 @@ function DevulturProvider({ api, baseUrl, children }) {
     },
     [createUploadUrlAction, confirmUploadAction, api.confirmUpload]
   );
-  const url = React7.useCallback(
+  const url = React8.useCallback(
     (media, options) => {
       if (!baseUrl) throw new Error("Devultur `url()` requires `baseUrl` on <DevulturProvider>");
       return mediaUrl2(baseUrl, media, { ...options, token: token ?? void 0 });
     },
     [baseUrl, token]
   );
-  const getCaptionsText = React7.useCallback(
+  const getCaptionsText = React8.useCallback(
     async (media, locale) => {
       if (!baseUrl) throw new Error("Devultur `getCaptionsText()` requires `baseUrl` on <DevulturProvider>");
       const path = mediaCaptionPath(media, locale);
@@ -938,7 +957,7 @@ function DevulturProvider({ api, baseUrl, children }) {
     },
     [baseUrl, token, reissueToken, sessionSecret]
   );
-  const deleteMedia = React7.useCallback(
+  const deleteMedia = React8.useCallback(
     (media) => {
       if (media.kind === "video" && api.deleteVideo) {
         deleteVideoAction({ videoId: media.id, visibility: media.visibility }).catch(console.error);
@@ -948,7 +967,7 @@ function DevulturProvider({ api, baseUrl, children }) {
     },
     [deleteMediaAction, deleteVideoAction, api.deleteVideo]
   );
-  const devulturValue = React7.useMemo(
+  const devulturValue = React8.useMemo(
     () => ({
       token,
       baseUrl: baseUrl ?? null,
@@ -988,13 +1007,13 @@ function ProgressBridge({
   const saveMutation = useMutation(save);
   const markCompleteMutation = useMutation(markComplete);
   const resetMutation = useMutation(reset);
-  const onSave = React7.useCallback(
+  const onSave = React8.useCallback(
     async (videoId, position) => {
       await saveMutation({ videoId, position });
     },
     [saveMutation]
   );
-  const onLoad = React7.useCallback(
+  const onLoad = React8.useCallback(
     async (videoId) => {
       const result = await convex.query(load, { videoId });
       if (!result) return null;
@@ -1005,37 +1024,37 @@ function ProgressBridge({
     },
     [convex, load]
   );
-  const onMarkComplete = React7.useCallback(
+  const onMarkComplete = React8.useCallback(
     async (videoId) => {
       await markCompleteMutation({ videoId });
     },
     [markCompleteMutation]
   );
-  const onReset = React7.useCallback(
+  const onReset = React8.useCallback(
     async (videoId) => {
       await resetMutation({ videoId });
     },
     [resetMutation]
   );
-  const value = React7.useMemo(
+  const value = React8.useMemo(
     () => ({ save: onSave, load: onLoad, markComplete: onMarkComplete, reset: onReset }),
     [onSave, onLoad, onMarkComplete, onReset]
   );
   return /* @__PURE__ */ jsx6(ProgressContext, { value, children });
 }
 function useDevultur() {
-  const context = React7.use(DevulturContext);
+  const context = React8.use(DevulturContext);
   if (!context) throw new Error("useDevultur must be used within <DevulturProvider>");
   return context;
 }
 function useDevulturProgress() {
-  const context = React7.use(ProgressContext);
+  const context = React8.use(ProgressContext);
   if (!context) throw new Error("useDevulturProgress requires progress API in DevulturProvider");
   return context;
 }
 function useMediaUrl(key, options) {
   const { token, baseUrl } = useDevultur();
-  return React7.useMemo(() => {
+  return React8.useMemo(() => {
     if (!key) return null;
     if (!baseUrl) throw new Error("useMediaUrl requires `baseUrl` on <DevulturProvider>");
     const isPublic = visibilityFromKey(key) === "public";
@@ -1063,7 +1082,7 @@ async function readImageDimensions(file) {
 function useVideoProps(media, options) {
   const { token, baseUrl, sessionSecret } = useDevultur();
   const locales = options?.locales;
-  return React7.useMemo(() => {
+  return React8.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;
@@ -1095,19 +1114,19 @@ function Image({
   ...imgProps
 }) {
   const { url, token, baseUrl, reissueToken, sessionSecret } = useDevultur();
-  const [failed, setFailed] = React7.useState(false);
-  const [blobSrc, setBlobSrc] = React7.useState(null);
-  const sessionRef = React7.useRef({ token, reissueToken });
-  React7.useEffect(() => {
+  const [failed, setFailed] = React8.useState(false);
+  const [blobSrc, setBlobSrc] = React8.useState(null);
+  const sessionRef = React8.useRef({ token, reissueToken });
+  React8.useEffect(() => {
     sessionRef.current = { token, reissueToken };
   });
   const isPrivate = media?.visibility === "private";
   const hasToken = token !== null;
-  React7.useEffect(() => {
+  React8.useEffect(() => {
     setFailed(false);
     setBlobSrc(null);
   }, [media]);
-  React7.useEffect(() => {
+  React8.useEffect(() => {
     if (!isPrivate || failed || !media || !hasToken) return;
     let cancelled = false;
     let objectUrl = null;
@@ -1139,7 +1158,7 @@ function Image({
       if (objectUrl) URL.revokeObjectURL(objectUrl);
     };
   }, [isPrivate, failed, media, hasToken, baseUrl, sessionSecret, width, height, fit, format, quality]);
-  const handleError = React7.useCallback(() => setFailed(true), []);
+  const handleError = React8.useCallback(() => setFailed(true), []);
   let src;
   if (failed || !media) {
     src = externalFallback ?? null;
@@ -1150,7 +1169,7 @@ function Image({
   }
   if (!src) return /* @__PURE__ */ jsx6(Fragment4, { children: fallback });
   if (render) {
-    return React7.cloneElement(render, {
+    return React8.cloneElement(render, {
       style: { ...render.props.style, backgroundImage: `url("${src}")` }
     });
   }
@@ -1168,7 +1187,7 @@ function Image({
 }
 function DownloadLink({ media, filename, children, ...anchorProps }) {
   const { url, token, baseUrl, sessionSecret, reissueToken } = useDevultur();
-  const handleClick = React7.useCallback(
+  const handleClick = React8.useCallback(
     async (event) => {
       if (media?.visibility !== "private" || !baseUrl) return;
       event.preventDefault();
@@ -1192,7 +1211,7 @@ function DownloadLink({ media, filename, children, ...anchorProps }) {
   return /* @__PURE__ */ jsx6("a", { href: url(media, { download: filename ?? true }), download: true, ...anchorProps, onClick: handleClick, children });
 }
 function useDevulturMedia(key) {
-  const apiCtx = React7.use(DevulturApiContext);
+  const apiCtx = React8.use(DevulturApiContext);
   if (!apiCtx?.getMedia) {
     throw new Error("useDevulturMedia requires getMedia in DevulturProvider api");
   }
@@ -1249,7 +1268,7 @@ function useVideoState(media, options) {
   const { token, baseUrl, sessionSecret } = useDevultur();
   const status = useDevulturMedia(media?.kind === "video" ? media.id : null);
   const locales = options?.locales;
-  return React7.useMemo(() => {
+  return React8.useMemo(() => {
     if (media?.kind !== "video") return { phase: "idle" };
     if (status.isFailed) {
       return {
@@ -1293,23 +1312,23 @@ function useVideoState(media, options) {
 }
 function useMediaUpload(options) {
   const { visibility, onComplete, onError, replaces, process, locales } = options ?? {};
-  const api = React7.use(DevulturApiContext);
+  const api = React8.use(DevulturApiContext);
   if (!api) throw new Error("useMediaUpload must be used within <DevulturProvider>");
   const createUploadUrlAction = useAction(api.createUploadUrl);
   const deleteMediaAction = useAction(api.deleteMedia);
   const confirmUploadAction = useAction(api.confirmUpload ?? api.createUploadUrl);
   const processVideoAction = useAction(api.processVideo ?? api.createUploadUrl);
-  const [phase, setPhase] = React7.useState("idle");
-  const [percent, setPercent] = React7.useState(0);
-  const [currentFile, setCurrentFile] = React7.useState(null);
-  const [media, setMedia] = React7.useState(null);
-  const [uploadFailure, setUploadFailure] = React7.useState(null);
-  const [processRequested, setProcessRequested] = React7.useState(false);
-  const abortRef = React7.useRef(null);
-  const lastFileRef = React7.useRef(null);
-  const lastKeyRef = React7.useRef(null);
+  const [phase, setPhase] = React8.useState("idle");
+  const [percent, setPercent] = React8.useState(0);
+  const [currentFile, setCurrentFile] = React8.useState(null);
+  const [media, setMedia] = React8.useState(null);
+  const [uploadFailure, setUploadFailure] = React8.useState(null);
+  const [processRequested, setProcessRequested] = React8.useState(false);
+  const abortRef = React8.useRef(null);
+  const lastFileRef = React8.useRef(null);
+  const lastKeyRef = React8.useRef(null);
   const videoState = useVideoState(media, { locales });
-  const triggerProcess = React7.useCallback(
+  const triggerProcess = React8.useCallback(
     (key) => {
       if (!api.processVideo) {
         throw new Error("useMediaUpload: processing a video requires `processVideo` in the <DevulturProvider> api");
@@ -1322,7 +1341,7 @@ function useMediaUpload(options) {
     },
     [api.processVideo, processVideoAction]
   );
-  const runUpload = React7.useCallback(
+  const runUpload = React8.useCallback(
     async (file) => {
       const controller = new AbortController();
       abortRef.current = controller;
@@ -1393,10 +1412,10 @@ function useMediaUpload(options) {
       onError
     ]
   );
-  const cancel = React7.useCallback(() => {
+  const cancel = React8.useCallback(() => {
     abortRef.current?.abort();
   }, []);
-  const reset = React7.useCallback(() => {
+  const reset = React8.useCallback(() => {
     abortRef.current?.abort();
     setPhase("idle");
     setPercent(0);
@@ -1405,15 +1424,15 @@ function useMediaUpload(options) {
     setUploadFailure(null);
     setProcessRequested(false);
   }, []);
-  const retry = React7.useCallback(() => {
+  const retry = React8.useCallback(() => {
     if (phase === "upload-failed" && lastFileRef.current) {
       runUpload(lastFileRef.current);
       return;
     }
     if (lastKeyRef.current) triggerProcess(lastKeyRef.current);
   }, [phase, runUpload, triggerProcess]);
-  React7.useEffect(() => () => abortRef.current?.abort(), []);
-  const state = React7.useMemo(
+  React8.useEffect(() => () => abortRef.current?.abort(), []);
+  const state = React8.useMemo(
     () => deriveUploadState(
       { phase, percent, file: currentFile, failure: uploadFailure, media, processRequested },
       videoState,
@@ -1421,7 +1440,7 @@ function useMediaUpload(options) {
     ),
     [phase, percent, currentFile, uploadFailure, media, processRequested, videoState, retry]
   );
-  const upload = React7.useCallback((file) => runUpload(file), [runUpload]);
+  const upload = React8.useCallback((file) => runUpload(file), [runUpload]);
   return { upload, state, cancel, reset };
 }
 export {

package/dist/validators.d.ts

@@ -12,22 +12,22 @@ import { DevulturKind } from '@devultur/core';
  */
 declare const dv: {
     media(kind?: DevulturKind): convex_values.VObject<{
-        key?: string | undefined;
         filename?: string | undefined;
-        height?: number | undefined;
+        key?: string | undefined;
         width?: number | undefined;
-        visibility: "public" | "private";
+        height?: number | undefined;
         id: string;
         kind: DevulturKind;
+        visibility: "public" | "private";
     }, {
-        kind: convex_values.VLiteral<DevulturKind, "required"> | convex_values.VUnion<"video" | "image" | "file", [convex_values.VLiteral<"image", "required">, convex_values.VLiteral<"video", "required">, convex_values.VLiteral<"file", "required">], "required", never>;
+        kind: convex_values.VLiteral<DevulturKind, "required"> | convex_values.VUnion<"image" | "video" | "file", [convex_values.VLiteral<"image", "required">, convex_values.VLiteral<"video", "required">, convex_values.VLiteral<"file", "required">], "required", never>;
         id: convex_values.VString<string, "required">;
         visibility: convex_values.VUnion<"public" | "private", [convex_values.VLiteral<"public", "required">, convex_values.VLiteral<"private", "required">], "required", never>;
         filename: convex_values.VString<string | undefined, "optional">;
         key: convex_values.VString<string | undefined, "optional">;
         width: convex_values.VFloat64<number | undefined, "optional">;
         height: convex_values.VFloat64<number | undefined, "optional">;
-    }, "required", "key" | "filename" | "visibility" | "height" | "width" | "id" | "kind">;
+    }, "required", "id" | "kind" | "visibility" | "filename" | "key" | "width" | "height">;
 };
 
 export { dv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/convex",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Convex component for Devultur media: media records, uploads, transcodes, watch progress and React bindings",
   "keywords": [
     "convex",
@@ -55,8 +55,8 @@
     "dist"
   ],
   "dependencies": {
-    "@devultur/core": "1.3.1",
-    "@devultur/react": "1.3.1"
+    "@devultur/core": "1.3.2",
+    "@devultur/react": "1.3.2"
   },
   "peerDependencies": {
     "convex": ">=1.25.0",