shellx-ai 1.0.12 → 1.1.0

package/dist/shellx.d.ts

@@ -1,204 +1,707 @@
-import type { ElementSelector, ActionSequence as LegacyActionSequence, UIElement, ScreenShotOptions, WsServer } from './protocol';
-import type { ActionResult, Click, Input, Swipe, Key, Wait, Find, Command, AppInfo, Screenshot, Point, Element, FindResult, CommandResult, Action, Actions } from './types';
-import ConnectionTaskClient from './index';
-export type { UIElement, ElementSelector, LegacyActionSequence };
-export type { ActionResult, Click, Input, Swipe, Key, Wait, Find, Command, AppInfo, Screenshot, Point, Element, FindResult, CommandResult, Action, Actions };
-interface ShellCommandResult {
-    success: boolean;
-    output: string;
-    error?: string;
-    exitCode?: number;
-    duration: number;
-}
-interface ShellCommandOptions {
-    title?: string;
+/**
+ * ShellX - High-level automation utilities for Android device control
+ *
+ * This module provides a comprehensive API for automating Android devices,
+ * including UI actions, shell commands, element finding, and device information.
+ *
+ * @module shellx
+ */
+import type { ElementSelector, UIElement, WsServer } from "./protocol.js";
+import type { Actions, AppInfo, AppInfoResult, BaseResult, Click, ClickResult, Clipboard, ClipboardResult, Command, CommandResult as TypesCommandResult, Element, ExecuteActionsResult, Find, FindResult as TypesFindResult, Input, InputResult, Key, KeyResult, ScreenInfoResult, Screenshot, ScreenshotResult, Swipe, SwipeResult, Wait, WaitResult } from "./types.js";
+import ConnectionClient from "./index.js";
+import { type LogLevel } from "./logger.js";
+import type { WsClient } from "./protocol.js";
+export type { UIElement, ElementSelector };
+export type { LogLevel } from "./logger.js";
+export type { Click, Input, Swipe, Key, Wait, Find, Command, AppInfo, Screenshot, Clipboard, Actions, ClickResult, InputResult, SwipeResult, KeyResult, WaitResult, TypesFindResult as FindResult, TypesCommandResult as CommandResult, ClipboardResult, AppInfoResult, ScreenshotResult, ScreenInfoResult, ExecuteActionsResult, BaseResult, Element, };
+export type { ShellCommandResult, ShellCommandOptions } from "./shell/output-buffer.js";
+/**
+ * Configuration options for ShellX instance
+ */
+export interface ShellXOptions {
+    /** Device ID (UUID or identifier) */
+    deviceId: string | undefined;
+    /** Connection timeout in milliseconds (default: 5000) */
     timeout?: number;
-    waitAfterMs?: number;
-    onOutput?: (output: string) => void;
-    onError?: (error: string) => void;
-    expectedOutput?: string | RegExp;
-    successPattern?: string | RegExp;
-    allowPartialResult?: boolean;
+    /** Enable automatic reconnection (default: true) */
+    reconnect?: boolean;
+    /** Maximum reconnection attempts (default: 5) */
+    reconnectMaxAttempts?: number;
+    /** Reconnection interval in milliseconds (default: 1000) */
+    reconnectInterval?: number;
+    /** Ping interval in milliseconds (default: 2000) */
+    pingInterval?: number;
+    /** Log level (default: LogLevel.INFO) */
+    logLevel?: LogLevel;
+    /** Callback when connection is opened */
+    onOpen?: () => void;
+    /** Callback when connection is closed */
+    onClose?: () => void;
+    /** Callback when connection error occurs */
+    onError?: (error?: Error | Event) => void;
+    /** Callback for reconnection failure */
+    onReconnectFailed?: () => void;
+    /** Callback for WebSocket messages */
+    onMessage?: (message: WsServer) => void;
 }
 /**
- * ShellX automation utilities for common patterns
+ * ShellX - High-level Android automation SDK (Recommended API)
+ *
+ * **This is the recommended API for 95% of users.**
+ *
+ * ShellX provides a simple, intuitive interface for Android automation with:
+ *
+ * - ✅ Automatic error handling and retry logic
+ * - ✅ Type-safe TypeScript API
+ * - ✅ Consistent method signatures
+ * - ✅ Built-in timing and performance tracking
+ * - ✅ Simplified element selection
+ *
+ * **Key Features:**
+ * - UI interaction: click, input, swipe, press, wait
+ * - Element finding with smart selectors
+ * - Shell command execution
+ * - Screen info and screenshots
+ * - Batch operations
+ *
+ * **Quick Start:**
+ * ```typescript
+ * import { ShellX } from '@shellx-ai/sdk';
+ *
+ * // Initialize
+ * const shellx = new ShellX({ deviceId: 'your-device-id' });
+ *
+ * // Connect
+ * await shellx.connect();
+ *
+ * // Automate
+ * await shellx.click('Submit');
+ * await shellx.input({ text: 'Hello World' });
+ * await shellx.swipe({ fromX: 500, fromY: 1000, toX: 500, toY: 500 });
+ *
+ * // Get info
+ * const screen = await shellx.getScreenInfo();
+ * console.log(`Screen: ${screen.width}x${screen.height}`);
+ * ```
+ *
+ * **Note:** For low-level WebSocket access, see ConnectionClient (advanced users only).
+ *
+ * @see API-GUIDE.md for comprehensive documentation
+ * @see ConnectionClient for low-level protocol access
  */
 export declare class ShellX {
+    /** Logger instance for ShellX */
+    private logger;
+    /** UI action handler for executing UI operations */
+    private uiActionHandler;
+    /** Element finder for locating UI elements */
+    private elementFinder;
+    /** Shell command executor for running shell commands */
+    private shellCommandExecutor;
+    /** Connection client for device communication */
     private client;
-    private shellOutputBuffers;
-    private shellCommandPromises;
-    constructor(client: ConnectionTaskClient);
-    /**
-     * Get the WebSocket client instance
-     */
-    getClient(): ConnectionTaskClient;
-    /**
-     * 设置 shell 输出监听器（需要在创建 WebSocketTaskClient 时调用）
-     */
-    static createShellOutputHandler(helpers: ShellX): (message: WsServer) => void;
-    /**
-     * 处理 shell 输出数据
-     */
-    handleShellOutput(chunks: [any, number, Uint8Array[]]): void;
-    /**
-     * 清理命令输出，去除输入的命令内容
-     */
-    private cleanCommandOutput;
-    /**
-     * 合并多个 session 的输出
-     */
-    private combineSessionOutputs;
-    /**
-     * 通用重试机制 - 失败时返回 undefined 而不是抛出异常
-     */
-    private withRetry;
-    /**
-     * 转换精简选择器为原始选择器
-     */
-    private convertSelector;
-    /**
-     * 转换精简元素为原始元素
-     */
-    private convertElement;
-    /**
-     * 点击操作 - 支持元素ID、坐标或选择器
-     */
-    click(clickData: Click): Promise<ActionResult>;
-    /**
-     * 输入操作 - 支持元素ID、资源ID或选择器
-     */
-    input(inputData: Input): Promise<ActionResult>;
-    /**
-     * 滑动操作 - 支持坐标点
-     */
-    swipe(swipeData: Swipe): Promise<ActionResult>;
-    /**
-     * 按键操作
-     */
-    pressKey(keyData: Key): Promise<ActionResult>;
-    /**
-     * 等待操作 - 等待元素出现或消失
-     */
-    wait(waitData: Wait): Promise<ActionResult>;
-    /**
-     * 查找操作 - 查找元素
-     */
-    find(findData: Find): Promise<FindResult>;
-    /**
-     * 执行命令 - 兼容现有的 shell 命令执行
-     */
-    executeCommand(commandData: Command): Promise<CommandResult>;
-    executeCodeEval(context: any, code: string, timeout?: number): Promise<any>;
-    executeCode(agentCode: string, context: any, timeout?: number): Promise<any>;
-    /**
-     * 获取应用信息
-     */
-    getAppInfo(appInfoData: AppInfo): Promise<ActionResult>;
     /**
-     * 截图操作
-     */
-    takeScreenshot(screenshotData?: Screenshot): Promise<ActionResult>;
-    /**
-     * 执行操作序列 - 支持多个操作连续执行
-     */
-    executeActions(actions: Array<Click | Input | Swipe | Key | Wait | Find | Command | AppInfo | Screenshot>): Promise<ActionResult[]>;
-    /**
-     * Smart element finder with retry logic
+     * Creates a ShellX instance
+     *
+     * @param options - Configuration options for ShellX instance
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({
+     *   deviceId: 'device-id',
+     *   onOpen: () => console.log('Connected!'),
+     *   onMessage: (msg) => console.log(msg)
+     * });
+     *
+     * // Optionally wait for connection
+     * await shellx.ready();
+     *
+     * // Start using ShellX
+     * await shellx.click('Settings');
+     * ```
+     */
+    constructor(options: ShellXOptions);
+    /**
+     * Wait for connection to be ready
+     *
+     * This method waits for the WebSocket connection to be established.
+     * Most operations will automatically wait for connection, but you can
+     * call this method explicitly if you need to ensure connection before
+     * performing operations.
+     *
+     * @returns Promise that resolves when connection is ready
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * await shellx.ready();
+     * console.log('Connection is ready!');
+     * ```
+     */
+    ready(): Promise<void>;
+    /**
+     * Get the underlying ConnectionClient instance
+     *
+     * @returns The ConnectionClient instance
+     */
+    getClient(): ConnectionClient;
+    /**
+     * Get the current log level
+     *
+     * @returns Current log level
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * console.log('Current log level:', shellx.getLogLevel());
+     * ```
+     */
+    getLogLevel(): LogLevel;
+    /**
+     * Set the log level
+     *
+     * @param level - Log level to set
+     *
+     * @example
+     * ```typescript
+     * import { ShellX, LogLevel } from '@shellx-ai/sdk';
+     *
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * shellx.setLogLevel(LogLevel.NONE);  // Disable all logging
+     * shellx.setLogLevel(LogLevel.ERROR); // Only errors
+     * shellx.setLogLevel(LogLevel.DEBUG); // All logs
+     * ```
+     */
+    setLogLevel(level: LogLevel): void;
+    /**
+     * Enable all logging (equivalent to setLogLevel(LogLevel.DEBUG))
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * shellx.enableDebugLogging();
+     * ```
+     */
+    enableDebugLogging(): void;
+    /**
+     * Disable all logging (equivalent to setLogLevel(LogLevel.NONE))
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * shellx.disableLogging();
+     * ```
+     */
+    disableLogging(): void;
+    /**
+     * Ensure connection is ready before executing device operations
+     *
+     * @param timeout - Timeout in milliseconds (default: 10000ms)
+     * @throws Error if connection timeout
+     */
+    private ensureConnectionReady;
+    /**
+     * Send chat message through ShellX
+     *
+     * @param message - The chat message to send
+     * @returns Promise that resolves when the message is sent
+     */
+    sendChat(message: string): Promise<void>;
+    /**
+     * Execute a click action
+     *
+     * @param selector - Element selector (text) or full click configuration
+     * @param options - Additional click options (when using string selector)
+     * @returns Promise resolving to ClickResult
+     *
+     * @example
+     * ```typescript
+     * // Simplified - click by text
+     * await shellx.click('Submit');
+     *
+     * // Simplified - click by text with options
+     * await shellx.click('Submit', { clickType: 'long' });
+     *
+     * // Full - click by element ID
+     * await shellx.click({ elementId: 'element123' });
+     *
+     * // Full - click by coordinates
+     * await shellx.click({ x: 500, y: 1000 });
+     *
+     * // Full - click by text
+     * await shellx.click({ text: 'Submit' });
+     * ```
+     */
+    click(selector: string, options?: Omit<Click, "text" | "elementId" | "resourceId" | "class" | "x" | "y">): Promise<ClickResult>;
+    click(clickData: Click): Promise<ClickResult>;
+    /**
+     * Execute an input action
+     *
+     * @param inputData - Input configuration
+     * @returns Promise resolving to InputResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.input({
+     *   elementId: 'field123',
+     *   text: 'Hello World',
+     *   clear: true
+     * });
+     * ```
+     */
+    input(inputData: Input): Promise<InputResult>;
+    /**
+     * Execute a swipe action
+     *
+     * @param swipeData - Swipe configuration
+     * @returns Promise resolving to SwipeResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.swipe({
+     *   fromX: 500,
+     *   fromY: 1000,
+     *   toX: 500,
+     *   toY: 500,
+     *   duration: 800
+     * });
+     * ```
+     */
+    swipe(swipeData: Swipe): Promise<SwipeResult>;
+    /**
+     * Execute a key press action
+     *
+     * @param key - Key code (without KEYCODE_ prefix) or full key configuration
+     * @param options - Additional key options (when using string key)
+     * @returns Promise resolving to KeyResult
+     *
+     * @example
+     * ```typescript
+     * // Simplified - press back key
+     * await shellx.press('BACK');
+     *
+     * // Simplified - press home key
+     * await shellx.press('HOME');
+     *
+     * // Simplified - long press menu key
+     * await shellx.press('MENU', { longPress: true });
+     *
+     * // Full - press with all options
+     * await shellx.press({ key: 'BACK', longPress: true });
+     * ```
+     */
+    press(key: string, options?: Omit<Key, "key">): Promise<KeyResult>;
+    press(keyData: Key): Promise<KeyResult>;
+    /**
+     * Wait for an element condition
+     *
+     * @param selector - Element selector (text) or full wait configuration
+     * @param options - Additional wait options (when using string selector)
+     * @returns Promise resolving to WaitResult
+     *
+     * @example
+     * ```typescript
+     * // Simplified - wait for element to appear
+     * await shellx.wait('Submit');
+     *
+     * // Simplified - wait with timeout
+     * await shellx.wait('Loading', { timeout: 10000 });
+     *
+     * // Simplified - wait for element to disappear
+     * await shellx.wait('Loading', { condition: 'gone' });
+     *
+     * // Full - wait with all options
+     * await shellx.wait({ text: 'Submit', condition: 'visible', timeout: 10000 });
+     * ```
+     */
+    wait(selector: string, options?: Omit<Wait, "text" | "elementId" | "resourceId" | "class">): Promise<WaitResult>;
+    wait(waitData: Wait): Promise<WaitResult>;
+    /**
+     * Find UI elements
+     *
+     * @param selector - Element selector (text) or full find configuration
+     * @param options - Additional find options (when using string selector)
+     * @returns Promise resolving to FindResult
+     *
+     * @example
+     * ```typescript
+     * // Simplified - find single element
+     * const result = await shellx.find('Submit');
+     *
+     * // Simplified - find multiple elements
+     * const all = await shellx.find('Submit', { multiple: true, maxResults: 10 });
+     *
+     * // Full - find with all options
+     * const result = await shellx.find({ text: 'Submit', multiple: true });
+     *
+     * console.log(`Found ${result.count} elements`);
+     * result.elements.forEach(el => console.log(el.text));
+     * ```
+     */
+    find(selector: string, options?: Omit<Find, "text" | "elementId" | "resourceId" | "class">): Promise<TypesFindResult>;
+    find(findData: Find): Promise<TypesFindResult>;
+    /**
+     * Execute a shell command
+     *
+     * @param cmd - Command string or full command configuration
+     * @param options - Additional command options (when using string command)
+     * @returns Promise resolving to CommandResult
+     *
+     * @example
+     * ```typescript
+     * // Simplified - execute command
+     * const result = await shellx.command('ls -la');
+     *
+     * // Simplified - execute with timeout
+     * const result = await shellx.command('ls -la', { timeout: 5000 });
+     *
+     * // Full - execute with all options
+     * const result = await shellx.command({ cmd: 'ls -la', timeout: 5000 });
+     *
+     * console.log(result.output);
+     * ```
+     */
+    command(cmd: string, options?: Omit<Command, "cmd">): Promise<TypesCommandResult>;
+    command(commandData: Command): Promise<TypesCommandResult>;
+    /**
+     * Execute a clipboard action
+     *
+     * @param clipboardData - Clipboard configuration
+     * @returns Promise resolving to ClipboardResult
+     *
+     * @example
+     * ```typescript
+     * // Get clipboard content
+     * const result = await shellx.clipboard({ get: true });
+     * console.log(result.text);
+     *
+     * // Set clipboard content
+     * await shellx.clipboard({ text: 'Hello' });
+     *
+     * // Paste clipboard content
+     * await shellx.clipboard({ paste: true });
+     * ```
+     */
+    clipboard(clipboardData: Clipboard): Promise<ClipboardResult>;
+    /**
+     * Get application information
+     *
+     * @param pkg - Package name or full app info configuration
+     * @param options - Additional app info options (when using string package)
+     * @returns Promise resolving to AppInfoResult
+     *
+     * @example
+     * ```typescript
+     * // Simplified - get app info
+     * const result = await shellx.getAppInfo('com.example.app');
+     *
+     * // Simplified - get with retry
+     * const result = await shellx.getAppInfo('com.example.app', { retry: 3 });
+     *
+     * // Full - get with all options
+     * const result = await shellx.getAppInfo({ package: 'com.example.app', retry: 3 });
+     * ```
+     */
+    getAppInfo(pkg: string, options?: Omit<AppInfo, "package">): Promise<AppInfoResult>;
+    getAppInfo(appInfoData: AppInfo): Promise<AppInfoResult>;
+    /**
+     * Get list of installed applications
+     *
+     * @param options - Options for filtering app list
+     * @returns Promise resolving to app list response
+     *
+     * @example
+     * ```typescript
+     * // Get all user apps
+     * const result = await shellx.getAppList();
+     * console.log(`Found ${result.userAppCount} user apps`);
+     * result.apps.forEach(app => {
+     *   console.log(`${app.appName} (${app.packageName})`);
+     * });
+     *
+     * // Get user and system apps
+     * const allApps = await shellx.getAppList({
+     *   includeSystemApps: true,
+     *   includeDisabledApps: false
+     * });
+     * ```
+     */
+    getAppList(options?: {
+        includeSystemApps?: boolean;
+        includeDisabledApps?: boolean;
+    }): Promise<{
+        apps: Array<{
+            packageName: string;
+            appName: string;
+            versionName: string;
+            versionCode: number;
+            isSystemApp: boolean;
+            isEnabled: boolean;
+            firstInstallTime: number;
+            lastUpdateTime: number;
+            sourceDir: string;
+        }>;
+        totalCount: number;
+        systemAppCount: number;
+        userAppCount: number;
+        timestamp: number;
+        success?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Take a screenshot
+     *
+     * @param screenshotData - Screenshot configuration
+     * @returns Promise resolving to ScreenshotResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.takeScreenshot({
+     *   format: 'png',
+     *   quality: 100,
+     *   saveToFile: true
+     * });
+     *
+     * console.log(result.imagePath);
+     * ```
+     */
+    takeScreenshot(screenshotData?: Screenshot): Promise<ScreenshotResult>;
+    /**
+     * Get screen information
+     *
+     * @returns Promise resolving to ScreenInfoResult
+     *
+     * @example
+     * ```typescript
+     * const screenInfo = await shellx.getScreenInfo();
+     * console.log(`Screen: ${screenInfo.width}x${screenInfo.height}`);
+     * console.log(`Current app: ${screenInfo.foregroundApp}`);
+     * ```
+     */
+    getScreenInfo(): Promise<ScreenInfoResult>;
+    /**
+     * Execute multiple actions in sequence
+     *
+     * @param actions - Array of actions to execute
+     * @returns Promise resolving to ExecuteActionsResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.executeActions([
+     *   { text: 'Settings' },
+     *   { text: 'Accounts' },
+     *   { cmd: 'ls -la' }
+     * ]);
+     *
+     * console.log(`Success: ${result.successCount}, Failed: ${result.failureCount}`);
+     * result.results.forEach((res, index) => {
+     *   console.log(`Action ${index + 1}: ${res.success ? 'Success' : 'Failed'}`);
+     * });
+     * ```
+     */
+    executeActions(actions: Array<Click | Input | Swipe | Key | Wait | Find | Command | AppInfo | Screenshot | Clipboard>): Promise<ExecuteActionsResult>;
+    /**
+     * Find a single element with retry logic
+     *
+     * @param selector - Element selector
+     * @param maxRetries - Maximum retry attempts (default: 3)
+     * @param retryDelay - Delay between retries in milliseconds (default: 1000)
+     * @returns Promise resolving to UIElement or null
+     *
+     * @example
+     * ```typescript
+     * const element = await shellx.findElement(
+     *   { text: 'Submit', visible: true },
+     *   3,
+     *   1000
+     * );
+     * ```
      */
     findElementWithRetry(selector: ElementSelector, maxRetries?: number, retryDelay?: number): Promise<UIElement | null>;
     /**
-     * Smart multiple elements finder with retry logic
+     * Find multiple elements with retry logic
+     *
+     * @param selector - Element selector
+     * @param maxRetries - Maximum retry attempts (default: 3)
+     * @param retryDelay - Delay between retries in milliseconds (default: 1000)
+     * @param options - Additional find options
+     * @returns Promise resolving to array of UIElements
+     *
+     * @example
+     * ```typescript
+     * const elements = await shellx.findElementsWithRetry(
+     *   { className: 'Button', visible: true },
+     *   3,
+     *   1000,
+     *   { maxResults: 10 }
+     * );
+     * ```
      */
     findElementsWithRetry(selector: ElementSelector, maxRetries?: number, retryDelay?: number, options?: {
         maxResults?: number;
         visibleOnly?: boolean;
         clickableOnly?: boolean;
     }): Promise<UIElement[]>;
-    /**
-     * 打印元素信息的工具方法
-     */
-    printElementInfo(element: UIElement, index?: number): void;
-    /**
-     * 打印多个元素信息的工具方法
-     */
-    printElementsInfo(elements: UIElement[], title?: string): void;
-    /**
-     * Click element by text content
-     */
-    clickByText(text: string, exact?: boolean): Promise<boolean>;
-    /**
-     * Input text into field
-     */
-    inputText(selector: ElementSelector, text: string, options?: {
-        clear?: boolean;
-        hideKeyboard?: boolean;
-    }): Promise<boolean>;
-    /**
-     * Take screenshot and save info
-     */
-    captureScreen(options?: ScreenShotOptions & {
-        saveInfo?: boolean;
-    }): Promise<import("./protocol").ScreenShotResponse>;
     /**
      * Wait for any of multiple elements to appear
+     * @deprecated Use waitAnyElement() instead for consistency
      */
     waitForAnyElement(selectors: ElementSelector[], timeout?: number): Promise<{
         element: UIElement;
         selectorIndex: number;
     } | null>;
     /**
-     * Navigate through app using a series of clicks
-     */
-    navigateByPath(textPath: string[]): Promise<boolean>;
-    /**
-     * Scroll to find element
-     */
-    scrollToFindElement(selector: ElementSelector, maxScrolls?: number, direction?: 'up' | 'down'): Promise<UIElement | null>;
-    /**
-     * Execute shell command action with output monitoring
-     */
-    executeShellCommand(command: string, options?: ShellCommandOptions): Promise<ShellCommandResult>;
-    /**
-     * Execute shell command with simple output (for backward compatibility)
-     */
-    executeSimpleShellCommand(command: string, options?: {
-        title?: string;
-        timeout?: number;
-        waitAfterMs?: number;
-    }): Promise<ShellCommandResult>;
-    /**
-     * Execute multiple shell commands in sequence
-     */
-    executeShellCommands(commands: Array<{
-        command: string;
-        title?: string;
-        waitAfterMs?: number;
-    }>, options?: {
-        continueOnError?: boolean;
-        timeout?: number;
-    }): Promise<ShellCommandResult[]>;
-    /**
-     * Common ADB commands helper
-     */
-    adbCommand(command: string, options?: ShellCommandOptions): Promise<ShellCommandResult>;
-    /**
-     * Device info commands
-     */
-    getDeviceInfo(): Promise<ShellCommandResult[]>;
+     * Wait for any of multiple elements to appear
+     *
+     * @param selectors - Array of element selectors
+     * @param timeout - Maximum wait time in milliseconds (default: 10000)
+     * @returns Promise resolving to the first found element and its index, or null
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.waitAnyElement(
+     *   [
+     *     { text: 'Submit' },
+     *     { text: 'OK' },
+     *     { text: 'Confirm' }
+     *   ],
+     *   10000
+     * );
+     * ```
+     */
+    waitAnyElement(selectors: ElementSelector[], timeout?: number): Promise<{
+        element: UIElement;
+        selectorIndex: number;
+    } | null>;
     /**
-     * Execute key action (press a key)
-     */
-    executeKeyAction(keyCode: string, options?: {
-        longPress?: boolean;
-        waitAfterMs?: number;
-    }): Promise<boolean>;
+     * Scroll to find an element
+     *
+     * @param selector - Element selector
+     * @param maxScrolls - Maximum scroll attempts (default: 5)
+     * @param direction - Scroll direction (default: 'down')
+     * @returns Promise resolving to UIElement or null
+     *
+     * @example
+     * ```typescript
+     * const element = await shellx.scrollToFindElement(
+     *   { text: 'Target' },
+     *   5,
+     *   'down'
+     * );
+     * ```
+     */
+    scrollToFindElement(selector: ElementSelector, maxScrolls?: number, direction?: "up" | "down"): Promise<UIElement | null>;
+    /**
+     * Handle shell output from WebSocket messages
+     *
+     * This method should be called in the WebSocket message handler.
+     *
+     * @param chunks - Shell output chunks
+     *
+     * @example
+     * ```typescript
+     * const client = new ConnectionClient(deviceId, {
+     *   onMessage: (message) => {
+     *     if (message.chunks) {
+     *       shellx.handleShellOutput(message.chunks);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    handleShellOutput(chunks: [number, number, Uint8Array[]]): void;
+    /**
+     * Send raw WebSocket message (for advanced use cases)
+     *
+     * This method allows you to send raw WebSocket protocol messages directly,
+     * bypassing the high-level ShellX API. This is useful for:
+     * - Custom protocol operations not exposed by ShellX
+     * - Testing and debugging
+     * - Advanced integrations requiring low-level control
+     *
+     * @param message - Raw WebSocket client message (WsClient type)
+     * @returns Promise resolving to the server response
+     *
+     * @example
+     * ```typescript
+     * // Send a custom find element request
+     * await shellx.sendRawMessage({
+     *   findElement: {
+     *     type: 'find',
+     *     selector: { text: 'Submit' },
+     *     options: { maxResults: 10 }
+     *   }
+     * });
+     *
+     * // Send a custom action sequence
+     * await shellx.sendRawMessage({
+     *   actions: [
+     *     { action: 'Launch', app: 'com.example.app' },
+     *     { action: 'Tap', element: [500, 1000] }
+     *   ]
+     * });
+     *
+     * // Send screen info request
+     * await shellx.sendRawMessage({
+     *   screenInfo: { keepScreenOn: true, wakeApp: true }
+     * });
+     * ```
+     */
+    sendRawMessage(message: WsClient): Promise<unknown>;
+    /**
+     * Start ASR (Automatic Speech Recognition)
+     * @returns Promise that resolves when speech recognition has started
+     *
+     * @example
+     * ```typescript
+     * await shellx.startSpeechRecognition();
+     * console.log('Speech recognition started');
+     * ```
+     */
+    startSpeechRecognition(): Promise<void>;
+    /**
+     * Stop ASR (Automatic Speech Recognition)
+     * @returns Promise that resolves when speech recognition has stopped
+     *
+     * @example
+     * ```typescript
+     * await shellx.stopSpeechRecognition();
+     * console.log('Speech recognition stopped');
+     * ```
+     */
+    stopSpeechRecognition(): Promise<void>;
+    /**
+     * Speak text aloud using TTS (Text-to-Speech)
+     * @param text - The text to speak
+     * @returns Promise that resolves when TTS has started speaking
+     *
+     * @example
+     * ```typescript
+     * await shellx.speak('Hello, world!');
+     * ```
+     */
+    speak(text: string): Promise<void>;
+    /**
+     * Stop TTS (Text-to-Speech)
+     * @returns Promise that resolves when TTS has stopped speaking
+     *
+     * @example
+     * ```typescript
+     * await shellx.stopSpeaking();
+     * ```
+     */
+    stopSpeaking(): Promise<void>;
+    /**
+     * Static factory method to create shell output handler
+     * @deprecated This method is kept for backward compatibility but is no longer needed
+     * @param shellx - The ShellX instance
+     * @returns Message handler function
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * const handler = ShellX.createShellOutputHandler(shellx);
+     * ```
+     */
+    static createShellOutputHandler(shellx: ShellX): (message: WsServer) => void;
 }
-/**
- * Create ShellX instance
- */
-export declare function createShellX(client: ConnectionTaskClient): ShellX;
-/**
- * Create ShellX instance with automatic authentication and shell output monitoring
- * 自动处理ShellX.ai认证和连接，无需外部提供连接地址
- */
-export declare function createShellXWithShellMonitoring(config?: any): Promise<ShellX>;