umedia 0.4.2 → 0.5.0

package/lib/providers/youtube.js

@@ -1,146 +0,0 @@
-import { parseDuration, hostMatches } from "../util.js";
-import { Codes, UMediaError } from "../errors.js";
-
-/** YouTube via InnerTube (youtubei.js) — search + metadata always; stream URLs when the network allows. */
-export const name = "youtube";
-
-let _engine = null;
-async function engine() {
-  if (!_engine) {
-    const { Innertube } = await import("youtubei.js");
-    _engine = await Innertube.create({ retrieve_player: true });
-  }
-  return _engine;
-}
-
-export function canHandle(url) {
-  try {
-    return hostMatches(new URL(String(url)).hostname, ["youtube.com", "youtu.be", "youtube-nocookie.com"]);
-  } catch { return false; }
-}
-
-export function videoId(url) {
-  const u = new URL(String(url));
-  if (u.hostname.includes("youtu.be")) return u.pathname.slice(1).split("/")[0];
-  if (u.searchParams.get("v")) return u.searchParams.get("v");
-  const m = u.pathname.match(/\/(shorts|embed|live|v)\/([^/?#]+)/);
-  return m ? m[2] : null;
-}
-
-export async function search({ q, type = "video", limit = 12 }, ctx = {}) {
-  const attempt = { provider: name, status: "skipped" };
-  ctx.attempts?.push(attempt);
-  const t0 = Date.now();
-  try {
-    const e = await engine();
-    let query = q;
-    if (type === "movie") query = `${q} trailer`;
-    const res = await e.search(query, { type: "video" });
-    attempt.status = "success";
-    attempt.latencyMs = Date.now() - t0;
-    return (res.videos || []).slice(0, limit).map((v) => {
-      const id = v.id;
-      return {
-        id,
-        title: v.title?.text ?? String(v.title ?? ""),
-        author: v.author?.name ?? v.author ?? null,
-        pageUrl: `https://www.youtube.com/watch?v=${id}`,
-        thumbnail: v.thumbnails?.[v.thumbnails.length - 1]?.url ?? null,
-        duration: parseDuration(v.duration?.text) ?? v.duration?.seconds ?? null,
-        mediaType: type === "music" ? "music" : v.type === "short" ? "short_video" : "video",
-        source: name,
-        previewUrl: `https://www.youtube.com/embed/${id}`,
-        previewKind: type === "movie" ? "trailer" : "embed",
-      };
-    });
-  } catch (e) {
-    attempt.status = "failed";
-    attempt.error = e.message;
-    return [];
-  }
-}
-
-function fmtToVariant(f, url) {
-  return {
-    quality: f.quality_label || (f.height ? `${f.height}p` : f.quality || "unknown"),
-    width: f.width ?? null,
-    height: f.height ?? null,
-    url: url ?? null,
-    mimeType: (f.mime_type || "").split(";")[0] || null,
-    bitrateKbps: f.bitrate ? Math.round(f.bitrate / 1000) : null,
-    hasAudio: Boolean(f.has_audio),
-    hasVideo: Boolean(f.has_video),
-  };
-}
-
-export async function resolve(url, ctx = {}) {
-  const attempt = { provider: name, status: "skipped" };
-  ctx.attempts?.push(attempt);
-  const id = videoId(url);
-  if (!id) throw new UMediaError(Codes.INVALID_URL, `Not a recognizable YouTube URL: ${url}`);
-  const t0 = Date.now();
-  try {
-    const e = await engine();
-    const info = await e.getInfo(id);
-    attempt.status = "success";
-    attempt.latencyMs = Date.now() - t0;
-    const b = info.basic_info || {};
-    const all = [...(info.streaming_data?.formats || []), ...(info.streaming_data?.adaptive_formats || [])];
-
-    // stream URLs: present when the network isn't bot-gated; otherwise honest nulls
-    const variants = [];
-    for (const f of all) {
-      let u = null;
-      if (f.url) u = f.url;
-      else if (f.signature_cipher || f.cipher) {
-        try {
-          u = await f.decipher(e.session?.player);
-        } catch { u = null; }
-      }
-      variants.push(fmtToVariant(f, u));
-    }
-    const withUrls = variants.filter((v) => v.url);
-    const best = withUrls.sort((a, b2) => (b2.height || 0) - (a.height || 0))[0] || variants.sort((a, b2) => (b2.height || 0) - (a.height || 0))[0];
-
-    return {
-      result: {
-        sourceUrl: url,
-        platform: "youtube",
-        title: b.title ?? null,
-        author: b.author ?? null,
-        thumbnail: b.thumbnail?.[b.thumbnail.length - 1]?.url ?? null,
-        itemCount: 1,
-        counts: { images: 0, videos: 1, audios: 0, other: 0 },
-        truncated: false,
-        media: [{
-          type: "video",
-          index: 0,
-          url: best?.url ?? null,
-          thumbnail: b.thumbnail?.[b.thumbnail.length - 1]?.url ?? null,
-          mimeType: best?.mimeType ?? null,
-          width: best?.width ?? null,
-          height: best?.height ?? null,
-          duration: b.duration ?? null,
-          size: null,
-          quality: best?.quality ?? null,
-          hasAudio: best?.hasAudio ?? null,
-          hasVideo: best?.hasVideo ?? null,
-          source: name,
-          variants,
-        }],
-        streamUrlsAvailable: withUrls.length > 0,
-        streamAccess: withUrls.length > 0 ? "direct"
-          : "withheld — YouTube is bot-gating this network; install yt-dlp for hard networks",
-      },
-      engine: {
-        attempts: ctx.attempts || [attempt],
-        finalProvider: name,
-        totalLatencyMs: Date.now() - t0,
-      },
-    };
-  } catch (e) {
-    attempt.status = "failed";
-    attempt.error = e.message;
-    throw new UMediaError(e instanceof UMediaError ? e.code : Codes.PROVIDER_ERROR, `YouTube resolve failed: ${e.message}`, { attempts: [attempt] });
-  }
-}

package/lib/providers/ytdlp.js

@@ -1,97 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { Codes, UMediaError } from "../errors.js";
-
-/**
- * Optional yt-dlp power tier. If `yt-dlp` is on PATH (or UMedia_YTDLP points at it),
- * it unlocks 1800+ sites and hard networks (PO tokens, cookies, muxing).
- * Labeled honestly as source: "ytdlp" — never silently mixed with native results.
- */
-export const name = "ytdlp";
-
-let _path;
-export function binary() {
-  if (_path !== undefined) return _path;
-  const probe = process.env.UMedia_YTDLP || "yt-dlp";
-  try {
-    const r = spawnSync(probe, ["--version"], { encoding: "utf8", timeout: 8000 });
-    _path = r.status === 0 ? probe : null;
-  } catch { _path = null; }
-  return _path;
-}
-
-export function canHandle() {
-  return Boolean(binary());
-}
-
-export function probe(url, extra = []) {
-  const bin = binary();
-  if (!bin) throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, "yt-dlp not installed — `pip install yt-dlp` to enable the 1800+ sites tier");
-  const r = spawnSync(bin, ["--no-playlist", "-J", ...extra, url], {
-    encoding: "utf8", timeout: 120_000, maxBuffer: 64 * 1024 * 1024,
-  });
-  if (r.status !== 0) {
-    throw new UMediaError(Codes.PROVIDER_ERROR, `yt-dlp failed: ${(r.stderr || "").split("\n").slice(-2)[0] || "unknown error"}`);
-  }
-  return JSON.parse(r.stdout);
-}
-
-export async function resolve(url, ctx = {}) {
-  const attempt = { provider: name, status: "skipped" };
-  ctx.attempts?.push(attempt);
-  const t0 = Date.now();
-  try {
-    const info = probe(url);
-    attempt.status = "success";
-    attempt.latencyMs = Date.now() - t0;
-    const entries = info.entries || [info];
-    const media = entries.slice(0, 200).map((e, i) => ({
-      type: e._type === "image" ? "image" : (e.vcodec && e.vcodec !== "none") ? "video" : "audio",
-      index: i,
-      url: e.url || e.entries?.[0]?.url || null,
-      thumbnail: e.thumbnail ?? null,
-      mimeType: null,
-      width: e.width ?? null,
-      height: e.height ?? null,
-      duration: e.duration ?? null,
-      size: e.filesize ?? e.filesize_approx ?? null,
-      quality: e.height ? `${e.height}p` : null,
-      hasAudio: e.acodec && e.acodec !== "none",
-      hasVideo: e.vcodec && e.vcodec !== "none",
-      source: name,
-      variants: (e.formats || []).filter((f) => f.url).map((f) => ({
-        quality: f.format_note || (f.height ? `${f.height}p` : "unknown"),
-        width: f.width ?? null, height: f.height ?? null, url: f.url,
-        mimeType: (f.ext ? `video/${f.ext}` : null),
-        bitrateKbps: f.tbr ? Math.round(f.tbr) : null,
-        hasAudio: Boolean(f.acodec && f.acodec !== "none"),
-        hasVideo: Boolean(f.vcodec && f.vcodec !== "none"),
-      })),
-    }));
-    return {
-      result: {
-        sourceUrl: url,
-        platform: info.extractor_key?.toLowerCase() ?? "ytdlp",
-        title: info.title ?? null,
-        author: info.uploader ?? info.channel ?? null,
-        thumbnail: info.thumbnail ?? null,
-        itemCount: media.length,
-        counts: {
-          images: media.filter((m) => m.type === "image").length,
-          videos: media.filter((m) => m.type === "video").length,
-          audios: media.filter((m) => m.type === "audio").length, other: 0,
-        },
-        truncated: Boolean(info.entries && info.entries.length > 200),
-        media,
-      },
-      engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
-    };
-  } catch (e) {
-    attempt.status = "failed";
-    attempt.error = e.message;
-    throw e instanceof UMediaError ? e : new UMediaError(Codes.PROVIDER_ERROR, e.message, { attempts: [attempt] });
-  }
-}
-
-export async function search() {
-  return [];
-}

package/lib/quality.js

@@ -1,49 +0,0 @@
-/** Honest quality ladder — heights come from the real source, never invented. */
-export const LADDER = ["original", "best", "2160p", "1440p", "1080p", "720p", "480p", "360p", "240p", "144p", "audio"];
-
-export function heightOf(quality) {
-  const m = /^(\d+)p$/.exec(String(quality || ""));
-  return m ? Number(m[1]) : null;
-}
-
-export function labelOfHeight(h) {
-  return h ? `${h}p` : "unknown";
-}
-
-/**
- * Pick the best format whose real height <= requested (fallback: closest available).
- * @returns {{format: object|null, requestedQuality: string, selectedQuality: string|null, fallback: boolean}}
- */
-export function pickFormat(formats, requestedQuality = "best") {
-  const req = String(requestedQuality || "best").toLowerCase();
-  const usable = (formats || []).filter((f) => f && (f.height || f.audioOnly));
-  if (!usable.length) return { format: null, requestedQuality: req, selectedQuality: null, fallback: false };
-
-  if (req === "audio") {
-    const audios = usable.filter((f) => f.audioOnly);
-    const format = audios[0] || null;
-    return { format, requestedQuality: req, selectedQuality: format ? "audio" : null, fallback: false };
-  }
-  const videos = usable.filter((f) => f.height);
-  if (!videos.length) {
-    return { format: null, requestedQuality: req, selectedQuality: null, fallback: false };
-  }
-  const sorted = [...videos].sort((a, b) => b.height - a.height);
-  if (req === "original" || req === "best") {
-    const format = sorted[0];
-    return { format, requestedQuality: req, selectedQuality: labelOfHeight(format.height), fallback: false };
-  }
-  const target = heightOf(req);
-  if (!target) {
-    const format = sorted[0];
-    return { format, requestedQuality: req, selectedQuality: labelOfHeight(format.height), fallback: true };
-  }
-  const atOrBelow = sorted.find((f) => f.height <= target);
-  const format = atOrBelow || sorted[sorted.length - 1];
-  return {
-    format,
-    requestedQuality: req,
-    selectedQuality: labelOfHeight(format.height),
-    fallback: format.height !== target,
-  };
-}

package/lib/registry.js

@@ -1,222 +0,0 @@
-import * as yt from "./providers/youtube.js";
-import * as tiktok from "./providers/tiktok.js";
-import * as pinterest from "./providers/pinterest.js";
-import * as soundcloud from "./providers/soundcloud.js";
-import * as dailymotion from "./providers/dailymotion.js";
-import * as vimeo from "./providers/vimeo.js";
-import * as streamable from "./providers/streamable.js";
-import * as twitch from "./providers/twitch.js";
-import * as bluesky from "./providers/bluesky.js";
-import * as reddit from "./providers/reddit.js";
-import * as xprov from "./providers/x.js";
-import * as ig from "./providers/instagram.js";
-import * as facebook from "./providers/facebook.js";
-import * as threads from "./providers/threads.js";
-import * as snapchat from "./providers/snapchat.js";
-import * as rumble from "./providers/rumble.js";
-import * as tumblr from "./providers/tumblr.js";
-import * as ytdlp from "./providers/ytdlp.js";
-import * as itunes from "./providers/itunes.js";
-import { Codes, UMediaError } from "./errors.js";
-import { validateUrl } from "./util.js";
-
-const NATIVE = [yt, tiktok, pinterest, soundcloud, dailymotion, vimeo, streamable, twitch, bluesky, reddit, xprov, ig, facebook, threads, snapchat, rumble, tumblr];
-
-export function detectPlatform(url) {
-  for (const p of NATIVE) {
-    try { if (p.canHandle(url)) return p.name; } catch { /* bad URL — keep scanning */ }
-  }
-  return ytdlp.binary() ? "ytdlp" : "unknown";
-}
-
-const DIRECT_MEDIA = /\.(mp4|webm|m4a|mp3|aac|wav|jpg|jpeg|png|gif|webp|mov|mkv)(\?|#|$)/i;
-
-/** Signed CDN blob URLs have no file extension — probe the content-type honestly. */
-async function probeDirectMedia(url) {
-  try {
-    let res = await fetch(url, {
-      method: "HEAD",
-      headers: { "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36" },
-      redirect: "follow",
-      signal: AbortSignal.timeout(12_000),
-    });
-    if (!res.ok && res.status !== 405) {
-      res = await fetch(url, {
-        headers: { "user-agent": "Mozilla/5.0", range: "bytes=0-0" },
-        redirect: "follow",
-        signal: AbortSignal.timeout(12_000),
-      });
-    }
-    const ct = (res.headers.get("content-type") || "").split(";")[0].trim();
-    const kind = /^video\//.test(ct) ? "video" : /^audio\//.test(ct) ? "audio" : /^image\//.test(ct) ? "image" : null;
-    return kind ? { kind, mimeType: ct } : null;
-  } catch {
-    return null;
-  }
-}
-
-function directResult(url, kind, mimeType, note) {
-  return {
-    data: {
-      sourceUrl: url, platform: "direct",
-      title: String(url).split("/").pop()?.split("?")[0] || "Direct media",
-      author: null, thumbnail: kind === "video" ? null : url,
-      itemCount: 1,
-      counts: { images: kind === "image" ? 1 : 0, videos: kind === "video" ? 1 : 0, audios: kind === "audio" ? 1 : 0, other: 0 },
-      truncated: false,
-      media: [{
-        type: kind, index: 0, url: String(url), thumbnail: null, mimeType: mimeType ?? null,
-        width: null, height: null, duration: null, size: null, quality: "original",
-        hasAudio: kind !== "image", hasVideo: kind !== "audio", source: "direct", variants: [],
-      }],
-    },
-    engine: { attempts: [{ provider: "direct", status: "success", note }], finalProvider: "direct", totalLatencyMs: 0 },
-  };
-}
-
-/** Resolve a URL: native adapter first, optional yt-dlp fallback. attempts[] is the honest trail. */
-export async function resolve(url) {
-  // SSRF hygiene FIRST — never dispatch or fetch private/internal targets (bots pass user URLs!)
-  validateUrl(url);
-
-  // direct media URL (an image/video/audio file) -> single-item result, no platform needed
-  const direct = String(url).split("#")[0].match(DIRECT_MEDIA);
-  if (direct) {
-    const ext = direct[1].toLowerCase();
-    const kind = ["mp4", "webm", "mov", "mkv"].includes(ext) ? "video"
-      : ["jpg", "jpeg", "png", "gif", "webp"].includes(ext) ? "image" : "audio";
-    return {
-      data: {
-        sourceUrl: url, platform: "direct",
-        title: String(url).split("/").pop() || "Direct media",
-        author: null, thumbnail: kind === "video" ? null : url,
-        itemCount: 1,
-        counts: { images: kind === "image" ? 1 : 0, videos: kind === "video" ? 1 : 0, audios: kind === "audio" ? 1 : 0, other: 0 },
-        truncated: false,
-        media: [{
-          type: kind, index: 0, url: String(url), thumbnail: null, mimeType: null,
-          width: null, height: null, duration: null, size: null, quality: "original",
-          hasAudio: kind !== "image", hasVideo: kind !== "audio", source: "direct", variants: [],
-        }],
-      },
-      engine: { attempts: [{ provider: "direct", status: "success" }], finalProvider: "direct", totalLatencyMs: 0 },
-    };
-  }
-
-  const ctx = { attempts: [] };
-  let lastTyped = null;
-  for (const p of NATIVE) {
-    if (!p.canHandle(url)) continue;
-    try {
-      const r = await p.resolve(url, ctx);
-      return { data: r.result, engine: r.engine };
-    } catch (e) {
-      if (e instanceof UMediaError && [Codes.MEDIA_NOT_FOUND, Codes.CONTENT_PRIVATE, Codes.SSRF_BLOCKED, Codes.INVALID_URL].includes(e.code)) {
-        // definitive outcome for this platform — don't mask it with fallbacks
-        e.attempts = ctx.attempts;
-        throw e;
-      }
-      // transient/provider failure → try the next layer
-      if (e instanceof UMediaError) lastTyped = e;
-      continue;
-    }
-  }
-  if (ytdlp.binary()) {
-    try {
-      const r = await ytdlp.resolve(url, ctx);
-      return { data: r.result, engine: r.engine };
-    } catch (e) {
-      e.attempts = ctx.attempts;
-      throw e;
-    }
-  }
-  const last = ctx.attempts[ctx.attempts.length - 1];
-  // extension-less signed CDN URLs: honest content-type probe before refusing
-  if (detectPlatform(url) === "unknown") {
-    const probe = await probeDirectMedia(url);
-    if (probe) return directResult(url, probe.kind, probe.mimeType, "direct media URL (content-type probe)");
-    throw new UMediaError(Codes.INVALID_URL,
-      `No provider could resolve this URL${last?.error ? " Last error: " + last.error : ""}. Tip: install yt-dlp to unlock 1800+ sites and hard networks.`,
-      { attempts: ctx.attempts });
-  }
-  // surface the real provider error when every matching provider failed —
-  // never mask a typed outcome behind a generic message
-  if (lastTyped) {
-    lastTyped.attempts = ctx.attempts;
-    throw lastTyped;
-  }
-  throw new UMediaError(
-    Codes.PROVIDER_UNAVAILABLE,
-    `No provider could resolve this URL.${last?.error ? " Last error: " + last.error : ""}` +
-      (ytdlp.binary() ? "" : " Tip: install yt-dlp to unlock 1800+ sites and hard networks."),
-    { attempts: ctx.attempts },
-  );
-}
-
-/** Multi-source search. Music leads with iTunes 30s previews, then YouTube. */
-export async function search({ q, type = "video", limit = 12, adult = false } = {}) {
-  const ctx = { attempts: [] };
-  const out = [];
-  const plan = type === "music" ? [itunes, yt] : [yt];
-  for (const p of plan) {
-    if (out.length >= limit) break;
-    const items = await p.search({ q, type, limit: limit - out.length }, ctx);
-    out.push(...items);
-  }
-  return { items: out.slice(0, limit), attempts: ctx.attempts };
-}
-
-export function capabilities() {
-  return {
-    platforms: [
-      { platform: "youtube", search: true, resolve: true, download: "network-dependent (yt-dlp tier recommended)", notes: "search+metadata always; stream URLs depend on network/PO-token state" },
-      { platform: "tiktok", search: false, resolve: true, download: true, notes: "video posts = direct CDN mp4; galleries = every slide the platform exposes (truncated flag honest)" },
-      { platform: "pinterest", search: false, resolve: true, download: true, notes: "image pins, video pins (direct mp4), idea/story pins, pin.it links" },
-      { platform: "soundcloud", search: false, resolve: true, download: true, notes: "full tracks: direct progressive MP3 + HLS, real titles/artists" },
-      { platform: "dailymotion", search: false, resolve: true, download: true, notes: "public metadata API; HLS/progressive renditions" },
-      { platform: "vimeo", search: false, resolve: true, download: true, notes: "player config: progressive mp4 when served, HLS otherwise" },
-      { platform: "streamable", search: false, resolve: true, download: true, notes: "direct mp4 renditions" },
-      { platform: "twitch", search: false, resolve: true, download: true, notes: "clips = direct mp4s; VODs/livestreams via yt-dlp tier" },
-      { platform: "bluesky", search: false, resolve: true, download: true, notes: "public AppView API: full-size images + video playlists" },
-      { platform: "instagram", search: false, resolve: true, download: true, notes: "oEmbed→mobile info API: photos, videos, full carousels" },
-      { platform: "reddit", search: false, resolve: true, download: true, notes: "posts + galleries + video with audio sidecar" },
-      { platform: "x", search: false, resolve: true, download: true, notes: "syndication token + guest GraphQL — photos/videos/gifs" },
-      { platform: "facebook", search: false, resolve: true, download: true, notes: "reels/watch/videos/shares/fb.watch via the player JSON" },
-      { platform: "threads", search: false, resolve: true, download: true, notes: "post SSR state + og media" },
-      { platform: "snapchat", search: false, resolve: true, download: true, notes: "spotlight videos + public story snap lists" },
-      { platform: "rumble", search: false, resolve: true, download: true, notes: "embed API: direct mp4 renditions" },
-      { platform: "tumblr", search: false, resolve: true, download: true, notes: "mobile API: video/audio/photo posts + reblog trails" },
-      { platform: "itunes", search: true, resolve: false, download: "previews", notes: "real 30s clips" },
-      { platform: "ytdlp", search: false, resolve: Boolean(ytdlp.binary()), download: Boolean(ytdlp.binary()), notes: "optional tier: 1800+ sites — install yt-dlp" },
-    ],
-    qualityLadder: ["original", "best", "2160p", "1440p", "1080p", "720p", "480p", "360p", "240p", "144p", "audio"],
-  };
-}
-
-export function status() {
-  return {
-    overall: "operational",
-    runtime: { node: process.version, platform: process.platform },
-    providers: [
-      { name: "youtube", state: "operational", via: "youtubei.js" },
-      { name: "tiktok", state: "operational", via: "embed state" },
-      { name: "pinterest", state: "operational", via: "public widget API" },
-      { name: "soundcloud", state: "operational", via: "public api-v2" },
-      { name: "dailymotion", state: "operational", via: "player metadata" },
-      { name: "vimeo", state: "operational", via: "player config" },
-      { name: "streamable", state: "operational", via: "public video api" },
-      { name: "twitch", state: "operational", via: "public GraphQL (clips)" },
-      { name: "bluesky", state: "operational", via: "public AppView XRPC" },
-      { name: "instagram", state: "operational", via: "oEmbed + mobile info api" },
-      { name: "reddit", state: "operational", via: "public json" },
-      { name: "x", state: "operational", via: "syndication + guest graphql" },
-      { name: "facebook", state: "operational", via: "web player json" },
-      { name: "threads", state: "operational", via: "share page state" },
-      { name: "snapchat", state: "operational", via: "spotlight + story state" },
-      { name: "rumble", state: "operational", via: "embed json api" },
-      { name: "tumblr", state: "operational", via: "mobile api" },
-      { name: "itunes", state: "operational", via: "search api" },
-      { name: "ytdlp", state: ytdlp.binary() ? "operational" : "unavailable", via: "external binary" },
-    ],
-  };
-}

package/lib/util.js

@@ -1,93 +0,0 @@
-import { UMediaError, Codes } from "./errors.js";
-
-export const UA =
-  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36";
-
-export function rid() {
-  return "req_" + Math.random().toString(16).slice(2, 10) + Date.now().toString(16).slice(-8);
-}
-
-/** Hostname match: exact or dot-suffix (www-insensitive). */
-export function hostMatches(hostname, list) {
-  const h = String(hostname || "").toLowerCase().replace(/^www\./, "");
-  return list.some((d) => h === d || h.endsWith("." + d));
-}
-
-/** http(s) only, no private/loopback/link-local targets (SSRF hygiene). */
-export function validateUrl(raw) {
-  let u;
-  try {
-    u = new URL(String(raw || "").trim());
-  } catch {
-    throw new UMediaError(Codes.INVALID_URL, `Invalid URL: ${String(raw).slice(0, 120)}`);
-  }
-  if (!/^https?:$/.test(u.protocol)) {
-    throw new UMediaError(Codes.INVALID_URL, `Only http(s) URLs are supported — got ${u.protocol}`);
-  }
-  const host = u.hostname.toLowerCase();
-  if (
-    host === "localhost" || host.endsWith(".local") || host.endsWith(".internal") ||
-    /^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) ||
-    /^172\.(1[6-9]|2\d|3[01])\./.test(host) || /^169\.254\./.test(host) ||
-    host === "0.0.0.0" || host === "::1" || host === "[::1]"
-  ) {
-    throw new UMediaError(Codes.SSRF_BLOCKED, `Refusing private/internal host: ${host}`);
-  }
-  return u;
-}
-
-export async function fetchJson(url, opts = {}, timeoutMs = 20_000) {
-  const ctl = new AbortController();
-  const t = setTimeout(() => ctl.abort(), timeoutMs);
-  try {
-    const res = await fetch(url, {
-      ...opts,
-      signal: ctl.signal,
-      headers: { "user-agent": UA, ...(opts.headers || {}) },
-    });
-    if (!res.ok) {
-      throw new UMediaError(
-        res.status === 429 ? Codes.RATE_LIMITED : res.status === 404 ? Codes.NOT_FOUND : Codes.PROVIDER_ERROR,
-        `HTTP ${res.status} from ${new URL(url).hostname}`,
-        { status: res.status },
-      );
-    }
-    return await res.json();
-  } catch (e) {
-    if (e instanceof UMediaError) throw e;
-    if (e.name === "AbortError") throw new UMediaError(Codes.TIMEOUT, `Timed out after ${timeoutMs}ms: ${new URL(url).hostname}`);
-    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Network error from ${new URL(url).hostname}: ${e.message}`);
-  } finally {
-    clearTimeout(t);
-  }
-}
-
-export async function fetchText(url, opts = {}, timeoutMs = 20_000) {
-  const ctl = new AbortController();
-  const t = setTimeout(() => ctl.abort(), timeoutMs);
-  try {
-    const res = await fetch(url, {
-      ...opts,
-      signal: ctl.signal,
-      headers: { "user-agent": UA, ...(opts.headers || {}) },
-    });
-    return { status: res.status, text: await res.text(), headers: res.headers };
-  } catch (e) {
-    if (e.name === "AbortError") throw new UMediaError(Codes.TIMEOUT, `Timed out after ${timeoutMs}ms: ${new URL(url).hostname}`);
-    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Network error from ${new URL(url).hostname}: ${e.message}`);
-  } finally {
-    clearTimeout(t);
-  }
-}
-
-export function parseDuration(text) {
-  if (text == null) return null;
-  if (typeof text === "number") return text;
-  const p = String(text).split(":").map(Number);
-  if (p.some(Number.isNaN)) return null;
-  return p.reduce((acc, n) => acc * 60 + n, 0);
-}
-
-export function cleanName(s) {
-  return String(s || "media").replace(/[\\/:*?"<>|]/g, "_").slice(0, 120).trim() || "media";
-}