shellx-ai 1.0.11 → 1.1.0

package/dist/automation/ui-action-handler.js

@@ -0,0 +1,873 @@
+/**
+ * UIActionHandler - A module for handling UI automation actions
+ *
+ * This module provides functionality for executing various UI actions such as
+ * clicking, inputting text, swiping, pressing keys, and more.
+ */
+import { RetryHelper } from "../utils/retry-helper.js";
+import { extractErrorMessage, createErrorResult, createSuccessResult, validateOneOfRequired, validateRequired, } from "../error-handler.js";
+import { ValidationError } from "../errors.js";
+import { ElementFinder } from "./element-finder.js";
+import { createLogger } from "../logger.js";
+/**
+ * UIActionHandler class handles UI automation operations
+ *
+ * This class provides methods to:
+ * - Execute UI actions (click, input, swipe, key press)
+ * - Wait for elements
+ * - Take screenshots
+ * - Execute action sequences
+ * - Navigate through app UI
+ */
+export class UIActionHandler {
+    client;
+    elementFinder;
+    logger = createLogger("UIActionHandler");
+    /**
+     * Creates a UIActionHandler instance
+     *
+     * @param client - The ConnectionClient instance for UI operations
+     */
+    constructor(client) {
+        this.client = client;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
+        this.elementFinder = new ElementFinder(client);
+    }
+    /**
+     * Validate that client is initialized
+     *
+     * @returns true if client is valid, false otherwise
+     */
+    validateClient(methodName) {
+        if (!this.client) {
+            this.logger.error(`❌ Cannot execute ${methodName}: Client is not initialized`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Convert simplified selector to protocol selector
+     *
+     * @param selector - Simplified selector object
+     * @returns Protocol ElementSelector object
+     */
+    convertSelector(selector) {
+        return {
+            elementId: selector.elementId,
+            resourceId: selector.resourceId,
+            className: selector.class,
+            text: selector.text,
+            textContains: undefined,
+            visible: selector.visible,
+            clickable: selector.clickable,
+        };
+    }
+    /**
+     * Execute action and verify it succeeded
+     *
+     * @param action - The action sequence to execute
+     */
+    async executeAndVerifyAction(action) {
+        await this.client.executeAction(action);
+    }
+    /**
+     * Execute operation with retry and unified error handling
+     *
+     * @param operation - Async operation to execute
+     * @param startTime - Operation start time
+     * @param options - Retry and error handling options
+     * @returns Promise resolving to operation result
+     */
+    async executeWithRetry(operation, startTime, options = {}) {
+        const { retry = 3, delay = 500, logPrefix, defaultErrorMessage } = options;
+        for (let attempt = 1; attempt <= retry; attempt++) {
+            try {
+                const data = await operation();
+                return createSuccessResult(data, startTime);
+            }
+            catch (error) {
+                const isLastAttempt = attempt === retry;
+                const errorMessage = extractErrorMessage(error);
+                if (!isLastAttempt) {
+                    if (logPrefix) {
+                        this.logger.warn(`${logPrefix} - Attempt ${attempt}/${retry} failed: ${errorMessage}. Retrying in ${delay}ms...`);
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                else {
+                    if (logPrefix) {
+                        this.logger.error(`${logPrefix} - Failed after ${retry} attempts: ${errorMessage}`);
+                    }
+                    return createErrorResult(error, startTime, {
+                        logPrefix,
+                        defaultErrorMessage,
+                    });
+                }
+            }
+        }
+        // This should never be reached
+        return createErrorResult(new Error("Operation failed unexpectedly"), startTime, {
+            logPrefix,
+            defaultErrorMessage,
+        });
+    }
+    /**
+     * Execute a click action
+     *
+     * @param clickData - Click configuration
+     * @returns Promise resolving to ClickResult
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.click({
+     *   elementId: 'element123',
+     *   clickType: 'single',
+     *   wait: 3000
+     * });
+     * ```
+     */
+    async click(clickData) {
+        const startTime = Date.now();
+        // Validate client
+        if (!this.validateClient("click")) {
+            return createErrorResult(new Error("Client not initialized"), startTime, {
+                logPrefix: "❌ [UIActionHandler] click",
+            });
+        }
+        // Validate target
+        validateOneOfRequired(clickData, ["elementId", "resourceId", "x", "y", "text", "class"]);
+        return await this.executeWithRetry(async () => {
+            // Ensure visibility for click operations
+            clickData.visible = true;
+            let target;
+            if (clickData.elementId) {
+                target = { type: "elementId", value: clickData.elementId };
+            }
+            else if (clickData.resourceId) {
+                target = { type: "resourceId", value: clickData.resourceId };
+            }
+            else if (clickData.x !== undefined && clickData.y !== undefined) {
+                target = { type: "coordinate", value: { x: clickData.x, y: clickData.y } };
+            }
+            else if (clickData.text || clickData.class) {
+                const element = await this.elementFinder.findElement(this.convertSelector(clickData), {
+                    maxRetries: 1,
+                });
+                validateRequired(element, "Target element");
+                target = { type: "elementId", value: element.elementId };
+            }
+            else {
+                throw new ValidationError("Must specify target: elementId, resourceId, coordinates, or selector");
+            }
+            const action = {
+                title: `Click action: ${clickData.clickType || "single"}`,
+                actions: [
+                    {
+                        type: "click",
+                        target,
+                        options: {
+                            clickType: clickData.clickType || "single",
+                            waitAfterMs: clickData.wait || 3000,
+                        },
+                    },
+                ],
+            };
+            await this.executeAndVerifyAction(action);
+            return {
+                elementId: clickData.elementId,
+                resourceId: clickData.resourceId,
+                text: clickData.text,
+                class: clickData.class,
+                x: clickData.x,
+                y: clickData.y,
+                clickType: clickData.clickType,
+            };
+        }, startTime, { retry: clickData.retry, delay: 500, logPrefix: "🔨 [UIActionHandler] click" });
+    }
+    /**
+     * Execute an input action
+     *
+     * @param inputData - Input configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.input({
+     *   elementId: 'element123',
+     *   text: 'Hello World',
+     *   clear: true,
+     *   hideKeyboard: false,
+     *   wait: 500
+     * });
+     * ```
+     */
+    async input(inputData) {
+        const startTime = Date.now();
+        // Validate client
+        if (!this.validateClient("input")) {
+            return createErrorResult(new Error("Client not initialized"), startTime, {
+                logPrefix: "❌ [UIActionHandler] input",
+            });
+        }
+        // Validate target
+        validateOneOfRequired(inputData, ["elementId", "resourceId"]);
+        return await this.executeWithRetry(async () => {
+            let target;
+            if (inputData.elementId) {
+                target = { type: "elementId", value: inputData.elementId };
+            }
+            else if (inputData.resourceId) {
+                target = { type: "resourceId", value: inputData.resourceId };
+            }
+            else {
+                throw new ValidationError("Must specify target: elementId or resourceId");
+            }
+            const action = {
+                title: `Input text: ${inputData.text}`,
+                actions: [
+                    {
+                        type: "input",
+                        text: inputData.text,
+                        target,
+                        options: {
+                            replaceExisting: inputData.clear ?? true,
+                            hideKeyboardAfter: inputData.hideKeyboard ?? false,
+                            waitAfterMs: inputData.wait || 500,
+                        },
+                    },
+                ],
+            };
+            await this.executeAndVerifyAction(action);
+            return {
+                text: inputData.text,
+                elementId: inputData.elementId,
+                resourceId: inputData.resourceId,
+                cleared: inputData.clear,
+            };
+        }, startTime, { retry: inputData.retry, delay: 500, logPrefix: "🔨 [UIActionHandler] input" });
+    }
+    /**
+     * Execute a swipe action
+     *
+     * @param swipeData - Swipe configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.swipe({
+     *   fromX: 500,
+     *   fromY: 1000,
+     *   toX: 500,
+     *   toY: 500,
+     *   duration: 800,
+     *   wait: 500
+     * });
+     * ```
+     */
+    async swipe(swipeData) {
+        const startTime = Date.now();
+        // Validate client
+        if (!this.validateClient("swipe")) {
+            return createErrorResult(new Error("Client not initialized"), startTime, {
+                logPrefix: "❌ [UIActionHandler] swipe",
+            });
+        }
+        // Validate coordinates
+        validateRequired(swipeData.fromX, "fromX");
+        validateRequired(swipeData.fromY, "fromY");
+        validateRequired(swipeData.toX, "toX");
+        validateRequired(swipeData.toY, "toY");
+        return await this.executeWithRetry(async () => {
+            const from = { x: swipeData.fromX, y: swipeData.fromY };
+            const to = { x: swipeData.toX, y: swipeData.toY };
+            const action = {
+                title: `Swipe action: ${from.x},${from.y} → ${to.x},${to.y}`,
+                actions: [
+                    {
+                        type: "swipe",
+                        from,
+                        to,
+                        options: {
+                            durationMs: swipeData.duration || 800,
+                            waitAfterMs: swipeData.wait || 500,
+                        },
+                    },
+                ],
+            };
+            await this.executeAndVerifyAction(action);
+            return {
+                fromX: swipeData.fromX,
+                fromY: swipeData.fromY,
+                toX: swipeData.toX,
+                toY: swipeData.toY,
+            };
+        }, startTime, { retry: swipeData.retry, delay: 500, logPrefix: "🔨 [UIActionHandler] swipe" });
+    }
+    /**
+     * Execute a key press action
+     *
+     * @param keyData - Key configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.pressKey({
+     *   key: 'KEYCODE_BACK',
+     *   longPress: false,
+     *   wait: 500
+     * });
+     * ```
+     */
+    async pressKey(keyData) {
+        const startTime = Date.now();
+        // Validate client
+        if (!this.validateClient("pressKey")) {
+            return createErrorResult(new Error("Client not initialized"), startTime, {
+                logPrefix: "❌ [UIActionHandler] pressKey",
+            });
+        }
+        // Validate key
+        validateRequired(keyData.key, "key");
+        return await this.executeWithRetry(async () => {
+            // Automatically add KEYCODE_ prefix if not present
+            const keyCode = keyData.key.startsWith("KEYCODE_")
+                ? keyData.key
+                : `KEYCODE_${keyData.key.toUpperCase()}`;
+            const action = {
+                title: `Key press: ${keyCode}${keyData.longPress ? " (long press)" : ""}`,
+                actions: [
+                    {
+                        type: "key",
+                        keyCode: keyCode,
+                        options: {
+                            longPress: keyData.longPress || false,
+                        },
+                    },
+                ],
+            };
+            await this.executeAndVerifyAction(action);
+            if (keyData.wait) {
+                await new Promise((resolve) => setTimeout(resolve, keyData.wait));
+            }
+            return {
+                key: keyData.key,
+                longPress: keyData.longPress,
+            };
+        }, startTime, { retry: keyData.retry, delay: 500, logPrefix: "🔨 [UIActionHandler] pressKey" });
+    }
+    /**
+     * Wait for an element condition
+     *
+     * @param waitData - Wait configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * // Wait for element to appear
+     * const result = await actionHandler.wait({
+     *   text: 'Submit',
+     *   condition: 'visible',
+     *   timeout: 10000
+     * });
+     *
+     * // Wait for element to disappear
+     * const result = await actionHandler.wait({
+     *   text: 'Loading',
+     *   condition: 'gone',
+     *   timeout: 10000
+     * });
+     * ```
+     */
+    async wait(waitData) {
+        const startTime = Date.now();
+        // Validate client
+        if (!this.validateClient("wait")) {
+            return createErrorResult(new Error("Client not initialized"), startTime, {
+                logPrefix: "❌ [UIActionHandler] wait",
+            });
+        }
+        // Validate target
+        validateOneOfRequired(waitData, ["elementId", "resourceId", "text", "class"]);
+        return await this.executeWithRetry(async () => {
+            const selector = this.convertSelector(waitData);
+            const timeout = waitData.timeout || 10000;
+            const interval = 500;
+            const maxAttempts = Math.floor(timeout / interval);
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                try {
+                    const findResult = (await this.client.findElement(selector, {
+                        timeout: interval,
+                        maxResults: 1,
+                        visibleOnly: waitData.condition === "visible",
+                        clickableOnly: waitData.condition === "clickable",
+                    }));
+                    if (!findResult || findResult.success === false) {
+                        await new Promise((resolve) => setTimeout(resolve, interval));
+                        continue;
+                    }
+                    if (findResult.elements && findResult.elements.length > 0) {
+                        if (waitData.condition === "gone") {
+                            await new Promise((resolve) => setTimeout(resolve, interval));
+                            continue;
+                        }
+                        else {
+                            return {
+                                elementId: waitData.elementId,
+                                resourceId: waitData.resourceId,
+                                text: waitData.text,
+                                class: waitData.class,
+                                condition: waitData.condition,
+                                found: true,
+                            };
+                        }
+                    }
+                    else if (waitData.condition === "gone") {
+                        return {
+                            elementId: waitData.elementId,
+                            resourceId: waitData.resourceId,
+                            text: waitData.text,
+                            class: waitData.class,
+                            condition: waitData.condition,
+                            found: false,
+                        };
+                    }
+                }
+                catch {
+                    // Continue waiting
+                }
+                await new Promise((resolve) => setTimeout(resolve, interval));
+            }
+            throw new ValidationError(`Wait timeout: ${waitData.condition || "visible"}`);
+        }, startTime, { retry: waitData.retry, delay: 500, logPrefix: "🔨 [UIActionHandler] wait" });
+    }
+    /**
+     * Execute a clipboard action
+     *
+     * @param clipboardData - Clipboard configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * // Get clipboard content
+     * const result = await actionHandler.clipboard({ get: true });
+     *
+     * // Set clipboard content
+     * const result = await actionHandler.clipboard({
+     *   text: 'Hello',
+     *   paste: false
+     * });
+     *
+     * // Paste clipboard content
+     * const result = await actionHandler.clipboard({ paste: true });
+     * ```
+     */
+    async clipboard(clipboardData) {
+        const startTime = Date.now();
+        const result = await RetryHelper.execute(async () => {
+            try {
+                if (clipboardData.get) {
+                    const { promise } = await this.client.sendMessageWithTaskId({
+                        action: {
+                            action: {
+                                type: "clipboard",
+                                get: true,
+                            },
+                        },
+                    }, "clipboard");
+                    const response = await promise;
+                    if (response) {
+                        return {
+                            success: response.success ?? true,
+                            data: {
+                                text: response.text,
+                            },
+                            error: response.error,
+                            duration: Date.now() - startTime,
+                            timestamp: startTime,
+                        };
+                    }
+                    else {
+                        throw new Error("Failed to get clipboard content");
+                    }
+                }
+                // Write or paste operation
+                if (!clipboardData.paste && (!clipboardData.text || clipboardData.text.length === 0)) {
+                    throw new Error("Must provide text when writing to clipboard");
+                }
+                await this.client.sendMessageWithTaskId({
+                    action: {
+                        action: {
+                            type: "clipboard",
+                            text: clipboardData.text,
+                            paste: clipboardData.paste ?? false,
+                        },
+                    },
+                }, "action");
+                return {
+                    success: true,
+                    data: {
+                        text: clipboardData.text,
+                        paste: clipboardData.paste ?? false,
+                    },
+                    duration: Date.now() - startTime,
+                    timestamp: startTime,
+                };
+            }
+            catch (error) {
+                throw new Error(`Clipboard action failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }, { retry: clipboardData.retry, delay: 500 });
+        if (!result) {
+            return {
+                success: false,
+                error: "Clipboard action failed",
+                duration: Date.now() - startTime,
+                timestamp: startTime,
+            };
+        }
+        return result;
+    }
+    /**
+     * Take a screenshot
+     *
+     * @param screenshotData - Screenshot configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.takeScreenshot({
+     *   format: 'png',
+     *   quality: 100,
+     *   scale: 1,
+     *   saveToFile: true
+     * });
+     * ```
+     */
+    async takeScreenshot(screenshotData = {}) {
+        const startTime = Date.now();
+        const result = await RetryHelper.execute(async () => {
+            try {
+                const options = {
+                    format: screenshotData.format || "png",
+                    quality: screenshotData.quality || 100,
+                    scale: screenshotData.scale || 1,
+                };
+                if (screenshotData.saveToFile !== undefined) {
+                    options.saveToFile = screenshotData.saveToFile;
+                }
+                if (screenshotData.regionX !== undefined &&
+                    screenshotData.regionY !== undefined &&
+                    screenshotData.regionWidth !== undefined &&
+                    screenshotData.regionHeight !== undefined) {
+                    options.region = {
+                        left: screenshotData.regionX,
+                        top: screenshotData.regionY,
+                        width: screenshotData.regionWidth,
+                        height: screenshotData.regionHeight,
+                    };
+                }
+                const screenshot = await this.client.screenShot(options);
+                if (!screenshot || screenshot.success === false) {
+                    throw new Error(screenshot?.error || "Screenshot failed");
+                }
+                // Return ScreenshotResult format (flat structure, not nested)
+                return {
+                    success: true,
+                    imageData: screenshot.imageData,
+                    imagePath: screenshot.imagePath,
+                    format: screenshot.format,
+                    width: screenshot.dimensions?.width,
+                    height: screenshot.dimensions?.height,
+                    duration: Date.now() - startTime,
+                    timestamp: screenshot.timestamp || startTime,
+                };
+            }
+            catch (error) {
+                throw new Error(`Screenshot action failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }, { retry: screenshotData.retry, delay: 500 });
+        if (!result) {
+            return {
+                success: false,
+                error: "Screenshot action failed",
+                duration: Date.now() - startTime,
+                timestamp: startTime,
+            };
+        }
+        return result;
+    }
+    /**
+     * Get application info
+     *
+     * @param appInfoData - App info configuration
+     * @returns Promise resolving to ActionResult
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.getAppInfo({
+     *   package: 'com.example.app',
+     *   retry: 3
+     * });
+     * ```
+     */
+    async getAppInfo(appInfoData) {
+        const startTime = Date.now();
+        const result = await RetryHelper.execute(async () => {
+            try {
+                const action = {
+                    title: `Get app info: ${appInfoData.package}`,
+                    actions: [
+                        {
+                            type: "get_app_info",
+                            packageName: appInfoData.package,
+                        },
+                    ],
+                };
+                await this.client.executeAction(action);
+                return {
+                    success: true,
+                    package: appInfoData.package,
+                    duration: Date.now() - startTime,
+                    timestamp: startTime,
+                };
+            }
+            catch (error) {
+                throw new Error(`Get app info failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }, { retry: appInfoData.retry, delay: 500 });
+        if (!result) {
+            return {
+                success: false,
+                error: "Get app info failed",
+                duration: Date.now() - startTime,
+                timestamp: startTime,
+                package: appInfoData.package,
+            };
+        }
+        return result;
+    }
+    /**
+     * Get screen information
+     *
+     * @returns Promise resolving to ScreenInfoResponse
+     *
+     * @example
+     * ```typescript
+     * const screenInfo = await actionHandler.getScreenInfo();
+     * console.log(`Screen size: ${screenInfo.width}x${screenInfo.height}`);
+     * ```
+     */
+    async getScreenInfo() {
+        const result = await RetryHelper.execute(async () => {
+            try {
+                const info = await this.client.getScreenInfo();
+                if (!info || info.success === false) {
+                    throw new Error(info?.error || "Failed to get screen info");
+                }
+                return info;
+            }
+            catch (error) {
+                throw new Error(`Get screen info failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }, { retry: 3, delay: 500 });
+        if (!result) {
+            return {
+                displayId: 0,
+                width: 0,
+                height: 0,
+                density: 0,
+                name: "",
+                visible: false,
+                foregroundPackageName: "",
+                foregroundActivityName: "",
+                screenOn: false,
+                screenUnlocked: false,
+                accurateForegroundActivity: "",
+                accurateForegroundApp: "",
+                bashStatus: 0,
+            };
+        }
+        return result;
+    }
+    /**
+     * Get list of installed applications
+     *
+     * @param options - Options for filtering app list
+     * @returns Promise resolving to app list response
+     *
+     * @example
+     * ```typescript
+     * const result = await actionHandler.getAppList({
+     *   includeSystemApps: false,
+     *   includeDisabledApps: false
+     * });
+     * console.log(`Found ${result.userAppCount} user apps`);
+     * ```
+     */
+    async getAppList(options) {
+        const startTime = Date.now();
+        try {
+            const result = await RetryHelper.execute(async () => {
+                try {
+                    const { promise } = await this.client.sendMessageWithTaskId({ appList: options || {} }, "appList", { timeout: 10000 });
+                    const response = await promise;
+                    // 检查响应是否有效
+                    if (!response) {
+                        throw new Error("Empty response from server");
+                    }
+                    // 类型断言：服务器返回的 appList 数据
+                    const appListData = response;
+                    // 验证必需字段
+                    if (!appListData.apps || !Array.isArray(appListData.apps)) {
+                        throw new Error("Invalid app list format: missing or invalid apps array");
+                    }
+                    // ✅ 返回包含 success 字段的完整响应
+                    return {
+                        apps: appListData.apps,
+                        totalCount: appListData.totalCount || appListData.apps.length,
+                        systemAppCount: appListData.systemAppCount || 0,
+                        userAppCount: appListData.userAppCount || appListData.apps.length,
+                        timestamp: appListData.timestamp || startTime,
+                        success: true, // ✅ 添加 success 字段
+                    };
+                }
+                catch (error) {
+                    throw new Error(`Get app list failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }, { retry: 2, delay: 500 });
+            if (!result) {
+                return {
+                    apps: [],
+                    totalCount: 0,
+                    systemAppCount: 0,
+                    userAppCount: 0,
+                    timestamp: startTime,
+                    success: false,
+                    error: "Get app list failed",
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            // 捕获所有异常，返回统一的错误响应
+            return {
+                apps: [],
+                totalCount: 0,
+                systemAppCount: 0,
+                userAppCount: 0,
+                timestamp: startTime,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Navigate through app using a series of text-based clicks
+     *
+     * @param textPath - Array of text strings to click in sequence
+     * @returns Promise resolving to boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * const success = await actionHandler.navigateByPath([
+     *   'Settings',
+     *   'Accounts',
+     *   'Add Account'
+     * ]);
+     * ```
+     */
+    async navigateByPath(textPath) {
+        try {
+            this.logger.info("Starting navigation path:", textPath.join(" → "));
+            for (const [index, text] of textPath.entries()) {
+                this.logger.info(`Navigation step ${index + 1}/${textPath.length}: Click "${text}"`);
+                await this.clickByText(text);
+                // Wait between clicks
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
+            this.logger.info("✅ Navigation completed");
+            return true;
+        }
+        catch (error) {
+            this.logger.error("❌ Navigation failed:", error);
+            return false;
+        }
+    }
+    /**
+     * Click element by text content
+     *
+     * @param text - Text content to search for
+     * @param exact - Whether to match exact text (default: false)
+     * @returns Promise resolving to boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Click element containing text
+     * await actionHandler.clickByText('Submit');
+     *
+     * // Click element with exact text match
+     * await actionHandler.clickByText('Submit', true);
+     * ```
+     */
+    async clickByText(text, exact = false) {
+        const selector = exact
+            ? { text, clickable: false, visible: true }
+            : { textContains: text, clickable: false, visible: true };
+        const element = await this.elementFinder.findElement(selector, { maxRetries: 3 });
+        if (!element) {
+            return false;
+        }
+        const action = {
+            title: `Click by text: ${text}`,
+            actions: [
+                {
+                    type: "click",
+                    target: { type: "elementId", value: element.elementId },
+                    options: { waitAfterMs: 2000 },
+                },
+            ],
+        };
+        await this.executeAndVerifyAction(action);
+        return true;
+    }
+    /**
+     * Input text into a field
+     *
+     * @param selector - Element selector
+     * @param text - Text to input
+     * @param options - Additional options
+     * @returns Promise resolving to boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * await actionHandler.inputText(
+     *   { resourceId: 'username_field' },
+     *   'john.doe',
+     *   { clear: true, hideKeyboard: false }
+     * );
+     * ```
+     */
+    async inputText(selector, text, options) {
+        const element = await this.elementFinder.findElement(selector, { maxRetries: 3 });
+        if (!element) {
+            return false;
+        }
+        const action = {
+            title: `Input text: ${text}`,
+            actions: [
+                {
+                    type: "input",
+                    text,
+                    target: { type: "elementId", value: element.elementId },
+                    options: {
+                        replaceExisting: options?.clear ?? true,
+                        hideKeyboardAfter: options?.hideKeyboard ?? false,
+                    },
+                },
+            ],
+        };
+        await this.executeAndVerifyAction(action);
+        return true;
+    }
+}
+//# sourceMappingURL=ui-action-handler.js.map