@simplysm/capacitor-plugin-file-system 13.0.100 → 14.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/capacitor-plugin-file-system
 
-Simplysm Package - Capacitor File System Plugin. Provides file system access for Android (MANAGE_EXTERNAL_STORAGE on Android 11+) with IndexedDB-based browser emulation.
+Capacitor file system plugin with full storage access on Android 11+.
 
 ## Installation
 
@@ -14,85 +14,121 @@ npm install @simplysm/capacitor-plugin-file-system
 
 | API | Type | Description |
 |-----|------|-------------|
-| `FileSystem` | class | File system access plugin (static methods) |
-| `FileSystemPlugin` | interface | Low-level Capacitor plugin interface for file system |
-| `StorageType` | type | Storage location type |
-| `FileInfo` | interface | File/directory entry information |
-
----
-
-### `StorageType`
-
-```typescript
-type StorageType =
-  | "external"       // External storage root (Environment.getExternalStorageDirectory)
-  | "externalFiles"  // App-specific external files directory
-  | "externalCache"  // App-specific external cache directory
-  | "externalMedia"  // App-specific external media directory
-  | "appData"        // App data directory
-  | "appFiles"       // App files directory
-  | "appCache";      // App cache directory
+| `StorageType` | Type | Union of supported Android storage location identifiers |
+| `FileInfo` | Interface | File entry metadata returned by directory listing |
+| `FileSystemPlugin` | Interface | Native plugin interface for file system operations |
+| `FileSystem` | Class | Static API for file system access with permission management |
+
+## Types
+
+### StorageType
+
+```ts
+type StorageType = "external" | "externalFiles" | "externalCache" | "externalMedia" | "appData" | "appFiles" | "appCache";
 ```
 
-### `FileInfo`
+| Value | Description |
+|-------|-------------|
+| `"external"` | Shared external storage root |
+| `"externalFiles"` | App-specific external files directory |
+| `"externalCache"` | App-specific external cache directory |
+| `"externalMedia"` | App-specific external media directory |
+| `"appData"` | Internal app data directory |
+| `"appFiles"` | Internal app files directory |
+| `"appCache"` | Internal app cache directory |
+
+## Interfaces
+
+### FileInfo
+
+Metadata for a single file or directory entry.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `name` | `string` | File or directory name |
-| `isDirectory` | `boolean` | Whether the entry is a directory |
+| `name` | `string` | Name of the file or directory |
+| `isDirectory` | `boolean` | `true` if the entry is a directory |
 
-### `FileSystemPlugin`
+### FileSystemPlugin
+
+Native plugin interface for file system operations.
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `checkPermissions` | `() => Promise<{ granted: boolean }>` | Check file system permission |
-| `requestPermissions` | `() => Promise<void>` | Request file system permission |
-| `readdir` | `(options: { path: string }) => Promise<{ files: FileInfo[] }>` | Read directory contents |
-| `getStoragePath` | `(options: { type: StorageType }) => Promise<{ path: string }>` | Get storage path by type |
-| `getUri` | `(options: { path: string }) => Promise<{ uri: string }>` | Get FileProvider URI |
-| `writeFile` | `(options: { path: string; data: string; encoding?: "utf8" \| "base64" }) => Promise<void>` | Write file |
-| `readFile` | `(options: { path: string; encoding?: "utf8" \| "base64" }) => Promise<{ data: string }>` | Read file |
-| `remove` | `(options: { path: string }) => Promise<void>` | Delete file/directory |
-| `mkdir` | `(options: { path: string }) => Promise<void>` | Create directory |
-| `exists` | `(options: { path: string }) => Promise<{ exists: boolean }>` | Check existence |
+| `checkPermissions` | `() => Promise<{ granted: boolean }>` | Check if storage permissions are granted |
+| `requestPermissions` | `() => Promise<void>` | Request storage permissions |
+| `readdir` | `(options: { path: string }) => Promise<{ files: FileInfo[] }>` | List files in a directory |
+| `getStoragePath` | `(options: { type: StorageType }) => Promise<{ path: string }>` | Get the absolute path for a storage type |
+| `getUri` | `(options: { path: string }) => Promise<{ uri: string }>` | Get a FileProvider content URI for a file path |
+| `writeFile` | `(options: { path: string; data: string; encoding?: "utf8" \| "base64" }) => Promise<void>` | Write data to a file |
+| `readFile` | `(options: { path: string; encoding?: "utf8" \| "base64" }) => Promise<{ data: string }>` | Read data from a file |
+| `remove` | `(options: { path: string }) => Promise<void>` | Remove a file or directory |
+| `mkdir` | `(options: { path: string }) => Promise<void>` | Create a directory |
+| `exists` | `(options: { path: string }) => Promise<{ exists: boolean }>` | Check if a path exists |
+
+## Classes
+
+### FileSystem
 
-### `FileSystem`
+File system access plugin. On Android 11+ it uses `MANAGE_EXTERNAL_STORAGE`. On Android 10 and below it uses `READ_EXTERNAL_STORAGE` / `WRITE_EXTERNAL_STORAGE`. On the browser it falls back to IndexedDB emulation.
 
-Abstract class with static methods for file system access. Android 11+ uses MANAGE_EXTERNAL_STORAGE; Android 10- uses READ/WRITE_EXTERNAL_STORAGE; browser uses IndexedDB emulation.
+All methods are static.
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `checkPermissions` | `() => Promise<boolean>` | Check permission |
-| `requestPermissions` | `() => Promise<void>` | Request permission (Android 11+: settings, Android 10-: dialog) |
-| `readdir` | `(dirPath: string) => Promise<FileInfo[]>` | Read directory |
-| `getStoragePath` | `(type: StorageType) => Promise<string>` | Get storage path |
-| `getUri` | `(filePath: string) => Promise<string>` | Get FileProvider URI |
-| `writeFile` | `(filePath: string, data: string \| Bytes) => Promise<void>` | Write file (string or Uint8Array) |
-| `readFile` | `(filePath: string) => Promise<Bytes>` | Read file as Bytes |
-| `readFile` | `(filePath: string, encoding: "utf8") => Promise<string>` | Read file as UTF-8 string |
-| `remove` | `(targetPath: string) => Promise<void>` | Delete file/directory (recursive) |
-| `mkdir` | `(targetPath: string) => Promise<void>` | Create directory (recursive) |
-| `exists` | `(targetPath: string) => Promise<boolean>` | Check existence |
+| `checkPermissions` | `static async checkPermissions(): Promise<boolean>` | Check whether storage permissions are granted |
+| `requestPermissions` | `static async requestPermissions(): Promise<void>` | Request storage permissions from the user |
+| `readdir` | `static async readdir(dirPath: string): Promise<FileInfo[]>` | List files and directories at the given path |
+| `getStoragePath` | `static async getStoragePath(type: StorageType): Promise<string>` | Get the absolute path for a storage type (`external`, `externalFiles`, `externalCache`, `externalMedia`, `appData`, `appFiles`, `appCache`) |
+| `getUri` | `static async getUri(filePath: string): Promise<string>` | Get a FileProvider content URI for the given file path |
+| `writeFile` | `static async writeFile(filePath: string, data: string \| Bytes): Promise<void>` | Write string or binary data to a file. Binary data (`Bytes`) is automatically base64-encoded. |
+| `readFile` | `static async readFile(filePath: string): Promise<Bytes>` | Read a file as binary data |
+| `readFile` (overload) | `static async readFile(filePath: string, encoding: "utf8"): Promise<string>` | Read a file as a UTF-8 string |
+| `remove` | `static async remove(targetPath: string): Promise<void>` | Recursively delete a file or directory |
+| `mkdir` | `static async mkdir(targetPath: string): Promise<void>` | Recursively create a directory and all parent directories |
+| `exists` | `static async exists(targetPath: string): Promise<boolean>` | Check whether a file or directory exists at the given path |
 
 ## Usage Examples
 
 ### Read and write files
 
-```typescript
+```ts
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
-// Check and request permissions
-if (!(await FileSystem.checkPermissions())) {
+// Ensure permissions
+const granted = await FileSystem.checkPermissions();
+if (!granted) {
   await FileSystem.requestPermissions();
 }
 
-// Get storage path and write a file
-const storagePath = await FileSystem.getStoragePath("appFiles");
-await FileSystem.writeFile(`${storagePath}/data.txt`, "Hello, world!");
+// Get external files directory
+const basePath = await FileSystem.getStoragePath("externalFiles");
+
+// Write a text file
+await FileSystem.writeFile(`${basePath}/config.json`, '{"key": "value"}');
+
+// Read it back as a string
+const content = await FileSystem.readFile(`${basePath}/config.json`, "utf8");
+```
+
+### List directory contents
+
+```ts
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+const files = await FileSystem.readdir("/storage/emulated/0/Download");
+for (const file of files) {
+  console.log(`${file.name} (${file.isDirectory ? "dir" : "file"})`);
+}
+```
+
+### Create directories and check existence
 
-// Read it back
-const content = await FileSystem.readFile(`${storagePath}/data.txt`, "utf8");
+```ts
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
-// List directory contents
-const files = await FileSystem.readdir(storagePath);
+const dirPath = "/storage/emulated/0/MyApp/data/logs";
+
+if (!(await FileSystem.exists(dirPath))) {
+  await FileSystem.mkdir(dirPath);
+}
 ```

package/android/build.gradle

@@ -1,4 +1,5 @@
 apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
 
 android {
     namespace "kr.co.simplysm.capacitor.filesystem"

package/android/src/main/kotlin/kr/co/simplysm/capacitor/filesystem/FileSystemPlugin.kt

@@ -0,0 +1,306 @@
+package kr.co.simplysm.capacitor.filesystem
+
+import android.Manifest
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.os.Environment
+import android.provider.Settings
+import android.util.Base64
+import android.util.Log
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import androidx.core.content.FileProvider
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import java.io.BufferedInputStream
+import java.io.BufferedOutputStream
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.nio.charset.StandardCharsets
+
+@CapacitorPlugin(name = "FileSystem")
+class FileSystemPlugin : Plugin() {
+
+    companion object {
+        private const val TAG = "FileSystemPlugin"
+        private const val PERMISSION_REQUEST_CODE = 1001
+    }
+
+    @PluginMethod
+    fun checkPermissions(call: PluginCall) {
+        val granted = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            Environment.isExternalStorageManager()
+        } else {
+            val ctx = context
+            ContextCompat.checkSelfPermission(ctx, Manifest.permission.READ_EXTERNAL_STORAGE) == PackageManager.PERMISSION_GRANTED
+                    && ContextCompat.checkSelfPermission(ctx, Manifest.permission.WRITE_EXTERNAL_STORAGE) == PackageManager.PERMISSION_GRANTED
+        }
+        val ret = JSObject()
+        ret.put("granted", granted)
+        call.resolve(ret)
+    }
+
+    @PluginMethod
+    fun requestPermissions(call: PluginCall) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            if (!Environment.isExternalStorageManager()) {
+                val intent = Intent(Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION)
+                intent.data = Uri.parse("package:" + context.packageName)
+                activity.startActivity(intent)
+            }
+        } else {
+            val readGranted = ContextCompat.checkSelfPermission(
+                context,
+                Manifest.permission.READ_EXTERNAL_STORAGE
+            ) == PackageManager.PERMISSION_GRANTED
+            val writeGranted = ContextCompat.checkSelfPermission(
+                context,
+                Manifest.permission.WRITE_EXTERNAL_STORAGE
+            ) == PackageManager.PERMISSION_GRANTED
+
+            if (!readGranted || !writeGranted) {
+                ActivityCompat.requestPermissions(
+                    activity,
+                    arrayOf(
+                        Manifest.permission.READ_EXTERNAL_STORAGE,
+                        Manifest.permission.WRITE_EXTERNAL_STORAGE
+                    ),
+                    PERMISSION_REQUEST_CODE
+                )
+            }
+        }
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun readdir(call: PluginCall) {
+        val path = call.getString("path")
+        if (path == null) {
+            call.reject("path is required")
+            return
+        }
+
+        val dir = File(path)
+        if (!dir.exists() || !dir.isDirectory) {
+            call.reject("Directory does not exist")
+            return
+        }
+
+        val files = dir.listFiles()
+        if (files == null) {
+            call.reject("Cannot read directory")
+            return
+        }
+
+        val result = JSArray()
+        for (f in files) {
+            val info = JSObject()
+            info.put("name", f.name)
+            info.put("isDirectory", f.isDirectory)
+            result.put(info)
+        }
+
+        val ret = JSObject()
+        ret.put("files", result)
+        call.resolve(ret)
+    }
+
+    @PluginMethod
+    fun getStoragePath(call: PluginCall) {
+        val type = call.getString("type")
+        if (type == null) {
+            call.reject("type is required")
+            return
+        }
+
+        val ctx = context
+        val path: File? = when (type) {
+            "external" -> Environment.getExternalStorageDirectory()
+            "externalFiles" -> ctx.getExternalFilesDir(null)
+            "externalCache" -> ctx.externalCacheDir
+            "externalMedia" -> {
+                val dirs = ctx.externalMediaDirs
+                if (dirs.isNotEmpty()) dirs[0] else null
+            }
+            "appData" -> File(ctx.applicationInfo.dataDir)
+            "appFiles" -> ctx.filesDir
+            "appCache" -> ctx.cacheDir
+            else -> {
+                call.reject("Unknown type: $type")
+                return
+            }
+        }
+
+        if (path == null) {
+            call.reject("Path not available")
+            return
+        }
+
+        val ret = JSObject()
+        ret.put("path", path.absolutePath)
+        call.resolve(ret)
+    }
+
+    @PluginMethod
+    fun getUri(call: PluginCall) {
+        val path = call.getString("path")
+        if (path == null) {
+            call.reject("path is required")
+            return
+        }
+
+        try {
+            val authority = context.packageName + ".filesystem.provider"
+            val uri = FileProvider.getUriForFile(context, authority, File(path))
+            val ret = JSObject()
+            ret.put("uri", uri.toString())
+            call.resolve(ret)
+        } catch (e: Exception) {
+            Log.e(TAG, "getUri failed", e)
+            call.reject("getUri failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun writeFile(call: PluginCall) {
+        val path = call.getString("path")
+        val data = call.getString("data")
+        val encoding = call.getString("encoding", "utf8")
+
+        if (path == null || data == null) {
+            call.reject("path and data are required")
+            return
+        }
+
+        try {
+            val file = File(path)
+            val parent = file.parentFile
+            if (parent != null && !parent.exists()) {
+                parent.mkdirs()
+            }
+
+            val bytes = if ("base64" == encoding) {
+                Base64.decode(data, Base64.DEFAULT)
+            } else {
+                data.toByteArray(StandardCharsets.UTF_8)
+            }
+
+            BufferedOutputStream(FileOutputStream(file)).use { bos ->
+                bos.write(bytes)
+            }
+
+            call.resolve()
+        } catch (e: Exception) {
+            Log.e(TAG, "writeFile failed", e)
+            call.reject("Write failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun readFile(call: PluginCall) {
+        val path = call.getString("path")
+        val encoding = call.getString("encoding", "utf8")
+
+        if (path == null) {
+            call.reject("path is required")
+            return
+        }
+
+        val file = File(path)
+        if (!file.exists()) {
+            call.reject("File not found: $path")
+            return
+        }
+
+        try {
+            BufferedInputStream(FileInputStream(file)).use { bis ->
+                ByteArrayOutputStream().use { baos ->
+                    val buf = ByteArray(8192)
+                    var len: Int
+                    while (bis.read(buf).also { len = it } != -1) {
+                        baos.write(buf, 0, len)
+                    }
+
+                    val result = if ("base64" == encoding) {
+                        Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP)
+                    } else {
+                        baos.toString("UTF-8")
+                    }
+
+                    val ret = JSObject()
+                    ret.put("data", result)
+                    call.resolve(ret)
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "readFile failed", e)
+            call.reject("Read failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun remove(call: PluginCall) {
+        val path = call.getString("path")
+        if (path == null) {
+            call.reject("path is required")
+            return
+        }
+
+        if (deleteRecursively(File(path))) {
+            call.resolve()
+        } else {
+            call.reject("Delete failed")
+        }
+    }
+
+    @PluginMethod
+    fun mkdir(call: PluginCall) {
+        val path = call.getString("path")
+        if (path == null) {
+            call.reject("path is required")
+            return
+        }
+
+        val dir = File(path)
+        if (dir.exists() || dir.mkdirs()) {
+            call.resolve()
+        } else {
+            call.reject("Failed to create directory")
+        }
+    }
+
+    @PluginMethod
+    fun exists(call: PluginCall) {
+        val path = call.getString("path")
+        if (path == null) {
+            call.reject("path is required")
+            return
+        }
+
+        val ret = JSObject()
+        ret.put("exists", File(path).exists())
+        call.resolve(ret)
+    }
+
+    private fun deleteRecursively(file: File): Boolean {
+        if (file.isDirectory) {
+            val children = file.listFiles()
+            if (children != null) {
+                for (child in children) {
+                    if (!deleteRecursively(child)) {
+                        return false
+                    }
+                }
+            }
+        }
+        return file.delete()
+    }
+}

package/android/src/main/kotlin/kr/co/simplysm/capacitor/filesystem/FileSystemProvider.kt

@@ -0,0 +1,5 @@
+package kr.co.simplysm.capacitor.filesystem
+
+import androidx.core.content.FileProvider
+
+class FileSystemProvider : FileProvider()

package/dist/FileSystem.d.ts

@@ -1,61 +1,61 @@
 import type { FileInfo, StorageType } from "./FileSystemPlugin";
 import type { Bytes } from "@simplysm/core-common";
 /**
- * File system access plugin
- * - Android 11+: Full file system access via MANAGE_EXTERNAL_STORAGE permission
- * - Android 10-: READ/WRITE_EXTERNAL_STORAGE permission
- * - Browser: IndexedDB-based emulation
+ * 파일 시스템 접근 플러그인
+ * - Android 11+: MANAGE_EXTERNAL_STORAGE 권한을 통한 전체 파일 시스템 접근
+ * - Android 10-: READ/WRITE_EXTERNAL_STORAGE 권한
+ * - Browser: IndexedDB 기반 에뮬레이션
  */
 export declare abstract class FileSystem {
     /**
-     * Check permission
+     * 권한 확인
      */
     static checkPermissions(): Promise<boolean>;
     /**
-     * Request permission
-     * - Android 11+: Navigate to settings
-     * - Android 10-: Show permission dialog
+     * 권한 요청
+     * - Android 11+: 설정 화면으로 이동
+     * - Android 10-: 권한 대화상자 표시
      */
     static requestPermissions(): Promise<void>;
     /**
-     * Read directory
+     * 디렉토리 읽기
      */
     static readdir(dirPath: string): Promise<FileInfo[]>;
     /**
-     * Get storage path
-     * @param type Storage type
-     * - external: External storage root (Environment.getExternalStorageDirectory)
-     * - externalFiles: App-specific external files directory
-     * - externalCache: App-specific external cache directory
-     * - externalMedia: App-specific external media directory
-     * - appData: App data directory
-     * - appFiles: App files directory
-     * - appCache: App cache directory
+     * 저장소 경로 조회
+     * @param type 저장소 유형
+     * - external: 외부 저장소 루트 (Environment.getExternalStorageDirectory)
+     * - externalFiles: 앱 전용 외부 파일 디렉토리
+     * - externalCache: 앱 전용 외부 캐시 디렉토리
+     * - externalMedia: 앱 전용 외부 미디어 디렉토리
+     * - appData: 앱 데이터 디렉토리
+     * - appFiles: 앱 파일 디렉토리
+     * - appCache: 앱 캐시 디렉토리
      */
     static getStoragePath(type: StorageType): Promise<string>;
     /**
-     * Get file URI (FileProvider)
+     * 파일 URI 조회 (FileProvider)
      */
     static getUri(filePath: string): Promise<string>;
     /**
-     * Write file
+     * 파일 쓰기
      */
     static writeFile(filePath: string, data: string | Bytes): Promise<void>;
     /**
-     * Read file (default: Bytes, with encoding "utf8": string)
+     * 파일 읽기 (기본: Bytes, encoding "utf8" 지정 시: string)
      */
     static readFile(filePath: string): Promise<Bytes>;
     static readFile(filePath: string, encoding: "utf8"): Promise<string>;
     /**
-     * Delete file/directory (recursive)
+     * 파일/디렉토리 삭제 (재귀)
      */
     static remove(targetPath: string): Promise<void>;
     /**
-     * Create directory (recursive)
+     * 디렉토리 생성 (재귀)
      */
     static mkdir(targetPath: string): Promise<void>;
     /**
-     * Check existence
+     * 존재 여부 확인
      */
     static exists(targetPath: string): Promise<boolean>;
 }