rfi-ai-android/dist/es/index.d.ts

Android automation library for Midscene

import { PageAgent, PageAgentOpt } from 'rfi-ai-web/agent';
import { PageType, Size, Point } from 'rfi-ai-core';
import { ElementInfo } from 'rfi-ai-shared/extractor';
import { AndroidDevicePage, AndroidDeviceInputOpt } from 'rfi-ai-web';
export { overrideAIConfig } from 'rfi-ai-shared/env';

type AndroidDeviceOpt = {
    imeStrategy?: 'webdriverio-only' | 'prefer-webdriverio';
    capabilities?: any;
    hostname?: string;
    port?: number;
    protocol?: 'http' | 'https';
    path?: string;
} & AndroidDeviceInputOpt;
declare class AndroidDevice implements AndroidDevicePage {
    private deviceId;
    private screenSize;
    private deviceRatio;
    private driver;
    private connectingDriver;
    private destroyed;
    pageType: PageType;
    uri: string | undefined;
    options?: AndroidDeviceOpt;
    constructor(deviceId: string, options?: AndroidDeviceOpt);
    /**
     * Connects to the Appium server and starts a session
     */
    connect(): Promise<any>;
    /**
     * Disconnects from the Appium server and ends the session
     */
    disconnect(): Promise<void>;
    getDriver(): Promise<any>;
    launch(uri: string): Promise<AndroidDevice>;
    getElementsInfo(): Promise<ElementInfo[]>;
    getElementsNodeTree(): Promise<any>;
    private getScreenSize;
    size(): Promise<Size>;
    screenshotBase64(): Promise<string>;
    private adjustCoordinates;
    private reverseAdjustCoordinates;
    get mouse(): {
        click: (x: number, y: number) => Promise<void>;
        wheel: (deltaX: number, deltaY: number) => Promise<void>;
        move: (x: number, y: number) => Promise<void>;
        drag: (from: {
            x: number;
            y: number;
        }, to: {
            x: number;
            y: number;
        }) => Promise<void>;
    };
    get keyboard(): {
        type: (text: string, options?: AndroidDeviceInputOpt) => Promise<void>;
        press: (action: {
            key: string;
            command?: string;
        } | {
            key: string;
            command?: string;
        }[]) => Promise<void>;
    };
    clearInput(element: ElementInfo): Promise<void>;
    url(): Promise<string>;
    scrollUntilTop(startPoint?: Point): Promise<void>;
    scrollUntilBottom(startPoint?: Point): Promise<void>;
    scrollUntilLeft(startPoint?: Point): Promise<void>;
    scrollUntilRight(startPoint?: Point): Promise<void>;
    scrollUp(distance?: number, startPoint?: Point): Promise<void>;
    scrollDown(distance?: number, startPoint?: Point): Promise<void>;
    scrollLeft(distance?: number, startPoint?: Point): Promise<void>;
    scrollRight(distance?: number, startPoint?: Point): Promise<void>;
    private keyboardType;
    private keyboardPress;
    private keyboardPressAction;
    private mouseClick;
    private mouseMove;
    /**
     * @deprecated Use swipe() method instead for W3C Actions API compliance
     */
    private mouseDrag;
    destroy(): Promise<void>;
    back(): Promise<void>;
    home(): Promise<void>;
    recentApps(): Promise<void>;
    getXpathsById(id: string): Promise<string[]>;
    getElementInfoByXpath(xpath: string): Promise<ElementInfo>;
    /**
     * W3C Actions API - Tap at specific coordinates
     */
    tap(x: number, y: number): Promise<void>;
    /**
     * W3C Actions API - Swipe from one point to another
     */
    swipe(startX: number, startY: number, endX: number, endY: number, duration?: number): Promise<void>;
}

/**
 * Appium server configuration options
 */
interface AppiumServerConfig {
    /**
     * Hostname of the Appium server
     */
    hostname: string;
    /**
     * Port number of the Appium server
     */
    port: number;
    /**
     * Path to the WebDriver endpoint (default: '/wd/hub')
     */
    path?: string;
    /**
     * Protocol to use (default: 'http')
     */
    protocol?: 'http' | 'https';
}
/**
 * Base capabilities for Appium Android sessions
 */
interface AppiumBaseCapabilities {
    /**
     * Platform name (must be 'Android')
     */
    platformName: 'Android';
    /**
     * Automation name (e.g., 'UiAutomator2', 'Espresso')
     */
    'appium:automationName'?: string;
    /**
     * Android platform version
     */
    'appium:platformVersion'?: string;
    /**
     * Device name
     */
    'appium:deviceName'?: string;
    /**
     * Device UDID (unique device identifier)
     */
    'appium:udid'?: string;
    /**
     * Path or URL to APK file
     */
    'appium:app'?: string;
    /**
     * Package name of the Android app
     */
    'appium:appPackage'?: string;
    /**
     * Activity name to launch
     */
    'appium:appActivity'?: string;
    /**
     * Timeout for new commands in seconds
     */
    'appium:newCommandTimeout'?: number;
    /**
     * Automatically grant permissions to the app
     */
    'appium:autoGrantPermissions'?: boolean;
    /**
     * Other vendor-specific capabilities
     */
    [key: string]: any;
}
/**
 * Sauce Labs specific options
 */
interface SauceLabsSpecificOptions {
    /**
     * Build identifier
     */
    build?: string;
    /**
     * Test name
     */
    name?: string;
    /**
     * Tags for the test
     */
    tags?: string[];
    /**
     * Tunnel identifier for Sauce Connect
     */
    tunnelIdentifier?: string;
    /**
     * Appium version to use
     */
    appiumVersion?: string;
    /**
     * Sauce Labs username
     */
    username?: string;
    /**
     * Sauce Labs access key
     */
    accessKey?: string;
}
/**
 * Sauce Labs capabilities
 */
interface SauceLabsCapabilities extends AppiumBaseCapabilities {
    /**
     * Sauce Labs specific options
     */
    'sauce:options'?: SauceLabsSpecificOptions;
}
/**
 * Sauce Labs configuration
 */
interface SauceLabsConfig {
    /**
     * Sauce Labs username
     */
    user: string;
    /**
     * Sauce Labs access key
     */
    key: string;
    /**
     * Sauce Labs region
     */
    region: 'us-west-1' | 'eu-central-1' | 'us-east-1';
    /**
     * Whether to use headless testing
     */
    headless?: boolean;
}

type AndroidAgentOpt = PageAgentOpt;
declare class AndroidAgent extends PageAgent<AndroidDevice> {
    constructor(page: AndroidDevice, opts?: AndroidAgentOpt);
    launch(uri: string): Promise<void>;
}

declare class AppiumDevice extends AndroidDevice {
    private config;
    private capabilities;
    constructor(config: AppiumServerConfig, capabilities: AppiumBaseCapabilities);
    connect(): Promise<void>;
    getCurrentPackage(): Promise<string>;
    getDriver(): Promise<any>;
}
declare function agentFromAdbDevice(deviceId?: string, opts?: AndroidAgentOpt & AndroidDeviceOpt): Promise<AndroidAgent>;
/**
 * Creates an AndroidAgent from an Appium server
 *
 * @param config - Appium server configuration
 * @param capabilities - Appium capabilities
 * @param agentOpts - Optional agent options
 * @returns Promise resolving to an AndroidAgent
 */
declare function agentFromAppiumServer(config: AppiumServerConfig, capabilities: AppiumBaseCapabilities, agentOpts?: PageAgentOpt): Promise<AndroidAgent>;
/**
 * Creates an AndroidAgent from a local Appium server
 *
 * @param capabilities - Appium capabilities
 * @param agentOpts - Optional agent options
 * @returns Promise resolving to an AndroidAgent
 */
declare function agentFromLocalAppium(capabilities: AppiumBaseCapabilities, agentOpts?: PageAgentOpt): Promise<AndroidAgent>;
/**
 * Creates an AndroidAgent from Sauce Labs
 *
 * @param slConfig - Sauce Labs configuration
 * @param capabilities - Appium capabilities with Sauce Labs options
 * @param agentOpts - Optional agent options
 * @returns Promise resolving to an AndroidAgent
 */
declare function agentFromSauceLabs(slConfig: SauceLabsConfig, capabilities: AppiumBaseCapabilities & SauceLabsCapabilities, agentOpts?: PageAgentOpt): Promise<AndroidAgent>;

/**
 * Performance monitoring utilities for Android devices
 */

/**
 * Interface for CPU information
 */
interface CpuInfo {
    user: number;
    system: number;
    idle: number;
    total: number;
}
/**
 * Interface for memory information
 */
interface MemoryInfo {
    totalMem: number;
    freeMem: number;
    usedMem: number;
    usedMemPercent: number;
}
/**
 * Interface for battery information
 */
interface BatteryInfo {
    level: number;
    status: string;
    temperature: number;
}
/**
 * Interface for network information
 */
interface NetworkInfo {
    rxBytes: number;
    txBytes: number;
    rxPackets: number;
    txPackets: number;
}
/**
 * Interface for device information
 */
interface DeviceInfo {
    model: string;
    manufacturer: string;
    androidVersion: string;
    cpuArchitecture: string;
    cpuCores: number;
    totalRam: string;
    screenDensity: string;
}
/**
 * Interface for performance metrics
 */
interface PerformanceMetrics {
    timestamp: number;
    packageName: string;
    cpuInfo?: CpuInfo;
    memoryInfo?: MemoryInfo;
    batteryInfo?: BatteryInfo;
    networkInfo?: NetworkInfo;
}
/**
 * Performance monitor class for Android devices
 */
declare class PerformanceMonitor {
    private device;
    private defaultPackageName?;
    private metrics;
    private monitoringInterval;
    private availableMetrics;
    private lastActivePackage;
    /**
     * Creates a new PerformanceMonitor instance
     *
     * @param device - AppiumDevice instance
     * @param defaultPackageName - Optional default package name to use if active package detection fails
     */
    constructor(device: AppiumDevice, defaultPackageName?: string);
    /**
     * Gets the currently active package name
     */
    private getActivePackage;
    /**
     * Initializes the performance monitor
     */
    initialize(): Promise<string[]>;
    /**
     * Gets device information
     */
    getDeviceInfo(): Promise<DeviceInfo>;
    /**
     * Gets current performance metrics
     */
    getCurrentMetrics(): Promise<PerformanceMetrics>;
    /**
     * Starts monitoring performance metrics at the specified interval
     *
     * @param intervalMs - Interval in milliseconds (default: 5000)
     */
    startMonitoring(intervalMs?: number): void;
    /**
     * Stops monitoring performance metrics
     */
    stopMonitoring(): void;
    /**
     * Gets all collected metrics
     */
    getMetrics(): PerformanceMetrics[];
    /**
     * Clears all collected metrics
     */
    clearMetrics(): void;
    /**
     * Exports metrics to JSON string
     */
    exportMetricsToJson(): string;
    /**
     * Exports metrics to a JSON file
     *
     * @param filePath - Path to save the JSON file
     */
    exportMetricsToFile(filePath: string): Promise<void>;
    /**
     * Gets metrics for a specific package
     *
     * @param packageName - Package name to filter by
     */
    getMetricsForPackage(packageName: string): PerformanceMetrics[];
    /**
     * Gets metrics within a time range
     *
     * @param startTime - Start timestamp in milliseconds
     * @param endTime - End timestamp in milliseconds
     */
    getMetricsInTimeRange(startTime: number, endTime: number): PerformanceMetrics[];
}

/**
 * Media utility functions for Android automation
 *
 * This module provides helper functions for taking screenshots, recording video,
 * and other media-related operations on Android devices.
 */

/**
 * Options for taking a screenshot
 */
interface ScreenshotOptions {
    /**
     * File path where the screenshot should be saved
     * If not provided, the screenshot will only be returned as base64
     */
    filePath?: string;
    /**
     * Whether to create the directory if it doesn't exist
     * @default true
     */
    createDir?: boolean;
    /**
     * Quality of the screenshot (1-100)
     * Only applicable when saving to a JPEG file
     * @default 90
     */
    quality?: number;
    /**
     * Whether to return the screenshot as base64 data
     * @default true
     */
    returnBase64?: boolean;
}
/**
 * Options for recording video
 */
interface VideoRecordingOptions {
    /**
     * File path where the video should be saved
     */
    filePath: string;
    /**
     * Whether to create the directory if it doesn't exist
     * @default true
     */
    createDir?: boolean;
    /**
     * Maximum duration of the recording in seconds
     * @default 180 (3 minutes)
     */
    timeLimit?: number;
    /**
     * Bit rate for the video in bits per second
     * @default 4000000 (4 Mbps)
     */
    bitRate?: number;
    /**
     * Video size (width x height) in pixels
     * @default "1280x720"
     */
    size?: string;
}
/**
 * Takes a screenshot of the current screen
 *
 * @param device - AppiumDevice instance
 * @param options - Screenshot options
 * @returns Promise resolving to the screenshot as base64 data (if returnBase64 is true)
 *
 * @example
 * ```typescript
 * // Take a screenshot and save it to a file
 * await takeScreenshot(device, { filePath: 'screenshots/home-screen.png' });
 *
 * // Take a screenshot and get it as base64 data
 * const base64Screenshot = await takeScreenshot(device);
 * ```
 */
declare function takeScreenshot(device: AppiumDevice, options?: ScreenshotOptions): Promise<string | void>;
/**
 * Starts recording the screen
 *
 * @param device - AppiumDevice instance
 * @param options - Video recording options
 * @returns Promise resolving when recording has started
 *
 * @example
 * ```typescript
 * // Start recording video
 * await startVideoRecording(device, {
 *   timeLimit: 60, // 1 minute
 *   bitRate: 6000000 // 6 Mbps
 * });
 *
 * // Perform some actions...
 *
 * // Stop recording and save the video
 * await stopVideoRecording(device, { filePath: 'videos/test-recording.mp4' });
 * ```
 */
declare function startVideoRecording(device: AppiumDevice, options?: Partial<VideoRecordingOptions>): Promise<void>;
/**
 * Stops recording the screen and saves the video
 *
 * @param device - AppiumDevice instance
 * @param options - Video recording options
 * @returns Promise resolving to the video as base64 data
 *
 * @example
 * ```typescript
 * // Stop recording and save the video
 * await stopVideoRecording(device, { filePath: 'videos/test-recording.mp4' });
 * ```
 */
declare function stopVideoRecording(device: AppiumDevice, options: VideoRecordingOptions): Promise<string>;

export { AndroidAgent, AndroidDevice, AndroidDevice as AndroidDeviceBase, type AppiumBaseCapabilities, AppiumDevice, type AppiumServerConfig, type BatteryInfo, type CpuInfo, type DeviceInfo, type MemoryInfo, type NetworkInfo, type PerformanceMetrics, PerformanceMonitor, type SauceLabsCapabilities, type SauceLabsConfig, type SauceLabsSpecificOptions, type ScreenshotOptions, type VideoRecordingOptions, agentFromAdbDevice, agentFromAppiumServer, agentFromLocalAppium, agentFromSauceLabs, startVideoRecording, stopVideoRecording, takeScreenshot };