umedia 0.2.0 → 0.2.2

package/README.md

@@ -75,10 +75,10 @@ trailers, social posts with official embeds. `previewKind: "none"` beats a fake
 | Platform | Search | Resolve | Download | How |
 |---|---|---|---|---|
 | **YouTube** | ✅ | ✅ | ✅ * | InnerTube — search & metadata always; stream URLs depend on your network (see below) |
-| **TikTok** | — | ✅ | ✅ | photo galleries + video posts |
-| **Instagram** | — | ✅ best-effort | ✅ | public embeds |
-| **Reddit** | — | ✅ | ✅ | posts + galleries |
-| **X** | — | ✅ best-effort | ✅ | public posts |
+| **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) |
 | **iTunes** | ✅ | — | ✅ previews | real 30s clips, rock solid |
 | **1800+ sites** | — | ✅ | ✅ | optional tier: `pip install yt-dlp` — labeled `source: "ytdlp"` |
 
@@ -88,6 +88,9 @@ On typical home connections `download()` just works; on hard networks you'll get
 `downloadWithYtdlp()` / `umedia download <url> --ytdlp` which handles PO tokens, cookies and muxing.
 We'd rather tell you the truth than fake a download.
 
+**Direct media URLs always work:** give `resolve()`/`download()` any direct `.mp4/.m4a/.jpg/…` link and it
+goes straight to disk — no platform needed.
+
 ```js
 // the power tier — one function, 1800+ sites, hard networks
 await media.downloadWithYtdlp({ url: "https://example.com/anything", quality: "720p", dir: "./out" });

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";
@@ -38,6 +38,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,6 +82,7 @@ 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]
@@ -132,6 +136,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/instagram.js

@@ -1,11 +1,13 @@
-import { fetchText } from "../util.js";
+import { fetchText, hostMatches } from "../util.js";
 import { Codes, UMediaError } from "../errors.js";
 
 /** Instagram — public embed page parse. Best-effort: IG gates aggressively; failures are typed. */
 export const name = "instagram";
 
 export function canHandle(url) {
-  return /(?:^|\.)(instagram\.com|instagr\.am)\//i.test(String(url)) && /\/(p|reel|tv)\//i.test(String(url));
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["instagram.com", "instagr.am"]) && /\/(p|reel|tv)\//i.test(String(url));
+  } catch { return false; }
 }
 
 export async function resolve(url, ctx = {}) {

package/lib/providers/reddit.js

@@ -1,11 +1,13 @@
-import { fetchJson, UA } from "../util.js";
+import { fetchJson, UA, hostMatches } from "../util.js";
 import { Codes, UMediaError } from "../errors.js";
 
 /** Reddit — public JSON endpoints. Datacenter IPs may get 403; the error is honest. */
 export const name = "reddit";
 
 export function canHandle(url) {
-  return /(?:^|\.)(reddit\.com|redd\.it)\//i.test(String(url));
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["reddit.com", "redd.it"]);
+  } catch { return false; }
 }
 
 export async function resolve(url, ctx = {}) {
@@ -13,8 +15,25 @@ export async function resolve(url, ctx = {}) {
   ctx.attempts?.push(attempt);
   const t0 = Date.now();
   const base = String(url).split("?")[0].replace(/\/$/, "");
+
+  // Reddit edge-gates datacenter IPs per-host — try the alternate public edges, honestly.
+  async function fetchRedditJson() {
+    const path = base.replace(/^https?:\/\/[^/]+/, "");
+    const hosts = [...new Set([
+      new URL(base).host,
+      "old.reddit.com", "api.reddit.com", "www.reddit.com",
+    ])];
+    let lastErr = null;
+    for (const host of hosts) {
+      try {
+        return await fetchJson(`https://${host}${path}.json?raw_json=1`, { headers: { "user-agent": UA + " umedia-sdk" } }, 15_000);
+      } catch (e) { lastErr = e; }
+    }
+    throw lastErr;
+  }
+
   try {
-    const json = await fetchJson(`${base}.json?raw_json=1`, { headers: { "user-agent": UA + " umedia-sdk" } }, 15_000);
+    const json = await fetchRedditJson();
     const post = json?.[0]?.data?.children?.[0]?.data;
     if (!post) throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Reddit post not found");
     const media = [];

package/lib/providers/tiktok.js

@@ -42,8 +42,24 @@ export async function resolve(url, ctx = {}) {
           payload = { data: JSON.parse(raw) };
           if (id) _cache.set(id, { at: Date.now(), data: payload.data });
         } else if (status === 200) {
-          const m = text.match(/<script id="[^"]*" type="application\/json">(.*?)<\/script>/s);
-          if (m) { payload = { data: JSON.parse(m[1]) }; if (id) _cache.set(id, { at: Date.now(), data: payload.data }); }
+          // Frontity state (current embed/v2 shape) first, then any JSON script that carries media data
+          const frontity = text.split('<script id="__FRONTITY_CONNECT_STATE__" type="application/json">')[1]?.split("</script>")[0];
+          if (frontity) {
+            payload = { data: JSON.parse(frontity) };
+            if (id) _cache.set(id, { at: Date.now(), data: payload.data });
+          } else {
+            for (const m of text.matchAll(/<script[^>]*type="application\/json"[^>]*>([\s\S]*?)<\/script>/g)) {
+              try {
+                const parsed = JSON.parse(m[1]);
+                const rawStr = JSON.stringify(parsed);
+                if (rawStr.includes("urlList") || rawStr.includes("playAddr") || rawStr.includes("imagePost")) {
+                  payload = { data: parsed };
+                  if (id) _cache.set(id, { at: Date.now(), data: payload.data });
+                  break;
+                }
+              } catch { /* not state JSON */ }
+            }
+          }
         }
         if (!payload) attempts.push(`embed fetch ${status}`);
       } catch (e) {
@@ -58,8 +74,20 @@ export async function resolve(url, ctx = {}) {
     || payload?.data?.itemInfo?.itemStruct
     || null;
 
-  if (scope?.imagePost?.images?.length) {
-    scope.imagePost.images.forEach((img, i) => {
+  // Frontity state — the CURRENT embed/v2 shape (Sept 2026+): source.data[<route>].videoData
+  let frontity = null;
+  const sourceData = payload?.data?.source?.data;
+  if (sourceData && typeof sourceData === "object") {
+    for (const node of Object.values(sourceData)) {
+      if (node && typeof node === "object" && node.videoData) { frontity = node.videoData; break; }
+    }
+  }
+
+  // images: canonical imagePost.images[] (complete) OR displayImages[] (public surface — possibly partial)
+  let galleryDegraded = false;
+  const imageList = scope?.imagePost?.images;
+  if (imageList?.length) {
+    imageList.forEach((img, i) => {
       const u = img.imageURL?.urlList?.[0] || img.imageURL?.url;
       if (u) media.push({
         type: "image", index: i, url: u, thumbnail: u, mimeType: "image/jpeg",
@@ -68,13 +96,35 @@ export async function resolve(url, ctx = {}) {
         hasAudio: false, hasVideo: false, source: name, variants: [],
       });
     });
-  } else if (scope?.video) {
-    const u = scope.video.playAddr || scope.video.downloadAddr || scope.video.bitrateInfo?.[0]?.PlayAddr?.UrlList?.[0];
-    if (u) media.push({
-      type: "video", index: 0, url: u, thumbnail: scope.video.cover || meta.thumbnail_url || null,
-      mimeType: "video/mp4", width: scope.video.width ?? null, height: scope.video.height ?? null,
-      duration: scope.video.duration ? scope.video.duration / 1000 : null, size: null,
-      quality: scope.video.height ? `${scope.video.height}p` : null,
+  } else if (frontity?.imagePostInfo?.displayImages?.length) {
+    galleryDegraded = true; // platform now serves a partial gallery publicly — honest truncated flag
+    frontity.imagePostInfo.displayImages.forEach((img, i) => {
+      const u = img?.urlList?.[0];
+      if (u) media.push({
+        type: "image", index: i, url: u, thumbnail: u, mimeType: "image/jpeg",
+        width: img.width ?? null, height: img.height ?? null, duration: null, size: null,
+        quality: img.width && img.height ? `${img.width}x${img.height}` : null,
+        hasAudio: false, hasVideo: false, source: name, variants: [],
+      });
+    });
+  }
+
+  // video: classic playAddr OR Frontity itemInfos.video.urls (direct CDN mp4)
+  const fv = frontity?.itemInfos?.video;
+  const videoUrl = scope?.video?.playAddr || scope?.video?.downloadAddr
+    || scope?.video?.bitrateInfo?.[0]?.PlayAddr?.UrlList?.[0]
+    || (fv?.urls?.length ? fv.urls[0] : null);
+  if (videoUrl) {
+    const meta = scope?.video || {};
+    const fmeta = fv?.videoMeta || {};
+    media.push({
+      type: "video", index: media.length, url: videoUrl,
+      thumbnail: meta.cover || frontity?.itemInfos?.covers?.[0] || null,
+      mimeType: "video/mp4",
+      width: meta.width ?? fmeta.width ?? null, height: meta.height ?? fmeta.height ?? null,
+      duration: meta.duration ? meta.duration / 1000 : (fmeta.duration ?? null),
+      size: null,
+      quality: (meta.height || fmeta.height) ? `${meta.height || fmeta.height}p` : null,
       hasAudio: true, hasVideo: true, source: name, variants: [],
     });
   }
@@ -92,8 +142,8 @@ export async function resolve(url, ctx = {}) {
     result: {
       sourceUrl: url,
       platform: "tiktok",
-      title: meta.title ?? scope?.desc ?? null,
-      author: meta.author_name ?? scope?.author?.nickname ?? null,
+      title: meta.title ?? scope?.desc ?? frontity?.itemInfos?.text ?? null,
+      author: meta.author_name ?? scope?.author?.nickname ?? frontity?.authorInfos?.nickName ?? frontity?.authorInfos?.uniqueId ?? null,
       thumbnail: meta.thumbnail_url ?? media[0].thumbnail,
       itemCount: media.length,
       counts: {
@@ -101,7 +151,9 @@ export async function resolve(url, ctx = {}) {
         videos: media.filter((m) => m.type === "video").length,
         audios: 0, other: 0,
       },
-      truncated: false,
+      // honest: true when the public surface exposed only a partial gallery —
+      // the full slides need the yt-dlp tier (TikTok degrades embeds since 2026-09)
+      truncated: galleryDegraded,
       media,
     },
     engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },

package/lib/providers/x.js

@@ -1,11 +1,13 @@
-import { fetchJson } from "../util.js";
+import { fetchJson, hostMatches } from "../util.js";
 import { Codes, UMediaError } from "../errors.js";
 
 /** X (Twitter) — syndication endpoint for public posts. Best-effort, honestly labeled. */
 export const name = "x";
 
 export function canHandle(url) {
-  return /(?:^|\.)(twitter\.com|x\.com)\//i.test(String(url));
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["twitter.com", "x.com"]);
+  } catch { return false; }
 }
 
 export async function resolve(url, ctx = {}) {

package/lib/providers/youtube.js

@@ -1,4 +1,4 @@
-import { parseDuration } from "../util.js";
+import { parseDuration, hostMatches } from "../util.js";
 import { Codes, UMediaError } from "../errors.js";
 
 /** YouTube via InnerTube (youtubei.js) — search + metadata always; stream URLs when the network allows. */
@@ -14,7 +14,9 @@ async function engine() {
 }
 
 export function canHandle(url) {
-  return /(?:^|\.)(youtube\.com|youtu\.be|youtube-nocookie\.com)\/|^(www\.)?youtu\.be\//i.test(String(url));
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["youtube.com", "youtu.be", "youtube-nocookie.com"]);
+  } catch { return false; }
 }
 
 export function videoId(url) {

package/lib/registry.js

@@ -6,16 +6,48 @@ import * as ig from "./providers/instagram.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];
 
 export function detectPlatform(url) {
-  for (const p of NATIVE) if (p.canHandle(url)) return p.name;
+  for (const p of NATIVE) {
+    try { if (p.canHandle(url)) return p.name; } catch { /* bad URL — keep scanning */ }
+  }
   return ytdlp.binary() ? "ytdlp" : "unknown";
 }
 
+const DIRECT_MEDIA = /\.(mp4|webm|m4a|mp3|aac|wav|jpg|jpeg|png|gif|webp|mov|mkv)(\?|#|$)/i;
+
 /** Resolve a URL: native adapter first, optional yt-dlp fallback. attempts[] is the honest trail. */
 export async function resolve(url) {
+  // SSRF hygiene FIRST — never dispatch or fetch private/internal targets (bots pass user URLs!)
+  validateUrl(url);
+
+  // direct media URL (an image/video/audio file) -> single-item result, no platform needed
+  const direct = String(url).split("#")[0].match(DIRECT_MEDIA);
+  if (direct) {
+    const ext = direct[1].toLowerCase();
+    const kind = ["mp4", "webm", "mov", "mkv"].includes(ext) ? "video"
+      : ["jpg", "jpeg", "png", "gif", "webp"].includes(ext) ? "image" : "audio";
+    return {
+      data: {
+        sourceUrl: url, platform: "direct",
+        title: String(url).split("/").pop() || "Direct media",
+        author: null, thumbnail: kind === "video" ? null : url,
+        itemCount: 1,
+        counts: { images: kind === "image" ? 1 : 0, videos: kind === "video" ? 1 : 0, audios: kind === "audio" ? 1 : 0, other: 0 },
+        truncated: false,
+        media: [{
+          type: kind, index: 0, url: String(url), thumbnail: null, mimeType: null,
+          width: null, height: null, duration: null, size: null, quality: "original",
+          hasAudio: kind !== "image", hasVideo: kind !== "audio", source: "direct", variants: [],
+        }],
+      },
+      engine: { attempts: [{ provider: "direct", status: "success" }], finalProvider: "direct", totalLatencyMs: 0 },
+    };
+  }
+
   const ctx = { attempts: [] };
   for (const p of NATIVE) {
     if (!p.canHandle(url)) continue;

package/lib/util.js

@@ -7,6 +7,12 @@ export function rid() {
   return "req_" + Math.random().toString(16).slice(2, 10) + Date.now().toString(16).slice(-8);
 }
 
+/** Hostname match: exact or dot-suffix (www-insensitive). */
+export function hostMatches(hostname, list) {
+  const h = String(hostname || "").toLowerCase().replace(/^www\./, "");
+  return list.some((d) => h === d || h.endsWith("." + d));
+}
+
 /** http(s) only, no private/loopback/link-local targets (SSRF hygiene). */
 export function validateUrl(raw) {
   let u;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umedia",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",