ytdlp-react-native 1.0.0

package/src/mappers.ts

@@ -0,0 +1,168 @@
+/**
+ * Mapping from the raw JSON produced by yt-dlp into the stable public types.
+ *
+ * Everything is defensive: unknown fields become `undefined`, never fake
+ * values (see AGENTS.md §11, §69, §70).
+ */
+import type { DownloadProgress, Format, Thumbnail, VideoInfo } from './types';
+
+type RawRecord = Record<string, unknown>;
+
+const NONE_CODEC = 'none';
+
+export function mapVideoInfo(raw: unknown): VideoInfo {
+  const info = asRecord(raw);
+
+  const formats = Array.isArray(info.formats) ? info.formats.map(mapFormat) : [];
+
+  const liveStatus = stringOf(info.live_status);
+  const thumbnails = normalizeThumbnails(info.thumbnails, stringOf(info.thumbnail));
+
+  return {
+    id: stringOf(info.id),
+    title: stringOf(info.title),
+    description: stringOf(info.description),
+    uploader: stringOf(info.uploader),
+    uploaderId: stringOf(info.uploader_id),
+    uploaderUrl: stringOf(info.uploader_url),
+    channel: stringOf(info.channel),
+    channelId: stringOf(info.channel_id),
+    channelUrl: stringOf(info.channel_url),
+    webpageUrl: stringOf(info.webpage_url),
+    originalUrl: stringOf(info.original_url),
+    thumbnail: firstThumbnailUrl(thumbnails) ?? stringOf(info.thumbnail),
+    thumbnails,
+    duration: numberOf(info.duration),
+    durationString: stringOf(info.duration_string),
+    uploadDate: stringOf(info.upload_date),
+    timestamp: numberOf(info.timestamp),
+    viewCount: numberOf(info.view_count),
+    likeCount: numberOf(info.like_count),
+    commentCount: numberOf(info.comment_count),
+    ageLimit: numberOf(info.age_limit),
+    isLive: liveStatus === 'is_live',
+    wasLive: liveStatus === 'was_live',
+    extractor: stringOf(info.extractor),
+    extractorKey: stringOf(info.extractor_key),
+    webpageUrlDomain: stringOf(info.webpage_url_domain),
+    formats,
+  };
+}
+
+export function mapFormat(raw: unknown): Format {
+  const format = asRecord(raw);
+  const vcodec = stringOf(format.vcodec);
+  const acodec = stringOf(format.acodec);
+  const hasVideo = vcodec !== undefined && vcodec.toLowerCase() !== NONE_CODEC;
+  const hasAudio = acodec !== undefined && acodec.toLowerCase() !== NONE_CODEC;
+
+  return {
+    id: stringOf(format.format_id) ?? stringOf(format.id) ?? '',
+    url: stringOf(format.url),
+    ext: stringOf(format.ext),
+    protocol: stringOf(format.protocol),
+    format: stringOf(format.format),
+    formatNote: stringOf(format.format_note),
+    width: numberOf(format.width),
+    height: numberOf(format.height),
+    fps: numberOf(format.fps),
+    vcodec,
+    acodec,
+    abr: numberOf(format.abr),
+    vbr: numberOf(format.vbr),
+    tbr: numberOf(format.tbr),
+    filesize: numberOf(format.filesize),
+    filesizeApprox: numberOf(format.filesize_approx),
+    quality: numberOf(format.quality),
+    audioOnly: hasAudio && !hasVideo,
+    videoOnly: hasVideo && !hasAudio,
+    hasVideo,
+    hasAudio,
+    language: stringOf(format.language),
+    container: stringOf(format.container),
+  };
+}
+
+/**
+ * Maps the raw progress payload from the native `downloadEvent` into a
+ * `DownloadProgress`, replacing any non-finite numbers with `undefined`.
+ */
+export function mapDownloadProgress(raw: unknown, taskId: string): DownloadProgress | null {
+  const progress = asRecord(raw);
+  if (!progress) return null;
+
+  const percent = numberOf(progress.percent);
+  const phaseRaw = stringOf(progress.phase);
+
+  return {
+    taskId,
+    status: statusOf(progress.status),
+    phase: phaseRaw === 'extracting' || phaseRaw === 'processing' ? phaseRaw : 'downloading',
+    percent,
+    downloadedBytes: numberOf(progress.downloadedBytes),
+    totalBytes: numberOf(progress.totalBytes),
+    speedBytesPerSecond: numberOf(progress.speedBytesPerSecond),
+    etaSeconds: numberOf(progress.etaSeconds),
+    filename: stringOf(progress.filename),
+  };
+}
+
+function statusOf(value: unknown): DownloadProgress['status'] {
+  const s = stringOf(value);
+  switch (s) {
+    case 'queued':
+    case 'extracting':
+    case 'downloading':
+    case 'processing':
+    case 'completed':
+    case 'cancelled':
+    case 'failed':
+      return s;
+    default:
+      return 'downloading';
+  }
+}
+
+function normalizeThumbnails(value: unknown, fallbackUrl?: string): Thumbnail[] {
+  const result: Thumbnail[] = [];
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const record = asRecord(item);
+      const url = stringOf(record.url);
+      if (!url) continue;
+      result.push({
+        url,
+        width: numberOf(record.width),
+        height: numberOf(record.height),
+        resolution: stringOf(record.resolution),
+        id: stringOf(record.id),
+      });
+    }
+  }
+  if (result.length === 0 && fallbackUrl) {
+    result.push({ url: fallbackUrl });
+  }
+  return result;
+}
+
+function firstThumbnailUrl(thumbnails: Thumbnail[]): string | undefined {
+  return thumbnails[0]?.url;
+}
+
+function stringOf(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.length > 0) return value;
+  return undefined;
+}
+
+function numberOf(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+    return Number(value);
+  }
+  return undefined;
+}
+
+function asRecord(value: unknown): RawRecord {
+  if (typeof value === 'object' && value !== null) return value as RawRecord;
+  return {};
+}

package/src/types.ts

@@ -0,0 +1,219 @@
+/**
+ * Public types for expo-ytdlp-native.
+ *
+ * These types are the stable contract of the package. Native details never
+ * leak into this surface (see AGENTS.md §68).
+ */
+import type { YtDlpError } from './errors';
+
+export type DownloadStatus =
+  'queued' | 'extracting' | 'downloading' | 'processing' | 'completed' | 'cancelled' | 'failed';
+
+export type DownloadPhase = 'extracting' | 'downloading' | 'processing';
+
+export interface Thumbnail {
+  url: string;
+  width?: number;
+  height?: number;
+  resolution?: string;
+  id?: string;
+}
+
+/** Normalized media information. Every field is optional except `formats`. */
+export interface VideoInfo {
+  id?: string;
+  title?: string;
+  description?: string;
+  uploader?: string;
+  uploaderId?: string;
+  uploaderUrl?: string;
+  channel?: string;
+  channelId?: string;
+  channelUrl?: string;
+  webpageUrl?: string;
+  originalUrl?: string;
+  thumbnail?: string;
+  thumbnails?: Thumbnail[];
+  duration?: number;
+  durationString?: string;
+  uploadDate?: string;
+  timestamp?: number;
+  viewCount?: number;
+  likeCount?: number;
+  commentCount?: number;
+  ageLimit?: number;
+  isLive?: boolean;
+  wasLive?: boolean;
+  extractor?: string;
+  extractorKey?: string;
+  webpageUrlDomain?: string;
+  formats: Format[];
+}
+
+/** Normalized format model. Unknown native values become `undefined`. */
+export interface Format {
+  id: string;
+  url?: string;
+  ext?: string;
+  protocol?: string;
+  format?: string;
+  formatNote?: string;
+  width?: number;
+  height?: number;
+  fps?: number;
+  vcodec?: string;
+  acodec?: string;
+  abr?: number;
+  vbr?: number;
+  tbr?: number;
+  filesize?: number;
+  filesizeApprox?: number;
+  quality?: number;
+  audioOnly: boolean;
+  videoOnly: boolean;
+  hasVideo: boolean;
+  hasAudio: boolean;
+  language?: string;
+  container?: string;
+}
+
+export interface OutputOptions {
+  /**
+   * Directory name, relative to the app-specific external storage directory.
+   * Single path segments only; `..` is rejected.
+   */
+  directory?: string;
+  /**
+   * yt-dlp output template, e.g. `%(title)s.%(ext)s`.
+   * Static parts are sanitized; template directives are preserved.
+   */
+  filename?: string;
+}
+
+export interface SubtitleOptions {
+  enabled?: boolean;
+  languages?: string[];
+  autoGenerated?: boolean;
+}
+
+export interface CookieOptions {
+  source: 'file';
+  path: string;
+}
+
+export interface NetworkOptions {
+  timeout?: number;
+  retries?: number;
+}
+
+export interface PlaylistOptions {
+  enabled?: boolean;
+  start?: number;
+  end?: number;
+}
+
+export interface ExtractOptions {
+  /** Cookies used during extraction (e.g. for login-gated sources). */
+  cookies?: CookieOptions;
+  /** Additional HTTP headers sent during extraction. Never logged. */
+  headers?: Record<string, string>;
+  /** Custom `User-Agent`. */
+  userAgent?: string;
+  proxy?: string;
+}
+
+export interface DownloadOptions {
+  url: string;
+  /** Raw yt-dlp format expression, e.g. `best`, `bestvideo+bestaudio`. */
+  format?: string;
+  output?: OutputOptions;
+  merge?: boolean;
+  subtitles?: SubtitleOptions;
+  cookies?: CookieOptions;
+  /** Additional HTTP headers. Validated; secrets are never logged. */
+  headers?: Record<string, string>;
+  userAgent?: string;
+  referer?: string;
+  proxy?: string;
+  playlist?: PlaylistOptions;
+  network?: NetworkOptions;
+}
+
+export interface DownloadProgress {
+  taskId: string;
+  status: DownloadStatus;
+  phase: DownloadPhase;
+  percent?: number;
+  downloadedBytes?: number;
+  totalBytes?: number;
+  speedBytesPerSecond?: number;
+  etaSeconds?: number;
+  filename?: string;
+}
+
+export interface DownloadResult {
+  taskId: string;
+  path?: string;
+  uri?: string;
+  filename?: string;
+  mimeType?: string;
+  size?: number;
+  duration?: number;
+}
+
+export type DownloadEventType = 'progress' | 'state' | 'completed' | 'error' | 'cancelled';
+
+export interface DownloadEvent {
+  taskId: string;
+  type: DownloadEventType;
+  status: DownloadStatus;
+  phase: DownloadPhase;
+  progress?: DownloadProgress;
+  result?: DownloadResult;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+export type DownloadStateEvent = {
+  taskId: string;
+  status: DownloadStatus;
+};
+
+export interface Subscription {
+  remove(): void;
+}
+
+export interface DownloadTask {
+  id: string;
+  cancel(): Promise<void>;
+  getStatus(): Promise<DownloadStatus>;
+  getProgress(): Promise<DownloadProgress | null>;
+  addListener(event: 'progress', listener: (progress: DownloadProgress) => void): Subscription;
+  addListener(event: 'state', listener: (state: DownloadStateEvent) => void): Subscription;
+  addListener(event: 'completed', listener: (result: DownloadResult) => void): Subscription;
+  addListener(event: 'error', listener: (error: YtDlpError) => void): Subscription;
+}
+
+export interface YtDlpVersion {
+  ytDlp: string;
+  library: string;
+}
+
+export type YtDlpErrorCode =
+  | 'INVALID_URL'
+  | 'EXTRACTION_FAILED'
+  | 'DOWNLOAD_FAILED'
+  | 'CANCELLED'
+  | 'FORMAT_UNAVAILABLE'
+  | 'NETWORK_ERROR'
+  | 'AUTHENTICATION_REQUIRED'
+  | 'GEO_RESTRICTED'
+  | 'PRIVATE_CONTENT'
+  | 'AGE_RESTRICTED'
+  | 'PROCESSING_FAILED'
+  | 'STORAGE_ERROR'
+  | 'INIT_FAILED'
+  | 'UNSUPPORTED_PLATFORM'
+  | 'UNKNOWN';