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, Copy, Serialize, Deserialize, schemars::JsonSchema)]
156#[serde(rename_all = "lowercase")]
157pub enum MouseButton {
158    Left,
159    Middle,
160    Right,
161    Back,
162    Forward,
163}
164
165#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
166pub struct MouseButtonArgs {
167    #[schemars(description = "Viewport horizontal coordinate in CSS pixels.")]
168    pub x: f64,
169    #[schemars(description = "Viewport vertical coordinate in CSS pixels.")]
170    pub y: f64,
171    #[schemars(description = "Mouse button to hold or release.")]
172    pub button: MouseButton,
173}
174
175#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
176pub struct MouseMoveArgs {
177    #[schemars(description = "Viewport horizontal coordinate in CSS pixels.")]
178    pub x: f64,
179    #[schemars(description = "Viewport vertical coordinate in CSS pixels.")]
180    pub y: f64,
181}
182
183#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
184pub struct ScriptArgs {
185    #[serde(default)]
186    pub arguments: Vec<serde_json::Value>,
187    #[serde(default)]
188    pub raw: bool,
189    pub code: Option<String>,
190    pub file: Option<String>,
191    pub max_size: Option<usize>,
192    #[serde(default)]
193    pub no_await: bool,
194}
195
196#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
197pub struct FrameEvalArgs {
198    #[schemars(
199        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."
200    )]
201    pub frame: String,
202    pub code: Option<String>,
203    pub file: Option<String>,
204}
205
206#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
207pub struct FetchArgs {
208    pub url: String,
209    pub method: Option<String>,
210    pub headers: Option<serde_json::Value>,
211    pub body: Option<String>,
212    pub redirect: Option<String>,
213    #[serde(default)]
214    pub body_only: bool,
215    #[schemars(
216        description = "Raw text byte limit: default 8192, maximum 16777216; zero inspects headers only.",
217        range(max = 16777216)
218    )]
219    pub max_body: Option<usize>,
220}
221
222#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
223pub struct SetCookieArgs {
224    pub name: String,
225    pub value: String,
226    pub domain: Option<String>,
227    pub path: Option<String>,
228}
229
230#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
231pub struct DeleteCookieArgs {
232    pub name: String,
233    pub domain: Option<String>,
234}
235
236#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
237pub struct StorageArgs {
238    pub key: Option<String>,
239    #[serde(default)]
240    pub session_storage: bool,
241}
242
243#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
244pub struct SetStorageArgs {
245    pub key: String,
246    pub value: String,
247    #[serde(default)]
248    pub session_storage: bool,
249}
250
251#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
252pub struct PathArgs {
253    #[schemars(description = "File path.")]
254    pub path: String,
255}
256
257#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
258pub struct LoadStateArgs {
259    pub path: String,
260    #[serde(default)]
261    pub no_navigate: bool,
262}
263
264#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
265pub struct HeadersArgs {
266    pub headers_json: String,
267}
268
269#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
270pub struct ConsoleArgs {
271    #[serde(default)]
272    pub clear: bool,
273    pub level: Option<String>,
274}
275
276#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
277pub struct ClearFlagArgs {
278    #[serde(default)]
279    pub clear: bool,
280}
281
282#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
283pub struct TabNewArgs {
284    #[schemars(description = "Optional URL to navigate to. If omitted, opens a blank tab.")]
285    pub url: Option<String>,
286}
287
288#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
289pub struct TabIdArgs {
290    #[schemars(description = "Tab ID from list_tabs.")]
291    pub tab_id: String,
292}
293
294#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
295pub struct CloneFromArgs {
296    pub source: String,
297    pub to: Option<String>,
298}
299
300#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
301pub struct WaitArgs {
302    #[serde(default)]
303    pub expect: Option<crate::Expectation>,
304    pub ms: Option<u64>,
305    pub text: Option<String>,
306    pub url: Option<String>,
307    pub load: Option<String>,
308    #[serde(default)]
309    #[schemars(description = "CSS selector to wait for; see `state`.")]
310    pub selector: Option<String>,
311    #[serde(default)]
312    #[schemars(description = "What the selector must become. Defaults to visible.")]
313    pub state: Option<WaitSelectorState>,
314    pub timeout: Option<u64>,
315}
316
317#[derive(
318    Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default, schemars::JsonSchema,
319)]
320#[serde(rename_all = "lowercase")]
321#[schemars(description = "The condition a `wait` selector must reach.")]
322pub enum WaitSelectorState {
323    #[schemars(description = "Present in the DOM, rendered or not.")]
324    Attached,
325    #[schemars(description = "Rendered with visible CSS and a nonzero box.")]
326    #[default]
327    Visible,
328    #[schemars(description = "Absent or no longer rendered.")]
329    Hidden,
330}
331
332#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
333pub struct DialogAcceptArgs {
334    #[serde(default)]
335    #[schemars(
336        description = "Text to enter for a prompt() dialog; ignored for alert and confirm."
337    )]
338    pub prompt_text: Option<String>,
339}
340
341#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
342pub struct SelectorArgs {
343    #[schemars(description = "CSS selector of the element.")]
344    pub selector: String,
345}
346
347#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
348pub struct AttributeArgs {
349    #[schemars(description = "CSS selector of the element.")]
350    pub selector: String,
351    #[schemars(description = "Attribute name, for example href.")]
352    pub name: String,
353}
354
355#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
356pub struct ClickShadowArgs {
357    #[serde(deserialize_with = "shadow_selector")]
358    #[schemars(description = "CSS selector, matched through open and closed shadow roots.")]
359    pub selector: String,
360    #[serde(default)]
361    #[schemars(description = "Frame ID from `frames`; the top frame when omitted.")]
362    pub frame_id: Option<String>,
363    #[serde(
364        default = "default_click_shadow_timeout_ms",
365        deserialize_with = "shadow_timeout"
366    )]
367    pub timeout_ms: u64,
368}
369
370fn default_click_shadow_timeout_ms() -> u64 {
371    10_000
372}
373
374fn shadow_selector<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
375    let selector = String::deserialize(d)?;
376    if selector.trim().is_empty() || selector.len() > 4096 {
377        return Err(serde::de::Error::custom(
378            "selector must be 1..=4096 characters",
379        ));
380    }
381    Ok(selector)
382}
383
384fn shadow_timeout<'de, D: serde::Deserializer<'de>>(d: D) -> Result<u64, D::Error> {
385    let timeout = u64::deserialize(d)?;
386    if !(1..=60_000).contains(&timeout) {
387        return Err(serde::de::Error::custom(
388            "timeout_ms must be between 1 and 60000",
389        ));
390    }
391    Ok(timeout)
392}
393
394#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
395pub struct PathStringArgs {
396    #[schemars(description = "Target path, for example /docs or /about.")]
397    pub path: String,
398}
399
400#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
401pub struct FakeCameraArgs {
402    pub file: String,
403    #[serde(default)]
404    pub loop_video: bool,
405}
406
407#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
408pub struct WasmReadArgs {
409    pub addr: String,
410    pub len: usize,
411    pub memory: Option<String>,
412}
413
414#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
415pub struct WasmWriteArgs {
416    pub addr: String,
417    pub hex: String,
418    pub memory: Option<String>,
419}
420
421#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
422pub struct WasmFindArgs {
423    pub pattern: String,
424    pub start: Option<String>,
425    pub end: Option<String>,
426    #[serde(default = "default_wasm_find_max")]
427    pub max: usize,
428    pub memory: Option<String>,
429}
430
431impl Default for WasmFindArgs {
432    fn default() -> Self {
433        Self {
434            pattern: String::new(),
435            start: None,
436            end: None,
437            max: default_wasm_find_max(),
438            memory: None,
439        }
440    }
441}
442
443#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
444pub struct InterceptAddArgs {
445    pub url_pattern: String,
446    pub capture: Option<String>,
447    pub respond: Option<String>,
448    #[serde(default = "default_intercept_status")]
449    pub status: u16,
450}
451
452impl Default for InterceptAddArgs {
453    fn default() -> Self {
454        Self {
455            url_pattern: String::new(),
456            capture: None,
457            respond: None,
458            status: default_intercept_status(),
459        }
460    }
461}
462
463#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
464pub struct IdArgs {
465    pub id: String,
466}
467
468#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
469pub struct ModeArgs {
470    pub mode: String,
471}
472
473#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
474pub struct DomainArgs {
475    pub domain: String,
476}
477
478#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
479pub struct CaptchaInjectArgs {
480    pub token: String,
481    #[serde(default = "default_captcha_type")]
482    pub captcha_type: String,
483    pub callback: Option<String>,
484    pub click_after: Option<String>,
485}
486
487#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
488pub struct NetworkRecordStartArgs {
489    #[serde(default)]
490    pub patterns: Vec<String>,
491    #[serde(default)]
492    pub no_bodies: bool,
493    #[serde(default = "default_max_body_bytes")]
494    pub max_body_bytes: usize,
495    #[serde(default)]
496    pub clear: bool,
497}
498
499#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
500pub struct NetworkLogArgs {
501    pub limit: Option<usize>,
502    pub pattern: Option<String>,
503    pub method: Option<String>,
504    pub status: Option<u16>,
505    pub since: Option<u64>,
506    #[serde(default)]
507    pub compact: bool,
508}
509
510#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
511pub struct NetworkShowArgs {
512    pub id: u64,
513    #[serde(default)]
514    pub body: bool,
515    pub max_body: Option<usize>,
516}
517
518#[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)]
519pub struct NetworkWaitArgs {
520    pub pattern: Option<String>,
521    pub method: Option<String>,
522    pub status: Option<u16>,
523    pub timeout: Option<u64>,
524    pub since: Option<u64>,
525    #[serde(default)]
526    pub include_existing: bool,
527}
528
529#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
530pub struct NetworkExportArgs {
531    pub path: String,
532    #[serde(default = "default_network_export_format")]
533    pub format: String,
534    pub settle_ms: Option<u64>,
535}
536
537impl Default for NetworkExportArgs {
538    fn default() -> Self {
539        Self {
540            path: String::new(),
541            format: default_network_export_format(),
542            settle_ms: None,
543        }
544    }
545}
546
547fn default_max_body_bytes() -> usize {
548    10 * 1024 * 1024
549}
550
551fn default_network_export_format() -> String {
552    "har".to_string()
553}
554
555fn default_viewport_width() -> u32 {
556    390
557}
558
559fn default_viewport_height() -> u32 {
560    844
561}
562
563fn default_device_pixel_ratio() -> f64 {
564    2.0
565}
566
567fn default_wasm_find_max() -> usize {
568    20
569}
570
571fn default_intercept_status() -> u16 {
572    200
573}
574
575fn default_captcha_type() -> String {
576    "auto".to_string()
577}