@mcesystems/adb-kit 1.0.91 → 1.0.93

package/README.md

@@ -1,230 +1,230 @@
-# @mcesystems/adb-kit
-
-## 1. Description
-
-**What it does:** ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations: listing devices, reading device properties, installing/uninstalling apps, checking and waiting for USB debugging, and port forwarding.
-
-**When it's used:** Use this package when your application needs to communicate with Android devices over ADB—for example device management tools, test runners, or installers that target Android hardware.
-
-## 2. Install
-
-```bash
-npm install @mcesystems/adb-kit
-```
-
-**Requirements:** Node.js 18+, Android device with USB debugging enabled, and ADB binaries (see Resources).
-
-## 3. Resources
-
-This package needs ADB binaries to run. You can obtain them in one of these ways:
-
-**Option A – Export script (recommended for distribution)**  
-Bundle ADB for your app using the provided script:
-
-```bash
-npx export-adb-resources /path/to/your-app/resources/adb-kit
-
-# All platforms
-npx export-adb-resources /path/to/your-app/resources/adb-kit --all
-```
-
-See [scripts/README.md](./scripts/README.md) for arguments, options, output layout, and prerequisites.
-
-**Option B – Development**  
-- **Windows / macOS:** Set `AdbBinPath` to your ADB binary directory, or have `adb` on system PATH.  
-- **Linux:** Install via package manager (e.g. `sudo apt install adb`).
-
-The package resolves ADB in this order: `AdbBinPath` env, then bundled resources under `dist/resources/bin/<platform>/`, then system PATH.
-
-## 4. Examples
-
-**Create a device kit and read properties**
-
-```typescript
-import { AdbDeviceKit } from '@mcesystems/adb-kit';
-
-const device = new AdbDeviceKit('device-serial-number', 1);
-const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
-const allProps = await device.getAllDeviceProperties();
-const devices = await device.listDevices();
-```
-
-**Install/uninstall and check app**
-
-```typescript
-await device.installApp('/path/to/app.apk');
-const isInstalled = await device.isAppInstalled('com.example.app');
-await device.uninstallApp('com.example.app');
-```
-
-**USB debugging**
-
-```typescript
-const hasDebugging = await device.hasUsbDebugging();
-const { promise, events } = device.waitForUsbDebugging(30000); // 30s timeout
-events.on("usbDebuggingOff", () => console.log("Enable USB debugging on device"));
-events.on("usbDebuggingNeedsAlwaysAllow", () => console.log("Tap Always allow on device"));
-events.on("usbDebuggingAuthorized", () => console.log("Device ready"));
-const ok = await promise;
-```
-
-**Port forwarding**
-
-```typescript
-const localPort = await device.startPortForward('tcp:8080');
-```
-
-**Low-level clients**
-
-```typescript
-const client = await device.getClient();
-const deviceClient = await device.getDeviceClient();
-```
-
-**First connected Android properties**
-
-One-shot example that discovers the first connected Android device and prints a curated set of its properties (manufacturer, model, brand, Android version, etc.).
-
-```bash
-# From packages/adb-kit
-pnpm example:first-android-properties
-```
-
-See [src/examples/first-connected-android-properties.ts](./src/examples/first-connected-android-properties.ts) for the script.
-
-**USB debugging robustness example**
-
-Interactive example that runs the same flow 5 times to verify `waitForUsbDebugging` handling: start without USB debugging (device not found), short 5s timeout (user lets it pass), then wait up to 30s while the user enables USB debugging, show device recognized, then user disables USB debugging and repeats.
-
-```bash
-# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
-pnpm example:usb-debugging
-```
-
-See [src/examples/usb-debugging-robustness.ts](./src/examples/usb-debugging-robustness.ts) for the script.
-
-**USB debugging playground**
-
-Interactive playground to observe status events while you toggle USB debugging on/off or revoke authorizations. Prints events in real time as you change device settings.
-
-```bash
-# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
-pnpm example:usb-debugging-playground
-```
-
-See [src/examples/usb-debugging-playground.ts](./src/examples/usb-debugging-playground.ts) for the script.
-
-For more scenarios and step-by-step explanations, see [Example.md](./Example.md).
-
-## 5. API
-
-### AdbDeviceKit
-
-**Constructor**
-
-- **Input:** `deviceId: string`, `port: number`
-- **Output:** new `AdbDeviceKit` instance bound to that device and logical port.
-
-**listDevices()**
-
-- **Input:** none
-- **Output:** `Promise<AdbDevice[]>` — list of connected devices (`AdbDevice`: `{ id: string; type: AdbDeviceType }`).
-
-**getDeviceProperties(properties)**
-
-- **Input:** `properties: DeviceProperty[]` — e.g. `['Manufacturer', 'Model']`
-- **Output:** `Promise<string[]>` — values in the same order as `properties`; failed props are `""`.
-
-**getAllDeviceProperties()**
-
-- **Input:** none
-- **Output:** `Promise<Record<string, string>>` — all device properties from `getprop`.
-
-**installApp(appPath)**
-
-- **Input:** `appPath: string` — path to APK
-- **Output:** `Promise<void>` — resolves when install finishes; rejects on failure.
-
-**uninstallApp(packageName)**
-
-- **Input:** `packageName: string` — e.g. `'com.example.app'`
-- **Output:** `Promise<void>` — resolves when uninstall finishes; rejects on failure.
-
-**isAppInstalled(packageName)**
-
-- **Input:** `packageName: string`
-- **Output:** `Promise<boolean>` — whether the package is installed.
-
-**hasUsbDebugging()**
-
-- **Input:** none
-- **Output:** `Promise<boolean>` — whether this device appears in the ADB device list.
-
-**waitForUsbDebugging(timeout?, numberOfAllowedAttempts?)**
-
-- **Input:** `timeout?: number` (default `120000` ms), `numberOfAllowedAttempts?: number` (default `5`, accepted for backward compatibility; give-up is determined by timeout and tracker end only)
-- **Output:** `{ promise: Promise<boolean>; events: EventEmitter }` — await `promise` for the result (`true` when device is ready, `false` when tracking ends without device; rejects on timeout, device removal, or connection error). Subscribe to `events` for state changes:
-  - `usbDebuggingOff` — waiting started (USB debugging not enabled on device)
-  - `usbDebuggingNeedsAlwaysAllow` — device visible but user must tap "Always allow" on device
-  - `usbDebuggingAuthorized` — device ready
-
-**startPortForward(serviceName)**
-
-- **Input:** `serviceName: string` — e.g. `'tcp:8080'`
-- **Output:** `Promise<number | null>` — local port number used for forwarding, or `null` if forwarding failed. Reuses same port on repeated calls.
-
-**getClient()**
-
-- **Input:** none
-- **Output:** `Promise<AdbClient>` — underlying adbkit client.
-
-**getDeviceClient()**
-
-- **Input:** none
-- **Output:** `Promise<DeviceClient>` — adbkit device client for this device.
-
-**getDeviceId()**
-
-- **Input:** none
-- **Output:** `string` — device serial (last segment after `\` on Windows).
-
-**getPort()**
-
-- **Input:** none
-- **Output:** `number` — logical port passed to the constructor.
-
-### DeviceProperty
-
-Supported property names for `getDeviceProperties()`:  
-`Manufacturer`, `Name`, `Model`, `Brand`, `Device`, `Android Version`, `Platform`, `CPU`, `CPU.abi2`, `Description`, `Fingerprint`, `GSM Flexversion`, `GSM IMEI`, `Locale Language`, `Locale Region`, `Wifi Channels`, `Board Platform`, `Product Board`, `Display ID`, `Version Incremental`, `Version SDK`, `Version Codename`, `Version Release`, `Build Date`, `Build Type`, `Build User`.
-
-## 6. Flow
-
-Example flow: wait for device, read identity, install an app, then forward a port.
-
-```typescript
-import { AdbDeviceKit } from '@mcesystems/adb-kit';
-
-const deviceId = 'ABC123'; // from your device discovery
-const device = new AdbDeviceKit(deviceId, 1);
-
-// 1. Wait for USB debugging (e.g. after user enables it)
-const { promise } = device.waitForUsbDebugging(60000);
-await promise;
-
-// 2. Identify device
-const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
-console.log(`Device: ${manufacturer} ${model}`);
-
-// 3. Install app
-await device.installApp('./build/app.apk');
-
-// 4. Forward a device service to a local port
-const localPort = await device.startPortForward('tcp:8080');
-console.log(`Service reachable at localhost:${localPort}`);
-```
-
-## 7. TODO
-
-- [ ] Optional: Re-authorize handling when ADB reports vendor keys not set (revoke and re-authorize device).
-- [ ] Optional: Add Example.md with more detailed scenarios and explanations.
+# @mcesystems/adb-kit
+
+## 1. Description
+
+**What it does:** ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations: listing devices, reading device properties, installing/uninstalling apps, checking and waiting for USB debugging, and port forwarding.
+
+**When it's used:** Use this package when your application needs to communicate with Android devices over ADB—for example device management tools, test runners, or installers that target Android hardware.
+
+## 2. Install
+
+```bash
+npm install @mcesystems/adb-kit
+```
+
+**Requirements:** Node.js 18+, Android device with USB debugging enabled, and ADB binaries (see Resources).
+
+## 3. Resources
+
+This package needs ADB binaries to run. You can obtain them in one of these ways:
+
+**Option A – Export script (recommended for distribution)**  
+Bundle ADB for your app using the provided script:
+
+```bash
+npx export-adb-resources /path/to/your-app/resources/adb-kit
+
+# All platforms
+npx export-adb-resources /path/to/your-app/resources/adb-kit --all
+```
+
+See [scripts/README.md](./scripts/README.md) for arguments, options, output layout, and prerequisites.
+
+**Option B – Development**  
+- **Windows / macOS:** Set `AdbBinPath` to your ADB binary directory, or have `adb` on system PATH.  
+- **Linux:** Install via package manager (e.g. `sudo apt install adb`).
+
+The package resolves ADB in this order: `AdbBinPath` env, then bundled resources under `dist/resources/bin/<platform>/`, then system PATH.
+
+## 4. Examples
+
+**Create a device kit and read properties**
+
+```typescript
+import { AdbDeviceKit } from '@mcesystems/adb-kit';
+
+const device = new AdbDeviceKit('device-serial-number', 1);
+const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
+const allProps = await device.getAllDeviceProperties();
+const devices = await device.listDevices();
+```
+
+**Install/uninstall and check app**
+
+```typescript
+await device.installApp('/path/to/app.apk');
+const isInstalled = await device.isAppInstalled('com.example.app');
+await device.uninstallApp('com.example.app');
+```
+
+**USB debugging**
+
+```typescript
+const hasDebugging = await device.hasUsbDebugging();
+const { promise, events } = device.waitForUsbDebugging(30000); // 30s timeout
+events.on("usbDebuggingOff", () => console.log("Enable USB debugging on device"));
+events.on("usbDebuggingNeedsAlwaysAllow", () => console.log("Tap Always allow on device"));
+events.on("usbDebuggingAuthorized", () => console.log("Device ready"));
+const ok = await promise;
+```
+
+**Port forwarding**
+
+```typescript
+const localPort = await device.startPortForward('tcp:8080');
+```
+
+**Low-level clients**
+
+```typescript
+const client = await device.getClient();
+const deviceClient = await device.getDeviceClient();
+```
+
+**First connected Android properties**
+
+One-shot example that discovers the first connected Android device and prints a curated set of its properties (manufacturer, model, brand, Android version, etc.).
+
+```bash
+# From packages/adb-kit
+pnpm example:first-android-properties
+```
+
+See [src/examples/first-connected-android-properties.ts](./src/examples/first-connected-android-properties.ts) for the script.
+
+**USB debugging robustness example**
+
+Interactive example that runs the same flow 5 times to verify `waitForUsbDebugging` handling: start without USB debugging (device not found), short 5s timeout (user lets it pass), then wait up to 30s while the user enables USB debugging, show device recognized, then user disables USB debugging and repeats.
+
+```bash
+# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
+pnpm example:usb-debugging
+```
+
+See [src/examples/usb-debugging-robustness.ts](./src/examples/usb-debugging-robustness.ts) for the script.
+
+**USB debugging playground**
+
+Interactive playground to observe status events while you toggle USB debugging on/off or revoke authorizations. Prints events in real time as you change device settings.
+
+```bash
+# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
+pnpm example:usb-debugging-playground
+```
+
+See [src/examples/usb-debugging-playground.ts](./src/examples/usb-debugging-playground.ts) for the script.
+
+For more scenarios and step-by-step explanations, see [Example.md](./Example.md).
+
+## 5. API
+
+### AdbDeviceKit
+
+**Constructor**
+
+- **Input:** `deviceId: string`, `port: number`
+- **Output:** new `AdbDeviceKit` instance bound to that device and logical port.
+
+**listDevices()**
+
+- **Input:** none
+- **Output:** `Promise<AdbDevice[]>` — list of connected devices (`AdbDevice`: `{ id: string; type: AdbDeviceType }`).
+
+**getDeviceProperties(properties)**
+
+- **Input:** `properties: DeviceProperty[]` — e.g. `['Manufacturer', 'Model']`
+- **Output:** `Promise<string[]>` — values in the same order as `properties`; failed props are `""`.
+
+**getAllDeviceProperties()**
+
+- **Input:** none
+- **Output:** `Promise<Record<string, string>>` — all device properties from `getprop`.
+
+**installApp(appPath)**
+
+- **Input:** `appPath: string` — path to APK
+- **Output:** `Promise<void>` — resolves when install finishes; rejects on failure.
+
+**uninstallApp(packageName)**
+
+- **Input:** `packageName: string` — e.g. `'com.example.app'`
+- **Output:** `Promise<void>` — resolves when uninstall finishes; rejects on failure.
+
+**isAppInstalled(packageName)**
+
+- **Input:** `packageName: string`
+- **Output:** `Promise<boolean>` — whether the package is installed.
+
+**hasUsbDebugging()**
+
+- **Input:** none
+- **Output:** `Promise<boolean>` — whether this device appears in the ADB device list.
+
+**waitForUsbDebugging(timeout?, numberOfAllowedAttempts?)**
+
+- **Input:** `timeout?: number` (default `120000` ms), `numberOfAllowedAttempts?: number` (default `5`, accepted for backward compatibility; give-up is determined by timeout and tracker end only)
+- **Output:** `{ promise: Promise<boolean>; events: EventEmitter }` — await `promise` for the result (`true` when device is ready, `false` when tracking ends without device; rejects on timeout, device removal, or connection error). Subscribe to `events` for state changes:
+  - `usbDebuggingOff` — waiting started (USB debugging not enabled on device)
+  - `usbDebuggingNeedsAlwaysAllow` — device visible but user must tap "Always allow" on device
+  - `usbDebuggingAuthorized` — device ready
+
+**startPortForward(serviceName)**
+
+- **Input:** `serviceName: string` — e.g. `'tcp:8080'`
+- **Output:** `Promise<number | null>` — local port number used for forwarding, or `null` if forwarding failed. Reuses same port on repeated calls.
+
+**getClient()**
+
+- **Input:** none
+- **Output:** `Promise<AdbClient>` — underlying adbkit client.
+
+**getDeviceClient()**
+
+- **Input:** none
+- **Output:** `Promise<DeviceClient>` — adbkit device client for this device.
+
+**getDeviceId()**
+
+- **Input:** none
+- **Output:** `string` — device serial (last segment after `\` on Windows).
+
+**getPort()**
+
+- **Input:** none
+- **Output:** `number` — logical port passed to the constructor.
+
+### DeviceProperty
+
+Supported property names for `getDeviceProperties()`:  
+`Manufacturer`, `Name`, `Model`, `Brand`, `Device`, `Android Version`, `Platform`, `CPU`, `CPU.abi2`, `Description`, `Fingerprint`, `GSM Flexversion`, `GSM IMEI`, `Locale Language`, `Locale Region`, `Wifi Channels`, `Board Platform`, `Product Board`, `Display ID`, `Version Incremental`, `Version SDK`, `Version Codename`, `Version Release`, `Build Date`, `Build Type`, `Build User`.
+
+## 6. Flow
+
+Example flow: wait for device, read identity, install an app, then forward a port.
+
+```typescript
+import { AdbDeviceKit } from '@mcesystems/adb-kit';
+
+const deviceId = 'ABC123'; // from your device discovery
+const device = new AdbDeviceKit(deviceId, 1);
+
+// 1. Wait for USB debugging (e.g. after user enables it)
+const { promise } = device.waitForUsbDebugging(60000);
+await promise;
+
+// 2. Identify device
+const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
+console.log(`Device: ${manufacturer} ${model}`);
+
+// 3. Install app
+await device.installApp('./build/app.apk');
+
+// 4. Forward a device service to a local port
+const localPort = await device.startPortForward('tcp:8080');
+console.log(`Service reachable at localhost:${localPort}`);
+```
+
+## 7. TODO
+
+- [ ] Optional: Re-authorize handling when ADB reports vendor keys not set (revoke and re-authorize device).
+- [ ] Optional: Add Example.md with more detailed scenarios and explanations.

package/dist/index.js

@@ -31486,7 +31486,7 @@ var AdbDeviceKit = class {
     return client;
   }
   async listDevices() {
-    const devices = await this.client.listDevices();
+    const devices = await this.client.listDevices().filter((device) => device.type === "device");
     return devices;
   }
   async getProperty(adbDevice, property) {
@@ -31549,13 +31549,23 @@ var AdbDeviceKit = class {
   waitForUsbDebugging(timeout2 = 12e4, _numberOfAllowedAttempts = 5) {
     const events = new import_node_events.EventEmitter();
     const promise = (async () => {
-      if (await this.hasUsbDebugging()) {
+      const device = (await this.client.listDevices()).find(
+        (device2) => device2.id === this.deviceId
+      );
+      logDetail(`Device: ${device?.id} (${device?.type})`);
+      if (device?.type === "device") {
         logDetail("USB debugging is already enabled");
         return true;
       }
       const trackingClient = this.createTrackingClient();
       const tracker = await trackingClient.trackDevices();
-      events.emit(USB_DEBUGGING_EVENT_OFF);
+      setTimeout(() => {
+        if (device?.type === "unauthorized") {
+          events.emit(USB_DEBUGGING_EVENT_NEEDS_ALWAYS_ALLOW);
+        } else {
+          events.emit(USB_DEBUGGING_EVENT_OFF);
+        }
+      }, 0);
       let settled = false;
       return new Promise((resolve, reject) => {
         const timeoutId = setTimeout(() => {
@@ -31582,14 +31592,14 @@ var AdbDeviceKit = class {
             reject(result.err);
           }
         };
-        const handleAddOrChange = (device) => {
-          if (!this.matchesDeviceId(device)) return;
-          if (device.type === "unauthorized") {
+        const handleAddOrChange = (device2) => {
+          if (!this.matchesDeviceId(device2)) return;
+          if (device2.type === "unauthorized") {
             logDetail("Device needs 'Always allow' authorization");
             events.emit(USB_DEBUGGING_EVENT_NEEDS_ALWAYS_ALLOW);
             return;
           }
-          if (device.type === "device") {
+          if (device2.type === "device") {
             logDetail("Device authorized");
             events.emit(USB_DEBUGGING_EVENT_AUTHORIZED);
             settle({ type: "resolve", value: true });