nuxt-media-library 0.0.61 → 0.0.63

package/README.md

@@ -188,8 +188,85 @@ export default createMLCatchAllProxy({
   and, when `serviceUploads.proxy` is on, the service-upload pass-through.
   Your catch-all handles everything else under `/api/media-library`.
 
+### Showing media on public pages (embedded media)
+
+Public pages never resolve an asset id. Each service puts the media into its
+own response (Python: `pkg_media`'s `MediaEmbedder`, or `StrawberryMedia` for
+GraphQL), having decided who may see what. The page renders the fields it gets:
+
+```ts
+interface EmbeddedMedia {          // from the service's GraphQL schema (codegen)
+  assetId: string
+  kind: 'image' | 'video' | 'audio' | 'document' | 'other'
+  url: string | null               // the file; null when denied or not ready
+  poster: string | null            // the one image to show; set even when denied
+  sources: { url: string, width: number, height?: number | null }[]  // poster sizes
+  streams: { hls?: string | null, dash?: string | null } | null
+  width?: number | null; height?: number | null; alt?: string | null
+  expiresIn: number | null         // seconds until the first link expires; null = never
+  public: boolean                  // every link tokenless (cache-safe)
+}
+```
+
+The module auto-imports the helpers that read it (a structural type,
+`MLEmbeddedMedia`, so any codegen type fits):
+
+| Helper | Gives |
+|---|---|
+| `mlMediaPoster(media, fallback?)` | the image to show, else `fallback` |
+| `mlMediaSrcset(media)` | `srcset` from `media.sources`, or `undefined` |
+| `mlPlayableSource(media, { preferFile? })` | `{ src, type: 'hls' \| 'progressive' }`: the HLS ladder, else the file; `null` when locked or not ready |
+| `mlIsPlayableVideo(media)` | a video the viewer can play now |
+| `useMLMediaRenewal(media, renew, { marginSeconds?, retrySeconds? })` | calls `renew` 5 minutes (default) before tokened links expire, and again every 30 s (default) while it fails; browser only |
+
+```vue
+<script setup lang="ts">
+const { data: item } = await useAsyncData('article', fetchArticle)
+// Re-fetch before the links expire and swap in only `media`.
+useMLMediaRenewal(() => item.value?.media, async () => {
+  const fresh = await fetchArticle()
+  if (item.value && fresh?.media) item.value = { ...item.value, media: fresh.media }
+})
+const source = computed(() => mlPlayableSource(item.value?.media))
+</script>
+
+<template>
+  <!-- `sizes` is the box's widest rendered width. -->
+  <img
+    :src="mlMediaPoster(item?.media, '/placeholder.jpg')"
+    :srcset="mlMediaSrcset(item?.media)"
+    sizes="(min-width: 1024px) 420px, 100vw"
+    alt=""
+    loading="lazy"
+  >
+  <!-- A video: the app's own player (hls.js for type 'hls'). -->
+  <AppVideoPlayer v-if="source" :src="source.src" :type="source.type" :poster="item?.media?.poster" />
+</template>
+```
+
+- **Locked or missing:** `url` and `streams` are null; show `poster` (and a
+  paywall). No call to the media library can do better.
+- **Renewal:** tokened links expire (`expiresIn`). `useMLMediaRenewal` fetches the
+  record again before then; swap in only the new `media` and resume the player at
+  its playhead (key the player on its source).
+- **SEO:** pass `media.poster` (and the service's embedded share image) to your
+  SEO helper as URLs; the HTML rendered on the server then carries them.
+- **Caching:** a response with a tokened link is per user (`public: false`);
+  don't cache it at the edge.
+- `useMLAssetPreview`, `<MLPreviewProvider>` and `v-asset` resolve ids in the
+  browser through `/delivery`. They are **deprecated** (a warning in dev) and go
+  with `/delivery`; so do read grants (below).
+
+Design and rulings: [`docs/design/embedded-media.md`](docs/design/embedded-media.md).
+Moving a service and its layer over, step by step:
+[`docs/design/embedded-media-migration-guide.md`](docs/design/embedded-media-migration-guide.md).
+
 ### Showing assets of several services: read grants
 
+> **Deprecated** with `/delivery`: public pages show embedded media instead
+> (see above), and no grant is needed.
+
+
 Every link comes from the media library; each service decides only for its
 own assets by returning a read grant (`mlg_…`, e.g. the Python client's
 `client.grants.read(ids)`) with the data that references them. Hand the

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "media-library",
   "configKey": "mediaLibrary",
-  "version": "0.0.61",
+  "version": "0.0.63",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { defineNuxtModule, createResolver, addImportsDir, addComponentsDir, addServerHandler, useLogger, addPlugin } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addImportsDir, addImports, addComponentsDir, addServerHandler, useLogger, addPlugin } from '@nuxt/kit';
 import { browserHeaders } from '../dist/runtime/utils/credentialHeaders.js';
 import { normalizeBackends } from '../dist/runtime/utils/backends.js';
 export * from '../dist/runtime/types/resourcePolicy.js';
@@ -53,6 +53,10 @@ const module$1 = defineNuxtModule({
     const resolver = createResolver(import.meta.url);
     const runtimeDir = resolver.resolve("./runtime");
     addImportsDir(resolver.resolve("runtime/composables"));
+    addImports(["mlMediaPoster", "mlMediaSrcset", "mlPlayableSource", "mlIsPlayableVideo"].map((name) => ({
+      name,
+      from: resolver.resolve("runtime/utils/embeddedMedia")
+    })));
     nuxt.options.build.transpile ||= [];
     nuxt.options.build.transpile.push(runtimeDir);
     const existingPrivate = nuxt.options.runtimeConfig.mediaLibrary || {};

package/dist/runtime/components/MLPreviewProvider.vue

@@ -1,11 +1,13 @@
 <script setup>
 import { computed, watch } from "vue";
 import { useMLAssetPreview } from "../composables/useMLAssetPreview";
+import { warnDeprecated } from "../utils/deprecation";
 const props = defineProps({
   assetId: { type: [String, null], required: false },
   fallbackSrc: { type: [String, null], required: false },
   autoRegister: { type: Boolean, required: false, default: true }
 });
+warnDeprecated("<MLPreviewProvider>");
 const assetsStore = useMLAssetPreview();
 const asset = computed(
   () => props.assetId ? assetsStore.getAsset(props.assetId) : void 0

package/dist/runtime/composables/useMLAssetPreview.d.ts

@@ -6,6 +6,7 @@ declare function markBroken(id?: string | null): void;
 declare function clearBroken(id?: string | null): void;
 declare function ensureAssets(ids: string[]): Promise<void>;
 declare function register(id?: string | null): void;
+/** @deprecated Show the service's embedded media instead (see `warnDeprecated`). */
 export declare const useMLAssetPreview: () => {
     assets: import("vue").Ref<Record<string, AssetPreview>, Record<string, AssetPreview>>;
     pending: import("vue").Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>;

package/dist/runtime/composables/useMLAssetPreview.js

@@ -3,6 +3,7 @@ import { $fetch } from "ofetch";
 import { mediaGrantHeaders } from "./useMLMediaGrants.js";
 import { onMediaGrantsAdded } from "../utils/grants/listeners.js";
 import { streamUrlsStale } from "../utils/streamUrls.js";
+import { warnDeprecated } from "../utils/deprecation.js";
 const assets = ref({});
 const pending = ref(/* @__PURE__ */ new Set());
 const broken = ref(/* @__PURE__ */ new Set());
@@ -159,6 +160,7 @@ onMediaGrantsAdded(() => {
   if (import.meta.client) scheduleFetch();
 });
 export const useMLAssetPreview = () => {
+  warnDeprecated("useMLAssetPreview()");
   return {
     assets,
     pending,

package/dist/runtime/composables/useMLMediaRenewal.d.ts

@@ -0,0 +1,28 @@
+import { type MaybeRefOrGetter } from 'vue';
+import type { MLEmbeddedMedia } from '../types/embeddedMedia.js';
+export interface UseMLMediaRenewalOptions {
+    /** Seconds before expiry to renew. Default 300. */
+    marginSeconds?: number;
+    /**
+     * Seconds to wait before trying again when `renew` rejects (a transient
+     * network error must not let the links expire mid-playback). Default 30.
+     */
+    retrySeconds?: number;
+}
+/**
+ * The renewal loop without the client guard: watches `media` and calls
+ * `renew` shortly before its links expire. Returns a stop function. Prefer
+ * `useMLMediaRenewal`, which runs this in the browser only.
+ */
+export declare function watchMLMediaRenewal(media: MaybeRefOrGetter<MLEmbeddedMedia | null | undefined>, renew: () => Promise<unknown>, { marginSeconds, retrySeconds }?: UseMLMediaRenewalOptions): () => void;
+/**
+ * Keeps embedded media links alive: tokened links expire (`expiresIn`), so
+ * shortly before they do this calls `renew`, which re-fetches the record and
+ * swaps in its fresh `media`. Tokenless media (`expiresIn: null`) is left
+ * alone. Browser only; stops with the calling scope.
+ *
+ * Swap only `media` in `renew` rather than refreshing the whole page's data,
+ * so the page does not fall back to its loading state mid-playback; a player
+ * keyed on its source resumes at its playhead.
+ */
+export declare function useMLMediaRenewal(media: MaybeRefOrGetter<MLEmbeddedMedia | null | undefined>, renew: () => Promise<unknown>, options?: UseMLMediaRenewalOptions): void;

package/dist/runtime/composables/useMLMediaRenewal.js

@@ -0,0 +1,38 @@
+import { onScopeDispose, toValue, watch } from "vue";
+import { refreshDelay } from "../utils/streamUrls.js";
+const DEFAULT_MARGIN_SECONDS = 300;
+const DEFAULT_RETRY_SECONDS = 30;
+export function watchMLMediaRenewal(media, renew, { marginSeconds = DEFAULT_MARGIN_SECONDS, retrySeconds = DEFAULT_RETRY_SECONDS } = {}) {
+  let timer = null;
+  let generation = 0;
+  const clear = () => {
+    generation++;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+  const arm = (delay) => {
+    const current = generation;
+    timer = setTimeout(() => {
+      timer = null;
+      renew().catch((err) => {
+        console.warn("[nuxt-media-library] media renewal failed, retrying:", err);
+        if (current === generation) arm(retrySeconds * 1e3);
+      });
+    }, delay);
+  };
+  const stopWatch = watch(() => toValue(media), (current) => {
+    clear();
+    const now = Date.now();
+    const delay = refreshDelay(current?.expiresIn, now, now, marginSeconds);
+    if (delay == null) return;
+    arm(delay);
+  }, { immediate: true });
+  return () => {
+    stopWatch();
+    clear();
+  };
+}
+export function useMLMediaRenewal(media, renew, options = {}) {
+  if (!import.meta.client) return;
+  onScopeDispose(watchMLMediaRenewal(media, renew, options));
+}

package/dist/runtime/index.d.ts

@@ -25,6 +25,9 @@ export * from './utils/assetFormat.js';
 export * from './utils/fileAccept.js';
 export * from './utils/processingSteps.js';
 export * from './utils/streamUrls.js';
+export * from './utils/embeddedMedia.js';
+export * from './types/embeddedMedia.js';
+export * from './composables/useMLMediaRenewal.js';
 export * from './utils/webAppDeploys.js';
 export * from './composables/useMLWebAppDeploys.js';
 export * from './composables/useMLMediaMeta.js';

package/dist/runtime/index.js

@@ -25,6 +25,9 @@ export * from "./utils/assetFormat.js";
 export * from "./utils/fileAccept.js";
 export * from "./utils/processingSteps.js";
 export * from "./utils/streamUrls.js";
+export * from "./utils/embeddedMedia.js";
+export * from "./types/embeddedMedia.js";
+export * from "./composables/useMLMediaRenewal.js";
 export * from "./utils/webAppDeploys.js";
 export * from "./composables/useMLWebAppDeploys.js";
 export * from "./composables/useMLMediaMeta.js";

package/dist/runtime/plugins/asset-direcetive-client.js

@@ -1,6 +1,7 @@
 import { defineNuxtPlugin } from "#app";
 import { watch } from "vue";
 import { useMLAssetPreview } from "../composables/useMLAssetPreview.js";
+import { warnDeprecated } from "../utils/deprecation.js";
 function applyAssetToElement(el, asset, arg) {
   if (!asset || !asset.url) return;
   if (arg === "bg") {
@@ -33,6 +34,7 @@ function setupWatcher(el, id, arg) {
 }
 const assetDirective = {
   mounted(el, binding) {
+    warnDeprecated("v-asset");
     if (import.meta.server) return;
     const id = binding.value || "";
     const arg = binding.arg;

package/dist/runtime/types/embeddedMedia.d.ts

@@ -0,0 +1,25 @@
+export interface MLEmbeddedMediaSource {
+    url: string;
+    width: number;
+    height?: number | null;
+}
+export interface MLEmbeddedMedia {
+    kind?: string | null;
+    /** The file; null when the viewer may not open it or it is not ready. */
+    url?: string | null;
+    /** The one image to show; set even for a viewer who may not open the file. */
+    poster?: string | null;
+    /** The poster's sizes, smallest first. */
+    sources?: readonly MLEmbeddedMediaSource[] | null;
+    streams?: {
+        hls?: string | null;
+        dash?: string | null;
+    } | null;
+    /** Seconds until the first carried link expires; null: none expires. */
+    expiresIn?: number | null;
+}
+/** What a player plays: the HLS ladder (adaptive), else the file. */
+export interface MLPlayableSource {
+    src: string;
+    type: 'hls' | 'progressive';
+}

package/dist/runtime/utils/deprecation.d.ts

@@ -0,0 +1,2 @@
+export declare const EMBEDDED_MEDIA_HINT: string;
+export declare function warnDeprecated(name: string, hint?: string): void;

package/dist/runtime/utils/deprecation.js

@@ -0,0 +1,7 @@
+const warned = /* @__PURE__ */ new Set();
+export const EMBEDDED_MEDIA_HINT = "Show the media the owning service embeds in its response instead (`media.poster`, `media.sources`, `media.streams.hls`, `media.url`); the browser should not resolve asset ids. See nuxt-media-library docs/design/embedded-media-migration-guide.md.";
+export function warnDeprecated(name, hint = EMBEDDED_MEDIA_HINT) {
+  if (!import.meta.dev || warned.has(name)) return;
+  warned.add(name);
+  console.warn(`[nuxt-media-library] ${name} is deprecated and goes with the media library's /delivery. ${hint}`);
+}

package/dist/runtime/utils/embeddedMedia.d.ts

@@ -0,0 +1,20 @@
+import type { MLEmbeddedMedia, MLPlayableSource } from '../types/embeddedMedia.js';
+/** The image to show, or `fallback` when the media has none. */
+export declare function mlMediaPoster<F extends string | null | undefined = undefined>(media: MLEmbeddedMedia | null | undefined, fallback?: F): string | F;
+/**
+ * `srcset` for the poster `<img>`: its sizes from `media.sources`, so the
+ * browser loads the size the box needs (pair it with a `sizes` that is an
+ * upper bound of the rendered width). Undefined when there are none: `src`
+ * is then the only size.
+ */
+export declare function mlMediaSrcset(media: MLEmbeddedMedia | null | undefined): string | undefined;
+/**
+ * What a player should play: the HLS ladder, else the file. `preferFile`
+ * skips the ladder (a player falling back after the stream failed). Null when
+ * the viewer may not play it or it is not ready.
+ */
+export declare function mlPlayableSource(media: MLEmbeddedMedia | null | undefined, { preferFile }?: {
+    preferFile?: boolean;
+}): MLPlayableSource | null;
+/** A video the viewer can play now (a stream or the file). */
+export declare function mlIsPlayableVideo(media: MLEmbeddedMedia | null | undefined): boolean;

package/dist/runtime/utils/embeddedMedia.js

@@ -0,0 +1,15 @@
+export function mlMediaPoster(media, fallback) {
+  return media?.poster || fallback;
+}
+export function mlMediaSrcset(media) {
+  const sources = media?.sources;
+  return sources?.length ? sources.map((s) => `${s.url} ${s.width}w`).join(", ") : void 0;
+}
+export function mlPlayableSource(media, { preferFile = false } = {}) {
+  if (!media) return null;
+  if (!preferFile && media.streams?.hls) return { src: media.streams.hls, type: "hls" };
+  return media.url ? { src: media.url, type: "progressive" } : null;
+}
+export function mlIsPlayableVideo(media) {
+  return media?.kind === "video" && !!mlPlayableSource(media);
+}

package/dist/runtime/utils/streamUrls.d.ts

@@ -5,5 +5,12 @@ import type { StreamUrlFields } from '../types/asset.js';
  * Null when the asset has no stream URLs or no lifetime (nothing to refresh).
  */
 export declare function streamUrlsRefreshDelay(asset: StreamUrlFields | null | undefined, resolvedAt: number, now?: number, marginSeconds?: number): number | null;
+/**
+ * Milliseconds from `now` until links that lasted `ttlSeconds` from
+ * `resolvedAt` (ms epoch) should be fetched again, `marginSeconds` early
+ * (capped at half the lifetime); 0 when already due. Null when there is no
+ * lifetime: the links never expire.
+ */
+export declare function refreshDelay(ttlSeconds: number | null | undefined, resolvedAt: number, now?: number, marginSeconds?: number): number | null;
 /** True when the asset's stream URLs are expired or about to. */
 export declare function streamUrlsStale(asset: StreamUrlFields | null | undefined, resolvedAt: number, now?: number, marginSeconds?: number): boolean;

package/dist/runtime/utils/streamUrls.js

@@ -1,10 +1,12 @@
 const DEFAULT_MARGIN_SECONDS = 30;
 export function streamUrlsRefreshDelay(asset, resolvedAt, now = Date.now(), marginSeconds = DEFAULT_MARGIN_SECONDS) {
   if (!asset || !asset.hlsUrl && !asset.dashUrl) return null;
-  const ttl = asset.streamUrlExpiresIn;
-  if (ttl == null || !Number.isFinite(ttl) || ttl <= 0) return null;
-  const margin = Math.min(marginSeconds, ttl / 2);
-  return Math.max(0, resolvedAt + (ttl - margin) * 1e3 - now);
+  return refreshDelay(asset.streamUrlExpiresIn, resolvedAt, now, marginSeconds);
+}
+export function refreshDelay(ttlSeconds, resolvedAt, now = Date.now(), marginSeconds = DEFAULT_MARGIN_SECONDS) {
+  if (ttlSeconds == null || !Number.isFinite(ttlSeconds) || ttlSeconds <= 0) return null;
+  const margin = Math.min(marginSeconds, ttlSeconds / 2);
+  return Math.max(0, resolvedAt + (ttlSeconds - margin) * 1e3 - now);
 }
 export function streamUrlsStale(asset, resolvedAt, now = Date.now(), marginSeconds = DEFAULT_MARGIN_SECONDS) {
   return streamUrlsRefreshDelay(asset, resolvedAt, now, marginSeconds) === 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-media-library",
-  "version": "0.0.61",
+  "version": "0.0.63",
   "description": "Nuxt module for media library management — chunked uploads, asset previews, and resource policies",
   "repository": {
     "type": "git",