@devultur/convex 1.5.1 → 1.5.2

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-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/{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/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";
@@ -29,14 +34,12 @@ import {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/convex",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "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.5.2",
+    "@devultur/react": "1.5.2"
   },
   "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"