umedia 0.2.1 → 0.3.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 · 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,17 @@ 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 |
+| **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** | — | ✅ 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) |
+| **Facebook · Threads · Snapchat · Rumble · Tumblr** | — | ✅ best-effort | ✅ best-effort | official Open Graph media on their share pages; often login-gated on datacenter IPs |
 | **iTunes** | ✅ | — | ✅ previews | real 30s clips, rock solid |
 | **1800+ sites** | — | ✅ | ✅ | optional tier: `pip install yt-dlp` — labeled `source: "ytdlp"` |
 

package/lib/download.js

@@ -5,7 +5,7 @@ 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 } from "./util.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";
@@ -27,6 +27,66 @@ 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;
+
+  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")) {
+    throw new UMediaError(Codes.QUALITY_UNAVAILABLE,
+      "fMP4 HLS stream — single-file muxing needs the yt-dlp tier: downloadWithYtdlp()");
+  }
+  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);
+  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 };
+}
+
 /**
  * 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.
@@ -38,6 +98,9 @@ export async function download({ url, quality = "best", type = "video", dir = ".
   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();
@@ -79,14 +142,24 @@ export async function download({ url, quality = "best", type = "video", dir = ".
         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 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 isHls = /\.m3u8$/i.test(chosenUrl.split(/[?#]/)[0]);
+      const 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);
+      const name = `${String(item.index + 1).padStart(3, "0")} - ${base.toLowerCase().endsWith(`.${ext}`) ? base.slice(0, -(ext.length + 1)) : base}.${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 });
+      let size, hlsHeight = null;
+      if (isHls) {
+        ({ size, height: hlsHeight } = await downloadHls(chosenUrl, dest, onProgress));
+        if (hlsHeight) selectedQuality = `${hlsHeight}p`; // the REAL rendition downloaded
+      } 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 });
     }
@@ -132,6 +205,7 @@ export async function download({ url, quality = "best", type = "video", dir = ".
 /** 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");

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/ogembed.js

@@ -0,0 +1,111 @@
+import { fetchText, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * og-embed tier — Facebook, Threads, Snapchat Spotlight, Rumble, Tumblr.
+ * These platforms publish official media previews as Open Graph meta tags on
+ * their public share pages; some networks gate them (typed honest errors there,
+ * the yt-dlp tier is the reliable path). No scraping tricks — their own tags.
+ */
+export const name = "ogembed";
+
+const HOSTS = ["facebook.com", "fb.watch", "threads.net", "threads.com", "snapchat.com", "rumble.com", "tumblr.com"];
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, HOSTS);
+  } catch { return false; }
+}
+
+function meta(h, key) {
+  const pats = [
+    new RegExp(`<meta[^>]+(?:property|name)="${key}"[^>]+content="([^"]*)"`, "i"),
+    new RegExp(`<meta[^>]+content="([^"]*)"[^>]+(?:property|name)="${key}"`, "i"),
+  ];
+  for (const p of pats) {
+    const m = h.match(p);
+    if (m) return m[1].replace(/&amp;/g, "&").replace(/&#(\d+);/g, (_, n) => String.fromCharCode(n));
+  }
+  return null;
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+  const host = (() => { try { return new URL(String(url)).hostname.replace(/^www\./, ""); } catch { return "?"; } })();
+
+  let html;
+  try {
+    const r = await fetchText(String(url), {}, 18_000);
+    if (r.status >= 400) {
+      attempt.status = "failed";
+      attempt.error = `HTTP ${r.status}`;
+      throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `${host} returned HTTP ${r.status}`, { attempts: [attempt] });
+    }
+    html = r.text;
+  } catch (e) {
+    if (e instanceof UMediaError) throw e;
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `${host} not retrievable. ${e.message}`, { attempts: [attempt] });
+  }
+
+  const video = meta(html, "og:video:secure_url") || meta(html, "og:video") || meta(html, "og:video:url");
+  const image = meta(html, "og:image:secure_url") || meta(html, "og:image");
+  const title = meta(html, "og:title");
+  const desc = meta(html, "og:description");
+  const author = meta(html, "og:article:author") || meta(html, "twitter:creator") || null;
+
+  const media = [];
+  if (video && /\.mp4|\.m3u8|video/i.test(video)) {
+    media.push({
+      type: "video", index: 0, url: video, thumbnail: image,
+      mimeType: /\.m3u8/i.test(video) ? "application/x-mpegURL" : "video/mp4",
+      width: parseInt(meta(html, "og:video:width") || "", 10) || null,
+      height: parseInt(meta(html, "og:video:height") || "", 10) || null,
+      duration: parseInt(meta(html, "video:duration") || meta(html, "og:video:duration") || "", 10) || null,
+      size: null, quality: null,
+      hasAudio: true, hasVideo: true, source: name, variants: [],
+    });
+  }
+  if (image && (!video || !/\.mp4/i.test(video))) {
+    media.push({
+      type: "image", index: media.length, url: image, thumbnail: image,
+      mimeType: "image/jpeg", width: null, height: null, duration: null, size: null,
+      quality: null, hasAudio: false, hasVideo: false, source: name, variants: [],
+    });
+  }
+
+  if (!media.length) {
+    attempt.status = "failed";
+    attempt.error = "no media in the public share page (login-gated or removed)";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND,
+      `${host} exposes no media on its public page (often login-gated from datacenter IPs) — the yt-dlp tier is the reliable path. ${attempt.error}`, { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: host,
+      title: title || desc || null,
+      author,
+      thumbnail: image || 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/pinterest.js

@@ -0,0 +1,181 @@
+import { fetchJson, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Pinterest — public widget API (widgets.pinterest.com pidgets), the same
+ * route Pinterest's own embed widgets call. Images (all sizes), video pins
+ * (direct V_720P mp4 + HLS variants), story/idea pins. pin.it links resolve.
+ */
+export const name = "pinterest";
+
+const PIN_RE = /\/pin\/(\d{6,22})/i;
+
+export function canHandle(url) {
+  try {
+    const u = new URL(String(url));
+    return hostMatches(u.hostname, ["pinterest.com", "pin.it"]) || /^pinterest\.[a-z.]+$/.test(u.hostname.replace(/^www\./, ""));
+  } catch { return false; }
+}
+
+export function pinId(url) {
+  const m = String(url).match(PIN_RE);
+  return m ? m[1] : null;
+}
+
+async function followPinIt(url, ctx) {
+  // pin.it short links 30x to the canonical /pin/{id}/ URL
+  const ctl = AbortSignal.timeout?.(15_000);
+  const res = await fetch(url, { headers: { "user-agent": "Mozilla/5.0" }, redirect: "follow", signal: ctl });
+  const final = res.url || "";
+  const id = pinId(final);
+  if (id) return id;
+  const body = await res.text().catch(() => "");
+  return pinId(body) || pinId(final);
+}
+
+function mediaFromPin(p, media, ctx) {
+  const imgs = p.images || {};
+  // image(s): prefer orig, else the largest available size — all sizes kept as variants
+  const sizeKeys = Object.keys(imgs).sort((a, b) => {
+    const n = (k) => parseInt((imgs[k]?.width || k.match(/\d+/)?.[0] || 0), 10);
+    return n(b) - n(a);
+  });
+  const variants = sizeKeys
+    .filter((k) => imgs[k]?.url)
+    .map((k) => ({ height: imgs[k]?.height ?? null, width: imgs[k]?.width ?? null, url: imgs[k].url, hasAudio: false, hasVideo: false, quality: k }));
+
+  const vl = p.videos?.video_list || {};
+  const vKeys = Object.keys(vl);
+  if (vKeys.length) {
+    // video pin: direct mp4 first (V_720P / V_EXP7 / EXP), HLS as variants
+    const direct = vl.V_720P || vl.V_EXP7 || vl.V_EXP4 || null;
+    const vVariants = vKeys.map((k) => ({
+      height: vl[k]?.height ?? null, width: vl[k]?.width ?? null, url: vl[k].url,
+      hasAudio: true, hasVideo: true, quality: k,
+      mimeType: /\.m3u8/.test(vl[k]?.url || "") ? "application/x-mpegURL" : "video/mp4",
+    })).sort((a, b) => {
+      // direct mp4 first at equal height — never prefer an HLS manifest over a real file
+      const aMp4 = a.mimeType === "video/mp4" ? 1 : 0;
+      const bMp4 = b.mimeType === "video/mp4" ? 1 : 0;
+      return (b.height || 0) - (a.height || 0) || bMp4 - aMp4;
+    });
+    const chosen = direct || vVariants.find((v) => v.mimeType === "video/mp4") || vVariants[0];
+    media.push({
+      type: "video", index: media.length, url: chosen.url,
+      thumbnail: chosen.thumbnail || vl[vKeys[0]]?.thumbnail || variants[0]?.url || null,
+      mimeType: /\.m3u8/.test(chosen.url) ? "application/x-mpegURL" : "video/mp4",
+      width: chosen.width ?? null, height: chosen.height ?? null,
+      duration: vl[vKeys[0]]?.duration ? Math.round(vl[vKeys[0]].duration / 1000) : null,
+      size: null, quality: chosen.height ? `${chosen.height}p` : null,
+      hasAudio: true, hasVideo: true, source: name,
+      variants: vVariants.filter((v) => v.url),
+    });
+  }
+  if (!p.videos?.video_list && variants.length) {
+    media.push({
+      type: "image", index: media.length, url: variants[0].url,
+      thumbnail: variants[0].url, mimeType: "image/jpeg",
+      width: variants[0].width ?? null, height: variants[0].height ?? null,
+      duration: null, size: null, quality: variants[0].quality,
+      hasAudio: false, hasVideo: false, source: name, variants,
+    });
+  }
+
+  // story / idea pins: one media per page, in order — never silently truncate
+  const pages = p.story_pin_data?.pages || [];
+  pages.forEach((pg) => {
+    const blocks = pg.blocks || [];
+    for (const b of blocks) {
+      const vid = b.video?.video_list ? Object.values(b.video.video_list)[0] : null;
+      const img = b.image && (b.image.images?.orig?.url || b.image.images?.["564x"]?.url);
+      if (vid?.url) {
+        media.push({
+          type: "video", index: media.length, url: vid.url, thumbnail: vid.thumbnail ?? null,
+          mimeType: /\.m3u8/.test(vid.url) ? "application/x-mpegURL" : "video/mp4",
+          width: vid.width ?? null, height: vid.height ?? null,
+          duration: vid.duration ? Math.round(vid.duration / 1000) : null, size: null,
+          quality: vid.height ? `${vid.height}p` : null,
+          hasAudio: true, hasVideo: true, source: name, variants: [],
+        });
+      } else if (img) {
+        media.push({
+          type: "image", index: media.length, url: img, thumbnail: img, mimeType: "image/jpeg",
+          width: null, height: null, duration: null, size: null, quality: null,
+          hasAudio: false, hasVideo: false, source: name, variants: [],
+        });
+      }
+    }
+  });
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+
+  let id = pinId(url);
+  if (!id && /pin\.it\//i.test(String(url))) {
+    try { id = await followPinIt(url, ctx); } catch (e) { attempt.error = e.message; }
+  }
+  if (!id) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.INVALID_URL,
+      "Not a pin URL — expected pinterest.* /pin/{id} or a pin.it share link", { attempts: [attempt] });
+  }
+
+  // primary: public widget API (the route Pinterest's own embeds use)
+  let pin = null;
+  try {
+    const j = await fetchJson(
+      `https://widgets.pinterest.com/v3/pidgets/pins/info/?pin_ids=${id}`, {}, 15_000);
+    const row = (j?.data || [])[0];
+    if (row && !row.error) pin = row;
+    else attempt.error = row?.error || "pin not found (deleted or secret board)";
+  } catch (e) { attempt.error = e.message; }
+
+  // fallback: Pinterest's own PinResource endpoint
+  if (!pin) {
+    try {
+      const data = encodeURIComponent(JSON.stringify({ options: { id, field_set_key: "auth_web_main_pin", is_buyable_pin: false }, context: {} }));
+      const j = await fetchJson(
+        `https://www.pinterest.com/resource/PinResource/get/?source_url=/pin/${id}/&data=${data}`,
+        { headers: { "x-pinterest-app-state": "active", accept: "application/json" } }, 15_000);
+      if (j?.resource_response?.data) pin = j.resource_response.data;
+      else attempt.error = j?.resource_response?.error?.message || attempt.error;
+    } catch (e) { attempt.error = e.message; }
+  }
+
+  const media = [];
+  if (pin) mediaFromPin(pin, media, ctx);
+
+  if (!media.length) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND,
+      `Pinterest pin has no retrievable media. ${attempt.error || ""}`.trim(), { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: pin?.grid_title || pin?.description || pin?.title || null,
+      author: pin?.pinner?.username || pin?.native_creator?.username || null,
+      thumbnail: pin?.images?.orig?.url || pin?.images?.["564x"]?.url || 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/soundcloud.js

@@ -0,0 +1,138 @@
+import { fetchJson, fetchText, hostMatches, UA } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * SoundCloud — public api-v2 (the route the web player itself calls):
+ * resolve -> transcodings -> CDN hop -> direct progressive MP3 (or HLS).
+ * This is the music pipeline: search elsewhere, download REAL full tracks here.
+ */
+export const name = "soundcloud";
+
+let _client_id = null;   // cached; rotated by SoundCloud occasionally
+let _cidFetchedAt = 0;
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["soundcloud.com", "snd.sc"]);
+  } catch { return false; }
+}
+
+export function trackId(url) {
+  const m = String(url).match(/soundcloud\.com\/([\w-]+)\/([\w-]+)/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+async function clientId() {
+  if (_client_id && Date.now() - _cidFetchedAt < 6 * 3600_000) return _client_id;
+  // SoundCloud ships its public client_id inside its JS bundles — read it like the web player does
+  const page = await fetchText("https://soundcloud.com/discover", {}, 15_000);
+  const bundles = [...new Set((page.text.match(/https:\/\/a-v2\.sndcdn\.com\/assets\/[^"']+\.js/g) || []))].slice(0, 14);
+  for (const b of bundles) {
+    try {
+      const js = await fetchText(b, {}, 15_000);
+      const m = js.text.match(/client_id[":= ]{1,4}([A-Za-z0-9]{24,40})/);
+      if (m) {
+        _client_id = m[1];
+        _cidFetchedAt = Date.now();
+        return _client_id;
+      }
+    } catch { /* try the next bundle */ }
+  }
+  throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, "SoundCloud client_id not retrievable (site changed) — use the yt-dlp tier");
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+
+  const slug = trackId(url);
+  if (!slug) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.INVALID_URL, "Not a SoundCloud track URL (expected soundcloud.com/{user}/{track})", { attempts: [attempt] });
+  }
+
+  const cid = await clientId();
+  let track;
+  try {
+    track = await fetchJson(
+      `https://api-v2.soundcloud.com/resolve?url=${encodeURIComponent(String(url).split("?")[0])}&client_id=${cid}`, {}, 20_000);
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `SoundCloud track not retrievable. ${e.message}`, { attempts: [attempt] });
+  }
+  if (!track || track.kind !== "track") {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "SoundCloud: not a public track (removed, private, or a set)", { attempts: [attempt] });
+  }
+
+  const media = [];
+  const variants = [];
+  for (const tr of (track.media?.transcodings || [])) {
+    const fmt = tr.format || {};
+    const isProg = fmt.protocol === "progressive";
+    const isMp3 = /mpeg|mp3/i.test(fmt.mime_type || "");
+    variants.push({
+      url: `${tr.url}${tr.url.includes("?") ? "&" : "?"}client_id=${cid}`,
+      height: null, width: null,
+      hasAudio: true, hasVideo: false,
+      quality: tr.quality || (isProg ? "progressive" : fmt.protocol),
+      mimeType: fmt.mime_type || null,
+      protocol: fmt.protocol,
+      _mp3: isProg && isMp3,
+    });
+  }
+  // resolve each transcoding hop -> real CDN URL (progressive mp3 first, then HLS)
+  const order = [...variants].sort((a, b) => (b._mp3 ? 1 : 0) - (a._mp3 ? 1 : 0));
+  const resolvedVariants = [];
+  for (const v of order) {
+    try {
+      const hop = await fetchJson(v.url, {}, 15_000);
+      if (hop?.url) resolvedVariants.push({ ...v, url: hop.url });
+    } catch { /* rights-restricted encoding — skip honestly */ }
+  }
+
+  if (!resolvedVariants.length) {
+    attempt.status = "failed";
+    attempt.error = "no downloadable encodings (rights-restricted)";
+    throw new UMediaError(Codes.ACCESS_RESTRICTED,
+      "SoundCloud exposes no downloadable encoding for this track (rights-restricted) — stream it in-app or use the yt-dlp tier", { attempts: [attempt] });
+  }
+
+  const chosen = resolvedVariants.find((v) => v._mp3) || resolvedVariants[0];
+  media.push({
+    type: "audio", index: 0, url: chosen.url,
+    thumbnail: track.artwork_url || track.user?.avatar_url || null,
+    mimeType: chosen.mimeType || (/mpegurl/.test(chosen.mimeType || "") ? "application/x-mpegURL" : "audio/mpeg"),
+    width: null, height: null,
+    duration: track.duration ? Math.round(track.duration / 1000) : null,
+    size: null, quality: chosen.quality,
+    hasAudio: true, hasVideo: false, source: name,
+    variants: resolvedVariants.map((v) => ({
+      height: null, width: null, url: v.url,
+      hasAudio: true, hasVideo: false, quality: v.quality, mimeType: v.mimeType,
+    })),
+  });
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: track.title || null,
+      author: track.user?.username || null,
+      thumbnail: track.artwork_url || null,
+      itemCount: 1,
+      counts: { images: 0, videos: 0, audios: 1, other: 0 },
+      truncated: false,
+      media,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/streamable.js

@@ -0,0 +1,93 @@
+import { fetchJson, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Streamable — the public video JSON (api.streamable.com/videos/{id}):
+ * direct mp4 renditions (mp4 / mp4-mobile / original) with real heights.
+ */
+export const name = "streamable";
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["streamable.com"]);
+  } catch { return false; }
+}
+
+export function videoId(url) {
+  const m = String(url).match(/streamable\.com\/(?:e\/|video\/)?([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 Streamable URL", { attempts: [attempt] });
+  }
+
+  let v;
+  try {
+    v = await fetchJson(`https://api.streamable.com/videos/${id}`, {}, 15_000);
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Streamable video not retrievable. ${e.message}`, { attempts: [attempt] });
+  }
+  if (v?.error || (v?.status && v.status !== 2 && !v.files)) {
+    attempt.status = "failed";
+    attempt.error = v?.error || v?.message || "video not found or still processing";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Streamable: ${attempt.error}`, { attempts: [attempt] });
+  }
+
+  const variants = [];
+  for (const [key, f] of Object.entries(v.files || {})) {
+    // their API occasionally returns a doubled scheme — normalize, never silently drop
+    const raw = typeof f?.url === "string" ? f.url.replace(/^https:https:\/\//, "https://") : null;
+    if (!raw) continue;
+    variants.push({
+      height: f.height ?? null, width: f.width ?? null, url: raw,
+      hasAudio: true, hasVideo: true,
+      quality: key === "mp4-mobile" ? "360p" : (f.height ? `${f.height}p` : key),
+      mimeType: "video/mp4",
+    });
+  }
+  const chosen = variants.sort((a, b) => (b.height || 0) - (a.height || 0))[0];
+  if (!chosen) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Streamable: no downloadable renditions (deleted or processing)", { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: v.title || null,
+      author: null,
+      thumbnail: (typeof v.thumbnail_url === "string" ? v.thumbnail_url.replace(/^https:https:\/\//, "https://") : v.thumbnail_url) || null,
+      itemCount: 1,
+      counts: { images: 0, videos: 1, audios: 0, other: 0 },
+      truncated: false,
+      media: [{
+        type: "video", index: 0, url: chosen.url,
+        thumbnail: (typeof v.thumbnail_url === "string" ? v.thumbnail_url.replace(/^https:https:\/\//, "https://") : v.thumbnail_url) || null,
+        mimeType: "video/mp4",
+        width: chosen.width ?? null, height: chosen.height ?? null,
+        duration: v.video_duration ?? v.duration ?? null,
+        size: null, quality: chosen.quality,
+        hasAudio: true, hasVideo: true, source: name, variants,
+      }],
+      streamUrlsAvailable: true,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/twitch.js

@@ -0,0 +1,108 @@
+import { fetchJson, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Twitch clips — the public GraphQL endpoint the web player calls (its web
+ * client-id ships in Twitch's own JS; nothing secret). Direct CloudFront mp4
+ * renditions per quality. VODs/livestreams need the yt-dlp tier (honest).
+ */
+export const name = "twitch";
+
+// Twitch's own public web client id (shipped in their frontend bundle)
+const CLIENT_ID = "kimne78kx3ncx6brgo4mv6wki5h1ko";
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["twitch.tv", "clips.twitch.tv"]);
+  } catch { return false; }
+}
+
+export function clipSlug(url) {
+  const m = String(url).match(/(?:clips\.twitch\.tv\/|\/clip\/)([\w-]+)/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 slug = clipSlug(url);
+  if (!slug) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.INVALID_URL,
+      "Only Twitch CLIP urls resolve natively (clips.twitch.tv/{slug} or twitch.tv/{ch}/clip/{slug}). VODs/livestreams: use downloadWithYtdlp().", { attempts: [attempt] });
+  }
+
+  let gql;
+  try {
+    gql = await fetchJson("https://gql.twitch.tv/gql",
+      {
+        method: "POST",
+        headers: { "client-id": CLIENT_ID, "content-type": "text/plain" },
+        body: JSON.stringify({
+          query: `query{clip(slug:"${slug}"){title durationSeconds broadcaster{displayName} thumbnailURL videoQualities{frameRate quality sourceURL} playbackAccessToken(params:{platform:"web",playerType:"site"}){value signature}}}`,
+        }),
+      }, 15_000);
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Twitch GraphQL unavailable. ${e.message}`, { attempts: [attempt] });
+  }
+  const clip = gql?.data?.clip;
+  if (!clip) {
+    attempt.status = "failed";
+    attempt.error = "clip not found (expired clips are removed with their VOD)";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Twitch: ${attempt.error}`, { attempts: [attempt] });
+  }
+
+  // Twitch CDN (nauth) URLs only serve with the clip's playback token — sign them like the web player
+  const tok = clip.playbackAccessToken;
+  const sign = (u) => (tok?.value && tok?.signature
+    ? `${u}${u.includes("?") ? "&" : "?"}token=${encodeURIComponent(tok.value)}&sig=${tok.signature}`
+    : u);
+
+  const variants = (clip.videoQualities || [])
+    .filter((q) => q?.sourceURL)
+    .map((q) => ({
+      height: parseInt(q.quality, 10) || null, width: null, url: sign(q.sourceURL),
+      hasAudio: true, hasVideo: true,
+      quality: q.quality ? `${q.quality}p` : null, mimeType: "video/mp4",
+    }))
+    .sort((a, b) => (b.height || 0) - (a.height || 0));
+  const chosen = variants[0];
+  if (!chosen) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Twitch clip has no downloadable renditions", { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: clip.title || null,
+      author: clip.broadcaster?.displayName || null,
+      thumbnail: clip.thumbnailURL || null,
+      itemCount: 1,
+      counts: { images: 0, videos: 1, audios: 0, other: 0 },
+      truncated: false,
+      media: [{
+        type: "video", index: 0, url: chosen.url,
+        thumbnail: clip.thumbnailURL || null,
+        mimeType: "video/mp4",
+        width: null, height: chosen.height ?? null,
+        duration: clip.durationSeconds ?? null,
+        size: null, quality: chosen.quality,
+        hasAudio: true, hasVideo: true, source: name, variants,
+      }],
+      streamUrlsAvailable: true,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/vimeo.js

@@ -0,0 +1,108 @@
+import { fetchJson, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Vimeo — the public player config JSON (player.vimeo.com/video/{id}/config):
+ * progressive renditions when Vimeo serves them, otherwise HLS masters with
+ * real per-rendition quality labels.
+ */
+export const name = "vimeo";
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["vimeo.com", "player.vimeo.com"]);
+  } catch { return false; }
+}
+
+export function videoId(url) {
+  const m = String(url).match(/(?:video\/|vimeo\.com\/(?:video\/)?)(\d{6,12})/);
+  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 Vimeo video URL (password-protected/album URLs need the yt-dlp tier)", { attempts: [attempt] });
+  }
+
+  let cfg;
+  try {
+    cfg = await fetchJson(`https://player.vimeo.com/video/${id}/config`,
+      { headers: { referer: "https://vimeo.com/" } }, 15_000);
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Vimeo player config unavailable. ${e.message}`, { attempts: [attempt] });
+  }
+  const v = cfg?.video;
+  if (!v) {
+    attempt.status = "failed";
+    attempt.error = cfg?.title || "video unavailable";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Vimeo: ${attempt.error}`, { attempts: [attempt] });
+  }
+
+  const files = cfg.request?.files || {};
+  const variants = [];
+  for (const p of (files.progressive || [])) {
+    if (!p?.url) continue;
+    variants.push({
+      height: p.height ?? null, width: p.width ?? null, url: p.url,
+      hasAudio: true, hasVideo: true,
+      quality: p.quality || (p.height ? `${p.height}p` : null),
+      mimeType: p.mime || "video/mp4",
+    });
+  }
+  const hls = files.hls || {};
+  const cdns = hls.cdns || {};
+  const defaultUrl = cdns[hls.default_cdn]?.avc_url || Object.values(cdns)[0]?.avc_url || null;
+  if (defaultUrl) {
+    variants.push({
+      height: null, width: null, url: defaultUrl,
+      hasAudio: !hls.separate_av, hasVideo: true,
+      quality: "hls", mimeType: "application/x-mpegURL",
+    });
+  }
+
+  const progressive = variants.find((v) => /mp4/.test(v.mimeType || ""));
+  const chosen = progressive || variants[0];
+  if (!chosen) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Vimeo serves no stream URLs (private or domain-restricted video)", { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: v.title || null,
+      author: cfg.owner?.display_name || cfg.user?.name || null,
+      thumbnail: v.thumbs?.base || v.thumb || null,
+      itemCount: 1,
+      counts: { images: 0, videos: 1, audios: 0, other: 0 },
+      truncated: false,
+      media: [{
+        type: "video", index: 0, url: chosen.url,
+        thumbnail: v.thumbs?.base || v.thumb || null,
+        mimeType: chosen.mimeType,
+        width: v.width ?? null, height: v.height ?? null,
+        duration: v.duration ?? null,
+        size: null, quality: chosen.quality,
+        hasAudio: true, hasVideo: true, source: name,
+        variants,
+      }],
+      streamUrlsAvailable: true,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
+}
+
+export async function search() {
+  return [];
+}

package/lib/registry.js

@@ -1,13 +1,22 @@
 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 ogembed from "./providers/ogembed.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, reddit, xprov, ig];
+const NATIVE = [yt, tiktok, pinterest, soundcloud, dailymotion, vimeo, streamable, twitch, bluesky, reddit, xprov, ig, ogembed];
 
 export function detectPlatform(url) {
   for (const p of NATIVE) {
@@ -20,6 +29,9 @@ const DIRECT_MEDIA = /\.(mp4|webm|m4a|mp3|aac|wav|jpg|jpeg|png|gif|webp|mov|mkv)
 
 /** 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) {
@@ -95,10 +107,18 @@ 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: "photo galleries + video posts" },
+      { 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: "public embed best-effort" },
       { platform: "reddit", search: false, resolve: true, download: true, notes: "posts + galleries" },
       { platform: "x", search: false, resolve: true, download: true, notes: "public posts via syndication" },
+      { platform: "facebook · threads · snapchat · rumble · tumblr", search: false, resolve: "best-effort", download: "best-effort", notes: "official Open Graph media; often login-gated on datacenter IPs — yt-dlp tier reliable" },
       { 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" },
     ],
@@ -112,10 +132,18 @@ export function status() {
     runtime: { node: process.version, platform: process.platform },
     providers: [
       { name: "youtube", state: "operational", via: "youtubei.js" },
-      { name: "tiktok", state: "operational", via: "embed/v2" },
+      { 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: "degraded", via: "public embed (best-effort)" },
       { name: "reddit", state: "operational", via: "public json" },
       { name: "x", state: "degraded", via: "syndication (best-effort)" },
+      { name: "ogembed", state: "degraded", via: "open graph meta (best-effort)" },
       { name: "itunes", state: "operational", via: "search api" },
       { name: "ytdlp", state: ytdlp.binary() ? "operational" : "unavailable", via: "external binary" },
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umedia",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Standalone media engine — search, resolve and download media from YouTube, TikTok, Instagram, Reddit, X, iTunes (and 1800+ sites via the yt-dlp tier) entirely on your machine. No hosted API, no keys, no server bills. Honest quality labels, complete galleries, typed errors.",
   "type": "module",
   "main": "./index.js",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "umedia": "./bin/umedia.js"
+    "umedia": "bin/umedia.js"
   },
   "files": [
     "index.js",