@devultur/convex 1.0.2 → 1.1.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   dv
-} from "./chunk-FHWT3GD6.js";
+} from "./chunk-GKLFRSGI.js";
 
 // src/index.ts
 import {
@@ -17,7 +17,7 @@ import {
 
 // src/client.ts
 import { extractId } from "@devultur/core";
-import { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
+import { actionGeneric, mutationGeneric, paginationOptsValidator, queryGeneric } from "convex/server";
 import { v } from "convex/values";
 var Devultur = class {
   component;
@@ -33,10 +33,50 @@ var Devultur = class {
   async loadProgress(ctx, args) {
     return ctx.runQuery(this.component.public.loadProgress, args);
   }
+  /** An upload URL from your server, optionally locked (retention and/or hold, written with the bytes). */
+  async createUploadUrl(ctx, args) {
+    return ctx.runAction(this.component.public.createUploadUrl, args);
+  }
+  /**
+   * Records an upload in the component once its bytes are stored (after the PUT): it then shows in `listMedia`.
+   * Returns the record, or `null` when nothing is stored at `key`. Uploads nobody confirms are recorded a day later.
+   */
+  async confirmUpload(ctx, args) {
+    return ctx.runAction(this.component.uploads.confirmUpload, args);
+  }
+  /**
+   * The recorded media (every confirmed upload, and every video sent to `processVideo`), optionally of one type.
+   * `mediaFromRecord(record)` turns a row into the reference `<Image>` and `dv.media()` take. Unbounded: it reads every
+   * record, so a media library pages with `listMediaPage`.
+   */
+  async listMedia(ctx, args) {
+    return ctx.runQuery(this.component.public.listMedia, args ?? {});
+  }
+  /** One page of the recorded media, newest first, optionally of one type. Takes Convex's `paginationOpts`. */
+  async listMediaPage(ctx, args) {
+    return ctx.runQuery(this.component.public.listMediaPage, args);
+  }
+  /** The lock in force on `key`. */
+  async getLock(ctx, key) {
+    return ctx.runAction(this.component.lock.getLock, { key });
+  }
+  /** Sets or extends `key`'s retention (shortening a governance one needs `bypassGovernance` and the Worker's hook). */
+  async setLock(ctx, key, options) {
+    return ctx.runAction(this.component.lock.setLock, { key, ...options });
+  }
+  /** Holds `keys` (any number: sent in pages). A bulk hold by prefix uses `@devultur/core`'s client on your server. */
+  async setHold(ctx, keys) {
+    return ctx.runAction(this.component.lock.setHold, { keys });
+  }
+  /** Releases `keys`' holds: a retention `period` starts now; without a retention they're free. */
+  async releaseHold(ctx, keys) {
+    return ctx.runAction(this.component.lock.releaseHold, { keys });
+  }
   static exposeApi(component, config) {
     const preset = config?.video?.transcodePreset;
     const locales = config?.video?.captionLocales ?? [];
     const visibilityArg = v.optional(v.union(v.literal("public"), v.literal("private")));
+    const uploadLock = config?.upload?.lock;
     return {
       issueViewerToken: actionGeneric({
         args: { sessionSecret: v.optional(v.string()) },
@@ -47,7 +87,23 @@ var Devultur = class {
       createUploadUrl: actionGeneric({
         args: { filename: v.string(), contentType: v.string(), visibility: visibilityArg },
         handler: async (ctx, args) => {
-          return ctx.runAction(component.public.createUploadUrl, args);
+          return ctx.runAction(component.public.createUploadUrl, {
+            ...args,
+            ...uploadLock ? { lock: uploadLock } : {}
+          });
+        }
+      }),
+      // Records an upload once its bytes are stored (the Worker HEADs the key): a browser can't list anything
+      // that isn't in your bucket. `useDevultur().upload()` and `useMediaUpload` call it after the PUT.
+      confirmUpload: actionGeneric({
+        args: {
+          key: v.string(),
+          filename: v.optional(v.string()),
+          width: v.optional(v.number()),
+          height: v.optional(v.number())
+        },
+        handler: async (ctx, args) => {
+          return ctx.runAction(component.uploads.confirmUpload, args);
         }
       }),
       deleteMedia: actionGeneric({
@@ -79,6 +135,17 @@ var Devultur = class {
           return ctx.runQuery(component.public.getMediaByKey, { key: mediaKey });
         }
       }),
+      // The media library, a page at a time (for `usePaginatedQuery`). It lists every record, of every user: export
+      // it only when every caller may see the whole library, otherwise wrap `devultur.listMediaPage` with your checks.
+      listMediaPage: queryGeneric({
+        args: {
+          type: v.optional(v.union(v.literal("video"), v.literal("image"), v.literal("file"))),
+          paginationOpts: paginationOptsValidator
+        },
+        handler: async (ctx, args) => {
+          return ctx.runQuery(component.public.listMediaPage, args);
+        }
+      }),
       saveProgress: mutationGeneric({
         args: { userId: v.string(), videoId: v.string(), position: v.number() },
         handler: async (ctx, args) => {
@@ -106,6 +173,34 @@ var Devultur = class {
     };
   }
 };
+
+// src/errors.ts
+import { ConvexError } from "convex/values";
+function isErrorData(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const fields = data;
+  return typeof fields.code === "string" && typeof fields.status === "number" && typeof fields.message === "string";
+}
+function isDevulturError(error) {
+  return error instanceof ConvexError && isErrorData(error.data);
+}
+function devulturErrorOf(error) {
+  return isDevulturError(error) ? error.data : null;
+}
+
+// src/media-record.ts
+function mediaFromRecord(record) {
+  if (!record.visibility) return null;
+  return {
+    id: record.key,
+    kind: record.type,
+    visibility: record.visibility,
+    filename: record.filename,
+    ...record.objectKey ? { key: record.objectKey } : {},
+    ...record.width !== void 0 ? { width: record.width } : {},
+    ...record.height !== void 0 ? { height: record.height } : {}
+  };
+}
 export {
   CaptionLocale,
   Devultur,
@@ -117,5 +212,8 @@ export {
   TranscodePreset,
   TranscodeProvider,
   TranslationProvider,
-  dv
+  devulturErrorOf,
+  dv,
+  isDevulturError,
+  mediaFromRecord
 };

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Visibility, DevulturMedia, MediaUrlOptions, ProcessingPhase, FailureReason, MediaStatusValue } from '@devultur/core';
-import { BakeOutputFormat, MediaUploadState, MediaUploadError } from '@devultur/react';
-export { MediaUploadError, MediaUploadState } from '@devultur/react';
+import { BakeOutputFormat, MediaUploadState, MediaUploadError, UploadProgress } from '@devultur/react';
+export { MediaUploadError, MediaUploadState, UploadProgress } from '@devultur/react';
 import { FunctionReference } from 'convex/server';
 
 interface CropUploadRenderProps {
@@ -59,6 +59,8 @@ 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;
@@ -73,7 +75,18 @@ interface DevulturApi {
 interface UploadOptions {
     /** Visibility override for this resource. Omitted → inherits the router's default by type. */
     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;
 }
+/**
+ * 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;
+};
 interface DevulturContextValue {
     token: string | null;
     baseUrl: string | null;
@@ -83,8 +96,8 @@ interface DevulturContextValue {
         url: string;
         key: string;
     }>;
-    /** Uploads a file and returns the typed reference ready to save. */
-    upload: (file: File, options?: UploadOptions) => Promise<DevulturMedia>;
+    /** Uploads a file (reporting progress), records it in the component, and returns the reference ready to save. */
+    upload: (file: File, options?: UploadOptions) => Promise<UploadedMedia>;
     /** 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). */
@@ -278,4 +291,4 @@ interface UseMediaUploadReturn {
  */
 declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
 
-export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, useDevultur, useDevulturMedia, useDevulturProgress, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };
+export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, type UploadedMedia, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, useDevultur, useDevulturMedia, useDevulturProgress, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };

package/dist/react.js

@@ -13,7 +13,10 @@ import {
   SESSION_HEADER,
   visibilityFromKey
 } from "@devultur/core";
-import { UploadHttpError, uploadFileWithProgress } from "@devultur/react";
+import {
+  UploadHttpError,
+  uploadFileWithProgress
+} from "@devultur/react";
 import { useAction, useConvex, useMutation, useQuery } from "convex/react";
 
 // src/image-recovery.ts
@@ -175,6 +178,7 @@ function DevulturProvider({ api, baseUrl, children }) {
   const issueViewerToken = useAction(api.issueViewerToken);
   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 = React2.useRef(null);
   const reissueInFlightRef = React2.useRef(null);
@@ -230,26 +234,23 @@ function DevulturProvider({ api, baseUrl, children }) {
   const upload = React2.useCallback(
     async (file, options) => {
       const dimensions = await readImageDimensions(file);
-      const result = await createUploadUrlAction({
+      const target = await createUploadUrlAction({
         filename: file.name,
         contentType: file.type,
         visibility: options?.visibility
       });
-      const uploadResponse = await fetch(result.url, {
-        method: "PUT",
-        body: file,
-        headers: { "Content-Type": file.type }
-      });
-      if (!uploadResponse.ok) throw new Error(`Upload failed: ${uploadResponse.status}`);
+      await uploadFileWithProgress(target.url, file, { onBytes: options?.onProgress, signal: options?.signal });
+      if (api.confirmUpload) await confirmUploadBestEffort(confirmUploadAction, target.key, file, dimensions);
       return {
-        id: result.id,
-        kind: result.kind,
-        visibility: result.visibility,
+        id: target.id,
+        kind: target.kind,
+        visibility: target.visibility,
         filename: file.name,
+        key: target.key,
         ...dimensions
       };
     },
-    [createUploadUrlAction]
+    [createUploadUrlAction, confirmUploadAction, api.confirmUpload]
   );
   const url = React2.useCallback(
     (media, options) => {
@@ -381,6 +382,13 @@ function useMediaUrl(key, options) {
     return buildMediaUrl(baseUrl, key, { ...options, token: isPublic ? void 0 : token ?? void 0 });
   }, [key, baseUrl, token, options]);
 }
+async function confirmUploadBestEffort(confirmUpload, key, file, dimensions) {
+  try {
+    await confirmUpload({ key, filename: file.name, ...dimensions });
+  } catch (error) {
+    console.warn("Devultur: could not record the upload; it is recorded later", error);
+  }
+}
 async function readImageDimensions(file) {
   if (typeof createImageBitmap !== "function" || !file.type.startsWith("image/")) return {};
   try {
@@ -628,6 +636,7 @@ function useMediaUpload(options) {
   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] = React2.useState("idle");
   const [percent, setPercent] = React2.useState(0);
@@ -693,11 +702,13 @@ function useMediaUpload(options) {
         const rejected = err instanceof UploadHttpError && (err.status === 413 || err.status === 415);
         return fail(rejected ? "rejected" : "network", err instanceof Error ? err.message : "The upload failed");
       }
+      if (api.confirmUpload) await confirmUploadBestEffort(confirmUploadAction, result.key, file, dimensions);
       const uploaded = {
         id: result.id,
         kind: result.kind,
         visibility: result.visibility,
         filename: file.name,
+        key: result.key,
         ...dimensions
       };
       setMedia(uploaded);
@@ -708,7 +719,18 @@ function useMediaUpload(options) {
       if ((process ?? true) && uploaded.kind === "video") triggerProcess(result.key);
       return uploaded;
     },
-    [createUploadUrlAction, deleteMediaAction, triggerProcess, visibility, replaces, process, onComplete, onError]
+    [
+      createUploadUrlAction,
+      confirmUploadAction,
+      api.confirmUpload,
+      deleteMediaAction,
+      triggerProcess,
+      visibility,
+      replaces,
+      process,
+      onComplete,
+      onError
+    ]
   );
   const cancel = React2.useCallback(() => {
     abortRef.current?.abort();

package/dist/validators.d.ts

@@ -12,20 +12,22 @@ import { DevulturKind } from '@devultur/core';
  */
 declare const dv: {
     media(kind?: DevulturKind): convex_values.VObject<{
+        key?: string | undefined;
         filename?: string | undefined;
-        width?: number | undefined;
         height?: number | undefined;
+        width?: number | undefined;
+        visibility: "public" | "private";
         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>;
         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", "filename" | "id" | "kind" | "visibility" | "width" | "height">;
+    }, "required", "key" | "filename" | "visibility" | "height" | "width" | "id" | "kind">;
 };
 
 export { dv };

package/dist/validators.js

@@ -1,6 +1,6 @@
 import {
   dv
-} from "./chunk-FHWT3GD6.js";
+} from "./chunk-GKLFRSGI.js";
 export {
   dv
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/convex",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Convex component for Devultur media: media records, uploads, transcodes, watch progress and React bindings",
   "keywords": [
     "convex",
@@ -51,8 +51,8 @@
     "dist"
   ],
   "dependencies": {
-    "@devultur/core": "1.0.2",
-    "@devultur/react": "1.0.2"
+    "@devultur/core": "1.1.0",
+    "@devultur/react": "1.1.0"
   },
   "peerDependencies": {
     "convex": ">=1.25.0",
@@ -64,10 +64,14 @@
     }
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.3.0",
     "convex": "^1.21.0",
+    "jsdom": "^30.1.3",
     "react": "^19.0.0",
+    "react-dom": "^19.2.7",
     "tsup": "^8.0.0",
     "typescript": "^5.8.0"
   },
@@ -76,6 +80,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts src/validators.ts src/react.tsx src/bin/init.ts --format esm --dts && tsc -p src/component/tsconfig.json",
+    "codegen": "node scripts/codegen.ts",
     "dev": "tsup src/index.ts src/react.tsx --format esm --dts --watch",
     "typecheck": "tsc --noEmit"
   }