umedia 0.1.2 → 0.2.1

package/index.d.ts

@@ -1,6 +1,4 @@
-/** umedia — official client for the Unified Media API (core media engine). */
-
-export const DEFAULT_BASE_URL: string;
+/** umedia — standalone media engine. Runs entirely on your machine: no hosted API, no keys, no bills. */
 
 export type ErrorCode =
   | "INVALID_REQUEST" | "INVALID_URL" | "SSRF_BLOCKED" | "AUTH_REQUIRED" | "AUTH_INVALID"
@@ -9,6 +7,7 @@ export type ErrorCode =
   | "NOT_FOUND" | "INTERNAL";
 
 export const Codes: Readonly<Record<ErrorCode, ErrorCode>>;
+export const qualityLadder: readonly string[];
 
 export class UMediaError extends Error {
   name: "UMediaError";
@@ -18,14 +17,11 @@ export class UMediaError extends Error {
   attempts: ProviderAttempt[];
   details: unknown;
   constructor(code: ErrorCode, message: string, opts?: {
-    status?: number;
-    requestId?: string | null;
-    attempts?: ProviderAttempt[];
-    details?: unknown;
+    status?: number; requestId?: string | null; attempts?: ProviderAttempt[]; details?: unknown;
   });
 }
 
-/** Honest provider-selection record — real attempts, never invented. */
+/** Honest provider record — which adapter actually did the work (or why it couldn't). */
 export interface ProviderAttempt {
   provider: string;
   status: "success" | "failed" | "skipped";
@@ -33,42 +29,35 @@ export interface ProviderAttempt {
   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;
+  url?: string | null;             // null when the network is bot-gated — never faked
   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;
+  url: string | null;
   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
+  quality?: string | null;
   hasAudio?: boolean | null;
   hasVideo?: boolean | null;
   source?: string;
   variants: MediaVariant[];
 }
 
-export interface MediaCounts {
-  images: number;
-  videos: number;
-  audios: number;
-  other: number;
-}
+export interface MediaCounts { images: number; videos: number; audios: number; other: number; }
 
 export interface ResolveResult {
   sourceUrl: string;
@@ -78,13 +67,15 @@ export interface ResolveResult {
   thumbnail?: string | null;
   itemCount: number;
   counts: MediaCounts;
-  /** true only when the max-media-items cap was hit — never silent truncation */
+  /** true only when an item cap was hit — never silent truncation */
   truncated: boolean;
   media: MediaObject[];
+  /** YouTube-specific honesty about stream URL availability on this network */
+  streamUrlsAvailable?: boolean;
+  streamAccess?: string;
   [k: string]: unknown;
 }
 
-/** Provider-selection transparency (multi-source engine visibility). */
 export interface ResolveMeta {
   attempts: ProviderAttempt[];
   finalProvider?: string | null;
@@ -96,137 +87,94 @@ export interface SearchItem {
   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 {
+export interface DownloadedFile {
   name: string;
-  size?: number;
-  ext?: string;
+  path: string;
+  size: number;
+  ext: string;
   mimeType?: string | null;
   index: number;
-  [k: string]: unknown;
+  quality?: string | null;
 }
 
-/** 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 };
+  title?: string | null;
+  source?: string | null;
+  requestedQuality: string;
+  selectedQuality: string | null;
+  fallback: boolean;
+  files: DownloadedFile[];
+  itemCount: number;
+  requestedItems: number;
+  truncated: boolean;
+  failedItems: Array<{ index?: number; type?: string; url?: string; error?: string }>;
+  note?: string;
 }
 
-/** Normalized envelope meta — every response carries meta.requestId. */
 export interface Meta {
   requestId: string;
-  cached: boolean;
   source?: string | null;
   timestamp: string;
-  [k: string]: unknown;
+  elapsedMs?: number;
 }
 
-export interface Envelope<T> {
-  data: T;
-  meta: Meta;
-}
+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;
+  /** default directory for downloads (default "./umedia-downloads") */
+  downloadDir?: string;
   timeoutMs?: number;
-  fetch?: typeof fetch;
 }
 
 export class UMedia {
   constructor(opts?: UMediaOptions);
-  apiKey: string | null;
-  baseUrl: string;
-  timeoutMs: number;
+  downloadDir: string;
 
   search(p?: {
-    q?: string;
-    query?: string;
+    q?: string; query?: string;
     type?: "video" | "music" | "movie" | "short_video";
-    limit?: number;
-    adult?: boolean;
-  }): Promise<Envelope<SearchResponse>>;
+    limit?: number; adult?: boolean;
+  }): Promise<Envelope<{ items: SearchItem[]; adultFilter?: unknown }> & { engine: { attempts: ProviderAttempt[] } }>;
 
-  resolve(url: string): Promise<{ data: ResolveResult; engine?: ResolveMeta; meta: Meta }>;
+  resolve(url: string): Promise<{ data: ResolveResult; engine: ResolveMeta }>;
 
-  createDownload(p: {
+  download(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 }>>;
+    type?: "video" | "music" | "movie" | "short_video";
+    dir?: string;
+    zip?: boolean;
+    onProgress?: (done: number, total: number) => void;
+  }): Promise<Envelope<DownloadResult> & { engine?: ResolveMeta }>;
+
+  downloadWithYtdlp(p: {
+    url: string; quality?: string; dir?: string;
+    onProgress?: (done: number, total: number) => void;
+  }): Promise<Envelope<DownloadResult>>;
+
+  capabilities(): Promise<Envelope<{
+    platforms: Array<{ platform: string; search: boolean; resolve: boolean; download: boolean | string; notes?: string }>;
+    qualityLadder: string[];
+  }>>;
+
+  status(): Promise<Envelope<{
+    overall: string;
+    runtime: { node: string; platform: string };
+    providers: Array<{ name: string; state: string; via: string }>;
+  }>>;
 }
 
 export default UMedia;

package/index.js

@@ -1,219 +1,75 @@
 /**
- * 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.
+ * umedia — standalone media engine. Runs entirely on YOUR machine:
+ * no hosted API, no keys, no rate limits, no server bills.
+ *
+ * Search · Resolve · Download — honest quality labels, real previews, complete galleries.
  */
+import { rid } from "./lib/util.js";
+import * as registry from "./lib/registry.js";
+import { download, downloadWithYtdlp } from "./lib/download.js";
+import { UMediaError, Codes } from "./lib/errors.js";
 
-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 { UMediaError, Codes };
+export { LADDER as qualityLadder } from "./lib/quality.js";
 
 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.
-   */
+  /** @param {{downloadDir?: string, timeoutMs?: number}} [opts] */
   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 }");
-    }
+    this.downloadDir = opts.downloadDir || "./umedia-downloads";
+    this.timeoutMs = opts.timeoutMs ?? 120_000;
   }
 
-  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).
+   * Multi-source search. Music leads with REAL 30s previews (iTunes), then YouTube.
    * @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,
+  async search(p = {}) {
+    const t0 = Date.now();
+    const { items, attempts } = await registry.search({
+      q: p.q ?? p.query ?? "",
       type: p.type ?? "video",
-      quality: p.quality ?? "best",
+      limit: Math.max(1, Math.min(25, p.limit ?? 12)),
+      adult: Boolean(p.adult),
     });
-  }
-
-  /** List download jobs for this API key. */
-  listDownloads() {
-    return this._call("GET", "/api/v1/download");
+    return {
+      data: { items, adultFilter: { enabled: !p.adult } },
+      meta: { requestId: rid(), source: attempts.find((a) => a.status === "success")?.provider ?? null, timestamp: new Date().toISOString(), elapsedMs: Date.now() - t0 },
+      engine: { attempts },
+    };
   }
 
   /**
-   * Poll a download job. When done, `data.result` carries files[], itemCount,
-   * requestedItems, truncated, failedItems[], requestedQuality, selectedQuality.
+   * Resolve a post URL into ALL of its media — every photo, every video, in order.
+   * `engine.attempts` is the honest provider trail.
    */
-  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`);
+  async resolve(url) {
+    return registry.resolve(url);
   }
 
   /**
-   * Direct URL of one result file. Single-file jobs stream the file;
-   * multi-item jobs serve an ordered zip (`001 - name`).
+   * Download every media item to disk (order preserved, failures named).
+   * Quality is honest: `requestedQuality` vs `selectedQuality` + `fallback`.
+   * @param {{url: string, quality?: string, type?: string, dir?: string, zip?: boolean, onProgress?: (done:number,total:number)=>void}} p
    */
-  fileUrl(jobId, index = 0) {
-    return `${this.baseUrl}/api/v1/download/${encodeURIComponent(jobId)}/file?index=${index}`;
+  async download(p = {}) {
+    if (!p.url) throw new UMediaError(Codes.INVALID_REQUEST, "download({ url }) — url is required");
+    return download({ ...p, dir: p.dir || this.downloadDir });
   }
 
-  /** 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;
+  /** Power tier: route a download through yt-dlp (1800+ sites, hard networks, muxing). */
+  async downloadWithYtdlp(p = {}) {
+    if (!p.url) throw new UMediaError(Codes.INVALID_REQUEST, "downloadWithYtdlp({ url }) — url is required");
+    return downloadWithYtdlp({ ...p, dir: p.dir || this.downloadDir });
   }
 
-  // ---------- platform metadata (public) ----------
-
-  /** Live capability registry: which platforms/media types the engine serves. */
-  capabilities() {
-    return this._call("GET", "/api/v1/capabilities");
+  /** What this engine can actually do on THIS machine — never overstated. */
+  async capabilities() {
+    return { data: registry.capabilities(), meta: { requestId: rid(), source: "local", timestamp: new Date().toISOString() } };
   }
 
-  /** Real operational status — components and provider intelligence. */
-  status() {
-    return this._call("GET", "/api/v1/status");
+  /** Real engine status — which adapters are operational here. */
+  async status() {
+    return { data: registry.status(), meta: { requestId: rid(), source: "local", timestamp: new Date().toISOString() } };
   }
 }