@devultur/convex 1.4.3 → 1.5.0

package/README.md

@@ -107,8 +107,13 @@ export const { createUploadUrl, confirmUpload, issueViewerToken, getMedia, listM
   signed-in user can't read or overwrite someone else's progress. Return `{ userId, canActForOthers: true }` for a
   caller who may (an admin resetting a learner's progress). A guard that returns no `userId` keeps the browser's, as
   `exposeApi` does: return one whenever the progress functions are exported.
+- The guard may also return a `rewrite`, `{ name, args }`: each key of `args` replaces the caller's argument of that
+  name, on your server, before the function runs (see [Upload visibility](#upload-visibility)). `name` is the guarded
+  operation's, so `args` are typed for it; a rewrite named for another operation throws. The rewritten arguments
+  aren't validated again.
 - `visibility: "internal"` registers them as internal functions, for your own actions and mutations to call.
-- `config` takes what `Devultur.exposeApi` does (transcode preset, caption locales, upload lock).
+- `config` takes what `Devultur.exposeApi` does (transcode preset, caption locales, upload lock and default
+  visibility).
 - Each function keeps its arguments and result types, so `api.devultur.confirmUpload` is typed as before and
   `<DevulturProvider api={api.devultur}>` takes them as it takes `exposeApi`'s.
 
@@ -117,6 +122,44 @@ export const { createUploadUrl, confirmUpload, issueViewerToken, getMedia, listM
 > use it only for a deployment where every caller is trusted, or move to `defineDevulturFunctions`, which takes the
 > same `config`.
 
+## Upload visibility
+
+`config.upload.visibility` sets the visibility of an upload whose caller passes none. Without it, the Worker's default
+by type applies.
+
+```typescript
+export const { createUploadUrl, confirmUpload } = defineDevulturFunctions(devultur, {
+  guard,
+  config: { upload: { visibility: "public" } }, // a site whose uploads are public unless the browser asks otherwise
+});
+```
+
+The browser can still pass `visibility` (`upload(file, { visibility })`, `useMediaUpload({ visibility })`). To decide
+it on your server instead, rewrite it in the guard: the guard's `rewrite` replaces the browser's arguments.
+
+```typescript
+guard: async (ctx, operation) => {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) throw new ConvexError("Sign in first");
+  // Members' uploads are always private, whatever the browser asked for.
+  if (operation.name === "createUploadUrl") {
+    return { userId: identity.subject, rewrite: { name: "createUploadUrl", args: { visibility: "private" } } };
+  }
+  return { userId: identity.subject };
+},
+```
+
+Which one wins, from first to last:
+
+1. The guard's `rewrite.args.visibility`.
+2. The caller's `visibility`.
+3. `config.upload.visibility`.
+4. The Worker's default by type.
+
+The guard sees the caller's arguments as they arrived (`operation.args.visibility` is `undefined` when the browser
+passed none): the config's default is applied after the guard. `config.upload.lock` isn't an argument, so neither
+the browser nor the guard's `rewrite` change it.
+
 ## Upload progress
 
 `upload(file, { onProgress, signal })` reports the PUT's progress and resolves to the stored reference:
@@ -175,7 +218,7 @@ ignored. Your action returns what the component's action returns: `{ token, expi
 ### Display-only apps
 
 An app that only shows media (no uploads, no deletes) uses `<DevulturViewerProvider>`, which needs only the base URL
-and a viewer token action:
+and, for private media, a viewer token action:
 
 ```tsx
 import { DevulturViewerProvider, Preview } from "@devultur/convex/react";
@@ -194,13 +237,49 @@ import { DevulturViewerProvider, Preview } from "@devultur/convex/react";
 that need the `api` (`useDevulturApi`, `useMediaUpload`, `<MediaLibrary>`, `<MediaPicker>`), throw a
 `DevulturCapabilityError` whose `code` is `capability_unavailable`.
 
+Like `<DevulturProvider>`, it issues the viewer token as soon as it mounts. With `lazyToken`, it issues it only when
+a private media is shown, and renews it from then on: while every media on the page is public, it calls nothing,
+`tokenStatus` stays `"idle"` and `token` stays `null`. Code that reads `token` itself then calls
+`useDevultur().requestToken()` first; the built-in components and hooks do it for private media.
+
+```tsx
+<DevulturViewerProvider baseUrl={MEDIA_URL} issueViewerToken={api.devultur.issueViewerToken} lazyToken>
+  <Gallery />
+</DevulturViewerProvider>
+```
+
+When all the media is public, leave `issueViewerToken` out. The provider then needs no Convex client and issues
+nothing:
+
+```tsx
+<DevulturViewerProvider baseUrl={MEDIA_URL}>
+  <Image media={post.cover} alt={post.title} />
+</DevulturViewerProvider>
+```
+
+A private media shown under it fails with `token_unavailable`, and `tokenError` says the provider has no
+`issueViewerToken`.
+
+### Components outside a provider
+
+`useDevultur()` throws outside `<DevulturProvider>` and `<DevulturViewerProvider>`. A component that also renders
+without one uses `useDevulturOptional()`, which returns the same value, or `null` outside both:
+
+```tsx
+function Avatar({ media, fallbackUrl }) {
+  const devultur = useDevulturOptional();
+  if (!devultur || !media) return <img src={fallbackUrl} alt="" />;
+  return <Image media={media} alt="" width={64} />;
+}
+```
+
 ### When the viewer token can't be issued
 
 `useDevultur()` tells where the viewer token stands:
 
 ```tsx
 const { tokenStatus, tokenError, retryToken } = useDevultur();
-// tokenStatus: "idle" | "loading" | "ready" | "error"
+// tokenStatus: "idle" (not asked for yet) | "loading" | "ready" | "error"
 if (tokenStatus === "error") return <button onClick={retryToken}>Try again</button>; // tokenError has why
 ```
 
@@ -210,6 +289,10 @@ there until `retryToken()`: a failed issuance isn't retried on its own. Meanwhil
 `<Preview>` passes it to its `fallback`, `<PdfThumbnail>` and `<Image>` render their `fallback` (`<Image onLoadError>`
 receives it), and `<DownloadLink onDownloadError>` receives it on click. They load once `retryToken()` gets a token.
 
+`<Preview>`'s video plays in `<VideoPlayer>` from `@devultur/react`, with its playback metrics on: anonymous, no
+cookies, sent to the media host (see [Playback metrics](https://github.com/devultur/devultur/blob/main/docs/guides/video-player.md#playback-metrics)).
+`<Preview metrics={false}>` turns them off. A private video shows `loading` until its viewer token is issued.
+
 `<Preview>`'s video re-issues the token once when the delivery answers the playlist or a segment with a 401
 `session_mismatch`; after that, or on any other 401, it renders its `fallback` with `session_mismatch` or
 `token_unavailable`. `<VideoPlayer onError>` (from `@devultur/react`) reports these failures when you render the
@@ -658,8 +741,8 @@ the same name.
 
 `@devultur/convex/locales/es` addresses the reader with «tú» ("Vuelve a intentarlo"). For «usted» ("Vuelva a
 intentarlo", "No tiene permiso…"), import the same names from `@devultur/convex/locales/es-formal`: it exports exactly
-what `locales/es` does (error, attachment, preview, library and picker labels), and differs only in the strings that
-address the reader.
+what `locales/es` does (error, attachment, preview, library, picker and video player labels), and differs only in the
+strings that address the reader.
 
 ```tsx
 import { describeDevulturError } from "@devultur/convex";
@@ -685,6 +768,18 @@ Pass a partial map to change some messages and keep the rest, or a full one for
 describeDevulturError(error, { ...spanishLabels, lock_conflict: "Alguien más acaba de cambiarlo." });
 ```
 
+### Video player labels
+
+`<VideoPlayer>` from `@devultur/react` takes `labels` like the components here do. Both Spanish locales export
+`videoPlayerLabels`:
+
+```tsx
+import { VideoPlayer } from "@devultur/react";
+import { videoPlayerLabels } from "@devultur/convex/locales/es";
+
+<VideoPlayer {...useVideoProps(lesson.video)} labels={videoPlayerLabels} />;
+```
+
 ## Object lock
 
 - `devultur.createUploadUrl(ctx, { filename, contentType, lock, hold })` locks a file from its first write.

package/dist/{chunk-JZYKPLI4.js → chunk-RDVBE3G3.js}

@@ -175,11 +175,30 @@ var mediaPickerLabels = {
   removed: (name) => `${name} se quit\xF3.`,
   cleared: "Se limpi\xF3 la selecci\xF3n."
 };
+var videoPlayerLabels = {
+  player: "Reproductor de video",
+  controls: "Controles del video",
+  play: "Reproducir",
+  pause: "Pausar",
+  seek: "Posici\xF3n del video",
+  mute: "Silenciar",
+  unmute: "Activar el sonido",
+  volume: "Volumen",
+  captions: "Subt\xEDtulos",
+  captionsOff: "Desactivados",
+  quality: "Calidad del video",
+  qualityAuto: "Autom\xE1tica",
+  speed: "Velocidad de reproducci\xF3n",
+  speedNormal: "Normal",
+  fullscreen: "Pantalla completa",
+  exitFullscreen: "Salir de pantalla completa"
+};
 
 export {
   devulturErrorLabels,
   previewLabels,
   attachmentLabels,
   mediaLibraryLabels,
-  mediaPickerLabels
+  mediaPickerLabels,
+  videoPlayerLabels
 };

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { ObjectLock, LockView, SetLockOptions, HoldPage, DevulturMedia } from '@
 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 { 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 { D as DevulturComponentConfig, M as MediaRecord } from './types-C0ruHUcu.js';
+export { a as DevulturUploadConfig, P as ProgressRecord } 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';
 
@@ -430,15 +430,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 +468,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, Devultur, type DevulturArgsRewrite, DevulturComponentConfig, type DevulturErrorData, type DevulturFunctionsOptions, type DevulturGuard, type DevulturGuardCtx, type DevulturGuardResult, type DevulturOperation, MediaRecord, 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.
@@ -263,11 +274,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";