@devultur/convex 1.4.3 → 1.5.1

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { ObjectLock, LockView, SetLockOptions, HoldPage, DevulturMedia } from '@devultur/core';
+import { WorkerUploadResult, DeleteVideoResult, TranscodeJobResult, 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 { FunctionReference, FunctionVisibility, DefaultFunctionArgs, GenericQueryCtx, GenericDataModel, GenericMutationCtx, GenericActionCtx, RegisteredQuery, RegisteredMutation, RegisteredAction, PaginationOptions, PaginationResult } from 'convex/server';
+import { FunctionReference, PaginationResult, FunctionVisibility, DefaultFunctionArgs, GenericQueryCtx, GenericDataModel, GenericMutationCtx, GenericActionCtx, RegisteredQuery, RegisteredMutation, RegisteredAction, PaginationOptions } from 'convex/server';
 import { PropertyValidators, Value, ConvexError } from 'convex/values';
-import { D as DevulturComponentConfig, M as MediaRecord } from './types-DZxN6Eij.js';
-export { P as ProgressRecord } from './types-DZxN6Eij.js';
+import { M as MediaRecord, P as ProgressRecord, D as DevulturComponentConfig } from './types-C0ruHUcu.js';
+export { a as DevulturUploadConfig } from './types-C0ruHUcu.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-D0Vbp-qA.js';
 export { dv } from './validators.js';
 
@@ -188,6 +188,42 @@ type ComponentApi<Name extends string | undefined = string | undefined> = {
     };
 };
 
+/** Convex's system fields on a document a component returns. Its `_id` is a plain string in your app. */
+interface ComponentSystemFields {
+    _id: string;
+    _creationTime: number;
+}
+/** A media record as the component's functions return it: the stored fields and the system fields. */
+interface MediaDocument extends MediaRecord, ComponentSystemFields {
+}
+/** A watch-progress record as the component's functions return it. */
+interface ProgressDocument extends ProgressRecord, ComponentSystemFields {
+}
+/** The result of each exposed function, by name. */
+interface DevulturFunctionResults {
+    issueViewerToken: {
+        token: string;
+        expiresIn: number;
+    };
+    createUploadUrl: WorkerUploadResult;
+    /** The record, or `null` when nothing is stored at the key. */
+    confirmUpload: MediaDocument | null;
+    /** The updated record, or `null` when there is none. */
+    updateMediaMeta: MediaDocument | null;
+    deleteMedia: null;
+    deleteVideo: DeleteVideoResult;
+    processVideo: TranscodeJobResult;
+    getMedia: MediaDocument | null;
+    listMediaPage: PaginationResult<MediaDocument>;
+    searchMedia: PaginationResult<MediaDocument>;
+    /** The progress record's id. */
+    saveProgress: string;
+    loadProgress: ProgressDocument | null;
+    /** The progress record's id. */
+    markComplete: string;
+    resetProgress: null;
+}
+
 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. */
@@ -283,10 +319,10 @@ declare function exposedFunctions(component: ComponentApi, config?: DevulturComp
 };
 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;
+type Registered<Fn, Visibility extends FunctionVisibility, Result> = Fn extends ExposedFunction<"query", infer Args, unknown> ? RegisteredQuery<Visibility, Args, Promise<Result>> : Fn extends ExposedFunction<"mutation", infer Args, unknown> ? RegisteredMutation<Visibility, Args, Promise<Result>> : Fn extends ExposedFunction<"action", infer Args, unknown> ? 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>;
+    [Name in ExposedFunctionName]: Registered<ExposedFunctions[Name], Visibility, DevulturFunctionResults[Name]>;
 };
 
 type DevulturComponent = ComponentApi;
@@ -329,34 +365,35 @@ declare class Devultur {
     /** The mounted component (`components.devultur`) this client calls. */
     readonly component: DevulturComponent;
     constructor(component: DevulturComponent);
-    getMedia(ctx: QueryCtx, key: string): Promise<any>;
+    getMedia(ctx: QueryCtx, key: string): Promise<MediaDocument | null>;
+    /** Returns the progress record's id. */
     saveProgress(ctx: MutationCtx, args: {
         userId: string;
         videoId: string;
         position: number;
-    }): Promise<any>;
+    }): Promise<string>;
     loadProgress(ctx: QueryCtx, args: {
         userId: string;
         videoId: string;
-    }): Promise<any>;
+    }): Promise<ProgressDocument | null>;
     /** 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>;
+    }): Promise<DevulturFunctionResults["createUploadUrl"]>;
     /**
      * 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>;
+    confirmUpload(ctx: ActionCtx, args: ConfirmUploadArgs): Promise<MediaDocument | 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>;
+    updateMediaMeta(ctx: MutationCtx, args: MediaMetaArgs): Promise<MediaDocument | 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
@@ -364,15 +401,15 @@ declare class Devultur {
      */
     listMedia(ctx: QueryCtx, args?: {
         type?: MediaType;
-    }): Promise<MediaRecord[]>;
+    }): Promise<MediaDocument[]>;
     /** One page of the recorded media, newest first, optionally of one type. Takes Convex's `paginationOpts`. */
-    listMediaPage(ctx: QueryCtx, args: MediaPageArgs): Promise<PaginationResult<MediaRecord>>;
+    listMediaPage(ctx: QueryCtx, args: MediaPageArgs): Promise<PaginationResult<MediaDocument>>;
     /**
      * 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>>;
+    searchMedia(ctx: QueryCtx, args: SearchMediaArgs): Promise<PaginationResult<MediaDocument>>;
     /**
      * 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.
@@ -430,15 +467,32 @@ type DevulturGuardCtx<DataModel extends GenericDataModel = any> = GenericQueryCt
 /**
  * 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`).
+ * refused with `user_mismatch`, unless the guard also returns `canActForOthers: true`). May also return a `rewrite` of
+ * the caller's arguments (see `DevulturArgsRewrite`).
  */
-type DevulturGuard = (ctx: DevulturGuardCtx, operation: DevulturOperation) => GuardResult | Promise<GuardResult>;
-type GuardResult = CallerContext | undefined | void;
+type DevulturGuard = (ctx: DevulturGuardCtx, operation: DevulturOperation) => DevulturGuardResult | Promise<DevulturGuardResult>;
+/**
+ * Arguments a guard rewrites, on your server, before the function runs: each key of `args` replaces the caller's
+ * argument of that name. `name` is the operation's, so `args` are typed for it:
+ * `{ name: "createUploadUrl", args: { visibility: "private" } }` uploads privately whatever the browser asked for.
+ * A rewrite named for another operation than the one being guarded throws. The rewritten arguments aren't validated
+ * again.
+ */
+type DevulturArgsRewrite = {
+    [Name in ExposedFunctionName]: {
+        name: Name;
+        args: Partial<ArgsOf<ExposedFunctions[Name]>>;
+    };
+}[ExposedFunctionName];
+/** What a guard returns: what it learned about the caller, and the arguments it rewrites. */
+type DevulturGuardResult = (CallerContext & {
+    rewrite?: DevulturArgsRewrite;
+}) | 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. */
+    /** Same as `Devultur.exposeApi`'s: the transcode preset, caption locales, upload lock and default visibility. */
     config?: DevulturComponentConfig;
 }
 /** `Devultur.exposeApi`'s functions, each calling `options.guard` before it runs. Export the ones your app uses. */
@@ -451,4 +505,4 @@ declare function defineDevulturFunctions<Visibility extends FunctionVisibility =
  */
 declare function mediaFromRecord(record: MediaRecord): DevulturMedia | null;
 
-export { type CallerContext, Devultur, DevulturComponentConfig, type DevulturErrorData, type DevulturFunctionsOptions, type DevulturGuard, type DevulturGuardCtx, type DevulturOperation, MediaRecord, type RegisteredFunctions, defineDevulturFunctions, devulturErrorOf, isDevulturError, mediaFromRecord };
+export { type CallerContext, type ComponentSystemFields, Devultur, type DevulturArgsRewrite, DevulturComponentConfig, type DevulturErrorData, type DevulturFunctionResults, type DevulturFunctionsOptions, type DevulturGuard, type DevulturGuardCtx, type DevulturGuardResult, type DevulturOperation, type MediaDocument, MediaRecord, type ProgressDocument, ProgressRecord, type RegisteredFunctions, defineDevulturFunctions, devulturErrorOf, isDevulturError, mediaFromRecord };

package/dist/index.js

@@ -53,12 +53,16 @@ function progressArgsFor(args, caller) {
   });
 }
 function mediaIdOf(key) {
+  if (typeof key !== "string") {
+    throw new ConvexError({ code: "invalid_key", message: "The media key must be a string", status: 400 });
+  }
   return key.includes("/") ? extractId(key) : key;
 }
 function exposedFunctions(component, config) {
   const preset = config?.video?.transcodePreset;
   const locales = config?.video?.captionLocales ?? [];
   const uploadLock = config?.upload?.lock;
+  const defaultVisibility = config?.upload?.visibility;
   return {
     issueViewerToken: exposed(
       "action",
@@ -68,11 +72,18 @@ function exposedFunctions(component, config) {
         ...caller.userId ? { userId: caller.userId } : {}
       })
     ),
-    // Optional per-resource visibility; omitted → the component resolves the config's default (secure-by-default).
+    // Visibility: the caller's (after the guard's rewrite), else `config.upload.visibility`, else the Worker's default.
     createUploadUrl: exposed(
       "action",
       { filename: v.string(), contentType: v.string(), visibility: visibilityArg },
-      async (ctx, args) => ctx.runAction(component.public.createUploadUrl, { ...args, ...uploadLock ? { lock: uploadLock } : {} })
+      async (ctx, args) => {
+        const visibility = args.visibility ?? defaultVisibility;
+        return ctx.runAction(component.public.createUploadUrl, {
+          ...args,
+          ...visibility ? { visibility } : {},
+          ...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.
@@ -175,6 +186,7 @@ var Devultur = class {
   async getMedia(ctx, key) {
     return ctx.runQuery(this.component.public.getMediaByKey, { key });
   }
+  /** Returns the progress record's id. */
   async saveProgress(ctx, args) {
     return ctx.runMutation(this.component.public.saveProgress, args);
   }
@@ -263,11 +275,18 @@ function defineDevulturFunctions(devultur, options) {
   return registerFunctions(exposedFunctions(devultur.component, config), visibility, (name, fn) => {
     return async (ctx, args) => {
       const operation = { name, kind: fn.kind, args };
-      const caller = await guard(ctx, operation) ?? {};
-      return fn.handler(ctx, args, caller);
+      const { rewrite, ...caller } = await guard(ctx, operation) ?? {};
+      return fn.handler(ctx, rewrittenArgs(name, args, rewrite), caller);
     };
   });
 }
+function rewrittenArgs(name, args, rewrite) {
+  if (!rewrite) return args;
+  if (rewrite.name !== name) {
+    throw new Error(`The guard rewrote ${rewrite.name}'s arguments while guarding ${name}`);
+  }
+  return { ...args, ...rewrite.args };
+}
 export {
   CaptionLocale,
   DEVULTUR_ERROR_CODES,

package/dist/locales/es-formal.d.ts

@@ -1,6 +1,7 @@
-import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-B7HNa7Va.js';
+import { VideoPlayerLabels } from '@devultur/react';
+import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-C2nUUY_f.js';
 import { D as DevulturErrorLabels } from '../error-labels-D0Vbp-qA.js';
-import '../types-DZxN6Eij.js';
+import '../types-C0ruHUcu.js';
 import '@devultur/core';
 import 'convex/values';
 import 'convex/server';
@@ -10,5 +11,6 @@ declare const attachmentLabels: AttachmentLabels;
 declare const previewLabels: PreviewLabels;
 declare const mediaLibraryLabels: MediaLibraryLabels;
 declare const mediaPickerLabels: MediaPickerLabels;
+declare const videoPlayerLabels: VideoPlayerLabels;
 
-export { attachmentLabels, devulturErrorLabels, mediaLibraryLabels, mediaPickerLabels, previewLabels };
+export { attachmentLabels, devulturErrorLabels, mediaLibraryLabels, mediaPickerLabels, previewLabels, videoPlayerLabels };

package/dist/locales/es-formal.js

@@ -3,8 +3,9 @@ import {
   devulturErrorLabels,
   mediaLibraryLabels,
   mediaPickerLabels,
-  previewLabels
-} from "../chunk-JZYKPLI4.js";
+  previewLabels,
+  videoPlayerLabels
+} from "../chunk-RDVBE3G3.js";
 import "../chunk-QBHIZBOQ.js";
 import {
   describeDevulturError,
@@ -55,10 +56,12 @@ var mediaPickerLabels2 = {
   dropHint: (multiple) => multiple ? "o suelte los archivos aqu\xED" : "o suelte un archivo aqu\xED",
   uploadError: (error) => describeDevulturError(error, devulturErrorLabels2) ?? `La subida fall\xF3. ${TRY_AGAIN}`
 };
+var videoPlayerLabels2 = videoPlayerLabels;
 export {
   attachmentLabels2 as attachmentLabels,
   devulturErrorLabels2 as devulturErrorLabels,
   mediaLibraryLabels2 as mediaLibraryLabels,
   mediaPickerLabels2 as mediaPickerLabels,
-  previewLabels2 as previewLabels
+  previewLabels2 as previewLabels,
+  videoPlayerLabels2 as videoPlayerLabels
 };

package/dist/locales/es.d.ts

@@ -1,6 +1,7 @@
-import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-B7HNa7Va.js';
+import { VideoPlayerLabels } from '@devultur/react';
+import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-C2nUUY_f.js';
 import { D as DevulturErrorLabels } from '../error-labels-D0Vbp-qA.js';
-import '../types-DZxN6Eij.js';
+import '../types-C0ruHUcu.js';
 import '@devultur/core';
 import 'convex/values';
 import 'convex/server';
@@ -10,5 +11,6 @@ declare const previewLabels: PreviewLabels;
 declare const attachmentLabels: AttachmentLabels;
 declare const mediaLibraryLabels: MediaLibraryLabels;
 declare const mediaPickerLabels: MediaPickerLabels;
+declare const videoPlayerLabels: VideoPlayerLabels;
 
-export { attachmentLabels, devulturErrorLabels, mediaLibraryLabels, mediaPickerLabels, previewLabels };
+export { attachmentLabels, devulturErrorLabels, mediaLibraryLabels, mediaPickerLabels, previewLabels, videoPlayerLabels };

package/dist/locales/es.js

@@ -3,8 +3,9 @@ import {
   devulturErrorLabels,
   mediaLibraryLabels,
   mediaPickerLabels,
-  previewLabels
-} from "../chunk-JZYKPLI4.js";
+  previewLabels,
+  videoPlayerLabels
+} from "../chunk-RDVBE3G3.js";
 import "../chunk-QBHIZBOQ.js";
 import "../chunk-YYOZ3PDH.js";
 export {
@@ -12,5 +13,6 @@ export {
   devulturErrorLabels,
   mediaLibraryLabels,
   mediaPickerLabels,
-  previewLabels
+  previewLabels,
+  videoPlayerLabels
 };

package/dist/{preview-labels-B7HNa7Va.d.ts → preview-labels-C2nUUY_f.d.ts}

@@ -1,4 +1,4 @@
-import { M as MediaRecord } from './types-DZxN6Eij.js';
+import { M as MediaRecord } from './types-C0ruHUcu.js';
 
 /** What an attachment is, for its icon and type label. */
 type AttachmentKind = "image" | "video" | "pdf" | "audio" | "text" | "file";

package/dist/react/hooks.d.ts

@@ -0,0 +1,6 @@
+export { D as DevulturApi, c as DevulturApiContext, d as DevulturContext, e as DevulturContextValue, f as DevulturProgressContext, g as DevulturProgressContextValue, U as UploadOptions, h as UploadedMedia, V as VideoProps, u as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress, m as useMediaUrl, n as useVideoProps } from '../hooks-uqpBd5UF.js';
+import 'react';
+import '@devultur/core';
+import '@devultur/react';
+import 'convex/server';
+import 'convex/values';

package/dist/react/hooks.js

@@ -0,0 +1,23 @@
+"use client";
+import {
+  DevulturApiContext,
+  DevulturContext,
+  DevulturProgressContext,
+  useDevultur,
+  useDevulturApi,
+  useDevulturOptional,
+  useDevulturProgress,
+  useMediaUrl,
+  useVideoProps
+} from "../chunk-BDEO67OT.js";
+export {
+  DevulturApiContext,
+  DevulturContext,
+  DevulturProgressContext,
+  useDevultur,
+  useDevulturApi,
+  useDevulturOptional,
+  useDevulturProgress,
+  useMediaUrl,
+  useVideoProps
+};