@devultur/convex 1.5.1 → 1.6.0

package/README.md

@@ -276,12 +276,28 @@ function Avatar({ media, fallbackUrl }) {
 }
 ```
 
+`useDevulturOptional()` is non-null under a `<DevulturProvider>` given no `baseUrl` too, where the hooks that build
+URLs throw. `useCanDeliver()` answers that instead: `true` only under a provider with a non-empty `baseUrl`.
+
+```tsx
+function Cover({ media, fallbackUrl }) {
+  if (!useCanDeliver() || !media) return <img src={fallbackUrl} alt="" />;
+  return <Image media={media} alt="" />;
+}
+```
+
+Public media needs nothing more. Private media also needs the viewer token, which a provider may not have yet
+(`lazyToken`) or can't issue (a `<DevulturViewerProvider>` without `issueViewerToken`); `tokenStatus` from
+`useDevultur()` tells, and the components show their error state when it fails.
+
 ### Only the hooks
 
 `@devultur/convex/react/hooks` exports the contexts and the hooks that only read them, without the components or
-Convex's client: `useDevultur`, `useDevulturOptional`, `useDevulturApi`, `useDevulturProgress`, `useMediaUrl`,
-`useVideoProps`, and the `DevulturContext`, `DevulturApiContext` and `DevulturProgressContext` objects. A shared
-component that only checks for a provider adds well under 1 kB gzipped to the bundle:
+Convex's client: `useDevultur`, `useDevulturOptional`, `useCanDeliver`, `useDevulturApi`, `useDevulturProgress`,
+`useMediaUrl`, `useVideoProps`, and the `DevulturContext`, `DevulturApiContext` and `DevulturProgressContext` objects.
+The contexts and the hooks that only read them sit in a chunk of their own, apart from `useMediaUrl`, `useVideoProps`
+and `@devultur/core`'s URL helpers, so a shared component that only checks for a provider adds under 0.5 kB gzipped,
+even to the entry of an app that lazy-loads `@devultur/convex/react` on a route:
 
 ```tsx
 import { useDevulturOptional } from "@devultur/convex/react/hooks";

package/dist/{chunk-RDVBE3G3.js → chunk-34XXHYL3.js}

@@ -7,7 +7,7 @@ import {
   formatBytes,
   formatDate,
   labelText
-} from "./chunk-YYOZ3PDH.js";
+} from "./chunk-V5YH4YJG.js";
 
 // src/locales/es.ts
 var LOCALE = "es";
@@ -57,6 +57,18 @@ var devulturErrorLabels = {
   link_expired: "Este enlace de descarga ya venci\xF3.",
   link_used: "Este enlace de descarga ya se us\xF3.",
   not_configured: "Esta funci\xF3n no est\xE1 configurada.",
+  invalid_grant: "Este permiso de descarga no es v\xE1lido.",
+  grant_gone: "Este permiso de descarga ya no es v\xE1lido.",
+  grant_exhausted: "Este permiso de descarga ya emiti\xF3 todos sus enlaces.",
+  grant_exists: "Este permiso de descarga ya existe.",
+  grant_in_query: "Env\xEDa el permiso de descarga en el encabezado Authorization, nunca en una URL.",
+  grant_not_found: "Este permiso de descarga no existe.",
+  grant_cannot_delete: "Este permiso de descarga no puede eliminar su archivo.",
+  link_exceeds_grant: "El enlace de descarga supera lo que permite el permiso.",
+  invalid_link_caps: "Los l\xEDmites del enlace de descarga no son v\xE1lidos.",
+  invalid_max_links: "El n\xFAmero de enlaces no es v\xE1lido.",
+  invalid_can_delete: "Si el permiso puede eliminar su archivo debe ser verdadero o falso.",
+  invalid_metadata: "Los metadatos no son v\xE1lidos.",
   retention_active: (details) => {
     if (details.hold === true) return "Este archivo tiene una retenci\xF3n legal y no se puede modificar ni eliminar.";
     const until = formatDate(details.until, LOCALE);

package/dist/{chunk-BDEO67OT.js → chunk-AUAWZ5BD.js}

@@ -1,46 +1,9 @@
-// src/capability-error.ts
-var DevulturCapabilityError = class extends Error {
-  code = "capability_unavailable";
-  capability;
-  constructor(capability) {
-    super(
-      `Devultur: \`${capability}\` isn't available under <DevulturViewerProvider>. Use <DevulturProvider api> with the actions it needs.`
-    );
-    this.name = "DevulturCapabilityError";
-    this.capability = capability;
-  }
-};
-
-// src/devultur-context.ts
-import React from "react";
-var DevulturContext = /* @__PURE__ */ React.createContext(null);
-var DevulturApiContext = /* @__PURE__ */ React.createContext(null);
-function useDevultur() {
-  const context = React.use(DevulturContext);
-  if (!context) throw new Error("useDevultur must be used within <DevulturProvider> or <DevulturViewerProvider>");
-  return context;
-}
-function useDevulturOptional() {
-  return React.use(DevulturContext);
-}
-function useDevulturApi() {
-  const api = React.use(DevulturApiContext);
-  if (api) return api;
-  if (React.use(DevulturContext)) throw new DevulturCapabilityError("api");
-  throw new Error("useDevulturApi must be used within <DevulturProvider>");
-}
-
-// src/progress-context.ts
-import React2 from "react";
-var DevulturProgressContext = /* @__PURE__ */ React2.createContext(null);
-function useDevulturProgress() {
-  const context = React2.use(DevulturProgressContext);
-  if (!context) throw new Error("useDevulturProgress requires progress API in DevulturProvider");
-  return context;
-}
+import {
+  useDevultur
+} from "./chunk-FOBFHC4A.js";
 
 // src/media-url-hooks.ts
-import React4 from "react";
+import React2 from "react";
 import {
   buildMediaUrl,
   CaptionLocaleLabel,
@@ -50,11 +13,11 @@ import {
 } from "@devultur/core";
 
 // src/request-token.ts
-import React3 from "react";
+import React from "react";
 function useRequestTokenWhen(session, isNeeded) {
   const { requestToken, token } = session;
   const hasToken = token !== null;
-  React3.useEffect(() => {
+  React.useEffect(() => {
     if (isNeeded && !hasToken) requestToken();
   }, [isNeeded, hasToken, requestToken]);
 }
@@ -64,7 +27,7 @@ function useMediaUrl(key, options) {
   const devultur = useDevultur();
   const { token, baseUrl } = devultur;
   useRequestTokenWhen(devultur, Boolean(key) && visibilityFromKey(key ?? "") !== "public");
-  return React4.useMemo(() => {
+  return React2.useMemo(() => {
     if (!key) return null;
     if (!baseUrl) throw new Error("useMediaUrl requires `baseUrl` on <DevulturProvider>");
     const isPublic = visibilityFromKey(key) === "public";
@@ -76,7 +39,7 @@ function useVideoProps(media, options) {
   const { token, baseUrl, sessionSecret } = devultur;
   useRequestTokenWhen(devultur, media?.kind === "video" && media.visibility === "private");
   const locales = options?.locales;
-  return React4.useMemo(() => {
+  return React2.useMemo(() => {
     if (media?.kind !== "video") return null;
     if (!baseUrl) throw new Error("useVideoProps requires `baseUrl` on <DevulturProvider>");
     const viewerToken = media.visibility === "private" ? token ?? void 0 : void 0;
@@ -96,14 +59,6 @@ function useVideoProps(media, options) {
 }
 
 export {
-  DevulturCapabilityError,
-  DevulturContext,
-  DevulturApiContext,
-  useDevultur,
-  useDevulturOptional,
-  useDevulturApi,
-  DevulturProgressContext,
-  useDevulturProgress,
   useRequestTokenWhen,
   useMediaUrl,
   useVideoProps

package/dist/chunk-FOBFHC4A.js

@@ -0,0 +1,55 @@
+// src/capability-error.ts
+var DevulturCapabilityError = class extends Error {
+  code = "capability_unavailable";
+  capability;
+  constructor(capability) {
+    super(
+      `Devultur: \`${capability}\` isn't available under <DevulturViewerProvider>. Use <DevulturProvider api> with the actions it needs.`
+    );
+    this.name = "DevulturCapabilityError";
+    this.capability = capability;
+  }
+};
+
+// src/devultur-context.ts
+import React from "react";
+var DevulturContext = /* @__PURE__ */ React.createContext(null);
+var DevulturApiContext = /* @__PURE__ */ React.createContext(null);
+function useDevultur() {
+  const context = React.use(DevulturContext);
+  if (!context) throw new Error("useDevultur must be used within <DevulturProvider> or <DevulturViewerProvider>");
+  return context;
+}
+function useDevulturOptional() {
+  return React.use(DevulturContext);
+}
+function useCanDeliver() {
+  return Boolean(React.use(DevulturContext)?.baseUrl);
+}
+function useDevulturApi() {
+  const api = React.use(DevulturApiContext);
+  if (api) return api;
+  if (React.use(DevulturContext)) throw new DevulturCapabilityError("api");
+  throw new Error("useDevulturApi must be used within <DevulturProvider>");
+}
+
+// src/progress-context.ts
+import React2 from "react";
+var DevulturProgressContext = /* @__PURE__ */ React2.createContext(null);
+function useDevulturProgress() {
+  const context = React2.use(DevulturProgressContext);
+  if (!context) throw new Error("useDevulturProgress requires progress API in DevulturProvider");
+  return context;
+}
+
+export {
+  DevulturCapabilityError,
+  DevulturContext,
+  DevulturApiContext,
+  useDevultur,
+  useDevulturOptional,
+  useCanDeliver,
+  useDevulturApi,
+  DevulturProgressContext,
+  useDevulturProgress
+};

package/dist/{chunk-YYOZ3PDH.js → chunk-V5YH4YJG.js}

@@ -40,6 +40,19 @@ var DEVULTUR_ERROR_CODES = [
   "link_expired",
   "link_used",
   "not_configured",
+  // Download grants
+  "invalid_grant",
+  "grant_gone",
+  "grant_exhausted",
+  "grant_exists",
+  "grant_in_query",
+  "grant_not_found",
+  "grant_cannot_delete",
+  "link_exceeds_grant",
+  "invalid_link_caps",
+  "invalid_max_links",
+  "invalid_can_delete",
+  "invalid_metadata",
   // Retention and holds
   "retention_active",
   "lock_conflict",
@@ -170,6 +183,18 @@ var devulturErrorLabels = {
   link_expired: "This download link has expired.",
   link_used: "This download link was already used.",
   not_configured: "This feature isn't set up.",
+  invalid_grant: "This download grant isn't valid.",
+  grant_gone: "This download grant is no longer valid.",
+  grant_exhausted: "This download grant has issued all its links.",
+  grant_exists: "This download grant already exists.",
+  grant_in_query: "Send the download grant in the Authorization header, never in a URL.",
+  grant_not_found: "This download grant doesn't exist.",
+  grant_cannot_delete: "This download grant can't delete its file.",
+  link_exceeds_grant: "The download link exceeds what the grant allows.",
+  invalid_link_caps: "The download link limits aren't valid.",
+  invalid_max_links: "The number of links isn't valid.",
+  invalid_can_delete: "Whether the grant can delete its file must be true or false.",
+  invalid_metadata: "The metadata isn't valid.",
   retention_active: (details) => {
     if (details.hold === true) return "This file is on hold and can't be changed or deleted.";
     const until = formatDate(details.until, "en");

package/dist/{hooks-uqpBd5UF.d.ts → contexts-6F8TJINX.d.ts}

@@ -120,42 +120,20 @@ declare function useDevultur(): DevulturContextValue;
  * `<DevulturViewerProvider>`, and `null` outside both instead of throwing.
  */
 declare function useDevulturOptional(): DevulturContextValue | null;
+/**
+ * Whether the media hooks can build delivery URLs here: `true` under `<DevulturProvider>` or `<DevulturViewerProvider>`
+ * with a non-empty `baseUrl`; `false` outside both, or under a `<DevulturProvider>` without one, where `useMediaUrl`,
+ * `useVideoProps` and `url()` throw. That's all a public media needs. A private media also needs the viewer token,
+ * which the provider may not have yet (lazy issuance) or can't issue (no `issueViewerToken`): `tokenStatus` from
+ * `useDevultur()` tells, and the components handle it themselves.
+ */
+declare function useCanDeliver(): boolean;
 /**
  * The `api` passed to `<DevulturProvider>`: your app's exported Devultur functions. Under a `<DevulturViewerProvider>`
  * it throws a `DevulturCapabilityError`.
  */
 declare function useDevulturApi(): DevulturApi;
 
-/**
- * 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 DevulturProgressContextValue {
     save: (videoId: string, position: number) => Promise<void>;
     load: (videoId: string) => Promise<{
@@ -168,4 +146,4 @@ interface DevulturProgressContextValue {
 declare const DevulturProgressContext: React.Context<DevulturProgressContextValue | null>;
 declare function useDevulturProgress(): DevulturProgressContextValue;
 
-export { type DevulturApi as D, type TokenStatus as T, type UploadOptions as U, type VideoProps as V, type ViewerTokenAction as a, type ViewerTokenArgs as b, DevulturApiContext as c, DevulturContext as d, type DevulturContextValue as e, DevulturProgressContext as f, type DevulturProgressContextValue as g, type UploadedMedia as h, type ViewerTokenResult as i, useDevulturApi as j, useDevulturOptional as k, useDevulturProgress as l, useMediaUrl as m, useVideoProps as n, useDevultur as u };
+export { type DevulturApi as D, type MediaRenderOptions as M, type TokenStatus as T, type UploadOptions as U, type ViewerTokenAction as V, type ViewerTokenArgs as a, DevulturApiContext as b, DevulturContext as c, type DevulturContextValue as d, DevulturProgressContext as e, type DevulturProgressContextValue as f, type UploadedMedia as g, type ViewerTokenResult as h, useDevultur as i, useDevulturApi as j, useDevulturOptional as k, useDevulturProgress as l, useCanDeliver as u };

package/dist/{error-labels-D0Vbp-qA.d.ts → error-labels-Sf6gow24.d.ts}

@@ -1,4 +1,4 @@
-declare const DEVULTUR_ERROR_CODES: readonly ["file_too_large", "content_type_not_allowed", "content_type_mismatch", "content_unverified", "unsupported_content_type", "media_type_mismatch", "already_exists", "write_conflict", "upload_not_found", "invalid_upload_key", "invalid_path", "path_required", "invalid_expires_in", "invalid_file_expires_in", "invalid_cache_control", "invalid_limits", "invalid_prefix", "invalid_visibility", "invalid_cursor", "invalid_sha256", "sha256_mismatch", "max_files_reached", "invalid_multipart", "invalid_size", "invalid_part", "invalid_parts", "part_size_mismatch", "part_sha256_required", "invalid_media_metadata", "expired", "invalid_key", "invalid_max_uses", "link_exists", "link_not_found", "link_expired", "link_used", "not_configured", "retention_active", "lock_conflict", "compliance_extend_only", "lock_privilege_required", "lock_record_unreadable", "lock_below_minimum", "invalid_lock", "invalid_hold", "reserved_key", "keys_bucket_missing", "encryption_key_missing", "unauthorized", "session_mismatch", "token_rejected", "reserved_user_id", "invalid_scopes", "user_mismatch", "transcode_not_configured", "transcode_runner_unavailable", "transcode_launch_failed", "original_not_retained", "locale_not_allowed", "captions_provider_rate_limited", "captions_provider_error", "captions_failed", "webhook_secret_missing", "worker_auth_secret_missing", "worker_error", "http_error", "too_large", "unsupported_type", "type_mismatch", "token_unavailable", "page_cap", "render_failed", "capability_unavailable"];
+declare const DEVULTUR_ERROR_CODES: readonly ["file_too_large", "content_type_not_allowed", "content_type_mismatch", "content_unverified", "unsupported_content_type", "media_type_mismatch", "already_exists", "write_conflict", "upload_not_found", "invalid_upload_key", "invalid_path", "path_required", "invalid_expires_in", "invalid_file_expires_in", "invalid_cache_control", "invalid_limits", "invalid_prefix", "invalid_visibility", "invalid_cursor", "invalid_sha256", "sha256_mismatch", "max_files_reached", "invalid_multipart", "invalid_size", "invalid_part", "invalid_parts", "part_size_mismatch", "part_sha256_required", "invalid_media_metadata", "expired", "invalid_key", "invalid_max_uses", "link_exists", "link_not_found", "link_expired", "link_used", "not_configured", "invalid_grant", "grant_gone", "grant_exhausted", "grant_exists", "grant_in_query", "grant_not_found", "grant_cannot_delete", "link_exceeds_grant", "invalid_link_caps", "invalid_max_links", "invalid_can_delete", "invalid_metadata", "retention_active", "lock_conflict", "compliance_extend_only", "lock_privilege_required", "lock_record_unreadable", "lock_below_minimum", "invalid_lock", "invalid_hold", "reserved_key", "keys_bucket_missing", "encryption_key_missing", "unauthorized", "session_mismatch", "token_rejected", "reserved_user_id", "invalid_scopes", "user_mismatch", "transcode_not_configured", "transcode_runner_unavailable", "transcode_launch_failed", "original_not_retained", "locale_not_allowed", "captions_provider_rate_limited", "captions_provider_error", "captions_failed", "webhook_secret_missing", "worker_auth_secret_missing", "worker_error", "http_error", "too_large", "unsupported_type", "type_mismatch", "token_unavailable", "page_cap", "render_failed", "capability_unavailable"];
 /** A stable error code: match on it, not on `message`. */
 type DevulturErrorCode = (typeof DEVULTUR_ERROR_CODES)[number];
 declare function isDevulturErrorCode(code: unknown): code is DevulturErrorCode;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { FunctionReference, PaginationResult, FunctionVisibility, DefaultFunctio
 import { PropertyValidators, Value, ConvexError } from 'convex/values';
 import { M as MediaRecord, P as ProgressRecord, D as DevulturComponentConfig } from './types-C0ruHUcu.js';
 export { a as DevulturUploadConfig } from './types-C0ruHUcu.js';
-export { a as DEVULTUR_ERROR_CODES, b as DevulturErrorCode, c as DevulturErrorDetails, d as DevulturErrorLabel, D as DevulturErrorLabels, e as describeDevulturError, f as devulturErrorLabels, i as isDevulturErrorCode } from './error-labels-D0Vbp-qA.js';
+export { a as DEVULTUR_ERROR_CODES, b as DevulturErrorCode, c as DevulturErrorDetails, d as DevulturErrorLabel, D as DevulturErrorLabels, e as describeDevulturError, f as devulturErrorLabels, i as isDevulturErrorCode } from './error-labels-Sf6gow24.js';
 export { dv } from './validators.js';
 
 /**

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   devulturErrorOf,
   isDevulturError,
   isDevulturErrorCode
-} from "./chunk-YYOZ3PDH.js";
+} from "./chunk-V5YH4YJG.js";
 
 // src/index.ts
 import {

package/dist/locales/es-formal.d.ts

@@ -1,6 +1,6 @@
 import { VideoPlayerLabels } from '@devultur/react';
 import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-C2nUUY_f.js';
-import { D as DevulturErrorLabels } from '../error-labels-D0Vbp-qA.js';
+import { D as DevulturErrorLabels } from '../error-labels-Sf6gow24.js';
 import '../types-C0ruHUcu.js';
 import '@devultur/core';
 import 'convex/values';

package/dist/locales/es-formal.js

@@ -5,12 +5,12 @@ import {
   mediaPickerLabels,
   previewLabels,
   videoPlayerLabels
-} from "../chunk-RDVBE3G3.js";
+} from "../chunk-34XXHYL3.js";
 import "../chunk-QBHIZBOQ.js";
 import {
   describeDevulturError,
   labelText
-} from "../chunk-YYOZ3PDH.js";
+} from "../chunk-V5YH4YJG.js";
 
 // src/locales/es-formal.ts
 var TRY_AGAIN = "Vuelva a intentarlo.";
@@ -30,6 +30,7 @@ var devulturErrorLabels2 = {
     if (details.field === "tags") return "Use como m\xE1ximo 20 etiquetas, de hasta 50 caracteres cada una.";
     return labelText(devulturErrorLabels.invalid_media_metadata, details);
   },
+  grant_in_query: "Env\xEDe el permiso de descarga en el encabezado Authorization, nunca en una URL.",
   lock_conflict: `La protecci\xF3n del archivo cambi\xF3 mientras tanto. ${TRY_AGAIN}`,
   lock_privilege_required: "No tiene permiso para acortar ni quitar la protecci\xF3n de este archivo.",
   encryption_key_missing: "Este archivo ya no se puede leer. Vuelva a subirlo.",

package/dist/locales/es.d.ts

@@ -1,6 +1,6 @@
 import { VideoPlayerLabels } from '@devultur/react';
 import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-C2nUUY_f.js';
-import { D as DevulturErrorLabels } from '../error-labels-D0Vbp-qA.js';
+import { D as DevulturErrorLabels } from '../error-labels-Sf6gow24.js';
 import '../types-C0ruHUcu.js';
 import '@devultur/core';
 import 'convex/values';

package/dist/locales/es.js

@@ -5,9 +5,9 @@ import {
   mediaPickerLabels,
   previewLabels,
   videoPlayerLabels
-} from "../chunk-RDVBE3G3.js";
+} from "../chunk-34XXHYL3.js";
 import "../chunk-QBHIZBOQ.js";
-import "../chunk-YYOZ3PDH.js";
+import "../chunk-V5YH4YJG.js";
 export {
   attachmentLabels,
   devulturErrorLabels,

package/dist/react/contexts.d.ts

@@ -0,0 +1,6 @@
+export { D as DevulturApi, b as DevulturApiContext, c as DevulturContext, d as DevulturContextValue, e as DevulturProgressContext, f as DevulturProgressContextValue, U as UploadOptions, g as UploadedMedia, u as useCanDeliver, i as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress } from '../contexts-6F8TJINX.js';
+import 'react';
+import '@devultur/core';
+import '@devultur/react';
+import 'convex/server';
+import 'convex/values';

package/dist/react/contexts.js

@@ -0,0 +1,22 @@
+"use client";
+import "../chunk-O76FU54F.js";
+import {
+  DevulturApiContext,
+  DevulturContext,
+  DevulturProgressContext,
+  useCanDeliver,
+  useDevultur,
+  useDevulturApi,
+  useDevulturOptional,
+  useDevulturProgress
+} from "../chunk-FOBFHC4A.js";
+export {
+  DevulturApiContext,
+  DevulturContext,
+  DevulturProgressContext,
+  useCanDeliver,
+  useDevultur,
+  useDevulturApi,
+  useDevulturOptional,
+  useDevulturProgress
+};

package/dist/react/hooks.d.ts

@@ -1,6 +1,39 @@
-export { D as DevulturApi, c as DevulturApiContext, d as DevulturContext, e as DevulturContextValue, f as DevulturProgressContext, g as DevulturProgressContextValue, U as UploadOptions, h as UploadedMedia, V as VideoProps, u as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress, m as useMediaUrl, n as useVideoProps } from '../hooks-uqpBd5UF.js';
+import { DevulturMedia } from '@devultur/core';
+import { M as MediaRenderOptions } from '../contexts-6F8TJINX.js';
+export { D as DevulturApi, b as DevulturApiContext, c as DevulturContext, d as DevulturContextValue, e as DevulturProgressContext, f as DevulturProgressContextValue, U as UploadOptions, g as UploadedMedia, u as useCanDeliver, i as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress } from '../contexts-6F8TJINX.js';
 import 'react';
-import '@devultur/core';
 import '@devultur/react';
 import 'convex/server';
 import 'convex/values';
+
+/**
+ * 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;
+
+export { type VideoProps, useMediaUrl, useVideoProps };

package/dist/react/hooks.js

@@ -1,19 +1,24 @@
 "use client";
+import {
+  useMediaUrl,
+  useVideoProps
+} from "../chunk-AUAWZ5BD.js";
+import "../chunk-O76FU54F.js";
 import {
   DevulturApiContext,
   DevulturContext,
   DevulturProgressContext,
+  useCanDeliver,
   useDevultur,
   useDevulturApi,
   useDevulturOptional,
-  useDevulturProgress,
-  useMediaUrl,
-  useVideoProps
-} from "../chunk-BDEO67OT.js";
+  useDevulturProgress
+} from "../chunk-FOBFHC4A.js";
 export {
   DevulturApiContext,
   DevulturContext,
   DevulturProgressContext,
+  useCanDeliver,
   useDevultur,
   useDevulturApi,
   useDevulturOptional,

package/dist/react.d.ts

@@ -1,11 +1,13 @@
 import React from '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 { V as ViewerTokenAction, a as ViewerTokenArgs, D as DevulturApi } from './contexts-6F8TJINX.js';
+export { b as DevulturApiContext, c as DevulturContext, d as DevulturContextValue, e as DevulturProgressContext, f as DevulturProgressContextValue, T as TokenStatus, U as UploadOptions, g as UploadedMedia, h as ViewerTokenResult, u as useCanDeliver, i as useDevultur, j as useDevulturApi, k as useDevulturOptional, l as useDevulturProgress } from './contexts-6F8TJINX.js';
 import { BakeOutputFormat, MediaUploadState, MediaUploadError } from '@devultur/react';
 export { MediaUploadError, MediaUploadState, UploadProgress } from '@devultur/react';
 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 { VideoProps } from './react/hooks.js';
+export { useMediaUrl, useVideoProps } from './react/hooks.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';

package/dist/react.js

@@ -1,4 +1,9 @@
 "use client";
+import {
+  useMediaUrl,
+  useRequestTokenWhen,
+  useVideoProps
+} from "./chunk-AUAWZ5BD.js";
 import {
   mediaFromRecord
 } from "./chunk-KAIVI7RB.js";
@@ -23,20 +28,18 @@ import {
 } from "./chunk-QBHIZBOQ.js";
 import {
   describeDevulturError
-} from "./chunk-YYOZ3PDH.js";
+} from "./chunk-V5YH4YJG.js";
 import {
   DevulturApiContext,
   DevulturCapabilityError,
   DevulturContext,
   DevulturProgressContext,
+  useCanDeliver,
   useDevultur,
   useDevulturApi,
   useDevulturOptional,
-  useDevulturProgress,
-  useMediaUrl,
-  useRequestTokenWhen,
-  useVideoProps
-} from "./chunk-BDEO67OT.js";
+  useDevulturProgress
+} from "./chunk-FOBFHC4A.js";
 
 // src/react.tsx
 import React26 from "react";
@@ -2609,6 +2612,7 @@ export {
   formatDuration,
   formatFileSize,
   matchesAccept,
+  useCanDeliver,
   useDevultur,
   useDevulturApi,
   useDevulturMedia,

package/docs/guides/plugins.md

@@ -8,7 +8,7 @@ same API as yours. Add plugins to extend the Worker, or replace a default one.
 import { createWorker, defaultPlugins } from "@devultur/self-host";
 import { usageLog } from "./plugins/usage-log";
 
-export { DownloadLink } from "@devultur/self-host";
+export { DownloadGrants, DownloadLink } from "@devultur/self-host";
 
 export default createWorker({
   plugins: [...defaultPlugins({ transcode: { maxResolution: "1080p" } }), usageLog()],
@@ -22,7 +22,7 @@ export default createWorker({
 | `staticConfig(config)` | Applies the [rules](self-host.md#rules) to every request. Put it first: later plugins narrow it. |
 | `workerSecretAuth()` | Control routes require `Authorization: Bearer <WORKER_AUTH_SECRET>`; the transcode runner uploads with the same secret. |
 | `credentialPolicy(options?)` | Decides before a credential is issued. Without options it issues what is asked; `maxTtlSeconds: { viewer: 3600 }` caps a kind. |
-| `downloadLinks()` | `POST /v1/token/download` and `GET /v1/download/<id>` (needs the `DOWNLOAD_LINKS` Durable Object). Without it both answer `404`. |
+| `downloadLinks()` | `POST /v1/token/download` and `GET /v1/download/<id>` (needs the `DOWNLOAD_LINKS` Durable Object), and download grants: `/v1/token/grant` and `/v1/grant/*` (also need `DOWNLOAD_GRANTS`). Without it they answer `404`. |
 
 `createWorker()` refuses to start when no plugin authenticates requests, so dropping `workerSecretAuth()` without
 an auth plugin of yours fails at deploy, not in production.
@@ -42,6 +42,7 @@ interface WorkerPlugin {
   routes?: Array<{ path: string; app: Hono }>;
   issueCredential?: (context: Context, request: CredentialRequest) => CredentialDecision | Promise<CredentialDecision>;
   beforeLinkRedeem?: (context: Context, link: DownloadLinkInfo) => Response | null | Promise<Response | null>;
+  authorizeGrant?: (context: Context, request: GrantAccessRequest) => Response | null | Promise<Response | null>;
   authorizeLockChange?: (context: Context, request: LockChangeRequest) => LockChangeDecision | Promise<LockChangeDecision>;
   onLockAudit?: (context: Context, record: LockAuditRecord) => void | Promise<void>;
 }
@@ -94,8 +95,8 @@ updateRequestState(context, { context: { appId: "web" } });
 
 ## Hooks
 
-**`issueCredential`** runs before the Worker issues a viewer token, an upload token, a download link or the runner's
-service token. It gets the `kind`, the `scopes`, the `path` it is bound to and the requested `expiresAt` (epoch ms).
+**`issueCredential`** runs before the Worker issues a viewer token, an upload token, a download link, a download grant
+or the runner's service token. It gets the `kind`, the `scopes`, the `path` it is bound to and the requested `expiresAt` (epoch ms).
 Return `{ allow: false, response }` to refuse, or `{ allow: true, expiresAt?, claims? }` to issue it: `expiresAt`
 caps the expiry, and `claims` are added to a token. The hooks of every plugin run in order: the first refusal wins,
 the earliest `expiresAt` applies, and the claims of all of them are added.
@@ -120,6 +121,12 @@ allow gets `403 { "code": "token_rejected" }`; which claim failed is only logged
 **`beforeLinkRedeem`** runs before `GET /v1/download/<id>` spends a use of a link. Return a `Response` to refuse it
 (the use isn't spent), or `null` to let it go on. It gets the link's `storagePrefix`, `key` and plugin `context`.
 
+**`authorizeGrant`** runs before a download grant is used, once the Worker checked the grant is live and belongs to the
+request's storage prefix: `action` is `head`, `issue-link`, `delete-file` or `revoke` (its bearer), or `owner-revoke`
+(the owner, by its public id). It also gets the `grant` (its key, caps, `linksIssued`, metadata and the plugin `context`
+it was issued with, never its secret). Return a `Response` to refuse (a refused link spends nothing), or `null`. Use it
+to tie a grant to the credential that issued it, for example to refuse it once that credential is revoked.
+
 **`authorizeLockChange`** runs before the Worker changes a lock ([Retention and holds](object-lock.md)):
 `PUT /v1/lock/<key>` once per change, and `POST /v1/lock/hold` once per page. It gets:
 
@@ -173,7 +180,8 @@ const auditToD1: WorkerPlugin = {
 ## After the route
 
 - `getRouteResult(context)` tells a middleware that runs after `await next()` what the route did: `redeemedLink`
-  (the download link just redeemed), `originalDeleted` (`transcode.complete` deleted the original),
+  (the download link just redeemed), `issuedGrant` and `revokedGrant` (a download grant, with its public id; a revoke
+  says `by: "bearer"` or `"owner"`), `grantDeletedKey` (a grant deleted its file), `originalDeleted` (`transcode.complete` deleted the original),
   `originalRetained` (it kept a locked original instead) and
   `transcodeJob` (the job a runner callback belongs to, with its plugin `context`).
 - `getPendingUpload(context)`, before the route, returns the upload an upload URL points to: its key, storage key,

package/docs/guides/self-host.md

@@ -44,7 +44,7 @@ media Worker from `@devultur/self-host`:
 
 ```typescript
 import { createWorker } from "@devultur/self-host";
-export { DownloadLink } from "@devultur/self-host";
+export { DownloadGrants, DownloadLink } from "@devultur/self-host";
 
 export default createWorker();
 ```
@@ -98,7 +98,7 @@ It prints a config snippet with the new namespace's `id`. Paste that id into the
 
 #### 4. Write `wrangler.toml`
 
-Bind both buckets, the KV namespace and the `DownloadLink` Durable Object:
+Bind both buckets, the KV namespace and the `DownloadLink` and `DownloadGrants` Durable Objects:
 
 ```toml
 name = "media"
@@ -123,13 +123,22 @@ id = "<kv-namespace-id>"
 name = "DOWNLOAD_LINKS"
 class_name = "DownloadLink"
 
+[[durable_objects.bindings]]
+name = "DOWNLOAD_GRANTS"
+class_name = "DownloadGrants"
+
 [[migrations]]
 tag = "v1"
 new_sqlite_classes = ["DownloadLink"]
+
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["DownloadGrants"]
 ```
 
-Without the `DOWNLOAD_LINKS` binding, `POST /v1/token/download` answers `501`. For staging and production in one
-file, see [Per-environment config](#per-environment-config).
+Without the `DOWNLOAD_LINKS` binding, `POST /v1/token/download` answers `501`; without `DOWNLOAD_GRANTS`, the download
+grant routes do. A Worker deployed before download grants keeps its `v1` migration and adds `v2`. For staging and
+production in one file, see [Per-environment config](#per-environment-config).
 
 #### 5. Set the secrets
 
@@ -189,6 +198,10 @@ account_id = "<your-account-id>"
 tag = "v1"
 new_sqlite_classes = ["DownloadLink"]
 
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["DownloadGrants"]
+
 # Staging
 [env.staging]
 name = "media-staging"
@@ -209,6 +222,10 @@ id = "<staging-kv-namespace-id>"
 name = "DOWNLOAD_LINKS"
 class_name = "DownloadLink"
 
+[[env.staging.durable_objects.bindings]]
+name = "DOWNLOAD_GRANTS"
+class_name = "DownloadGrants"
+
 # Production
 [env.production]
 name = "media-production"
@@ -228,6 +245,10 @@ id = "<production-kv-namespace-id>"
 [[env.production.durable_objects.bindings]]
 name = "DOWNLOAD_LINKS"
 class_name = "DownloadLink"
+
+[[env.production.durable_objects.bindings]]
+name = "DOWNLOAD_GRANTS"
+class_name = "DownloadGrants"
 ```
 
 `vars` aren't inherited either: repeat `[env.<name>.vars]` (for example `TRANSCODE_RUNNER`) in each one. Then set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/convex",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Convex component for Devultur media: media records, uploads, transcodes, watch progress and React bindings",
   "keywords": [
     "convex",
@@ -69,8 +69,8 @@
     "docs"
   ],
   "dependencies": {
-    "@devultur/core": "1.5.1",
-    "@devultur/react": "1.5.1"
+    "@devultur/core": "1.6.0",
+    "@devultur/react": "1.6.0"
   },
   "peerDependencies": {
     "convex": ">=1.25.0",
@@ -102,7 +102,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/validators.ts src/react.tsx src/react/hooks.ts src/pdfjs.ts src/locales/es.ts src/locales/es-formal.ts src/bin/init.ts --format esm --dts --clean && tsc -p src/component/tsconfig.json && node scripts/add-import-extensions.ts && node ../../scripts/copy-guides.mts",
+    "build": "tsup src/index.ts src/validators.ts src/react.tsx src/react/hooks.ts src/react/contexts.ts src/pdfjs.ts src/locales/es.ts src/locales/es-formal.ts src/bin/init.ts --format esm --dts --clean && tsc -p src/component/tsconfig.json && node scripts/add-import-extensions.ts && node ../../scripts/copy-guides.mts",
     "codegen": "node scripts/codegen.ts",
     "dev": "tsup src/index.ts src/react.tsx --format esm --dts --watch",
     "typecheck": "tsc --noEmit"