ytdlp-react-native 1.0.0

package/src/ExpoYtDlpModule.ts

@@ -0,0 +1,41 @@
+/**
+ * Thin typed binding to the native `ExpoYtDlp` module.
+ *
+ * On unsupported platforms (web/iOS) the native module is absent; we detect
+ * this here and surface it at call time as `UNSUPPORTED_PLATFORM`, so a plain
+ * import never crashes.
+ */
+import { NativeModule, requireOptionalNativeModule } from 'expo';
+
+import type { DownloadEvent, DownloadStatus } from './types';
+
+export interface DownloadTaskInfo {
+  taskId: string;
+  directory: string;
+}
+
+export interface DownloadStatusInfo {
+  taskId: string;
+  status: DownloadStatus;
+  percent?: number;
+  downloadedBytes?: number;
+  totalBytes?: number;
+  speedBytesPerSecond?: number;
+  etaSeconds?: number;
+  filename?: string;
+}
+
+export type ExpoYtDlpModuleEvents = {
+  downloadEvent: (event: DownloadEvent) => void;
+};
+
+export declare class ExpoYtDlpNativeModule extends NativeModule<ExpoYtDlpModuleEvents> {
+  getVersion(): Promise<string>;
+  extractInfo(url: string, options: Record<string, unknown>): Promise<string>;
+  startDownload(options: Record<string, unknown>): Promise<DownloadTaskInfo>;
+  cancelDownload(taskId: string): Promise<boolean>;
+  getDownloadStatus(taskId: string): Promise<DownloadStatusInfo | null>;
+}
+
+export const NativeExpoYtDlp: ExpoYtDlpNativeModule | null =
+  requireOptionalNativeModule<ExpoYtDlpNativeModule>('ExpoYtDlp');

package/src/ExpoYtDlpModule.web.ts

@@ -0,0 +1,15 @@
+import { NativeModule, registerWebModule } from 'expo';
+
+import { SUPPORTED_PLATFORM_MESSAGE } from './constants';
+
+/**
+ * Web placeholder. The package is Android-only (see AGENTS.md §3); every
+ * method throws a meaningful error instead of a silent no-op.
+ */
+class ExpoYtDlpModule extends NativeModule {
+  getVersion(): Promise<string> {
+    throw new Error(SUPPORTED_PLATFORM_MESSAGE);
+  }
+}
+
+export default registerWebModule(ExpoYtDlpModule, 'ExpoYtDlp');

package/src/YtDlp.ts

@@ -0,0 +1,151 @@
+import { NativeExpoYtDlp, type ExpoYtDlpNativeModule } from './ExpoYtDlpModule';
+import { LIBRARY_VERSION, SUPPORTED_PLATFORM_MESSAGE } from './constants';
+import { YtDlpDownloadTask } from './downloadTask';
+import { normalizeError, normalizeExtractionError, YtDlpError } from './errors';
+import { mapVideoInfo } from './mappers';
+import type {
+  CookieOptions,
+  DownloadOptions,
+  DownloadTask,
+  ExtractOptions,
+  Format,
+  VideoInfo,
+  YtDlpVersion,
+} from './types';
+
+function requireNative(): ExpoYtDlpNativeModule {
+  if (!NativeExpoYtDlp) {
+    throw new YtDlpError('UNSUPPORTED_PLATFORM', SUPPORTED_PLATFORM_MESSAGE);
+  }
+  return NativeExpoYtDlp;
+}
+
+function validateUrl(url: string | undefined): void {
+  if (!url || url.trim().length === 0) {
+    throw new YtDlpError('INVALID_URL', 'URL is required.');
+  }
+}
+
+/**
+ * Read the yt-dlp version embedded in the native runtime plus this package's
+ * version. The two are independent (see AGENTS.md §35).
+ */
+export async function getVersion(): Promise<YtDlpVersion> {
+  try {
+    const native = requireNative();
+    const ytDlp = await native.getVersion();
+    return { ytDlp, library: LIBRARY_VERSION };
+  } catch (cause) {
+    throw normalizeError(cause);
+  }
+}
+
+/**
+ * Extract normalized media information without downloading anything.
+ */
+export async function extractInfo(url: string, options?: ExtractOptions): Promise<VideoInfo> {
+  validateUrl(url);
+  try {
+    const native = requireNative();
+    const json = await native.extractInfo(url, serializeExtractOptions(options));
+    return mapVideoInfo(JSON.parse(json));
+  } catch (cause) {
+    throw normalizeExtractionError(cause);
+  }
+}
+
+/**
+ * List usable download formats. Internally reuses the same extraction as
+ * `extractInfo` to avoid redundant work (see AGENTS.md §34).
+ */
+export async function getFormats(url: string, options?: ExtractOptions): Promise<Format[]> {
+  const info = await extractInfo(url, options);
+  return info.formats;
+}
+
+/**
+ * Start a download. Resolves with a [DownloadTask] immediately; progress and
+ * the final result arrive through the task's listeners (AGENTS.md §12).
+ */
+export async function download(options: DownloadOptions): Promise<DownloadTask> {
+  validateUrl(options.url);
+  try {
+    const native = requireNative();
+    const info = await native.startDownload(serializeDownloadOptions(options));
+    return new YtDlpDownloadTask(native, info.taskId);
+  } catch (cause) {
+    throw normalizeError(cause);
+  }
+}
+
+/** Cancel a download by task id, e.g. after app re-creation (AGENTS.md §22). */
+export async function cancel(taskId: string): Promise<boolean> {
+  try {
+    const native = requireNative();
+    return await native.cancelDownload(taskId);
+  } catch (cause) {
+    throw normalizeError(cause);
+  }
+}
+
+function serializeExtractOptions(options: ExtractOptions | undefined): Record<string, unknown> {
+  if (!options) return {};
+  const out: Record<string, unknown> = {};
+  if (options.cookies) out.cookies = serializeCookies(options.cookies);
+  if (options.proxy) out.proxy = options.proxy;
+  if (options.userAgent || options.headers) {
+    const headers: Record<string, string> = { ...(options.headers ?? {}) };
+    if (options.userAgent) headers['User-Agent'] = options.userAgent;
+    out.headers = headers;
+  }
+  return out;
+}
+
+function serializeDownloadOptions(options: DownloadOptions): Record<string, unknown> {
+  const out: Record<string, unknown> = { url: options.url };
+  if (options.format) out.format = options.format;
+  if (options.output) {
+    const output: Record<string, unknown> = {};
+    if (options.output.directory) output.directory = options.output.directory;
+    if (options.output.filename) output.filename = options.output.filename;
+    if (Object.keys(output).length > 0) out.output = output;
+  }
+  if (options.merge != null) out.merge = options.merge;
+  if (options.cookies) out.cookies = serializeCookies(options.cookies);
+  if (options.userAgent || options.headers) {
+    const headers: Record<string, string> = { ...(options.headers ?? {}) };
+    if (options.userAgent) headers['User-Agent'] = options.userAgent;
+    out.headers = headers;
+  }
+  if (options.referer) out.referer = options.referer;
+  if (options.proxy) out.proxy = options.proxy;
+  if (options.playlist) {
+    const playlist: Record<string, unknown> = {};
+    if (options.playlist.enabled != null) playlist.enabled = options.playlist.enabled;
+    if (options.playlist.start != null) playlist.start = options.playlist.start;
+    if (options.playlist.end != null) playlist.end = options.playlist.end;
+    if (Object.keys(playlist).length > 0) out.playlist = playlist;
+  }
+  if (options.network) {
+    const network: Record<string, unknown> = {};
+    if (options.network.timeout != null) network.timeout = options.network.timeout;
+    if (options.network.retries != null) network.retries = options.network.retries;
+    if (Object.keys(network).length > 0) out.network = network;
+  }
+  if (options.subtitles) {
+    const subtitles: Record<string, unknown> = {};
+    if (options.subtitles.enabled != null) subtitles.enabled = options.subtitles.enabled;
+    if (options.subtitles.languages?.length) subtitles.languages = options.subtitles.languages;
+    if (options.subtitles.autoGenerated != null)
+      subtitles.autoGenerated = options.subtitles.autoGenerated;
+    if (Object.keys(subtitles).length > 0) out.subtitles = subtitles;
+  }
+  return out;
+}
+
+function serializeCookies(cookies: CookieOptions): Record<string, unknown> {
+  if (cookies.source === 'file' && cookies.path) {
+    return { path: cookies.path };
+  }
+  throw new YtDlpError('INVALID_URL', 'Cookies must reference a cookies file path.');
+}

package/src/constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Package-level constants.
+ */
+export const LIBRARY_VERSION = '0.1.0';
+
+export const SUPPORTED_PLATFORM = 'android';
+
+export const SUPPORTED_PLATFORM_MESSAGE = `${'expo-ytdlp-native'} is currently supported on ${SUPPORTED_PLATFORM} only.`;
+
+/** yt-dlp output template used when the caller does not provide a filename. */
+export const DEFAULT_FILENAME_TEMPLATE = '%(title)s.%(ext)s';

package/src/downloadTask.ts

@@ -0,0 +1,159 @@
+/**
+ * JS-side `DownloadTask` implementation.
+ *
+ * Keeps this module dependency-light: all per-task state lives in the native
+ * task registry; the JS object only relays events and forwards commands
+ * (AGENTS.md §17, §47).
+ */
+import type { DownloadStatusInfo, ExpoYtDlpNativeModule } from './ExpoYtDlpModule';
+import { YtDlpError } from './errors';
+import { attachTaskListeners } from './events';
+import type {
+  DownloadProgress,
+  DownloadResult,
+  DownloadStateEvent,
+  DownloadStatus,
+  DownloadTask,
+  Subscription,
+} from './types';
+
+type Listener<T> = (value: T) => void;
+
+interface TaskListenerSets {
+  progress: Set<Listener<DownloadProgress>>;
+  state: Set<Listener<DownloadStateEvent>>;
+  completed: Set<Listener<DownloadResult>>;
+  error: Set<Listener<YtDlpError>>;
+}
+
+export class YtDlpDownloadTask implements DownloadTask {
+  readonly id: string;
+
+  private readonly native: ExpoYtDlpNativeModule;
+  private currentStatus: DownloadStatus = 'queued';
+  private finalized = false;
+  private readonly listeners: TaskListenerSets = {
+    progress: new Set(),
+    state: new Set(),
+    completed: new Set(),
+    error: new Set(),
+  };
+  private subscriptions: Subscription[] = [];
+
+  constructor(native: ExpoYtDlpNativeModule, id: string) {
+    this.native = native;
+    this.id = id;
+    this.subscriptions = attachTaskListeners(id, {
+      progress: (progress) => {
+        this.currentStatus = progress.status;
+        this.listeners.progress.forEach((listener) => listener(progress));
+      },
+      state: (state) => {
+        this.currentStatus = state.status;
+        this.listeners.state.forEach((listener) => listener(state));
+      },
+      completed: (result) => {
+        this.finalized = true;
+        this.currentStatus = 'completed';
+        this.teardown();
+        this.listeners.completed.forEach((listener) => listener(result));
+      },
+      cancelled: () => {
+        this.finalized = true;
+        this.currentStatus = 'cancelled';
+        this.teardown();
+      },
+      error: (error) => {
+        this.finalized = true;
+        this.currentStatus = 'failed';
+        this.teardown();
+        this.listeners.error.forEach((listener) => listener(error));
+      },
+    });
+  }
+
+  async cancel(): Promise<void> {
+    await this.native.cancelDownload(this.id);
+  }
+
+  async getStatus(): Promise<DownloadStatus> {
+    if (this.finalized) return this.currentStatus;
+    const info = await this.native.getDownloadStatus(this.id);
+    if (info?.status) this.currentStatus = info.status;
+    return this.currentStatus;
+  }
+
+  async getProgress(): Promise<DownloadProgress | null> {
+    const info = await this.native.getDownloadStatus(this.id);
+    if (!info) return null;
+    return mapStatusInfo(this.id, this.currentStatus, info);
+  }
+
+  addListener(event: 'progress', listener: Listener<DownloadProgress>): Subscription;
+  addListener(event: 'state', listener: Listener<DownloadStateEvent>): Subscription;
+  addListener(event: 'completed', listener: Listener<DownloadResult>): Subscription;
+  addListener(event: 'error', listener: Listener<YtDlpError>): Subscription;
+  addListener(
+    event: 'progress' | 'state' | 'completed' | 'error',
+    listener:
+      | Listener<DownloadProgress>
+      | Listener<DownloadStateEvent>
+      | Listener<DownloadResult>
+      | Listener<YtDlpError>
+  ): Subscription {
+    const set =
+      event === 'progress'
+        ? this.listeners.progress
+        : event === 'state'
+          ? this.listeners.state
+          : event === 'completed'
+            ? this.listeners.completed
+            : this.listeners.error;
+    set.add(listener as never);
+    return {
+      remove: () => {
+        set.delete(listener as never);
+      },
+    };
+  }
+
+  private teardown() {
+    this.subscriptions.forEach((subscription) => subscription.remove());
+    this.subscriptions = [];
+  }
+}
+
+function mapStatusInfo(
+  taskId: string,
+  fallbackStatus: DownloadStatus,
+  info: DownloadStatusInfo
+): DownloadProgress {
+  return {
+    taskId,
+    status: (info.status ?? fallbackStatus) as DownloadStatus,
+    phase: phaseOf(info.status),
+    percent: finiteOrUndefined(info.percent),
+    downloadedBytes: finiteOrUndefined(info.downloadedBytes),
+    totalBytes: finiteOrUndefined(info.totalBytes),
+    speedBytesPerSecond: finiteOrUndefined(info.speedBytesPerSecond),
+    etaSeconds: finiteOrUndefined(info.etaSeconds),
+    filename: info.filename,
+  };
+}
+
+function phaseOf(status: DownloadStatus): DownloadProgress['phase'] {
+  switch (status) {
+    case 'downloading':
+      return 'downloading';
+    case 'completed':
+    case 'processing':
+      return 'processing';
+    default:
+      return 'extracting';
+  }
+}
+
+function finiteOrUndefined(value: number | undefined): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  return Number.isFinite(value) ? value : undefined;
+}

package/src/errors.ts

@@ -0,0 +1,133 @@
+import type { YtDlpErrorCode } from './types';
+
+/** Prefix used by the Kotlin layer to carry error codes across the bridge. */
+const NATIVE_PREFIX = 'YTD_NATIVE|';
+
+export class YtDlpError extends Error {
+  readonly code: YtDlpErrorCode;
+  readonly taskId?: string;
+  readonly cause?: unknown;
+
+  constructor(
+    code: YtDlpErrorCode,
+    message: string,
+    options?: { taskId?: string; cause?: unknown }
+  ) {
+    super(message);
+    this.name = 'YtDlpError';
+    this.code = code;
+    if (options?.taskId) this.taskId = options.taskId;
+    if (options?.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+/**
+ * Normalizes anything thrown by the native layer into a `YtDlpError`.
+ * Unknown/missing codes map to `UNKNOWN`; raw stack traces are never surfaced.
+ */
+export function normalizeError(
+  cause: unknown,
+  fallbackMessage = 'Unknown yt-dlp error'
+): YtDlpError {
+  if (cause instanceof YtDlpError) return cause;
+
+  if (cause instanceof Error) {
+    const parsed = parseNativeMessage(cause.message);
+    if (parsed) {
+      return new YtDlpError(parsed.code, parsed.message, { cause });
+    }
+    return new YtDlpError('UNKNOWN', cause.message || fallbackMessage, { cause });
+  }
+
+  if (typeof cause === 'string') {
+    const parsed = parseNativeMessage(cause);
+    if (parsed) return new YtDlpError(parsed.code, parsed.message);
+    return new YtDlpError('UNKNOWN', cause || fallbackMessage);
+  }
+
+  return new YtDlpError('UNKNOWN', fallbackMessage, { cause });
+}
+
+function parseNativeMessage(message: string): { code: YtDlpErrorCode; message: string } | null {
+  if (!message.startsWith(NATIVE_PREFIX)) return null;
+  const rest = message.slice(NATIVE_PREFIX.length);
+  const separator = rest.indexOf('|');
+  if (separator === -1) return null;
+  const rawCode = rest.slice(0, separator);
+  const text = rest.slice(separator + 1);
+  const code = toKnownCode(rawCode);
+  return { code, message: text || rawCode };
+}
+
+function toKnownCode(rawCode: string): YtDlpErrorCode {
+  const known: 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',
+  ];
+  if ((known as readonly string[]).includes(rawCode)) return rawCode as YtDlpErrorCode;
+  return 'UNKNOWN';
+}
+
+/**
+ * Builds a `YtDlpError` from a code+message pair received from native events.
+ * Unknown codes degrade to `UNKNOWN` (AGENTS.md §23).
+ */
+export function fromNativeCode(code: string, message: string): YtDlpError {
+  return new YtDlpError(toKnownCode(code), message);
+}
+
+/**
+ * Refines an extraction failure into a more specific code by matching the
+ * yt-dlp error message. Kept conservative: no match falls back to the
+ * normalized code.
+ */
+export function normalizeExtractionError(
+  cause: unknown,
+  fallbackMessage = 'Failed to extract media information'
+): YtDlpError {
+  const base = normalizeError(cause, fallbackMessage);
+  if (base.code !== 'EXTRACTION_FAILED' && base.code !== 'UNKNOWN') return base;
+
+  const message = base.message.toLowerCase();
+  if (
+    /http error|connection|timed out|unreachable|name or service not known|failed to establish|reset by peer|couldn't connect|503|429/.test(
+      message
+    )
+  ) {
+    return new YtDlpError('NETWORK_ERROR', base.message, { cause: base.cause });
+  }
+  if (
+    message.includes('sign in to confirm') ||
+    message.includes('log in') ||
+    message.includes('sign up')
+  ) {
+    return new YtDlpError('AUTHENTICATION_REQUIRED', base.message, { cause: base.cause });
+  }
+  if (message.includes('private') || message.includes('members-only')) {
+    return new YtDlpError('PRIVATE_CONTENT', base.message, { cause: base.cause });
+  }
+  if (message.includes('age') || message.includes('mature') || message.includes('under 18')) {
+    return new YtDlpError('AGE_RESTRICTED', base.message, { cause: base.cause });
+  }
+  if (
+    message.includes('geographic') ||
+    message.includes('geo-') ||
+    message.includes('not available in your country')
+  ) {
+    return new YtDlpError('GEO_RESTRICTED', base.message, { cause: base.cause });
+  }
+  return base;
+}

package/src/events.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared helpers for reacting to native `downloadEvent` emissions.
+ */
+import { NativeExpoYtDlp } from './ExpoYtDlpModule';
+import { fromNativeCode, type YtDlpError } from './errors';
+import type {
+  DownloadEvent,
+  DownloadProgress,
+  DownloadResult,
+  DownloadStateEvent,
+  Subscription,
+} from './types';
+
+const EVENT_NAME = 'downloadEvent';
+
+/**
+ * Returns a per-task subscription backed by the native event stream.
+ * `taskId` is used to filter events that belong to another task.
+ */
+export function subscribeToTask(
+  taskId: string,
+  handler: (event: DownloadEvent) => void
+): Subscription {
+  return subscribeToDownloadEvents((event) => {
+    if (event.taskId === taskId) {
+      handler(event);
+    }
+  });
+}
+
+export function subscribeToDownloadEvents(handler: (event: DownloadEvent) => void): Subscription {
+  if (!NativeExpoYtDlp) {
+    return { remove: () => {} };
+  }
+  // The native module is itself an EventEmitter (Expo SDK 52+); the old
+  // `new NativeEventEmitter(module)` path requires `addListener`/`removeListeners`
+  // that Expo modules do not expose.
+  const subscription = NativeExpoYtDlp.addListener(EVENT_NAME, (event: DownloadEvent) => {
+    try {
+      handler(normalizeEvent(event));
+    } catch {
+      // Never let a listener crash the JS runtime.
+    }
+  });
+  return { remove: () => subscription.remove() };
+}
+
+/**
+ * Adds task-level listeners to a [DownloadTask] from a raw subscription
+ * factory. Keeps the event filtering in one place.
+ */
+export function attachTaskListeners(
+  taskId: string,
+  listeners: {
+    progress?: (progress: DownloadProgress) => void;
+    state?: (state: DownloadStateEvent) => void;
+    completed?: (result: DownloadResult) => void;
+    cancelled?: () => void;
+    error?: (error: YtDlpError) => void;
+  }
+): Subscription[] {
+  const subs: Subscription[] = [];
+
+  subs.push(
+    subscribeToTask(taskId, (event) => {
+      switch (event.type) {
+        case 'progress':
+          if (event.progress && listeners.progress) listeners.progress(event.progress);
+          break;
+        case 'state':
+          if (listeners.state) listeners.state({ taskId: event.taskId, status: event.status });
+          break;
+        case 'completed':
+          if (event.result && listeners.completed) listeners.completed(event.result);
+          break;
+        case 'cancelled':
+          if (listeners.cancelled) listeners.cancelled();
+          if (listeners.state) listeners.state({ taskId: event.taskId, status: 'cancelled' });
+          break;
+        case 'error':
+          if (event.error) {
+            const error = fromNativeCode(event.error.code, event.error.message);
+            if (listeners.error) listeners.error(error);
+          }
+          break;
+      }
+    })
+  );
+
+  return subs;
+}
+
+function normalizeEvent(event: DownloadEvent): DownloadEvent {
+  if (event.type === 'progress' && event.progress) {
+    return {
+      ...event,
+      progress: {
+        taskId: event.taskId,
+        status: event.status,
+        phase: event.progress.phase,
+        percent: finiteOrUndefined(event.progress.percent),
+        downloadedBytes: finiteOrUndefined(event.progress.downloadedBytes),
+        totalBytes: finiteOrUndefined(event.progress.totalBytes),
+        speedBytesPerSecond: finiteOrUndefined(event.progress.speedBytesPerSecond),
+        etaSeconds: finiteOrUndefined(event.progress.etaSeconds),
+        filename: event.progress.filename,
+      },
+    };
+  }
+  return event;
+}
+
+function finiteOrUndefined(value: number | undefined): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  return Number.isFinite(value) ? value : undefined;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+import { cancel, download, extractInfo, getFormats, getVersion } from './YtDlp';
+import { YtDlpError } from './errors';
+
+export type * from './types';
+
+/** Main SDK facade. */
+export const YtDlp = {
+  getVersion,
+  extractInfo,
+  getFormats,
+  download,
+  cancel,
+};
+
+export { YtDlpError };
+
+export default YtDlp;