@devultur/convex 1.4.3 → 1.5.1

package/dist/react.d.ts

@@ -1,59 +1,16 @@
 import React from 'react';
-import { DevulturMedia, MediaUrlOptions, Visibility, ProcessingPhase, FailureReason, MediaStatusValue } from '@devultur/core';
-import { BakeOutputFormat, MediaUploadState, MediaUploadError, UploadProgress } from '@devultur/react';
+import { V as VideoProps, a as ViewerTokenAction, b as ViewerTokenArgs, D as DevulturApi } from './hooks-uqpBd5UF.js';
+export { c as DevulturApiContext, d as DevulturContext, e as DevulturContextValue, f as DevulturProgressContext, g as DevulturProgressContextValue, T as TokenStatus, U as UploadOptions, h as UploadedMedia, i as ViewerTokenResult, u as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress, m as useMediaUrl, n as useVideoProps } from './hooks-uqpBd5UF.js';
+import { 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-B7HNa7Va.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-B7HNa7Va.js';
-import { Value } from 'convex/values';
-import { M as MediaRecord } from './types-DZxN6Eij.js';
+import { A as AttachmentLabels, b as MediaFetchError, M as MediaLibraryLabels, P as PreviewLabels, a as MediaPickerLabels } 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 { Visibility, DevulturMedia, MediaUrlOptions, MediaStatusValue, ProcessingPhase, FailureReason } from '@devultur/core';
+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';
-
-/** 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>;
-    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>;
-}
+import 'convex/server';
+import 'convex/values';
 
 /** What `useDevultur()` can do only under a `<DevulturProvider>` given the matching actions. */
 type DevulturCapability = "upload" | "uploadUrl" | "deleteMedia" | "api";
@@ -159,6 +116,27 @@ interface AttachmentCardProps extends Omit<React.HTMLAttributes<HTMLElement>, "c
  */
 declare function AttachmentCard({ media, contentType, onOpen, preview, headingLevel, locale, labels, ...articleProps }: AttachmentCardProps): React.JSX.Element | null;
 
+interface DownloadLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "download" | "media"> {
+    media: DevulturMedia | null | undefined;
+    /** Name it downloads as. Without this it uses the upload's original name. */
+    filename?: string;
+    /**
+     * A private download that failed: `token_unavailable` right away when the viewer token couldn't be issued
+     * (`useDevultur().retryToken()` tries again), `http_error` when the delivery refused it.
+     */
+    onDownloadError?: (error: MediaFetchError) => void;
+    children: React.ReactNode;
+}
+/**
+ * `<a>` that downloads a media with its original name (token-transparent). The worker serves it with
+ * `Content-Disposition: attachment`, so a click downloads the file instead of opening it in a tab.
+ *
+ * Private: an `<a download>` NAVIGATES, and a navigation can't send `${SESSION_HEADER}` → with session
+ * binding the gate gives a 401. So, for private media, we intercept the click, blob-fetch with the header
+ * (like private `<Image>`) and trigger the download from the object URL. Public keeps native navigation.
+ */
+declare function DownloadLink({ media, filename, onDownloadError, children, ...anchorProps }: DownloadLinkProps): React.JSX.Element | null;
+
 /** An explicit `srcSet` is passed through to the `<img>` as is, and wins over the one `widths` builds. */
 interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
     /** Typed reference. `null`/`undefined` → renders `fallback` (or `externalFallback`). Its `alt` is the default `alt`. */
@@ -200,6 +178,68 @@ interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "sr
  */
 declare function Image({ media, width, height, fit, format, quality, widths, sizes, fallback, externalFallback, render, alt, onLoadError, ...imgProps }: ImageProps): React.JSX.Element;
 
+interface MediaStatusReturn {
+    status: MediaStatusValue;
+    /** Typed progress: `phase` is the pipeline step (no `as any`). */
+    progress: {
+        current: number;
+        total: number;
+        percent: number;
+        phase?: ProcessingPhase;
+    } | null;
+    error: string | null;
+    /** Categorized failure reason (null if it didn't fail). */
+    failureReason: FailureReason | null;
+    /** Whether the failure is retriable (null if it didn't fail). */
+    retriable: boolean | null;
+    isQueued: boolean;
+    isTranscoding: boolean;
+    isCaptioning: boolean;
+    isReady: boolean;
+    isFailed: boolean;
+    playlistUrl: string | null;
+    thumbnailKey: string | null;
+    captionLocales: string[];
+    duration: number | null;
+    isLoading: boolean;
+}
+declare function useDevulturMedia(key: string | null | undefined): MediaStatusReturn;
+interface CaptionTrack {
+    locale: string;
+    label: string;
+    src: string;
+}
+/**
+ * A video's pipeline state as a **discriminated union** on `phase`: the render is an exhaustive
+ * `switch` (no boolean ordering or `as any`), and adding a new phase is a compile error until it's
+ * handled. `processing` carries typed `step`/`percent`; `ready` carries the ref + props ready for
+ * `<VideoPlayer>` (token-transparent); `failed` carries a categorized `reason` + `retriable`.
+ */
+type VideoState = {
+    phase: "idle";
+} | {
+    phase: "queued";
+} | {
+    phase: "processing";
+    step: ProcessingPhase;
+    percent: number;
+} | {
+    phase: "ready";
+    media: DevulturMedia;
+    playlist: string;
+    duration: number;
+    captions: CaptionTrack[];
+    playerProps: VideoProps;
+} | {
+    phase: "failed";
+    reason: FailureReason;
+    message: string;
+    retriable: boolean;
+};
+declare function useVideoState(media: DevulturMedia | null | undefined, options?: {
+    locales?: string[];
+}): VideoState;
+
 /** What `renderItem` gets besides the record. */
 interface MediaLibraryItemState {
     /** The record's reference (`mediaFromRecord`), `null` for a record without a visibility. */
@@ -528,6 +568,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
@@ -538,7 +583,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";
@@ -577,228 +622,8 @@ 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;
-}
-/**
- * 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;
-}
-interface ProgressContextValue {
-    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>;
-}
-interface DevulturProviderProps {
-    api: DevulturApi;
-    /** Media worker base (e.g. `https://media.your-domain.com`). Required for `useMediaUrl`. */
-    baseUrl?: string;
-    /**
-     * Extra arguments sent with `sessionSecret` on every viewer token issuance (first, renewal and re-issue), for
-     * example `{ workspaceId }`. Compared by value: when they change, the current token is dropped and a new one is
-     * issued. The component's own `issueViewerToken` accepts only `sessionSecret`, so pass your own action in
-     * `issueViewerToken` that takes these arguments.
-     */
-    tokenArgs?: ViewerTokenArgs;
-    /**
-     * Your own viewer token action, used instead of `api.issueViewerToken`. It receives `{ sessionSecret, ...tokenArgs }`
-     * and returns what the component's `issueViewerToken` returns.
-     */
-    issueViewerToken?: ViewerTokenAction;
-    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
- * never touches the token or the query — it only declares what it wants (download, resize, etc.).
- *
- * @example
- * <img src={useMediaUrl(key)} />
- * <a href={useMediaUrl(key, { download: true })} download>Download</a>
- * <img src={useMediaUrl(key, { width: 512, format: "webp" })} />
- */
-declare function useMediaUrl(key: string | null | undefined, options?: MediaRenderOptions): string | null;
-interface VideoProps {
-    src: string;
-    token: string | undefined;
-    captions: {
-        locale: string;
-        label: string;
-        src: string;
-    }[];
-    /** Session secret → `<VideoPlayer>` sends it in `${SESSION_HEADER}` on hls.js/captions requests. */
-    sessionSecret?: string;
-}
-/**
- * Token-transparent props for `<VideoPlayer>` from a video reference: builds the HLS playlist `src`,
- * the viewer `token` (only if private), and the `captions` for the requested locales.
- * The consumer just does `<VideoPlayer {...useVideoProps(lesson.video, { locales })} />`.
- */
-declare function useVideoProps(media: DevulturMedia | null | undefined, options?: {
-    locales?: string[];
-}): VideoProps | null;
-interface DownloadLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "download" | "media"> {
-    media: DevulturMedia | null | undefined;
-    /** Name it downloads as. Without this it uses the upload's original name. */
-    filename?: string;
-    /**
-     * A private download that failed: `token_unavailable` right away when the viewer token couldn't be issued
-     * (`useDevultur().retryToken()` tries again), `http_error` when the delivery refused it.
-     */
-    onDownloadError?: (error: MediaFetchError) => void;
-    children: React.ReactNode;
-}
-/**
- * `<a>` that downloads a media with its original name (token-transparent). The worker serves it with
- * `Content-Disposition: attachment`, so a click downloads the file instead of opening it in a tab.
- *
- * Private: an `<a download>` NAVIGATES, and a navigation can't send `${SESSION_HEADER}` → with session
- * binding the gate gives a 401. So, for private media, we intercept the click, blob-fetch with the header
- * (like private `<Image>`) and trigger the download from the object URL. Public keeps native navigation.
- */
-declare function DownloadLink({ media, filename, onDownloadError, children, ...anchorProps }: DownloadLinkProps): React.JSX.Element | null;
-interface MediaStatusReturn {
-    status: MediaStatusValue;
-    /** Typed progress: `phase` is the pipeline step (no `as any`). */
-    progress: {
-        current: number;
-        total: number;
-        percent: number;
-        phase?: ProcessingPhase;
-    } | null;
-    error: string | null;
-    /** Categorized failure reason (null if it didn't fail). */
-    failureReason: FailureReason | null;
-    /** Whether the failure is retriable (null if it didn't fail). */
-    retriable: boolean | null;
-    isQueued: boolean;
-    isTranscoding: boolean;
-    isCaptioning: boolean;
-    isReady: boolean;
-    isFailed: boolean;
-    playlistUrl: string | null;
-    thumbnailKey: string | null;
-    captionLocales: string[];
-    duration: number | null;
-    isLoading: boolean;
-}
-declare function useDevulturMedia(key: string | null | undefined): MediaStatusReturn;
-interface CaptionTrack {
-    locale: string;
-    label: string;
-    src: string;
-}
-/**
- * A video's pipeline state as a **discriminated union** on `phase`: the render is an exhaustive
- * `switch` (no boolean ordering or `as any`), and adding a new phase is a compile error until it's
- * handled. `processing` carries typed `step`/`percent`; `ready` carries the ref + props ready for
- * `<VideoPlayer>` (token-transparent); `failed` carries a categorized `reason` + `retriable`.
- */
-type VideoState = {
-    phase: "idle";
-} | {
-    phase: "queued";
-} | {
-    phase: "processing";
-    step: ProcessingPhase;
-    percent: number;
-} | {
-    phase: "ready";
-    media: DevulturMedia;
-    playlist: string;
-    duration: number;
-    captions: CaptionTrack[];
-    playerProps: VideoProps;
-} | {
-    phase: "failed";
-    reason: FailureReason;
-    message: string;
-    retriable: boolean;
-};
-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;
@@ -829,4 +654,61 @@ 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 };
+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;
+}
+/**
+ * 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>
+ */
+declare function DevulturViewerProvider({ issueViewerToken, ...props }: DevulturViewerProviderProps): React.JSX.Element;
+
+interface DevulturProviderProps {
+    api: DevulturApi;
+    /** Media worker base (e.g. `https://media.your-domain.com`). Required for `useMediaUrl`. */
+    baseUrl?: string;
+    /**
+     * Extra arguments sent with `sessionSecret` on every viewer token issuance (first, renewal and re-issue), for
+     * example `{ workspaceId }`. Compared by value: when they change, the current token is dropped and a new one is
+     * issued. The component's own `issueViewerToken` accepts only `sessionSecret`, so pass your own action in
+     * `issueViewerToken` that takes these arguments.
+     */
+    tokenArgs?: ViewerTokenArgs;
+    /**
+     * Your own viewer token action, used instead of `api.issueViewerToken`. It receives `{ sessionSecret, ...tokenArgs }`
+     * and returns what the component's `issueViewerToken` returns.
+     */
+    issueViewerToken?: ViewerTokenAction;
+    children: React.ReactNode;
+}
+declare function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children }: DevulturProviderProps): React.JSX.Element;
+
+export { AttachmentCard, type AttachmentCardProps, AttachmentLabels, type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturApi, type DevulturCapability, DevulturCapabilityError, DevulturProvider, DevulturViewerProvider, type DevulturViewerProviderProps, DocumentLink, type DocumentLinkProps, DownloadLink, type DownloadLinkProps, 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 MediaStatusReturn, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, PreviewLabels, type PreviewProps, type UseMediaLibraryOptions, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, VideoProps, type VideoState, ViewerTokenArgs, matchesAccept, useDevulturMedia, useMediaLibrary, useMediaObjectUrl, useMediaPicker, useMediaUpload, useVideoState };