@mediar-ai/terminator 0.20.6

package/index.d.ts

@@ -0,0 +1,738 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Result of element validation */
+export interface ValidationResult {
+  /** Whether the element exists */
+  exists: boolean
+  /** The element if found */
+  element?: Element
+  /** Error message if validation failed (not element not found, but actual error) */
+  error?: string
+}
+export interface Bounds {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+export interface Coordinates {
+  x: number
+  y: number
+}
+export interface ClickResult {
+  method: string
+  coordinates?: Coordinates
+  details: string
+}
+export interface CommandOutput {
+  exitStatus?: number
+  stdout: string
+  stderr: string
+}
+export interface Monitor {
+  id: string
+  name: string
+  isPrimary: boolean
+  width: number
+  height: number
+  x: number
+  y: number
+  scaleFactor: number
+}
+export interface MonitorScreenshotPair {
+  monitor: Monitor
+  screenshot: ScreenshotResult
+}
+export interface ScreenshotResult {
+  width: number
+  height: number
+  imageData: Array<number>
+  monitor?: Monitor
+}
+export interface UIElementAttributes {
+  role: string
+  name?: string
+  label?: string
+  value?: string
+  description?: string
+  properties: Record<string, string | undefined | null>
+  isKeyboardFocusable?: boolean
+  bounds?: Bounds
+}
+export interface UINode {
+  id?: string
+  attributes: UIElementAttributes
+  children: Array<UINode>
+}
+export const enum PropertyLoadingMode {
+  /** Only load essential properties (role + name) - fastest */
+  Fast = 'Fast',
+  /** Load all properties for complete element data - slower but comprehensive */
+  Complete = 'Complete',
+  /** Load specific properties based on element type - balanced approach */
+  Smart = 'Smart'
+}
+export interface TreeBuildConfig {
+  /** Property loading strategy */
+  propertyMode: PropertyLoadingMode
+  /** Optional timeout per operation in milliseconds */
+  timeoutPerOperationMs?: number
+  /** Optional yield frequency for responsiveness */
+  yieldEveryNElements?: number
+  /** Optional batch size for processing elements */
+  batchSize?: number
+}
+export const enum TextPosition {
+  Top = 'Top',
+  TopRight = 'TopRight',
+  Right = 'Right',
+  BottomRight = 'BottomRight',
+  Bottom = 'Bottom',
+  BottomLeft = 'BottomLeft',
+  Left = 'Left',
+  TopLeft = 'TopLeft',
+  Inside = 'Inside'
+}
+export interface FontStyle {
+  size: number
+  bold: boolean
+  color: number
+}
+/** Main entry point for desktop automation. */
+export declare class Desktop {
+  /**
+   * Create a new Desktop automation instance with configurable options.
+   *
+   * @param {boolean} [useBackgroundApps=false] - Enable background apps support.
+   * @param {boolean} [activateApp=false] - Enable app activation support.
+   * @param {string} [logLevel] - Logging level (e.g., 'info', 'debug', 'warn', 'error').
+   * @returns {Desktop} A new Desktop automation instance.
+   */
+  constructor(useBackgroundApps?: boolean | undefined | null, activateApp?: boolean | undefined | null, logLevel?: string | undefined | null)
+  /**
+   * Get the root UI element of the desktop.
+   *
+   * @returns {Element} The root UI element.
+   */
+  root(): Element
+  /**
+   * Get a list of all running applications.
+   *
+   * @returns {Array<Element>} List of application UI elements.
+   */
+  applications(): Array<Element>
+  /**
+   * Get a running application by name.
+   *
+   * @param {string} name - The name of the application to find.
+   * @returns {Element} The application UI element.
+   */
+  application(name: string): Element
+  /**
+   * Open an application by name.
+   *
+   * @param {string} name - The name of the application to open.
+   */
+  openApplication(name: string): Element
+  /**
+   * Activate an application by name.
+   *
+   * @param {string} name - The name of the application to activate.
+   */
+  activateApplication(name: string): void
+  /**
+   * (async) Run a shell command.
+   *
+   * @param {string} [windowsCommand] - Command to run on Windows.
+   * @param {string} [unixCommand] - Command to run on Unix.
+   * @returns {Promise<CommandOutput>} The command output.
+   */
+  runCommand(windowsCommand?: string | undefined | null, unixCommand?: string | undefined | null): Promise<CommandOutput>
+  /**
+   * (async) Execute a shell command using GitHub Actions-style syntax.
+   *
+   * @param {string} command - The command to run (can be single or multi-line).
+   * @param {string} [shell] - Optional shell to use (defaults to PowerShell on Windows, bash on Unix).
+   * @param {string} [workingDirectory] - Optional working directory for the command.
+   * @returns {Promise<CommandOutput>} The command output.
+   */
+  run(command: string, shell?: string | undefined | null, workingDirectory?: string | undefined | null): Promise<CommandOutput>
+  /**
+   * (async) Perform OCR on an image file.
+   *
+   * @param {string} imagePath - Path to the image file.
+   * @returns {Promise<string>} The extracted text.
+   */
+  ocrImagePath(imagePath: string): Promise<string>
+  /**
+   * (async) Perform OCR on a screenshot.
+   *
+   * @param {ScreenshotResult} screenshot - The screenshot to process.
+   * @returns {Promise<string>} The extracted text.
+   */
+  ocrScreenshot(screenshot: ScreenshotResult): Promise<string>
+  /**
+   * (async) Get the currently focused browser window.
+   *
+   * @returns {Promise<Element>} The current browser window element.
+   */
+  getCurrentBrowserWindow(): Promise<Element>
+  /**
+   * Create a locator for finding UI elements.
+   *
+   * @param {string | Selector} selector - The selector.
+   * @returns {Locator} A locator for finding elements.
+   */
+  locator(selector: string | Selector): Locator
+  /**
+   * (async) Get the currently focused window.
+   *
+   * @returns {Promise<Element>} The current window element.
+   */
+  getCurrentWindow(): Promise<Element>
+  /**
+   * (async) Get the currently focused application.
+   *
+   * @returns {Promise<Element>} The current application element.
+   */
+  getCurrentApplication(): Promise<Element>
+  /**
+   * Get the currently focused element.
+   *
+   * @returns {Element} The focused element.
+   */
+  focusedElement(): Element
+  /**
+   * Open a URL in a browser.
+   *
+   * @param {string} url - The URL to open.
+   * @param {string} [browser] - The browser to use. Can be "Default", "Chrome", "Firefox", "Edge", "Brave", "Opera", "Vivaldi", or a custom browser path.
+   */
+  openUrl(url: string, browser?: string | undefined | null): Element
+  /**
+   * Open a file with its default application.
+   *
+   * @param {string} filePath - Path to the file to open.
+   */
+  openFile(filePath: string): void
+  /**
+   * Activate a browser window by title.
+   *
+   * @param {string} title - The window title to match.
+   */
+  activateBrowserWindowByTitle(title: string): void
+  /**
+   * Get the UI tree for a window identified by process ID and optional title.
+   *
+   * @param {number} pid - Process ID of the target application.
+   * @param {string} [title] - Optional window title filter.
+   * @param {TreeBuildConfig} [config] - Optional configuration for tree building.
+   * @returns {UINode} Complete UI tree starting from the identified window.
+   */
+  getWindowTree(pid: number, title?: string | undefined | null, config?: TreeBuildConfig | undefined | null): UINode
+  /**
+   * (async) List all available monitors/displays.
+   *
+   * @returns {Promise<Array<Monitor>>} List of monitor information.
+   */
+  listMonitors(): Promise<Array<Monitor>>
+  /**
+   * (async) Get the primary monitor.
+   *
+   * @returns {Promise<Monitor>} Primary monitor information.
+   */
+  getPrimaryMonitor(): Promise<Monitor>
+  /**
+   * (async) Get the monitor containing the currently focused window.
+   *
+   * @returns {Promise<Monitor>} Active monitor information.
+   */
+  getActiveMonitor(): Promise<Monitor>
+  /**
+   * (async) Get a monitor by its ID.
+   *
+   * @param {string} id - The monitor ID to find.
+   * @returns {Promise<Monitor>} Monitor information.
+   */
+  getMonitorById(id: string): Promise<Monitor>
+  /**
+   * (async) Get a monitor by its name.
+   *
+   * @param {string} name - The monitor name to find.
+   * @returns {Promise<Monitor>} Monitor information.
+   */
+  getMonitorByName(name: string): Promise<Monitor>
+  /**
+   * (async) Capture a screenshot of a specific monitor.
+   *
+   * @param {Monitor} monitor - The monitor to capture.
+   * @returns {Promise<ScreenshotResult>} The screenshot data.
+   */
+  captureMonitor(monitor: Monitor): Promise<ScreenshotResult>
+  /**
+   * (async) Capture screenshots of all monitors.
+   *
+   * @returns {Promise<Array<{monitor: Monitor, screenshot: ScreenshotResult}>>} Array of monitor and screenshot pairs.
+   */
+  captureAllMonitors(): Promise<Array<MonitorScreenshotPair>>
+  /**
+   * (async) Get all window elements for a given application name.
+   *
+   * @param {string} name - The name of the application whose windows will be retrieved.
+   * @returns {Promise<Array<Element>>} A list of window elements belonging to the application.
+   */
+  windowsForApplication(name: string): Promise<Array<Element>>
+  /**
+   * (async) Get the UI tree for all open applications in parallel.
+   *
+   * @returns {Promise<Array<UINode>>} List of UI trees for all applications.
+   */
+  getAllApplicationsTree(): Promise<Array<UINode>>
+  /**
+   * (async) Press a key globally.
+   *
+   * @param {string} key - The key to press (e.g., "Enter", "Ctrl+C", "F1").
+   */
+  pressKey(key: string): Promise<void>
+  /**
+   * (async) Execute JavaScript in the currently focused browser tab.
+   * Automatically finds the active browser window and executes the script.
+   *
+   * @param {string} script - The JavaScript code to execute in browser context.
+   * @returns {Promise<string>} The result of script execution.
+   */
+  executeBrowserScript(script: string): Promise<string>
+  /**
+   * (async) Delay execution for a specified number of milliseconds.
+   * Useful for waiting between actions to ensure UI stability.
+   *
+   * @param {number} delayMs - Delay in milliseconds.
+   * @returns {Promise<void>}
+   */
+  delay(delayMs: number): Promise<void>
+  /**
+   * Navigate to a URL in a browser.
+   * This is the recommended method for browser navigation - more reliable than
+   * manually manipulating the address bar with keyboard/mouse actions.
+   *
+   * @param {string} url - URL to navigate to
+   * @param {string | null} browser - Optional browser name ('Chrome', 'Firefox', 'Edge', 'Brave', 'Opera', 'Vivaldi', or 'Default')
+   * @returns {Promise<Element>} The browser window element
+   */
+  navigateBrowser(url: string, browser?: string | undefined | null): Element
+  /**
+   * (async) Set the zoom level to a specific percentage.
+   *
+   * @param {number} percentage - The zoom percentage (e.g., 100 for 100%, 150 for 150%, 50 for 50%).
+   */
+  setZoom(percentage: number): Promise<void>
+}
+/** A UI element in the accessibility tree. */
+export declare class Element {
+  /**
+   * Get the element's ID.
+   *
+   * @returns {string | null} The element's ID, if available.
+   */
+  id(): string | null
+  /**
+   * Get the element's role.
+   *
+   * @returns {string} The element's role (e.g., "button", "textfield").
+   */
+  role(): string
+  /**
+   * Get all attributes of the element.
+   *
+   * @returns {UIElementAttributes} The element's attributes.
+   */
+  attributes(): UIElementAttributes
+  /**
+   * Get the element's name.
+   *
+   * @returns {string | null} The element's name, if available.
+   */
+  name(): string | null
+  /**
+   * Get children of this element.
+   *
+   * @returns {Array<Element>} List of child elements.
+   */
+  children(): Array<Element>
+  /**
+   * Get the parent element.
+   *
+   * @returns {Element | null} The parent element, if available.
+   */
+  parent(): Element | null
+  /**
+   * Get element bounds.
+   *
+   * @returns {Bounds} The element's bounds (x, y, width, height).
+   */
+  bounds(): Bounds
+  /**
+   * Click on this element.
+   *
+   * @returns {ClickResult} Result of the click operation.
+   */
+  click(): ClickResult
+  /**
+   * Double click on this element.
+   *
+   * @returns {ClickResult} Result of the click operation.
+   */
+  doubleClick(): ClickResult
+  /** Right click on this element. */
+  rightClick(): void
+  /** Hover over this element. */
+  hover(): void
+  /**
+   * Check if element is visible.
+   *
+   * @returns {boolean} True if the element is visible.
+   */
+  isVisible(): boolean
+  /**
+   * Check if element is enabled.
+   *
+   * @returns {boolean} True if the element is enabled.
+   */
+  isEnabled(): boolean
+  /** Focus this element. */
+  focus(): void
+  /**
+   * Get text content of this element.
+   *
+   * @param {number} [maxDepth] - Maximum depth to search for text.
+   * @returns {string} The element's text content.
+   */
+  text(maxDepth?: number | undefined | null): string
+  /**
+   * Type text into this element.
+   *
+   * @param {string} text - The text to type.
+   * @param {boolean} [useClipboard] - Whether to use clipboard for pasting.
+   */
+  typeText(text: string, useClipboard?: boolean | undefined | null): void
+  /**
+   * Press a key while this element is focused.
+   *
+   * @param {string} key - The key to press.
+   */
+  pressKey(key: string): void
+  /**
+   * Set value of this element.
+   *
+   * @param {string} value - The value to set.
+   */
+  setValue(value: string): void
+  /**
+   * Perform a named action on this element.
+   *
+   * @param {string} action - The action to perform.
+   */
+  performAction(action: string): void
+  /**
+   * Invoke this element (triggers the default action).
+   * This is often more reliable than clicking for controls like radio buttons or menu items.
+   */
+  invoke(): void
+  /**
+   * Scroll the element in a given direction.
+   *
+   * @param {string} direction - The direction to scroll.
+   * @param {number} amount - The amount to scroll.
+   */
+  scroll(direction: string, amount: number): void
+  /** Activate the window containing this element. */
+  activateWindow(): void
+  /** Minimize the window containing this element. */
+  minimizeWindow(): void
+  /** Maximize the window containing this element. */
+  maximizeWindow(): void
+  /**
+   * Check if element is focused.
+   *
+   * @returns {boolean} True if the element is focused.
+   */
+  isFocused(): boolean
+  /**
+   * Check if element is keyboard focusable.
+   *
+   * @returns {boolean} True if the element can receive keyboard focus.
+   */
+  isKeyboardFocusable(): boolean
+  /**
+   * Drag mouse from start to end coordinates.
+   *
+   * @param {number} startX - Starting X coordinate.
+   * @param {number} startY - Starting Y coordinate.
+   * @param {number} endX - Ending X coordinate.
+   * @param {number} endY - Ending Y coordinate.
+   */
+  mouseDrag(startX: number, startY: number, endX: number, endY: number): void
+  /**
+   * Press and hold mouse at coordinates.
+   *
+   * @param {number} x - X coordinate.
+   * @param {number} y - Y coordinate.
+   */
+  mouseClickAndHold(x: number, y: number): void
+  /**
+   * Move mouse to coordinates.
+   *
+   * @param {number} x - X coordinate.
+   * @param {number} y - Y coordinate.
+   */
+  mouseMove(x: number, y: number): void
+  /** Release mouse button. */
+  mouseRelease(): void
+  /**
+   * Create a locator from this element.
+   * Accepts either a selector string or a Selector object.
+   *
+   * @param {string | Selector} selector - The selector.
+   * @returns {Locator} A new locator for finding elements.
+   */
+  locator(selector: string | Selector): Locator
+  /**
+   * Get the containing application element.
+   *
+   * @returns {Element | null} The containing application element, if available.
+   */
+  application(): Element | null
+  /**
+   * Get the containing window element.
+   *
+   * @returns {Element | null} The containing window element, if available.
+   */
+  window(): Element | null
+  /**
+   * Highlights the element with a colored border and optional text overlay.
+   *
+   * @param {number} [color] - Optional BGR color code (32-bit integer). Default: 0x0000FF (red)
+   * @param {number} [durationMs] - Optional duration in milliseconds.
+   * @param {string} [text] - Optional text to display. Text will be truncated to 10 characters.
+   * @param {TextPosition} [textPosition] - Optional position for the text overlay (default: Top)
+   * @param {FontStyle} [fontStyle] - Optional font styling for the text
+   * @returns {HighlightHandle} Handle that can be used to close the highlight early
+   */
+  highlight(color?: number | undefined | null, durationMs?: number | undefined | null, text?: string | undefined | null, textPosition?: TextPosition | undefined | null, fontStyle?: FontStyle | undefined | null): HighlightHandle
+  /**
+   * Capture a screenshot of this element.
+   *
+   * @returns {ScreenshotResult} The screenshot data containing image data and dimensions.
+   */
+  capture(): ScreenshotResult
+  /**
+   * Get the process ID of the application containing this element.
+   *
+   * @returns {number} The process ID.
+   */
+  processId(): number
+  toString(): string
+  /**
+   * Sets the transparency of the window.
+   *
+   * @param {number} percentage - The transparency percentage from 0 (completely transparent) to 100 (completely opaque).
+   * @returns {void}
+   */
+  setTransparency(percentage: number): void
+  /**
+   * Close the element if it's closable (like windows, applications).
+   * Does nothing for non-closable elements (like buttons, text, etc.).
+   *
+   * @returns {void}
+   */
+  close(): void
+  /**
+   * Get the monitor containing this element.
+   *
+   * @returns {Monitor} The monitor information for the display containing this element.
+   */
+  monitor(): Monitor
+  /**
+   * Scrolls the element into view within its window viewport.
+   * If the element is already visible, returns immediately.
+   *
+   * @returns {void}
+   */
+  scrollIntoView(): void
+  /**
+   * Selects an option in a dropdown or combobox by its visible text.
+   *
+   * @param {string} optionName - The visible text of the option to select.
+   * @returns {void}
+   */
+  selectOption(optionName: string): void
+  /**
+   * Lists all available option strings from a dropdown or list box.
+   *
+   * @returns {Array<string>} List of available option strings.
+   */
+  listOptions(): Array<string>
+  /**
+   * Checks if a control (like a checkbox or toggle switch) is currently toggled on.
+   *
+   * @returns {boolean} True if the control is toggled on.
+   */
+  isToggled(): boolean
+  /**
+   * Sets the state of a toggleable control.
+   * It only performs an action if the control is not already in the desired state.
+   *
+   * @param {boolean} state - The desired toggle state.
+   * @returns {void}
+   */
+  setToggled(state: boolean): void
+  /**
+   * Checks if an element is selected (e.g., list item, tree node, tab).
+   *
+   * @returns {boolean} True if the element is selected, false otherwise.
+   */
+  isSelected(): boolean
+  /**
+   * Sets the selection state of a selectable item.
+   * Only performs an action if the element is not already in the desired state.
+   *
+   * @param {boolean} state - The desired selection state.
+   * @returns {void}
+   */
+  setSelected(state: boolean): void
+  /**
+   * Gets the current value from a range-based control like a slider or progress bar.
+   *
+   * @returns {number} The current value of the range control.
+   */
+  getRangeValue(): number
+  /**
+   * Sets the value of a range-based control like a slider.
+   *
+   * @param {number} value - The value to set.
+   * @returns {void}
+   */
+  setRangeValue(value: number): void
+  /**
+   * Gets the value attribute of an element (text inputs, combo boxes, etc.).
+   *
+   * @returns {string | null} The value attribute, or null if not available.
+   */
+  getValue(): string | null
+  /**
+   * Execute JavaScript in web browser using dev tools console.
+   * Returns the result of the script execution as a string.
+   *
+   * @param {string} script - The JavaScript code to execute.
+   * @returns {Promise<string>} The result of script execution.
+   */
+  executeBrowserScript(script: string): Promise<string>
+  /**
+   * Get the UI tree starting from this element.
+   * Returns a tree structure containing this element and all its descendants.
+   *
+   * @param {number} [maxDepth=100] - Maximum depth to traverse (default: 100).
+   * @returns {UINode} Tree structure with recursive children.
+   */
+  getTree(maxDepth?: number | undefined | null): UINode
+}
+/** Locator for finding UI elements by selector. */
+export declare class Locator {
+  /**
+   * (async) Get the first matching element.
+   *
+   * @param {number} timeoutMs - Timeout in milliseconds (required).
+   * @returns {Promise<Element>} The first matching element.
+   */
+  first(timeoutMs: number): Promise<Element>
+  /**
+   * (async) Get all matching elements.
+   *
+   * @param {number} timeoutMs - Timeout in milliseconds (required).
+   * @param {number} [depth] - Maximum depth to search.
+   * @returns {Promise<Array<Element>>} List of matching elements.
+   */
+  all(timeoutMs: number, depth?: number | undefined | null): Promise<Array<Element>>
+  /**
+   * Set a default timeout for this locator.
+   *
+   * @param {number} timeoutMs - Timeout in milliseconds.
+   * @returns {Locator} A new locator with the specified timeout.
+   */
+  timeout(timeoutMs: number): Locator
+  /**
+   * Set the root element for this locator.
+   *
+   * @param {Element} element - The root element.
+   * @returns {Locator} A new locator with the specified root element.
+   */
+  within(element: Element): Locator
+  /**
+   * Chain another selector.
+   * Accepts either a selector string or a Selector object.
+   *
+   * @param {string | Selector} selector - The selector.
+   * @returns {Locator} A new locator with the chained selector.
+   */
+  locator(selector: string | Selector): Locator
+  /**
+   * (async) Validate element existence without throwing an error.
+   *
+   * @param {number} timeoutMs - Timeout in milliseconds (required).
+   * @returns {Promise<ValidationResult>} Validation result with exists flag and optional element.
+   */
+  validate(timeoutMs: number): Promise<ValidationResult>
+  /**
+   * (async) Wait for an element to meet a specific condition.
+   *
+   * @param {string} condition - Condition to wait for: 'exists', 'visible', 'enabled', 'focused'
+   * @param {number} timeoutMs - Timeout in milliseconds (required).
+   * @returns {Promise<Element>} The element when condition is met.
+   */
+  waitFor(condition: string, timeoutMs: number): Promise<Element>
+}
+/** Selector for locating UI elements. Provides a typed alternative to the string based selector API. */
+export declare class Selector {
+  /** Create a selector that matches elements by their accessibility `name`. */
+  static name(name: string): Selector
+  /** Create a selector that matches elements by role (and optionally name). */
+  static role(role: string, name?: string | undefined | null): Selector
+  /** Create a selector that matches elements by accessibility `id`. */
+  static id(id: string): Selector
+  /** Create a selector that matches elements by the text they display. */
+  static text(text: string): Selector
+  /** Create a selector from an XPath-like path string. */
+  static path(path: string): Selector
+  /** Create a selector that matches elements by a native automation id (e.g., AutomationID on Windows). */
+  static nativeId(id: string): Selector
+  /** Create a selector that matches elements by their class name. */
+  static className(name: string): Selector
+  /** Create a selector from an arbitrary attribute map. */
+  static attributes(attributes: Record<string, string>): Selector
+  /** Chain another selector onto this selector. */
+  chain(other: Selector): Selector
+  /** Filter by visibility. */
+  visible(isVisible: boolean): Selector
+  /**
+   * Create a selector that selects the nth element from matches.
+   * Positive values are 0-based from the start (0 = first, 1 = second).
+   * Negative values are from the end (-1 = last, -2 = second-to-last).
+   */
+  static nth(index: number): Selector
+  /**
+   * Create a selector that matches elements having at least one descendant matching the inner selector.
+   * This is similar to Playwright's :has() pseudo-class.
+   */
+  static has(innerSelector: Selector): Selector
+  /**
+   * Create a selector that navigates to the parent element.
+   * This is similar to Playwright's .. syntax.
+   */
+  static parent(): Selector
+}
+export declare class HighlightHandle {
+  close(): void
+}