# @mcesystems/adb-kit

ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations.

## Features

- **Device Operations**: Get device properties, install/uninstall apps
- **USB Debugging Detection**: Check and wait for USB debugging enabled
- **Port Forwarding**: Forward local ports to device services
- **Cross-platform**: Works on Windows, macOS, and Linux

## Installation

```bash
npm install @mcesystems/adb-kit
```

## Requirements

- Node.js 18+
- Android device with USB debugging enabled
- ADB binaries (see Platform Setup)

### Platform Setup

#### Using the Export Script (Recommended for Distribution)

Use the export script to bundle ADB binaries for your application:
```bash
# Using npx (after installing the package)
npx export-adb-resources /path/to/your-app/resources/adb-kit

# Or export for all platforms at once
npx export-adb-resources /path/to/your-app/resources/adb-kit --all

# Or run the script directly
npx tsx node_modules/@mcesystems/adb-kit/scripts/export-resources.ts /path/to/your-app/resources
```

See [scripts/README.md](./scripts/README.md) for detailed prerequisites and instructions.

#### Windows & macOS (Development)

Set the `AdbBinPath` environment variable to the ADB binary location, or ensure `adb` is in your system PATH.

#### Linux

Install ADB via your package manager:
```bash
sudo apt install adb  # Debian/Ubuntu
sudo dnf install android-tools  # Fedora
```

## Usage

### Basic Device Operations

```typescript
import { AdbDeviceKit } from '@mcesystems/adb-kit';

// Create a device kit for a specific device
const device = new AdbDeviceKit('device-serial-number', 1);

// Get device properties
const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
console.log(`Device: ${manufacturer} ${model}`);

// Get all properties
const allProps = await device.getAllDeviceProperties();

// List connected devices
const devices = await device.listDevices();
```

### App Management

```typescript
const device = new AdbDeviceKit('device-serial-number', 1);

// Install an APK
await device.installApp('/path/to/app.apk');

// Check if app is installed
const isInstalled = await device.isAppInstalled('com.example.app');

// Uninstall an app
await device.uninstallApp('com.example.app');
```

### USB Debugging

```typescript
const device = new AdbDeviceKit('device-serial-number', 1);

// Check if USB debugging is enabled
const hasDebugging = await device.hasUsbDebugging();

// Wait for USB debugging to be enabled (with timeout)
await device.waitForUsbDebugging(30000); // 30 seconds
```

### Port Forwarding

```typescript
const device = new AdbDeviceKit('device-serial-number', 1);

// Forward a local port to a device service
const localPort = await device.startPortForward('tcp:8080');
console.log(`Forwarded to local port: ${localPort}`);
```

### Access ADB Client

```typescript
const device = new AdbDeviceKit('device-serial-number', 1);

// Get the underlying adbkit client for advanced operations
const client = await device.getClient();

// Get the device client for direct device operations
const deviceClient = await device.getDeviceClient();
```

## API Reference

### AdbDeviceKit

**Constructor:**
- `new AdbDeviceKit(deviceId: string, port: number)`: Create a device kit

**Device Info:**
- `getDeviceId()`: Get the device serial number
- `getPort()`: Get the logical port number
- `getDeviceProperties(properties: DeviceProperty[])`: Get specific device properties
- `getAllDeviceProperties()`: Get all device properties

**Device State:**
- `hasUsbDebugging()`: Check if USB debugging is enabled
- `waitForUsbDebugging(timeout?)`: Wait for USB debugging

**App Management:**
- `installApp(apkPath: string)`: Install an APK
- `uninstallApp(packageName: string)`: Uninstall an app
- `isAppInstalled(packageName: string)`: Check if app is installed

**Port Forwarding:**
- `startPortForward(serviceName: string)`: Forward to a device service

**Advanced:**
- `getClient()`: Get the adbkit client
- `getDeviceClient()`: Get the device client
- `listDevices()`: List all connected devices

### DeviceProperty

Available device properties:
- `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`

## Development

```bash
# Build the package
npm run build

# Run tests
npm test

# Clean build artifacts
npm run clean
```

### Setting Up ADB for Development

For development, you can either:
1. Use the export script to download ADB to a local path
2. Install ADB via Homebrew (`brew install android-platform-tools`) or your system package manager
3. Set `AdbBinPath` environment variable to your ADB installation

## License

ISC

ADB Platform Tools are licensed under the Apache License 2.0.
