umedia 0.1.0 → 0.1.1

package/README.md

@@ -1,77 +1,70 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Anonymous20666/unified-media-api/main/web/og-image.jpg" alt="Unified Media API — one API for every media platform" width="760" />
+
 # umedia
 
-Official client for the **Unified Media API** — search, resolve and download media from
-YouTube, TikTok, Instagram, Reddit, X, iTunes and 1800+ sites through one REST API.
+**One API for every media platform — in your code and in your terminal.**
+
+Search, resolve and download media from YouTube · TikTok · Instagram · Reddit · X · iTunes · 1800+ sites
+
+[![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>
 
-- **Zero dependencies.** Node 18+, browsers, Deno, Bun — anything with `fetch`.
-- **Honest quality labels.** Every result reports `requestedQuality` vs `selectedQuality`
-  and a `fallback` flag. Quality is derived from the real source height — never manufactured.
-- **Full galleries preserved.** A 100-photo post resolves to 100 items, in order.
-  `truncated` / `failedItems[]` are always explicit — never silent.
-- **Real previews first.** 30s clips (`clip30s`), trailers, or official `embed`s —
-  `previewKind: "none"` when nothing honest exists.
+---
 
-## Install
+## ⚡ From zero to media in 60 seconds
 
 ```bash
 npm install umedia
 ```
 
-## Quickstart
-
 ```js
 import { UMedia } from "umedia";
 
 const client = new UMedia({ apiKey: process.env.UMedia_API_KEY }); // key optional
 
-// 1) Search — music results lead with real 30s previews
-const { data } = await client.search({ q: "afrobeats mix", type: "music", limit: 5 });
+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);
+  console.log(item.title, "—", item.previewKind, "→", item.previewUrl);
 }
+```
 
-// 2) Resolve a post URL → ALL media, in order
-const { data: post } = await client.resolve("https://www.tiktok.com/@user/photo/7690630628697459990");
-console.log(post.itemCount, post.counts, post.truncated);
-for (const m of post.media) console.log(m.index, m.type, m.quality, m.url);
+That's it. No SDK zoo, no six-service setup — one small client, the whole media web behind it.
 
-// 3) Download — honest quality, multi-item jobs return an ordered zip
-const { data: handle } = await client.createDownload({ url: "https://youtu.be/jNQXAC9IVRw", quality: "best" });
-// poll until done
-let job;
-do {
-  await new Promise((r) => setTimeout(r, 2000));
-  job = (await client.getDownload(handle.jobId)).data;
-} while (job.status !== "done" && job.status !== "failed");
+---
 
-const r = job.result;
-console.log(r.requestedQuality, "->", r.selectedQuality, r.fallback ? "(fallback)" : "");
-for (const f of r.files) console.log(f.index, f.name, client.fileUrl(handle.jobId, f.index));
-// stream a file
-const res = await client.fetchFile(handle.jobId, 0);
+## 🎯 Why developers pick it
+
+### 🏷️ Honest quality — the industry's favorite lie, removed
+
+Every download reports what you **asked for** vs what the source **actually has**:
+
+```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
 ```
 
-## API
+Quality is derived from the real source height. There is no "1080p" sticker on a 240p file. Ever.
 
-All methods return `{ data, meta }` — the platform's normalized envelope.
-`meta.requestId` is included in every response (quote it when reporting issues).
+### 🖼️ Galleries arrive complete — 100 photos means 100 photos
 
-| 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 `ResolveResult` |
-| `createDownload({url, type, quality})` | `POST /api/v1/download` | `quality`: `original` \| `best` \| `2160p` … `144p` \| `audio` |
-| `getDownload(jobId)` | `GET /api/v1/download/{id}` | poll until `status` is `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 streams; multi-item = ordered zip |
-| `fetchFile(jobId, index)` | same | returns a `Response` (streamable) |
-| `capabilities()` | `GET /api/v1/capabilities` | live platform registry |
-| `status()` | `GET /api/v1/status` | real component + provider health |
+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.
 
-## Errors
+### 🎧 Previews drop first
 
-Failures throw `UMediaError` with an honest, typed reason — never fake data:
+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
 
 ```js
 import { UMediaError, Codes } from "umedia";
@@ -80,33 +73,138 @@ try {
   await client.resolve(url);
 } catch (e) {
   if (e instanceof UMediaError) {
-    console.log(e.code, e.message, e.requestId);
-    if (e.code === Codes.RATE_LIMITED) await wait(60_000);
-    if (e.code === Codes.PROVIDER_UNAVAILABLE) retryWithBackoff();
+    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();
   }
 }
 ```
 
-Codes: `INVALID_REQUEST`, `INVALID_URL`, `SSRF_BLOCKED`, `AUTH_REQUIRED`, `AUTH_INVALID`,
-`RATE_LIMITED`, `MEDIA_NOT_FOUND`, `CONTENT_PRIVATE`, `ACCESS_RESTRICTED`,
-`QUALITY_UNAVAILABLE`, `PROVIDER_ERROR`, `PROVIDER_UNAVAILABLE`, `TIMEOUT`, `NOT_FOUND`, `INTERNAL`.
+Every response — success or failure — carries a `meta.requestId`. Quote it and support can trace it.
+
+### 📦 Zero dependencies
+
+Node 18+, browsers, Deno, Bun. If you have `fetch`, you have `umedia`.
+
+---
 
-> Third-party platforms change, throttle and geo-block — no media API can promise zero
-> failures upstream. What this client guarantees: **typed, honest errors with a
-> `requestId` on every failure**, multi-provider attempts surfaced where available,
-> and graceful degradation instead of breakage.
+## 🧭 The tour
 
-## CLI
+### 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
+
+for (const m of post.media) {
+  console.log(m.index, m.type, m.quality, m.url);
+}
+
+// who actually served this — multi-source transparency
+console.log(engine.attempts, engine.finalProvider, engine.totalLatencyMs + "ms");
+```
+
+### Download — jobs, honest results, streaming files
+
+```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
+```
+
+---
+
+## 📚 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 |
+
+**Error codes** — `INVALID_REQUEST` · `INVALID_URL` · `SSRF_BLOCKED` · `AUTH_REQUIRED` ·
+`AUTH_INVALID` · `RATE_LIMITED` · `MEDIA_NOT_FOUND` · `CONTENT_PRIVATE` · `ACCESS_RESTRICTED` ·
+`QUALITY_UNAVAILABLE` · `PROVIDER_ERROR` · `PROVIDER_UNAVAILABLE` · `TIMEOUT` · `NOT_FOUND` · `INTERNAL`
+
+---
+
+## 🖥️ The 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 status
+npx umedia capabilities
 ```
 
-Environment: `UMedia_API_KEY` (optional), `UMedia_BASE_URL` (optional override).
+`--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.
+
+Build against the contract and your users see graceful, explainable behavior — the thing that
+*makes apps feel reliable*.
+
+---
+
+<div align="center">
+
+**`umedia` ships the media engine only** — account and key management live in the web platform.
 
-## License
+MIT © 2026 · [Unified Media API](https://dev-pappy-api-downloader.duckdns.org)
 
-MIT
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umedia",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official client for the Unified Media API — search, resolve and download media from YouTube, TikTok, Instagram, Reddit, X, iTunes and 1800+ sites through one REST API. Honest quality labels, multi-item galleries preserved, zero dependencies.",
   "type": "module",
   "main": "./index.js",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "umedia": "./bin/umedia.js"
+    "umedia": "bin/umedia.js"
   },
   "files": [
     "index.js",