@devultur/convex 1.2.0 → 1.3.1

package/README.md

@@ -83,8 +83,8 @@ await saveCover({ cover: media }); // a DevulturMedia: stores as-is in a dv.medi
 ```
 
 The PUT goes through `XMLHttpRequest` (`fetch` reports no upload progress), in parts for large files. `key` is an
-optional field of `DevulturMedia` and of `dv.media()` (since 1.1.0), so references stored without it stay valid. It
-is informational: delivery URLs are still derived from `id`, `kind`, `visibility` and `filename`.
+optional field of `DevulturMedia` and of `dv.media()`. It is informational: delivery URLs are derived from `id`,
+`kind`, `visibility` and `filename`.
 
 ## Media library
 
@@ -148,12 +148,11 @@ exposed functions: export your own action that checks `ctx.auth` and then calls
 The caller only names the key: the record's visibility, size and content type come from the Worker's `HEAD` of the
 object, never from the arguments.
 
-`deleteMedia` removes an image's or a file's record once
-the Worker deleted the object (a delete refused by a lock keeps it). `deleteVideo` removes a video's.
+`deleteMedia` removes an image's or a file's record once the Worker
+deleted the object (a delete refused by a lock keeps it). `deleteVideo` removes a video's.
 
-Records from before 1.1.0 (and a video only `processVideo` recorded) have no `visibility` or `objectKey`;
-`mediaFromRecord` returns `null` for them. Nothing needs migrating: the new fields are optional. `listMedia` doesn't
-report an object's lock: read it from an action with `devultur.getLock(ctx, record.objectKey)`.
+A video only `processVideo` recorded has no `visibility` or `objectKey`, and `mediaFromRecord` returns `null` for
+it. `listMedia` doesn't report an object's lock: read it from an action with `devultur.getLock(ctx, record.objectKey)`.
 
 ## Using a self-hosted Worker
 

package/dist/pdf-render-CiCK6V1X.d.ts

@@ -0,0 +1,43 @@
+interface PdfViewport {
+    width: number;
+    height: number;
+}
+interface PdfRenderTask {
+    promise: Promise<void>;
+    cancel(): void;
+}
+interface PdfPage {
+    getViewport(parameters: {
+        scale: number;
+    }): PdfViewport;
+    render(parameters: {
+        canvas: HTMLCanvasElement | null;
+        viewport: PdfViewport;
+    }): PdfRenderTask;
+    getTextContent(): Promise<{
+        items: ReadonlyArray<object>;
+    }>;
+    cleanup(): unknown;
+}
+interface PdfDocument {
+    numPages: number;
+    getPage(pageNumber: number): Promise<PdfPage>;
+}
+interface PdfLoadingTask {
+    promise: Promise<PdfDocument>;
+    /** Destroys the document and its worker (pdf.js 6 has no `PDFDocumentProxy.destroy`). */
+    destroy(): Promise<void>;
+}
+/** The parts of `pdfjs-dist` (legacy build) that the previews use. */
+interface PdfjsModule {
+    GlobalWorkerOptions: {
+        workerSrc: string;
+    };
+    getDocument(source: {
+        data: Uint8Array;
+    }): PdfLoadingTask;
+}
+/** Imports pdf.js, e.g. `() => import("pdfjs-dist/legacy/build/pdf.mjs")`. */
+type PdfjsLoader = () => Promise<PdfjsModule>;
+
+export type { PdfjsModule as P, PdfjsLoader as a };

package/dist/pdfjs.d.ts

@@ -0,0 +1,11 @@
+import { P as PdfjsModule } from './pdf-render-CiCK6V1X.js';
+
+/** The worker next to the legacy build, resolved by your bundler from this package. */
+declare const defaultPdfWorkerSrc: () => string;
+/**
+ * Imports the pdf.js legacy build (Safari and iOS 18+; the modern build needs iOS 26.2) and, unless a worker is set
+ * already, points `GlobalWorkerOptions.workerSrc` at `defaultPdfWorkerSrc()`.
+ */
+declare function loadPdfjs(): Promise<PdfjsModule>;
+
+export { defaultPdfWorkerSrc, loadPdfjs };

package/dist/pdfjs.js

@@ -0,0 +1,11 @@
+// src/pdfjs.ts
+var defaultPdfWorkerSrc = () => new URL("pdfjs-dist/legacy/build/pdf.worker.min.mjs", import.meta.url).href;
+async function loadPdfjs() {
+  const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+  if (!pdfjs.GlobalWorkerOptions.workerSrc) pdfjs.GlobalWorkerOptions.workerSrc = defaultPdfWorkerSrc();
+  return pdfjs;
+}
+export {
+  defaultPdfWorkerSrc,
+  loadPdfjs
+};

package/dist/react.d.ts

@@ -3,6 +3,8 @@ import { Visibility, DevulturMedia, MediaUrlOptions, ProcessingPhase, FailureRea
 import { BakeOutputFormat, MediaUploadState, MediaUploadError, UploadProgress } from '@devultur/react';
 export { MediaUploadError, MediaUploadState, UploadProgress } from '@devultur/react';
 import { FunctionReference } from 'convex/server';
+import { a as PdfjsLoader } from './pdf-render-CiCK6V1X.js';
+export { P as PdfjsModule } from './pdf-render-CiCK6V1X.js';
 
 interface CropUploadRenderProps {
     /** The state machine of the full cycle (idle → uploading → ready / failed). */
@@ -51,6 +53,184 @@ interface CropUploadProps {
  */
 declare function CropUpload({ aspectRatio, visibility, outputFormat, maxWidth, minSourceWidth, replaces, onComplete, onReject, accept, cropperClassName, labels, children, }: CropUploadProps): React.JSX.Element;
 
+/** Why a media fetch was refused. Stable: match on it, not on `message`. */
+type MediaFetchErrorCode = 
+/** The delivery answered with a non-2xx status (`status` has it). */
+"http_error"
+/** `Content-Length`, or the streamed body, exceeds `maxBytes`. */
+ | "too_large"
+/** The expected content type isn't one that can be previewed inline. */
+ | "unsupported_type"
+/** The response's `Content-Type` doesn't agree with the expected one. */
+ | "type_mismatch";
+declare class MediaFetchError extends Error {
+    readonly code: MediaFetchErrorCode;
+    /** HTTP status, for `http_error`. */
+    readonly status?: number;
+    constructor(code: MediaFetchErrorCode, message: string, status?: number);
+}
+
+interface UseMediaObjectUrlOptions {
+    /** `false` → nothing is fetched (e.g. a list row that isn't selected). Default `true`. */
+    enabled?: boolean;
+    /** Refuses bodies larger than this, by `Content-Length` and while streaming (`MediaFetchError` `too_large`). */
+    maxBytes?: number;
+    /**
+     * The type you know the media has. The response's `Content-Type` must agree with it, and the object URL is
+     * created with it (`type_mismatch` / `unsupported_type` otherwise). Without it, the object URL keeps the
+     * response's type only when previewable (see the guide's allowlist), else `application/octet-stream`.
+     * With it, public media is fetched and verified too, instead of returning its unverified delivery URL.
+     */
+    contentType?: string;
+}
+interface MediaObjectUrl {
+    /**
+     * `blob:` URL for private media (and public media with `contentType`); the delivery URL for other public media,
+     * whose type is whatever the server says, so don't frame it. `null` while loading, disabled or failed.
+     */
+    objectUrl: string | null;
+    /** The type the object URL was created with (not the server's verbatim). `null` for an unverified public URL. */
+    contentType: string | null;
+    isLoading: boolean;
+    /** A `MediaFetchError` (stable `code`), or a network error. */
+    error: Error | null;
+}
+/**
+ * An in-memory URL for any media, for elements that can't send headers (`<iframe>`, `<audio>`, `<img>`). Private
+ * media is fetched with the session header (one re-issue and retry on a 401 `session_mismatch`) into an object
+ * URL that is revoked when the media changes and on unmount. Public media returns its delivery URL, unfetched,
+ * unless `contentType` asks for it to be verified.
+ *
+ * @example
+ * const { objectUrl, error } = useMediaObjectUrl(document.file, { contentType: "application/pdf", maxBytes: 20e6 });
+ * return objectUrl && <iframe src={objectUrl} title={document.file.filename} />;
+ */
+declare function useMediaObjectUrl(media: DevulturMedia | null | undefined, options?: UseMediaObjectUrlOptions): MediaObjectUrl;
+
+/**
+ * Every string `<Preview>`, `<PdfThumbnail>` and their PDF pages show or announce. Pass any subset as `labels` on a
+ * component or on `PdfPreviewProvider`; the component's wins over the provider's, which wins over the English defaults.
+ */
+interface PreviewLabels {
+    /** Accessible name of a pdf.js document: its title and page count. */
+    document: (title: string, pageCount: number) => string;
+    /** Accessible name of one pdf.js page. */
+    page: (page: number, pageCount: number) => string;
+    /** Announced (visually hidden) while a preview loads, when no `loading` is passed. */
+    loading: string;
+    /** Note after the last rendered page when a PDF has more than `maxPages`; `fallback` follows it. */
+    pageCap: (shown: number, total: number) => string;
+    /** `title` of the default fallback's download link when a fetch was refused or the type can't be previewed. */
+    error: (code: MediaFetchErrorCode) => string;
+    /** Accessible name of a `<PdfThumbnail>`, from its title. */
+    thumbnail: (title: string) => string;
+    /** Name of a PDF (pdf.js document, `<iframe>` title, thumbnail) with no `title` and no filename. */
+    untitledPdf: string;
+    /** Name of an image or audio preview with no `title` and no filename. */
+    untitledMedia: string;
+    /** Text of the default fallback's download link when the media has no filename. */
+    download: string;
+}
+declare const defaultPreviewLabels: PreviewLabels;
+
+interface PdfPreviewConfig {
+    /**
+     * Imports pdf.js. Without it, PDFs render in an `<iframe>` (the browser's own viewer) and `<PdfThumbnail>` renders
+     * its fallback. `loadPdfjs` from `@devultur/convex/pdfjs` imports the legacy build and sets a default worker.
+     */
+    pdfjs?: PdfjsLoader;
+    /** URL of `pdf.worker.min.mjs`, set on `GlobalWorkerOptions.workerSrc` before a document opens. */
+    workerSrc?: string;
+    /** Labels for every `<Preview>` and `<PdfThumbnail>` below it; a component's own `labels` win over these. */
+    labels?: Partial<PreviewLabels>;
+}
+/**
+ * Renders the PDFs of every `<Preview>` and `<PdfThumbnail>` below it with pdf.js, on a `<canvas>`, and gives them
+ * default `labels`.
+ *
+ * @example
+ * import { loadPdfjs } from "@devultur/convex/pdfjs";
+ * <PdfPreviewProvider pdfjs={loadPdfjs}>{children}</PdfPreviewProvider>
+ */
+declare function PdfPreviewProvider({ pdfjs, workerSrc, labels, children, }: PdfPreviewConfig & {
+    children: React.ReactNode;
+}): React.JSX.Element;
+
+interface PdfThumbnailProps {
+    /** Typed reference. `null`/`undefined` → renders nothing. */
+    media: DevulturMedia | null | undefined;
+    /** The type you know the media has. Default: inferred from `media.filename`'s extension. */
+    contentType?: string;
+    /** CSS width of the thumbnail in pixels; the height follows the page. Default 96. */
+    width?: number;
+    /** Larger files render `fallback`. Default 50 MiB. */
+    maxBytes?: number;
+    /** Shown when the media isn't a PDF, pdf.js isn't available (no `PdfPreviewProvider`) or loading fails. */
+    fallback?: React.ReactNode;
+    /** Shown until page 1 is drawn, including while off-screen. Default: nothing. */
+    loading?: React.ReactNode;
+    /** Title the accessible name is built from (`labels.thumbnail`). Default: the filename. */
+    title?: string;
+    className?: string;
+    /** Overrides the provider's `workerSrc`. */
+    pdfWorkerSrc?: string;
+    /** Overrides `thumbnail` and `untitledPdf`; wins over `PdfPreviewProvider`'s `labels`. English by default. */
+    labels?: Partial<PreviewLabels>;
+}
+/**
+ * Page 1 of a PDF on a small canvas, for lists and upload queues. Nothing is fetched until it nears the viewport.
+ * Needs pdf.js from a `PdfPreviewProvider`; without it, renders `fallback`.
+ *
+ * @example
+ * <PdfThumbnail media={row.file} width={64} fallback={<FileIcon />} />
+ */
+declare function PdfThumbnail(props: PdfThumbnailProps): React.JSX.Element | null;
+
+interface PreviewProps {
+    /** Typed reference. `null`/`undefined` → renders nothing. */
+    media: DevulturMedia | null | undefined;
+    /** The type you know the media has (e.g. stored with it). Default: inferred from `media.filename`'s extension. */
+    contentType?: string;
+    /** Size cap for images, PDFs and audio; larger files render `fallback`. Default 50 MiB. */
+    maxBytes?: number;
+    /** Size cap for text previews. Default 1 MiB. */
+    maxTextBytes?: number;
+    /**
+     * Shown for types that don't preview inline and when the fetch fails. Default: a `<DownloadLink>`.
+     * As a function it receives why: a `MediaFetchError` when the fetch was refused (`http_error`, `too_large`,
+     * `type_mismatch`) or the type doesn't preview inline (`unsupported_type`, nothing fetched), `null` otherwise
+     * (a network failure, a PDF pdf.js can't open, or the link after the `maxPages` note).
+     */
+    fallback?: React.ReactNode | ((error: MediaFetchError | null) => React.ReactNode);
+    /** Shown while a file loads. Default: `labels.loading`, visually hidden, in a `role="status"`. `null` → nothing. */
+    loading?: React.ReactNode;
+    /** Accessible name of the preview (`alt`, `title`, `aria-label`). Default: the filename (text: none). */
+    title?: string;
+    className?: string;
+    /**
+     * PDF pages rendered with pdf.js; past it, a "first N of M pages" note and `fallback`. Default 500 (a tiny file
+     * can declare millions of pages).
+     */
+    maxPages?: number;
+    /** URL of pdf.js's worker for this preview; overrides `PdfPreviewProvider`'s `workerSrc`. */
+    pdfWorkerSrc?: string;
+    /** Overrides any string shown or announced; wins over `PdfPreviewProvider`'s `labels`. English by default. */
+    labels?: Partial<PreviewLabels>;
+}
+/**
+ * Renders a media inline by its content type: images in an `<img>`, PDFs on `<canvas>` pages with pdf.js under a
+ * `PdfPreviewProvider` (otherwise in an `<iframe>`), audio in an `<audio>`,
+ * plain text, CSV and JSON in a `<pre>`, and video in the streaming `<VideoPlayer>`. Everything else (HTML, SVG,
+ * XML, unknown types) and every refused fetch render `fallback`. Private media is token-transparent.
+ *
+ * @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;
+
+/** How a content type renders inline: `<img>`, a PDF view (pdf.js canvases or `<iframe>`), `<audio>` or `<pre>`. */
+type PreviewKind = "image" | "pdf" | "audio" | "text";
+
 /** Transform/delivery options for media URLs (without `token`, which the context injects). */
 type MediaRenderOptions = Omit<MediaUrlOptions, "token">;
 type AnyAction = FunctionReference<"action">;
@@ -291,4 +471,4 @@ interface UseMediaUploadReturn {
  */
 declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
 
-export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, type UploadedMedia, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, useDevultur, useDevulturMedia, useDevulturProgress, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };
+export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, MediaFetchError, type MediaFetchErrorCode, type MediaObjectUrl, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewLabels, type PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, defaultPreviewLabels, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };