umedia 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anonymous20666
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# 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.
+
+- **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
+
+```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 });
+for (const item of data.items) {
+  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);
+
+// 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);
+```
+
+## API
+
+All methods return `{ data, meta }` — the platform's normalized envelope.
+`meta.requestId` is included in every response (quote it when reporting issues).
+
+| 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 |
+
+## Errors
+
+Failures throw `UMediaError` with an honest, typed reason — never fake data:
+
+```js
+import { UMediaError, Codes } from "umedia";
+
+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();
+  }
+}
+```
+
+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`.
+
+> 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.
+
+## 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
+```
+
+Environment: `UMedia_API_KEY` (optional), `UMedia_BASE_URL` (optional override).
+
+## License
+
+MIT

package/bin/umedia.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * umedia CLI — search · resolve · download through the Unified Media API.
+ *
+ *   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 status
+ *   umedia capabilities
+ *
+ * Env: UMedia_API_KEY (optional), UMedia_BASE_URL (optional).
+ */
+import { UMedia, UMediaError } from "../index.js";
+
+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);
+      const next = argv[i + 1];
+      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
+
+  umedia search "<query>" [--type video|music|movie|short_video] [--limit N] [--adult]
+  umedia resolve <url>
+  umedia download <url> [--type video] [--quality best] [--wait]
+  umedia status
+  umedia capabilities
+
+Env: UMedia_API_KEY (optional key), UMedia_BASE_URL (optional)`;
+
+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 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),
+      });
+      print({ items: data.items, meta });
+      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 });
+      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 });
+      break;
+    }
+    case "status": {
+      const { data, meta } = await client.status();
+      print({ ...data, meta });
+      break;
+    }
+    case "capabilities": {
+      const { data, meta } = await client.capabilities();
+      print({ ...data, meta });
+      break;
+    }
+    default:
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  if (e instanceof UMediaError) {
+    console.error(JSON.stringify({
+      success: false,
+      error: { code: e.code, message: e.message, requestId: e.requestId, attempts: e.attempts },
+    }, null, 2));
+  } else {
+    console.error(String(e && e.message ? e.message : e));
+  }
+  process.exit(1);
+});

package/index.d.ts

@@ -0,0 +1,232 @@
+/** umedia — official client for the Unified Media API (core media engine). */
+
+export const DEFAULT_BASE_URL: string;
+
+export type ErrorCode =
+  | "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";
+
+export const Codes: Readonly<Record<ErrorCode, ErrorCode>>;
+
+export class UMediaError extends Error {
+  name: "UMediaError";
+  code: ErrorCode;
+  status: number;
+  requestId: string | null;
+  attempts: ProviderAttempt[];
+  details: unknown;
+  constructor(code: ErrorCode, message: string, opts?: {
+    status?: number;
+    requestId?: string | null;
+    attempts?: ProviderAttempt[];
+    details?: unknown;
+  });
+}
+
+/** Honest provider-selection record — real attempts, never invented. */
+export interface ProviderAttempt {
+  provider: string;
+  status: "success" | "failed" | "skipped";
+  latencyMs?: number | null;
+  error?: string | null;
+}
+
+/** One real, honestly-labeled rendition of a media item. */
+export interface MediaVariant {
+  quality: string;                 // derived from ACTUAL source height — never upscaled
+  width?: number | null;
+  height?: number | null;
+  url?: string | null;
+  mimeType?: string | null;
+  bitrateKbps?: number | null;
+  hasAudio?: boolean | null;
+  hasVideo?: boolean | null;
+}
+
+/** One media item. Multi-item posts yield ONE MediaObject per item, in order. */
+export interface MediaObject {
+  type: "image" | "video" | "audio" | "short_video" | "gif";
+  index: number;
+  url: string;
+  thumbnail?: string | null;
+  mimeType?: string | null;
+  width?: number | null;
+  height?: number | null;
+  duration?: number | null;
+  size?: number | null;
+  quality?: string | null;         // best real quality of this item
+  hasAudio?: boolean | null;
+  hasVideo?: boolean | null;
+  source?: string;
+  variants: MediaVariant[];
+}
+
+export interface MediaCounts {
+  images: number;
+  videos: number;
+  audios: number;
+  other: number;
+}
+
+export interface ResolveResult {
+  sourceUrl: string;
+  platform?: string | null;
+  title?: string | null;
+  author?: string | null;
+  thumbnail?: string | null;
+  itemCount: number;
+  counts: MediaCounts;
+  /** true only when the max-media-items cap was hit — never silent truncation */
+  truncated: boolean;
+  media: MediaObject[];
+  [k: string]: unknown;
+}
+
+/** Provider-selection transparency (multi-source engine visibility). */
+export interface ResolveMeta {
+  attempts: ProviderAttempt[];
+  finalProvider?: string | null;
+  totalLatencyMs?: number | null;
+}
+
+export interface SearchItem {
+  id?: string;
+  title?: string;
+  author?: string;
+  pageUrl?: string;
+  url?: string;
+  thumbnail?: string | null;
+  duration?: number | null;
+  mediaType?: string;
+  source?: string;
+  quality?: string | null;
+  explicit?: boolean;
+  /** real 30s clip / trailer / official embed — `none` when nothing honest exists */
+  previewUrl?: string | null;
+  previewKind?: "clip30s" | "trailer" | "embed" | "none";
+  providers?: ProviderAttempt[];
+  [k: string]: unknown;
+}
+
+export interface SearchResponse {
+  items: SearchItem[];
+  adultFilter?: unknown;
+  [k: string]: unknown;
+}
+
+export interface DownloadFile {
+  name: string;
+  size?: number;
+  ext?: string;
+  mimeType?: string | null;
+  index: number;
+  [k: string]: unknown;
+}
+
+/** Honest download outcome — quality truth lives here. */
+export interface DownloadResult {
+  title?: string;
+  source?: string;
+  duration?: number | null;
+  width?: number | null;
+  height?: number | null;
+  requestedQuality?: string;
+  selectedQuality?: string | null;
+  fallback?: boolean | null;
+  mimeType?: string | null;
+  file?: DownloadFile | null;
+  files?: DownloadFile[];
+  itemCount?: number;
+  requestedItems?: number;
+  truncated?: boolean;
+  failedItems?: Array<{ index?: number; type?: string; url?: string; error?: string }>;
+  completedAt?: number | null;
+  [k: string]: unknown;
+}
+
+export interface DownloadJob {
+  jobId: string;
+  url: string;
+  type?: string;
+  status?: string;                 // queued | running | done | failed | cancelled
+  stage?: string | null;
+  progress?: number;
+  requestedQuality?: string;
+  createdAt?: number | null;
+  startedAt?: number | null;
+  finishedAt?: number | null;
+  /** present when status === "done" */
+  result?: DownloadResult | null;
+  [k: string]: unknown;
+}
+
+export interface DownloadHandle {
+  jobId: string;
+  status: string;
+  progress: number;
+  links: { status: string; file: string; cancel: string };
+}
+
+/** Normalized envelope meta — every response carries meta.requestId. */
+export interface Meta {
+  requestId: string;
+  cached: boolean;
+  source?: string | null;
+  timestamp: string;
+  [k: string]: unknown;
+}
+
+export interface Envelope<T> {
+  data: T;
+  meta: Meta;
+}
+
+export interface UMediaOptions {
+  /** Optional API key — sends `X-API-Key` (higher rate limits). */
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+export class UMedia {
+  constructor(opts?: UMediaOptions);
+  apiKey: string | null;
+  baseUrl: string;
+  timeoutMs: number;
+
+  search(p?: {
+    q?: string;
+    query?: string;
+    type?: "video" | "music" | "movie" | "short_video";
+    limit?: number;
+    adult?: boolean;
+  }): Promise<Envelope<SearchResponse>>;
+
+  resolve(url: string): Promise<{ data: ResolveResult; engine?: ResolveMeta; meta: Meta }>;
+
+  createDownload(p: {
+    url: string;
+    type?: "video" | "music" | "movie" | "short_video";
+    /** original | best | 2160p … 144p | audio */
+    quality?: string;
+  }): Promise<Envelope<DownloadHandle>>;
+
+  listDownloads(): Promise<Envelope<{ jobs?: DownloadJob[]; [k: string]: unknown }>>;
+
+  getDownload(jobId: string): Promise<Envelope<DownloadJob>>;
+
+  cancelDownload(jobId: string): Promise<Envelope<DownloadJob>>;
+
+  fileUrl(jobId: string, index?: number): string;
+
+  fetchFile(jobId: string, index?: number): Promise<Response>;
+
+  capabilities(): Promise<Envelope<{ platforms?: unknown[]; [k: string]: unknown }>>;
+
+  status(): Promise<Envelope<{ overall?: string; [k: string]: unknown }>>;
+}
+
+export default UMedia;

package/index.js

@@ -0,0 +1,220 @@
+/**
+ * umedia — official client for the Unified Media API (core media engine).
+ * Search · Resolve · Download — honest quality labels, real previews.
+ * Zero dependencies. Node 18+ / any fetch-capable runtime.
+ */
+
+export const DEFAULT_BASE_URL = "https://pappy-api-downloader.duckdns.org";
+
+/** Error codes returned in `error.code` (stable API contract). */
+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 {
+  /**
+   * @param {string} code one of {@link Codes}
+   * @param {string} message human-readable, honest failure reason
+   * @param {{status?: number, requestId?: string|null, attempts?: object[]}} [opts]
+   */
+  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;
+  }
+}
+
+export class UMedia {
+  /**
+   * @param {{apiKey?: string, baseUrl?: string, timeoutMs?: number, fetch?: typeof fetch}} [opts]
+   *   apiKey — optional; sends `X-API-Key` (higher rate limits). Never required for public reads.
+   */
+  constructor(opts = {}) {
+    const { apiKey, baseUrl = DEFAULT_BASE_URL, timeoutMs = 60_000, fetch: fetchImpl } = opts;
+    this.apiKey = apiKey || null;
+    this.baseUrl = String(baseUrl).replace(/\/+$/, "");
+    this.timeoutMs = timeoutMs;
+    this._fetch = fetchImpl || globalThis.fetch;
+    if (typeof this._fetch !== "function") {
+      throw new TypeError("umedia: no fetch available — use Node 18+ or pass { fetch }");
+    }
+  }
+
+  async _call(method, path, body) {
+    const headers = { accept: "application/json" };
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    const init = { method, headers };
+    if (body !== undefined) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), this.timeoutMs);
+    init.signal = ctl.signal;
+
+    let res;
+    try {
+      res = await this._fetch(this.baseUrl + path, init);
+    } catch (e) {
+      const timedOut = e && (e.name === "AbortError" || e.code === "ABORT_ERR");
+      throw new UMediaError(
+        timedOut ? Codes.TIMEOUT : Codes.PROVIDER_UNAVAILABLE,
+        timedOut ? `Request timed out after ${this.timeoutMs}ms` : `Network error: ${e.message}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+
+    let env;
+    try {
+      env = await res.json();
+    } catch {
+      throw new UMediaError(Codes.INTERNAL, `Non-JSON response (HTTP ${res.status})`, { status: res.status });
+    }
+
+    if (!res.ok || env?.success === false) {
+      const err = env?.error || {};
+      const code = err.code
+        || (res.status === 429 ? Codes.RATE_LIMITED
+          : res.status === 401 ? Codes.AUTH_REQUIRED
+            : res.status === 404 ? Codes.NOT_FOUND
+              : Codes.INTERNAL);
+      throw new UMediaError(code, err.message || `HTTP ${res.status}`, {
+        status: res.status,
+        requestId: env?.meta?.requestId ?? null,
+        attempts: err.attempts || env?.meta?.attempts || [],
+        details: err.details ?? null,
+      });
+    }
+    return { data: env.data, meta: env.meta };
+  }
+
+  // ---------- core: search / resolve ----------
+
+  /**
+   * Search across providers (music leads with real 30s previews).
+   * @param {{q?: string, query?: string, type?: "video"|"music"|"movie"|"short_video", limit?: number, adult?: boolean}} [p]
+   * @returns {Promise<{data: {items: object[], adultFilter?: object}, meta: object}>}
+   */
+  search(p = {}) {
+    const q = p.q ?? p.query ?? "";
+    const type = p.type ?? "video";
+    const limit = Math.max(1, Math.min(25, p.limit ?? 12));
+    const adult = p.adult ? "true" : "false";
+    return this._call(
+      "GET",
+      `/api/v1/social/search?q=${encodeURIComponent(q)}&type=${encodeURIComponent(type)}&limit=${limit}&adult=${adult}`,
+    );
+  }
+
+  /**
+   * Resolve a post URL into ALL of its media — every photo, every video, in order.
+   * Multi-item posts return one MediaObject per item; `truncated` is never silent.
+   * `engine` surfaces the provider attempts behind the result (multi-source transparency).
+   * @param {string} url
+   * @returns {Promise<{data: ResolveResult, engine?: {attempts: object[], finalProvider?: string|null, totalLatencyMs?: number|null}, meta: object}>}
+   */
+  async resolve(url) {
+    const { data, meta } = await this._call("POST", "/api/v1/social/resolve", { url });
+    return { data: data?.result ?? data, engine: data?.engine, meta };
+  }
+
+  // ---------- core: downloads ----------
+
+  /**
+   * Enqueue a download job. Quality is honest: the result reports
+   * {requestedQuality, selectedQuality, fallback} — never manufactured.
+   * @param {{url: string, type?: "video"|"music"|"movie"|"short_video", quality?: string}} p
+   *        quality: original | best | 2160p … 144p | audio
+   * @returns {Promise<{data: {jobId: string, status: string, progress: number, links: {status: string, file: string, cancel: string}}, meta: object}>}
+   */
+  createDownload(p = {}) {
+    if (!p.url) throw new UMediaError(Codes.INVALID_REQUEST, "createDownload: { url } is required");
+    return this._call("POST", "/api/v1/download", {
+      url: p.url,
+      type: p.type ?? "video",
+      quality: p.quality ?? "best",
+    });
+  }
+
+  /** List download jobs for this API key. */
+  listDownloads() {
+    return this._call("GET", "/api/v1/download");
+  }
+
+  /**
+   * Poll a download job. When done, `data.result` carries files[], itemCount,
+   * requestedItems, truncated, failedItems[], requestedQuality, selectedQuality.
+   */
+  getDownload(jobId) {
+    return this._call("GET", `/api/v1/download/${encodeURIComponent(jobId)}`);
+  }
+
+  /** Cancel a queued/running job. */
+  cancelDownload(jobId) {
+    return this._call("POST", `/api/v1/download/${encodeURIComponent(jobId)}/cancel`);
+  }
+
+  /**
+   * Direct URL of one result file. Single-file jobs stream the file;
+   * multi-item jobs serve an ordered zip (`001 - name`).
+   */
+  fileUrl(jobId, index = 0) {
+    return `${this.baseUrl}/api/v1/download/${encodeURIComponent(jobId)}/file?index=${index}`;
+  }
+
+  /** Fetch one result file as a Response (streams in Node and browsers). */
+  async fetchFile(jobId, index = 0) {
+    const headers = {};
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    let res;
+    try {
+      res = await this._fetch(this.fileUrl(jobId, index), { headers });
+    } catch (e) {
+      throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Network error: ${e.message}`);
+    }
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`;
+      try {
+        const env = await res.json();
+        if (env?.error?.message) message = env.error.message;
+      } catch { /* binary error body */ }
+      throw new UMediaError(res.status === 404 ? Codes.NOT_FOUND : Codes.PROVIDER_ERROR, message, {
+        status: res.status,
+      });
+    }
+    return res;
+  }
+
+  // ---------- platform metadata (public) ----------
+
+  /** Live capability registry: which platforms/media types the engine serves. */
+  capabilities() {
+    return this._call("GET", "/api/v1/capabilities");
+  }
+
+  /** Real operational status — components and provider intelligence. */
+  status() {
+    return this._call("GET", "/api/v1/status");
+  }
+}
+
+export default UMedia;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "umedia",
+  "version": "0.1.0",
+  "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",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "umedia": "./bin/umedia.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "media",
+    "api",
+    "sdk",
+    "youtube",
+    "tiktok",
+    "instagram",
+    "reddit",
+    "downloader",
+    "search",
+    "resolve",
+    "rest"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anonymous20666/unified-media-api.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Anonymous20666/unified-media-api/issues"
+  },
+  "homepage": "https://github.com/Anonymous20666/unified-media-api#readme"
+}