umedia 0.4.2 → 0.5.0

package/lib/download.js

@@ -1,248 +0,0 @@
-import { createWriteStream } from "node:fs";
-import { mkdir, stat, rename } from "node:fs/promises";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import path from "node:path";
-import { zipSync } from "fflate";
-import { UMediaError, Codes } from "./errors.js";
-import { UA, cleanName, rid, validateUrl } from "./util.js";
-import { pickFormat } from "./quality.js";
-import * as registry from "./registry.js";
-import * as ytdlp from "./providers/ytdlp.js";
-
-async function fetchToFile(url, dest, onProgress) {
-  const res = await fetch(url, { headers: { "user-agent": UA }, redirect: "follow" });
-  if (!res.ok) throw new UMediaError(Codes.PROVIDER_ERROR, `HTTP ${res.status} fetching media`);
-  const total = Number(res.headers.get("content-length") || 0);
-  await mkdir(path.dirname(dest), { recursive: true });
-  const ws = createWriteStream(dest);
-  let done = 0;
-  const readable = Readable.fromWeb(res.body);
-  readable.on("data", (chunk) => {
-    done += chunk.length;
-    onProgress?.(done, total);
-  });
-  await pipeline(readable, ws);
-  const s = await stat(dest);
-  return s.size;
-}
-
-/**
- * HLS (.m3u8) -> real file on disk: pick a variant by its REAL RESOLUTION label,
- * fetch segments in order, concat to MPEG-TS (playable, no ffmpeg needed).
- * Video-only (separate audio) or fMP4 streams fail honestly and point at yt-dlp.
- * @returns {Promise<{size:number, height:number|null}>}
- */
-async function downloadHls(url, dest, onProgress) {
-  const getText = async (u) => {
-    const res = await fetch(u, { headers: { "user-agent": UA }, redirect: "follow" });
-    if (!res.ok) throw new UMediaError(Codes.PROVIDER_ERROR, `HTTP ${res.status} fetching HLS manifest`);
-    return res.text();
-  };
-  let manifest = await getText(url);
-  let base = url;
-  let pickedHeight = null;
-  let fmp4 = false;
-
-  if (manifest.includes("#EXT-X-STREAM-INF")) {
-    const lines = manifest.split(/\r?\n/);
-    let best = null;
-    for (let i = 0; i < lines.length; i++) {
-      if (!lines[i].startsWith("#EXT-X-STREAM-INF")) continue;
-      const res = /RESOLUTION=(\d+)x(\d+)/.exec(lines[i]);
-      const codecs = /CODECS="([^"]+)"/.exec(lines[i])?.[1] || "";
-      const h = res ? parseInt(res[2], 10) : 0;
-      const urlLine = lines.slice(i + 1).find((l) => l && !l.startsWith("#"));
-      if (!urlLine) continue;
-      if (!best || h > best.h) best = { url: new URL(urlLine, base).href, codecs, h };
-    }
-    if (!best) throw new UMediaError(Codes.PROVIDER_ERROR, "HLS master has no variants");
-    if (best.codecs && !/mp4a|opus|ac-3|ec-3/.test(best.codecs)) {
-      throw new UMediaError(Codes.QUALITY_UNAVAILABLE,
-        "HLS variant is video-only (separate audio track) — muxing needs the yt-dlp tier: downloadWithYtdlp()");
-    }
-    pickedHeight = best.h || null;
-    base = best.url;
-    manifest = await getText(base);
-  }
-  if (manifest.includes("#EXT-X-MAP")) {
-    // fMP4: init segment + media fragments concat to a valid fragmented MP4
-    fmp4 = true;
-  }
-  const mapUri = /#EXT-X-MAP:URI="([^"]+)"/.exec(manifest)?.[1] || null;
-  const segs = manifest.split(/\r?\n/).filter((l) => l && !l.startsWith("#")).map((l) => new URL(l, base).href);
-  if (!segs.length) throw new UMediaError(Codes.PROVIDER_ERROR, "HLS media playlist has no segments");
-
-  await mkdir(path.dirname(dest), { recursive: true });
-  const ws = createWriteStream(dest);
-  if (fmp4 && mapUri) {
-    const initRes = await fetch(new URL(mapUri, base).href, { headers: { "user-agent": UA }, redirect: "follow" });
-    if (!initRes.ok) throw new UMediaError(Codes.PROVIDER_ERROR, `HTTP ${initRes.status} fetching fMP4 init segment`);
-    const initBuf = Buffer.from(await initRes.arrayBuffer());
-    await new Promise((r, j) => ws.write(initBuf, (e) => (e ? j(e) : r())));
-  }
-  let done = 0;
-  for (const seg of segs) {
-    const res = await fetch(seg, { headers: { "user-agent": UA }, redirect: "follow" });
-    if (!res.ok) throw new UMediaError(Codes.PROVIDER_ERROR, `HTTP ${res.status} fetching HLS segment`);
-    const buf = Buffer.from(await res.arrayBuffer());
-    await new Promise((r, j) => ws.write(buf, (e) => (e ? j(e) : r())));
-    done += 1;
-    onProgress?.(done, segs.length);
-  }
-  await new Promise((r) => ws.end(r));
-  const st = await stat(dest);
-  return { size: st.size, height: pickedHeight, ext: fmp4 ? "mp4" : "ts" };
-}
-
-/**
- * Download every media item of a URL to disk — order preserved, failures named.
- * Direct media URLs (clips, images) download as a single item — no page-resolve needed.
- * @returns {Promise<{data: DownloadResult, meta}>}
- */
-const MEDIA_EXT = /\.(mp4|webm|m4a|mp3|aac|wav|jpg|jpeg|png|gif|webp|mov|mkv)(\?|#|$)/i;
-
-export async function download({ url, quality = "best", type = "video", dir = "./umedia-downloads", onProgress, zip = false } = {}) {
-  const requestId = rid();
-  const t0 = Date.now();
-
-  // SSRF hygiene FIRST — user-supplied URLs must never reach private/internal hosts
-  validateUrl(url);
-
-  let resolved, engine;
-  if (MEDIA_EXT.test(String(url).split("#")[0])) {
-    const ext = (String(url).match(MEDIA_EXT) || [])[1].toLowerCase();
-    const kind = /^(jpg|jpeg|png|gif|webp)$/.test(ext) ? "image" : /^(m4a|mp3|aac|wav)$/.test(ext) ? "audio" : "video";
-    resolved = {
-      sourceUrl: url, platform: "direct",
-      title: decodeURIComponent(String(url).split("/").pop().split("?")[0]) || "media",
-      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, thumbnail: null, mimeType: null,
-        width: null, height: null, duration: null, size: null, quality: null,
-        hasAudio: kind !== "image", hasVideo: kind !== "audio", source: "direct", variants: [],
-      }],
-    };
-    engine = { attempts: [{ provider: "direct", status: "success" }], finalProvider: "direct", totalLatencyMs: 0 };
-  } else {
-    ({ data: resolved, engine } = await registry.resolve(url));
-  }
-
-  // quality selection happens on real heights of the resolved items
-  const files = [];
-  const failedItems = [];
-  let selectedQuality = null;
-  let fallback = false;
-
-  await mkdir(dir, { recursive: true });
-
-  for (const item of resolved.media) {
-    try {
-      const pick = pickFormat(
-        item.variants?.length ? item.variants.map((v) => ({
-          height: v.height, audioOnly: v.hasAudio && !v.hasVideo, url: v.url,
-        })) : [{ height: item.height, audioOnly: item.type === "audio", url: item.url }],
-        item.type === "audio" ? "audio" : quality,
-      );
-      const chosenUrl = pick.format?.url || item.url;
-      if (!chosenUrl) {
-        throw new UMediaError(Codes.PROVIDER_UNAVAILABLE,
-          "no direct media URL available on this network (bot-gated) — install yt-dlp for hard networks");
-      }
-      validateUrl(chosenUrl); // never fetch private/internal targets, even from a provider response
-      if (!selectedQuality) { selectedQuality = pick.selectedQuality; fallback = pick.fallback; }
-
-      const isHls = /\.m3u8$/i.test(chosenUrl.split(/[?#]/)[0]);
-      let ext = isHls ? "ts" : ((chosenUrl.split("?")[0].match(/\.(mp4|webm|m4a|mp3|jpg|jpeg|png|gif|webp)$/) || [])[1]
-        || (item.type === "image" ? "jpg" : item.type === "audio" ? "m4a" : "mp4"));
-      const base = cleanName(resolved.title);
-      let name = `${String(item.index + 1).padStart(3, "0")} - ${base.toLowerCase().endsWith(`.${ext}`) ? base.slice(0, -(ext.length + 1)) : base}.${ext}`;
-      let dest = path.join(dir, name);
-      let size, hlsHeight = null, hlsExt = null;
-      if (isHls) {
-        ({ size, height: hlsHeight, ext: hlsExt } = await downloadHls(chosenUrl, dest, onProgress));
-        if (hlsHeight) selectedQuality = `${hlsHeight}p`; // the REAL rendition downloaded
-        if (hlsExt && hlsExt !== ext) {
-          // fMP4 concat produces a real .mp4 — rename so the file never lies about its container
-          ext = hlsExt;
-          name = name.replace(/\.ts$/, `.${ext}`);
-          dest = path.join(dir, name);
-          await rename(`${dest.replace(new RegExp(`\\.${ext}$`), ".ts")}`, dest).catch(() => {});
-        }
-      } else {
-        size = await fetchToFile(chosenUrl, dest, onProgress);
-      }
-      const fileQuality = (isHls && hlsHeight) ? `${hlsHeight}p` : (pick.selectedQuality ?? item.quality ?? null);
-      files.push({ name, path: dest, size, ext, mimeType: item.mimeType ?? null, index: item.index, quality: fileQuality });
-    } catch (e) {
-      failedItems.push({ index: item.index, type: item.type, url: String(item.url || "").slice(0, 120), error: e.message });
-    }
-  }
-
-  if (!files.length) {
-    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE,
-      `Nothing could be downloaded (${failedItems[0]?.error || "unknown"}). Every failure: ${JSON.stringify(failedItems)}`,
-      { requestId, attempts: engine?.attempts ?? [] });
-  }
-
-  if (zip && files.length > 1) {
-    const chunks = {};
-    for (const f of files) {
-      const { readFile } = await import("node:fs/promises");
-      chunks[f.name] = new Uint8Array(await readFile(f.path));
-    }
-    const zipped = zipSync(chunks);
-    const { writeFile } = await import("node:fs/promises");
-    const zipName = `${cleanName(resolved.title)}.zip`;
-    const zipPath = path.join(dir, zipName);
-    await writeFile(zipPath, zipped);
-    files.push({ name: zipName, path: zipPath, size: zipped.length, ext: "zip", mimeType: "application/zip", index: files.length, quality: null });
-  }
-
-  return {
-    data: {
-      url, title: resolved.title ?? null, source: resolved.platform ?? null,
-      requestedQuality: quality,
-      selectedQuality,
-      fallback,
-      files,
-      itemCount: files.length,
-      requestedItems: resolved.media.length,
-      truncated: Boolean(resolved.truncated),
-      failedItems,
-    },
-    meta: { requestId, source: resolved.platform ?? null, timestamp: new Date().toISOString(), elapsedMs: Date.now() - t0 },
-    engine,
-  };
-}
-
-/** yt-dlp escape hatch for downloads on hard networks / 1800+ sites. */
-export async function downloadWithYtdlp({ url, quality = "best", dir = "./umedia-downloads", onProgress } = {}) {
-  const requestId = rid();
-  validateUrl(url);
-  if (!ytdlp.binary()) throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, "yt-dlp not installed — `pip install yt-dlp`");
-  await mkdir(dir, { recursive: true });
-  const { spawn } = await import("node:child_process");
-  return new Promise((resolve, reject) => {
-    const fmt = quality === "audio" ? "bestaudio/best" : quality === "best" || quality === "original" ? "bestvideo*+bestaudio/best" : `bestvideo[height<=${parseInt(quality, 10) || 1080}]+bestaudio/best`;
-    const args = ["--no-playlist", "-f", fmt, "-o", path.join(dir, "%(title).80s [%(id)s].%(ext)s"), "--newline", url];
-    const p = spawn(ytdlp.binary(), args);
-    let lastLine = "";
-    p.stdout.on("data", (d) => {
-      const s = d.toString();
-      lastLine = s.split("\n").filter(Boolean).pop() || lastLine;
-      const m = lastLine.match(/(\d+\.\d+)%/);
-      if (m && onProgress) onProgress(Number(m[1]), 100);
-    });
-    let err = "";
-    p.stderr.on("data", (d) => { err += d.toString(); });
-    p.on("close", (code) => {
-      if (code !== 0) return reject(new UMediaError(Codes.PROVIDER_ERROR, `yt-dlp exited ${code}: ${err.split("\n").slice(-2)[0] || ""}`, { requestId }));
-      resolve({
-        data: { url, requestedQuality: quality, selectedQuality: quality, fallback: false, files: [], itemCount: 0, requestedItems: 0, truncated: false, failedItems: [], note: "saved by yt-dlp into " + dir },
-        meta: { requestId, source: "ytdlp", timestamp: new Date().toISOString(), elapsedMs: 0 },
-      });
-    });
-  });
-}

package/lib/errors.js

@@ -1,30 +0,0 @@
-/** Stable error contract — every failure is typed, honest, traceable. */
-export const Codes = Object.freeze({
-  INVALID_REQUEST: "INVALID_REQUEST",
-  INVALID_URL: "INVALID_URL",
-  SSRF_BLOCKED: "SSRF_BLOCKED",
-  AUTH_REQUIRED: "AUTH_REQUIRED",
-  AUTH_INVALID: "AUTH_INVALID",
-  RATE_LIMITED: "RATE_LIMITED",
-  MEDIA_NOT_FOUND: "MEDIA_NOT_FOUND",
-  CONTENT_PRIVATE: "CONTENT_PRIVATE",
-  ACCESS_RESTRICTED: "ACCESS_RESTRICTED",
-  QUALITY_UNAVAILABLE: "QUALITY_UNAVAILABLE",
-  PROVIDER_ERROR: "PROVIDER_ERROR",
-  PROVIDER_UNAVAILABLE: "PROVIDER_UNAVAILABLE",
-  TIMEOUT: "TIMEOUT",
-  NOT_FOUND: "NOT_FOUND",
-  INTERNAL: "INTERNAL",
-});
-
-export class UMediaError extends Error {
-  constructor(code, message, opts = {}) {
-    super(message);
-    this.name = "UMediaError";
-    this.code = code || Codes.INTERNAL;
-    this.status = opts.status ?? 0;
-    this.requestId = opts.requestId ?? null;
-    this.attempts = opts.attempts ?? [];
-    this.details = opts.details ?? null;
-  }
-}

package/lib/providers/bluesky.js

@@ -1,118 +0,0 @@
-import { fetchJson, hostMatches } from "../util.js";
-import { Codes, UMediaError } from "../errors.js";
-
-/**
- * Bluesky — the PUBLIC AppView XRPC API (api.bsky.app / public.api.bsky.app):
- * full-size images and video playlists, no auth, no key. Handles and DIDs both
- * work in bsky.app URLs.
- */
-export const name = "bluesky";
-
-export function canHandle(url) {
-  try {
-    return hostMatches(new URL(String(url)).hostname, ["bsky.app", "bsky.social"]);
-  } catch { return false; }
-}
-
-export function parseUrl(url) {
-  const m = String(url).match(/bsky\.app\/profile\/([\w.\-:%]+)\/post\/([\w]+)/i);
-  return m ? { actor: decodeURIComponent(m[1]), rkey: m[2] } : null;
-}
-
-export async function resolve(url, ctx = {}) {
-  const attempt = { provider: name, status: "skipped" };
-  ctx.attempts?.push(attempt);
-  const t0 = Date.now();
-
-  const parsed = parseUrl(url);
-  if (!parsed) {
-    attempt.status = "failed";
-    throw new UMediaError(Codes.INVALID_URL, "Not a Bluesky post URL (expected bsky.app/profile/{handle}/post/{rkey})", { attempts: [attempt] });
-  }
-
-  // handle -> DID (posts are addressed by DID)
-  let did = parsed.actor.startsWith("did:") ? parsed.actor : null;
-  if (!did) {
-    try {
-      const prof = await fetchJson(`https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=${encodeURIComponent(parsed.actor)}`, {}, 15_000);
-      did = prof?.did;
-    } catch { /* fall through to at://handle attempt */ }
-  }
-
-  let post = null;
-  for (const uri of [`at://${did || parsed.actor}/app.bsky.feed.post/${parsed.rkey}`]) {
-    try {
-      const j = await fetchJson(
-        `https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?uri=${encodeURIComponent(uri)}&depth=0`, {}, 15_000);
-      post = j?.thread?.post || null;
-      if (post) break;
-    } catch (e) { attempt.error = e.message; }
-  }
-  if (!post) {
-    attempt.status = "failed";
-    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Bluesky post not retrievable. ${attempt.error || "deleted or private"}`, { attempts: [attempt] });
-  }
-
-  const media = [];
-  const record = post.record || {};
-  const embed = post.embed || {};
-
-  // images: full-size originals, in post order (view embed carries real URLs)
-  const embType = String(embed.$type || "");
-  const mediaEmb = embed.media ? String(embed.media.$type || "") : "";
-  const images = (embType.startsWith("app.bsky.embed.images") && embed.images)
-    || (mediaEmb.startsWith("app.bsky.embed.images") && embed.media?.images)
-    || [];
-  for (const img of images) {
-    const u = img.fullsize || img.url;
-    if (!u) continue;
-    media.push({
-      type: "image", index: media.length, url: u, thumbnail: img.thumb || u,
-      mimeType: "image/jpeg", width: null, height: null, duration: null, size: null,
-      quality: "original", hasAudio: false, hasVideo: false, source: name, variants: [],
-    });
-  }
-
-  // video: HLS playlist (honest label) + poster
-  const vid = embType.startsWith("app.bsky.embed.video") ? embed
-    : mediaEmb.startsWith("app.bsky.embed.video") ? embed.media
-    : null;
-  const playlist = vid?.playlist || null;
-  if (playlist) {
-    media.push({
-      type: "video", index: media.length, url: playlist, thumbnail: vid?.thumbnail || null,
-      mimeType: "application/x-mpegURL", width: null, height: null, duration: null, size: null,
-      quality: "hls", hasAudio: true, hasVideo: true, source: name, variants: [],
-    });
-  }
-
-  if (!media.length) {
-    attempt.status = "failed";
-    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Bluesky post contains no media (text or link-only)", { attempts: [attempt] });
-  }
-
-  attempt.status = "success";
-  attempt.latencyMs = Date.now() - t0;
-  return {
-    result: {
-      sourceUrl: url,
-      platform: name,
-      title: (record.text || "").slice(0, 200) || null,
-      author: post.author?.handle || null,
-      thumbnail: media[0].thumbnail,
-      itemCount: media.length,
-      counts: {
-        images: media.filter((m) => m.type === "image").length,
-        videos: media.filter((m) => m.type === "video").length,
-        audios: 0, other: 0,
-      },
-      truncated: false,
-      media,
-    },
-    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
-  };
-}
-
-export async function search() {
-  return [];
-}

package/lib/providers/dailymotion.js

@@ -1,100 +0,0 @@
-import { fetchJson, hostMatches } from "../util.js";
-import { Codes, UMediaError } from "../errors.js";
-
-/**
- * Dailymotion — public player metadata API (no key): title, thumbnails,
- * HLS master + any progressive renditions the platform serves.
- */
-export const name = "dailymotion";
-
-export function canHandle(url) {
-  try {
-    return hostMatches(new URL(String(url)).hostname, ["dailymotion.com", "dai.ly"]);
-  } catch { return false; }
-}
-
-export function videoId(url) {
-  const m = String(url).match(/(?:video\/|dai\.ly\/)([a-z0-9]+)/i);
-  return m ? m[1] : null;
-}
-
-export async function resolve(url, ctx = {}) {
-  const attempt = { provider: name, status: "skipped" };
-  ctx.attempts?.push(attempt);
-  const t0 = Date.now();
-
-  const id = videoId(url);
-  if (!id) {
-    attempt.status = "failed";
-    throw new UMediaError(Codes.INVALID_URL, "Not a Dailymotion video URL", { attempts: [attempt] });
-  }
-
-  let meta;
-  try {
-    meta = await fetchJson(`https://www.dailymotion.com/player/metadata/video/${id}`, {}, 15_000);
-  } catch (e) {
-    attempt.status = "failed";
-    attempt.error = e.message;
-    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Dailymotion metadata unavailable. ${e.message}`, { attempts: [attempt] });
-  }
-  if (meta?.error) {
-    attempt.status = "failed";
-    attempt.error = meta.error.title || "video unavailable";
-    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Dailymotion: ${attempt.error}`, { attempts: [attempt] });
-  }
-
-  const q = meta.qualities || {};
-  const media = [];
-  const variants = [];
-  for (const [label, arr] of Object.entries(q)) {
-    for (const r of (Array.isArray(arr) ? arr : [arr])) {
-      if (!r?.url) continue;
-      variants.push({
-        height: r.height ?? null, width: r.width ?? null, url: r.url,
-        hasAudio: true, hasVideo: true,
-        quality: label === "auto" ? "hls" : label,
-        mimeType: r.type || (/\.m3u8/.test(r.url) ? "application/x-mpegURL" : "video/mp4"),
-      });
-    }
-  }
-  const progressive = variants.find((v) => /mp4/.test(v.mimeType || "")) || variants.find((v) => !/m3u8|mpegurl/i.test(v.url + (v.mimeType || "")));
-  const chosen = progressive || variants[0];
-  if (!chosen) {
-    attempt.status = "failed";
-    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Dailymotion serves no stream URLs for this video", { attempts: [attempt] });
-  }
-
-  media.push({
-    type: "video", index: 0, url: chosen.url,
-    thumbnail: meta.thumbnails?.["720"] || meta.thumbnails?.["480"] || Object.values(meta.thumbnails || {})[0] || null,
-    mimeType: chosen.mimeType,
-    width: null, height: null,
-    duration: meta.duration ? Math.round(meta.duration) : null,
-    size: null, quality: chosen.quality,
-    hasAudio: true, hasVideo: true, source: name,
-    variants,
-  });
-
-  attempt.status = "success";
-  attempt.latencyMs = Date.now() - t0;
-  return {
-    result: {
-      sourceUrl: url,
-      platform: name,
-      title: meta.title || null,
-      author: meta.owner?.screenname || meta.owner?.username || null,
-      thumbnail: media[0].thumbnail,
-      itemCount: 1,
-      counts: { images: 0, videos: 1, audios: 0, other: 0 },
-      truncated: false,
-      media,
-      // honest: HLS-only means a manifest, not a single muxed file — yt-dlp tier muxes to mp4
-      streamUrlsAvailable: true,
-    },
-    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
-  };
-}
-
-export async function search() {
-  return [];
-}

package/lib/providers/facebook.js

@@ -1,126 +0,0 @@
-import { fetchText, hostMatches } from "../util.js";
-import { Codes, UMediaError } from "../errors.js";
-
-/**
- * Facebook — the platform's own player JSON embedded in the page (the exact
- * fields Facebook's web player reads: browser_native_hd/sd_url,
- * playable_url_quality_hd/playable_url). Reels, watch, videos, shares, fb.watch.
- * Reference: yt-dlp facebook extractor + cobalt facebook service.
- */
-export const name = "facebook";
-
-const HEADERS = {
-  accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
-  "accept-language": "en-US,en;q=0.5",
-  "sec-fetch-mode": "navigate",
-  "sec-fetch-site": "none",
-};
-
-export function canHandle(url) {
-  try {
-    return hostMatches(new URL(String(url)).hostname, ["facebook.com", "fb.watch", "fb.com"]);
-  } catch { return false; }
-}
-
-export function videoId(url) {
-  const u = String(url);
-  return (u.match(/\/(?:reel|videos|watch)\/(?:\?v=)?(\d+)/) || u.match(/[?&]v=(\d+)/) || u.match(/\/share\/[^/]+\/([\w-]+)/) || [])[1] || null;
-}
-
-function pickJsonStr(html, key) {
-  const m = html.match(new RegExp(`"${key}":("(?:[^"\\\\]|\\\\.)*")`));
-  if (!m) return null;
-  try { return JSON.parse(m[1]); } catch { return null; }
-}
-
-async function resolveShort(url, ctx) {
-  // fb.watch / facebook.com/share short links -> canonical page (Location or Link header)
-  const res = await fetch(url, { headers: HEADERS, redirect: "follow" }).catch(() => null);
-  if (!res) return url;
-  return res.url || url;
-}
-
-export async function resolve(url, ctx = {}) {
-  const attempt = { provider: name, status: "skipped" };
-  ctx.attempts?.push(attempt);
-  const t0 = Date.now();
-
-  let target = String(url);
-  if (/fb\.watch\//i.test(target) || /facebook\.com\/share\//i.test(target)) {
-    try { target = await resolveShort(target, ctx); } catch { /* use original */ }
-  }
-  // normalize watch/video.php/reel forms onto a fetchable page
-  const id = videoId(target) || videoId(url);
-  if (/\/watch\/?\?/i.test(target) && id) target = `https://www.facebook.com/watch/?v=${id}`;
-  if (/video\.php/i.test(target) && id) target = `https://www.facebook.com/video.php?v=${id}`;
-  if (/\/reel\//i.test(target) && id) target = `https://www.facebook.com/reel/${id}`;
-
-  let html;
-  try {
-    const r = await fetchText(target, { headers: HEADERS }, 20_000);
-    html = r.text;
-  } catch (e) {
-    attempt.status = "failed";
-    attempt.error = e.message;
-    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Facebook page not retrievable. ${e.message}`, { attempts: [attempt] });
-  }
-
-  const hd = pickJsonStr(html, "browser_native_hd_url") || pickJsonStr(html, "playable_url_quality_hd");
-  const sd = pickJsonStr(html, "browser_native_sd_url") || pickJsonStr(html, "playable_url");
-
-  const media = [];
-  const variants = [];
-  for (const [u, q] of [[hd, "hd"], [sd, "sd"]]) {
-    if (u && /^https?:/.test(u)) variants.push({ url: u, quality: q, height: null, width: null, hasAudio: true, hasVideo: true, mimeType: "video/mp4" });
-  }
-  if (variants.length) {
-    media.push({
-      type: "video", index: 0, url: variants[0].url,
-      thumbnail: pickJsonStr(html, "playable_url_thumbnail") || null,
-      mimeType: "video/mp4", width: null, height: null, duration: null, size: null,
-      quality: variants[0].quality, hasAudio: true, hasVideo: true, source: name, variants,
-    });
-  } else {
-    // og fallback (public photos / gated networks)
-    const og = (html.match(/property="og:(?:video|image)"[^>]+content="([^"]+)"/) || html.match(/content="([^"]+)"[^>]+property="og:(?:video|image)"/) || [])[1];
-    const isVideo = /property="og:video"/.test(html);
-    if (og && /^https?:/.test(og.replace(/&/g, "&"))) {
-      media.push({
-        type: isVideo ? "video" : "image", index: 0, url: og.replace(/&/g, "&"), thumbnail: og,
-        mimeType: isVideo ? "video/mp4" : "image/jpeg", width: null, height: null,
-        duration: null, size: null, quality: null,
-        hasAudio: isVideo, hasVideo: isVideo, source: name, variants: [],
-      });
-    }
-  }
-
-  if (!media.length) {
-    attempt.status = "failed";
-    attempt.error = "no player JSON or og media in the page (login-gated, private, or removed)";
-    throw new UMediaError(Codes.MEDIA_NOT_FOUND,
-      `Facebook exposes no media for this URL (${attempt.error}) — public videos work from most networks; the yt-dlp tier covers gated ones.`, { attempts: [attempt] });
-  }
-
-  const title = (html.match(/"title":"((?:[^"\\]|\\.)*)"/) || html.match(/<title[^>]*>([^<]*)/i) || [])[1] || null;
-  attempt.status = "success";
-  attempt.latencyMs = Date.now() - t0;
-  return {
-    result: {
-      sourceUrl: url,
-      platform: name,
-      title: title ? title.replace(/\\u0025/g, "%").slice(0, 200) : null,
-      author: null,
-      thumbnail: media[0].thumbnail,
-      itemCount: media.length,
-      counts: { images: media.filter((m) => m.type === "image").length, videos: media.filter((m) => m.type === "video").length, audios: 0, other: 0 },
-      truncated: false,
-      media,
-      streamUrlsAvailable: true,
-    },
-    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
-  };
-}
-
-export async function search() {
-  return [];
-}