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

package/README.md

@@ -0,0 +1,125 @@
+# @simplysm/capacitor-plugin-usb-storage
+
+Capacitor USB mass storage plugin using the libaums library on Android.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-usb-storage
+```
+
+## API Overview
+
+### USB Storage
+
+| API | Type | Description |
+|-----|------|-------------|
+| `UsbDeviceInfo` | Interface | Metadata about a connected USB mass storage device |
+| `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
+
+### UsbDeviceInfo
+
+Metadata about a connected USB mass storage device.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `deviceName` | `string` | System-assigned device name |
+| `manufacturerName` | `string` | USB device manufacturer name |
+| `productName` | `string` | USB device product name |
+| `vendorId` | `number` | USB vendor ID |
+| `productId` | `number` | USB product ID |
+
+### UsbDeviceFilter
+
+Identifies a specific USB device by its vendor and product IDs. Used as a parameter for all device-specific operations.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `vendorId` | `number` | USB vendor ID of the target device |
+| `productId` | `number` | USB product ID of the target device |
+
+### UsbFileInfo
+
+Metadata for a single file or directory entry on a USB storage device.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Name of the file or directory |
+| `isDirectory` | `boolean` | `true` if the entry is a directory |
+
+### UsbStoragePlugin
+
+Native plugin interface for USB storage operations.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getDevices` | `() => Promise<{ devices: UsbDeviceInfo[] }>` | List all connected USB mass storage devices |
+| `requestPermissions` | `(options: UsbDeviceFilter) => Promise<{ granted: boolean }>` | Request permission to access a specific USB device |
+| `checkPermissions` | `(options: UsbDeviceFilter) => Promise<{ granted: boolean }>` | Check if permission is granted for a specific USB device |
+| `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
+
+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.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getDevices` | `static async getDevices(): Promise<UsbDeviceInfo[]>` | List all connected USB mass storage devices |
+| `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. |
+
+## Usage Examples
+
+### Discover and access a USB device
+
+```ts
+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");
+}
+
+const device = devices[0];
+const filter = { vendorId: device.vendorId, productId: device.productId };
+
+// Request permission
+const granted = await UsbStorage.requestPermissions(filter);
+if (!granted) {
+  throw new Error("USB 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);
+}
+```

package/package.json

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