@simplysm/capacitor-plugin-usb-storage 13.0.93 → 13.0.96

package/README.md

@@ -1,6 +1,7 @@
 # @simplysm/capacitor-plugin-usb-storage
 
 Capacitor USB Mass Storage 플러그인. Android에서 USB 저장장치를 열거하고, 권한을 관리하며, 파일을 읽는다.
+Web 환경에서는 IndexedDB 기반 가상 USB 스토리지를 제공하여 개발/테스트를 지원한다.
 
 ## 설치
 
@@ -12,18 +13,12 @@ npm install @simplysm/capacitor-plugin-usb-storage
 **Peer:** `@capacitor/core` ^7.4.4
 **Android 네이티브:** `me.jahnen:libaums:core:0.9.1` (USB Mass Storage 라이브러리)
 
-## Export 목록
-
-```typescript
-// index.ts
-export type { UsbStoragePlugin, UsbDeviceInfo, UsbDeviceFilter, UsbFileInfo } from "./UsbStoragePlugin";
-export { UsbStorage } from "./UsbStorage";
-```
-
-## 주요 사용법
+## 주요 기능
 
 ### 기기 목록 조회
 
+연결된 USB Mass Storage 기기 목록을 반환한다.
+
 ```typescript
 import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
 
@@ -40,6 +35,7 @@ const devices = await UsbStorage.getDevices();
 ### 권한 관리
 
 기기별로 `vendorId`/`productId` 조합으로 권한을 확인/요청한다.
+Android에서는 시스템 권한 다이얼로그가 표시되며, Web에서는 항상 granted를 반환한다.
 
 ```typescript
 import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
@@ -54,6 +50,8 @@ if (!granted) {
 
 ### 디렉토리 읽기
 
+USB 저장장치의 지정 경로에 있는 파일/폴더 목록을 반환한다.
+
 ```typescript
 const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
 
@@ -63,16 +61,16 @@ const files = await UsbStorage.readdir(filter, "/documents");
 
 ### 파일 읽기
 
+USB 저장장치에서 파일을 읽어 `Bytes`(Uint8Array)로 반환한다. 파일이 없으면 `undefined`를 반환한다.
+Android에서 최대 파일 크기는 100MB이다.
+
 ```typescript
 import type { Bytes } from "@simplysm/core-common";
 
 const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
 const data: Bytes | undefined = await UsbStorage.readFile(filter, "/documents/report.pdf");
-// 파일이 없으면 undefined, 있으면 Bytes (Uint8Array)
 ```
 
-Android에서 최대 파일 크기는 100MB이다.
-
 ## API 레퍼런스
 
 ### `UsbStorage` (abstract class, static 메서드)
@@ -131,9 +129,7 @@ interface UsbFileInfo {
 ```typescript
 import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
 
-// Web 환경에서만 UsbStorageWeb 인스턴스의 메서드를 직접 호출해야 함
-// 일반적으로 Capacitor plugin 등록 시 자동으로 Web 구현체가 사용됨
-
+// UsbStorageWeb 인스턴스에 직접 접근하여 가상 기기를 구성한다
 // 가상 기기 추가
 await usbStorageWeb.addVirtualDevice({
   vendorId: 1234,
@@ -151,6 +147,14 @@ await usbStorageWeb.addVirtualFile(filter, "/test.txt", new Uint8Array([72, 101,
 await usbStorageWeb.addVirtualDirectory(filter, "/docs");
 ```
 
+### `UsbStorageWeb` 테스트 전용 메서드
+
+| 메서드 | 시그니처 | 설명 |
+|--------|----------|------|
+| `addVirtualDevice` | `(device: { vendorId, productId, deviceName, manufacturerName, productName }) => Promise<void>` | 가상 USB 기기 추가 |
+| `addVirtualFile` | `(filter: UsbDeviceFilter, filePath: string, data: Uint8Array) => Promise<void>` | 가상 파일 추가 |
+| `addVirtualDirectory` | `(filter: UsbDeviceFilter, dirPath: string) => Promise<void>` | 가상 디렉토리 추가 |
+
 Web 가상 스토리지는 `VirtualUsbStorage` 클래스를 사용하며, IndexedDB(`capacitor_usb_virtual_storage`)에 기기와 파일 데이터를 저장한다.
 - 스토어: `devices` (keyPath: `key`, key = `vendorId:productId`), `files` (keyPath: `fullKey`, fullKey = `deviceKey:path`)
 
@@ -158,7 +162,7 @@ Web 가상 스토리지는 `VirtualUsbStorage` 클래스를 사용하며, Indexe
 
 - **패키지:** `kr.co.simplysm.capacitor.usbstorage`
 - **플러그인명:** `UsbStorage`
-- **라이브러리:** `me.jahnen:libaums:core:0.9.1`
+- **라이브러리:** `me.jahnen.libaums:core:0.9.1`
 - `getDevices`: `UsbMassStorageDevice.getMassStorageDevices(context)`
 - `requestPermissions`: `UsbManager.requestPermission` + BroadcastReceiver 콜백 (Android 13+: `RECEIVER_NOT_EXPORTED`, Android 12+: `PendingIntent.FLAG_MUTABLE`)
 - `readdir`/`readFile`: 기기 init -> 첫 번째 파티션의 FileSystem -> `root.search(path)` -> 작업 -> `device.close()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-usb-storage",
-  "version": "13.0.93",
+  "version": "13.0.96",
   "description": "Simplysm Package - Capacitor USB Storage Plugin",
   "author": "simplysm",
   "license": "MIT",
@@ -18,8 +18,8 @@
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-browser": "13.0.93",
-    "@simplysm/core-common": "13.0.93"
+    "@simplysm/core-browser": "13.0.96",
+    "@simplysm/core-common": "13.0.96"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.0"