@simplysm/capacitor-plugin-usb-storage 14.0.4 → 14.0.6

package/README.md

@@ -1,6 +1,9 @@
 # @simplysm/capacitor-plugin-usb-storage
 
-Capacitor USB mass storage plugin using the libaums library on Android.
+Capacitor plugin for accessing USB mass storage devices on Android.
+
+- **Android**: USB Mass Storage access via the libaums library
+- **Browser**: IndexedDB-based virtual USB storage emulation for development
 
 ## Installation
 
@@ -10,7 +13,7 @@ npm install @simplysm/capacitor-plugin-usb-storage
 
 ## API Overview
 
-### USB Storage
+### Interfaces
 
 | API | Type | Description |
 |-----|------|-------------|
@@ -18,14 +21,27 @@ npm install @simplysm/capacitor-plugin-usb-storage
 | `UsbDeviceFilter` | Interface | Vendor/product ID pair used to target a specific USB device |
 | `UsbFileInfo` | Interface | File entry metadata from a USB storage directory listing |
 | `UsbStoragePlugin` | Interface | Native plugin interface for USB storage operations |
-| `UsbStorage` | Class | Static API for USB mass storage access |
 
-## Interfaces
+### Classes
 
-### UsbDeviceInfo
+| API | Type | Description |
+|-----|------|-------------|
+| `UsbStorage` | Class | Static API for USB mass storage access |
+
+## `UsbDeviceInfo`
 
 Metadata about a connected USB mass storage device.
 
+```typescript
+interface UsbDeviceInfo {
+  deviceName: string;
+  manufacturerName: string;
+  productName: string;
+  vendorId: number;
+  productId: number;
+}
+```
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `deviceName` | `string` | System-assigned device name |
@@ -34,27 +50,51 @@ Metadata about a connected USB mass storage device.
 | `vendorId` | `number` | USB vendor ID |
 | `productId` | `number` | USB product ID |
 
-### UsbDeviceFilter
+## `UsbDeviceFilter`
 
 Identifies a specific USB device by its vendor and product IDs. Used as a parameter for all device-specific operations.
 
+```typescript
+interface UsbDeviceFilter {
+  vendorId: number;
+  productId: number;
+}
+```
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `vendorId` | `number` | USB vendor ID of the target device |
 | `productId` | `number` | USB product ID of the target device |
 
-### UsbFileInfo
+## `UsbFileInfo`
 
 Metadata for a single file or directory entry on a USB storage device.
 
+```typescript
+interface UsbFileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `name` | `string` | Name of the file or directory |
 | `isDirectory` | `boolean` | `true` if the entry is a directory |
 
-### UsbStoragePlugin
+## `UsbStoragePlugin`
+
+Native plugin interface for USB storage operations. Use the `UsbStorage` class for a simplified API.
 
-Native plugin interface for USB storage operations.
+```typescript
+interface UsbStoragePlugin {
+  getDevices(): Promise<{ devices: UsbDeviceInfo[] }>;
+  requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
+  checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
+  readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>;
+  readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>;
+}
+```
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
@@ -64,13 +104,19 @@ Native plugin interface for USB storage operations.
 | `readdir` | `(options: UsbDeviceFilter & { path: string }) => Promise<{ files: UsbFileInfo[] }>` | List files in a directory on the USB device |
 | `readFile` | `(options: UsbDeviceFilter & { path: string }) => Promise<{ data: string \| null }>` | Read a file from the USB device as a base64 string |
 
-## Classes
+## `UsbStorage`
 
-### UsbStorage
+Abstract class with static methods for USB storage operations. On Android it uses the libaums library for direct USB communication. On the browser it falls back to IndexedDB-based virtual USB storage emulation.
 
-USB mass storage access plugin. On Android it uses the libaums library for direct USB communication. On the browser it falls back to IndexedDB-based virtual USB storage emulation.
-
-All methods are static.
+```typescript
+abstract class UsbStorage {
+  static async getDevices(): Promise<UsbDeviceInfo[]>;
+  static async requestPermissions(filter: UsbDeviceFilter): Promise<boolean>;
+  static async checkPermissions(filter: UsbDeviceFilter): Promise<boolean>;
+  static async readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>;
+  static async readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>;
+}
+```
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
@@ -78,19 +124,19 @@ All methods are static.
 | `requestPermissions` | `static async requestPermissions(filter: UsbDeviceFilter): Promise<boolean>` | Request permission to access the specified USB device. Returns `true` if granted. |
 | `checkPermissions` | `static async checkPermissions(filter: UsbDeviceFilter): Promise<boolean>` | Check if permission is granted for the specified USB device |
 | `readdir` | `static async readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>` | List files and directories at the given path on the USB device |
-| `readFile` | `static async readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes \| undefined>` | Read a file from the USB device. Returns `Bytes` on success, `undefined` if the file does not exist or data is null. |
+| `readFile` | `static async readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes \| undefined>` | Read a file from the USB device. Returns `Bytes` on success, `undefined` if the file data is null. |
 
 ## Usage Examples
 
 ### Discover and access a USB device
 
-```ts
+```typescript
 import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
 
 // List connected USB devices
 const devices = await UsbStorage.getDevices();
 if (devices.length === 0) {
-  throw new Error("No USB storage device connected");
+  return; // No USB devices connected
 }
 
 const device = devices[0];
@@ -99,27 +145,17 @@ const filter = { vendorId: device.vendorId, productId: device.productId };
 // Request permission
 const granted = await UsbStorage.requestPermissions(filter);
 if (!granted) {
-  throw new Error("USB permission denied");
+  return; // Permission denied
 }
 
 // List root directory
 const files = await UsbStorage.readdir(filter, "/");
 for (const file of files) {
-  console.log(`${file.name} (${file.isDirectory ? "dir" : "file"})`);
-}
-```
-
-### Read a file from USB storage
-
-```ts
-import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
-
-const filter = { vendorId: 0x1234, productId: 0x5678 };
-
-const data = await UsbStorage.readFile(filter, "/data/export.csv");
-if (data !== undefined) {
-  // Convert Bytes to string for text files
-  const text = new TextDecoder().decode(data);
-  processCSV(text);
+  if (!file.isDirectory) {
+    const data = await UsbStorage.readFile(filter, `/${file.name}`);
+    if (data !== undefined) {
+      // process binary data
+    }
+  }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-usb-storage",
-  "version": "14.0.4",
+  "version": "14.0.6",
   "description": "심플리즘 패키지 - Capacitor USB 저장소 플러그인",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -18,8 +18,8 @@
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-common": "14.0.4",
-    "@simplysm/core-browser": "14.0.4"
+    "@simplysm/core-browser": "14.0.6",
+    "@simplysm/core-common": "14.0.6"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.1"