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

package/README.md

@@ -0,0 +1,134 @@
+# @simplysm/capacitor-plugin-file-system
+
+Capacitor file system plugin with full storage access on Android 11+.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-file-system
+```
+
+## API Overview
+
+### File System
+
+| API | Type | Description |
+|-----|------|-------------|
+| `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";
+```
+
+| 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` | Name of the file or directory |
+| `isDirectory` | `boolean` | `true` if the entry is a directory |
+
+### FileSystemPlugin
+
+Native plugin interface for file system operations.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `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
+
+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.
+
+All methods are static.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `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
+
+```ts
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+// Ensure permissions
+const granted = await FileSystem.checkPermissions();
+if (!granted) {
+  await FileSystem.requestPermissions();
+}
+
+// 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
+
+```ts
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+const dirPath = "/storage/emulated/0/MyApp/data/logs";
+
+if (!(await FileSystem.exists(dirPath))) {
+  await FileSystem.mkdir(dirPath);
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "14.0.1",
+  "version": "14.0.4",
   "description": "심플리즘 패키지 - Capacitor 파일 시스템 플러그인",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -18,11 +18,11 @@
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-browser": "14.0.1",
-    "@simplysm/core-common": "14.0.1"
+    "@simplysm/core-browser": "14.0.4",
+    "@simplysm/core-common": "14.0.4"
   },
   "devDependencies": {
-    "@capacitor/core": "^7.6.0"
+    "@capacitor/core": "^7.6.1"
   },
   "peerDependencies": {
     "@capacitor/core": "^7"