#Universal Automation Protocol (UAP)

/**
 * Types for AI actions (specs only)
 * Adapt best practices from Playwright and Puppeteer for AI era
 */

// Common base for all AI actions
export interface CommonAIAction {
	/**
	 * The command to execute (e.g. 'tap', 'wait', 'open_link', etc)
	 */
	command: string
	/**
	 * Optional message to display to the user
	 */
	displayMsg?: string
	/**
	 * If true, do not wait for this action to finish before proceeding to the next task (AI era best practice)
	 * Defaults to false
	 */
	noWait?: boolean
	/**
	 * Wait strategy
	 */
	waitUntil?:
		| 'domcontentloaded'
		| 'load'
		| 'networkidle'
		| 'visible'
		| 'hidden'
}

export interface AIGoalAction extends CommonAIAction {
	command: 'goal'
	goal: string // natural language goal
}

export interface AITapAction extends CommonAIAction {
	command: 'tap'
	selector: string
}

export interface AIHoverAction extends CommonAIAction {
	command: 'hover'
	selector: string
}

export interface AIDragAction extends CommonAIAction {
	command: 'drag'
	sourceSelector: string
	targetSelector: string
}

export interface AITypeAction extends CommonAIAction {
	command: 'type'
	selector: string
	text: string
}

export interface AIKeyboardPressAction extends CommonAIAction {
	command: 'keyboard_press'
	keys: string[]
}

export interface AIScrollAction extends CommonAIAction {
	command: 'scroll'
	selector?: string
	direction: 'up' | 'down' | 'left' | 'right'
	amount?: number // pixels or percent
}

export interface AIScrollToAction extends CommonAIAction {
	command: 'scroll_to'
	selector?: string
	edge: 'top' | 'bottom' | 'left' | 'right'
}

export interface AIWaitAction extends CommonAIAction {
	command: 'wait'
	duration: number // milliseconds
}

export interface AIOpenLinkAction extends CommonAIAction {
	command: 'open_link'
	url: string
}

export interface AIZoomAction extends CommonAIAction {
	command: 'zoom'
	zoomLevel: number // e.g. 1.0 = 100%, 2.0 = 200%
	selector?: string // optional, for zooming a specific element
}

export interface AIMultitouchAction extends CommonAIAction {
	command: 'multitouch'
	events: Array<{
		type: 'pinch' | 'spread' | 'rotate' | 'swipe'
		start: { x: number; y: number }
		end: { x: number; y: number }
		fingers?: number // default 2
		angle?: number // for rotate
		amount?: number // for pinch/spread (pixels or percent)
	}>
	selector?: string // optional, for targeting a specific element
}

export interface AIGestureAction extends CommonAIAction {
	command: 'gesture'
	gestureType:
		| 'swipe'
		| 'flick'
		| 'longpress'
		| 'doubletap'
		| 'press'
		| 'pan'
		| 'rotate' // exclude 'pinch' and 'zoom' to avoid overlap
	start: { x: number; y: number }
	end?: { x: number; y: number }
	duration?: number // ms, for longpress or press
	fingers?: number // default 1
	angle?: number // for rotate
	selector?: string // optional, for targeting a specific element
}

export interface AIGoToTabAction extends CommonAIAction {
	command: 'go_to_tab'
	description: string
}

/**
 * AISetValueAction: Set the value of an input or element.
 */
export interface AISetValueAction extends CommonAIAction {
  command: 'set_value'
  selector: string
  value: string | number | boolean
}

/**
 * AIAssertAction: Assert a condition on the UI or data.
 */
export interface AIAssertAction extends CommonAIAction {
  command: 'assert'
  assertion:
	| { type: 'visible'; selector: string }
	| { type: 'not_visible'; selector: string }
	| { type: 'text_equals'; selector: string; value: string }
	| { type: 'value_equals'; selector: string; value: string | number | boolean }
}

/**
 * AIActionType: Accepts any of the known action types, or a custom command with arbitrary params.
 * This enables extension with custom commands and parameters.
 */
export type AIActionType =
	// stochastic (random) actions
	| AIGoalAction
	// deterministic actions
	| AITapAction
	| AIWaitAction
	| AIHoverAction
	| AIDragAction
	| AITypeAction
	| AIKeyboardPressAction
	| AIScrollAction
	| AIScrollToAction
	| AIOpenLinkAction
	| AIZoomAction
	| AIMultitouchAction
	| AIGestureAction
	| AIGoToTabAction
	| CustomAIAction
	| AISetValueAction
	| AIAssertAction

/**
 * CustomAIAction: Allows any string as command and arbitrary params.
 */
export interface CustomAIAction extends CommonAIAction {
	command: string // any string
	[name: string]: any // allow arbitrary params
}