@simplysm/capacitor-plugin-file-system 14.0.48 → 14.0.50

package/README.md

@@ -10,45 +10,272 @@ npm install @simplysm/capacitor-plugin-file-system
 
 ## API Overview
 
-### Core File System Operations
+### `FileSystem`
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FileSystem.readdir` | function | 디렉토리의 파일/폴더 목록 조회 |
-| `FileSystem.writeFile` | function | 파일 쓰기 (문자열 또는 Bytes) |
-| `FileSystem.readFile` | function | 파일 읽기 (기본: Bytes, encoding="utf8" 시: string) |
-| `FileSystem.remove` | function | 파일/디렉토리 삭제 (재귀) |
-| `FileSystem.mkdir` | function | 디렉토리 생성 (재귀) |
-| `FileSystem.exists` | function | 파일/디렉토리 존재 여부 확인 |
+파일 시스템 접근 파사드 클래스. 모든 API는 정적 메서드로 제공됩니다.
 
-→ See [docs/file-operations.md](./docs/file-operations.md) for details.
+```typescript
+abstract class FileSystem
+```
+
+#### Members
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `checkPermissions` | static method | `() => Promise<boolean>` | 파일 시스템 접근 권한 확인 |
+| `requestPermissions` | static method | `() => Promise<void>` | 파일 시스템 접근 권한 요청 |
+| `readdir` | static method | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 파일/폴더 목록 조회 |
+| `getStoragePath` | static method | `(type: StorageType) => Promise<string>` | 저장소 유형별 경로 조회 |
+| `getUri` | static method | `(filePath: string) => Promise<string>` | 파일 URI 조회 (FileProvider / Blob URL) |
+| `writeFile` | static method | `(filePath: string, data: string \| Bytes) => Promise<void>` | 파일 쓰기 |
+| `readFile` | static method | `(filePath: string, encoding?: "utf8") => Promise<Bytes \| string>` | 파일 읽기 (오버로드) |
+| `remove` | static method | `(targetPath: string) => Promise<void>` | 파일/디렉토리 삭제 (재귀) |
+| `mkdir` | static method | `(targetPath: string) => Promise<void>` | 디렉토리 생성 (재귀) |
+| `exists` | static method | `(targetPath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인 |
+
+---
+
+#### `FileSystem.checkPermissions`
+
+```typescript
+static async checkPermissions(): Promise<boolean>
+```
+
+**Returns**: true (권한 허용), false (권한 거부)
+
+**플랫폼별 동작:**
+- **Android**: MANAGE_EXTERNAL_STORAGE 또는 READ/WRITE_EXTERNAL_STORAGE 권한 상태 확인
+- **Web**: 항상 true (권한 개념 없음)
+
+---
+
+#### `FileSystem.requestPermissions`
+
+```typescript
+static async requestPermissions(): Promise<void>
+```
+
+**플랫폼별 동작:**
+- **Android 11+ (API 30+)**: `MANAGE_EXTERNAL_STORAGE` 권한 — 설정 화면으로 이동하여 사용자가 수동 허용
+- **Android 10 이하 (API 29-)**: `READ_EXTERNAL_STORAGE` + `WRITE_EXTERNAL_STORAGE` — 표준 권한 대화상자 표시
+- **Web**: 아무 동작 없음
+
+**권한 관련 주의사항:**
+- Android 11+: `MANAGE_EXTERNAL_STORAGE`는 특수 권한으로 일반 권한 대화상자가 표시되지 않습니다. AndroidManifest.xml에 `android.permission.MANAGE_EXTERNAL_STORAGE`를 선언해야 합니다.
+- Android 10 이하: `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE`는 위험한(Dangerous) 권한으로 런타임 권한 요청이 필요합니다.
+
+---
+
+#### `FileSystem.readdir`
+
+```typescript
+static async readdir(dirPath: string): Promise<FileInfo[]>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dirPath` | string | 조회할 디렉토리의 절대 경로 |
+
+**Returns**: 디렉토리 내 파일/폴더 목록
+
+**Throws**: 디렉토리가 존재하지 않거나 허용되지 않는 경로일 경우 Error
+
+---
+
+#### `FileSystem.getStoragePath`
+
+```typescript
+static async getStoragePath(type: StorageType): Promise<string>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `StorageType` | 저장소 유형 |
+
+**Returns**: 절대 경로 문자열
+
+**StorageType별 경로:**
+
+| Type | Android Path | Web Path | 설명 |
+|------|--------------|----------|------|
+| `external` | `Environment.getExternalStorageDirectory()` | `/webfs/external` | 외부 저장소 루트 (공유 저장소) |
+| `externalFiles` | `getExternalFilesDir(null)` | `/webfs/externalFiles` | 앱 전용 외부 파일 디렉토리 |
+| `externalCache` | `externalCacheDir` | `/webfs/externalCache` | 앱 전용 외부 캐시 디렉토리 |
+| `externalMedia` | `externalMediaDirs[0]` | `/webfs/externalMedia` | 앱 전용 외부 미디어 디렉토리 |
+| `appData` | `applicationInfo.dataDir` | `/webfs/appData` | 앱 데이터 디렉토리 (내부) |
+| `appFiles` | `filesDir` | `/webfs/appFiles` | 앱 파일 디렉토리 (내부) |
+| `appCache` | `cacheDir` | `/webfs/appCache` | 앱 캐시 디렉토리 (내부) |
+
+---
+
+#### `FileSystem.getUri`
+
+```typescript
+static async getUri(filePath: string): Promise<string>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 파일의 절대 경로 |
+
+**Returns**:
+- Android: `content://` scheme의 FileProvider URI
+- Web: `blob:` scheme의 Blob URL
+
+**Web 환경 주의사항**: 반환된 Blob URL은 사용 후 반드시 `URL.revokeObjectURL(uri)`로 해제해야 합니다. 해제하지 않으면 메모리 누수가 발생합니다.
+
+---
+
+#### `FileSystem.writeFile`
+
+```typescript
+static async writeFile(filePath: string, data: string | Bytes): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 쓸 파일의 절대 경로 |
+| `data` | `string \| Bytes` | 파일 내용 (문자열 또는 Uint8Array) |
+
+**동작:**
+- 문자열인 경우: UTF-8 인코딩으로 저장 (`encoding: "utf8"`)
+- Bytes인 경우: Base64 인코딩을 중간 포맷으로 사용하여 저장 (`encoding: "base64"`)
+- 웹 환경: 상위 디렉토리가 없으면 자동 생성
 
-### Storage & Paths
+**Throws**: 쓰기 권한 없을 경우 Error
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FileSystem.getStoragePath` | function | 저장소 유형별 경로 조회 (external, externalFiles, appCache 등) |
-| `FileSystem.getUri` | function | 파일 URI 조회 (FileProvider Blob URL) |
-| `StorageType` | type | 저장소 유형 (external, externalFiles, externalCache, externalMedia, appData, appFiles, appCache) |
+---
 
-→ See [docs/storage-paths.md](./docs/storage-paths.md) for details.
+#### `FileSystem.readFile`
 
-### Permissions
+```typescript
+static async readFile(filePath: string): Promise<Bytes>;
+static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 읽을 파일의 절대 경로 |
+| `encoding` | `"utf8"` (optional) | 생략 시 `Bytes` 반환, `"utf8"` 지정 시 `string` 반환 |
+
+**Returns**:
+- `encoding` 생략: `Promise<Bytes>` (Uint8Array)
+- `encoding="utf8"`: `Promise<string>`
+
+**Throws**: 파일이 없거나 읽기 권한이 없을 경우 Error
+
+---
+
+#### `FileSystem.remove`
+
+```typescript
+static async remove(targetPath: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 삭제할 파일/디렉토리의 절대 경로 |
+
+**동작:**
+- 파일: 즉시 삭제
+- 디렉토리: 하위 파일/폴더 포함 재귀 삭제
+- 웹 환경: 경로 프리픽스로 모든 관련 항목 삭제
+
+**Throws**: 대상이 존재하지 않거나 권한 없을 경우 Error
+
+---
+
+#### `FileSystem.mkdir`
+
+```typescript
+static async mkdir(targetPath: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 생성할 디렉토리의 절대 경로 |
+
+**동작:**
+- 중간 경로가 없어도 자동 생성 (재귀)
+- 이미 존재하면 아무 동작 없음
+
+**Throws**: 권한 없을 경우 Error
+
+---
+
+#### `FileSystem.exists`
+
+```typescript
+static async exists(targetPath: string): Promise<boolean>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 확인할 파일/디렉토리의 절대 경로 |
+
+**Returns**: true (존재), false (존재하지 않음)
+
+---
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FileSystem.checkPermissions` | function | 파일 시스템 접근 권한 확인 |
-| `FileSystem.requestPermissions` | function | 파일 시스템 접근 권한 요청 |
+### `FileInfo`
 
-→ See [docs/permissions.md](./docs/permissions.md) for details.
+파일 또는 디렉토리의 정보를 나타내는 인터페이스입니다. `FileSystem.readdir()`의 반환 타입 요소입니다.
 
-### Types
+```typescript
+interface FileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FileInfo` | interface | 파일/디렉토리 정보 (name, isDirectory) |
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | 파일 또는 디렉토리의 이름 (경로 제외, 확장자 포함) |
+| `isDirectory` | boolean | true이면 디렉토리, false이면 파일 |
+
+---
+
+### `StorageType`
+
+저장소 유형을 나타내는 union type입니다.
+
+```typescript
+type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+```
 
-→ See [docs/types.md](./docs/types.md) for details.
+**선택 가이드:**
+- **내부 저장소 (앱 전용)**: `appData` (상태 데이터, 자동 백업 대상) / `appFiles` (일반 파일) / `appCache` (임시 캐시, 시스템이 삭제 가능)
+- **외부 저장소**: `external` (전체 외부 저장소, 권한 필요) / `externalFiles` (앱 전용 외부 파일, 권한 필요) / `externalCache` (앱 전용 외부 캐시, 권한 필요) / `externalMedia` (앱 전용 외부 미디어, 권한 필요)
+
+---
+
+### `FileSystemPlugin`
+
+Capacitor 플러그인 인터페이스입니다. 일반적으로 `FileSystem` 파사드를 통해 간접적으로 사용됩니다.
+
+```typescript
+interface FileSystemPlugin {
+  checkPermissions(): Promise<{ granted: boolean }>;
+  requestPermissions(): Promise<void>;
+  readdir(options: { path: string }): Promise<{ files: FileInfo[] }>;
+  getStoragePath(options: { type: StorageType }): Promise<{ path: string }>;
+  getUri(options: { path: string }): Promise<{ uri: string }>;
+  writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>;
+  readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>;
+  remove(options: { path: string }): Promise<void>;
+  mkdir(options: { path: string }): Promise<void>;
+  exists(options: { path: string }): Promise<{ exists: boolean }>;
+}
+```
+
+이 인터페이스는 내부 플러그인 구현용이며, 외부 사용자는 `FileSystem` 파사드의 정적 메서드를 사용합니다.
 
 ## Usage Examples
 
@@ -58,18 +285,13 @@ npm install @simplysm/capacitor-plugin-file-system
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
 async function readAppFile() {
-  // 권한 확인
   const hasPermission = await FileSystem.checkPermissions();
   if (!hasPermission) {
     await FileSystem.requestPermissions();
   }
 
-  // 앱 파일 디렉토리 경로 조회
   const appFilesPath = await FileSystem.getStoragePath("appFiles");
-
-  // 파일 읽기 (문자열)
   const content = await FileSystem.readFile(appFilesPath + "/config.json", "utf8");
-  console.log(content);
 }
 ```
 
@@ -77,30 +299,25 @@ async function readAppFile() {
 
 ```typescript
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-import { bytes } from "@simplysm/core-common";
 
-async function writeAppDataAsBytes() {
+async function writeImage() {
   const appCachePath = await FileSystem.getStoragePath("appCache");
-  
-  // Uint8Array로 작성
   const data = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header
   await FileSystem.writeFile(appCachePath + "/image.png", data);
 }
 ```
 
-### 디렉토리 탐색
+### 디렉토리 탐색 및 삭제
 
 ```typescript
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
-async function listDirectory(dirPath: string) {
+async function listAndClean(dirPath: string) {
   const files = await FileSystem.readdir(dirPath);
-  
   for (const file of files) {
     console.log(`${file.name} ${file.isDirectory ? "(dir)" : "(file)"}`);
   }
-  
-  // 삭제 전 존재 여부 확인
+
   const exists = await FileSystem.exists(dirPath);
   if (exists) {
     await FileSystem.remove(dirPath);
@@ -108,24 +325,20 @@ async function listDirectory(dirPath: string) {
 }
 ```
 
-### 브라우저에서 Blob URL 사용
+### 웹 환경: Blob URL 사용 후 해제
 
 ```typescript
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
 async function showImageInBrowser() {
   const appFilesPath = await FileSystem.getStoragePath("appFiles");
-  const imagePath = appFilesPath + "/photo.jpg";
-  
-  // Blob URL 획득
-  const uri = await FileSystem.getUri(imagePath);
-  
-  // DOM에서 사용
+  const uri = await FileSystem.getUri(appFilesPath + "/photo.jpg");
+
   const img = document.createElement("img");
   img.src = uri;
   document.body.appendChild(img);
-  
-  // 사용 완료 후 URL 해제 (메모리 누수 방지)
+
+  // 사용 완료 후 반드시 해제 (메모리 누수 방지)
   img.onload = () => {
     URL.revokeObjectURL(uri);
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "14.0.48",
+  "version": "14.0.50",
   "description": "심플리즘 패키지 - Capacitor 파일 시스템 플러그인",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -15,12 +15,11 @@
   "files": [
     "dist",
     "src",
-    "android",
-    "docs"
+    "android"
   ],
   "dependencies": {
-    "@simplysm/core-browser": "14.0.48",
-    "@simplysm/core-common": "14.0.48"
+    "@simplysm/core-browser": "14.0.50",
+    "@simplysm/core-common": "14.0.50"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.2"

package/docs/file-operations.md

@@ -1,154 +0,0 @@
-# File Operations
-
-## `FileSystem.readdir`
-
-디렉토리의 파일과 폴더 목록을 조회합니다.
-
-```typescript
-static async readdir(dirPath: string): Promise<FileInfo[]>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `dirPath` | string | 조회할 디렉토리의 절대 경로 |
-
-**Return**: 디렉토리 내 파일/폴더 목록 (각 항목은 name과 isDirectory 포함)
-
-**Throws**: 디렉토리가 존재하지 않거나 허용되지 않는 경로일 경우 Error
-
-```typescript
-const files = await FileSystem.readdir("/storage/emulated/0/Documents");
-for (const file of files) {
-  console.log(`${file.name} ${file.isDirectory ? "[DIR]" : ""}`);
-}
-```
-
-## `FileSystem.writeFile`
-
-파일을 작성합니다. 문자열 또는 Bytes(Uint8Array) 데이터를 지원합니다.
-
-```typescript
-static async writeFile(filePath: string, data: string | Bytes): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | string | 쓸 파일의 절대 경로 |
-| `data` | string \| Bytes | 파일 내용 (문자열 또는 Uint8Array) |
-
-**Behavior**:
-- 문자열인 경우: UTF-8 인코딩으로 저장 (encoding: "utf8")
-- Bytes인 경우: Base64 인코딩으로 저장 (encoding: "base64")
-- 상위 디렉토리가 없으면 자동 생성 (웹 환경에서만)
-
-**Throws**: 쓰기 권한 없을 경우 Error
-
-```typescript
-// 문자열 쓰기
-await FileSystem.writeFile("/storage/emulated/0/Documents/notes.txt", "Hello, World!");
-
-// Bytes 쓰기 (예: PNG 이미지)
-const pngData = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-await FileSystem.writeFile("/storage/emulated/0/Pictures/image.png", pngData);
-```
-
-## `FileSystem.readFile`
-
-파일을 읽습니다. 기본적으로 Bytes를 반환하며, encoding 파라미터로 문자열 반환을 지정할 수 있습니다.
-
-```typescript
-static async readFile(filePath: string): Promise<Bytes>;
-static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | string | 읽을 파일의 절대 경로 |
-| `encoding` | "utf8" (optional) | "utf8"일 경우 string 반환, 생략 시 Bytes 반환 |
-
-**Return**:
-- encoding 생략: `Promise<Bytes>` (Uint8Array)
-- encoding="utf8": `Promise<string>`
-
-**Throws**: 파일이 없거나 읽기 권한이 없을 경우 Error
-
-```typescript
-// Bytes로 읽기 (기본)
-const imageData = await FileSystem.readFile("/storage/emulated/0/Pictures/photo.jpg");
-console.log(imageData instanceof Uint8Array); // true
-
-// 문자열로 읽기
-const config = await FileSystem.readFile("/storage/emulated/0/Documents/config.json", "utf8");
-const obj = JSON.parse(config);
-```
-
-## `FileSystem.remove`
-
-파일 또는 디렉토리를 삭제합니다. 디렉토리인 경우 재귀적으로 삭제됩니다.
-
-```typescript
-static async remove(targetPath: string): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetPath` | string | 삭제할 파일/디렉토리의 절대 경로 |
-
-**Behavior**:
-- 파일: 즉시 삭제
-- 디렉토리: 하위의 모든 파일/폴더 포함하여 재귀 삭제
-- 웹 환경: 경로 프리픽스로 모든 관련 항목 삭제
-
-**Throws**: 대상이 존재하지 않거나 권한 없을 경우 Error
-
-```typescript
-// 파일 삭제
-await FileSystem.remove("/storage/emulated/0/Documents/temp.txt");
-
-// 디렉토리 재귀 삭제
-await FileSystem.remove("/storage/emulated/0/Documents/old_backup");
-```
-
-## `FileSystem.mkdir`
-
-디렉토리를 생성합니다. 상위 경로가 없는 경우 자동으로 생성됩니다 (재귀 생성).
-
-```typescript
-static async mkdir(targetPath: string): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetPath` | string | 생성할 디렉토리의 절대 경로 |
-
-**Behavior**:
-- 중간 경로가 없어도 자동 생성
-- 이미 존재하면 아무 동작 없음
-
-**Throws**: 권한 없을 경우 Error
-
-```typescript
-// 중간 경로 자동 생성
-await FileSystem.mkdir("/storage/emulated/0/Documents/projects/2025/Q1");
-```
-
-## `FileSystem.exists`
-
-파일 또는 디렉토리의 존재 여부를 확인합니다.
-
-```typescript
-static async exists(targetPath: string): Promise<boolean>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetPath` | string | 확인할 파일/디렉토리의 절대 경로 |
-
-**Return**: true (존재), false (존재하지 않음)
-
-```typescript
-const exists = await FileSystem.exists("/storage/emulated/0/Documents/config.json");
-if (!exists) {
-  await FileSystem.writeFile("/storage/emulated/0/Documents/config.json", "{}");
-}
-```

package/docs/permissions.md

@@ -1,84 +0,0 @@
-# Permissions
-
-## `FileSystem.checkPermissions`
-
-파일 시스템 접근 권한 여부를 확인합니다.
-
-```typescript
-static async checkPermissions(): Promise<boolean>
-```
-
-**Return**: true (권한 허용), false (권한 거부)
-
-**플랫폼별 동작**:
-- **Android**: 현재 권한 상태 확인 (MANAGE_EXTERNAL_STORAGE 또는 READ/WRITE_EXTERNAL_STORAGE)
-- **Web**: 항상 true (권한 개념 없음)
-
-```typescript
-const hasPermission = await FileSystem.checkPermissions();
-if (hasPermission) {
-  // 파일 접근 가능
-  const files = await FileSystem.readdir("/storage/emulated/0/Documents");
-} else {
-  // 권한 요청 필요
-  await FileSystem.requestPermissions();
-}
-```
-
-## `FileSystem.requestPermissions`
-
-파일 시스템 접근 권한을 요청합니다.
-
-```typescript
-static async requestPermissions(): Promise<void>
-```
-
-**플랫폼별 동작**:
-- **Android 11+ (API 30+)**:
-  - `MANAGE_EXTERNAL_STORAGE` 권한 요청
-  - 설정 화면으로 이동하여 사용자가 수동으로 허용
-  - 권한 대화상자가 표시되지 않음
-- **Android 10 이하 (API 29-)**:
-  - `READ_EXTERNAL_STORAGE` + `WRITE_EXTERNAL_STORAGE` 요청
-  - 표준 권한 대화상자 표시
-- **Web**: 아무 동작 없음
-
-```typescript
-async function ensureFileSystemAccess() {
-  const hasPermission = await FileSystem.checkPermissions();
-  
-  if (!hasPermission) {
-    try {
-      await FileSystem.requestPermissions();
-      console.log("Permission granted");
-    } catch (error) {
-      console.error("Permission request failed:", error);
-    }
-  }
-}
-
-// 앱 시작 시 권한 확인
-await ensureFileSystemAccess();
-
-// 외부 저장소 접근
-const externalPath = await FileSystem.getStoragePath("external");
-const files = await FileSystem.readdir(externalPath);
-```
-
-## 권한 관련 주의사항
-
-### Android 11+ (Scoped Storage)
-
-- `MANAGE_EXTERNAL_STORAGE` 권한은 특수 권한이며, 일반 권한 대화상자로 요청할 수 없습니다.
-- 권한 요청 시 설정 앱으로 이동하므로 사용자가 직접 허용/거부를 선택해야 합니다.
-- AndroidManifest.xml에 `android.permission.MANAGE_EXTERNAL_STORAGE`를 선언해야 합니다.
-
-### Android 10 이하
-
-- `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE` 권한이 필요합니다.
-- 이 권한들은 위험한(Dangerous) 권한으로 분류되어 런타임 권한 요청이 필요합니다.
-
-### 웹 환경
-
-- 권한 개념이 없으며, IndexedDB 기반 가상 파일 시스템을 사용합니다.
-- 사용자는 브라우저 저장소 한도에만 제한됩니다.

package/docs/storage-paths.md

@@ -1,107 +0,0 @@
-# Storage & Paths
-
-## `FileSystem.getStoragePath`
-
-저장소 유형별로 기기의 실제 경로(Android) 또는 가상 경로(웹)를 반환합니다.
-
-```typescript
-static async getStoragePath(type: StorageType): Promise<string>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `type` | StorageType | 저장소 유형 |
-
-**Return**: 절대 경로 문자열
-
-**StorageType 종류**:
-
-| Type | Android Path | Web Path | 설명 |
-|------|--------------|----------|------|
-| `external` | `Environment.getExternalStorageDirectory()` | `/webfs/external` | 외부 저장소 루트 (공유 저장소) |
-| `externalFiles` | `getExternalFilesDir(null)` | `/webfs/externalFiles` | 앱 전용 외부 파일 디렉토리 |
-| `externalCache` | `externalCacheDir` | `/webfs/externalCache` | 앱 전용 외부 캐시 디렉토리 |
-| `externalMedia` | `externalMediaDirs[0]` | `/webfs/externalMedia` | 앱 전용 외부 미디어 디렉토리 |
-| `appData` | `applicationInfo.dataDir` | `/webfs/appData` | 앱 데이터 디렉토리 (내부) |
-| `appFiles` | `filesDir` | `/webfs/appFiles` | 앱 파일 디렉토리 (내부) |
-| `appCache` | `cacheDir` | `/webfs/appCache` | 앱 캐시 디렉토리 (내부) |
-
-```typescript
-// 앱 캐시 디렉토리에 임시 파일 작성
-const cachePath = await FileSystem.getStoragePath("appCache");
-await FileSystem.writeFile(cachePath + "/temp.dat", "temporary data");
-
-// 외부 파일 디렉토리에 문서 저장
-const filesPath = await FileSystem.getStoragePath("externalFiles");
-await FileSystem.mkdir(filesPath + "/documents");
-await FileSystem.writeFile(filesPath + "/documents/report.pdf", pdfBytes);
-```
-
-## `FileSystem.getUri`
-
-파일의 URI를 조회합니다. 주로 Blob URL(웹) 또는 FileProvider URI(Android)로 반환됩니다.
-
-```typescript
-static async getUri(filePath: string): Promise<string>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | string | 파일의 절대 경로 |
-
-**Return**: URI 문자열
-- Android: `content://` scheme의 FileProvider URI
-- Web: `blob://` scheme의 Blob URL
-
-**Web 환경 주의사항**:
-반환된 Blob URL은 사용 후 반드시 `URL.revokeObjectURL(uri)`로 해제해야 합니다. 해제하지 않으면 메모리 누수가 발생할 수 있습니다.
-
-```typescript
-// 웹 환경: Blob URL 사용 후 해제
-const imagePath = await FileSystem.getStoragePath("appFiles");
-const imageFile = imagePath + "/photo.jpg";
-
-const uri = await FileSystem.getUri(imageFile);
-
-const img = document.createElement("img");
-img.src = uri;
-img.onload = () => {
-  URL.revokeObjectURL(uri); // 메모리 해제
-};
-
-// Android 환경: FileProvider URI를 다른 앱과 공유
-const documentPath = await FileSystem.getStoragePath("externalFiles");
-const documentFile = documentPath + "/report.pdf";
-const contentUri = await FileSystem.getUri(documentFile);
-
-// contentUri를 Intent의 data로 사용하여 다른 앱 실행
-const intent = new Intent(Intent.ACTION_VIEW);
-intent.setDataAndType(Uri.parse(contentUri), "application/pdf");
-startActivity(intent);
-```
-
-## `StorageType`
-
-저장소 유형을 나타내는 union type입니다.
-
-```typescript
-type StorageType =
-  | "external"
-  | "externalFiles"
-  | "externalCache"
-  | "externalMedia"
-  | "appData"
-  | "appFiles"
-  | "appCache";
-```
-
-**사용 가이드**:
-- **내부 저장소 (앱 전용)**:
-  - `appData`: 앱 상태 데이터 (자동 백업 대상)
-  - `appFiles`: 일반 파일 저장
-  - `appCache`: 임시 캐시 (시스템이 필요 시 삭제 가능)
-- **외부 저장소 (공유 또는 앱 전용)**:
-  - `external`: 전체 외부 저장소 (권한 필요)
-  - `externalFiles`: 앱 전용 외부 파일 (권한 필요)
-  - `externalCache`: 앱 전용 외부 캐시 (권한 필요)
-  - `externalMedia`: 앱 전용 외부 미디어 (권한 필요)

package/docs/types.md

@@ -1,83 +0,0 @@
-# Types
-
-## `FileInfo`
-
-파일 또는 디렉토리의 정보를 나타내는 인터페이스입니다.
-
-```typescript
-interface FileInfo {
-  name: string;
-  isDirectory: boolean;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | 파일 또는 디렉토리의 이름 (경로 제외, 확장자 포함) |
-| `isDirectory` | boolean | true일 경우 디렉토리, false일 경우 파일 |
-
-```typescript
-// 디렉토리 읽기 결과
-const files = await FileSystem.readdir("/storage/emulated/0/Documents");
-
-// FileInfo 배열 처리
-for (const file of files) {
-  if (file.isDirectory) {
-    console.log(`📁 ${file.name} (directory)`);
-  } else {
-    console.log(`📄 ${file.name} (file)`);
-  }
-}
-```
-
-## `FileSystemPlugin`
-
-Capacitor 플러그인 인터페이스입니다. 일반적으로 `FileSystem` 파사드를 통해 간접적으로 사용됩니다.
-
-```typescript
-interface FileSystemPlugin {
-  checkPermissions(): Promise<{ granted: boolean }>;
-  requestPermissions(): Promise<void>;
-  readdir(options: { path: string }): Promise<{ files: FileInfo[] }>;
-  getStoragePath(options: { type: StorageType }): Promise<{ path: string }>;
-  getUri(options: { path: string }): Promise<{ uri: string }>;
-  writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>;
-  readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>;
-  remove(options: { path: string }): Promise<void>;
-  mkdir(options: { path: string }): Promise<void>;
-  exists(options: { path: string }): Promise<{ exists: boolean }>;
-}
-```
-
-**참고**: 이 인터페이스는 내부 플러그인 구현용이며, 외부 사용자는 `FileSystem` 파사드의 정적 메서드를 사용합니다.
-
-## `Bytes`
-
-이 패키지에서는 `@simplysm/core-common`의 `Bytes` 타입(Uint8Array의 별칭)을 사용합니다.
-
-```typescript
-import type { Bytes } from "@simplysm/core-common";
-import { bytes } from "@simplysm/core-common";
-
-// Bytes = Uint8Array
-const data: Bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
-
-// Base64 변환 유틸리티
-const base64Str = bytes.toBase64(data);      // Bytes → Base64 문자열
-const bytesData = bytes.fromBase64(base64Str); // Base64 문자열 → Bytes
-```
-
-## `StorageType`
-
-저장소 유형 union type입니다. 자세한 설명은 [storage-paths.md](./storage-paths.md)를 참조하세요.
-
-```typescript
-type StorageType =
-  | "external"
-  | "externalFiles"
-  | "externalCache"
-  | "externalMedia"
-  | "appData"
-  | "appFiles"
-  | "appCache";
-```