umedia 0.1.2 → 0.2.1

package/lib/download.js

@@ -0,0 +1,159 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import path from "node:path";
+import { zipSync } from "fflate";
+import { UMediaError, Codes } from "./errors.js";
+import { UA, cleanName, rid } from "./util.js";
+import { pickFormat } from "./quality.js";
+import * as registry from "./registry.js";
+import * as ytdlp from "./providers/ytdlp.js";
+
+async function fetchToFile(url, dest, onProgress) {
+  const res = await fetch(url, { headers: { "user-agent": UA }, redirect: "follow" });
+  if (!res.ok) throw new UMediaError(Codes.PROVIDER_ERROR, `HTTP ${res.status} fetching media`);
+  const total = Number(res.headers.get("content-length") || 0);
+  await mkdir(path.dirname(dest), { recursive: true });
+  const ws = createWriteStream(dest);
+  let done = 0;
+  const readable = Readable.fromWeb(res.body);
+  readable.on("data", (chunk) => {
+    done += chunk.length;
+    onProgress?.(done, total);
+  });
+  await pipeline(readable, ws);
+  const s = await stat(dest);
+  return s.size;
+}
+
+/**
+ * Download every media item of a URL to disk — order preserved, failures named.
+ * Direct media URLs (clips, images) download as a single item — no page-resolve needed.
+ * @returns {Promise<{data: DownloadResult, meta}>}
+ */
+const MEDIA_EXT = /\.(mp4|webm|m4a|mp3|aac|wav|jpg|jpeg|png|gif|webp|mov|mkv)(\?|#|$)/i;
+
+export async function download({ url, quality = "best", type = "video", dir = "./umedia-downloads", onProgress, zip = false } = {}) {
+  const requestId = rid();
+  const t0 = Date.now();
+
+  let resolved, engine;
+  if (MEDIA_EXT.test(String(url).split("#")[0])) {
+    const ext = (String(url).match(MEDIA_EXT) || [])[1].toLowerCase();
+    const kind = /^(jpg|jpeg|png|gif|webp)$/.test(ext) ? "image" : /^(m4a|mp3|aac|wav)$/.test(ext) ? "audio" : "video";
+    resolved = {
+      sourceUrl: url, platform: "direct",
+      title: decodeURIComponent(String(url).split("/").pop().split("?")[0]) || "media",
+      itemCount: 1, counts: { images: kind === "image" ? 1 : 0, videos: kind === "video" ? 1 : 0, audios: kind === "audio" ? 1 : 0, other: 0 },
+      truncated: false,
+      media: [{
+        type: kind, index: 0, url, thumbnail: null, mimeType: null,
+        width: null, height: null, duration: null, size: null, quality: null,
+        hasAudio: kind !== "image", hasVideo: kind !== "audio", source: "direct", variants: [],
+      }],
+    };
+    engine = { attempts: [{ provider: "direct", status: "success" }], finalProvider: "direct", totalLatencyMs: 0 };
+  } else {
+    ({ data: resolved, engine } = await registry.resolve(url));
+  }
+
+  // quality selection happens on real heights of the resolved items
+  const files = [];
+  const failedItems = [];
+  let selectedQuality = null;
+  let fallback = false;
+
+  await mkdir(dir, { recursive: true });
+
+  for (const item of resolved.media) {
+    try {
+      const pick = pickFormat(
+        item.variants?.length ? item.variants.map((v) => ({
+          height: v.height, audioOnly: v.hasAudio && !v.hasVideo, url: v.url,
+        })) : [{ height: item.height, audioOnly: item.type === "audio", url: item.url }],
+        item.type === "audio" ? "audio" : quality,
+      );
+      const chosenUrl = pick.format?.url || item.url;
+      if (!chosenUrl) {
+        throw new UMediaError(Codes.PROVIDER_UNAVAILABLE,
+          "no direct media URL available on this network (bot-gated) — install yt-dlp for hard networks");
+      }
+      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 });
+    } catch (e) {
+      failedItems.push({ index: item.index, type: item.type, url: String(item.url || "").slice(0, 120), error: e.message });
+    }
+  }
+
+  if (!files.length) {
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE,
+      `Nothing could be downloaded (${failedItems[0]?.error || "unknown"}). Every failure: ${JSON.stringify(failedItems)}`,
+      { requestId, attempts: engine?.attempts ?? [] });
+  }
+
+  if (zip && files.length > 1) {
+    const chunks = {};
+    for (const f of files) {
+      const { readFile } = await import("node:fs/promises");
+      chunks[f.name] = new Uint8Array(await readFile(f.path));
+    }
+    const zipped = zipSync(chunks);
+    const { writeFile } = await import("node:fs/promises");
+    const zipName = `${cleanName(resolved.title)}.zip`;
+    const zipPath = path.join(dir, zipName);
+    await writeFile(zipPath, zipped);
+    files.push({ name: zipName, path: zipPath, size: zipped.length, ext: "zip", mimeType: "application/zip", index: files.length, quality: null });
+  }
+
+  return {
+    data: {
+      url, title: resolved.title ?? null, source: resolved.platform ?? null,
+      requestedQuality: quality,
+      selectedQuality,
+      fallback,
+      files,
+      itemCount: files.length,
+      requestedItems: resolved.media.length,
+      truncated: Boolean(resolved.truncated),
+      failedItems,
+    },
+    meta: { requestId, source: resolved.platform ?? null, timestamp: new Date().toISOString(), elapsedMs: Date.now() - t0 },
+    engine,
+  };
+}
+
+/** yt-dlp escape hatch for downloads on hard networks / 1800+ sites. */
+export async function downloadWithYtdlp({ url, quality = "best", dir = "./umedia-downloads", onProgress } = {}) {
+  const requestId = rid();
+  if (!ytdlp.binary()) throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, "yt-dlp not installed — `pip install yt-dlp`");
+  await mkdir(dir, { recursive: true });
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve, reject) => {
+    const fmt = quality === "audio" ? "bestaudio/best" : quality === "best" || quality === "original" ? "bestvideo*+bestaudio/best" : `bestvideo[height<=${parseInt(quality, 10) || 1080}]+bestaudio/best`;
+    const args = ["--no-playlist", "-f", fmt, "-o", path.join(dir, "%(title).80s [%(id)s].%(ext)s"), "--newline", url];
+    const p = spawn(ytdlp.binary(), args);
+    let lastLine = "";
+    p.stdout.on("data", (d) => {
+      const s = d.toString();
+      lastLine = s.split("\n").filter(Boolean).pop() || lastLine;
+      const m = lastLine.match(/(\d+\.\d+)%/);
+      if (m && onProgress) onProgress(Number(m[1]), 100);
+    });
+    let err = "";
+    p.stderr.on("data", (d) => { err += d.toString(); });
+    p.on("close", (code) => {
+      if (code !== 0) return reject(new UMediaError(Codes.PROVIDER_ERROR, `yt-dlp exited ${code}: ${err.split("\n").slice(-2)[0] || ""}`, { requestId }));
+      resolve({
+        data: { url, requestedQuality: quality, selectedQuality: quality, fallback: false, files: [], itemCount: 0, requestedItems: 0, truncated: false, failedItems: [], note: "saved by yt-dlp into " + dir },
+        meta: { requestId, source: "ytdlp", timestamp: new Date().toISOString(), elapsedMs: 0 },
+      });
+    });
+  });
+}

package/lib/errors.js

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

package/lib/providers/instagram.js

@@ -0,0 +1,69 @@
+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) {
+  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 = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+  const clean = String(url).split("?")[0].replace(/\/$/, "");
+  try {
+    const { status, text } = await fetchText(`${clean}/embed/captioned/`, {}, 15_000);
+    if (status !== 200) throw new UMediaError(Codes.PROVIDER_ERROR, `Instagram embed returned HTTP ${status}`);
+    const media = [];
+    // video first (reels), then display images
+    for (const m of text.matchAll(/"video_url":"(https:[^"]+?)"/g)) {
+      const u = m[1].replace(/\\u0026/g, "&").replace(/\\\//g, "/");
+      media.push({
+        type: "video", index: media.length, url: u, thumbnail: null, mimeType: "video/mp4",
+        width: null, height: null, duration: null, size: null, quality: null,
+        hasAudio: true, hasVideo: true, source: name, variants: [],
+      });
+      break; // first video per embed page
+    }
+    if (!media.length) {
+      for (const m of text.matchAll(/"display_url":"(https:[^"]+?)"/g)) {
+        const u = m[1].replace(/\\u0026/g, "&").replace(/\\\//g, "/");
+        if (!media.some((x) => x.url === u)) media.push({
+          type: "image", index: media.length, url: u, thumbnail: u, mimeType: "image/jpeg",
+          width: null, height: null, duration: null, size: null, quality: null,
+          hasAudio: false, hasVideo: false, source: name, variants: [],
+        });
+      }
+    }
+    if (!media.length) {
+      throw new UMediaError(Codes.MEDIA_NOT_FOUND, "No media exposed in the public embed (post may be private)");
+    }
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    return {
+      result: {
+        sourceUrl: url, platform: "instagram", title: 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,
+      },
+      engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+    };
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    if (e instanceof UMediaError) throw e;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Instagram unavailable: ${e.message}`, { attempts: [attempt] });
+  }
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/itunes.js

@@ -0,0 +1,47 @@
+import { fetchJson } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/** iTunes Search API — reliable everywhere. Music leads with REAL 30s previews. */
+export const name = "itunes";
+
+export async function search({ q, type = "music", limit = 12 }, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  if (type !== "music") {
+    attempt.error = "itunes serves music only (movie endpoint is dead upstream)";
+    return [];
+  }
+  const t0 = Date.now();
+  try {
+    const url = `https://itunes.apple.com/search?term=${encodeURIComponent(q)}&media=music&entity=song&limit=${Math.min(limit, 25)}`;
+    const json = await fetchJson(url, {}, 15_000);
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    return (json.results || []).map((r) => ({
+      title: r.trackName,
+      author: r.artistName,
+      pageUrl: r.trackViewUrl,
+      thumbnail: (r.artworkUrl100 || "").replace("100x100bb", "600x600bb") || null,
+      previewUrl: r.previewUrl || null,
+      previewKind: r.previewUrl ? "clip30s" : "none",
+      duration: r.trackTimeMillis ? r.trackTimeMillis / 1000 : null,
+      mediaType: "music",
+      source: name,
+      explicit: Boolean(r.trackExplicitness === "explicit"),
+    }));
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    if (e instanceof UMediaError && e.code === Codes.RATE_LIMITED) throw e;
+    return [];
+  }
+}
+
+/** iTunes media (preview clips) resolve straight from search metadata. */
+export async function resolve(url, ctx = {}) {
+  return { items: [], attempt: { provider: name, status: "skipped", error: "itunes media comes from search previews" } };
+}
+
+export function canHandle() {
+  return false;
+}

package/lib/providers/reddit.js

@@ -0,0 +1,97 @@
+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) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["reddit.com", "redd.it"]);
+  } catch { return false; }
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  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 fetchRedditJson();
+    const post = json?.[0]?.data?.children?.[0]?.data;
+    if (!post) throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Reddit post not found");
+    const media = [];
+    const add = (type, u, extra = {}) => u && media.push({
+      type, index: media.length, url: u, thumbnail: extra.thumbnail ?? null,
+      mimeType: extra.mimeType ?? null, width: extra.width ?? null, height: extra.height ?? null,
+      duration: extra.duration ?? null, size: null, quality: extra.quality ?? null,
+      hasAudio: type === "video", hasVideo: type === "video", source: name, variants: [],
+    });
+
+    const rv = post.secure_media?.reddit_video || post.media?.reddit_video;
+    if (rv) add("video", rv.fallback_url, {
+      width: rv.width, height: rv.height, duration: rv.duration,
+      quality: rv.height ? `${rv.height}p` : null, mimeType: "video/mp4",
+      thumbnail: post.preview?.images?.[0]?.source?.url?.replace(/&/g, "&") ?? null,
+    });
+
+    if (post.gallery_data?.items && post.media_metadata) {
+      for (const it of post.gallery_data.items) {
+        const m = post.media_metadata[it.media_id];
+        const src = m?.s;
+        const u = src?.u?.replace(/&/g, "&") || src?.gif || src?.mp4;
+        if (u) add(m?.e === "AnimatedImage" ? "gif" : "image", u, {
+          width: src?.x, height: src?.y, mimeType: m?.m ?? null,
+          quality: src?.x && src?.y ? `${src.x}x${src.y}` : null,
+        });
+      }
+    }
+    if (!media.length && post.preview?.images?.length) {
+      add("image", post.preview.images[0].source.url.replace(/&/g, "&"), {
+        width: post.preview.images[0].source.width, height: post.preview.images[0].source.height,
+      });
+    }
+    if (!media.length) throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Reddit post has no retrievable media");
+
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    return {
+      result: {
+        sourceUrl: url, platform: "reddit", title: post.title ?? null, author: post.author ?? null,
+        thumbnail: media[0].thumbnail ?? null, itemCount: media.length,
+        counts: {
+          images: media.filter((m) => m.type === "image").length,
+          videos: media.filter((m) => m.type === "video").length,
+          audios: 0, other: media.filter((m) => m.type === "gif").length,
+        },
+        truncated: false, media,
+      },
+      engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+    };
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    if (e instanceof UMediaError) throw e;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Reddit unavailable: ${e.message}`, { attempts: [attempt] });
+  }
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/tiktok.js

@@ -0,0 +1,165 @@
+import { fetchJson, fetchText } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/** TikTok — oEmbed metadata + embed/v2 for photo posts (proven adapter), CDN media. */
+export const name = "tiktok";
+
+export function canHandle(url) {
+  return /tiktok\.com\//i.test(String(url)) || /vm\.tiktok\.com\//i.test(String(url));
+}
+
+export function postId(url) {
+  const m = String(url).match(/\/(?:photo|video|embed\/v2?)\/(\d+)/);
+  return m ? m[1] : null;
+}
+
+const _cache = new Map(); // id -> {at, data}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+
+  // 1) oEmbed: title/author/thumbnail (works for public posts)
+  let meta = {};
+  try {
+    meta = await fetchJson(`https://www.tiktok.com/oembed?url=${encodeURIComponent(url)}`, {}, 12_000);
+  } catch { /* oEmbed is advisory */ }
+
+  // 2) embed/v2: the reliable path for photo galleries + video playAddr
+  const id = postId(url);
+  const attempts = [];
+  let payload = id ? _cache.get(id) : null;
+  if (!payload?.data) {
+    for (let i = 0; i < 3 && !payload; i++) {
+      try {
+        const target = id
+          ? `https://www.tiktok.com/embed/v2/${id}`
+          : `https://www.tiktok.com/embed/${encodeURIComponent(url)}`;
+        const { status, text } = await fetchText(target, {}, 15_000);
+        if (status === 200 && text.includes("__UNIVERSAL_DATA")) {
+          const raw = text.split('<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__" type="application/json">')[1]?.split("</script>")[0];
+          payload = { data: JSON.parse(raw) };
+          if (id) _cache.set(id, { at: Date.now(), data: payload.data });
+        } else if (status === 200) {
+          // 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) {
+        attempts.push(e.message);
+        await new Promise((r) => setTimeout(r, 800 * (i + 1)));
+      }
+    }
+  }
+
+  const media = [];
+  const scope = payload?.data?.__DEFAULT_SCOPE__?.["webapp.video-detail"]?.itemInfo?.itemStruct
+    || payload?.data?.itemInfo?.itemStruct
+    || null;
+
+  // 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",
+        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: [],
+      });
+    });
+  } 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: [],
+    });
+  }
+
+  if (!media.length) {
+    attempt.status = "failed";
+    attempt.error = attempts.length ? attempts[attempts.length - 1] : "no media exposed (post may be private or region-locked)";
+    // honest failure — unless oEmbed gave us at least a thumbnail-level record
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `TikTok media not retrievable for this URL. ${attempt.error}`, { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: "tiktok",
+      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: {
+        images: media.filter((m) => m.type === "image").length,
+        videos: media.filter((m) => m.type === "video").length,
+        audios: 0, other: 0,
+      },
+      // 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 },
+  };
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/x.js

@@ -0,0 +1,71 @@
+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) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["twitter.com", "x.com"]);
+  } catch { return false; }
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const m = String(url).match(/status\/(\d+)/);
+  if (!m) throw new UMediaError(Codes.INVALID_URL, `No status id in ${url}`);
+  const t0 = Date.now();
+  try {
+    const tw = await fetchJson(`https://cdn.syndication.twimg.com/tweet-result?id=${m[1]}&lang=en`, {}, 12_000);
+    const media = [];
+    const photos = tw.photos || [];
+    photos.forEach((p, i) => media.push({
+      type: "image", index: i, url: p.url, thumbnail: p.url,
+      mimeType: "image/jpeg", width: p.width ?? null, height: p.height ?? null,
+      duration: null, size: null, quality: p.width && p.height ? `${p.width}x${p.height}` : null,
+      hasAudio: false, hasVideo: false, source: name, variants: [],
+    }));
+    const vids = tw.video?.variants || [];
+    const mp4s = vids.filter((v) => v.src?.includes(".mp4")).sort((a, b) => (b.bitrate || 0) - (a.bitrate || 0));
+    if (mp4s.length) {
+      const best = mp4s[0];
+      media.push({
+        type: "video", index: media.length, url: best.src, thumbnail: tw.video?.poster ?? null,
+        mimeType: "video/mp4", width: null, height: null,
+        duration: tw.video?.duration_millis ? tw.video.duration_millis / 1000 : null,
+        size: null, quality: best.bitrate ? `~${Math.round(best.bitrate / 1000)}kbps` : null,
+        hasAudio: true, hasVideo: true, source: name,
+        variants: mp4s.map((v) => ({
+          quality: v.bitrate ? `~${Math.round(v.bitrate / 1000)}kbps` : "unknown",
+          url: v.src, mimeType: "video/mp4", hasAudio: true, hasVideo: true,
+        })),
+      });
+    }
+    if (!media.length) throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Post has no media (or it is not public)");
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    return {
+      result: {
+        sourceUrl: url, platform: "x", title: (tw.text || "").slice(0, 120) || null,
+        author: tw.user?.screen_name ?? null, thumbnail: media[0].thumbnail ?? null,
+        itemCount: media.length,
+        counts: {
+          images: media.filter((x) => x.type === "image").length,
+          videos: media.filter((x) => x.type === "video").length, audios: 0, other: 0,
+        },
+        truncated: false, media,
+      },
+      engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+    };
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    if (e instanceof UMediaError) throw e;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `X unavailable: ${e.message}`, { attempts: [attempt] });
+  }
+}
+
+export async function search() {
+  return [];
+}