isoautomate 0.1.0

<div align="center">
  <h1 align="center">isoAutomate Rust SDK</h1>
  
  <p align="center">
    <b>The Sovereign Browser Infrastructure & Orchestration Platform</b>
  </p>

  <a href="https://crates.io/crates/isoautomate">
    <img src="https://img.shields.io/crates/v/isoautomate.svg?color=orange" alt="Crates.io version">
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
  </a>
  <a href="https://isoautomate.com/docs">
    <img src="https://img.shields.io/badge/isoAutomate-Official-blue.svg" alt="Documentation">
  </a>
  <a href="https://docs.rs/isoautomate">
    <img src="https://img.shields.io/docsrs/isoautomate" alt="docs.rs">
  </a>
</div>

<br />

<div align="center">
<img src="ext/sdk-rust.png" alt="isoAutomate Architecture" width="450" />
</div>

---

## Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
isoautomate = "0.1.0"
tokio = { version = "1", features = ["full"] } # Required for async runtime

```

## Configuration


The SDK requires a connection to a Redis instance to communicate with the browser engine. You can configure this via an environment variable (`.env` file) or rely on defaults.

**Method A: Environment Variables (.env)**
Create a `.env` file in your project root.

```ini
REDIS_URL=redis://:yourpassword@localhost:6379/0

```

**Method B: Default Connection**
If no configuration is provided, the SDK defaults to `redis://127.0.0.1:6379`.

## Usage Example


Browser sessions are managed through the `BrowserClient`. Since all operations are asynchronous, you must use an async runtime like `tokio`.

### Basic Automation


```rust
use isoautomate::{BrowserClient, IsoError};

#[tokio::main]

async fn main() -> Result<(), IsoError> {
    // 1. Connect to Redis (loads .env automatically)
    let mut browser = BrowserClient::new().await?;

    // 2. Acquire a browser (Chrome, with Video recording enabled)
    println!("Acquiring browser...");
    browser.acquire("chrome", true, false, None).await?;

    // 3. Navigate & Interact
    browser.open_url("[https://example.com](https://example.com)").await?;
    browser.assert_text("Example Domain", "h1").await?;
    
    println!("Page Title: {:?}", browser.get_title().await?);

    // 4. Cleanup (Crucial step!)
    println!("Releasing browser...");
    let info = browser.release().await?;
    
    // 5. Access session video URL
    if let Some(video_url) = &browser.video_url {
        println!("Session Video: {}", video_url);
    }

    Ok(())
}

```

## The Acquire Method


The `.acquire()` method claims a browser from your remote fleet.

```rust
pub async fn acquire(
    &mut self, 
    browser_type: &str, // "chrome", "brave", "chrome_profiled"
    video: bool,        // Record MP4 video?
    record: bool,       // Record DOM events (RRWeb)?
    profile: Option<String> // Persistence Profile ID
) -> Result<Value, IsoError>

```

### Persistence (Profiles)


To keep cookies and logins across sessions, provide a `profile` string.

```rust
// Use a persistent profile named "marketing_bot_1"
browser.acquire("chrome", false, false, Some("marketing_bot_1".to_string())).await?;

```

---

## Browser Actions


All actions are `async` and return `Result<Value, IsoError>`.

### 1. Navigation


| Method | Arguments | Description |
| --- | --- | --- |
| `open_url(url)` | `&str` | Navigates to the website. |
| `reload(ignore_cache)` | `bool` | Reloads the page. |
| `refresh()` | - | Standard page refresh. |
| `go_back()` | - | History back. |
| `go_forward()` | - | History forward. |
| `internalize_links()` | - | Forces `target="_blank"` links to open in the current tab. |
| `get_navigation_history()` | - | Returns history list. |

```rust
browser.open_url("[https://isoautomate.com](https://isoautomate.com)").await?;
browser.reload(true).await?; // Hard reload

```

### 2. Mouse Interactions


| Method | Arguments | Description |
| --- | --- | --- |
| `click(selector)` | `&str` | Clicks an element. |
| `click_if_visible(selector)` | `&str` | Clicks only if visible. |
| `click_visible_elements(sel, limit)` | `&str`, `u32` | Clicks `limit` visible elements (0 = all). |
| `click_nth_element(sel, n)` | `&str`, `u32` | Clicks the Nth match found in DOM. |
| `click_nth_visible_element(sel, n)` | `&str`, `u32` | Clicks the Nth *visible* match. |
| `click_link(text)` | `&str` | Clicks link by text content. |
| `click_active_element()` | - | Clicks focused element. |
| `double_click(selector)` | `&str` | Double clicks element. |
| `right_click(selector)` | `&str` | Context click. |
| `hover(selector)` | `&str` | Hovers over element. |
| `nested_click(parent, child)` | `&str`, `&str` | Scopes click to child of parent. |
| `click_with_offset(sel, x, y, c)` | `&str`, `i32`, `i32`, `bool` | Clicks at offset coordinates. |
| `drag_and_drop(drag, drop)` | `&str`, `&str` | Drags element 1 to element 2. |

```rust
browser.click("#submit-btn").await?;
browser.click_nth_visible_element(".add-to-cart", 2).await?;

```

### 3. Keyboard & Input


| Method | Arguments | Description |
| --- | --- | --- |
| `type_text(sel, text)` | `&str`, `&str` | Rapid text entry. (Note: renamed from `type` in Python). |
| `press_keys(sel, keys)` | `&str`, `&str` | Human-like typing with events. |
| `send_keys(sel, keys)` | `&str`, `&str` | Standard automation key send. |
| `set_value(sel, val)` | `&str`, `&str` | Sets HTML value attribute directly. |
| `clear(selector)` | `&str` | Clears input field. |
| `clear_input(selector)` | `&str` | Specific clear for `<input>`. |
| `submit(selector)` | `&str` | Submits form containing element. |
| `focus(selector)` | `&str` | Focuses element. |

```rust
browser.type_text("#search", "Rust SDK").await?;
browser.press_keys("#password", "secure123").await?; // Slower, human-like
browser.submit("#login-form").await?;

```

### 4. GUI Actions (OS-Level / Hardware)


*Requires `_profiled` browser type.*

| Method | Arguments | Description |
| --- | --- | --- |
| `gui_click_element(sel, time)` | `&str`, `f64` | Moves OS mouse to element and clicks. |
| `gui_click_x_y(x, y)` | `u32`, `u32` | Clicks raw pixel coordinates. |
| `gui_hover_element(sel)` | `&str` | Moves OS mouse to hover element. |
| `gui_drag_and_drop(d, d, t)` | `&str`, `&str`, `f64` | Hardware drag gesture. |
| `gui_write(text)` | `&str` | Hardware keyboard typing. |
| `gui_press_keys(keys)` | `Vec<String>` | Hardware key combos (e.g., Ctrl+C). |
| `gui_click_captcha()` | - | Auto-clicks captcha checkboxes physically. |
| `solve_captcha()` | - | Trigger captcha solver. |

```rust
browser.gui_click_element("#login-btn", 0.5).await?;
browser.gui_write("Hardware typing").await?;

```

### 5. Selects & Dropdowns


| Method | Arguments | Description |
| --- | --- | --- |
| `select_option_by_text(sel, txt)` | `&str`, `&str` | Select by visible text. |
| `select_option_by_value(sel, val)` | `&str`, `&str` | Select by HTML value. |
| `select_option_by_index(sel, idx)` | `&str`, `u32` | Select by index. |

### 6. Window & Tabs


| Method | Arguments | Description |
| --- | --- | --- |
| `open_new_tab(url)` | `&str` | Opens new tab. |
| `open_new_window(url)` | `&str` | Opens new window. |
| `switch_to_tab(idx)` | `i32` | Switch tab (-1 for last). |
| `switch_to_window(idx)` | `i32` | Switch window. |
| `close_active_tab()` | - | Closes current tab. |
| `maximize()` | - | Maximizes window. |
| `minimize()` | - | Minimizes window. |
| `set_window_size(w, h)` | `u32`, `u32` | Sets viewport size. |
| `set_window_rect(x,y,w,h)` | `i32`, `i32`, `u32`, `u32` | Sets window position & size. |

### 7. Data Extraction


| Method | Arguments | Description |
| --- | --- | --- |
| `get_text(selector)` | `&str` | Gets visible text. |
| `get_title()` | - | Gets page title. |
| `get_current_url()` | - | Gets URL. |
| `get_page_source()` | - | Gets HTML source string. |
| `save_page_source_file(name)` | `Option<&str>` | Saves HTML to local file. |
| `get_html(selector)` | `&str` | Gets inner HTML. |
| `get_attribute(sel, attr)` | `&str`, `&str` | Gets attribute value. |
| `get_element_attributes(sel)` | `&str` | Gets all attributes map. |
| `get_user_agent()` | - | Gets UA string. |
| `get_element_rect(sel)` | `&str` | Gets x, y, w, h of element. |
| `is_element_visible(sel)` | `&str` | Returns boolean. |
| `is_text_visible(text)` | `&str` | Returns boolean. |

```rust
let price = browser.get_text(".price").await?;
let src = browser.get_attribute("img", "src").await?;

```

### 8. Cookies & Storage


| Method | Arguments | Description |
| --- | --- | --- |
| `get_all_cookies()` | - | Returns all cookies. |
| `add_cookie(json)` | `Value` | Adds a cookie (JSON object). |
| `delete_cookie(name)` | `&str` | Deletes cookie. |
| `clear_cookies()` | - | Clears all cookies. |
| `save_cookies(name)` | `Option<&str>` | Saves cookies to local JSON file. |
| `load_cookies(name, list)` | `Option<&str>`, `Option` | Loads cookies from file or JSON. |
| `get_local_storage_item(key)` | `&str` | Gets local storage value. |
| `set_local_storage_item(k, v)` | `&str`, `&str` | Sets local storage. |

### 9. Assertions & Waits


*Assertions automatically save a screenshot to `screenshots/failures/` if they fail.*

| Method | Arguments | Description |
| --- | --- | --- |
| `sleep(seconds)` | `f64` | Pauses execution. |
| `wait_for_element(sel, timeout)` | `&str`, `Option<u64>` | Waits for element. |
| `wait_for_text(text, sel, tm)` | `&str`, `&str`, `Option` | Waits for text. |
| `assert_element(sel)` | `&str` | Errors if element missing. |
| `assert_text(text, sel)` | `&str`, `&str` | Errors if text missing. |
| `assert_url(substring)` | `&str` | Errors if URL mismatch. |

```rust
browser.wait_for_element("#dashboard", Some(15)).await?;
browser.assert_text("Success", ".alert").await?;

```

### 10. Advanced & Files


| Method | Arguments | Description |
| --- | --- | --- |
| `execute_script(script)` | `&str` | Runs JS in browser. |
| `evaluate(expr)` | `&str` | Returns JS expression value. |
| `screenshot(sel, name)` | `Option`, `Option` | Saves screenshot to file. |
| `save_as_pdf(name)` | `&str` | Saves page as PDF. |
| `upload_file(sel, path)` | `&str`, `&str` | Uploads local file to input. |
| `execute_cdp_cmd(cmd, params)` | `&str`, `Value` | **God Mode:** Raw CDP access. |
| `get_mfa_code(key)` | `&str` | Generates TOTP code. |
| `enter_mfa_code(sel, key)` | `&str`, `&str` | Types TOTP code. |
| `block_urls(patterns)` | `Vec<String>` | Blocks network requests. |

```rust
// Execute JS
let val = browser.evaluate("window.innerWidth").await?;

// Upload File
browser.upload_file("input[type='file']", "./photo.jpg").await?;

// God Mode (CDP)
browser.execute_cdp_cmd("Network.clearBrowserCache", json!({})).await?;

```

---

## License


This project is licensed under the **MIT License**.
Built for the **isoAutomate** platform.