@devultur/convex 1.0.3 → 1.1.0

package/dist/component/workerErrors.js

@@ -0,0 +1,41 @@
+// Worker errors across the component boundary. A plain `Error` thrown in a component function reaches the app as a
+// message only; a `ConvexError` keeps its `data`. Every component action is built with `workerAction`, which rethrows
+// the Worker's `DevulturApiError` as `ConvexError<DevulturErrorData>`, so the app reads `error.data.code`
+// (`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";
+function isApiError(error) {
+    if (error instanceof DevulturApiError)
+        return true;
+    // A second copy of `@devultur/core` (bundling) fails `instanceof`; its shape doesn't.
+    return (error instanceof Error &&
+        error.name === "DevulturApiError" &&
+        typeof error.status === "number");
+}
+/** The error to rethrow: a Worker refusal becomes a `ConvexError` with its code; anything else passes through. */
+export function toComponentError(error) {
+    if (!isApiError(error))
+        return error;
+    const data = {
+        code: error.code ?? "worker_error",
+        message: error.message,
+        status: error.status,
+        // JSON from the Worker: valid Convex values once `undefined` is gone.
+        ...(error.details ? { details: JSON.parse(JSON.stringify(error.details)) } : {}),
+    };
+    return new ConvexError(data);
+}
+/** `action` whose handler rethrows Worker refusals as `ConvexError<DevulturErrorData>`. */
+export const workerAction = ((definition) => action({
+    ...definition,
+    handler: async (ctx, args) => {
+        try {
+            return await definition.handler(ctx, args);
+        }
+        catch (error) {
+            throw toComponentError(error);
+        }
+    },
+}));
+//# sourceMappingURL=workerErrors.js.map

package/dist/component/workerErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerErrors.js","sourceRoot":"","sources":["../../src/component/workerErrors.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,sHAAsH;AACtH,0GAA0G;AAC1G,iGAAiG;AACjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAc,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAa7C,SAAS,UAAU,CAAC,KAAc;IACjC,IAAI,KAAK,YAAY,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACnD,sFAAsF;IACtF,OAAO,CACN,KAAK,YAAY,KAAK;QACtB,KAAK,CAAC,IAAI,KAAK,kBAAkB;QACjC,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ,CAC1D,CAAC;AACH,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC9C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,IAAI,GAAsB;QAC/B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,cAAc;QAClC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,sEAAsE;QACtE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAA0B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzG,CAAC;IACF,OAAO,IAAI,WAAW,CAAC,IAAwB,CAAC,CAAC;AAClD,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,UAA0E,EAAE,EAAE,CAC3G,MAAM,CAAC;IACN,GAAG,UAAU;IACb,OAAO,EAAE,KAAK,EAAE,GAAY,EAAE,IAAa,EAAE,EAAE;QAC9C,IAAI,CAAC;YACJ,OAAO,MAAM,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACF,CAAC;CACQ,CAAC,CAA6B,CAAC"}

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { VideoModuleConfig } from '@devultur/core';
+import { VideoModuleConfig, ObjectLock, LockView, SetLockOptions, HoldPage, DevulturMedia } from '@devultur/core';
 export { CaptionLocale, DevulturConfig, DevulturKind, DevulturMedia, ImageFit, ImageFormat, SecurityLevel, SpeechProvider, StorageProvider, TranscodePreset, TranscodeProvider, TranslationProvider, VideoModuleConfig, Visibility } from '@devultur/core';
 import * as convex_server from 'convex/server';
-import { FunctionReference, GenericQueryCtx, GenericDataModel, GenericMutationCtx } from 'convex/server';
+import { FunctionReference, GenericQueryCtx, GenericDataModel, GenericMutationCtx, GenericActionCtx, PaginationOptions, PaginationResult } from 'convex/server';
+import { Value, ConvexError } from 'convex/values';
 export { dv } from './validators.js';
-import 'convex/values';
 
 /**
  * Generated `ComponentApi` utility.
@@ -26,6 +26,26 @@ import 'convex/values';
  * ```
  */
 type ComponentApi<Name extends string | undefined = string | undefined> = {
+    lock: {
+        getLock: FunctionReference<"action", "internal", {
+            key: string;
+        }, any, Name>;
+        releaseHold: FunctionReference<"action", "internal", {
+            keys: Array<string>;
+        }, any, Name>;
+        setHold: FunctionReference<"action", "internal", {
+            keys: Array<string>;
+        }, any, Name>;
+        setLock: FunctionReference<"action", "internal", {
+            bypassGovernance?: boolean;
+            derivatives?: "inherit" | "original-only";
+            key: string;
+            mode?: "governance" | "compliance";
+            period?: number;
+            remove?: true;
+            until?: string;
+        }, any, Name>;
+    };
     public: {
         createMedia: FunctionReference<"mutation", "internal", {
             contentType: string;
@@ -37,6 +57,16 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
         createUploadUrl: FunctionReference<"action", "internal", {
             contentType: string;
             filename: string;
+            hold?: boolean;
+            lock?: {
+                hold?: boolean;
+                retention?: {
+                    derivatives?: "inherit" | "original-only";
+                    mode: "governance" | "compliance";
+                    period?: number;
+                    until?: string;
+                };
+            };
             visibility?: "public" | "private";
         }, any, Name>;
         deleteMediaAction: FunctionReference<"action", "internal", {
@@ -62,6 +92,17 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
         listMedia: FunctionReference<"query", "internal", {
             type?: "video" | "image" | "file";
         }, any, Name>;
+        listMediaPage: FunctionReference<"query", "internal", {
+            paginationOpts: {
+                cursor: string | null;
+                endCursor?: string | null;
+                id?: number;
+                maximumBytesRead?: number;
+                maximumRowsRead?: number;
+                numItems: number;
+            };
+            type?: "video" | "image" | "file";
+        }, any, Name>;
         loadProgress: FunctionReference<"query", "internal", {
             userId: string;
             videoId: string;
@@ -108,17 +149,40 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
             vttUrl: string;
         }, any, Name>;
     };
+    uploads: {
+        confirmUpload: FunctionReference<"action", "internal", {
+            filename?: string;
+            height?: number;
+            key: string;
+            width?: number;
+        }, any, Name>;
+    };
 };
 
 interface DevulturComponentConfig {
     video?: VideoModuleConfig;
+    /**
+     * Lock every upload through the exposed `createUploadUrl` gets (retention and/or hold). Set here, on your server:
+     * the browser never chooses a lock. To lock per upload, call `devultur.createUploadUrl(ctx, { lock })` from your
+     * own function.
+     */
+    upload?: {
+        lock?: ObjectLock;
+    };
 }
 interface MediaRecord {
+    /** The media id (the `id` of its `DevulturMedia`), for every kind. */
     key: string;
     type: "video" | "image" | "file";
     filename: string;
     contentType: string;
     sizeBytes: number;
+    /** Set by a confirmed upload; unset on records from before 1.1.0. */
+    visibility?: "public" | "private";
+    /** Key of the uploaded object (a video's raw file). Set by a confirmed upload. */
+    objectKey?: string;
+    width?: number;
+    height?: number;
     transcodeStatus?: "queued" | "transcoding" | "captioning" | "ready" | "failed";
     transcodeProgress?: {
         current: number;
@@ -147,6 +211,23 @@ interface ProgressRecord {
 type DevulturComponent = ComponentApi;
 type QueryCtx = GenericQueryCtx<GenericDataModel>;
 type MutationCtx = GenericMutationCtx<GenericDataModel>;
+type ActionCtx = GenericActionCtx<GenericDataModel>;
+type UploadUrlArgs = {
+    filename: string;
+    contentType: string;
+    visibility?: "public" | "private";
+};
+type MediaType = "video" | "image" | "file";
+type MediaPageArgs = {
+    type?: MediaType;
+    paginationOpts: PaginationOptions;
+};
+type ConfirmUploadArgs = {
+    key: string;
+    filename?: string;
+    width?: number;
+    height?: number;
+};
 declare class Devultur {
     private component;
     constructor(component: DevulturComponent);
@@ -160,6 +241,34 @@ declare class Devultur {
         userId: string;
         videoId: string;
     }): Promise<any>;
+    /** An upload URL from your server, optionally locked (retention and/or hold, written with the bytes). */
+    createUploadUrl(ctx: ActionCtx, args: UploadUrlArgs & {
+        lock?: ObjectLock;
+        hold?: boolean;
+    }): Promise<any>;
+    /**
+     * 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.
+     */
+    confirmUpload(ctx: ActionCtx, args: ConfirmUploadArgs): Promise<MediaRecord | null>;
+    /**
+     * 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`.
+     */
+    listMedia(ctx: QueryCtx, args?: {
+        type?: MediaType;
+    }): Promise<MediaRecord[]>;
+    /** One page of the recorded media, newest first, optionally of one type. Takes Convex's `paginationOpts`. */
+    listMediaPage(ctx: QueryCtx, args: MediaPageArgs): Promise<PaginationResult<MediaRecord>>;
+    /** The lock in force on `key`. */
+    getLock(ctx: ActionCtx, key: string): Promise<LockView>;
+    /** Sets or extends `key`'s retention (shortening a governance one needs `bypassGovernance` and the Worker's hook). */
+    setLock(ctx: ActionCtx, key: string, options: SetLockOptions): Promise<LockView>;
+    /** Holds `keys` (any number: sent in pages). A bulk hold by prefix uses `@devultur/core`'s client on your server. */
+    setHold(ctx: ActionCtx, keys: string[]): Promise<Pick<HoldPage, "updated" | "skipped">>;
+    /** Releases `keys`' holds: a retention `period` starts now; without a retention they're free. */
+    releaseHold(ctx: ActionCtx, keys: string[]): Promise<Pick<HoldPage, "updated" | "skipped">>;
     static exposeApi(component: DevulturComponent, config?: DevulturComponentConfig): {
         issueViewerToken: convex_server.RegisteredAction<"public", {
             sessionSecret?: string;
@@ -169,6 +278,7 @@ declare class Devultur {
             contentType: string;
             visibility?: "public" | "private";
         }, Promise<any>>;
+        confirmUpload: convex_server.RegisteredAction<"public", ConfirmUploadArgs, Promise<any>>;
         deleteMedia: convex_server.RegisteredAction<"public", {
             key: string;
         }, Promise<any>>;
@@ -182,6 +292,7 @@ declare class Devultur {
         getMedia: convex_server.RegisteredQuery<"public", {
             key: string;
         }, Promise<any>>;
+        listMediaPage: convex_server.RegisteredQuery<"public", MediaPageArgs, Promise<any>>;
         saveProgress: convex_server.RegisteredMutation<"public", {
             userId: string;
             videoId: string;
@@ -202,4 +313,27 @@ declare class Devultur {
     };
 }
 
-export { Devultur, type DevulturComponentConfig, type MediaRecord, type ProgressRecord };
+/** `data` of the `ConvexError` a component action throws when the Worker refuses a request. */
+interface DevulturErrorData {
+    /** The Worker's stable code (`retention_active`, `file_too_large`, ...), or `worker_error` when it sent none. */
+    code: string;
+    message: string;
+    /** HTTP status of the Worker's answer. */
+    status: number;
+    /** The rest of the Worker's error body, e.g. `{ key, mode, until, hold }` on `retention_active`. */
+    details?: Record<string, Value>;
+}
+
+/** True when `error` is a Worker refusal from a component action. */
+declare function isDevulturError(error: unknown): error is ConvexError<DevulturErrorData & Record<string, never>>;
+/** The refusal's `{ code, message, status, details? }`, or `null` when `error` isn't one. */
+declare function devulturErrorOf(error: unknown): DevulturErrorData | null;
+
+/**
+ * The `DevulturMedia` reference of a component record (a `listMedia` row), ready for `<Image>`, `<DownloadLink>` or a
+ * `dv.media()` field. `null` for a record without a visibility: one from before 1.1.0, or a video only `processVideo`
+ * recorded.
+ */
+declare function mediaFromRecord(record: MediaRecord): DevulturMedia | null;
+
+export { Devultur, type DevulturComponentConfig, type DevulturErrorData, type MediaRecord, type ProgressRecord, devulturErrorOf, isDevulturError, mediaFromRecord };

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,9 +12,10 @@ 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;
@@ -23,9 +24,10 @@ declare const dv: {
         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" | "visibility" | "id" | "kind" | "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.3",
+  "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.3",
-    "@devultur/react": "1.0.3"
+    "@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"
   },