Skip to main content

eoka_protocol/
args.rs

1use serde::{Deserialize, Serialize};
2
3#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
4pub struct OpenArgs {
5    #[serde(flatten)]
6    pub operation: crate::ActionSettings,
7    pub url: String,
8    pub headers: Option<serde_json::Value>,
9    pub user_agent: Option<String>,
10    #[serde(default)]
11    pub bypass_csp: bool,
12    pub inject_js: Option<String>,
13    pub load_state: Option<String>,
14}
15
16#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
17pub struct SnapshotArgs {
18    #[serde(default)]
19    pub interactive: bool,
20    #[serde(default)]
21    pub all: bool,
22}
23
24#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
25pub struct ObserveArgs {
26    #[schemars(
27        description = "Filter: 'inputs' for form elements, 'buttons' for buttons and links, or 'all' for all observed elements."
28    )]
29    pub filter: Option<String>,
30    #[schemars(description = "Maximum elements to return.")]
31    pub max: Option<usize>,
32    #[serde(default)]
33    pub structured: bool,
34}
35
36#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
37pub struct ScreenshotArgs {
38    pub output: Option<String>,
39    #[serde(default)]
40    pub annotate: bool,
41    #[serde(default)]
42    #[schemars(description = "Image format; PNG when omitted.")]
43    pub format: Option<crate::sidecar::ScreenshotFormat>,
44    #[serde(default)]
45    #[schemars(range(max = 100), description = "JPEG or WebP quality, 0 to 100.")]
46    pub quality: Option<u8>,
47    #[serde(default)]
48    #[schemars(description = "Document-relative CSS pixel region; conflicts with full_page.")]
49    pub clip: Option<crate::sidecar::ScreenshotClip>,
50    #[serde(default)]
51    #[schemars(description = "Capture the whole scrollable page instead of the viewport.")]
52    pub full_page: bool,
53}
54
55#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
56pub struct RecordingStartArgs {
57    #[schemars(description = "Absolute path of the MP4 file to write.")]
58    pub path: String,
59    #[serde(default)]
60    #[schemars(description = "UUID naming this recording; generated when omitted.")]
61    pub recording_id: Option<String>,
62    #[serde(default)]
63    pub max_width: Option<u32>,
64    #[serde(default)]
65    pub max_height: Option<u32>,
66    #[serde(default)]
67    #[schemars(range(min = 1, max = 120))]
68    pub fps: Option<u32>,
69}
70
71#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
72pub struct RecordingIdArgs {
73    #[schemars(description = "Recording UUID returned by recording_start.")]
74    pub recording_id: String,
75}
76
77#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
78pub struct EmulateArgs {
79    #[serde(default = "default_viewport_width")]
80    pub width: u32,
81    #[serde(default = "default_viewport_height")]
82    pub height: u32,
83    #[serde(default = "default_device_pixel_ratio")]
84    pub dpr: f64,
85    #[serde(default)]
86    pub desktop: bool,
87    #[serde(default)]
88    pub reset: bool,
89}
90
91impl Default for EmulateArgs {
92    fn default() -> Self {
93        Self {
94            width: default_viewport_width(),
95            height: default_viewport_height(),
96            dpr: default_device_pixel_ratio(),
97            desktop: false,
98            reset: false,
99        }
100    }
101}
102
103#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
104pub struct TextArgs {
105    #[schemars(description = "Text substring to search for, matched case-insensitively.")]
106    pub text: String,
107}
108
109#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
110pub struct TargetArgs {
111    #[serde(flatten)]
112    pub operation: crate::ActionSettings,
113    #[schemars(
114        description = "Target element. Supports scoped refs from view, text:Submit, placeholder:Email, role:button, css:form button, id:my-btn, or plain text search."
115    )]
116    pub target: String,
117}
118
119#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
120pub struct FillArgs {
121    #[serde(flatten)]
122    pub operation: crate::ActionSettings,
123    #[schemars(
124        description = "Target input. Supports scoped refs from view, text:Email, placeholder:Enter code, css:input.search, id:email-field, or plain text search."
125    )]
126    pub target: String,
127    #[schemars(description = "Text to type into the element.")]
128    pub text: String,
129    #[serde(default)]
130    pub input_mode: crate::InputMode,
131}
132
133#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
134pub struct SelectArgs {
135    #[serde(flatten)]
136    pub operation: crate::ActionSettings,
137    #[schemars(
138        description = "Target select element by scoped reference, text, CSS selector, id, or role."
139    )]
140    pub target: String,
141    #[schemars(description = "Option value or visible text to select.")]
142    pub value: String,
143}
144
145#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
146pub struct KeyArgs {
147    #[serde(flatten)]
148    pub operation: crate::ActionSettings,
149    #[schemars(
150        description = "Key to press, for example Enter, Tab, Escape, ArrowDown, or Backspace."
151    )]
152    pub key: String,
153}
154
155#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
156pub struct HeldKeyArgs {
157    #[schemars(description = "Key to hold or release, for example Shift, Control, or a.")]
158    pub key: String,
159}
160
161#[derive(Debug, Clone, Copy, Serialize, Deserialize, schemars::JsonSchema)]
162#[serde(rename_all = "lowercase")]
163pub enum MouseButton {
164    Left,
165    Middle,
166    Right,
167    Back,
168    Forward,
169}
170
171#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
172pub struct MouseButtonArgs {
173    #[schemars(description = "Viewport horizontal coordinate in CSS pixels.")]
174    pub x: f64,
175    #[schemars(description = "Viewport vertical coordinate in CSS pixels.")]
176    pub y: f64,
177    #[schemars(description = "Mouse button to hold or release.")]
178    pub button: MouseButton,
179}
180
181#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
182pub struct MouseMoveArgs {
183    #[schemars(description = "Viewport horizontal coordinate in CSS pixels.")]
184    pub x: f64,
185    #[schemars(description = "Viewport vertical coordinate in CSS pixels.")]
186    pub y: f64,
187}
188
189#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
190pub struct ScriptArgs {
191    #[serde(default)]
192    pub arguments: Vec<serde_json::Value>,
193    #[serde(default)]
194    pub raw: bool,
195    pub code: Option<String>,
196    pub file: Option<String>,
197    pub max_size: Option<usize>,
198    #[serde(default)]
199    pub no_await: bool,
200}
201
202#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
203pub struct FrameEvalArgs {
204    #[schemars(
205        description = "CSS selector matching exactly one iframe/frame in the top document, or id:<frame-id> from frames for explicit/nested selection. Bare URLs and indices are not supported. Evaluation uses an isolated world, not page-owned JavaScript globals."
206    )]
207    pub frame: String,
208    pub code: Option<String>,
209    pub file: Option<String>,
210}
211
212#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
213pub struct FetchArgs {
214    pub url: String,
215    pub method: Option<String>,
216    pub headers: Option<serde_json::Value>,
217    pub body: Option<String>,
218    pub redirect: Option<String>,
219    #[serde(default)]
220    pub body_only: bool,
221    #[schemars(
222        description = "Raw text byte limit: default 8192, maximum 16777216; zero inspects headers only.",
223        range(max = 16777216)
224    )]
225    pub max_body: Option<usize>,
226}
227
228#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
229pub struct SetCookieArgs {
230    pub name: String,
231    pub value: String,
232    pub domain: Option<String>,
233    pub path: Option<String>,
234}
235
236#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
237pub struct DeleteCookieArgs {
238    pub name: String,
239    pub domain: Option<String>,
240}
241
242#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
243pub struct StorageArgs {
244    pub key: Option<String>,
245    #[serde(default)]
246    pub session_storage: bool,
247}
248
249#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
250pub struct SetStorageArgs {
251    pub key: String,
252    pub value: String,
253    #[serde(default)]
254    pub session_storage: bool,
255}
256
257#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
258pub struct PathArgs {
259    #[schemars(description = "File path.")]
260    pub path: String,
261}
262
263#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
264pub struct LoadStateArgs {
265    pub path: String,
266    #[serde(default)]
267    pub no_navigate: bool,
268}
269
270#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
271pub struct HeadersArgs {
272    pub headers_json: String,
273}
274
275#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
276pub struct ConsoleArgs {
277    #[serde(default)]
278    pub clear: bool,
279    pub level: Option<String>,
280}
281
282#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
283pub struct ClearFlagArgs {
284    #[serde(default)]
285    pub clear: bool,
286}
287
288#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
289pub struct TabNewArgs {
290    #[schemars(description = "Optional URL to navigate to. If omitted, opens a blank tab.")]
291    pub url: Option<String>,
292}
293
294#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
295pub struct TabIdArgs {
296    #[schemars(description = "Tab ID from list_tabs.")]
297    pub tab_id: String,
298}
299
300#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
301pub struct CloneFromArgs {
302    pub source: String,
303    pub to: Option<String>,
304}
305
306#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
307pub struct WaitArgs {
308    #[serde(default)]
309    pub expect: Option<crate::Expectation>,
310    pub ms: Option<u64>,
311    pub text: Option<String>,
312    pub url: Option<String>,
313    pub load: Option<String>,
314    #[serde(default)]
315    #[schemars(description = "CSS selector to wait for; see `state`.")]
316    pub selector: Option<String>,
317    #[serde(default)]
318    #[schemars(description = "What the selector must become. Defaults to visible.")]
319    pub state: Option<WaitSelectorState>,
320    pub timeout: Option<u64>,
321}
322
323#[derive(
324    Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default, schemars::JsonSchema,
325)]
326#[serde(rename_all = "lowercase")]
327#[schemars(description = "The condition a `wait` selector must reach.")]
328pub enum WaitSelectorState {
329    #[schemars(description = "Present in the DOM, rendered or not.")]
330    Attached,
331    #[schemars(description = "Rendered with visible CSS and a nonzero box.")]
332    #[default]
333    Visible,
334    #[schemars(description = "Absent or no longer rendered.")]
335    Hidden,
336}
337
338#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
339pub struct DialogAcceptArgs {
340    #[serde(default)]
341    #[schemars(
342        description = "Text to enter for a prompt() dialog; ignored for alert and confirm."
343    )]
344    pub prompt_text: Option<String>,
345}
346
347#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
348pub struct SelectorArgs {
349    #[schemars(description = "CSS selector of the element.")]
350    pub selector: String,
351}
352
353#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
354pub struct AttributeArgs {
355    #[schemars(description = "CSS selector of the element.")]
356    pub selector: String,
357    #[schemars(description = "Attribute name, for example href.")]
358    pub name: String,
359}
360
361#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
362pub struct ClickShadowArgs {
363    #[serde(deserialize_with = "shadow_selector")]
364    #[schemars(description = "CSS selector, matched through open and closed shadow roots.")]
365    pub selector: String,
366    #[serde(default)]
367    #[schemars(description = "Frame ID from `frames`; the top frame when omitted.")]
368    pub frame_id: Option<String>,
369    #[serde(
370        default = "default_click_shadow_timeout_ms",
371        deserialize_with = "shadow_timeout"
372    )]
373    pub timeout_ms: u64,
374}
375
376fn default_click_shadow_timeout_ms() -> u64 {
377    10_000
378}
379
380fn shadow_selector<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
381    let selector = String::deserialize(d)?;
382    if selector.trim().is_empty() || selector.len() > 4096 {
383        return Err(serde::de::Error::custom(
384            "selector must be 1..=4096 characters",
385        ));
386    }
387    Ok(selector)
388}
389
390fn shadow_timeout<'de, D: serde::Deserializer<'de>>(d: D) -> Result<u64, D::Error> {
391    let timeout = u64::deserialize(d)?;
392    if !(1..=60_000).contains(&timeout) {
393        return Err(serde::de::Error::custom(
394            "timeout_ms must be between 1 and 60000",
395        ));
396    }
397    Ok(timeout)
398}
399
400#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
401pub struct PathStringArgs {
402    #[schemars(description = "Target path, for example /docs or /about.")]
403    pub path: String,
404}
405
406#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
407pub struct FakeCameraArgs {
408    pub file: String,
409    #[serde(default)]
410    pub loop_video: bool,
411}
412
413#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
414pub struct WasmReadArgs {
415    pub addr: String,
416    pub len: usize,
417    pub memory: Option<String>,
418}
419
420#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
421pub struct WasmWriteArgs {
422    pub addr: String,
423    pub hex: String,
424    pub memory: Option<String>,
425}
426
427#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
428pub struct WasmFindArgs {
429    pub pattern: String,
430    pub start: Option<String>,
431    pub end: Option<String>,
432    #[serde(default = "default_wasm_find_max")]
433    pub max: usize,
434    pub memory: Option<String>,
435}
436
437impl Default for WasmFindArgs {
438    fn default() -> Self {
439        Self {
440            pattern: String::new(),
441            start: None,
442            end: None,
443            max: default_wasm_find_max(),
444            memory: None,
445        }
446    }
447}
448
449#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
450pub struct InterceptAddArgs {
451    pub url_pattern: String,
452    pub capture: Option<String>,
453    pub respond: Option<String>,
454    #[serde(default = "default_intercept_status")]
455    pub status: u16,
456}
457
458impl Default for InterceptAddArgs {
459    fn default() -> Self {
460        Self {
461            url_pattern: String::new(),
462            capture: None,
463            respond: None,
464            status: default_intercept_status(),
465        }
466    }
467}
468
469#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
470pub struct IdArgs {
471    pub id: String,
472}
473
474#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
475pub struct ModeArgs {
476    pub mode: String,
477}
478
479#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
480pub struct DomainArgs {
481    pub domain: String,
482}
483
484#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
485pub struct CaptchaInjectArgs {
486    pub token: String,
487    #[serde(default = "default_captcha_type")]
488    pub captcha_type: String,
489    pub callback: Option<String>,
490    pub click_after: Option<String>,
491}
492
493#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
494pub struct NetworkRecordStartArgs {
495    #[serde(default)]
496    pub patterns: Vec<String>,
497    #[serde(default)]
498    pub no_bodies: bool,
499    #[serde(default = "default_max_body_bytes")]
500    pub max_body_bytes: usize,
501    #[serde(default)]
502    pub clear: bool,
503}
504
505#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
506pub struct NetworkLogArgs {
507    pub limit: Option<usize>,
508    pub pattern: Option<String>,
509    pub method: Option<String>,
510    pub status: Option<u16>,
511    pub since: Option<u64>,
512    #[serde(default)]
513    pub compact: bool,
514}
515
516#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
517pub struct NetworkShowArgs {
518    pub id: u64,
519    #[serde(default)]
520    pub body: bool,
521    pub max_body: Option<usize>,
522}
523
524#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
525pub struct NetworkWaitArgs {
526    pub pattern: Option<String>,
527    pub method: Option<String>,
528    pub status: Option<u16>,
529    pub timeout: Option<u64>,
530    pub since: Option<u64>,
531    #[serde(default)]
532    pub include_existing: bool,
533}
534
535#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
536pub struct NetworkExportArgs {
537    pub path: String,
538    #[serde(default = "default_network_export_format")]
539    pub format: String,
540    pub settle_ms: Option<u64>,
541}
542
543impl Default for NetworkExportArgs {
544    fn default() -> Self {
545        Self {
546            path: String::new(),
547            format: default_network_export_format(),
548            settle_ms: None,
549        }
550    }
551}
552
553fn default_max_body_bytes() -> usize {
554    10 * 1024 * 1024
555}
556
557fn default_network_export_format() -> String {
558    "har".to_string()
559}
560
561fn default_viewport_width() -> u32 {
562    390
563}
564
565fn default_viewport_height() -> u32 {
566    844
567}
568
569fn default_device_pixel_ratio() -> f64 {
570    2.0
571}
572
573fn default_wasm_find_max() -> usize {
574    20
575}
576
577fn default_intercept_status() -> u16 {
578    200
579}
580
581fn default_captcha_type() -> String {
582    "auto".to_string()
583}