@devultur/convex 0.0.0-stage → 1.0.1

package/dist/component/schema.js

@@ -0,0 +1,63 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+// Outputs of a preset transcode (carried by `transcode.complete`): each MP4/ladder with its stable URL, the
+// poster (JPG + AVIF per transform), and whether the video ended up with audio.
+export const transcodeOutputFields = {
+    renditions: v.optional(v.array(v.object({
+        variant: v.string(),
+        kind: v.union(v.literal("hls"), v.literal("mp4")),
+        rung: v.string(),
+        key: v.string(),
+        width: v.optional(v.number()),
+        height: v.optional(v.number()),
+        url: v.string(),
+    }))),
+    posterUrls: v.optional(v.object({ jpg: v.optional(v.string()), avif: v.optional(v.string()) })),
+    hasAudio: v.optional(v.boolean()),
+    // Key of the storyboard VTT (scrub-bar previews). URL: `buildStoryboardUrl` / `buildMediaUrl` from core.
+    storyboardKey: v.optional(v.string()),
+};
+export default defineSchema({
+    media: defineTable({
+        key: v.string(),
+        type: v.union(v.literal("video"), v.literal("image"), v.literal("file")),
+        filename: v.string(),
+        contentType: v.string(),
+        sizeBytes: v.number(),
+        transcodeStatus: v.optional(v.union(v.literal("queued"), v.literal("transcoding"), v.literal("captioning"), v.literal("ready"), v.literal("failed"))),
+        transcodeProgress: v.optional(v.object({
+            current: v.number(),
+            total: v.number(),
+            phase: v.optional(v.union(v.literal("downloading"), v.literal("encoding"), v.literal("uploading"), v.literal("captioning"))),
+        })),
+        transcodeError: v.optional(v.string()),
+        // Categorized failure + whether it's retriable (webhook / accept-timeout). See FailureReason in core.
+        failureReason: v.optional(v.union(v.literal("invalid_input"), v.literal("unsupported_codec"), v.literal("timeout"), v.literal("capacity"), v.literal("internal"))),
+        retriable: v.optional(v.boolean()),
+        playlistUrl: v.optional(v.string()),
+        thumbnailKey: v.optional(v.string()),
+        // Outputs of a preset transcode: each MP4/ladder with its stable URL, poster, and whether it has audio.
+        ...transcodeOutputFields,
+        captionLocales: v.optional(v.array(v.string())),
+        duration: v.optional(v.number()),
+        createdAt: v.number(),
+    }).index("by_key", ["key"]),
+    captions: defineTable({
+        mediaKey: v.string(),
+        locale: v.string(),
+        vttUrl: v.string(),
+        srtUrl: v.optional(v.string()),
+        createdAt: v.number(),
+    })
+        .index("by_media", ["mediaKey"])
+        .index("by_media_locale", ["mediaKey", "locale"]),
+    progress: defineTable({
+        userId: v.string(),
+        videoId: v.string(),
+        lastPosition: v.number(),
+        completedAt: v.optional(v.number()),
+        watchedPercent: v.optional(v.number()),
+        updatedAt: v.number(),
+    }).index("by_user_video", ["userId", "videoId"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import { VideoModuleConfig } from '@devultur/core';
+export { CaptionLocale, DevulturConfig, DevulturKind, DevulturMedia, ImageFit, ImageFormat, SecurityLevel, SpeechProvider, StorageProvider, TranscodePreset, TranscodeProvider, TranslationProvider, VideoModuleConfig, Visibility } from '@devultur/core';
+import * as convex_server from 'convex/server';
+import { FunctionReference, GenericQueryCtx, GenericDataModel, GenericMutationCtx } from 'convex/server';
+export { dv } from './validators.js';
+import 'convex/values';
+
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+type ComponentApi<Name extends string | undefined = string | undefined> = {
+    public: {
+        createMedia: FunctionReference<"mutation", "internal", {
+            contentType: string;
+            filename: string;
+            key: string;
+            sizeBytes: number;
+            type: "video" | "image" | "file";
+        }, any, Name>;
+        createUploadUrl: FunctionReference<"action", "internal", {
+            contentType: string;
+            filename: string;
+        }, any, Name>;
+        deleteMediaAction: FunctionReference<"action", "internal", {
+            key: string;
+        }, any, Name>;
+        deleteVideo: FunctionReference<"action", "internal", {
+            videoId: string;
+        }, any, Name>;
+        getCourseProgress: FunctionReference<"query", "internal", {
+            userId: string;
+            videoIds: Array<string>;
+        }, any, Name>;
+        getMediaByKey: FunctionReference<"query", "internal", {
+            key: string;
+        }, any, Name>;
+        issueViewerToken: FunctionReference<"action", "internal", {
+            sessionSecret?: string;
+        }, any, Name>;
+        listCaptionsByMedia: FunctionReference<"query", "internal", {
+            mediaKey: string;
+        }, any, Name>;
+        listMedia: FunctionReference<"query", "internal", {
+            type?: "video" | "image" | "file";
+        }, any, Name>;
+        loadProgress: FunctionReference<"query", "internal", {
+            userId: string;
+            videoId: string;
+        }, any, Name>;
+        markComplete: FunctionReference<"mutation", "internal", {
+            userId: string;
+            videoId: string;
+        }, any, Name>;
+        processVideo: FunctionReference<"action", "internal", {
+            callbackUrl?: string;
+            key: string;
+            locales?: Array<string>;
+            preset?: string;
+        }, any, Name>;
+        resetProgress: FunctionReference<"mutation", "internal", {
+            userId: string;
+            videoId: string;
+        }, any, Name>;
+        saveProgress: FunctionReference<"mutation", "internal", {
+            position: number;
+            userId: string;
+            videoId: string;
+        }, any, Name>;
+        updateMedia: FunctionReference<"mutation", "internal", {
+            captionLocales?: Array<string>;
+            duration?: number;
+            key: string;
+            playlistUrl?: string;
+            thumbnailKey?: string;
+            transcodeError?: string;
+            transcodeProgress?: {
+                current: number;
+                total: number;
+            };
+            transcodeStatus?: "transcoding" | "captioning" | "ready" | "failed";
+        }, any, Name>;
+        upsertCaption: FunctionReference<"mutation", "internal", {
+            locale: string;
+            mediaKey: string;
+            srtUrl?: string;
+            vttUrl: string;
+        }, any, Name>;
+    };
+};
+
+interface DevulturComponentConfig {
+    video?: VideoModuleConfig;
+}
+interface MediaRecord {
+    key: string;
+    type: "video" | "image" | "file";
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    transcodeStatus?: "transcoding" | "captioning" | "ready" | "failed";
+    transcodeProgress?: {
+        current: number;
+        total: number;
+    };
+    transcodeError?: string;
+    playlistUrl?: string;
+    thumbnailKey?: string;
+    /** Key of the storyboard VTT (hover previews); URL via `buildStoryboardUrl` from `@devultur/core`. */
+    storyboardKey?: string;
+    captionLocales?: string[];
+    duration?: number;
+    createdAt: number;
+}
+interface ProgressRecord {
+    userId: string;
+    videoId: string;
+    lastPosition: number;
+    completedAt?: number;
+    watchedPercent?: number;
+    updatedAt: number;
+}
+
+type DevulturComponent = ComponentApi;
+type QueryCtx = GenericQueryCtx<GenericDataModel>;
+type MutationCtx = GenericMutationCtx<GenericDataModel>;
+declare class Devultur {
+    private component;
+    constructor(component: DevulturComponent);
+    getMedia(ctx: QueryCtx, key: string): Promise<any>;
+    saveProgress(ctx: MutationCtx, args: {
+        userId: string;
+        videoId: string;
+        position: number;
+    }): Promise<any>;
+    loadProgress(ctx: QueryCtx, args: {
+        userId: string;
+        videoId: string;
+    }): Promise<any>;
+    static exposeApi(component: DevulturComponent, config?: DevulturComponentConfig): {
+        issueViewerToken: convex_server.RegisteredAction<"public", {
+            sessionSecret?: string;
+        }, Promise<any>>;
+        createUploadUrl: convex_server.RegisteredAction<"public", {
+            filename: string;
+            contentType: string;
+            visibility?: "public" | "private";
+        }, Promise<any>>;
+        deleteMedia: convex_server.RegisteredAction<"public", {
+            key: string;
+        }, Promise<any>>;
+        deleteVideo: convex_server.RegisteredAction<"public", {
+            videoId: string;
+            visibility?: "public" | "private";
+        }, Promise<any>>;
+        processVideo: convex_server.RegisteredAction<"public", {
+            key: string;
+        }, Promise<any>>;
+        getMedia: convex_server.RegisteredQuery<"public", {
+            key: string;
+        }, Promise<any>>;
+        saveProgress: convex_server.RegisteredMutation<"public", {
+            userId: string;
+            videoId: string;
+            position: number;
+        }, Promise<any>>;
+        loadProgress: convex_server.RegisteredQuery<"public", {
+            userId: string;
+            videoId: string;
+        }, Promise<any>>;
+        markComplete: convex_server.RegisteredMutation<"public", {
+            userId: string;
+            videoId: string;
+        }, Promise<any>>;
+        resetProgress: convex_server.RegisteredMutation<"public", {
+            userId: string;
+            videoId: string;
+        }, Promise<any>>;
+    };
+}
+
+export { Devultur, type DevulturComponentConfig, type MediaRecord, type ProgressRecord };

package/dist/index.js

@@ -0,0 +1,121 @@
+import {
+  dv
+} from "./chunk-FHWT3GD6.js";
+
+// src/index.ts
+import {
+  CaptionLocale,
+  ImageFit,
+  ImageFormat,
+  SecurityLevel,
+  SpeechProvider,
+  StorageProvider,
+  TranscodePreset,
+  TranscodeProvider,
+  TranslationProvider
+} from "@devultur/core";
+
+// src/client.ts
+import { extractId } from "@devultur/core";
+import { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
+import { v } from "convex/values";
+var Devultur = class {
+  component;
+  constructor(component) {
+    this.component = component;
+  }
+  async getMedia(ctx, key) {
+    return ctx.runQuery(this.component.public.getMediaByKey, { key });
+  }
+  async saveProgress(ctx, args) {
+    return ctx.runMutation(this.component.public.saveProgress, args);
+  }
+  async loadProgress(ctx, args) {
+    return ctx.runQuery(this.component.public.loadProgress, args);
+  }
+  static exposeApi(component, config) {
+    const preset = config?.video?.transcodePreset;
+    const locales = config?.video?.captionLocales ?? [];
+    const visibilityArg = v.optional(v.union(v.literal("public"), v.literal("private")));
+    return {
+      issueViewerToken: actionGeneric({
+        args: { sessionSecret: v.optional(v.string()) },
+        handler: async (ctx, args) => {
+          return ctx.runAction(component.public.issueViewerToken, args);
+        }
+      }),
+      createUploadUrl: actionGeneric({
+        args: { filename: v.string(), contentType: v.string(), visibility: visibilityArg },
+        handler: async (ctx, args) => {
+          return ctx.runAction(component.public.createUploadUrl, args);
+        }
+      }),
+      deleteMedia: actionGeneric({
+        args: { key: v.string() },
+        handler: async (ctx, args) => {
+          return ctx.runAction(component.public.deleteMediaAction, args);
+        }
+      }),
+      deleteVideo: actionGeneric({
+        args: { videoId: v.string(), visibility: visibilityArg },
+        handler: async (ctx, args) => {
+          return ctx.runAction(component.public.deleteVideo, args);
+        }
+      }),
+      processVideo: actionGeneric({
+        args: { key: v.string() },
+        handler: async (ctx, args) => {
+          return ctx.runAction(component.public.processVideo, {
+            key: args.key,
+            preset,
+            locales
+          });
+        }
+      }),
+      getMedia: queryGeneric({
+        args: { key: v.string() },
+        handler: async (ctx, args) => {
+          const mediaKey = args.key.includes("/") ? extractId(args.key) : args.key;
+          return ctx.runQuery(component.public.getMediaByKey, { key: mediaKey });
+        }
+      }),
+      saveProgress: mutationGeneric({
+        args: { userId: v.string(), videoId: v.string(), position: v.number() },
+        handler: async (ctx, args) => {
+          return ctx.runMutation(component.public.saveProgress, args);
+        }
+      }),
+      loadProgress: queryGeneric({
+        args: { userId: v.string(), videoId: v.string() },
+        handler: async (ctx, args) => {
+          return ctx.runQuery(component.public.loadProgress, args);
+        }
+      }),
+      markComplete: mutationGeneric({
+        args: { userId: v.string(), videoId: v.string() },
+        handler: async (ctx, args) => {
+          return ctx.runMutation(component.public.markComplete, args);
+        }
+      }),
+      resetProgress: mutationGeneric({
+        args: { userId: v.string(), videoId: v.string() },
+        handler: async (ctx, args) => {
+          return ctx.runMutation(component.public.resetProgress, args);
+        }
+      })
+    };
+  }
+};
+export {
+  CaptionLocale,
+  Devultur,
+  ImageFit,
+  ImageFormat,
+  SecurityLevel,
+  SpeechProvider,
+  StorageProvider,
+  TranscodePreset,
+  TranscodeProvider,
+  TranslationProvider,
+  dv
+};

package/dist/react.d.ts

@@ -0,0 +1,281 @@
+import React from 'react';
+import { Visibility, DevulturMedia, MediaUrlOptions, ProcessingPhase, FailureReason, MediaStatusValue } from '@devultur/core';
+import { BakeOutputFormat, MediaUploadState, MediaUploadError } from '@devultur/react';
+export { MediaUploadError, MediaUploadState } from '@devultur/react';
+import { FunctionReference } from 'convex/server';
+
+interface CropUploadRenderProps {
+    /** The state machine of the full cycle (idle → uploading → ready / failed). */
+    state: MediaUploadState;
+    /** Opens the file picker. */
+    pickFile: () => void;
+    /** Selected file waiting to be cropped (`null` if none). */
+    pendingFile: File | null;
+    /** Cancels the in-progress upload. */
+    cancel: () => void;
+    /** Returns to idle and clears state (including discarding the pending file). */
+    reset: () => void;
+}
+/** Text of the crop controls; pass your own to localize them. */
+interface CropUploadLabels {
+    zoom: string;
+    confirm: string;
+    processing: string;
+    cancel: string;
+}
+interface CropUploadProps {
+    /** Crop aspect ratio (width/height), e.g. `16/9`. */
+    aspectRatio: number;
+    visibility?: Visibility;
+    outputFormat?: BakeOutputFormat;
+    maxWidth?: number;
+    minSourceWidth?: number;
+    /** Deletes this old asset after a successful upload. */
+    replaces?: DevulturMedia | null;
+    /** Fires with the uploaded `DevulturMedia` (persistence point). */
+    onComplete?: (media: DevulturMedia) => void;
+    onReject?: (reason: "too_small") => void;
+    /** Accepted types in the file picker. Default `["image/*"]`. */
+    accept?: string[];
+    /** Class for the cropper's box — only needs a **height** (`position: relative` is automatic). */
+    cropperClassName?: string;
+    /** Overrides any of the control labels (English by default). */
+    labels?: Partial<CropUploadLabels>;
+    /** External UI (trigger + state). Receives `pickFile`/`state`. Without this there's no way to start. */
+    children?: (api: CropUploadRenderProps) => React.ReactNode;
+}
+/**
+ * Upload with aspect-ratio crop: file picker → `<ImageCropper>` (crop + bake to WebP) →
+ * `useMediaUpload` (uploads the cropped result, returns `DevulturMedia`). Batteries-included for the crop
+ * phase (zoom + confirm); the trigger and state rendering are left to the consumer via `children`.
+ */
+declare function CropUpload({ aspectRatio, visibility, outputFormat, maxWidth, minSourceWidth, replaces, onComplete, onReject, accept, cropperClassName, labels, children, }: CropUploadProps): React.JSX.Element;
+
+/** Transform/delivery options for media URLs (without `token`, which the context injects). */
+type MediaRenderOptions = Omit<MediaUrlOptions, "token">;
+type AnyAction = FunctionReference<"action">;
+type AnyMutation = FunctionReference<"mutation">;
+type AnyQuery = FunctionReference<"query">;
+interface DevulturApi {
+    issueViewerToken: AnyAction;
+    createUploadUrl: 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;
+    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;
+}
+interface DevulturContextValue {
+    token: string | null;
+    baseUrl: string | null;
+    /** Browser session secret → sent in `${SESSION_HEADER}` on every private delivery. */
+    sessionSecret: string;
+    uploadUrl: (file: File) => Promise<{
+        url: string;
+        key: string;
+    }>;
+    /** Uploads a file and returns the typed reference ready to save. */
+    upload: (file: File, options?: UploadOptions) => Promise<DevulturMedia>;
+    /** 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>;
+    /** Deletes a media by reference: video → full folder; image/file → the object. */
+    deleteMedia: (media: DevulturMedia) => void;
+    /**
+     * 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>;
+}
+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;
+    children: React.ReactNode;
+}
+declare function DevulturProvider({ api, baseUrl, children }: DevulturProviderProps): React.JSX.Element;
+declare function useDevultur(): DevulturContextValue;
+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 ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
+    /** Typed reference. `null`/`undefined` → renders `fallback` (or `externalFallback`). */
+    media: DevulturMedia | null | undefined;
+    width?: number;
+    height?: number;
+    fit?: MediaUrlOptions["fit"];
+    format?: MediaUrlOptions["format"];
+    quality?: number;
+    /** What to show when there's no media (or it's loading). */
+    fallback?: React.ReactNode;
+    /** Explicit external URL (e.g. Unsplash) when `media` is null or the load fails. */
+    externalFallback?: string;
+    /** background-image mode: composes the URL as this element's `background-image` (doesn't force `<img>`). */
+    render?: React.ReactElement<{
+        style?: React.CSSProperties;
+    }>;
+}
+/**
+ * Renders any media declaratively: token-transparent, with typed transforms, and works inside a
+ * `.map()` (no wrappers or hooks rules on the consumer's side).
+ *
+ * @example
+ * <Image media={course.thumbnail} alt={course.title} width={512} format="webp" fallback={<Placeholder />} />
+ */
+declare function Image({ media, width, height, fit, format, quality, fallback, externalFallback, render, alt, ...imgProps }: ImageProps): React.JSX.Element;
+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;
+    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, 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). */
+    visibility?: Visibility;
+    /** Fires ONCE, at the persistence point (PUT done + transcode requested). */
+    onComplete?: (media: DevulturMedia) => void;
+    onError?: (error: MediaUploadError) => void;
+    /** Deletes this old video/asset after a successful PUT (best-effort). */
+    replaces?: DevulturMedia | null;
+    /** Auto-request the transcode for videos. Default `true`; `false` = upload the raw file unprocessed. */
+    process?: boolean;
+    /** Caption locales to request when transcoding. */
+    locales?: string[];
+}
+interface UseMediaUploadReturn {
+    /** Triggers the upload; resolves with the `DevulturMedia` at the persistence point, or `null` if cancelled/failed. */
+    upload: (file: File) => Promise<DevulturMedia | null>;
+    /** The reactive state machine for the full cycle. */
+    state: MediaUploadState;
+    /** Aborts the in-progress PUT (`uploading` phase). */
+    cancel: () => void;
+    /** Returns to `idle` and clears everything. */
+    reset: () => void;
+}
+/**
+ * Unified upload primitive: hides the seam between the (imperative) upload and the (reactive)
+ * transcode behind ONE state machine. The consumer calls `upload(file)`, persists the ref in
+ * `onComplete`, and renders a `switch` over `state.phase`. Video triggers the transcode on its own;
+ * image/file go straight to `ready`. Requires `createUploadUrl` + `getMedia` in the provider (and
+ * `processVideo` for video).
+ */
+declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
+
+export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, useDevultur, useDevulturMedia, useDevulturProgress, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };