@devultur/convex 1.0.2 → 1.1.0

package/dist/component/uploads.d.ts

@@ -0,0 +1,119 @@
+export declare const UPLOAD_CONFIRM_BACKSTOP_MS: number;
+/**
+ * Records an upload in the component's `media` table once its bytes are stored (call it after the PUT). Returns the
+ * record, or `null` when nothing is stored at `key`. Idempotent: confirming twice updates the same record, and a
+ * video's transcode state is left as it is.
+ */
+export declare const confirmUpload: import("convex/server").RegisteredAction<"public", {
+    width?: number | undefined;
+    height?: number | undefined;
+    filename?: string | undefined;
+    key: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"media">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    visibility?: "public" | "private" | undefined;
+    objectKey?: string | undefined;
+    transcodeStatus?: "queued" | "transcoding" | "captioning" | "ready" | "failed" | undefined;
+    transcodeProgress?: {
+        phase?: "captioning" | "downloading" | "encoding" | "uploading" | undefined;
+        current: number;
+        total: number;
+    } | undefined;
+    transcodeError?: string | undefined;
+    failureReason?: "invalid_input" | "unsupported_codec" | "timeout" | "capacity" | "internal" | undefined;
+    retriable?: boolean | undefined;
+    playlistUrl?: string | undefined;
+    thumbnailKey?: string | undefined;
+    captionLocales?: string[] | undefined;
+    captionsPending?: boolean | undefined;
+    duration?: number | undefined;
+    renditions?: {
+        width?: number | undefined;
+        height?: number | undefined;
+        variant: string;
+        kind: "hls" | "mp4";
+        rung: string;
+        key: string;
+        url: string;
+    }[] | undefined;
+    posterUrls?: {
+        jpg?: string | undefined;
+        avif?: string | undefined;
+    } | undefined;
+    hasAudio?: boolean | undefined;
+    storyboardKey?: string | undefined;
+    type: "video" | "image" | "file";
+    key: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    createdAt: number;
+} | null>>;
+/** The scheduled check `createUploadUrl` leaves behind: records the upload if it was stored and never confirmed. */
+export declare const confirmUploadLater: import("convex/server").RegisteredAction<"internal", {
+    width?: number | undefined;
+    height?: number | undefined;
+    filename?: string | undefined;
+    key: string;
+}, Promise<void>>;
+export declare const recordUpload: import("convex/server").RegisteredMutation<"internal", {
+    width?: number | undefined;
+    height?: number | undefined;
+    type: "video" | "image" | "file";
+    key: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    visibility: "public" | "private";
+    objectKey: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"media">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    visibility?: "public" | "private" | undefined;
+    objectKey?: string | undefined;
+    transcodeStatus?: "queued" | "transcoding" | "captioning" | "ready" | "failed" | undefined;
+    transcodeProgress?: {
+        phase?: "captioning" | "downloading" | "encoding" | "uploading" | undefined;
+        current: number;
+        total: number;
+    } | undefined;
+    transcodeError?: string | undefined;
+    failureReason?: "invalid_input" | "unsupported_codec" | "timeout" | "capacity" | "internal" | undefined;
+    retriable?: boolean | undefined;
+    playlistUrl?: string | undefined;
+    thumbnailKey?: string | undefined;
+    captionLocales?: string[] | undefined;
+    captionsPending?: boolean | undefined;
+    duration?: number | undefined;
+    renditions?: {
+        width?: number | undefined;
+        height?: number | undefined;
+        variant: string;
+        kind: "hls" | "mp4";
+        rung: string;
+        key: string;
+        url: string;
+    }[] | undefined;
+    posterUrls?: {
+        jpg?: string | undefined;
+        avif?: string | undefined;
+    } | undefined;
+    hasAudio?: boolean | undefined;
+    storyboardKey?: string | undefined;
+    type: "video" | "image" | "file";
+    key: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    createdAt: number;
+} | null>>;
+/** Drops the record of a deleted image or file. A video's record goes with `deleteVideo`, not with one of its keys. */
+export declare const forgetUpload: import("convex/server").RegisteredMutation<"internal", {
+    key: string;
+}, Promise<void>>;
+//# sourceMappingURL=uploads.d.ts.map

package/dist/component/uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../src/component/uploads.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,0BAA0B,QAAsB,CAAC;AAgD9D;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAGxB,CAAC;AAEH,oHAAoH;AACpH,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA0BvB,CAAC;AAEH,uHAAuH;AACvH,eAAO,MAAM,YAAY;;iBAYvB,CAAC"}

package/dist/component/uploads.js

@@ -0,0 +1,106 @@
+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 { parseUploadKey } from "./uploadKeys";
+import { workerAction } from "./workerErrors";
+// 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;
+/** The display name to store: the client's when it is the name in the key, else the key's own. */
+function displayName(uploadKey, filename) {
+    if (filename && sanitizeFilename(filename) === uploadKey.storedName)
+        return filename;
+    return uploadKey.storedName;
+}
+const confirmArgs = {
+    key: v.string(),
+    /** The original filename (display and download name). Ignored unless it is the one in the key. */
+    filename: v.optional(v.string()),
+    /** Intrinsic size of an image, read in the browser. */
+    width: v.optional(v.number()),
+    height: v.optional(v.number()),
+};
+/** HEADs the object and records it; `null` when no object is stored at `key` (yet). */
+// Annotated: the result of `internal.uploads.*` would otherwise type this module in terms of itself.
+async function confirm(ctx, args) {
+    const uploadKey = parseUploadKey(args.key);
+    if (!uploadKey) {
+        throw new ConvexError({ code: "invalid_upload_key", message: `Not an upload key: ${args.key}`, status: 400 });
+    }
+    const head = await getMediaClient().files.head(args.key);
+    if (!head)
+        return null;
+    return ctx.runMutation(internal.uploads.recordUpload, {
+        key: uploadKey.id,
+        objectKey: args.key,
+        type: uploadKey.kind,
+        visibility: uploadKey.visibility,
+        filename: displayName(uploadKey, args.filename),
+        contentType: head.contentType,
+        sizeBytes: head.size,
+        ...(args.width !== undefined ? { width: args.width } : {}),
+        ...(args.height !== undefined ? { height: args.height } : {}),
+    });
+}
+/**
+ * Records an upload in the component's `media` table once its bytes are stored (call it after the PUT). Returns the
+ * record, or `null` when nothing is stored at `key`. Idempotent: confirming twice updates the same record, and a
+ * video's transcode state is left as it is.
+ */
+export const confirmUpload = workerAction({
+    args: confirmArgs,
+    handler: async (ctx, args) => confirm(ctx, args),
+});
+/** The scheduled check `createUploadUrl` leaves behind: records the upload if it was stored and never confirmed. */
+export const confirmUploadLater = internalAction({
+    args: confirmArgs,
+    handler: async (ctx, args) => {
+        await confirm(ctx, args);
+    },
+});
+export const recordUpload = internalMutation({
+    args: {
+        key: v.string(),
+        objectKey: v.string(),
+        type: v.union(v.literal("video"), v.literal("image"), v.literal("file")),
+        visibility: v.union(v.literal("public"), v.literal("private")),
+        filename: v.string(),
+        contentType: v.string(),
+        sizeBytes: v.number(),
+        width: v.optional(v.number()),
+        height: v.optional(v.number()),
+    },
+    handler: async (ctx, args) => {
+        const existing = await ctx.db
+            .query("media")
+            .withIndex("by_key", (q) => q.eq("key", args.key))
+            .first();
+        if (!existing) {
+            const id = await ctx.db.insert("media", { ...args, createdAt: Date.now() });
+            return ctx.db.get(id);
+        }
+        // A video `processVideo` recorded first: fill in what only the upload knows, keep its transcode state.
+        await ctx.db.patch(existing._id, args);
+        return ctx.db.get(existing._id);
+    },
+});
+/** Drops the record of a deleted image or file. A video's record goes with `deleteVideo`, not with one of its keys. */
+export const forgetUpload = internalMutation({
+    args: { key: v.string() },
+    handler: async (ctx, args) => {
+        if (!parseUploadKey(args.key))
+            return;
+        const record = await ctx.db
+            .query("media")
+            .withIndex("by_key", (q) => q.eq("key", extractId(args.key)))
+            .first();
+        if (!record || record.type === "video")
+            return;
+        if (record.objectKey && record.objectKey !== args.key)
+            return;
+        await ctx.db.delete(record._id);
+    },
+});
+//# sourceMappingURL=uploads.js.map

package/dist/component/uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.js","sourceRoot":"","sources":["../../src/component/uploads.ts"],"names":[],"mappings":"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"}

package/dist/component/workerErrors.d.ts

@@ -0,0 +1,17 @@
+import { type Value } from "convex/values";
+import { action } from "./_generated/server";
+/** `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. */
+    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>;
+}
+/** The error to rethrow: a Worker refusal becomes a `ConvexError` with its code; anything else passes through. */
+export declare function toComponentError(error: unknown): unknown;
+/** `action` whose handler rethrows Worker refusals as `ConvexError<DevulturErrorData>`. */
+export declare const workerAction: typeof action;
+//# sourceMappingURL=workerErrors.d.ts.map

package/dist/component/workerErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerErrors.d.ts","sourceRoot":"","sources":["../../src/component/workerErrors.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,+FAA+F;AAC/F,MAAM,WAAW,iBAAiB;IACjC,iHAAiH;IACjH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAChC;AAYD,kHAAkH;AAClH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUxD;AAED,2FAA2F;AAC3F,eAAO,MAAM,YAAY,EAUG,OAAO,MAAM,CAAC"}

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,12 +57,24 @@ 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", {
             key: string;
         }, any, Name>;
         deleteVideo: FunctionReference<"action", "internal", {
             videoId: string;
+            visibility?: "public" | "private";
         }, any, Name>;
         getCourseProgress: FunctionReference<"query", "internal", {
             userId: string;
@@ -60,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;
@@ -85,16 +128,19 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
         }, any, Name>;
         updateMedia: FunctionReference<"mutation", "internal", {
             captionLocales?: Array<string>;
+            captionsPending?: boolean;
             duration?: number;
+            failureReason?: "invalid_input" | "unsupported_codec" | "timeout" | "capacity" | "internal";
             key: string;
             playlistUrl?: string;
+            retriable?: boolean;
             thumbnailKey?: string;
             transcodeError?: string;
             transcodeProgress?: {
                 current: number;
                 total: number;
             };
-            transcodeStatus?: "transcoding" | "captioning" | "ready" | "failed";
+            transcodeStatus?: "queued" | "transcoding" | "captioning" | "ready" | "failed";
         }, any, Name>;
         upsertCaption: FunctionReference<"mutation", "internal", {
             locale: string;
@@ -103,18 +149,41 @@ 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;
-    transcodeStatus?: "transcoding" | "captioning" | "ready" | "failed";
+    /** 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;
         total: number;
@@ -125,6 +194,8 @@ interface MediaRecord {
     /** Key of the storyboard VTT (hover previews); URL via `buildStoryboardUrl` from `@devultur/core`. */
     storyboardKey?: string;
     captionLocales?: string[];
+    /** True while requested captions haven't arrived; the video waits in "captioning" only then. */
+    captionsPending?: boolean;
     duration?: number;
     createdAt: number;
 }
@@ -140,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);
@@ -153,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;
@@ -162,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>>;
@@ -175,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;
@@ -195,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 };