umedia 0.2.2 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@
 
 No hosted API. No API keys. No rate limits. **No server bill.**
 
-YouTube · TikTok · Instagram · Reddit · X · iTunes · 1800+ sites (via the optional yt-dlp tier)
+YouTube · TikTok · Pinterest · SoundCloud · Dailymotion · Vimeo · Streamable · Twitch · Bluesky · Instagram · Reddit · X · Facebook · Threads · Snapchat · Rumble · Tumblr · iTunes · 1800+ sites (via the optional yt-dlp tier)
 
 [![npm version](https://img.shields.io/npm/v/umedia?color=67e8f9&label=npm)](https://www.npmjs.com/package/umedia)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2018-brightgreen)](https://nodejs.org)
@@ -76,9 +76,21 @@ trailers, social posts with official embeds. `previewKind: "none"` beats a fake
 |---|---|---|---|---|
 | **YouTube** | ✅ | ✅ | ✅ * | InnerTube — search & metadata always; stream URLs depend on your network (see below) |
 | **TikTok** | — | ✅ | ✅ | video posts = direct CDN mp4; photo galleries = every slide the platform publicly exposes, `truncated: true` when it degrades galleries |
-| **Instagram** | — | ✅ best-effort | ✅ | public embeds (gated on some networks — the yt-dlp tier is the reliable path) |
-| **Reddit** | — | ✅ best-effort | ✅ | public JSON across reddit edges (datacenter IPs often 403 — typed honest error) |
-| **X** | — | ✅ best-effort | ✅ | public syndication (media login-gated on some networks — typed honest error) |
+| **Pinterest** | — | ✅ | ✅ | image pins, video pins (direct mp4 + HLS variants), idea/story pins, `pin.it` short links |
+| **SoundCloud** | — | ✅ | ✅ | full tracks as direct progressive MP3 (+ HLS) with real titles/artists |
+| **Dailymotion** | — | ✅ | ✅ | public player metadata — HLS/progressive renditions (HLS saved as `.ts`) |
+| **Vimeo** | — | ✅ | ✅ | player config — progressive mp4 when served, HLS otherwise |
+| **Streamable** | — | ✅ | ✅ | direct mp4 renditions |
+| **Twitch** | — | ✅ | ✅ | clips = direct CloudFront mp4s; VODs/livestreams via the yt-dlp tier |
+| **Bluesky** | — | ✅ | ✅ | public AppView API — full-size images + video playlists |
+| **Instagram** | — | ✅ | ✅ | oEmbed→mobile info API: photos, videos, full carousels |
+| **Reddit** | — | ✅ | ✅ | posts + galleries + video with its audio sidecar (DC IPs may 403 — typed honest error) |
+| **X** | — | ✅ | ✅ | syndication token + guest GraphQL: photos/videos/gifs at real bitrates |
+| **Facebook** | — | ✅ | ✅ | reels/watch/videos/shares/fb.watch via the web player JSON |
+| **Threads** | — | ✅ | ✅ | post SSR state + og media (Meta gates some networks — typed honest error) |
+| **Snapchat** | — | ✅ best-effort | ✅ best-effort | spotlight + story snap lists (edge-gated on datacenter IPs) |
+| **Rumble** | — | ✅ best-effort | ✅ best-effort | embed API direct mp4s (site blocks datacenter IPs) |
+| **Tumblr** | — | ✅ | ✅ | mobile API: video/audio/photo posts + reblog trails, all in order |
 | **iTunes** | ✅ | — | ✅ previews | real 30s clips, rock solid |
 | **1800+ sites** | — | ✅ | ✅ | optional tier: `pip install yt-dlp` — labeled `source: "ytdlp"` |
 

package/lib/download.js

@@ -1,5 +1,5 @@
 import { createWriteStream } from "node:fs";
-import { mkdir, stat } from "node:fs/promises";
+import { mkdir, stat, rename } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import path from "node:path";
@@ -27,6 +27,74 @@ async function fetchToFile(url, dest, onProgress) {
   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.
@@ -85,12 +153,28 @@ export async function download({ url, quality = "best", type = "video", dir = ".
       validateUrl(chosenUrl); // never fetch private/internal targets, even from a provider response
       if (!selectedQuality) { selectedQuality = pick.selectedQuality; fallback = pick.fallback; }
 
-      const ext = (chosenUrl.split("?")[0].match(/\.(mp4|webm|m4a|mp3|jpg|jpeg|png|gif|webp)$/) || [])[1]
-        || (item.type === "image" ? "jpg" : item.type === "audio" ? "m4a" : "mp4");
-      const name = `${String(item.index + 1).padStart(3, "0")} - ${cleanName(resolved.title)}.${ext}`;
-      const dest = path.join(dir, name);
-      const size = await fetchToFile(chosenUrl, dest, onProgress);
-      files.push({ name, path: dest, size, ext, mimeType: item.mimeType ?? null, index: item.index, quality: pick.selectedQuality ?? item.quality ?? null });
+      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 });
     }

package/lib/providers/bluesky.js

@@ -0,0 +1,118 @@
+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

@@ -0,0 +1,100 @@
+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

@@ -0,0 +1,126 @@
+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 [];
+}