shellx-ai 1.0.0

package/README.md

@@ -0,0 +1,335 @@
+# ShellX
+
+[![npm version](https://badge.fury.io/js/shellx.svg)](https://badge.fury.io/js/shellx)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**ShellX** is a powerful automation framework for Android device control and UI automation. It provides seamless shell command execution, element finding, screen capture, and automated task execution through an intelligent WebSocket-based architecture.
+
+## ✨ Features
+
+- 🔐 **Zero-Configuration Setup** - Automatic authentication and connection management
+- 📱 **Android Device Control** - Execute shell commands with real-time output monitoring
+- 🎯 **Smart UI Automation** - Advanced element finding with retry logic and multiple strategies
+- 📸 **Screen Operations** - Screenshots, screen info, and visual change detection
+- 🔄 **Intelligent Fallback** - Automatic switching between cloud and local services
+- 🛡️ **Robust Error Handling** - Comprehensive error recovery and diagnostics
+- 🧠 **Shell Output Monitoring** - Real-time command output processing and analysis
+- 📊 **Rich Diagnostics** - Built-in element analysis and debugging tools
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install shellx-ai
+```
+
+### Basic Setup
+
+```typescript
+import { createShellXWithShellMonitoring } from 'shellx';
+
+// Set your authentication key
+process.env.SHELLX_AUTH_KEY = 'your-auth-key';
+
+// Initialize ShellX with automatic authentication
+const { client, shellx } = await createShellXWithShellMonitoring();
+
+// Start automating!
+await shellx.executeShellCommand('getprop ro.build.version.release');
+await shellx.clickByText('Settings');
+```
+
+### Environment Setup
+
+Set your authentication key as an environment variable:
+
+```bash
+# Linux/macOS
+export SHELLX_AUTH_KEY="your-auth-key"
+
+# Windows
+set SHELLX_AUTH_KEY=your-auth-key
+```
+
+## 📱 Common Use Cases
+
+### 1. Shell Command Execution
+
+```typescript
+// Execute shell commands with real-time output
+const result = await shellx.executeShellCommand('pm list packages', {
+  title: 'List installed packages',
+  timeout: 10000,
+  onOutput: (output) => {
+    console.log('Real-time output:', output);
+  }
+});
+
+console.log('Command result:', result.output);
+console.log('Success:', result.success);
+console.log('Duration:', result.duration, 'ms');
+```
+
+### 2. UI Element Operations
+
+```typescript
+// Smart element finding with retry logic
+const elements = await shellx.findElementsWithRetry({
+  className: 'android.widget.TextView',
+  textContains: 'Settings'
+}, 3, 1000, {
+  maxResults: 10,
+  visibleOnly: true
+});
+
+// Print detailed element information
+shellx.printElementsInfo(elements, 'Found Settings Elements');
+
+// Click by text content
+await shellx.clickByText('Wi-Fi', false);
+
+// Input text with options
+await shellx.inputText({
+  resourceId: 'search_field'
+}, 'Hello ShellX', {
+  clear: true,
+  hideKeyboard: true
+});
+```
+
+### 3. Screen Operations
+
+```typescript
+// Capture screenshot with details
+const screenshot = await shellx.captureScreen({
+  format: 'png',
+  quality: 90,
+  saveInfo: true
+});
+
+// Swipe gestures
+await shellx.swipe('up', 400, 800);  // direction, distance, duration
+await shellx.swipe('left', 300, 600);
+```
+
+### 4. App Automation Workflow
+
+```typescript
+// Login automation example
+await shellx.performLogin(
+  { resourceId: 'username_field' },      // username selector
+  { resourceId: 'password_field' },      // password selector  
+  { resourceId: 'login_button' },        // login button selector
+  'user@example.com',                    // username
+  'password123'                          // password
+);
+
+// Navigation workflow
+await shellx.navigateByPath([
+  'Settings',
+  'Network & internet', 
+  'Wi-Fi'
+]);
+```
+
+### 5. Advanced Element Finding
+
+```typescript
+// Wait for any of multiple elements to appear
+const result = await shellx.waitForAnyElement([
+  { textContains: 'OK' },
+  { textContains: 'Cancel' },
+  { textContains: 'Skip' }
+], 10000);
+
+if (result) {
+  console.log(`Found element: ${result.element.text} at index ${result.selectorIndex}`);
+}
+
+// Scroll to find element
+const element = await shellx.scrollToFindElement({
+  textContains: 'Privacy Settings'
+}, 5, 'down');
+```
+
+### 6. Batch Shell Commands
+
+```typescript
+// Execute multiple commands in sequence
+const commands = [
+  { command: 'am force-stop com.example.app', title: 'Stop app' },
+  { command: 'am start -n com.example.app/.MainActivity', title: 'Start app' },
+  { command: 'input keyevent KEYCODE_HOME', title: 'Go home', waitAfterMs: 1000 }
+];
+
+const results = await shellx.executeShellCommands(commands, {
+  continueOnError: true,
+  timeout: 5000
+});
+```
+
+### 7. Device Information
+
+```typescript
+// Get comprehensive device information
+const deviceInfo = await shellx.getDeviceInfo();
+deviceInfo.forEach((info, index) => {
+  console.log(`${index + 1}. ${info.output}`);
+});
+
+// ADB commands with enhanced output
+const result = await shellx.adbCommand('shell dumpsys battery', {
+  title: 'Get battery status',
+  successPattern: /level: \d+/,
+  errorPattern: /error|failed/i
+});
+```
+
+## 🎯 ShellX Class API
+
+### Core Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `executeShellCommand(cmd, opts?)` | Execute shell command with monitoring | `shellx.executeShellCommand('ls -la')` |
+| `clickByText(text, exact?)` | Click element by text content | `shellx.clickByText('OK', true)` |
+| `inputText(selector, text, opts?)` | Input text into element | `shellx.inputText({resourceId: 'field'}, 'text')` |
+| `findElementWithRetry(selector, retries?, delay?)` | Find single element with retry | `shellx.findElementWithRetry({text: 'Button'})` |
+| `findElementsWithRetry(selector, retries?, delay?, opts?)` | Find multiple elements with retry | `shellx.findElementsWithRetry({className: 'TextView'})` |
+| `swipe(direction, distance?, duration?)` | Perform swipe gesture | `shellx.swipe('up', 400, 800)` |
+| `captureScreen(opts?)` | Take screenshot | `shellx.captureScreen({saveInfo: true})` |
+
+### Utility Methods
+
+| Method | Description |
+|--------|-------------|
+| `printElementInfo(element, index?)` | Print detailed element information |
+| `printElementsInfo(elements, title?)` | Print information for multiple elements |
+| `waitForAnyElement(selectors, timeout?)` | Wait for any of multiple elements |
+| `scrollToFindElement(selector, maxScrolls?, direction?)` | Scroll to find element |
+| `performLogin(userSel, passSel, btnSel, user, pass)` | Automated login flow |
+| `navigateByPath(textPath)` | Navigate through UI by text path |
+| `getDeviceInfo()` | Get comprehensive device information |
+
+## 🛠️ Configuration
+
+### Environment Variables
+
+```bash
+# Required: Your ShellX authentication key
+SHELLX_AUTH_KEY=your-auth-key
+
+# Optional: Timeout settings
+SHELLX_TIMEOUT=20000
+SHELLX_RETRY_ATTEMPTS=3
+```
+
+### Connection Options
+
+```typescript
+const { client, shellx } = await createShellXWithShellMonitoring({
+  timeout: 15000,
+  reconnectMaxAttempts: 3,
+  onOpen: () => console.log('Connected'),
+  onClose: (event) => console.log('Disconnected'),
+  onError: (error) => console.error('Error:', error),
+  onMessage: (data) => {
+    // Handle custom messages
+  }
+});
+```
+
+## 🔧 Advanced Features
+
+### Shell Output Monitoring
+
+ShellX automatically monitors shell command output in real-time:
+
+```typescript
+const result = await shellx.executeShellCommand('top -n 1', {
+  onOutput: (output) => {
+    console.log('Live output:', output);
+  },
+  successPattern: /Tasks:/,
+  errorPattern: /error|failed/i,
+  timeout: 10000
+});
+```
+
+### Element Diagnostics
+
+Built-in diagnostic tools for troubleshooting:
+
+```typescript
+// Automatic element diagnosis when finding fails
+const elements = await shellx.findElementsWithRetry({
+  textContains: 'NotFound'
+});
+
+if (elements.length === 0) {
+  // ShellX automatically runs diagnostics
+  // Shows available elements, device info, etc.
+}
+```
+
+### Intelligent Fallback
+
+ShellX automatically handles service availability:
+
+```typescript
+// 1. Tries online authentication: https://shellx.ai/api/device/{authKey}
+// 2. On success: Uses returned machine URL  
+// 3. On failure: Falls back to local: ws://127.0.0.1:9091/api/s/{authKey}
+// 4. Seamless operation regardless of network conditions
+```
+
+## 📚 Complete Examples
+
+Check out the [examples directory](./examples/) for comprehensive use cases:
+
+- **[paytm.ts](./examples/paytm.ts)** - PayTM app automation with bill analysis
+- **[basic.ts](./examples/basic.ts)** - Basic automation operations
+- **[shell-commands-demo.ts](./examples/shell-commands-demo.ts)** - Shell command execution
+- **[find-elements-demo.ts](./examples/find-elements-demo.ts)** - Element finding strategies
+
+## 🚨 Error Handling
+
+ShellX provides comprehensive error handling with automatic recovery:
+
+```typescript
+try {
+  await shellx.executeShellCommand('invalid-command');
+} catch (error) {
+  // ShellX handles timeouts, connection issues, and command failures
+  console.error('Command failed:', error.message);
+  
+  // Automatic diagnostics on failure
+  // Device info, available elements, etc.
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 📚 [Documentation](https://shellx.ai/docs)
+- 🐛 [GitHub Issues](https://github.com/your-org/shellx/issues)
+- 💬 [Discord Community](https://discord.gg/shellx)
+
+## 🎉 Getting Started
+
+1. **Install ShellX**: `npm install shellx-ai`
+2. **Set your auth key**: `export SHELLX_AUTH_KEY="your-key"`  
+3. **Run the example**: `ts-node examples/basic.ts`
+4. **Start automating!** 🚀
+
+---
+
+*Made with ❤️ for the automation community* 

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+export interface TaskClientConfig {
+    timeout: number;
+    reconnect: boolean;
+    reconnectMaxAttempts: number;
+    reconnectInterval: number;
+    pingInterval: number;
+    onOpen: () => void;
+    onClose: (event?: CloseEvent) => void;
+    onError: (error?: Event) => void;
+    onReconnectFailed: () => void;
+    onMessage?: (data: any) => void;
+}
+export declare const DEFAULT_CONFIG: TaskClientConfig;

package/dist/constants.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.DEFAULT_CONFIG = {
+    timeout: 5000,
+    reconnect: true,
+    reconnectMaxAttempts: 5,
+    reconnectInterval: 1000,
+    pingInterval: 2000,
+    onOpen: () => { },
+    onClose: () => { },
+    onError: () => { },
+    onReconnectFailed: () => { },
+};

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { TaskClientConfig } from './constants';
+import type { WsClient, ActionSequence, ScreenShotOptions, ElementSelector, FindOptions, WaitOptions, UIHierarchy, WAITElement, ScreenShotResponse, ScreenInfoResponse, AppListResponse } from './protocol';
+export interface TaskResponse<T = any> {
+    taskId?: string;
+    success?: boolean;
+    data?: T;
+    error?: {
+        message: string;
+    };
+}
+export interface PendingTask {
+    resolve: (data: any) => void;
+    reject: (err: Error) => void;
+    timer: NodeJS.Timeout;
+    type: string;
+}
+/**
+ * Enhanced WebSocket Task Client with protocol-aware task methods
+ */
+export declare class WebSocketTaskClient {
+    private wsUrl;
+    private config;
+    ws: WebSocket | null;
+    private connected;
+    private pendingTasks;
+    private messageQueue;
+    private reconnectAttempts;
+    private pingIntervalId;
+    constructor(wsUrl: string, config?: Partial<TaskClientConfig>);
+    private init;
+    private handleMessage;
+    private processServerMessage;
+    private handleJsonDataResponse;
+    private sendMessage;
+    /**
+     * Find UI elements on the screen
+     */
+    findElement(selector: ElementSelector, options?: FindOptions): Promise<UIHierarchy>;
+    /**
+     * Wait for UI element to appear
+     */
+    waitElement(selector: ElementSelector, options?: WaitOptions): Promise<WAITElement>;
+    /**
+     * Take a screenshot
+     */
+    screenShot(options?: ScreenShotOptions): Promise<ScreenShotResponse>;
+    /**
+     * Get screen information
+     */
+    getScreenInfo(): Promise<ScreenInfoResponse>;
+    /**
+     * Get list of installed apps
+     */
+    getAppList(options?: {
+        includeSystemApps?: boolean;
+        includeDisabledApps?: boolean;
+    }): Promise<AppListResponse>;
+    /**
+     * Get specific app information
+     */
+    getAppInfo(packageName: string): Promise<any>;
+    /**
+     * Execute an action sequence
+     */
+    executeAction(actionSequence: ActionSequence): Promise<any>;
+    /**
+     * Execute promptflow actions
+     */
+    executePromptFlow(actionSequence: ActionSequence): Promise<any>;
+    /**
+     * Listen for display changes
+     */
+    screenChange(options?: {
+        interval?: number;
+        compareThreshold?: number;
+        includeScreenshot?: boolean;
+        enable?: boolean;
+    }): Promise<void>;
+    /**
+     * Switch to a different node
+     */
+    switchNode(nodeId: string): Promise<void>;
+    /**
+     * Send authentication data
+     */
+    authenticate(authData: Uint8Array): Promise<void>;
+    /**
+     * Set user name
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * Send chat message
+     */
+    sendChat(message: string): Promise<void>;
+    /**
+     * Send raw message (for custom integrations)
+     */
+    sendRawMessage(message: WsClient): Promise<void>;
+    private startPing;
+    private stopPing;
+    private reconnect;
+    private flushQueue;
+    close(): void;
+    get isConnected(): boolean;
+    get pendingTaskCount(): number;
+    get queuedMessageCount(): number;
+}
+export default WebSocketTaskClient;
+export { ShellX, createShellX, createShellXWithShellMonitoring } from './shellx';
+export type { UIElement, ElementSelector, ActionSequence } from './shellx';