@devultur/convex 1.2.0 → 1.3.0

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,146 @@ 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;
+
+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;
+}
+/**
+ * Renders the PDFs of every `<Preview>` and `<PdfThumbnail>` below it with pdf.js, on a `<canvas>`.
+ *
+ * @example
+ * import { loadPdfjs } from "@devultur/convex/pdfjs";
+ * <PdfPreviewProvider pdfjs={loadPdfjs}>{children}</PdfPreviewProvider>
+ */
+declare function PdfPreviewProvider({ pdfjs, workerSrc, 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;
+    /** Accessible name of the thumbnail. Default: the filename. */
+    title?: string;
+    className?: string;
+    /** Overrides the provider's `workerSrc`. */
+    pdfWorkerSrc?: string;
+}
+/**
+ * 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>`. */
+    fallback?: React.ReactNode;
+    /** Shown while a private file is loading. Default: 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;
+}
+/**
+ * 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, ...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 +433,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 PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };