rn-file-toolkit 1.0.1

package/lib/commonjs/index.js

@@ -0,0 +1,941 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.cancelDownload = cancelDownload;
+exports.clearCache = clearCache;
+exports.copyFile = copyFile;
+exports.default = void 0;
+exports.deleteFile = deleteFile;
+exports.download = download;
+exports.exists = exists;
+exports.fs = void 0;
+exports.getBackgroundDownloads = getBackgroundDownloads;
+exports.getCachedFiles = getCachedFiles;
+exports.getQueueStatus = getQueueStatus;
+exports.ls = ls;
+exports.mkdir = mkdir;
+exports.moveFile = moveFile;
+exports.onDownloadComplete = onDownloadComplete;
+exports.onDownloadError = onDownloadError;
+exports.onDownloadRetry = onDownloadRetry;
+exports.onUploadProgress = onUploadProgress;
+exports.openFile = openFile;
+exports.pauseDownload = pauseDownload;
+exports.readFile = readFile;
+exports.resumeDownload = resumeDownload;
+exports.saveBase64AsFile = saveBase64AsFile;
+exports.setQueueOptions = setQueueOptions;
+exports.shareFile = shareFile;
+exports.stat = stat;
+exports.unzip = unzip;
+exports.upload = upload;
+exports.urlToBase64 = urlToBase64;
+exports.useDownload = useDownload;
+exports.writeFile = writeFile;
+exports.zip = zip;
+var _react = require("react");
+var _reactNative = require("react-native");
+var _NativeFileToolkit = _interopRequireDefault(require("./NativeFileToolkit"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const FileToolkitModule = _reactNative.NativeModules.FileToolkit || _NativeFileToolkit.default;
+const eventEmitter = new _reactNative.NativeEventEmitter(FileToolkitModule);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * Rich progress information emitted during a download.
+ * Replaces the plain `number` percent from earlier versions.
+ */
+
+// ─── Queue ───────────────────────────────────────────────────────────────────
+
+class DownloadQueue {
+  _maxConcurrent = 3;
+  _active = 0;
+  _queue = [];
+  setOptions(opts) {
+    if (opts.maxConcurrent != null && opts.maxConcurrent > 0) {
+      this._maxConcurrent = opts.maxConcurrent;
+      // Kick off any slots that just opened.
+      this._flush();
+    }
+  }
+  getStatus() {
+    return {
+      active: this._active,
+      pending: this._queue.length,
+      maxConcurrent: this._maxConcurrent
+    };
+  }
+  enqueue(options) {
+    return new Promise((resolve, reject) => {
+      const item = {
+        options,
+        resolve,
+        reject
+      };
+      if (options.priority === 'high') {
+        this._queue.unshift(item);
+      } else {
+        this._queue.push(item);
+      }
+      this._flush();
+    });
+  }
+  _flush() {
+    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;
+      _executeDownload(nativeOptions).then(result => {
+        item.resolve(result);
+      }).catch(err => {
+        item.reject(err);
+      }).finally(() => {
+        this._active--;
+        this._flush();
+      });
+    }
+  }
+}
+const _globalQueue = new DownloadQueue();
+
+/**
+ * Configure the global managed download queue.
+ *
+ * @example
+ * ```ts
+ * setQueueOptions({ maxConcurrent: 3 });
+ * ```
+ */
+function setQueueOptions(options) {
+  _globalQueue.setOptions(options);
+}
+
+/**
+ * Get the current state of the managed download queue.
+ *
+ * @example
+ * ```ts
+ * const { active, pending, maxConcurrent } = getQueueStatus();
+ * ```
+ */
+function getQueueStatus() {
+  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) {
+  let progressSubscription = null;
+  let retrySubscription = 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 = null;
+
+  // Speed / ETA tracking (JS-side, works regardless of native platform)
+  let _lastProgressTs = null;
+  let _lastProgressBytes = 0;
+  // Smoothed speed using exponential moving average (α = 0.3)
+  let _smoothedSpeedBps = 0;
+  if (options.onProgress) {
+    progressSubscription = eventEmitter.addListener('onDownloadProgress', event => {
+      const matchesId = knownDownloadId && event.downloadId === knownDownloadId;
+      const matchesUrl = !knownDownloadId && event.url === options.url;
+      if ((matchesId || matchesUrl) && options.onProgress) {
+        const now = Date.now();
+        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;
+              }
+            }
+          }
+        }
+        _lastProgressTs = now;
+        _lastProgressBytes = bytesDownloaded;
+        const info = {
+          percent,
+          bytesDownloaded,
+          totalBytes,
+          speedBps,
+          etaSeconds
+        };
+        options.onProgress(info);
+      }
+    });
+  }
+  if (options.retry?.onRetry) {
+    retrySubscription = eventEmitter.addListener('onDownloadRetry', event => {
+      const matchesId = knownDownloadId && event.downloadId === knownDownloadId;
+      const matchesUrl = !knownDownloadId && event.url === options.url;
+      if ((matchesId || matchesUrl) && options.retry?.onRetry) {
+        options.retry.onRetry(event.attempt, event.error ?? '');
+      }
+    });
+  }
+  const cleanup = () => {
+    progressSubscription?.remove();
+    retrySubscription?.remove();
+  };
+  try {
+    const resultPromise = _NativeFileToolkit.default.download({
+      url: options.url,
+      fileName: options.fileName,
+      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 => {
+      if (partial?.downloadId && !partial?.filePath) {
+        // Android early-resolve: has downloadId but no filePath yet
+        knownDownloadId = partial.downloadId;
+      }
+    });
+    const result = await resultPromise;
+    cleanup();
+    return result;
+  } catch (error) {
+    cleanup();
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+/**
+ * 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',
+ * });
+ * ```
+ */
+function download(options) {
+  if (options.queue) {
+    return _globalQueue.enqueue(options);
+  }
+  return _executeDownload(options);
+}
+
+// ─── Core upload ───────────────────────────────────────────────────────────────
+
+/**
+ * Upload a file using multipart/form-data.
+ */
+async function upload(options) {
+  let progressSubscription = null;
+  if (options.onProgress) {
+    progressSubscription = eventEmitter.addListener('onUploadProgress', event => {
+      if (event.url === options.url && options.onProgress) {
+        options.onProgress(event.progress);
+      }
+    });
+  }
+  try {
+    const result = await _NativeFileToolkit.default.upload({
+      url: options.url,
+      filePath: options.filePath,
+      fieldName: options.fieldName ?? 'file',
+      headers: options.headers ?? {},
+      parameters: options.parameters ?? {}
+    });
+    if (progressSubscription) {
+      progressSubscription.remove();
+    }
+    return result;
+  } catch (error) {
+    if (progressSubscription) {
+      progressSubscription.remove();
+    }
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+// ─── 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.
+ */
+async function pauseDownload(downloadId) {
+  try {
+    return await _NativeFileToolkit.default.pauseDownload(downloadId);
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+/**
+ * Resume a previously paused download.
+ * On iOS resumes from partial data (HTTP Range). On Android unblocks the thread.
+ */
+async function resumeDownload(downloadId) {
+  try {
+    return await _NativeFileToolkit.default.resumeDownload(downloadId);
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+/**
+ * Cancel and discard a download (foreground or background).
+ * Any partially-downloaded file is deleted.
+ */
+async function cancelDownload(downloadId) {
+  try {
+    return await _NativeFileToolkit.default.cancelDownload(downloadId);
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+// ─── Cache management ─────────────────────────────────────────────────────────
+
+/**
+ * List all files in the app's cache directory.
+ */
+async function getCachedFiles() {
+  try {
+    return await _NativeFileToolkit.default.getCachedFiles();
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+/**
+ * Delete a single file by its absolute path.
+ */
+async function deleteFile(filePath) {
+  try {
+    return await _NativeFileToolkit.default.deleteFile(filePath);
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+/**
+ * Delete all files in the app's cache directory.
+ */
+async function clearCache() {
+  try {
+    return await _NativeFileToolkit.default.clearCache();
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+/**
+ * Get all active background downloads.
+ * Use this after app restart to "re-attach" to ongoing downloads.
+ */
+async function getBackgroundDownloads() {
+  try {
+    return await _NativeFileToolkit.default.getBackgroundDownloads();
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+// ─── File system helpers ─────────────────────────────────────────────────────
+
+function _ensureFsSuccess(result, fallback) {
+  if (!result?.success) {
+    throw new Error(result?.error || fallback);
+  }
+}
+
+/** Check whether a file or directory exists. */
+async function exists(filePath) {
+  const result = await _NativeFileToolkit.default.exists(filePath);
+  _ensureFsSuccess(result, 'EXISTS_ERROR');
+  return !!result.exists;
+}
+
+/** Get file or directory metadata. */
+async function stat(filePath) {
+  const result = await _NativeFileToolkit.default.stat(filePath);
+  _ensureFsSuccess(result, 'STAT_ERROR');
+  return result.stat;
+}
+
+/** Read a file as utf8 (default) or base64 string. */
+async function readFile(filePath, encoding = 'utf8') {
+  const result = await _NativeFileToolkit.default.readFile(filePath, encoding);
+  _ensureFsSuccess(result, 'READ_FILE_ERROR');
+  return result.data ?? '';
+}
+
+/** Write utf8 (default) or base64 data to a file. */
+async function writeFile(filePath, data, encoding = 'utf8') {
+  const result = await _NativeFileToolkit.default.writeFile(filePath, data, encoding);
+  _ensureFsSuccess(result, 'WRITE_FILE_ERROR');
+}
+
+/** Copy a file from source to destination. */
+async function copyFile(fromPath, toPath) {
+  const result = await _NativeFileToolkit.default.copyFile(fromPath, toPath);
+  _ensureFsSuccess(result, 'COPY_FILE_ERROR');
+}
+
+/** Move a file from source to destination. */
+async function moveFile(fromPath, toPath) {
+  const result = await _NativeFileToolkit.default.moveFile(fromPath, toPath);
+  _ensureFsSuccess(result, 'MOVE_FILE_ERROR');
+}
+
+/** Create a directory recursively. */
+async function mkdir(dirPath) {
+  const result = await _NativeFileToolkit.default.mkdir(dirPath);
+  _ensureFsSuccess(result, 'MKDIR_ERROR');
+}
+
+/** List direct entries (names) in a directory. */
+async function ls(dirPath) {
+  const result = await _NativeFileToolkit.default.ls(dirPath);
+  _ensureFsSuccess(result, 'LS_ERROR');
+  return result.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');
+ * ```
+ */
+const fs = exports.fs = {
+  exists,
+  stat,
+  readFile,
+  writeFile,
+  copyFile,
+  moveFile,
+  deleteFile: async filePath => {
+    const result = await deleteFile(filePath);
+    _ensureFsSuccess(result, 'DELETE_FILE_ERROR');
+  },
+  mkdir,
+  ls
+};
+
+// ─── Event helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Subscribe to background download completion events.
+ * Returns an unsubscribe function.
+ */
+function onDownloadComplete(callback) {
+  const sub = eventEmitter.addListener('onDownloadComplete', callback);
+  return () => sub.remove();
+}
+
+/**
+ * Subscribe to background download error events.
+ * Returns an unsubscribe function.
+ */
+function onDownloadError(callback) {
+  const sub = eventEmitter.addListener('onDownloadError', callback);
+  return () => sub.remove();
+}
+
+/**
+ * Subscribe to upload progress events.
+ * Returns an unsubscribe function.
+ */
+function onUploadProgress(callback) {
+  const sub = eventEmitter.addListener('onUploadProgress', callback);
+  return () => sub.remove();
+}
+
+/**
+ * Subscribe to download retry events (fired before each retry attempt).
+ * Returns an unsubscribe function.
+ */
+function onDownloadRetry(callback) {
+  const sub = eventEmitter.addListener('onDownloadRetry', callback);
+  return () => sub.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'
+ * });
+ * ```
+ */
+async function saveBase64AsFile(options) {
+  try {
+    let {
+      base64Data,
+      fileName,
+      destination
+    } = options;
+
+    // Parse data URI if present (e.g., "data:image/png;base64,iVBORw0...")
+    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 result = await FileToolkitModule.saveBase64AsFile({
+      base64Data,
+      fileName,
+      destination
+    });
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.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);
+ * }
+ * ```
+ */
+async function urlToBase64(options) {
+  try {
+    const result = await FileToolkitModule.urlToBase64({
+      url: options.url,
+      headers: options.headers
+    });
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.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');
+ * }
+ * ```
+ */
+async function shareFile(options) {
+  try {
+    const result = await FileToolkitModule.shareFile(options.filePath, {
+      title: options.title,
+      subject: options.subject
+    });
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.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');
+ * }
+ * ```
+ */
+async function openFile(options) {
+  try {
+    const result = await FileToolkitModule.openFile(options.filePath, options.mimeType || '');
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'UNKNOWN_ERROR'
+    };
+  }
+}
+
+// ─── Zip / Unzip ─────────────────────────────────────────────────────────────
+
+/**
+ * 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);
+ * }
+ * ```
+ */
+async function unzip(sourcePath, destDir) {
+  try {
+    const result = await _NativeFileToolkit.default.unzip(sourcePath, destDir);
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || '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);
+ * }
+ * ```
+ */
+async function zip(sourcePath, destPath) {
+  try {
+    const result = await _NativeFileToolkit.default.zip(sourcePath, destPath);
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || 'ZIP_ERROR'
+    };
+  }
+}
+
+// ─── useDownload hook ─────────────────────────────────────────────────────────
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+function useDownload() {
+  const [status, setStatus] = (0, _react.useState)('idle');
+  const [progress, setProgress] = (0, _react.useState)(null);
+  const [result, setResult] = (0, _react.useState)(null);
+  const [downloadId, setDownloadId] = (0, _react.useState)(null);
+  const downloadIdRef = (0, _react.useRef)(null);
+  const start = (0, _react.useCallback)(async options => {
+    setStatus('downloading');
+    setProgress(null);
+    setResult(null);
+    setDownloadId(null);
+    downloadIdRef.current = null;
+    const res = await download({
+      ...options,
+      onProgress: info => {
+        setProgress(info);
+        options.onProgress?.(info);
+      }
+    });
+    if (res.downloadId) {
+      downloadIdRef.current = res.downloadId;
+      setDownloadId(res.downloadId);
+    }
+    setResult(res);
+    const isBackgroundPending = !!options.background && !!res.success && !!res.downloadId && !res.filePath;
+    setStatus(isBackgroundPending ? 'downloading' : res.success ? 'done' : 'error');
+    return res;
+  }, []);
+  const pause = (0, _react.useCallback)(async () => {
+    if (downloadIdRef.current) {
+      await pauseDownload(downloadIdRef.current);
+      setStatus('paused');
+    }
+  }, []);
+  const resume = (0, _react.useCallback)(async () => {
+    if (downloadIdRef.current) {
+      await resumeDownload(downloadIdRef.current);
+      setStatus('downloading');
+    }
+  }, []);
+  const cancel = (0, _react.useCallback)(async () => {
+    if (downloadIdRef.current) {
+      await cancelDownload(downloadIdRef.current);
+      setStatus('idle');
+      setProgress(null);
+      setResult(null);
+      downloadIdRef.current = null;
+      setDownloadId(null);
+    }
+  }, []);
+  return {
+    start,
+    pause,
+    resume,
+    cancel,
+    status,
+    progress,
+    result,
+    downloadId
+  };
+}
+var _default = exports.default = {
+  download,
+  upload,
+  pauseDownload,
+  resumeDownload,
+  cancelDownload,
+  getCachedFiles,
+  deleteFile,
+  clearCache,
+  getBackgroundDownloads,
+  saveBase64AsFile,
+  urlToBase64,
+  shareFile,
+  openFile,
+  onDownloadComplete,
+  onDownloadError,
+  onUploadProgress,
+  onDownloadRetry,
+  setQueueOptions,
+  getQueueStatus,
+  exists,
+  stat,
+  readFile,
+  writeFile,
+  copyFile,
+  moveFile,
+  mkdir,
+  ls,
+  fs,
+  useDownload,
+  unzip,
+  zip
+};
+//# sourceMappingURL=index.js.map