@devultur/convex 1.3.2 → 1.4.0

package/dist/index.d.ts

@@ -1,8 +1,10 @@
-import { VideoModuleConfig, ObjectLock, LockView, SetLockOptions, HoldPage, DevulturMedia } from '@devultur/core';
+import { 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, GenericActionCtx, PaginationOptions, PaginationResult } from 'convex/server';
-import { Value, ConvexError } from 'convex/values';
+import { FunctionReference, FunctionVisibility, DefaultFunctionArgs, GenericQueryCtx, GenericDataModel, GenericMutationCtx, GenericActionCtx, RegisteredQuery, RegisteredMutation, RegisteredAction, PaginationOptions, PaginationResult } from 'convex/server';
+import { PropertyValidators, Value, ConvexError } from 'convex/values';
+import { D as DevulturComponentConfig, M as MediaRecord } from './types-LrusGVDf.js';
+export { P as ProgressRecord } from './types-LrusGVDf.js';
+export { a as DEVULTUR_ERROR_CODES, b as DevulturErrorCode, c as DevulturErrorDetails, d as DevulturErrorLabel, D as DevulturErrorLabels, e as describeDevulturError, f as devulturErrorLabels, i as isDevulturErrorCode } from './error-labels-BfqcFh2R.js';
 export { dv } from './validators.js';
 
 /**
@@ -26,6 +28,23 @@ export { dv } from './validators.js';
  * ```
  */
 type ComponentApi<Name extends string | undefined = string | undefined> = {
+    library: {
+        backfillSearchText: FunctionReference<"mutation", "internal", {
+            batchSize?: number;
+        }, any, Name>;
+        searchMedia: FunctionReference<"query", "internal", {
+            paginationOpts: {
+                cursor: string | null;
+                endCursor?: string | null;
+                id?: number;
+                maximumBytesRead?: number;
+                maximumRowsRead?: number;
+                numItems: number;
+            };
+            search: string;
+            type?: "video" | "image" | "file";
+        }, any, Name>;
+    };
     lock: {
         getLock: FunctionReference<"action", "internal", {
             key: string;
@@ -46,6 +65,14 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
             until?: string;
         }, any, Name>;
     };
+    metadata: {
+        updateMediaMeta: FunctionReference<"mutation", "internal", {
+            alt?: string;
+            key: string;
+            tags?: Array<string>;
+            title?: string;
+        }, any, Name>;
+    };
     public: {
         createMedia: FunctionReference<"mutation", "internal", {
             contentType: string;
@@ -85,6 +112,7 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
         }, any, Name>;
         issueViewerToken: FunctionReference<"action", "internal", {
             sessionSecret?: string;
+            userId?: string;
         }, any, Name>;
         listCaptionsByMedia: FunctionReference<"query", "internal", {
             mediaKey: string;
@@ -154,59 +182,112 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
             filename?: string;
             height?: number;
             key: string;
+            pageCount?: number;
             width?: number;
         }, any, Name>;
     };
 };
 
-interface DevulturComponentConfig {
-    video?: VideoModuleConfig;
+type FunctionKind = "query" | "mutation" | "action";
+type ContextOf<Kind extends FunctionKind> = Kind extends "query" ? GenericQueryCtx<GenericDataModel> : Kind extends "mutation" ? GenericMutationCtx<GenericDataModel> : GenericActionCtx<GenericDataModel>;
+/** What a guard tells the function about its caller. */
+interface CallerContext {
     /**
-     * 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.
+     * The caller's user: the subject of `issueViewerToken`'s token, and the only `userId` the progress functions accept
+     * (another one is refused with `user_mismatch`).
      */
-    upload?: {
-        lock?: ObjectLock;
-    };
+    userId?: string;
+    /** The caller may name any `userId` in the progress functions (an admin resetting a learner's progress). */
+    canActForOthers?: boolean;
 }
-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;
-        total: number;
-    };
-    transcodeError?: string;
-    playlistUrl?: string;
-    thumbnailKey?: string;
-    /** 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;
-}
-interface ProgressRecord {
-    userId: string;
-    videoId: string;
-    lastPosition: number;
-    completedAt?: number;
-    watchedPercent?: number;
-    updatedAt: number;
+interface ExposedFunction<Kind extends FunctionKind, Args extends DefaultFunctionArgs, Result> {
+    kind: Kind;
+    args: PropertyValidators;
+    handler: (ctx: ContextOf<Kind>, args: Args, caller: CallerContext) => Promise<Result>;
 }
+declare function exposedFunctions(component: ComponentApi, config?: DevulturComponentConfig): {
+    issueViewerToken: ExposedFunction<"action", {
+        sessionSecret?: string | undefined;
+    }, any>;
+    createUploadUrl: ExposedFunction<"action", {
+        visibility?: "public" | "private" | undefined;
+        contentType: string;
+        filename: string;
+    }, any>;
+    confirmUpload: ExposedFunction<"action", {
+        filename?: string | undefined;
+        height?: number | undefined;
+        pageCount?: number | undefined;
+        width?: number | undefined;
+        key: string;
+    }, any>;
+    updateMediaMeta: ExposedFunction<"mutation", {
+        alt?: string | undefined;
+        tags?: string[] | undefined;
+        title?: string | undefined;
+        key: string;
+    }, any>;
+    deleteMedia: ExposedFunction<"action", {
+        key: string;
+    }, any>;
+    deleteVideo: ExposedFunction<"action", {
+        visibility?: "public" | "private" | undefined;
+        videoId: string;
+    }, any>;
+    processVideo: ExposedFunction<"action", {
+        key: string;
+    }, any>;
+    getMedia: ExposedFunction<"query", {
+        key: string;
+    }, any>;
+    listMediaPage: ExposedFunction<"query", {
+        type?: "video" | "image" | "file" | undefined;
+        paginationOpts: {
+            id?: number;
+            endCursor?: string | null;
+            maximumRowsRead?: number;
+            maximumBytesRead?: number;
+            numItems: number;
+            cursor: string | null;
+        };
+    }, any>;
+    searchMedia: ExposedFunction<"query", {
+        type?: "video" | "image" | "file" | undefined;
+        paginationOpts: {
+            id?: number;
+            endCursor?: string | null;
+            maximumRowsRead?: number;
+            maximumBytesRead?: number;
+            numItems: number;
+            cursor: string | null;
+        };
+        search: string;
+    }, any>;
+    saveProgress: ExposedFunction<"mutation", {
+        videoId: string;
+        userId: string;
+        position: number;
+    }, any>;
+    loadProgress: ExposedFunction<"query", {
+        videoId: string;
+        userId: string;
+    }, any>;
+    markComplete: ExposedFunction<"mutation", {
+        videoId: string;
+        userId: string;
+    }, any>;
+    resetProgress: ExposedFunction<"mutation", {
+        videoId: string;
+        userId: string;
+    }, any>;
+};
+type ExposedFunctions = ReturnType<typeof exposedFunctions>;
+type ExposedFunctionName = keyof ExposedFunctions;
+type Registered<Fn, Visibility extends FunctionVisibility> = Fn extends ExposedFunction<"query", infer Args, infer Result> ? RegisteredQuery<Visibility, Args, Promise<Result>> : Fn extends ExposedFunction<"mutation", infer Args, infer Result> ? RegisteredMutation<Visibility, Args, Promise<Result>> : Fn extends ExposedFunction<"action", infer Args, infer Result> ? RegisteredAction<Visibility, Args, Promise<Result>> : never;
+/** The Convex functions registered from `ExposedFunctions`, each with its own args and result. */
+type RegisteredFunctions<Visibility extends FunctionVisibility> = {
+    [Name in ExposedFunctionName]: Registered<ExposedFunctions[Name], Visibility>;
+};
 
 type DevulturComponent = ComponentApi;
 type QueryCtx = GenericQueryCtx<GenericDataModel>;
@@ -222,14 +303,30 @@ type MediaPageArgs = {
     type?: MediaType;
     paginationOpts: PaginationOptions;
 };
+type SearchMediaArgs = MediaPageArgs & {
+    search: string;
+};
+/** `updated`: records this first batch filled. `isDone`: `false` while later batches are scheduled. */
+type BackfillResult = {
+    updated: number;
+    isDone: boolean;
+};
 type ConfirmUploadArgs = {
     key: string;
     filename?: string;
     width?: number;
     height?: number;
+    pageCount?: number;
+};
+type MediaMetaArgs = {
+    key: string;
+    title?: string;
+    alt?: string;
+    tags?: string[];
 };
 declare class Devultur {
-    private component;
+    /** The mounted component (`components.devultur`) this client calls. */
+    readonly component: DevulturComponent;
     constructor(component: DevulturComponent);
     getMedia(ctx: QueryCtx, key: string): Promise<any>;
     saveProgress(ctx: MutationCtx, args: {
@@ -249,8 +346,16 @@ declare class Devultur {
     /**
      * 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.
+     * `width`, `height` and `pageCount` are the client's hints (positive integers up to 100,000); an image size the
+     * Worker read from the bytes wins over them.
      */
     confirmUpload(ctx: ActionCtx, args: ConfirmUploadArgs): Promise<MediaRecord | null>;
+    /**
+     * Sets a record's `title`, `alt` and/or `tags` (only the ones passed; an empty string clears a title or alt, `[]`
+     * the tags). `key` is the media id. Trimmed and deduplicated; past title 200, alt 1000 or 20 tags of 50 characters
+     * it throws `invalid_media_metadata`. Returns the updated record, or `null` when there is none.
+     */
+    updateMediaMeta(ctx: MutationCtx, args: MediaMetaArgs): 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
@@ -261,6 +366,19 @@ declare class Devultur {
     }): 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>>;
+    /**
+     * One page of the records whose title or filename matches `search` (its last word as a prefix), best match first,
+     * optionally of one type. A blank `search` lists newest first, like `listMediaPage`. Records from before 1.4.0
+     * match once `backfillSearchText` (or any write) gives them a `searchText`.
+     */
+    searchMedia(ctx: QueryCtx, args: SearchMediaArgs): Promise<PaginationResult<MediaRecord>>;
+    /**
+     * One-off for records written before 1.4.0: gives every record without a `searchText` one, `batchSize` records
+     * per mutation (default 100, at most 1000). Runs the first batch and schedules the rest. Safe to run again.
+     */
+    backfillSearchText(ctx: MutationCtx, options?: {
+        batchSize?: number;
+    }): Promise<BackfillResult>;
     /** 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). */
@@ -269,48 +387,11 @@ declare class Devultur {
     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;
-        }, Promise<any>>;
-        createUploadUrl: convex_server.RegisteredAction<"public", {
-            filename: string;
-            contentType: string;
-            visibility?: "public" | "private";
-        }, Promise<any>>;
-        confirmUpload: convex_server.RegisteredAction<"public", ConfirmUploadArgs, Promise<any>>;
-        deleteMedia: convex_server.RegisteredAction<"public", {
-            key: string;
-        }, Promise<any>>;
-        deleteVideo: convex_server.RegisteredAction<"public", {
-            videoId: string;
-            visibility?: "public" | "private";
-        }, Promise<any>>;
-        processVideo: convex_server.RegisteredAction<"public", {
-            key: string;
-        }, Promise<any>>;
-        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;
-            position: number;
-        }, Promise<any>>;
-        loadProgress: convex_server.RegisteredQuery<"public", {
-            userId: string;
-            videoId: string;
-        }, Promise<any>>;
-        markComplete: convex_server.RegisteredMutation<"public", {
-            userId: string;
-            videoId: string;
-        }, Promise<any>>;
-        resetProgress: convex_server.RegisteredMutation<"public", {
-            userId: string;
-            videoId: string;
-        }, Promise<any>>;
-    };
+    /**
+     * The component's functions for your app to export. They have no auth of their own: anyone who can call your
+     * Convex deployment can call them. `defineDevulturFunctions` returns the same functions behind your guard.
+     */
+    static exposeApi(component: DevulturComponent, config?: DevulturComponentConfig): RegisteredFunctions<"public">;
 }
 
 /** `data` of the `ConvexError` a component action throws when the Worker refuses a request. */
@@ -329,11 +410,41 @@ declare function isDevulturError(error: unknown): error is ConvexError<DevulturE
 /** The refusal's `{ code, message, status, details? }`, or `null` when `error` isn't one. */
 declare function devulturErrorOf(error: unknown): DevulturErrorData | null;
 
+type ArgsOf<Fn> = Fn extends {
+    handler: (ctx: never, args: infer Args, caller: never) => unknown;
+} ? Args : never;
+/** One call to guard: which function, of which kind, with the caller's arguments. Narrow on `name`. */
+type DevulturOperation = {
+    [Name in ExposedFunctionName]: {
+        name: Name;
+        kind: ExposedFunctions[Name]["kind"];
+        args: ArgsOf<ExposedFunctions[Name]>;
+    };
+}[ExposedFunctionName];
+/** The ctx of the guarded function: a query's, a mutation's or an action's (all of them have `auth`). */
+type DevulturGuardCtx = GenericQueryCtx<GenericDataModel> | GenericMutationCtx<GenericDataModel> | GenericActionCtx<GenericDataModel>;
+/**
+ * Throws to deny the call. May return what it learned about the caller: a `userId` becomes the subject of the token
+ * `issueViewerToken` issues, and the only user the progress functions act for (another `userId` in their arguments is
+ * refused with `user_mismatch`, unless the guard also returns `canActForOthers: true`).
+ */
+type DevulturGuard = (ctx: DevulturGuardCtx, operation: DevulturOperation) => GuardResult | Promise<GuardResult>;
+type GuardResult = CallerContext | undefined | void;
+interface DevulturFunctionsOptions<Visibility extends FunctionVisibility> {
+    guard: DevulturGuard;
+    /** `"internal"` registers them as internal functions (callable from your server only). Default `"public"`. */
+    visibility?: Visibility;
+    /** Same as `Devultur.exposeApi`'s: the transcode preset, caption locales and upload lock. */
+    config?: DevulturComponentConfig;
+}
+/** `Devultur.exposeApi`'s functions, each calling `options.guard` before it runs. Export the ones your app uses. */
+declare function defineDevulturFunctions<Visibility extends FunctionVisibility = "public">(devultur: Devultur, options: DevulturFunctionsOptions<Visibility>): RegisteredFunctions<Visibility>;
+
 /**
  * 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.
+ * recorded. A stored reference is a copy: a later `updateMediaMeta` changes the record, not the references to it.
  */
 declare function mediaFromRecord(record: MediaRecord): DevulturMedia | null;
 
-export { Devultur, type DevulturComponentConfig, type DevulturErrorData, type MediaRecord, type ProgressRecord, devulturErrorOf, isDevulturError, mediaFromRecord };
+export { type CallerContext, Devultur, DevulturComponentConfig, type DevulturErrorData, type DevulturFunctionsOptions, type DevulturGuard, type DevulturGuardCtx, type DevulturOperation, MediaRecord, type RegisteredFunctions, defineDevulturFunctions, devulturErrorOf, isDevulturError, mediaFromRecord };