@devultur/convex 1.4.2 → 1.5.0

package/dist/react.d.ts

@@ -1,12 +1,12 @@
 import React from 'react';
 import { DevulturMedia, MediaUrlOptions, Visibility, ProcessingPhase, FailureReason, MediaStatusValue } from '@devultur/core';
-import { BakeOutputFormat, MediaUploadState, MediaUploadError, UploadProgress } from '@devultur/react';
+import { UploadProgress, BakeOutputFormat, MediaUploadState, MediaUploadError } from '@devultur/react';
 export { MediaUploadError, MediaUploadState, UploadProgress } from '@devultur/react';
 import { FunctionReference } from 'convex/server';
-import { A as AttachmentLabels, M as MediaLibraryLabels, P as PreviewLabels, a as MediaPickerLabels, b as MediaFetchError } from './preview-labels-B-2mra1h.js';
-export { c as AttachmentKind, d as MediaFetchErrorCode, e as defaultAttachmentLabels, f as defaultMediaLibraryLabels, g as defaultMediaPickerLabels, h as defaultPreviewLabels, i as formatDuration, j as formatFileSize } from './preview-labels-B-2mra1h.js';
 import { Value } from 'convex/values';
-import { M as MediaRecord } from './types-LrusGVDf.js';
+import { A as AttachmentLabels, M as MediaLibraryLabels, P as PreviewLabels, a as MediaPickerLabels, b as MediaFetchError } from './preview-labels-C2nUUY_f.js';
+export { c as AttachmentKind, d as MediaFetchErrorCode, e as defaultAttachmentLabels, f as defaultMediaLibraryLabels, g as defaultMediaPickerLabels, h as defaultPreviewLabels, i as formatDuration, j as formatFileSize } from './preview-labels-C2nUUY_f.js';
+import { M as MediaRecord } from './types-C0ruHUcu.js';
 import { P as PdfjsLoader } from './pdf-render-BwJGagvz.js';
 export { a as PdfjsModule } from './pdf-render-BwJGagvz.js';
 
@@ -25,8 +25,12 @@ 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;
+    sessionSecret?: string;
 }>;
 interface MediaSession {
     token: string | null;
@@ -36,6 +40,12 @@ interface MediaSession {
     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;
@@ -51,6 +61,75 @@ interface MediaSession {
     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 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;
+/**
+ * The `api` passed to `<DevulturProvider>`: your app's exported Devultur functions. Under a `<DevulturViewerProvider>`
+ * it throws a `DevulturCapabilityError`.
+ */
+declare function useDevulturApi(): DevulturApi;
+
 /** What `useDevultur()` can do only under a `<DevulturProvider>` given the matching actions. */
 type DevulturCapability = "upload" | "uploadUrl" | "deleteMedia" | "api";
 /**
@@ -442,12 +521,13 @@ type MediaPickerProps = CommonProps & (SingleValueProps | MultipleValueProps);
  * @example
  * <MediaPicker accept={["image/*"]} value={cover} onChange={setCover} />
  */
-declare function MediaPicker(props: MediaPickerProps): React.JSX.Element;
-declare namespace MediaPicker {
-    var Upload: typeof MediaPickerUpload;
-    var Library: typeof MediaPickerLibrary;
-    var Selection: typeof MediaPickerSelection;
-}
+declare function MediaPickerRoot(props: MediaPickerProps): React.JSX.Element;
+declare const MediaPicker: typeof MediaPickerRoot & {
+    displayName: string;
+    Upload: typeof MediaPickerUpload;
+    Library: typeof MediaPickerLibrary;
+    Selection: typeof MediaPickerSelection;
+};
 
 /** A file's name and type, or a record's filename and content type. */
 interface Candidate {
@@ -523,6 +603,11 @@ interface PreviewProps {
     pdfWorkerSrc?: string;
     /** Overrides any string shown or announced; wins over `PdfPreviewProvider`'s `labels`. English by default. */
     labels?: Partial<PreviewLabels>;
+    /**
+     * A video's playback metrics (`<VideoPlayer metrics>`): anonymous, no cookies, sent to the media host. On by
+     * default; `false` turns them off.
+     */
+    metrics?: boolean;
 }
 /**
  * Renders a media inline by its content type: images in an `<img>`, PDFs on `<canvas>` pages with pdf.js under a
@@ -533,7 +618,7 @@ interface PreviewProps {
  * @example
  * <Preview media={document.file} maxBytes={20_000_000} className="h-[80vh] w-full" />
  */
-declare function Preview({ media, contentType, fallback, loading, labels, ...viewProps }: PreviewProps): React.JSX.Element | null;
+declare function Preview({ media, contentType, fallback, loading, labels, metrics, ...viewProps }: PreviewProps): React.JSX.Element | null;
 
 /** How a content type renders inline: `<img>`, a PDF view (pdf.js canvases or `<iframe>`), `<audio>` or `<pre>`. */
 type PreviewKind = "image" | "pdf" | "audio" | "text";
@@ -572,60 +657,43 @@ interface MediaLibraryState {
  */
 declare function useMediaLibrary(options?: UseMediaLibraryOptions): MediaLibraryState;
 
-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 → inherits the router's default by type. */
-    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;
+interface DevulturViewerProviderProps {
+    /** Media worker base (e.g. `https://media.your-domain.com`). */
+    baseUrl: string;
+    /**
+     * Your viewer token action. It receives `{ sessionSecret, ...tokenArgs }`, like `<DevulturProvider>`'s. Leave it
+     * out when every media is public: the provider then needs no Convex client, issues nothing, and a private media
+     * fails with `token_unavailable`.
+     */
+    issueViewerToken?: ViewerTokenAction;
+    /**
+     * `true` → the token is issued only once a private media is shown (and renewed from then on), so a page of public
+     * media calls nothing. Code that reads `token` itself then calls `requestToken()` first. Default `false`: issued
+     * as soon as the provider mounts.
+     */
+    lazyToken?: boolean;
+    /** Extra arguments for `issueViewerToken`, compared by value (see `<DevulturProvider tokenArgs>`). */
+    tokenArgs?: ViewerTokenArgs;
+    children: React.ReactNode;
 }
 /**
- * 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`).
+ * A provider for apps that only display media: `<Image>`, `<Preview>`, `<DownloadLink>`, `useMediaObjectUrl` and the
+ * video hooks work, and it needs no upload or delete actions. It issues and renews the viewer token (with `lazyToken`,
+ * only once a private media is shown). Without `issueViewerToken` it needs no Convex client at all. `upload`, `uploadUrl` and `deleteMedia` throw a `DevulturCapabilityError`, as do the hooks that
+ * need the `api` (`useMediaUpload`, `useDevulturApi`, `<MediaLibrary>`, `<MediaPicker>`).
+ *
+ * @example
+ * <DevulturViewerProvider baseUrl={MEDIA_URL} issueViewerToken={api.admin.issueViewerToken} tokenArgs={{ workspaceId }}>
+ *   <Preview media={document.file} />
+ * </DevulturViewerProvider>
+ *
+ * // Only public media: no token action, no Convex client.
+ * <DevulturViewerProvider baseUrl={MEDIA_URL}>
+ *   <Image media={post.cover} alt="" />
+ * </DevulturViewerProvider>
  */
-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 function DevulturViewerProvider({ issueViewerToken, ...props }: DevulturViewerProviderProps): React.JSX.Element;
+
 interface ProgressContextValue {
     save: (videoId: string, position: number) => Promise<void>;
     load: (videoId: string) => Promise<{
@@ -654,33 +722,6 @@ interface DevulturProviderProps {
     children: React.ReactNode;
 }
 declare function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children }: DevulturProviderProps): React.JSX.Element;
-declare function useDevultur(): DevulturContextValue;
-/**
- * The `api` passed to `<DevulturProvider>`: your app's exported Devultur functions. Under a `<DevulturViewerProvider>`
- * it throws a `DevulturCapabilityError`.
- */
-declare function useDevulturApi(): DevulturApi;
-interface DevulturViewerProviderProps {
-    /** Media worker base (e.g. `https://media.your-domain.com`). */
-    baseUrl: string;
-    /** Your viewer token action. It receives `{ sessionSecret, ...tokenArgs }`, like `<DevulturProvider>`'s. */
-    issueViewerToken: ViewerTokenAction;
-    /** Extra arguments for `issueViewerToken`, compared by value (see `<DevulturProvider tokenArgs>`). */
-    tokenArgs?: ViewerTokenArgs;
-    children: React.ReactNode;
-}
-/**
- * A provider for apps that only display media: it issues and renews the viewer token, so `<Image>`, `<Preview>`,
- * `<DownloadLink>`, `useMediaObjectUrl` and the video hooks work, and it needs no upload or delete actions. `upload`,
- * `uploadUrl` and `deleteMedia` throw a `DevulturCapabilityError`, as do the hooks that need the `api`
- * (`useMediaUpload`, `useDevulturApi`, `<MediaLibrary>`, `<MediaPicker>`).
- *
- * @example
- * <DevulturViewerProvider baseUrl={MEDIA_URL} issueViewerToken={api.admin.issueViewerToken} tokenArgs={{ workspaceId }}>
- *   <Preview media={document.file} />
- * </DevulturViewerProvider>
- */
-declare function DevulturViewerProvider({ baseUrl, issueViewerToken, tokenArgs, children, }: DevulturViewerProviderProps): React.JSX.Element;
 declare function useDevulturProgress(): ProgressContextValue;
 /**
  * Ready-to-use delivery URL for a key, with the context's viewer token already injected. The consumer
@@ -793,7 +834,7 @@ declare function useVideoState(media: DevulturMedia | null | undefined, options?
     locales?: string[];
 }): VideoState;
 interface UseMediaUploadOptions {
-    /** Resource visibility. Omitted → config default → private (secure-by-default). */
+    /** Resource visibility. Omitted → `config.upload.visibility`, else the Worker's default by type. Your guard can rewrite it. */
     visibility?: Visibility;
     /** Fires ONCE, at the persistence point (PUT done + transcode requested). */
     onComplete?: (media: DevulturMedia) => void;
@@ -824,4 +865,4 @@ interface UseMediaUploadReturn {
  */
 declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
 
-export { AttachmentCard, type AttachmentCardProps, AttachmentLabels, type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, type DevulturApi, type DevulturCapability, DevulturCapabilityError, DevulturProvider, DevulturViewerProvider, DocumentLink, type DocumentLinkProps, DownloadLink, Image, type ImageProps, MediaFetchError, MediaLibrary, type MediaLibraryItemState, MediaLibraryLabels, type MediaLibraryPart, type MediaLibraryProps, type MediaLibraryState, type MediaLibraryStatus, type MediaObjectUrl, MediaPicker, MediaPickerLabels, type MediaPickerLibraryProps, type MediaPickerProps, type MediaPickerSelectionProps, type MediaPickerState, type MediaPickerUpload$1 as MediaPickerUpload, type MediaPickerUploadProps, type MediaPickerUploads, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, PreviewLabels, type PreviewProps, type TokenStatus, type UploadedMedia, type UseMediaLibraryOptions, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, type ViewerTokenArgs, type ViewerTokenResult, matchesAccept, useDevultur, useDevulturApi, useDevulturMedia, useDevulturProgress, useMediaLibrary, useMediaObjectUrl, useMediaPicker, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };
+export { AttachmentCard, type AttachmentCardProps, AttachmentLabels, type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, type DevulturApi, type DevulturCapability, DevulturCapabilityError, type DevulturContextValue, DevulturProvider, DevulturViewerProvider, type DevulturViewerProviderProps, DocumentLink, type DocumentLinkProps, DownloadLink, Image, type ImageProps, MediaFetchError, MediaLibrary, type MediaLibraryItemState, MediaLibraryLabels, type MediaLibraryPart, type MediaLibraryProps, type MediaLibraryState, type MediaLibraryStatus, type MediaObjectUrl, MediaPicker, MediaPickerLabels, type MediaPickerLibraryProps, type MediaPickerProps, type MediaPickerSelectionProps, type MediaPickerState, type MediaPickerUpload$1 as MediaPickerUpload, type MediaPickerUploadProps, type MediaPickerUploads, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, PreviewLabels, type PreviewProps, type TokenStatus, type UploadOptions, type UploadedMedia, type UseMediaLibraryOptions, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, type ViewerTokenArgs, type ViewerTokenResult, matchesAccept, useDevultur, useDevulturApi, useDevulturMedia, useDevulturOptional, useDevulturProgress, useMediaLibrary, useMediaObjectUrl, useMediaPicker, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };