rn-file-toolkit 1.0.1 → 1.0.3

package/src/index.tsx

@@ -5,131 +5,60 @@ import FileToolkitSpec from './NativeFileToolkit';
 const FileToolkitModule = NativeModules.FileToolkit || FileToolkitSpec;
 const eventEmitter = new NativeEventEmitter(FileToolkitModule);
 
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/**
- * Rich progress information emitted during a download.
- * Replaces the plain `number` percent from earlier versions.
- */
 export interface ProgressInfo {
-  /** Download progress as a percentage (0–100) */
   percent: number;
-  /** Number of bytes downloaded so far */
   bytesDownloaded: number;
-  /** Total file size in bytes (0 if unknown) */
   totalBytes: number;
-  /** Current download speed in bytes per second */
   speedBps: number;
-  /** Estimated seconds remaining (0 if unknown) */
   etaSeconds: number;
 }
 
 export interface DownloadOptions {
-  /** Remote URL to download from */
   url: string;
-  /** Optional file name. Auto-detected from URL if not provided */
   fileName?: string;
-  /**
-   * Run as a background download.
-   * - iOS: uses NSURLSession background configuration
-   * - Android: uses system DownloadManager
-   * Background downloads survive app suspension. Listen to `onDownloadComplete`
-   * and `onDownloadError` events instead of awaiting the promise.
-   */
   background?: boolean;
-  /** Custom request headers (e.g. Authorization) */
   headers?: Record<string, string>;
-  /**
-   * Destination directory for the downloaded file.
-   * - 'downloads': Public Downloads folder (default)
-   * - 'cache': App-private cache directory (cleared by OS when space is low)
-   * - 'documents': App-private documents directory (persisted)
-   */
   destination?: 'downloads' | 'cache' | 'documents';
-  /** Android only: custom title for the system download notification */
   notificationTitle?: string;
-  /** Android only: custom description for the system download notification */
   notificationDescription?: string;
-  /** Optional checksum verification after download completes */
   checksum?: {
     hash: string;
     algorithm: 'md5' | 'sha1' | 'sha256';
   };
-  /** Called with rich progress info during foreground downloads */
   onProgress?: (info: ProgressInfo) => void;
-  /**
-   * Join the managed download queue instead of starting immediately.
-   * Respects the `maxConcurrent` limit set via `setQueueOptions()`.
-   * Defaults to `false`.
-   */
   queue?: boolean;
-  /**
-   * Priority inside the queue.
-   * - `'high'`: inserted at the front of the pending queue.
-   * - `'normal'` (default): appended to the back.
-   * Has no effect when `queue` is `false`.
-   */
+  downloadId?: string;
   priority?: 'high' | 'normal';
-  /**
-   * Auto-retry on network failure with exponential backoff.
-   * Only retries on network errors (timeouts, connection drops).
-   * Server errors (4xx/5xx) and checksum mismatches are NOT retried.
-   *
-   * @example
-   * ```ts
-   * download({
-   *   url: '...',
-   *   retry: {
-   *     attempts: 3,
-   *     delay: 1000,       // 1s → 2s → 4s (doubles each time, capped at 30s)
-   *     onRetry: (attempt, error) => console.log(`Retry #${attempt}: ${error}`),
-   *   }
-   * })
-   * ```
-   */
   retry?: {
-    /** Maximum number of retry attempts (default: 0 = no retry) */
     attempts: number;
-    /** Base delay in ms between retries. Doubles each attempt (default: 1000) */
     delay?: number;
-    /** Called just before each retry attempt */
     onRetry?: (attempt: number, error: string) => void;
   };
 }
 
 export interface UploadOptions {
-  /** Remote URL to upload to */
   url: string;
-  /** Absolute local path of the file to upload */
   filePath: string;
-  /** Multi-part field name for the file (default: 'file') */
   fieldName?: string;
-  /** Custom request headers */
   headers?: Record<string, string>;
-  /** Additional text parameters for the multi-part request */
   parameters?: Record<string, string>;
-  /** Called with progress 0–100 during upload */
   onProgress?: (percent: number) => void;
+  uploadId?: string;
 }
 
 export interface DownloadResult {
   success: boolean;
-  /** Local path of the saved file */
   filePath?: string;
-  /** Unique ID for this download — use with pause/resume/cancel */
   downloadId?: string;
-  /** Error message if success is false */
   error?: string;
 }
 
 export interface UploadResult {
   success: boolean;
-  /** HTTP response status code */
   status?: number;
-  /** HTTP response body as string (if any) */
   data?: string;
-  /** Error message if success is false */
   error?: string;
+  uploadId?: string;
 }
 
 export interface ActionResult {
@@ -140,9 +69,7 @@ export interface ActionResult {
 export interface CachedFile {
   fileName: string;
   filePath: string;
-  /** File size in bytes */
   size: number;
-  /** Last-modified timestamp in milliseconds */
   modifiedAt: number;
 }
 
@@ -153,91 +80,59 @@ export interface CacheResult {
 }
 
 export interface SaveBase64Options {
-  /**
-   * Base64 string or data URI (e.g., "data:image/png;base64,iVBORw0...")
-   * If a data URI is provided, the base64 portion will be extracted automatically.
-   */
   base64Data: string;
-  /** Optional file name. Auto-generated if not provided */
   fileName?: string;
-  /**
-   * Destination directory for the saved file.
-   * - 'downloads': Public Downloads folder (default)
-   * - 'cache': App-private cache directory
-   * - 'documents': App-private documents directory
-   */
   destination?: 'downloads' | 'cache' | 'documents';
 }
 
 export interface SaveBase64Result {
   success: boolean;
-  /** Local path of the saved file */
   filePath?: string;
-  /** Error message if success is false */
   error?: string;
 }
 
 export interface UrlToBase64Options {
-  /** URL of the file to convert to base64 (image, video, gif, etc.) */
   url: string;
-  /** Optional custom headers (e.g., Authorization) */
   headers?: Record<string, string>;
 }
 
 export interface UrlToBase64Result {
   success: boolean;
-  /** Base64-encoded string */
   base64?: string;
-  /** MIME type detected from response (e.g., 'image/png') */
   mimeType?: string;
-  /** Complete data URI (e.g., 'data:image/png;base64,...') */
   dataUri?: string;
-  /** Error message if success is false */
   error?: string;
 }
 
 export interface ShareFileOptions {
-  /** Absolute path to the file to share */
   filePath: string;
-  /** Optional title for the share dialog (Android only) */
   title?: string;
-  /** Optional subject for email sharing (Android only) */
   subject?: string;
 }
 
 export interface OpenFileOptions {
-  /** Absolute path to the file to open */
   filePath: string;
-  /** MIME type of the file (e.g., 'application/pdf', 'image/jpeg'). Auto-detected if not provided. */
   mimeType?: string;
 }
 
 export interface ShareFileResult {
   success: boolean;
-  /** Whether user completed the share action (iOS only) */
   completed?: boolean;
-  /** Error message if success is false */
   error?: string;
 }
 
 export interface OpenFileResult {
   success: boolean;
-  /** Error message if success is false */
   error?: string;
 }
 
 export type FsEncoding = 'utf8' | 'base64';
 
 export interface FsStat {
-  /** Absolute path */
   path: string;
-  /** Basename */
   name: string;
-  /** Size in bytes (0 for directories) */
   size: number;
-  /** Last modified timestamp in milliseconds */
   modified: number;
-  /** Whether path is a directory */
   isDir: boolean;
 }
 
@@ -257,22 +152,13 @@ export interface FsApi {
   ls: (dirPath: string) => Promise<string[]>;
 }
 
-// ─── Queue ───────────────────────────────────────────────────────────────────
-
 export interface QueueOptions {
-  /**
-   * Maximum number of simultaneous downloads when using the managed queue.
-   * Defaults to `3`.
-   */
   maxConcurrent?: number;
 }
 
 export interface QueueStatus {
-  /** Number of downloads actively running right now */
   active: number;
-  /** Number of downloads waiting in the queue */
   pending: number;
-  /** Current `maxConcurrent` setting */
   maxConcurrent: number;
 }
 
@@ -290,7 +176,6 @@ class DownloadQueue {
   setOptions(opts: QueueOptions): void {
     if (opts.maxConcurrent != null && opts.maxConcurrent > 0) {
       this._maxConcurrent = opts.maxConcurrent;
-      // Kick off any slots that just opened.
       this._flush();
     }
   }
@@ -319,7 +204,6 @@ class DownloadQueue {
     while (this._active < this._maxConcurrent && this._queue.length > 0) {
       const item = this._queue.shift()!;
       this._active++;
-      // Strip queue-specific fields before passing to the native layer.
       const nativeOptions = { ...item.options };
       delete nativeOptions.queue;
       delete nativeOptions.priority;
@@ -340,123 +224,71 @@ class DownloadQueue {
 
 const _globalQueue = new DownloadQueue();
 
-/**
- * Configure the global managed download queue.
- *
- * @example
- * ```ts
- * setQueueOptions({ maxConcurrent: 3 });
- * ```
- */
+function _generateId(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
 export function setQueueOptions(options: QueueOptions): void {
   _globalQueue.setOptions(options);
 }
 
-/**
- * Get the current state of the managed download queue.
- *
- * @example
- * ```ts
- * const { active, pending, maxConcurrent } = getQueueStatus();
- * ```
- */
 export function getQueueStatus(): QueueStatus {
   return _globalQueue.getStatus();
 }
 
-// ─── Core download ────────────────────────────────────────────────────────────
-
-/**
- * Core native download executor — used internally by `download()` and the queue.
- * Never routes through the queue.
- */
 async function _executeDownload(
   options: DownloadOptions
 ): Promise<DownloadResult> {
-  let progressSubscription: ReturnType<typeof eventEmitter.addListener> | null =
-    null;
-  let retrySubscription: ReturnType<typeof eventEmitter.addListener> | null =
-    null;
-
-  // downloadId is resolved immediately on Android foreground, allowing
-  // ID-based event filtering. On iOS it only arrives on completion, so we
-  // fall back to URL-based filtering in that case.
-  let knownDownloadId: string | null = null;
-
-  // Speed / ETA tracking (JS-side, works regardless of native platform)
+  let progressSubscription: any = null;
+  let retrySubscription: any = null;
+  const downloadId = options.downloadId || _generateId();
+  const knownDownloadId: string = downloadId;
   let _lastProgressTs: number | null = null;
   let _lastProgressBytes: number = 0;
-  // Smoothed speed using exponential moving average (α = 0.3)
   let _smoothedSpeedBps: number = 0;
 
   if (options.onProgress) {
     progressSubscription = eventEmitter.addListener(
       'onDownloadProgress',
       (event: any) => {
-        const matchesId =
-          knownDownloadId && event.downloadId === knownDownloadId;
-        const matchesUrl = !knownDownloadId && event.url === options.url;
+        const matchesId = event.downloadId === knownDownloadId;
+        const matchesUrl = !event.downloadId && event.url === options.url;
         if ((matchesId || matchesUrl) && options.onProgress) {
           const now = Date.now();
-          const percent: number = event.progress ?? 0;
-          const bytesDownloaded: number = event.bytesDownloaded ?? 0;
-          const totalBytes: number = event.totalBytes ?? 0;
-
+          const percent = event.progress ?? 0;
+          const bytesDownloaded = event.bytesDownloaded ?? 0;
+          const totalBytes = event.totalBytes ?? 0;
           let speedBps = 0;
           let etaSeconds = 0;
-
           if (_lastProgressTs !== null) {
             const dtSec = (now - _lastProgressTs) / 1000;
             if (dtSec > 0) {
               const bytesDelta = bytesDownloaded - _lastProgressBytes;
-              // Only update speed if we have byte-level data from native
               if (bytesDelta > 0 && totalBytes > 0) {
                 const instantSpeed = bytesDelta / dtSec;
-                // Exponential moving average for smoother readings
                 _smoothedSpeedBps =
                   _smoothedSpeedBps === 0
                     ? instantSpeed
                     : 0.3 * instantSpeed + 0.7 * _smoothedSpeedBps;
                 speedBps = _smoothedSpeedBps;
-                const remaining = totalBytes - bytesDownloaded;
-                etaSeconds = speedBps > 0 ? remaining / speedBps : 0;
-              } else if (percent > 0 && percent < 100) {
-                // Fallback: estimate from percent when bytes aren't available
-                const estimatedTotalBytes =
-                  totalBytes > 0
-                    ? totalBytes
-                    : _lastProgressBytes / (percent / 100);
-                const percentDelta =
-                  percent - (_lastProgressBytes / estimatedTotalBytes) * 100;
-                if (percentDelta > 0) {
-                  const estimatedByteDelta =
-                    (percentDelta / 100) * estimatedTotalBytes;
-                  const instantSpeed = estimatedByteDelta / dtSec;
-                  _smoothedSpeedBps =
-                    _smoothedSpeedBps === 0
-                      ? instantSpeed
-                      : 0.3 * instantSpeed + 0.7 * _smoothedSpeedBps;
-                  speedBps = _smoothedSpeedBps;
-                  const remainingPct = 100 - percent;
-                  const estimatedRemaining =
-                    (remainingPct / 100) * estimatedTotalBytes;
-                  etaSeconds = speedBps > 0 ? estimatedRemaining / speedBps : 0;
-                }
+                etaSeconds =
+                  speedBps > 0 ? (totalBytes - bytesDownloaded) / speedBps : 0;
               }
             }
           }
-
           _lastProgressTs = now;
           _lastProgressBytes = bytesDownloaded;
-
-          const info: ProgressInfo = {
+          options.onProgress!({
             percent,
             bytesDownloaded,
             totalBytes,
             speedBps,
             etaSeconds,
-          };
-          options.onProgress(info);
+          });
         }
       }
     );
@@ -466,9 +298,8 @@ async function _executeDownload(
     retrySubscription = eventEmitter.addListener(
       'onDownloadRetry',
       (event: any) => {
-        const matchesId =
-          knownDownloadId && event.downloadId === knownDownloadId;
-        const matchesUrl = !knownDownloadId && event.url === options.url;
+        const matchesId = event.downloadId === knownDownloadId;
+        const matchesUrl = !event.downloadId && event.url === options.url;
         if ((matchesId || matchesUrl) && options.retry?.onRetry) {
           options.retry.onRetry(event.attempt, event.error ?? '');
         }
@@ -482,35 +313,13 @@ async function _executeDownload(
   };
 
   try {
-    const resultPromise = (FileToolkitSpec as any).download({
-      url: options.url,
-      fileName: options.fileName,
+    const result = await (FileToolkitModule as any).download({
+      ...options,
+      downloadId,
       background: options.background ?? false,
       headers: options.headers ?? {},
       destination: options.destination ?? 'downloads',
-      notificationTitle: options.notificationTitle,
-      notificationDescription: options.notificationDescription,
-      checksum: options.checksum,
-      retry: options.retry
-        ? {
-            attempts: options.retry.attempts,
-            delay: options.retry.delay ?? 1000,
-          }
-        : undefined,
-    });
-
-    // On Android foreground the promise resolves immediately with downloadId,
-    // giving us a precise ID to filter events by before download completes.
-    // On iOS it only resolves on completion, so knownDownloadId stays null
-    // and URL-based filtering is used as the fallback.
-    resultPromise.then?.((partial: any) => {
-      if (partial?.downloadId && !partial?.filePath) {
-        // Android early-resolve: has downloadId but no filePath yet
-        knownDownloadId = partial.downloadId;
-      }
     });
-
-    const result = await resultPromise;
     cleanup();
     return result as DownloadResult;
   } catch (error: any) {
@@ -519,277 +328,146 @@ async function _executeDownload(
   }
 }
 
-/**
- * Download a file.
- *
- * For **foreground** downloads the promise resolves when the file is saved.
- * For **background** downloads the promise resolves immediately with a
- * `downloadId`; listen to the `onDownloadComplete` / `onDownloadError`
- * events for the final result.
- *
- * Pass `queue: true` to join the managed queue and respect the `maxConcurrent`
- * limit configured via `setQueueOptions()`. Use `priority: 'high'` to jump
- * ahead of other pending items in the queue.
- *
- * @example
- * ```ts
- * // Direct (unqueued) download
- * const result = await download({ url: 'https://...' });
- *
- * // Queued download with high priority
- * setQueueOptions({ maxConcurrent: 3 });
- * const result = await download({
- *   url: 'https://...',
- *   queue: true,
- *   priority: 'high',
- * });
- * ```
- */
 export function download(options: DownloadOptions): Promise<DownloadResult> {
-  if (options.queue) {
-    return _globalQueue.enqueue(options);
-  }
+  if (options.queue) return _globalQueue.enqueue(options);
   return _executeDownload(options);
 }
 
-// ─── Core upload ───────────────────────────────────────────────────────────────
-
-/**
- * Upload a file using multipart/form-data.
- */
 export async function upload(options: UploadOptions): Promise<UploadResult> {
-  let progressSubscription: ReturnType<typeof eventEmitter.addListener> | null =
-    null;
-
+  let sub: any = null;
+  const uploadId = options.uploadId || _generateId();
   if (options.onProgress) {
-    progressSubscription = eventEmitter.addListener(
-      'onUploadProgress',
-      (event: any) => {
-        if (event.url === options.url && options.onProgress) {
-          options.onProgress(event.progress);
-        }
-      }
-    );
+    sub = eventEmitter.addListener('onUploadProgress', (e: any) => {
+      if (e.uploadId === uploadId) options.onProgress!(e.progress);
+    });
   }
-
   try {
-    const result = await (FileToolkitSpec as any).upload({
-      url: options.url,
-      filePath: options.filePath,
+    const res = await (FileToolkitModule as any).upload({
+      ...options,
+      uploadId,
       fieldName: options.fieldName ?? 'file',
       headers: options.headers ?? {},
       parameters: options.parameters ?? {},
     });
-
-    if (progressSubscription) {
-      progressSubscription.remove();
-    }
-
-    return result as UploadResult;
-  } catch (error: any) {
-    if (progressSubscription) {
-      progressSubscription.remove();
-    }
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    sub?.remove();
+    return { ...res, uploadId } as UploadResult;
+  } catch (err: any) {
+    sub?.remove();
+    return { success: false, error: err?.message || 'UNKNOWN_ERROR', uploadId };
   }
 }
 
-// ─── Pause / Resume / Cancel ──────────────────────────────────────────────────
-
-/**
- * Pause an active foreground download.
- * On iOS the partial data is stored so it can be resumed.
- * On Android the download thread is suspended.
- */
-export async function pauseDownload(downloadId: string): Promise<ActionResult> {
+export async function pauseDownload(id: string): Promise<ActionResult> {
   try {
-    return (await (FileToolkitSpec as any).pauseDownload(
-      downloadId
-    )) as ActionResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).pauseDownload(id);
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-/**
- * Resume a previously paused download.
- * On iOS resumes from partial data (HTTP Range). On Android unblocks the thread.
- */
-export async function resumeDownload(
-  downloadId: string
-): Promise<ActionResult> {
+export async function resumeDownload(id: string): Promise<ActionResult> {
   try {
-    return (await (FileToolkitSpec as any).resumeDownload(
-      downloadId
-    )) as ActionResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).resumeDownload(id);
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-/**
- * Cancel and discard a download (foreground or background).
- * Any partially-downloaded file is deleted.
- */
-export async function cancelDownload(
-  downloadId: string
-): Promise<ActionResult> {
+export async function cancelDownload(id: string): Promise<ActionResult> {
   try {
-    return (await (FileToolkitSpec as any).cancelDownload(
-      downloadId
-    )) as ActionResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).cancelDownload(id);
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-// ─── Cache management ─────────────────────────────────────────────────────────
-
-/**
- * List all files in the app's cache directory.
- */
 export async function getCachedFiles(): Promise<CacheResult> {
   try {
-    return (await (FileToolkitSpec as any).getCachedFiles()) as CacheResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).getCachedFiles();
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-/**
- * Delete a single file by its absolute path.
- */
-export async function deleteFile(filePath: string): Promise<ActionResult> {
+export async function deleteFile(path: string): Promise<ActionResult> {
   try {
-    return (await (FileToolkitSpec as any).deleteFile(
-      filePath
-    )) as ActionResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).deleteFile(path);
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-/**
- * Delete all files in the app's cache directory.
- */
 export async function clearCache(): Promise<ActionResult> {
   try {
-    return (await (FileToolkitSpec as any).clearCache()) as ActionResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).clearCache();
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-/**
- * Get all active background downloads.
- * Use this after app restart to "re-attach" to ongoing downloads.
- */
-export async function getBackgroundDownloads(): Promise<{
-  success: boolean;
-  downloads?: Array<{
-    downloadId: string;
-    url: string;
-    status: number;
-    progress: number;
-  }>;
-  error?: string;
-}> {
+export async function getBackgroundDownloads(): Promise<any> {
   try {
-    return (await (FileToolkitSpec as any).getBackgroundDownloads()) as any;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await (FileToolkitModule as any).getBackgroundDownloads();
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-// ─── File system helpers ─────────────────────────────────────────────────────
-
-function _ensureFsSuccess(result: any, fallback: string): void {
-  if (!result?.success) {
-    throw new Error(result?.error || fallback);
-  }
+function _ensure(res: any, msg: string) {
+  if (!res?.success) throw new Error(res?.error || msg);
 }
 
-/** Check whether a file or directory exists. */
-export async function exists(filePath: string): Promise<boolean> {
-  const result = await (FileToolkitSpec as any).exists(filePath);
-  _ensureFsSuccess(result, 'EXISTS_ERROR');
-  return !!result.exists;
+export async function exists(path: string): Promise<boolean> {
+  const res = await (FileToolkitModule as any).exists(path);
+  _ensure(res, 'EXISTS_ERROR');
+  return !!res.exists;
 }
 
-/** Get file or directory metadata. */
-export async function stat(filePath: string): Promise<FsStat> {
-  const result = await (FileToolkitSpec as any).stat(filePath);
-  _ensureFsSuccess(result, 'STAT_ERROR');
-  return result.stat as FsStat;
+export async function stat(path: string): Promise<FsStat> {
+  const res = await (FileToolkitModule as any).stat(path);
+  _ensure(res, 'STAT_ERROR');
+  return res.stat;
 }
 
-/** Read a file as utf8 (default) or base64 string. */
 export async function readFile(
-  filePath: string,
-  encoding: FsEncoding = 'utf8'
+  path: string,
+  enc: FsEncoding = 'utf8'
 ): Promise<string> {
-  const result = await (FileToolkitSpec as any).readFile(filePath, encoding);
-  _ensureFsSuccess(result, 'READ_FILE_ERROR');
-  return result.data ?? '';
+  const res = await (FileToolkitModule as any).readFile(path, enc);
+  _ensure(res, 'READ_ERROR');
+  return res.data ?? '';
 }
 
-/** Write utf8 (default) or base64 data to a file. */
 export async function writeFile(
-  filePath: string,
+  path: string,
   data: string,
-  encoding: FsEncoding = 'utf8'
+  enc: FsEncoding = 'utf8'
 ): Promise<void> {
-  const result = await (FileToolkitSpec as any).writeFile(
-    filePath,
-    data,
-    encoding
-  );
-  _ensureFsSuccess(result, 'WRITE_FILE_ERROR');
+  const res = await (FileToolkitModule as any).writeFile(path, data, enc);
+  _ensure(res, 'WRITE_ERROR');
 }
 
-/** Copy a file from source to destination. */
-export async function copyFile(
-  fromPath: string,
-  toPath: string
-): Promise<void> {
-  const result = await (FileToolkitSpec as any).copyFile(fromPath, toPath);
-  _ensureFsSuccess(result, 'COPY_FILE_ERROR');
+export async function copyFile(from: string, to: string): Promise<void> {
+  const res = await (FileToolkitModule as any).copyFile(from, to);
+  _ensure(res, 'COPY_ERROR');
 }
 
-/** Move a file from source to destination. */
-export async function moveFile(
-  fromPath: string,
-  toPath: string
-): Promise<void> {
-  const result = await (FileToolkitSpec as any).moveFile(fromPath, toPath);
-  _ensureFsSuccess(result, 'MOVE_FILE_ERROR');
+export async function moveFile(from: string, to: string): Promise<void> {
+  const res = await (FileToolkitModule as any).moveFile(from, to);
+  _ensure(res, 'MOVE_ERROR');
 }
 
-/** Create a directory recursively. */
-export async function mkdir(dirPath: string): Promise<void> {
-  const result = await (FileToolkitSpec as any).mkdir(dirPath);
-  _ensureFsSuccess(result, 'MKDIR_ERROR');
+export async function mkdir(path: string): Promise<void> {
+  const res = await (FileToolkitModule as any).mkdir(path);
+  _ensure(res, 'MKDIR_ERROR');
 }
 
-/** List direct entries (names) in a directory. */
-export async function ls(dirPath: string): Promise<string[]> {
-  const result = await (FileToolkitSpec as any).ls(dirPath);
-  _ensureFsSuccess(result, 'LS_ERROR');
-  return (result.entries || []) as string[];
+export async function ls(path: string): Promise<string[]> {
+  const res = await (FileToolkitModule as any).ls(path);
+  _ensure(res, 'LS_ERROR');
+  return res.entries || [];
 }
 
-/**
- * File system API namespace.
- *
- * @example
- * ```ts
- * import { fs } from 'rn-file-toolkit';
- *
- * const ok = await fs.exists('/path/to/file.pdf');
- * const meta = await fs.stat('/path/to/file.pdf');
- * const text = await fs.readFile('/path/to/file.txt');
- * ```
- */
 export const fs: FsApi = {
   exists,
   stat,
@@ -797,454 +475,170 @@ export const fs: FsApi = {
   writeFile,
   copyFile,
   moveFile,
-  deleteFile: async (filePath: string) => {
-    const result = await deleteFile(filePath);
-    _ensureFsSuccess(result, 'DELETE_FILE_ERROR');
+  deleteFile: async (p) => {
+    _ensure(await deleteFile(p), 'DEL_ERROR');
   },
   mkdir,
   ls,
 };
 
-// ─── Event helpers ────────────────────────────────────────────────────────────
-
-/**
- * Subscribe to background download completion events.
- * Returns an unsubscribe function.
- */
-export function onDownloadComplete(
-  callback: (result: DownloadResult) => void
-): () => void {
-  const sub = eventEmitter.addListener('onDownloadComplete', callback as any);
-  return () => sub.remove();
+export function onDownloadComplete(cb: any) {
+  const s = eventEmitter.addListener('onDownloadComplete', cb);
+  return () => s.remove();
 }
-
-/**
- * Subscribe to background download error events.
- * Returns an unsubscribe function.
- */
-export function onDownloadError(
-  callback: (result: DownloadResult) => void
-): () => void {
-  const sub = eventEmitter.addListener('onDownloadError', callback as any);
-  return () => sub.remove();
+export function onDownloadError(cb: any) {
+  const s = eventEmitter.addListener('onDownloadError', cb);
+  return () => s.remove();
 }
-
-/**
- * Subscribe to upload progress events.
- * Returns an unsubscribe function.
- */
-export function onUploadProgress(
-  callback: (result: { url: string; progress: number }) => void
-): () => void {
-  const sub = eventEmitter.addListener('onUploadProgress', callback as any);
-  return () => sub.remove();
+export function onUploadProgress(cb: any) {
+  const s = eventEmitter.addListener('onUploadProgress', cb);
+  return () => s.remove();
 }
-
-/**
- * Subscribe to download retry events (fired before each retry attempt).
- * Returns an unsubscribe function.
- */
-export function onDownloadRetry(
-  callback: (result: {
-    downloadId: string;
-    url: string;
-    attempt: number;
-  }) => void
-): () => void {
-  const sub = eventEmitter.addListener('onDownloadRetry', callback as any);
-  return () => sub.remove();
+export function onDownloadRetry(cb: any) {
+  const s = eventEmitter.addListener('onDownloadRetry', cb);
+  return () => s.remove();
 }
 
-// ─── saveBase64AsFile ─────────────────────────────────────────────────────────
-
-/**
- * Save a base64 string or data URI as a file.
- * Supports data URIs (e.g., "data:image/png;base64,iVBORw0...") and plain base64 strings.
- *
- * @example
- * ```typescript
- * // From data URI
- * const result = await saveBase64AsFile({
- *   base64Data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...',
- *   fileName: 'photo.png',
- *   destination: 'documents'
- * });
- *
- * // From plain base64
- * const result = await saveBase64AsFile({
- *   base64Data: 'SGVsbG8gV29ybGQ=',
- *   fileName: 'hello.txt',
- *   destination: 'cache'
- * });
- * ```
- */
 export async function saveBase64AsFile(
-  options: SaveBase64Options
+  opts: SaveBase64Options
 ): Promise<SaveBase64Result> {
   try {
-    let { base64Data, fileName, destination } = options;
-
-    // Parse data URI if present (e.g., "data:image/png;base64,iVBORw0...")
+    let { base64Data, fileName, destination } = opts;
     if (base64Data.startsWith('data:')) {
-      const matches = base64Data.match(/^data:([^;]+);base64,(.+)$/);
-      if (matches && matches[2]) {
-        base64Data = matches[2];
-
-        // Auto-detect file extension from MIME type if fileName not provided
-        if (!fileName && matches[1]) {
-          const mimeType = matches[1];
-          const ext = mimeType.split('/')[1] || 'bin';
-          fileName = `file_${Date.now()}.${ext}`;
-        }
-      } else {
-        return {
-          success: false,
-          error:
-            'Invalid data URI format. Expected: data:<mimetype>;base64,<data>',
-        };
+      const m = base64Data.match(/^data:([^;]+);base64,(.+)$/);
+      if (m && m[2]) {
+        base64Data = m[2];
+        if (!fileName && m[1])
+          fileName = `file_${Date.now()}.${m[1].split('/')[1] || 'bin'}`;
       }
     }
-
-    const result = await FileToolkitModule.saveBase64AsFile({
+    return await FileToolkitModule.saveBase64AsFile({
       base64Data,
       fileName,
       destination,
     });
-
-    return result as SaveBase64Result;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-// ─── urlToBase64 ──────────────────────────────────────────────────────────────
-
-/**
- * Convert a web URL (image, video, gif, etc.) to base64 string.
- * Downloads the file and returns both the base64 string and data URI format.
- *
- * @example
- * ```typescript
- * // Convert image to base64
- * const result = await urlToBase64({
- *   url: 'https://example.com/photo.jpg',
- *   headers: { Authorization: 'Bearer token' }
- * });
- *
- * if (result.success) {
- *   console.log('Base64:', result.base64);
- *   console.log('Data URI:', result.dataUri);
- *   console.log('MIME Type:', result.mimeType);
- * }
- * ```
- */
 export async function urlToBase64(
-  options: UrlToBase64Options
+  opts: UrlToBase64Options
 ): Promise<UrlToBase64Result> {
   try {
-    const result = await FileToolkitModule.urlToBase64({
-      url: options.url,
-      headers: options.headers,
-    });
-
-    return result as UrlToBase64Result;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await FileToolkitModule.urlToBase64(opts);
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-// ─── shareFile ────────────────────────────────────────────────────────────────
-
-/**
- * Share a file with other apps using the native share dialog.
- * Opens the system share sheet on iOS and share chooser on Android.
- *
- * @example
- * ```typescript
- * const result = await shareFile({
- *   filePath: '/path/to/document.pdf',
- *   title: 'Share Document',
- *   subject: 'Check out this file'
- * });
- *
- * if (result.success) {
- *   console.log('File shared successfully');
- * }
- * ```
- */
 export async function shareFile(
-  options: ShareFileOptions
+  opts: ShareFileOptions
 ): Promise<ShareFileResult> {
   try {
-    const result = await FileToolkitModule.shareFile(options.filePath, {
-      title: options.title,
-      subject: options.subject,
+    return await FileToolkitModule.shareFile(opts.filePath, {
+      title: opts.title,
+      subject: opts.subject,
     });
-
-    return result as ShareFileResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-// ─── openFile ─────────────────────────────────────────────────────────────────
-
-/**
- * Open a file with the default app or app chooser.
- * On iOS, displays a preview or shows apps that can handle the file.
- * On Android, opens with the default app or shows app chooser.
- *
- * @example
- * ```typescript
- * const result = await openFile({
- *   filePath: '/path/to/document.pdf',
- *   mimeType: 'application/pdf' // optional, auto-detected if not provided
- * });
- *
- * if (result.success) {
- *   console.log('File opened successfully');
- * }
- * ```
- */
-export async function openFile(
-  options: OpenFileOptions
-): Promise<OpenFileResult> {
+export async function openFile(opts: OpenFileOptions): Promise<OpenFileResult> {
   try {
-    const result = await FileToolkitModule.openFile(
-      options.filePath,
-      options.mimeType || ''
-    );
-
-    return result as OpenFileResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNKNOWN_ERROR' };
+    return await FileToolkitModule.openFile(opts.filePath, opts.mimeType || '');
+  } catch (err: any) {
+    return { success: false, error: err.message || 'UNKNOWN_ERROR' };
   }
 }
 
-// ─── Zip / Unzip ─────────────────────────────────────────────────────────────
-
 export interface UnzipResult {
   success: boolean;
-  /** Absolute path of the destination directory */
   destDir?: string;
-  /** List of absolute paths of all extracted files */
   files?: string[];
-  /** Error message if success is false */
   error?: string;
 }
 
 export interface ZipResult {
   success: boolean;
-  /** Absolute path of the created zip archive */
   zipPath?: string;
-  /** Error message if success is false */
   error?: string;
 }
 
-/**
- * Extract a ZIP archive to a destination directory.
- *
- * Uses `java.util.zip` on Android and zlib (system framework) on iOS.
- * No third-party dependency required.
- *
- * @param sourcePath Absolute path to the `.zip` file
- * @param destDir    Absolute path to the directory where files will be extracted.
- *                   The directory is created automatically if it does not exist.
- *
- * @example
- * ```ts
- * const result = await unzip(
- *   '/path/to/archive.zip',
- *   '/path/to/output-folder'
- * );
- *
- * if (result.success) {
- *   console.log('Extracted files:', result.files);
- * }
- * ```
- */
-export async function unzip(
-  sourcePath: string,
-  destDir: string
-): Promise<UnzipResult> {
+export async function unzip(s: string, d: string): Promise<UnzipResult> {
   try {
-    const result = await (FileToolkitSpec as any).unzip(sourcePath, destDir);
-    return result as UnzipResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'UNZIP_ERROR' };
+    return await (FileToolkitModule as any).unzip(s, d);
+  } catch {
+    return { success: false, error: 'UNZIP_ERROR' };
   }
 }
 
-/**
- * Create a ZIP archive from a file or directory.
- *
- * Uses `java.util.zip` on Android and zlib (system framework) on iOS.
- * No third-party dependency required.
- *
- * @param sourcePath Absolute path to the file or directory to compress
- * @param destPath   Absolute path for the output `.zip` file.
- *                   Parent directory is created automatically if needed.
- *
- * @example
- * ```ts
- * // Zip a single file
- * const result = await zip(
- *   '/path/to/document.pdf',
- *   '/path/to/document.zip'
- * );
- *
- * // Zip an entire directory
- * const result = await zip(
- *   '/path/to/my-folder',
- *   '/path/to/my-folder.zip'
- * );
- *
- * if (result.success) {
- *   console.log('Archive created at:', result.zipPath);
- * }
- * ```
- */
-export async function zip(
-  sourcePath: string,
-  destPath: string
-): Promise<ZipResult> {
+export async function zip(s: string, d: string): Promise<ZipResult> {
   try {
-    const result = await (FileToolkitSpec as any).zip(sourcePath, destPath);
-    return result as ZipResult;
-  } catch (error: any) {
-    return { success: false, error: error?.message || 'ZIP_ERROR' };
+    return await (FileToolkitModule as any).zip(s, d);
+  } catch {
+    return { success: false, error: 'ZIP_ERROR' };
   }
 }
 
-// ─── useDownload hook ─────────────────────────────────────────────────────────
-
-export type DownloadStatus =
-  | 'idle'
-  | 'downloading'
-  | 'paused'
-  | 'done'
-  | 'error';
-
 export interface UseDownloadReturn {
-  /** Start a download. Resolves with the final result. */
   start: (options: DownloadOptions) => Promise<DownloadResult>;
-  /** Pause the current download */
   pause: () => Promise<void>;
-  /** Resume the current download */
   resume: () => Promise<void>;
-  /** Cancel the current download */
   cancel: () => Promise<void>;
-  /** Current status of the download */
-  status: DownloadStatus;
-  /** Rich progress information (null until first progress event) */
+  status: 'idle' | 'downloading' | 'paused' | 'done' | 'error';
   progress: ProgressInfo | null;
-  /** Final result once download completes or fails */
   result: DownloadResult | null;
-  /** The active download ID (available after download starts) */
   downloadId: string | null;
 }
 
-/**
- * React hook for managing a single download with built-in state.
- *
- * Tracks status, rich progress (percent, speed, ETA), and the final result.
- * Exposes `pause`, `resume`, and `cancel` controls tied to the active download.
- *
- * @example
- * ```tsx
- * function DownloadButton() {
- *   const { start, pause, resume, cancel, status, progress, result } = useDownload();
- *
- *   return (
- *     <View>
- *       <Button
- *         title="Download"
- *         onPress={() => start({ url: 'https://example.com/file.zip' })}
- *       />
- *
- *       {status === 'downloading' && progress && (
- *         <View>
- *           <Text>{progress.percent.toFixed(1)}%</Text>
- *           <Text>Speed: {(progress.speedBps / 1024).toFixed(1)} KB/s</Text>
- *           <Text>ETA: {progress.etaSeconds.toFixed(0)}s</Text>
- *           <ProgressBar value={progress.percent / 100} />
- *           <Button title="Pause" onPress={pause} />
- *         </View>
- *       )}
- *
- *       {status === 'paused' && (
- *         <Button title="Resume" onPress={resume} />
- *       )}
- *
- *       {status === 'done' && result?.success && (
- *         <Text>Saved to: {result.filePath}</Text>
- *       )}
- *
- *       {status === 'error' && (
- *         <Text>Error: {result?.error}</Text>
- *       )}
- *     </View>
- *   );
- * }
- * ```
- */
 export function useDownload(): UseDownloadReturn {
-  const [status, setStatus] = useState<DownloadStatus>('idle');
+  const [status, setStatus] = useState<any>('idle');
   const [progress, setProgress] = useState<ProgressInfo | null>(null);
   const [result, setResult] = useState<DownloadResult | null>(null);
   const [downloadId, setDownloadId] = useState<string | null>(null);
   const downloadIdRef = useRef<string | null>(null);
 
-  const start = useCallback(
-    async (options: DownloadOptions): Promise<DownloadResult> => {
-      setStatus('downloading');
-      setProgress(null);
-      setResult(null);
-      setDownloadId(null);
-      downloadIdRef.current = null;
-
-      const res = await download({
-        ...options,
-        onProgress: (info: ProgressInfo) => {
-          setProgress(info);
-          options.onProgress?.(info);
-        },
-      });
-
-      if (res.downloadId) {
-        downloadIdRef.current = res.downloadId;
-        setDownloadId(res.downloadId);
-      }
+  const start = useCallback(async (opts: DownloadOptions) => {
+    const id = opts.downloadId || _generateId();
+    setStatus('downloading');
+    setProgress(null);
+    setResult(null);
+    setDownloadId(id);
+    downloadIdRef.current = id;
+    const res = await download({
+      ...opts,
+      downloadId: id,
+      onProgress: (p) => {
+        setProgress(p);
+        opts.onProgress?.(p);
+      },
+    });
+    setResult(res);
+    setStatus(
+      !!opts.background && !!res.success && !!res.downloadId && !res.filePath
+        ? 'downloading'
+        : res.success
+        ? 'done'
+        : 'error'
+    );
+    return res;
+  }, []);
 
-      setResult(res);
-      const isBackgroundPending =
-        !!options.background &&
-        !!res.success &&
-        !!res.downloadId &&
-        !res.filePath;
-      setStatus(
-        isBackgroundPending ? 'downloading' : res.success ? 'done' : 'error'
-      );
-      return res;
-    },
-    []
-  );
-
-  const pause = useCallback(async (): Promise<void> => {
+  const pause = useCallback(async () => {
     if (downloadIdRef.current) {
       await pauseDownload(downloadIdRef.current);
       setStatus('paused');
     }
   }, []);
-
-  const resume = useCallback(async (): Promise<void> => {
+  const resume = useCallback(async () => {
     if (downloadIdRef.current) {
       await resumeDownload(downloadIdRef.current);
       setStatus('downloading');
     }
   }, []);
-
-  const cancel = useCallback(async (): Promise<void> => {
+  const cancel = useCallback(async () => {
     if (downloadIdRef.current) {
       await cancelDownload(downloadIdRef.current);
       setStatus('idle');