umedia 0.1.2 → 0.2.1

package/README.md

@@ -4,20 +4,25 @@
 
 # umedia
 
-**One API for every media platform — in your code and in your terminal.**
+**The standalone media engine — search, resolve and download, entirely on YOUR machine.**
 
-Search, resolve and download media from YouTube · TikTok · Instagram · Reddit · X · iTunes · 1800+ sites
+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)
 
 [![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)
-[![dependencies](https://img.shields.io/badge/dependencies-0-8b5cf6)](#-zero-dependencies)
 [![license](https://img.shields.io/npm/l/umedia?color=22d3ee)](LICENSE)
 
 </div>
 
 ---
 
-## ⚡ From zero to media in 60 seconds
+## 💸 Why this exists
+
+Hosted media APIs cost money **every month** — per request, per user, per server.
+`umedia` flips the model: the engine runs **inside your app**. Your users' machines do the work,
+so your costs are… zero. Install it, call it, ship.
 
 ```bash
 npm install umedia
@@ -26,139 +31,83 @@ npm install umedia
 ```js
 import { UMedia } from "umedia";
 
-const client = new UMedia({ apiKey: process.env.UMedia_API_KEY }); // key optional
-
-const { data } = await client.search({ q: "afrobeats", type: "music", limit: 3 });
-for (const item of data.items) {
-  console.log(item.title, "—", item.previewKind, "→", item.previewUrl);
-}
-```
-
-That's it. No SDK zoo, no six-service setup — one small client, the whole media web behind it.
-
----
-
-## 🎯 Why developers pick it
+const media = new UMedia();
 
-### 🏷️ Honest quality — the industry's favorite lie, removed
+// 1) Search — music leads with REAL 30-second previews
+const { data } = await media.search({ q: "afrobeats", type: "music", limit: 3 });
+for (const item of data.items) console.log(item.title, "—", item.previewKind, "→", item.previewUrl);
 
-Every download reports what you **asked for** vs what the source **actually has**:
+// 2) Resolve a post → ALL media, in order
+const { data: post } = await media.resolve("https://www.tiktok.com/@user/photo/7690630628697459990");
+console.log(post.itemCount, post.counts);   // 30 { images: 30, … } — never truncated silently
 
-```js
-const { data: handle } = await client.createDownload({ url: oldVideo, quality: "best" });
-// … poll …
-const r = (await client.getDownload(handle.jobId)).data.result;
-console.log(r.requestedQuality, "→", r.selectedQuality); // "best" → "240p"  ← real, never invented
+// 3) Download everything to disk
+const { data: job } = await media.download({ url: post.sourceUrl, quality: "best", dir: "./out" });
+console.log(job.requestedQuality, "→", job.selectedQuality);  // "best" → "720p" — real, never invented
 ```
 
-Quality is derived from the real source height. There is no "1080p" sticker on a 240p file. Ever.
-
-### 🖼️ Galleries arrive complete — 100 photos means 100 photos
+That's the whole model: **your code, your machine, your files.**
 
-A TikTok photo post with 30 slides resolves to **30 MediaObjects, in order**. A mixed post keeps
-its sequence. If anything is dropped, it's named — `truncated: true`, `failedItems[]` — never silent.
-
-### 🎧 Previews drop first
-
-Music search leads with real **30-second clips** (`previewKind: "clip30s"`), movies with trailers,
-social posts with official embeds. `previewKind: "none"` when nothing honest exists — we'd rather
-say "none" than fake one.
+---
 
-### 🧯 Typed failures instead of mystery crashes
+## 🎯 The contract that keeps your app honest
 
-```js
-import { UMediaError, Codes } from "umedia";
-
-try {
-  await client.resolve(url);
-} catch (e) {
-  if (e instanceof UMediaError) {
-    console.error(e.code, e.message, e.requestId); // e.g. PROVIDER_UNAVAILABLE, req_9f3a…
-    if (e.code === Codes.RATE_LIMITED) await sleep(60_000);
-    if (e.code === Codes.PROVIDER_UNAVAILABLE) await retryWithBackoff();
-  }
-}
-```
+### 🏷️ Quality is never manufactured
+`requestedQuality` vs `selectedQuality` on every download. A 240p source never arrives wearing a
+1080p sticker. `fallback: true` tells you exactly when reality differed from the request.
 
-Every response — success or failure — carries a `meta.requestId`. Quote it and support can trace it.
+### 🖼️ Galleries arrive complete
+100 photos → **100 files, in order** (`001 - …`, `002 - …`). Anything that failed is named in
+`failedItems[]` with the reason — never silent, never partial-by-accident.
 
-### 📦 Zero dependencies
+### 🎧 Previews drop first
+Music search leads with real **30s iTunes clips** (`previewKind: "clip30s"`), movies with YouTube
+trailers, social posts with official embeds. `previewKind: "none"` beats a fake preview.
 
-Node 18+, browsers, Deno, Bun. If you have `fetch`, you have `umedia`.
+### 🧯 Typed failures, always
+`UMediaError` with a stable `code` (`RATE_LIMITED`, `MEDIA_NOT_FOUND`, `PROVIDER_UNAVAILABLE`,
+`SSRF_BLOCKED`, …), plus `engine.attempts[]` — the real trail of which providers were tried and why.
 
 ---
 
-## 🧭 The tour
-
-### Resolve a post → every photo, every video, in order
-
-```js
-const { data: post, engine } = await client.resolve(
-  "https://www.tiktok.com/@user/photo/7690630628697459990"
-);
-
-console.log(post.itemCount);   // 30
-console.log(post.counts);      // { images: 30, videos: 0, audios: 0, other: 0 }
-console.log(post.truncated);   // false — we tell you, always
+## 🗺️ What runs where (honest edition)
 
-for (const m of post.media) {
-  console.log(m.index, m.type, m.quality, m.url);
-}
+| Platform | Search | Resolve | Download | How |
+|---|---|---|---|---|
+| **YouTube** | ✅ | ✅ | ✅ * | InnerTube — search & metadata always; stream URLs depend on your network (see below) |
+| **TikTok** | — | ✅ | ✅ | video posts = direct CDN mp4; photo galleries = every slide the platform publicly exposes, `truncated: true` when it degrades galleries |
+| **Instagram** | — | ✅ best-effort | ✅ | public embeds (gated on some networks — the yt-dlp tier is the reliable path) |
+| **Reddit** | — | ✅ best-effort | ✅ | public JSON across reddit edges (datacenter IPs often 403 — typed honest error) |
+| **X** | — | ✅ best-effort | ✅ | public syndication (media login-gated on some networks — typed honest error) |
+| **iTunes** | ✅ | — | ✅ previews | real 30s clips, rock solid |
+| **1800+ sites** | — | ✅ | ✅ | optional tier: `pip install yt-dlp` — labeled `source: "ytdlp"` |
 
-// who actually served this — multi-source transparency
-console.log(engine.attempts, engine.finalProvider, engine.totalLatencyMs + "ms");
-```
+**\* About YouTube stream URLs:** YouTube bot-gates datacenter IPs and serves formats without URLs.
+On typical home connections `download()` just works; on hard networks you'll get a typed
+`PROVIDER_UNAVAILABLE` with the real reason — or run `download({ … })` via
+`downloadWithYtdlp()` / `umedia download <url> --ytdlp` which handles PO tokens, cookies and muxing.
+We'd rather tell you the truth than fake a download.
 
-### Download — jobs, honest results, streaming files
+**Direct media URLs always work:** give `resolve()`/`download()` any direct `.mp4/.m4a/.jpg/…` link and it
+goes straight to disk — no platform needed.
 
 ```js
-const { data: handle } = await client.createDownload({
-  url: "https://youtu.be/jNQXAC9IVRw",
-  type: "video",
-  quality: "best",        // original | best | 2160p … 144p | audio
-});
-
-// poll the job
-let job;
-do {
-  await new Promise((r) => setTimeout(r, 2000));
-  job = (await client.getDownload(handle.jobId)).data;
-} while (!["done", "failed", "cancelled"].includes(job.status));
-
-// honest outcome
-const r = job.result;
-console.log(r.requestedQuality, "→", r.selectedQuality, r.fallback ? "(fallback)" : "");
-
-// stream or save
-const res = await client.fetchFile(handle.jobId, 0);
-// multi-item job? files come as an ordered zip: "001 - name.jpg", "002 - …"
-for (const f of r.files) console.log(f.index, f.name, client.fileUrl(handle.jobId, f.index));
-```
-
-### Platform metadata — real, not marketing
-
-```js
-const { data: caps } = await client.capabilities();  // live capability registry
-const { data: st }   = await client.status();        // real component + provider health
-console.log(st.overall); // "operational" — checked, not hard-coded
+// the power tier — one function, 1800+ sites, hard networks
+await media.downloadWithYtdlp({ url: "https://example.com/anything", quality: "720p", dir: "./out" });
 ```
 
 ---
 
-## 📚 Reference
-
-| Method | Endpoint | Notes |
-|---|---|---|
-| `search({q, type, limit, adult})` | `GET /api/v1/social/search` | `type`: `video` \| `music` \| `movie` \| `short_video` · `limit ≤ 25` |
-| `resolve(url)` | `POST /api/v1/social/resolve` | returns `{ data: ResolveResult, engine }` |
-| `createDownload({url, type, quality})` | `POST /api/v1/download` | returns `{ jobId, status, progress, links }` |
-| `getDownload(jobId)` | `GET /api/v1/download/{id}` | poll until `done` / `failed` / `cancelled` |
-| `listDownloads()` | `GET /api/v1/download` | jobs for this key |
-| `cancelDownload(jobId)` | `POST /api/v1/download/{id}/cancel` | |
-| `fileUrl(jobId, index)` | `GET /api/v1/download/{id}/file?index=N` | single = file · multi = ordered zip |
-| `fetchFile(jobId, index)` | same | returns a streamable `Response` |
-| `capabilities()` | `GET /api/v1/capabilities` | live platform registry |
-| `status()` | `GET /api/v1/status` | real health, refreshed continuously |
+## 📚 API
+
+| Call | What it does |
+|---|---|
+| `media.search({q, type, limit, adult})` | Multi-source search — `type`: `video` \| `music` \| `movie` \| `short_video` |
+| `media.resolve(url)` | Every media item of a post, in order + honest `engine.attempts` |
+| `media.download({url, quality, dir, zip, onProgress})` | Saves files to disk — `quality`: `original` \| `best` \| `2160p` … `144p` \| `audio` |
+| `media.downloadWithYtdlp({url, quality, dir})` | yt-dlp tier (requires `yt-dlp` on PATH) |
+| `media.capabilities()` | What THIS machine can actually do — never overstated |
+| `media.status()` | Real adapter status |
 
 **Error codes** — `INVALID_REQUEST` · `INVALID_URL` · `SSRF_BLOCKED` · `AUTH_REQUIRED` ·
 `AUTH_INVALID` · `RATE_LIMITED` · `MEDIA_NOT_FOUND` · `CONTENT_PRIVATE` · `ACCESS_RESTRICTED` ·
@@ -166,45 +115,30 @@ console.log(st.overall); // "operational" — checked, not hard-coded
 
 ---
 
-## 🖥️ The CLI
+## 🖥️ CLI
 
 ```bash
 npx umedia search "lofi beats" --type music --limit 5
 npx umedia resolve "https://www.tiktok.com/@user/photo/7690630628697459990"
-npx umedia download "https://youtu.be/jNQXAC9IVRw" --quality best --wait
+npx umedia download "https://youtu.be/jNQXAC9IVRw" --quality best -o ./out
+npx umedia download "https://example.com/video" --ytdlp      # power tier
 npx umedia status
-npx umedia capabilities
 ```
 
-`--wait` polls the job and prints ready-to-use file URLs. Environment: `UMedia_API_KEY` (optional),
-`UMedia_BASE_URL` (optional override).
-
 ---
 
-## 🤝 The honest reliability contract
-
-Let's be straight about guarantees, because the industry isn't:
-
-- **Our layer** (auth, search, resolve, downloads, files): designed and measured for high
-  availability — hundreds of requests per second sustained on this platform, 4-worker jobs,
-  typed errors with `requestId` on every failure. A correct integration **degrades gracefully;
-  it does not break**.
-- **Their layer** (the upstream platforms): YouTube, TikTok and friends change, throttle and
-  geo-block. **No media API on earth can honestly promise zero upstream failures** — and this one
-  won't insult you by pretending.
-- **What you get instead**: real data or a typed, honest error. Never fake quality, never silent
-  truncation, never a `200` with garbage. `requestedQuality` vs `selectedQuality`, `truncated`,
-  `failedItems[]`, `engine.attempts[]` — the truth is in every payload.
+## 🧯 Safety, built in
 
-Build against the contract and your users see graceful, explainable behavior — the thing that
-*makes apps feel reliable*.
+- **SSRF hygiene** — private, loopback and internal hosts are refused (`SSRF_BLOCKED`).
+- **No secrets to manage** — there are none. No keys, no tokens, no dashboards.
+- **Zero telemetry.** Your users' requests never touch anyone's server — because there isn't one.
 
 ---
 
 <div align="center">
 
-**`umedia` ships the media engine only** — account and key management live in the web platform.
+**Built to save you the hosting bill.** Ship the engine, not the infrastructure.
 
-MIT © 2026 · [Unified Media API](https://dev-pappy-api-downloader.duckdns.org)
+MIT © 2026 · part of the [Unified Media API](https://dev-pappy-api-downloader.duckdns.org) project
 
 </div>

package/bin/umedia.js

@@ -1,14 +1,12 @@
 #!/usr/bin/env node
 /**
- * umedia CLI — search · resolve · download through the Unified Media API.
+ * umedia CLI — the standalone media engine, in your terminal.
  *
  *   umedia search "afrobeats" --type music --limit 5
  *   umedia resolve "https://www.tiktok.com/@user/photo/123"
- *   umedia download "https://youtu.be/jNQXAC9IVRw" --quality best --wait
+ *   umedia download "https://youtu.be/jNQXAC9IVRw" --quality best -o ./out
  *   umedia status
  *   umedia capabilities
- *
- * Env: UMedia_API_KEY (optional), UMedia_BASE_URL (optional).
  */
 import { UMedia, UMediaError } from "../index.js";
 
@@ -16,94 +14,70 @@ function parseArgs(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
+    if (a.startsWith("--") || a.startsWith("-")) {
+      const key = a.replace(/^-+/, "");
       const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith("--")) { out[key] = next; i++; }
+      if (next !== undefined && !next.startsWith("-")) { out[key] = next; i++; }
       else out[key] = true;
     } else out._.push(a);
   }
   return out;
 }
 
-const HELP = `umedia — Unified Media API client
+const HELP = `umedia — standalone media engine (runs on YOUR machine, no API needed)
 
-  umedia search "<query>" [--type video|music|movie|short_video] [--limit N] [--adult]
+  umedia search "<query>" [--type video|music|movie|short_video] [--limit N]
   umedia resolve <url>
-  umedia download <url> [--type video] [--quality best] [--wait]
+  umedia download <url> [--quality best|720p|audio] [-o <dir>] [--zip] [--ytdlp]
   umedia status
-  umedia capabilities
-
-Env: UMedia_API_KEY (optional key), UMedia_BASE_URL (optional)`;
+  umedia capabilities`;
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._[0];
-
 if (!cmd || cmd === "help" || args.help) {
   console.log(HELP);
   process.exit(0);
 }
 
-const client = new UMedia({
-  apiKey: process.env.UMedia_API_KEY,
-  baseUrl: process.env.UMedia_BASE_URL,
-});
-
+const client = new UMedia({ downloadDir: args.o || args.out || "./umedia-downloads" });
 const print = (x) => console.log(JSON.stringify(x, null, 2));
 
 async function main() {
   switch (cmd) {
     case "search": {
       const q = args._.slice(1).join(" ");
-      if (!q) throw new UMediaError("INVALID_REQUEST", "usage: umedia search \"<query>\"");
-      const { data, meta } = await client.search({
-        q,
-        type: args.type || "video",
-        limit: args.limit ? Number(args.limit) : 12,
-        adult: Boolean(args.adult),
+      if (!q) throw new UMediaError("INVALID_REQUEST", 'usage: umedia search "<query>"');
+      const { data, meta, engine } = await client.search({
+        q, type: args.type || "video", limit: args.limit ? Number(args.limit) : 12, adult: Boolean(args.adult),
       });
-      print({ items: data.items, meta });
+      print({ items: data.items, meta, engine });
       break;
     }
     case "resolve": {
       const url = args._[1];
       if (!url) throw new UMediaError("INVALID_REQUEST", "usage: umedia resolve <url>");
-      const { data, meta } = await client.resolve(url);
-      print({ ...data, meta });
+      const r = await client.resolve(url);
+      print(r);
       break;
     }
     case "download": {
       const url = args._[1];
       if (!url) throw new UMediaError("INVALID_REQUEST", "usage: umedia download <url>");
-      let { data } = await client.createDownload({
-        url,
-        type: args.type || "video",
-        quality: args.quality || "best",
-      });
-      const jobId = data.jobId;
-      if (args.wait) {
-        for (;;) {
-          await new Promise((r) => setTimeout(r, 2000));
-          ({ data } = await client.getDownload(jobId));
-          if (["done", "failed", "cancelled"].includes(data.status)) break;
-          process.stderr.write(`  status: ${data.status}${data.stage ? " · " + data.stage : ""}\n`);
-        }
-      }
-      const result = data.result || null;
-      if (result && result.files) {
-        result.files = result.files.map((f) => ({ ...f, url: client.fileUrl(jobId, f.index) }));
-      }
-      print({ ...data, result });
+      const onProgress = args.json ? undefined : (done, total) => {
+        if (total) process.stderr.write(`\r  ${((done / total) * 100).toFixed(1)}%`);
+      };
+      const fn = args.ytdlp ? client.downloadWithYtdlp.bind(client) : client.download.bind(client);
+      const r = await fn({ url, quality: args.quality || "best", type: args.type || "video", zip: Boolean(args.zip), onProgress });
+      if (!args.json) process.stderr.write("\n");
+      print(r.data);
       break;
     }
     case "status": {
-      const { data, meta } = await client.status();
-      print({ ...data, meta });
+      print((await client.status()).data);
       break;
     }
     case "capabilities": {
-      const { data, meta } = await client.capabilities();
-      print({ ...data, meta });
+      print((await client.capabilities()).data);
       break;
     }
     default: