rn-file-toolkit 1.0.7 → 1.0.9

package/FileToolkit.podspec

@@ -17,6 +17,7 @@ Pod::Spec.new do |s|
   s.private_header_files = "ios/**/*.h"
 
   s.libraries = "z"
+  s.frameworks = "Photos"
 
   install_modules_dependencies(s)
 end

package/README.md

@@ -25,10 +25,20 @@
 - [Quick Start: `useDownload`](#-quick-start-usedownload)
 - [Core APIs](#-core-apis)
   - [Background Downloads](#background-downloads)
+  - [Download Controls](#download-controls)
   - [Multipart Uploads](#multipart-uploads)
+  - [Queue Management](#queue-management)
   - [File System (FS)](#file-system-fs)
   - [Zip & Unzip Archives](#zip--unzip-archives)
+  - [Cache Management](#cache-management)
   - [Media & Utilities](#media--utilities)
+  - [Disk Space](#disk-space)
+  - [File Appending](#file-appending)
+  - [File Hashing](#file-hashing)
+  - [Session Management](#session-management)
+  - [Cookie Management](#cookie-management)
+  - [MediaStore / Photos Library](#mediastore--photos-library)
+  - [Event Listeners](#event-listeners)
 - [API Reference](#-api-reference)
 - [Expo Support](#-expo-support)
 - [Contributing](#-contributing)
@@ -46,7 +56,10 @@ Most React Native file solutions (`rn-fetch-blob`, `react-native-fs`) are fragme
 - 🚦 **Smart Queueing:** Cap concurrency and set priorities without touching native code.
 - 🛡️ **Resilient:** Auto-retries on network errors with exponential backoff and HTTP resume.
 - 🗜️ **Zero-Dependency Zip:** Uses native `java.util.zip` and iOS `zlib`.
-- 🗄️ **Rich File System API:** Comprehensive FS methods (`readFile`, `writeFile`, `copyFile`, `mkdir`, `stat`, etc.).
+- 🗄️ **Rich File System API:** Comprehensive FS methods (`readFile`, `writeFile`, `appendFile`, `copyFile`, `mkdir`, `stat`, `hash`, `df`, etc.).
+- 🍪 **Cookie Management:** Read and clear HTTP cookies from the platform's shared cookie store.
+- 📸 **MediaStore / Photos Library:** Save files directly to the device's shared media store.
+- 📦 **Session Management:** Group files into named sessions for batch cleanup.
 - 🛠️ **Expo Compatible:** Seamless integration with Expo custom dev clients.
 
 ---
@@ -159,19 +172,54 @@ export default function DownloadScreen() {
 For programmatic, queue-aware background downloads outside of React components.
 
 ```typescript
-import { download, setQueueOptions } from 'rn-file-toolkit';
-
-// Optimize global concurrency
-setQueueOptions({ maxConcurrent: 3 });
+import { download } from 'rn-file-toolkit';
 
 const result = await download({
   url: 'https://example.com/file.pdf',
+  fileName: 'report.pdf', // Optional custom filename
   destination: 'documents', // 'downloads' | 'cache' | 'documents'
+  background: true, // Survive app suspension
+  headers: { Authorization: 'Bearer token' },
   queue: true, // Join the managed queue
   priority: 'high', // 'high' | 'normal'
-  retry: { attempts: 3, delay: 1000 },
+  downloadId: 'my-unique-id', // Optional custom ID for tracking
+  notificationTitle: 'Downloading report…', // Android notification
+  notificationDescription: 'Please wait',
+  checksum: { hash: 'abc123...', algorithm: 'sha256' }, // Verify integrity
+  retry: {
+    attempts: 3,
+    delay: 1000,
+    onRetry: (attempt, error) => console.warn(`Retry #${attempt}: ${error}`),
+  },
   onProgress: (p) => console.log(`${p.percent.toFixed(1)}% downloaded`),
 });
+
+console.log(result.filePath); // Path to the downloaded file
+```
+
+### Download Controls
+
+Pause, resume, or cancel any active download by its ID—works both inside and outside React components.
+
+```typescript
+import {
+  download,
+  pauseDownload,
+  resumeDownload,
+  cancelDownload,
+} from 'rn-file-toolkit';
+
+// Start a download with a known ID
+const result = download({
+  url: 'https://example.com/large-video.mp4',
+  downloadId: 'video-1',
+  destination: 'documents',
+});
+
+// Later… pause, resume, or cancel by ID
+await pauseDownload('video-1');
+await resumeDownload('video-1');
+await cancelDownload('video-1');
 ```
 
 ### Multipart Uploads
@@ -185,21 +233,52 @@ const result = await upload({
   url: 'https://api.example.com/v1/upload',
   filePath: '/path/to/local/image.jpg',
   fieldName: 'file',
+  headers: { Authorization: 'Bearer token' },
   parameters: { userId: '123', folder: 'avatars' },
+  uploadId: 'upload-1', // Optional custom ID for tracking
   onProgress: (percent) => console.log(`Uploading: ${percent}%`),
 });
+
+console.log(result.status); // HTTP status code
+console.log(result.data); // Server response body
+```
+
+### Queue Management
+
+Control download concurrency globally and inspect the queue state.
+
+```typescript
+import { setQueueOptions, getQueueStatus } from 'rn-file-toolkit';
+
+// Set the maximum number of simultaneous downloads
+setQueueOptions({ maxConcurrent: 3 });
+
+// Inspect the queue at any time
+const status = getQueueStatus();
+console.log(status.active); // Currently downloading
+console.log(status.pending); // Waiting in queue
+console.log(status.maxConcurrent); // Concurrency cap
+```
+
+You can also retrieve all downloads currently running in the background (useful after app re-launch):
+
+```typescript
+import { getBackgroundDownloads } from 'rn-file-toolkit';
+
+const active = await getBackgroundDownloads();
+console.log(active); // Array of background download descriptors
 ```
 
 ### File System (FS)
 
-Perform native filesystem operations securely.
+Perform native filesystem operations securely. All methods are available both as the namespaced `fs` object and as standalone named exports.
 
 ```typescript
 import { fs } from 'rn-file-toolkit';
 
 // Check & Inspect
 const exists = await fs.exists('/path/to/data.json');
-const stats = await fs.stat('/path/to/data.json'); // { size, modified, isDir }
+const stats = await fs.stat('/path/to/data.json'); // { path, name, size, modified, isDir }
 
 // Read & Write
 await fs.writeFile('/path/to/data.txt', 'Hello World', 'utf8'); // Also supports 'base64'
@@ -213,18 +292,42 @@ await fs.moveFile('/path/old.txt', '/path/new.txt');
 await fs.deleteFile('/path/unwanted.txt');
 ```
 
+> **Tip:** You can also import each FS method individually:
+> ```typescript
+> import { exists, stat, readFile, writeFile, copyFile, moveFile, deleteFile, mkdir, ls } from 'rn-file-toolkit';
+> ```
+
 ### Zip & Unzip Archives
 
-Compress and extract archives directly on the device.
+Compress and extract archives directly on the device using native `java.util.zip` (Android) and `zlib` (iOS).
 
 ```typescript
 import { unzip, zip } from 'rn-file-toolkit';
 
 // Extract a downloaded zip
-await unzip('/path/to/bundle.zip', '/path/to/extract-folder');
+const unzipResult = await unzip('/path/to/bundle.zip', '/path/to/extract-folder');
+console.log(unzipResult.files); // List of extracted file paths
 
 // Compress user data before uploading
-await zip('/path/to/user-data-folder', '/path/to/backup.zip');
+const zipResult = await zip('/path/to/user-data-folder', '/path/to/backup.zip');
+console.log(zipResult.zipPath); // Path to the created archive
+```
+
+### Cache Management
+
+Inspect and clear files stored in the cache directory.
+
+```typescript
+import { getCachedFiles, clearCache } from 'rn-file-toolkit';
+
+// List all cached files with metadata
+const cache = await getCachedFiles();
+cache.files?.forEach((f) => {
+  console.log(f.fileName, f.filePath, f.size, f.modifiedAt);
+});
+
+// Wipe the entire cache directory
+await clearCache();
 ```
 
 ### Media & Utilities
@@ -239,18 +342,27 @@ import {
   openFile,
 } from 'rn-file-toolkit';
 
-// Base64 to File
+// Base64 to File (accepts raw base64 or data URIs)
 await saveBase64AsFile({
   base64Data: 'data:image/png;base64,...',
   destination: 'documents',
   fileName: 'image.png',
 });
 
-// URL to Base64 (Great for caching small images)
-const b64 = await urlToBase64({ url: 'https://example.com/icon.png' });
+// URL to Base64 (great for caching small images)
+const b64 = await urlToBase64({
+  url: 'https://example.com/icon.png',
+  headers: { Authorization: 'Bearer token' }, // Optional
+});
+console.log(b64.mimeType); // e.g. 'image/png'
+console.log(b64.dataUri); // Ready-to-use data URI string
 
 // Native Share Sheet
-await shareFile({ filePath: '/path/to/report.pdf' });
+await shareFile({
+  filePath: '/path/to/report.pdf',
+  title: 'Share report', // Optional
+  subject: 'Monthly report', // Optional (email subject)
+});
 
 // Open with default system app
 await openFile({
@@ -259,19 +371,248 @@ await openFile({
 });
 ```
 
+### Event Listeners
+
+Subscribe to global download and upload lifecycle events. Each listener returns an unsubscribe function.
+
+```typescript
+import {
+  onDownloadComplete,
+  onDownloadError,
+  onDownloadRetry,
+  onUploadProgress,
+} from 'rn-file-toolkit';
+
+// Fires when any download finishes successfully
+const unsub1 = onDownloadComplete((event) => {
+  console.log('Download done:', event);
+});
+
+// Fires when any download fails
+const unsub2 = onDownloadError((event) => {
+  console.error('Download failed:', event);
+});
+
+// Fires on each retry attempt (when retry is configured)
+const unsub3 = onDownloadRetry((event) => {
+  console.warn(`Retry #${event.attempt}:`, event.error);
+});
+
+// Fires on upload progress updates
+const unsub4 = onUploadProgress((event) => {
+  console.log(`Upload ${event.uploadId}: ${event.progress}%`);
+});
+
+// Clean up when done
+unsub1();
+unsub2();
+unsub3();
+unsub4();
+```
+
+### Disk Space
+
+Check available and total device storage.
+
+```typescript
+import { df } from 'rn-file-toolkit';
+// or: import { fs } from 'rn-file-toolkit'; const result = await fs.df();
+
+const space = await df();
+if (space.success) {
+  console.log(`Free: ${(space.freeBytes! / 1024 / 1024 / 1024).toFixed(2)} GB`);
+  console.log(`Total: ${(space.totalBytes! / 1024 / 1024 / 1024).toFixed(2)} GB`);
+}
+```
+
+### File Appending
+
+Append data to the end of a file without overwriting existing content.
+
+```typescript
+import { appendFile } from 'rn-file-toolkit';
+
+// Append a log line
+await appendFile('/path/to/log.txt', 'New log entry\n');
+
+// Append base64 data
+await appendFile('/path/to/data.bin', base64String, 'base64');
+```
+
+### File Hashing
+
+Compute the MD5, SHA-1, or SHA-256 hash of any file on disk.
+
+```typescript
+import { hash } from 'rn-file-toolkit';
+
+const result = await hash('/path/to/file.zip', 'sha256');
+if (result.success) {
+  console.log('SHA-256:', result.hash);
+}
+```
+
+### Session Management
+
+Group downloaded files into sessions for batch cleanup. Useful for temporary file workflows.
+
+```typescript
+import { session, download } from 'rn-file-toolkit';
+
+// Download files and track them in a session
+const result = await download({ url: 'https://example.com/tmp1.pdf', destination: 'cache' });
+if (result.filePath) session.add('my-workflow', result.filePath);
+
+const result2 = await download({ url: 'https://example.com/tmp2.pdf', destination: 'cache' });
+if (result2.filePath) session.add('my-workflow', result2.filePath);
+
+// List session files
+console.log(session.get('my-workflow')); // ['/path/to/tmp1.pdf', '/path/to/tmp2.pdf']
+
+// Clean up everything when done
+await session.clear('my-workflow');
+```
+
+> **Note:** Session data lives in memory and does not persist across app restarts.
+
+### Cookie Management
+
+Read and clear HTTP cookies from the platform's shared cookie store.
+
+```typescript
+import { getCookies, clearCookies } from 'rn-file-toolkit';
+// or: import { cookies } from 'rn-file-toolkit';
+
+// Get cookies for a domain
+const result = await getCookies('example.com');
+result.cookies?.forEach((c) => {
+  console.log(`${c.name}=${c.value} (domain: ${c.domain})`);
+});
+
+// Clear cookies for a specific domain
+await clearCookies('example.com');
+
+// Clear ALL cookies
+await clearCookies();
+```
+
+### MediaStore / Photos Library
+
+Save files to the device's shared media store (Android MediaStore / iOS Photos Library).
+
+```typescript
+import { saveToMediaStore } from 'rn-file-toolkit';
+
+// Save an image to the Photos library / gallery
+const result = await saveToMediaStore({
+  filePath: '/path/to/photo.jpg',
+  mediaType: 'image',
+  album: 'MyApp',  // Optional album/subfolder
+});
+console.log(result.uri); // content://... (Android) or file path (iOS)
+
+// Save a video
+await saveToMediaStore({
+  filePath: '/path/to/video.mp4',
+  mediaType: 'video',
+});
+
+// Save to the Downloads folder
+await saveToMediaStore({
+  filePath: '/path/to/report.pdf',
+  mediaType: 'download',
+});
+```
+
+> **Permissions:** iOS requires `NSPhotoLibraryAddUsageDescription` in your `Info.plist` for image/video saves. Android may require `WRITE_EXTERNAL_STORAGE` on API < 29.
+
 ---
 
 ## 📚 API Reference
 
-| Interface           | Key Properties                                             | Description                             |
-| :------------------ | :--------------------------------------------------------- | :-------------------------------------- |
-| `DownloadOptions`   | `url`, `destination`, `queue`, `retry`, `onProgress`       | Configuration for downloading a file.   |
-| `UploadOptions`     | `url`, `filePath`, `fieldName`, `parameters`, `onProgress` | Configuration for multipart uploads.    |
-| `ProgressInfo`      | `percent`, `bytesDownloaded`, `speedBps`, `etaSeconds`     | Rich real-time progress payload.        |
-| `UseDownloadReturn` | `start`, `pause`, `resume`, `cancel`, `status`, `progress` | Hook state and control methods.         |
-| `FsStat`            | `size`, `modified`, `isDir`                                | Output of the filesystem `stat` method. |
-
-_For advanced types and detailed parameter documentation, please refer to the source TypeScript definitions._
+### Types & Interfaces
+
+| Interface | Key Properties | Description |
+| :--- | :--- | :--- |
+| `DownloadOptions` | `url`, `fileName`, `destination`, `background`, `headers`, `queue`, `priority`, `downloadId`, `checksum`, `retry`, `onProgress`, `notificationTitle`, `notificationDescription` | Full configuration for downloading a file. |
+| `UploadOptions` | `url`, `filePath`, `fieldName`, `headers`, `parameters`, `uploadId`, `onProgress` | Configuration for multipart uploads. |
+| `ProgressInfo` | `percent`, `bytesDownloaded`, `totalBytes`, `speedBps`, `etaSeconds` | Rich real-time download progress payload. |
+| `DownloadResult` | `success`, `filePath`, `downloadId`, `error` | Result returned after a download completes. |
+| `UploadResult` | `success`, `status`, `data`, `uploadId`, `error` | Result returned after an upload completes. |
+| `ActionResult` | `success`, `error` | Generic result for actions like pause/resume/cancel. |
+| `UseDownloadReturn` | `start`, `pause`, `resume`, `cancel`, `status`, `progress`, `result`, `downloadId` | Hook state and control methods. |
+| `FsApi` | `exists`, `stat`, `readFile`, `writeFile`, `appendFile`, `copyFile`, `moveFile`, `deleteFile`, `mkdir`, `ls`, `df`, `hash` | Namespaced filesystem API. |
+| `FsStat` | `path`, `name`, `size`, `modified`, `isDir` | Output of the filesystem `stat` method. |
+| `FsEncoding` | `'utf8'` \| `'base64'` | Encoding used for read/write operations. |
+| `QueueOptions` | `maxConcurrent` | Configuration for the download queue. |
+| `QueueStatus` | `active`, `pending`, `maxConcurrent` | Snapshot of the current queue state. |
+| `CachedFile` | `fileName`, `filePath`, `size`, `modifiedAt` | Metadata for a single cached file. |
+| `CacheResult` | `success`, `files`, `error` | Result of `getCachedFiles()`. |
+| `SaveBase64Options` | `base64Data`, `fileName`, `destination` | Options for saving a base64 string to a file. |
+| `SaveBase64Result` | `success`, `filePath`, `error` | Result of `saveBase64AsFile()`. |
+| `UrlToBase64Options` | `url`, `headers` | Options for converting a URL to base64. |
+| `UrlToBase64Result` | `success`, `base64`, `mimeType`, `dataUri`, `error` | Result of `urlToBase64()`. |
+| `ShareFileOptions` | `filePath`, `title`, `subject` | Options for the native share sheet. |
+| `OpenFileOptions` | `filePath`, `mimeType` | Options for opening a file with the system default app. |
+| `UnzipResult` | `success`, `destDir`, `files`, `error` | Result of `unzip()`. |
+| `ZipResult` | `success`, `zipPath`, `error` | Result of `zip()`. |
+
+### Exported Functions
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `download` | `(options: DownloadOptions) => Promise<DownloadResult>` | Download a file (supports queue, background, retries). |
+| `upload` | `(options: UploadOptions) => Promise<UploadResult>` | Multipart upload a file. |
+| `pauseDownload` | `(id: string) => Promise<ActionResult>` | Pause an active download by ID. |
+| `resumeDownload` | `(id: string) => Promise<ActionResult>` | Resume a paused download by ID. |
+| `cancelDownload` | `(id: string) => Promise<ActionResult>` | Cancel a download by ID. |
+| `setQueueOptions` | `(options: QueueOptions) => void` | Set global queue concurrency. |
+| `getQueueStatus` | `() => QueueStatus` | Get current queue state (active/pending counts). |
+| `getBackgroundDownloads` | `() => Promise<any>` | Retrieve active background download descriptors. |
+| `getCachedFiles` | `() => Promise<CacheResult>` | List all files in the cache directory. |
+| `clearCache` | `() => Promise<ActionResult>` | Delete all cached files. |
+| `deleteFile` | `(path: string) => Promise<ActionResult>` | Delete a single file by path. |
+| `exists` | `(path: string) => Promise<boolean>` | Check if a file or directory exists. |
+| `stat` | `(path: string) => Promise<FsStat>` | Get metadata for a file or directory. |
+| `readFile` | `(path: string, encoding?: FsEncoding) => Promise<string>` | Read file contents as a string. |
+| `writeFile` | `(path: string, data: string, encoding?: FsEncoding) => Promise<void>` | Write a string to a file. |
+| `copyFile` | `(from: string, to: string) => Promise<void>` | Copy a file. |
+| `moveFile` | `(from: string, to: string) => Promise<void>` | Move or rename a file. |
+| `mkdir` | `(path: string) => Promise<void>` | Create a directory (recursive). |
+| `ls` | `(path: string) => Promise<string[]>` | List directory contents. |
+| `unzip` | `(src: string, dest: string) => Promise<UnzipResult>` | Extract a zip archive. |
+| `zip` | `(src: string, dest: string) => Promise<ZipResult>` | Compress a folder into a zip archive. |
+| `saveBase64AsFile` | `(options: SaveBase64Options) => Promise<SaveBase64Result>` | Save a base64 string as a file. |
+| `urlToBase64` | `(options: UrlToBase64Options) => Promise<UrlToBase64Result>` | Fetch a URL and return its content as base64. |
+| `shareFile` | `(options: ShareFileOptions) => Promise<ShareFileResult>` | Open the native share sheet for a file. |
+| `openFile` | `(options: OpenFileOptions) => Promise<OpenFileResult>` | Open a file with the system default app. |
+| `onDownloadComplete` | `(cb) => () => void` | Subscribe to download completion events. |
+| `onDownloadError` | `(cb) => () => void` | Subscribe to download error events. |
+| `onDownloadRetry` | `(cb) => () => void` | Subscribe to download retry events. |
+| `onUploadProgress` | `(cb) => () => void` | Subscribe to upload progress events. |
+| `useDownload` | `() => UseDownloadReturn` | React hook for managing a download with state. |
+| `df` | `() => Promise<DiskSpaceResult>` | Get free and total device disk space. |
+| `appendFile` | `(path: string, data: string, encoding?: FsEncoding) => Promise<void>` | Append data to a file. |
+| `hash` | `(path: string, algorithm?: HashAlgorithm) => Promise<HashResult>` | Compute a file's hash digest. |
+| `getCookies` | `(domain: string) => Promise<CookiesResult>` | Get cookies for a domain. |
+| `clearCookies` | `(domain?: string) => Promise<ActionResult>` | Clear cookies (domain or all). |
+| `saveToMediaStore` | `(options: MediaStoreOptions) => Promise<MediaStoreResult>` | Save file to shared media store. |
+| `fs` | `FsApi` | Namespaced object grouping all filesystem methods (includes `df`, `appendFile`, `hash`). |
+| `cookies` | `{ get, clear }` | Namespaced cookie management. |
+| `session` | `SessionApi` | Namespaced session management. |
+
+### New Types & Interfaces
+
+| Interface | Key Properties | Description |
+| :--- | :--- | :--- |
+| `DiskSpaceResult` | `success`, `freeBytes`, `totalBytes`, `error` | Result of `df()`. |
+| `HashAlgorithm` | `'md5'` \| `'sha1'` \| `'sha256'` | Algorithm for file hashing. |
+| `HashResult` | `success`, `hash`, `error` | Result of `hash()`. |
+| `Cookie` | `name`, `value`, `domain`, `path`, `expiresDate`, `isSecure`, `isHTTPOnly` | A single cookie entry. |
+| `CookiesResult` | `success`, `cookies`, `error` | Result of `getCookies()`. |
+| `MediaStoreOptions` | `filePath`, `mediaType`, `album` | Options for saving to the media store. |
+| `MediaStoreResult` | `success`, `uri`, `error` | Result of `saveToMediaStore()`. |
+| `SessionApi` | `add`, `get`, `clear`, `clearAll` | Session management methods. |
 
 ---