rn-file-toolkit 1.0.8 → 1.0.10

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

@@ -32,6 +32,12 @@
   - [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)
@@ -50,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.
 
 ---
@@ -401,6 +410,122 @@ 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
@@ -416,7 +541,7 @@ unsub4();
 | `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`, `copyFile`, `moveFile`, `deleteFile`, `mkdir`, `ls` | Namespaced filesystem API. |
+| `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. |
@@ -466,7 +591,28 @@ unsub4();
 | `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. |
-| `fs` | `FsApi` | Namespaced object grouping all filesystem methods. |
+| `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. |
 
 ---
 

package/android/src/main/java/com/filetoolkit/FileToolkitModule.kt

@@ -99,11 +99,17 @@ class FileToolkitModule(private val reactContext: ReactApplicationContext) :
 
   private fun getDestinationFile(fileName: String, destination: String?): File {
     return when (destination) {
-      "cache" -> File(reactContext.cacheDir, fileName)
+      "cache" -> {
+        val dir = File(reactContext.cacheDir, "RNFileToolkit")
+        dir.mkdirs()
+        File(dir, fileName)
+      }
       "documents" -> {
         // getExternalFilesDir can return null if external storage is unavailable
-        val dir = reactContext.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS)
+        val baseDir = reactContext.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS)
           ?: reactContext.filesDir
+        val dir = File(baseDir, "RNFileToolkit")
+        dir.mkdirs()
         File(dir, fileName)
       }
       else -> File(
@@ -531,8 +537,11 @@ class FileToolkitModule(private val reactContext: ReactApplicationContext) :
       // Scan all three directories: public downloads, cache, documents
       val dirs = listOfNotNull(
         Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS),
-        reactContext.cacheDir,
-        reactContext.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS) ?: reactContext.filesDir
+        File(reactContext.cacheDir, "RNFileToolkit"),
+        File(
+          reactContext.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS) ?: reactContext.filesDir,
+          "RNFileToolkit"
+        )
       )
 
       for (dir in dirs) {
@@ -573,13 +582,16 @@ class FileToolkitModule(private val reactContext: ReactApplicationContext) :
 
   override fun clearCache(promise: Promise) {
     try {
-      // Only clear app-private directories — never touch public Downloads
+      // Only clear the toolkit-owned subdirectory — never touch the app's own files or public Downloads
       val dirs = listOfNotNull(
-        reactContext.cacheDir,
-        reactContext.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS) ?: reactContext.filesDir
+        File(reactContext.cacheDir, "RNFileToolkit"),
+        File(
+          reactContext.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS) ?: reactContext.filesDir,
+          "RNFileToolkit"
+        )
       )
       for (dir in dirs) {
-        dir.listFiles()?.forEach { it.delete() }
+        dir.listFiles()?.forEach { it.deleteRecursively() }
       }
       promise.resolve(Arguments.createMap().apply { putBoolean("success", true) })
     } catch (e: Exception) {
@@ -1327,6 +1339,279 @@ class FileToolkitModule(private val reactContext: ReactApplicationContext) :
     zos.closeEntry()
   }
 
+  // ─── df (disk space) ──────────────────────────────────────────────────────
+
+  override fun df(promise: Promise) {
+    try {
+      val stat = android.os.StatFs(Environment.getDataDirectory().path)
+      val freeBytes = stat.availableBytes
+      val totalBytes = stat.totalBytes
+
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", true)
+        putDouble("freeBytes", freeBytes.toDouble())
+        putDouble("totalBytes", totalBytes.toDouble())
+      })
+    } catch (e: Throwable) {
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", false)
+        putString("error", e.message ?: "DF_ERROR")
+      })
+    }
+  }
+
+  // ─── appendFile ───────────────────────────────────────────────────────────
+
+  override fun appendFile(filePath: String, data: String, encoding: String, promise: Promise) {
+    try {
+      val file = File(filePath)
+      if (!file.exists()) {
+        // Create parent dirs and the file if it doesn't exist
+        file.parentFile?.mkdirs()
+      }
+
+      if (encoding.equals("base64", ignoreCase = true)) {
+        val bytes = android.util.Base64.decode(data, android.util.Base64.DEFAULT)
+        FileOutputStream(file, true).use { fos ->
+          fos.write(bytes)
+        }
+      } else {
+        FileOutputStream(file, true).use { fos ->
+          fos.write(data.toByteArray(Charsets.UTF_8))
+        }
+      }
+
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", true)
+      })
+    } catch (e: Throwable) {
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", false)
+        putString("error", e.message ?: "APPEND_FILE_ERROR")
+      })
+    }
+  }
+
+  // ─── hash ─────────────────────────────────────────────────────────────────
+
+  override fun hash(filePath: String, algorithm: String, promise: Promise) {
+    try {
+      val file = File(filePath)
+      if (!file.exists() || file.isDirectory) {
+        promise.resolve(Arguments.createMap().apply {
+          putBoolean("success", false)
+          putString("error", "File not found: $filePath")
+        })
+        return
+      }
+
+      val hashValue = calculateChecksum(file, algorithm)
+
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", true)
+        putString("hash", hashValue)
+      })
+    } catch (e: Throwable) {
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", false)
+        putString("error", e.message ?: "HASH_ERROR")
+      })
+    }
+  }
+
+  // ─── getCookies ───────────────────────────────────────────────────────────
+
+  override fun getCookies(domain: String, promise: Promise) {
+    try {
+      val cookieManager = android.webkit.CookieManager.getInstance()
+      val cookieString = cookieManager.getCookie(domain)
+
+      val cookiesArray = Arguments.createArray()
+
+      if (!cookieString.isNullOrBlank()) {
+        // CookieManager returns cookies as "name1=value1; name2=value2; ..."
+        cookieString.split(";").forEach { pair ->
+          val trimmed = pair.trim()
+          val eqIndex = trimmed.indexOf("=")
+          if (eqIndex > 0) {
+            val name = trimmed.substring(0, eqIndex)
+            val value = trimmed.substring(eqIndex + 1)
+            cookiesArray.pushMap(Arguments.createMap().apply {
+              putString("name", name)
+              putString("value", value)
+              putString("domain", domain)
+              putString("path", "/")
+            })
+          }
+        }
+      }
+
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", true)
+        putArray("cookies", cookiesArray)
+      })
+    } catch (e: Throwable) {
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", false)
+        putString("error", e.message ?: "GET_COOKIES_ERROR")
+      })
+    }
+  }
+
+  // ─── clearCookies ─────────────────────────────────────────────────────────
+
+  override fun clearCookies(domain: String, promise: Promise) {
+    try {
+      val cookieManager = android.webkit.CookieManager.getInstance()
+
+      if (domain.isBlank()) {
+        // Clear ALL cookies
+        cookieManager.removeAllCookies { success ->
+          promise.resolve(Arguments.createMap().apply {
+            putBoolean("success", success)
+          })
+        }
+      } else {
+        // Android CookieManager does not support per-domain clearing directly.
+        // We read cookies for the domain and set each to expired.
+        val cookieString = cookieManager.getCookie(domain)
+        if (!cookieString.isNullOrBlank()) {
+          cookieString.split(";").forEach { pair ->
+            val trimmed = pair.trim()
+            val eqIndex = trimmed.indexOf("=")
+            if (eqIndex > 0) {
+              val name = trimmed.substring(0, eqIndex)
+              cookieManager.setCookie(domain, "$name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT")
+            }
+          }
+          cookieManager.flush()
+        }
+        promise.resolve(Arguments.createMap().apply {
+          putBoolean("success", true)
+        })
+      }
+    } catch (e: Throwable) {
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", false)
+        putString("error", e.message ?: "CLEAR_COOKIES_ERROR")
+      })
+    }
+  }
+
+  // ─── saveToMediaStore ─────────────────────────────────────────────────────
+
+  override fun saveToMediaStore(options: ReadableMap, promise: Promise) {
+    val filePath = options.getString("filePath")
+    if (filePath.isNullOrBlank()) {
+      promise.resolve(Arguments.createMap().apply {
+        putBoolean("success", false)
+        putString("error", "filePath is required")
+      })
+      return
+    }
+
+    val mediaType = if (options.hasKey("mediaType")) options.getString("mediaType") else "download"
+    val album = if (options.hasKey("album")) options.getString("album") else null
+
+    thread {
+      try {
+        val file = File(filePath)
+        if (!file.exists()) {
+          promise.resolve(Arguments.createMap().apply {
+            putBoolean("success", false)
+            putString("error", "File not found: $filePath")
+          })
+          return@thread
+        }
+
+        val mimeType = getMimeType(filePath)
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+          // Android 10+ — use MediaStore ContentResolver API
+          val contentUri = when (mediaType) {
+            "image" -> android.provider.MediaStore.Images.Media.getContentUri(android.provider.MediaStore.VOLUME_EXTERNAL_PRIMARY)
+            "video" -> android.provider.MediaStore.Video.Media.getContentUri(android.provider.MediaStore.VOLUME_EXTERNAL_PRIMARY)
+            "audio" -> android.provider.MediaStore.Audio.Media.getContentUri(android.provider.MediaStore.VOLUME_EXTERNAL_PRIMARY)
+            else -> android.provider.MediaStore.Downloads.getContentUri(android.provider.MediaStore.VOLUME_EXTERNAL_PRIMARY)
+          }
+
+          val relativePath = when (mediaType) {
+            "image" -> if (album != null) "${Environment.DIRECTORY_PICTURES}/$album" else Environment.DIRECTORY_PICTURES
+            "video" -> if (album != null) "${Environment.DIRECTORY_MOVIES}/$album" else Environment.DIRECTORY_MOVIES
+            "audio" -> if (album != null) "${Environment.DIRECTORY_MUSIC}/$album" else Environment.DIRECTORY_MUSIC
+            else -> if (album != null) "${Environment.DIRECTORY_DOWNLOADS}/$album" else Environment.DIRECTORY_DOWNLOADS
+          }
+
+          val values = android.content.ContentValues().apply {
+            put(android.provider.MediaStore.MediaColumns.DISPLAY_NAME, file.name)
+            put(android.provider.MediaStore.MediaColumns.MIME_TYPE, mimeType)
+            put(android.provider.MediaStore.MediaColumns.RELATIVE_PATH, relativePath)
+            put(android.provider.MediaStore.MediaColumns.IS_PENDING, 1)
+          }
+
+          val resolver = reactContext.contentResolver
+          val uri = resolver.insert(contentUri, values)
+
+          if (uri == null) {
+            promise.resolve(Arguments.createMap().apply {
+              putBoolean("success", false)
+              putString("error", "Failed to create MediaStore entry")
+            })
+            return@thread
+          }
+
+          resolver.openOutputStream(uri)?.use { outputStream ->
+            FileInputStream(file).use { inputStream ->
+              val buffer = ByteArray(8192)
+              var count: Int
+              while (inputStream.read(buffer).also { count = it } != -1) {
+                outputStream.write(buffer, 0, count)
+              }
+            }
+          }
+
+          values.clear()
+          values.put(android.provider.MediaStore.MediaColumns.IS_PENDING, 0)
+          resolver.update(uri, values, null, null)
+
+          promise.resolve(Arguments.createMap().apply {
+            putBoolean("success", true)
+            putString("uri", uri.toString())
+          })
+        } else {
+          // Android 9 and below — copy to public directory and media-scan
+          val destDir = when (mediaType) {
+            "image" -> Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES)
+            "video" -> Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_MOVIES)
+            "audio" -> Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_MUSIC)
+            else -> Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS)
+          }
+
+          val albumDir = if (album != null) File(destDir, album) else destDir
+          albumDir.mkdirs()
+          val destFile = File(albumDir, file.name)
+          file.copyTo(destFile, overwrite = true)
+
+          android.media.MediaScannerConnection.scanFile(
+            reactContext,
+            arrayOf(destFile.absolutePath),
+            arrayOf(mimeType)
+          ) { _, scannedUri ->
+            promise.resolve(Arguments.createMap().apply {
+              putBoolean("success", true)
+              putString("uri", scannedUri?.toString() ?: destFile.absolutePath)
+            })
+          }
+        }
+      } catch (e: Exception) {
+        promise.resolve(Arguments.createMap().apply {
+          putBoolean("success", false)
+          putString("error", e.message ?: "MEDIA_STORE_ERROR")
+        })
+      }
+    }
+  }
+
   companion object {
     const val NAME = NativeFileToolkitSpec.NAME
   }