@devultur/convex 1.5.0 → 1.5.2

package/README.md

@@ -114,8 +114,11 @@ export const { createUploadUrl, confirmUpload, issueViewerToken, getMedia, listM
 - `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 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.
+- Each function keeps its arguments and returns the component's result, typed: with no annotation,
+  `useQuery(api.devultur.getMedia, { key })` is a `MediaDocument | null` (a `MediaRecord` with its `_id` and
+  `_creationTime`), and `listMediaPage` and `searchMedia` are a `PaginationResult<MediaDocument>`.
+  `DevulturFunctionResults` names every function's result. `<DevulturProvider api={api.devultur}>` takes them as it
+  takes `exposeApi`'s, whose results are the same.
 
 > **`Devultur.exposeApi` has no auth.** It returns the same functions with no guard: anyone who can reach your Convex
 > deployment can create upload URLs, confirm uploads, list the whole library and delete media. It keeps working, but
@@ -273,6 +276,37 @@ function Avatar({ media, fallbackUrl }) {
 }
 ```
 
+`useDevulturOptional()` is non-null under a `<DevulturProvider>` given no `baseUrl` too, where the hooks that build
+URLs throw. `useCanDeliver()` answers that instead: `true` only under a provider with a non-empty `baseUrl`.
+
+```tsx
+function Cover({ media, fallbackUrl }) {
+  if (!useCanDeliver() || !media) return <img src={fallbackUrl} alt="" />;
+  return <Image media={media} alt="" />;
+}
+```
+
+Public media needs nothing more. Private media also needs the viewer token, which a provider may not have yet
+(`lazyToken`) or can't issue (a `<DevulturViewerProvider>` without `issueViewerToken`); `tokenStatus` from
+`useDevultur()` tells, and the components show their error state when it fails.
+
+### Only the hooks
+
+`@devultur/convex/react/hooks` exports the contexts and the hooks that only read them, without the components or
+Convex's client: `useDevultur`, `useDevulturOptional`, `useCanDeliver`, `useDevulturApi`, `useDevulturProgress`,
+`useMediaUrl`, `useVideoProps`, and the `DevulturContext`, `DevulturApiContext` and `DevulturProgressContext` objects.
+The contexts and the hooks that only read them sit in a chunk of their own, apart from `useMediaUrl`, `useVideoProps`
+and `@devultur/core`'s URL helpers, so a shared component that only checks for a provider adds under 0.5 kB gzipped,
+even to the entry of an app that lazy-loads `@devultur/convex/react` on a route:
+
+```tsx
+import { useDevulturOptional } from "@devultur/convex/react/hooks";
+```
+
+They're the very objects `@devultur/convex/react` exports, so a `<DevulturProvider>` or `<DevulturViewerProvider>`
+imported from there fills them. The hooks that call your Convex functions (`useDevulturMedia`, `useVideoState`,
+`useMediaUpload`, `useMediaLibrary`) stay in `@devultur/convex/react`, with the components.
+
 ### When the viewer token can't be issued
 
 `useDevultur()` tells where the viewer token stands:
@@ -290,7 +324,8 @@ there until `retryToken()`: a failed issuance isn't retried on its own. Meanwhil
 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)).
+cookies, sent to the media host (see [Playback metrics](https://github.com/devultur/devultur/blob/main/docs/guides/video-player.md#playback-metrics),
+also in `node_modules/@devultur/convex/docs/guides/video-player.md`).
 `<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
@@ -796,6 +831,8 @@ what's enforced and the caveats.
 ## Documentation
 
 Guides and API reference: [github.com/devultur/devultur/tree/main/docs](https://github.com/devultur/devultur/tree/main/docs).
+The guides this README links to ship with the package, for the installed version, in
+`node_modules/@devultur/convex/docs/guides/`: `video-player.md`, `self-host.md`, `plugins.md` and `object-lock.md`.
 
 ## License
 

package/dist/chunk-AUAWZ5BD.js

@@ -0,0 +1,65 @@
+import {
+  useDevultur
+} from "./chunk-FOBFHC4A.js";
+
+// src/media-url-hooks.ts
+import React2 from "react";
+import {
+  buildMediaUrl,
+  CaptionLocaleLabel,
+  mediaCaptionPath,
+  mediaPath,
+  visibilityFromKey
+} from "@devultur/core";
+
+// src/request-token.ts
+import React from "react";
+function useRequestTokenWhen(session, isNeeded) {
+  const { requestToken, token } = session;
+  const hasToken = token !== null;
+  React.useEffect(() => {
+    if (isNeeded && !hasToken) requestToken();
+  }, [isNeeded, hasToken, requestToken]);
+}
+
+// src/media-url-hooks.ts
+function useMediaUrl(key, options) {
+  const devultur = useDevultur();
+  const { token, baseUrl } = devultur;
+  useRequestTokenWhen(devultur, Boolean(key) && visibilityFromKey(key ?? "") !== "public");
+  return React2.useMemo(() => {
+    if (!key) return null;
+    if (!baseUrl) throw new Error("useMediaUrl requires `baseUrl` on <DevulturProvider>");
+    const isPublic = visibilityFromKey(key) === "public";
+    return buildMediaUrl(baseUrl, key, { ...options, token: isPublic ? void 0 : token ?? void 0 });
+  }, [key, baseUrl, token, options]);
+}
+function useVideoProps(media, options) {
+  const devultur = useDevultur();
+  const { token, baseUrl, sessionSecret } = devultur;
+  useRequestTokenWhen(devultur, media?.kind === "video" && media.visibility === "private");
+  const locales = options?.locales;
+  return React2.useMemo(() => {
+    if (media?.kind !== "video") return null;
+    if (!baseUrl) throw new Error("useVideoProps requires `baseUrl` on <DevulturProvider>");
+    const viewerToken = media.visibility === "private" ? token ?? void 0 : void 0;
+    const captions = (locales ?? []).flatMap((locale) => {
+      const path = mediaCaptionPath(media, locale);
+      if (!path) return [];
+      const label = CaptionLocaleLabel[locale] ?? locale;
+      return [{ locale, label, src: buildMediaUrl(baseUrl, path, { token: viewerToken }) }];
+    });
+    return {
+      src: buildMediaUrl(baseUrl, mediaPath(media), { token: viewerToken }),
+      token: viewerToken,
+      captions,
+      sessionSecret: media.visibility === "private" ? sessionSecret : void 0
+    };
+  }, [media, baseUrl, token, locales, sessionSecret]);
+}
+
+export {
+  useRequestTokenWhen,
+  useMediaUrl,
+  useVideoProps
+};

package/dist/chunk-FOBFHC4A.js

@@ -0,0 +1,55 @@
+// src/capability-error.ts
+var DevulturCapabilityError = class extends Error {
+  code = "capability_unavailable";
+  capability;
+  constructor(capability) {
+    super(
+      `Devultur: \`${capability}\` isn't available under <DevulturViewerProvider>. Use <DevulturProvider api> with the actions it needs.`
+    );
+    this.name = "DevulturCapabilityError";
+    this.capability = capability;
+  }
+};
+
+// src/devultur-context.ts
+import React from "react";
+var DevulturContext = /* @__PURE__ */ React.createContext(null);
+var DevulturApiContext = /* @__PURE__ */ React.createContext(null);
+function useDevultur() {
+  const context = React.use(DevulturContext);
+  if (!context) throw new Error("useDevultur must be used within <DevulturProvider> or <DevulturViewerProvider>");
+  return context;
+}
+function useDevulturOptional() {
+  return React.use(DevulturContext);
+}
+function useCanDeliver() {
+  return Boolean(React.use(DevulturContext)?.baseUrl);
+}
+function useDevulturApi() {
+  const api = React.use(DevulturApiContext);
+  if (api) return api;
+  if (React.use(DevulturContext)) throw new DevulturCapabilityError("api");
+  throw new Error("useDevulturApi must be used within <DevulturProvider>");
+}
+
+// src/progress-context.ts
+import React2 from "react";
+var DevulturProgressContext = /* @__PURE__ */ React2.createContext(null);
+function useDevulturProgress() {
+  const context = React2.use(DevulturProgressContext);
+  if (!context) throw new Error("useDevulturProgress requires progress API in DevulturProvider");
+  return context;
+}
+
+export {
+  DevulturCapabilityError,
+  DevulturContext,
+  DevulturApiContext,
+  useDevultur,
+  useDevulturOptional,
+  useCanDeliver,
+  useDevulturApi,
+  DevulturProgressContext,
+  useDevulturProgress
+};

package/dist/component/http.js

@@ -1,7 +1,7 @@
 import { isBearerOf } from "@devultur/core";
 import { httpRouter } from "convex/server";
-import { internal } from "./_generated/api";
-import { env, httpAction } from "./_generated/server";
+import { internal } from "./_generated/api.js";
+import { env, httpAction } from "./_generated/server.js";
 const http = httpRouter();
 http.route({
     path: "/webhook",

package/dist/component/library.d.ts

@@ -1,6 +1,6 @@
 import { type PaginationOptions, type PaginationResult } from "convex/server";
-import type { Doc } from "./_generated/dataModel";
-import type { QueryCtx } from "./_generated/server";
+import type { Doc } from "./_generated/dataModel.js";
+import type { QueryCtx } from "./_generated/server.js";
 type MediaType = Doc<"media">["type"];
 export declare const BACKFILL_BATCH_SIZE: {
     readonly default: 100;

package/dist/component/library.js

@@ -2,9 +2,9 @@
 // records from before 1.4.0 the `searchText` they were written without.
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
-import { internal } from "./_generated/api";
-import { internalMutation, mutation, query } from "./_generated/server";
-import { missingSearchText } from "./mediaMeta";
+import { internal } from "./_generated/api.js";
+import { internalMutation, mutation, query } from "./_generated/server.js";
+import { missingSearchText } from "./mediaMeta.js";
 const mediaType = v.union(v.literal("video"), v.literal("image"), v.literal("file"));
 /** Longest search kept: Convex matches at most 16 terms, so a longer query only costs. */
 const SEARCH_MAX_LENGTH = 200;

package/dist/component/lock.js

@@ -5,9 +5,9 @@
 // `lock_privilege_required`, `lock_conflict`, ...); see workerErrors.ts.
 import { HOLD_PAGE_SIZE } from "@devultur/core";
 import { v } from "convex/values";
-import { derivativesValidator, retentionModeValidator } from "./lockValidators";
-import { getMediaClient } from "./mediaClient";
-import { workerAction } from "./workerErrors";
+import { derivativesValidator, retentionModeValidator } from "./lockValidators.js";
+import { getMediaClient } from "./mediaClient.js";
+import { workerAction } from "./workerErrors.js";
 const keysValidator = v.array(v.string());
 export const getLock = workerAction({
     args: { key: v.string() },

package/dist/component/mediaClient.js

@@ -1,6 +1,6 @@
 // The component's client of the media Worker, from the env the app mounts the component with.
 import { createWorkerClient } from "@devultur/core";
-import { env } from "./_generated/server";
+import { env } from "./_generated/server.js";
 export function getMediaClient() {
     return createWorkerClient(env.DEVULTUR_SECRET, env.DEVULTUR_API_URL);
 }

package/dist/component/metadata.js

@@ -1,8 +1,8 @@
 // Editing a media record's descriptive metadata (title, alt text, tags). The upload's own facts (size, dimensions,
 // duration, page count) are recorded by `uploads.ts` and the transcode webhook, never edited here.
 import { v } from "convex/values";
-import { mutation } from "./_generated/server";
-import { mediaMetaPatch, searchTextOf } from "./mediaMeta";
+import { mutation } from "./_generated/server.js";
+import { mediaMetaPatch, searchTextOf } from "./mediaMeta.js";
 /**
  * Sets a record's `title`, `alt` and/or `tags` (only the ones passed). Trimmed; an empty title or alt clears it, and
  * tags are deduplicated. Throws `invalid_media_metadata` past the limits (title 200, alt 1000, 20 tags of 50). Returns

package/dist/component/public.js

@@ -1,15 +1,15 @@
 import { DEFAULT_TOKEN_EXPIRY_SECONDS, extractId, MediaEventName, MediaStatus } from "@devultur/core";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
-import { api, internal } from "./_generated/api";
-import { internalMutation, mutation, query } from "./_generated/server";
-import { listNewestFirst } from "./library";
-import { objectLockValidator } from "./lockValidators";
-import { getMediaClient } from "./mediaClient";
-import { missingSearchText, searchTextOf } from "./mediaMeta";
-import { transcodeOutputFields } from "./schema";
-import { UPLOAD_CONFIRM_BACKSTOP_MS } from "./uploads";
-import { workerAction } from "./workerErrors";
+import { api, internal } from "./_generated/api.js";
+import { internalMutation, mutation, query } from "./_generated/server.js";
+import { listNewestFirst } from "./library.js";
+import { objectLockValidator } from "./lockValidators.js";
+import { getMediaClient } from "./mediaClient.js";
+import { missingSearchText, searchTextOf } from "./mediaMeta.js";
+import { transcodeOutputFields } from "./schema.js";
+import { UPLOAD_CONFIRM_BACKSTOP_MS } from "./uploads.js";
+import { workerAction } from "./workerErrors.js";
 // Webhook path RELATIVE to the component. Convex gives the component a `CONVEX_SITE_URL` that ALREADY
 // includes its mount prefix (e.g. `${site}/devultur`), so `${CONVEX_SITE_URL}/webhook` resolves to the
 // mounted route (`${site}/devultur/webhook`) without duplicating the prefix. Do NOT add `/devultur/` here

package/dist/component/uploads.js

@@ -1,11 +1,11 @@
 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 { searchTextOf, validUploadHints } from "./mediaMeta";
-import { parseUploadKey } from "./uploadKeys";
-import { workerAction } from "./workerErrors";
+import { internal } from "./_generated/api.js";
+import { internalAction, internalMutation } from "./_generated/server.js";
+import { getMediaClient } from "./mediaClient.js";
+import { searchTextOf, validUploadHints } from "./mediaMeta.js";
+import { parseUploadKey } from "./uploadKeys.js";
+import { workerAction } from "./workerErrors.js";
 // 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;

package/dist/component/workerErrors.d.ts

@@ -1,5 +1,5 @@
 import { type Value } from "convex/values";
-import { action } from "./_generated/server";
+import { action } from "./_generated/server.js";
 /** `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. */

package/dist/component/workerErrors.js

@@ -4,7 +4,7 @@
 // (`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";
+import { action } from "./_generated/server.js";
 function isApiError(error) {
     if (error instanceof DevulturApiError)
         return true;

package/dist/contexts-6F8TJINX.d.ts

@@ -0,0 +1,149 @@
+import React from 'react';
+import { DevulturMedia, MediaUrlOptions, Visibility } from '@devultur/core';
+import { UploadProgress } from '@devultur/react';
+import { FunctionReference } from 'convex/server';
+import { Value } from 'convex/values';
+
+/** What a viewer token action returns: the token with its lifetime, or the bare token (default lifetime). */
+type ViewerTokenResult = {
+    token: string;
+    expiresIn: number;
+} | string;
+/** Extra arguments sent with `sessionSecret` to the viewer token action. */
+type ViewerTokenArgs = Record<string, Value>;
+/**
+ * Where the viewer token for the current `tokenArgs` stands: not requested yet, being issued (no token yet), held, or
+ * failed (the action threw or returned no token). A renewal in flight, or one that failed, keeps `"ready"`.
+ */
+type TokenStatus = "idle" | "loading" | "ready" | "error";
+
+/** Transform/delivery options for media URLs (without `token`, which the context injects). */
+type MediaRenderOptions = Omit<MediaUrlOptions, "token">;
+/**
+ * The viewer token action: the component's `issueViewerToken` (as `defineDevulturFunctions` or `exposeApi` export it,
+ * where `sessionSecret` is optional) or an app's own, which may require it. The providers always send it.
+ */
+type ViewerTokenAction = FunctionReference<"action", "public", {
+    sessionSecret?: string;
+}>;
+interface MediaSession {
+    token: string | null;
+    /** Where the viewer token stands; `"error"` makes private previews fail fast with `token_unavailable`. */
+    tokenStatus: TokenStatus;
+    /** Why the last issuance failed (the action threw or returned no token), while `tokenStatus` is `"error"`. */
+    tokenError: Error | null;
+    /** Issues the viewer token again (after a failure, for example). Resolves to the new token, or `null`. */
+    retryToken: () => Promise<string | null>;
+    /**
+     * Asks for the viewer token where it's issued lazily (`<DevulturViewerProvider lazyToken>`): the first private media
+     * shown calls it, and so must code that reads `token` itself. A no-op once asked, and where the token is issued
+     * right away (the default).
+     */
+    requestToken: () => void;
+    baseUrl: string | null;
+    /** Browser session secret → sent in `${SESSION_HEADER}` on every private delivery. */
+    sessionSecret: string;
+    /** 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). */
+    getCaptionsText: (media: DevulturMedia, locale: string) => Promise<string>;
+    /**
+     * Re-issues the viewer token (new session fingerprint with the current UA/IP) and updates the context.
+     * Single-flight: concurrent calls share the same issuance. Returns the new token (or null if it
+     * failed). The render uses it to transparently recover from a 401 `session_mismatch`.
+     */
+    reissueToken: () => Promise<string | null>;
+}
+
+type AnyAction = FunctionReference<"action">;
+type AnyMutation = FunctionReference<"mutation">;
+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;
+    /** Requests the transcode of an uploaded video. Required by `useMediaUpload` for auto-process. */
+    processVideo?: AnyAction;
+    getMedia?: AnyQuery;
+    /** The library, newest first. Required by `useMediaLibrary` and `<MediaLibrary>`. */
+    listMediaPage?: AnyQuery;
+    /** The library matching a search. Required by `useMediaLibrary` and `<MediaLibrary>` to search. */
+    searchMedia?: AnyQuery;
+    saveProgress?: AnyMutation;
+    loadProgress?: AnyQuery;
+    markComplete?: AnyMutation;
+    resetProgress?: AnyMutation;
+}
+interface UploadOptions {
+    /**
+     * Visibility override for this resource. Omitted → `config.upload.visibility` on your server, else the Worker's
+     * default by type. Your guard can still rewrite it.
+     */
+    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;
+    /** A PDF's page count to record with it, a hint (`countPdfPages` from `@devultur/convex/pdfjs` counts it). */
+    pageCount?: number;
+}
+/**
+ * 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;
+};
+/**
+ * What `useDevultur()` returns. Under a `<DevulturViewerProvider>`, `uploadUrl`, `upload` and `deleteMedia` throw a
+ * `DevulturCapabilityError` (`capability_unavailable`).
+ */
+interface DevulturContextValue extends MediaSession {
+    uploadUrl: (file: File) => Promise<{
+        url: string;
+        key: string;
+    }>;
+    /** Uploads a file (reporting progress), records it in the component, and returns the reference ready to save. */
+    upload: (file: File, options?: UploadOptions) => Promise<UploadedMedia>;
+    /** Deletes a media by reference: video → full folder; image/file → the object. */
+    deleteMedia: (media: DevulturMedia) => void;
+}
+declare const DevulturContext: React.Context<DevulturContextValue | null>;
+declare const DevulturApiContext: React.Context<DevulturApi | null>;
+declare function useDevultur(): DevulturContextValue;
+/**
+ * `useDevultur()` for components that also render outside a provider: the same value under `<DevulturProvider>` or
+ * `<DevulturViewerProvider>`, and `null` outside both instead of throwing.
+ */
+declare function useDevulturOptional(): DevulturContextValue | null;
+/**
+ * Whether the media hooks can build delivery URLs here: `true` under `<DevulturProvider>` or `<DevulturViewerProvider>`
+ * with a non-empty `baseUrl`; `false` outside both, or under a `<DevulturProvider>` without one, where `useMediaUrl`,
+ * `useVideoProps` and `url()` throw. That's all a public media needs. A private media also needs the viewer token,
+ * which the provider may not have yet (lazy issuance) or can't issue (no `issueViewerToken`): `tokenStatus` from
+ * `useDevultur()` tells, and the components handle it themselves.
+ */
+declare function useCanDeliver(): boolean;
+/**
+ * The `api` passed to `<DevulturProvider>`: your app's exported Devultur functions. Under a `<DevulturViewerProvider>`
+ * it throws a `DevulturCapabilityError`.
+ */
+declare function useDevulturApi(): DevulturApi;
+
+interface DevulturProgressContextValue {
+    save: (videoId: string, position: number) => Promise<void>;
+    load: (videoId: string) => Promise<{
+        lastPosition: number;
+        completedAt: Date | null;
+    } | null>;
+    markComplete: (videoId: string) => Promise<void>;
+    reset: (videoId: string) => Promise<void>;
+}
+declare const DevulturProgressContext: React.Context<DevulturProgressContextValue | null>;
+declare function useDevulturProgress(): DevulturProgressContextValue;
+
+export { type DevulturApi as D, type MediaRenderOptions as M, type TokenStatus as T, type UploadOptions as U, type ViewerTokenAction as V, type ViewerTokenArgs as a, DevulturApiContext as b, DevulturContext as c, type DevulturContextValue as d, DevulturProgressContext as e, type DevulturProgressContextValue as f, type UploadedMedia as g, type ViewerTokenResult as h, useDevultur as i, useDevulturApi as j, useDevulturOptional as k, useDevulturProgress as l, useCanDeliver as u };

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-C0ruHUcu.js';
-export { a as DevulturUploadConfig, P as ProgressRecord } from './types-C0ruHUcu.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.
@@ -468,4 +505,4 @@ declare function defineDevulturFunctions<Visibility extends FunctionVisibility =
  */
 declare function mediaFromRecord(record: MediaRecord): DevulturMedia | null;
 
-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 };
+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

@@ -186,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);
   }

package/dist/react/contexts.d.ts

@@ -0,0 +1,6 @@
+export { D as DevulturApi, b as DevulturApiContext, c as DevulturContext, d as DevulturContextValue, e as DevulturProgressContext, f as DevulturProgressContextValue, U as UploadOptions, g as UploadedMedia, u as useCanDeliver, i as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress } from '../contexts-6F8TJINX.js';
+import 'react';
+import '@devultur/core';
+import '@devultur/react';
+import 'convex/server';
+import 'convex/values';