cmdop 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

cmdop/__init__.py

@@ -124,7 +124,7 @@ from cmdop.logging import (
     get_log_dir,
 )
 
-__version__ = "0.1.23"
+__version__ = "0.1.25"
 
 __all__ = [
     # Version

cmdop/helpers/__init__.py

@@ -2,8 +2,16 @@
 
 from cmdop.helpers.formatting import json_to_toon
 from cmdop.helpers.cleaner import JsonCleaner
+from cmdop.helpers.network_analyzer import (
+    NetworkAnalyzer,
+    NetworkSnapshot,
+    RequestSnapshot,
+)
 
 __all__ = [
     "json_to_toon",
     "JsonCleaner",
+    "NetworkAnalyzer",
+    "NetworkSnapshot",
+    "RequestSnapshot",
 ]

cmdop/helpers/network_analyzer.py

@@ -0,0 +1,368 @@
+"""Network analyzer for discovering API endpoints and creating request snapshots."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+from urllib.parse import urlparse, parse_qs
+
+if TYPE_CHECKING:
+    from cmdop.services.browser.session import BrowserSession
+    from cmdop.services.browser.models import NetworkExchange
+
+
+class RequestSnapshot(BaseModel):
+    """Complete snapshot of an API request for reproduction."""
+
+    # Request info
+    url: str
+    method: str = "GET"
+    headers: dict[str, str] = Field(default_factory=dict)
+    body: str = ""
+
+    # Response info
+    status: int | None = None
+    content_type: str = ""
+    size: int = 0
+
+    # Parsed URL parts
+    base_url: str = ""
+    path: str = ""
+    query_params: dict[str, list[str]] = Field(default_factory=dict)
+
+    # Data analysis
+    data_key: str | None = None
+    item_count: int | None = None
+    item_fields: list[str] = Field(default_factory=list)
+    sample_response: Any = None
+
+    # Session data
+    cookies: dict[str, str] = Field(default_factory=dict)
+
+    def to_curl(self) -> str:
+        """Generate curl command to reproduce request."""
+        parts = [f"curl -X {self.method}"]
+
+        # Add headers
+        for key, value in self.headers.items():
+            if key.lower() not in ("host", "content-length"):
+                parts.append(f"-H '{key}: {value}'")
+
+        # Add cookies if not in headers
+        if self.cookies and "cookie" not in [k.lower() for k in self.headers]:
+            cookie_str = "; ".join(f"{k}={v}" for k, v in self.cookies.items())
+            parts.append(f"-H 'Cookie: {cookie_str}'")
+
+        # Add body
+        if self.body:
+            parts.append(f"-d '{self.body}'")
+
+        # Add URL
+        parts.append(f"'{self.url}'")
+
+        return " \\\n  ".join(parts)
+
+    def to_httpx(self) -> str:
+        """Generate httpx Python code to reproduce request."""
+        lines = ["import httpx", ""]
+
+        # Headers
+        if self.headers:
+            lines.append("headers = {")
+            for key, value in self.headers.items():
+                if key.lower() not in ("host", "content-length"):
+                    lines.append(f'    "{key}": "{value}",')
+            lines.append("}")
+        else:
+            lines.append("headers = {}")
+
+        # Cookies
+        if self.cookies:
+            lines.append("")
+            lines.append("cookies = {")
+            for key, value in self.cookies.items():
+                lines.append(f'    "{key}": "{value}",')
+            lines.append("}")
+        else:
+            lines.append("cookies = {}")
+
+        # Request
+        lines.append("")
+        if self.method == "GET":
+            lines.append(f'response = httpx.get("{self.url}", headers=headers, cookies=cookies)')
+        elif self.method == "POST":
+            if self.body:
+                lines.append(f'data = {repr(self.body)}')
+                lines.append(f'response = httpx.post("{self.url}", headers=headers, cookies=cookies, content=data)')
+            else:
+                lines.append(f'response = httpx.post("{self.url}", headers=headers, cookies=cookies)')
+        else:
+            lines.append(f'response = httpx.request("{self.method}", "{self.url}", headers=headers, cookies=cookies)')
+
+        lines.append("print(response.json())")
+
+        return "\n".join(lines)
+
+
+class NetworkSnapshot(BaseModel):
+    """Complete snapshot of network activity for a site."""
+
+    url: str
+    timestamp: str = ""
+
+    # Session data
+    cookies: dict[str, str] = Field(default_factory=dict)
+    local_storage: dict[str, str] = Field(default_factory=dict)
+
+    # Captured requests
+    api_requests: list[RequestSnapshot] = Field(default_factory=list)
+    json_requests: list[RequestSnapshot] = Field(default_factory=list)
+    other_requests: list[dict] = Field(default_factory=list)
+
+    # Stats
+    total_requests: int = 0
+    total_bytes: int = 0
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert to JSON string."""
+        return self.model_dump_json(indent=indent)
+
+    def best_api(self) -> RequestSnapshot | None:
+        """Get the best data API (largest response, then most items)."""
+        if not self.api_requests:
+            return None
+        return max(self.api_requests, key=lambda r: (r.size, r.item_count or 0))
+
+
+class NetworkAnalyzer:
+    """Analyze network requests to discover API endpoints.
+
+    Creates complete request snapshots including cookies, headers, and
+    all data needed to reproduce API calls.
+
+    Usage:
+        from cmdop import CMDOPClient
+        from cmdop.helpers import NetworkAnalyzer
+
+        client = CMDOPClient.local()
+        with client.browser.create_session(headless=False) as b:
+            analyzer = NetworkAnalyzer(b)
+
+            # Interactive mode - user clicks pagination
+            snapshot = analyzer.capture("https://example.com/cars", wait_seconds=30)
+
+            # Get best API endpoint
+            if snapshot.api_requests:
+                best = snapshot.best_api()
+                print(f"API: {best.url}")
+                print(f"Curl: {best.to_curl()}")
+    """
+
+    # Common keys that contain data arrays
+    DATA_KEYS = [
+        "data", "items", "results", "list", "records",
+        "cars", "vehicles", "products", "listings", "entries",
+        "rows", "content", "objects", "elements", "collection",
+    ]
+
+    def __init__(self, session: "BrowserSession"):
+        """Initialize with browser session."""
+        self._session = session
+
+    def capture(
+        self,
+        url: str,
+        wait_seconds: int = 30,
+        url_pattern: str = "",
+        clear_initial: bool = True,
+        same_origin: bool = True,
+        min_size: int = 100,
+        max_size: int = 5_000_000,
+        countdown_message: str = "Click pagination!",
+    ) -> NetworkSnapshot:
+        """Capture network requests while user interacts with page.
+
+        Args:
+            url: Page URL to open
+            wait_seconds: Time to wait for user interactions
+            url_pattern: Optional regex filter for API URLs
+            clear_initial: Clear page load requests before capture
+            same_origin: Only capture requests to same domain (default True)
+            min_size: Min response size in bytes (filter tracking pixels)
+            max_size: Max response size in bytes (filter images/assets)
+            countdown_message: Message to show in countdown toast
+
+        Returns:
+            NetworkSnapshot with all captured requests and session data
+        """
+        from cmdop.services.browser.models import WaitUntil
+        from datetime import datetime
+
+        b = self._session
+        snapshot = NetworkSnapshot(
+            url=url,
+            timestamp=datetime.now().isoformat(),
+        )
+
+        # Extract base domain for filtering
+        base_domain = self._extract_base_domain(url)
+
+        # Enable network capture
+        b.network.enable(max_exchanges=500, max_response_size=5_000_000)
+
+        try:
+            print(f"Opening {url}...")
+            b.navigate(url, timeout_ms=90000, wait_until=WaitUntil.LOAD)
+
+            # Wait for page to be interactive
+            try:
+                b.wait_for("body", timeout_ms=10000)
+            except Exception:
+                pass
+            time.sleep(2)
+
+            if clear_initial:
+                b.network.clear()
+
+            # Show countdown while user interacts
+            b.visual.countdown(wait_seconds, countdown_message)
+
+            # Get cookies
+            b.visual.toast("Getting cookies...")
+            try:
+                cookies = b.get_cookies()
+                snapshot.cookies = {c.name: c.value for c in cookies}
+            except Exception:
+                pass
+
+            # Get stats
+            b.visual.toast("Getting network stats...")
+            stats = b.network.stats()
+            snapshot.total_requests = stats.total_captured
+            snapshot.total_bytes = stats.total_bytes
+
+            b.visual.toast(f"Captured {stats.total_captured} requests")
+
+            # Get XHR/Fetch calls
+            b.visual.toast("Filtering XHR/Fetch...")
+            # print("Calling network.filter...", flush=True)
+            api_calls = b.network.filter(
+                url_pattern=url_pattern,
+                resource_types=["xhr", "fetch"],
+            )
+            # print(f"Filter returned {len(api_calls)} calls", flush=True)
+
+            # Filter by domain
+            # print("Filtering by domain...", flush=True)
+            if same_origin:
+                api_calls = [
+                    call for call in api_calls
+                    if base_domain in urlparse(call.request.url).netloc
+                ]
+            # print(f"After domain filter: {len(api_calls)}", flush=True)
+
+            # # Show sizes before filtering
+            # for call in api_calls:
+            #     size = call.response.size if call.response else 0
+            #     print(f"  {call.request.url[:60]}... size={size}", flush=True)
+
+            # Filter by response size (ignore tracking pixels and heavy assets)
+            # print(f"Filtering by size ({min_size}-{max_size})...", flush=True)
+            api_calls = [
+                call for call in api_calls
+                if call.response and min_size <= call.response.size <= max_size
+            ]
+            # print(f"After size filter: {len(api_calls)}", flush=True)
+
+            # print("Showing toast...", flush=True)
+            b.visual.toast(f"Found {len(api_calls)} API calls")
+
+            # Analyze calls - all JSON responses are API requests
+            # print(f"Analyzing {len(api_calls)} calls...", flush=True)
+            for call in api_calls:
+                req = self._create_snapshot(call, snapshot.cookies)
+                if req:
+                    if req.content_type and "json" in req.content_type:
+                        snapshot.api_requests.append(req)
+                    else:
+                        snapshot.other_requests.append({
+                            "url": call.request.url,
+                            "method": call.request.method,
+                            "status": call.response.status if call.response else None,
+                        })
+
+            # print("Analysis done", flush=True)
+
+        finally:
+            # print("Disabling network capture...", flush=True)
+            b.network.disable()
+            # print("Network disabled", flush=True)
+
+        # print("Returning snapshot", flush=True)
+        return snapshot
+
+    def _extract_base_domain(self, url: str) -> str:
+        """Extract base domain from URL, handling country-code TLDs."""
+        parsed = urlparse(url)
+        host = parsed.netloc.replace("www.", "")
+        parts = host.split(".")
+
+        # Country-code second-level domains
+        cc_slds = {"co", "com", "net", "org", "ac", "go", "ne", "or"}
+
+        if len(parts) >= 3 and parts[-2] in cc_slds:
+            return ".".join(parts[-3:])  # bobaedream.co.kr
+        elif len(parts) >= 2:
+            return ".".join(parts[-2:])  # kcar.com
+        return host
+
+    def _create_snapshot(
+        self,
+        exchange: "NetworkExchange",
+        session_cookies: dict[str, str],
+    ) -> RequestSnapshot | None:
+        """Create request snapshot from network exchange."""
+        if not exchange.response:
+            return None
+
+        parsed = urlparse(exchange.request.url)
+
+        snapshot = RequestSnapshot(
+            url=exchange.request.url,
+            method=exchange.request.method,
+            headers=dict(exchange.request.headers),
+            body=exchange.request.body.decode("utf-8", errors="ignore") if exchange.request.body else "",
+            status=exchange.response.status,
+            content_type=exchange.response.content_type or "",
+            size=exchange.response.size,
+            base_url=f"{parsed.scheme}://{parsed.netloc}",
+            path=parsed.path,
+            query_params=parse_qs(parsed.query),
+            cookies=session_cookies,
+        )
+
+        # Parse JSON response
+        if "json" in snapshot.content_type.lower():
+            try:
+                data = exchange.json_body()
+                snapshot.sample_response = data
+
+                if isinstance(data, list):
+                    snapshot.item_count = len(data)
+                    if data and isinstance(data[0], dict):
+                        snapshot.item_fields = list(data[0].keys())
+                elif isinstance(data, dict):
+                    for key in self.DATA_KEYS:
+                        if key in data and isinstance(data[key], list):
+                            snapshot.data_key = key
+                            snapshot.item_count = len(data[key])
+                            if data[key] and isinstance(data[key][0], dict):
+                                snapshot.item_fields = list(data[key][0].keys())
+                            break
+            except Exception:
+                pass
+
+        return snapshot
+

cmdop/services/browser/capabilities/__init__.py

@@ -6,6 +6,7 @@ from .timing import TimingCapability
 from .dom import DOMCapability
 from .fetch import FetchCapability
 from .network import NetworkCapability
+from .visual import VisualCapability
 
 __all__ = [
     "ScrollCapability",
@@ -14,4 +15,5 @@ __all__ = [
     "DOMCapability",
     "FetchCapability",
     "NetworkCapability",
+    "VisualCapability",
 ]

cmdop/services/browser/capabilities/visual.py

@@ -0,0 +1,100 @@
+"""Visual capability - CMDOP plugin overlay effects."""
+
+from __future__ import annotations
+
+import time
+
+from ._base import BaseCapability
+
+
+class VisualCapability(BaseCapability):
+    """Visual effects via CMDOP browser plugin.
+
+    Provides toast notifications, click effects, highlights, etc.
+
+    Usage:
+        b.visual.toast("Hello!")
+        b.visual.countdown(10)  # Smart countdown with early exit
+        b.visual.highlight(".button")
+    """
+
+    def _dispatch(self, action: str, data: dict) -> None:
+        """Dispatch visual action via CMDOP Visual extension.
+
+        Uses "mw:" prefix for main world execution to access __CMDOP_VISUAL__.
+        The extension API internally handles postMessage to content script.
+        """
+        import json
+        data_json = json.dumps(data)
+        # "mw:" prefix tells Go backend to execute in main world context
+        self._js(f"""mw:(() => {{
+                const data = {data_json};
+                const api = window.__CMDOP_VISUAL__;
+                if (!api) return;
+
+                switch ('{action}') {{
+                    case 'toast': api.showToast?.(data.message); break;
+                    case 'clearToasts': api.clearToasts?.(); break;
+                    case 'click': api.showClick?.(data.x, data.y, data.type || 'left'); break;
+                    case 'move': api.showMouseMove?.(data.fromX, data.fromY, data.toX, data.toY); break;
+                    case 'highlight': api.showHighlight?.(data.selector); break;
+                    case 'hideHighlight': api.hideHighlight?.(); break;
+                    case 'clearTrail': api.clearTrail?.(); break;
+                    case 'state': api.setAutomationState?.(data.state); break;
+                }}
+            }})()
+        """)
+
+    def toast(self, message: str) -> None:
+        """Show toast notification in browser."""
+        self._dispatch("toast", {"message": message})
+
+    def clear_toasts(self) -> None:
+        """Clear all toast notifications."""
+        self._dispatch("clearToasts", {})
+
+    def click(self, x: int, y: int, click_type: str = "left") -> None:
+        """Show click effect at coordinates."""
+        self._dispatch("click", {"x": x, "y": y, "type": click_type})
+
+    def move(self, from_x: int, from_y: int, to_x: int, to_y: int) -> None:
+        """Show mouse movement trail."""
+        self._dispatch("move", {"fromX": from_x, "fromY": from_y, "toX": to_x, "toY": to_y})
+
+    def highlight(self, selector: str) -> None:
+        """Highlight element by selector."""
+        self._dispatch("highlight", {"selector": selector})
+
+    def hide_highlight(self) -> None:
+        """Hide element highlight."""
+        self._dispatch("hideHighlight", {})
+
+    def clear_trail(self) -> None:
+        """Clear cursor trail."""
+        self._dispatch("clearTrail", {})
+
+    def set_state(self, state: str) -> None:
+        """Set automation state: 'idle', 'active', 'busy'."""
+        self._dispatch("state", {"state": state})
+
+    def countdown(self, seconds: int, message: str = "Click pagination!") -> None:
+        """Visual countdown timer with toast notifications.
+
+        Shows countdown in browser while user interacts with page.
+        No early exit - just waits the full duration.
+
+        Args:
+            seconds: Seconds to wait
+            message: Message to show with countdown
+        """
+        for i in range(seconds, 0, -1):
+            try:
+                self.clear_toasts()
+                self.toast(f"⏱️ {i}s - {message}")
+            except Exception:
+                pass
+
+            print(f"{i}", end=" ", flush=True)
+            time.sleep(1)
+
+        print("done", flush=True)

cmdop/services/browser/session.py

@@ -12,6 +12,7 @@ from .capabilities import (
     DOMCapability,
     FetchCapability,
     NetworkCapability,
+    VisualCapability,
 )
 
 if TYPE_CHECKING:
@@ -53,6 +54,7 @@ class BrowserSession:
         "_dom",
         "_fetch",
         "_network",
+        "_visual",
     )
 
     def __init__(self, service: "BrowserService", session_id: str) -> None:
@@ -64,6 +66,7 @@ class BrowserSession:
         self._dom: DOMCapability | None = None
         self._fetch: FetchCapability | None = None
         self._network: NetworkCapability | None = None
+        self._visual: VisualCapability | None = None
 
     @property
     def session_id(self) -> str:
@@ -113,6 +116,13 @@ class BrowserSession:
             self._network = NetworkCapability(self)
         return self._network
 
+    @property
+    def visual(self) -> VisualCapability:
+        """Visual: toast(), click(), move(), highlight(), hide_highlight(), clear_trail(), set_state()"""
+        if self._visual is None:
+            self._visual = VisualCapability(self)
+        return self._visual
+
     # === Core Methods ===
 
     def navigate(

cmdop-0.1.25.dist-info/METADATA

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: cmdop
+Version: 0.1.25
+Summary: Python SDK for CMDOP agent interaction
+Project-URL: Homepage, https://cmdop.com
+Project-URL: Documentation, https://cmdop.com
+Project-URL: Repository, https://github.com/markolofsen/cmdop-client
+Author: CMDOP Team
+License: MIT
+License-File: LICENSE
+Keywords: agent,automation,cmdop,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: toon-python>=0.1.2
+Provides-Extra: dev
+Requires-Dist: beautifulsoup4>=4.12.0; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.60.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-grpc-aio>=0.3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cmdop
+
+Python SDK for CMDOP browser automation and server control.
+
+## Architecture
+
+```
+Your Code ──── Cloud Relay ──── Agent (on server)
+                    │
+        Outbound only, works through any NAT/firewall
+```
+
+## Install
+
+```bash
+pip install cmdop
+```
+
+## Connection
+
+```python
+from cmdop import CMDOPClient, AsyncCMDOPClient
+
+# Local (direct IPC to running agent)
+client = CMDOPClient.local()
+
+# Remote (via cloud relay)
+client = CMDOPClient.remote(api_key="cmd_xxx")
+
+# Async
+async with AsyncCMDOPClient.local() as client:
+    await client.files.read("/etc/hostname")
+```
+
+## Browser
+
+```python
+from cmdop.services.browser.models import WaitUntil
+
+with client.browser.create_session(headless=False) as s:
+    s.navigate("https://shop.com", wait_until=WaitUntil.NETWORKIDLE)
+
+    # Core methods
+    s.click("button.buy", move_cursor=True)
+    s.type("input[name=q]", "search term")
+    s.wait_for(".results")
+    s.execute_script("return document.title")
+    s.screenshot()
+    s.get_state()        # URL + title
+    s.get_page_info()    # Full page info
+    s.get_cookies()
+    s.set_cookies([...])
+```
+
+**WaitUntil options:**
+| Value | Description |
+|-------|-------------|
+| `LOAD` | Wait for load event (default) |
+| `DOMCONTENTLOADED` | Wait for DOMContentLoaded |
+| `NETWORKIDLE` | Wait until network is idle (best for SPA) |
+| `COMMIT` | Return immediately (fastest) |
+
+### Capabilities
+
+**`s.scroll`** - Scrolling
+```python
+s.scroll.js("down", 500)           # JS scroll (works on complex sites)
+s.scroll.native("down", 500)       # Browser API scroll
+s.scroll.to_bottom()               # Scroll to page bottom
+s.scroll.to_element(".item")       # Scroll element into view
+s.scroll.info()                    # Get scroll position/dimensions
+
+# Smart infinite scroll with extraction
+items = s.scroll.infinite(
+    extract_fn=lambda: extract_new_items(),
+    limit=100,
+    max_scrolls=50,
+    scroll_amount=800,
+)
+```
+
+**`s.input`** - Input
+```python
+s.input.click_js(".btn")           # JS click (reliable)
+s.input.click_all("See more")      # Click all matching elements
+s.input.key("Escape")              # Press key
+s.input.key("Enter", ".input")     # Press key on element
+s.input.hover(".tooltip")          # Native hover
+s.input.hover_js(".tooltip")       # JS hover
+s.input.mouse_move(500, 300)       # Move cursor to coordinates
+```
+
+**`s.timing`** - Delays
+```python
+s.timing.wait(500)                 # Wait ms
+s.timing.seconds(2)                # Wait seconds
+s.timing.random(0.5, 1.5)          # Random delay
+s.timing.timeout(fn, 10, cleanup)  # Run with timeout
+```
+
+**`s.dom`** - DOM operations
+```python
+s.dom.html(".container")           # Get HTML
+s.dom.text(".title")               # Get text
+s.dom.soup(".items")               # → SoupWrapper (chainable BS4)
+s.dom.parse(html_string)           # → BeautifulSoup
+s.dom.extract(".items", "href")    # Get attr list
+s.dom.select("#country", "US")     # Dropdown select
+s.dom.close_modal()                # Close dialogs/popups
+```
+
+**`s.fetch`** - HTTP from browser (bypass CORS, inherit cookies)
+```python
+s.fetch.json("/api/items")               # Fetch JSON
+s.fetch.all(["/api/a", "/api/b"])        # Parallel fetch
+s.fetch.execute("return fetch(...)")     # Custom JS
+```
+
+**`s.network`** - Traffic capture
+```python
+s.network.enable(max_exchanges=1000)
+s.navigate(url)
+
+# Get exchanges
+exchanges = s.network.get_all()
+api = s.network.last("/api/data")
+data = api.json_body()
+
+# Filter
+posts = s.network.filter(
+    url_pattern="/api/posts",
+    methods=["GET", "POST"],
+    status_codes=[200],
+    resource_types=["xhr", "fetch"],
+)
+
+# Convenience
+s.network.api_calls("/api/")       # XHR/Fetch matching pattern
+s.network.last_json("/api/data")   # JSON body directly
+s.network.wait_for("/api/", 5000)  # Wait for request
+s.network.export_har()             # Export to HAR
+s.network.stats()                  # Capture statistics
+s.network.clear()                  # Clear captured
+s.network.disable()
+```
+
+**`s.visual`** - Browser overlay (requires CMDOP extension)
+```python
+s.visual.toast("Loading...")           # Show toast
+s.visual.clear_toasts()                # Clear all toasts
+s.visual.countdown(30, "Click!")       # Countdown timer
+s.visual.highlight(".element")         # Highlight element
+s.visual.hide_highlight()              # Hide highlight
+s.visual.click(100, 200)               # Show click effect
+s.visual.move(0, 0, 100, 200)          # Show cursor trail
+s.visual.set_state("busy")             # idle/active/busy
+```
+
+## NetworkAnalyzer
+
+Discover API endpoints by capturing traffic while user interacts.
+
+```python
+from cmdop import CMDOPClient
+from cmdop.helpers import NetworkAnalyzer
+
+client = CMDOPClient.local()
+with client.browser.create_session(headless=False) as b:
+    analyzer = NetworkAnalyzer(b)
+
+    snapshot = analyzer.capture(
+        "https://example.com/cars",
+        wait_seconds=30,
+        countdown_message="Click pagination!",
+        min_size=100,       # Ignore tracking pixels
+        max_size=500_000,   # Ignore heavy assets
+        same_origin=True,   # Only same domain
+    )
+
+    # Get best data API
+    if snapshot.api_requests:
+        best = snapshot.best_api()
+        print(best.url)
+        print(best.item_count)
+        print(best.data_key)        # "data", "items", etc.
+        print(best.item_fields)     # Field names
+        print(best.to_curl())       # curl command
+        print(best.to_httpx())      # Python httpx code
+
+    # All captured
+    for req in snapshot.api_requests:
+        print(f"{req.method} {req.url} → {req.item_count} items")
+```
+
+**NetworkSnapshot:**
+- `api_requests` - Requests with data arrays
+- `json_requests` - Other JSON responses
+- `cookies` - Session cookies
+- `total_requests`, `total_bytes`
+
+**RequestSnapshot:**
+- `url`, `method`, `headers`, `body`, `cookies`
+- `status`, `content_type`, `size`
+- `data_key`, `item_count`, `item_fields`, `sample_response`
+- `to_curl()`, `to_httpx()`
+
+## Agent
+
+Run AI tasks with typed output:
+
+```python
+from pydantic import BaseModel
+
+class Health(BaseModel):
+    status: str
+    cpu: float
+    issues: list[str]
+
+result = client.agent.run("Check server health", output_schema=Health)
+health: Health = result.output  # Typed!
+```
+
+## Terminal
+
+```python
+session = client.terminal.create()
+client.terminal.send_input(session.session_id, "ls -la\n")
+output = client.terminal.get_history(session.session_id)
+client.terminal.resize(session.session_id, 120, 40)
+client.terminal.send_signal(session.session_id, "SIGINT")
+client.terminal.close(session.session_id)
+```
+
+## Files
+
+```python
+client.files.list("/var/log")
+client.files.read("/etc/nginx/nginx.conf")
+client.files.write("/tmp/config.json", b'{"key": "value"}')
+client.files.delete("/tmp/old.txt")
+client.files.copy("/src", "/dst")
+client.files.move("/old", "/new")
+client.files.mkdir("/new/dir")
+client.files.info("/path")
+```
+
+## SDKBaseModel
+
+Auto-cleaning Pydantic model:
+
+```python
+from cmdop import SDKBaseModel
+
+class Product(SDKBaseModel):
+    __base_url__ = "https://shop.com"
+    name: str = ""    # "  iPhone 15  \n" → "iPhone 15"
+    price: int = 0    # "$1,299.00" → 1299
+    rating: float = 0 # "4.5 stars" → 4.5
+    url: str = ""     # "/p/123" → "https://shop.com/p/123"
+
+products = Product.from_list(raw["items"])  # Auto dedupe + filter
+```
+
+## Utilities
+
+```python
+from cmdop import get_logger, json_to_toon
+
+# Logging (rich console + file)
+log = get_logger(__name__)
+log.info("Starting")
+
+# TOON format (30-50% token savings)
+toon = json_to_toon({"name": "Alice", "age": 25})
+# → "name: Alice\nage: 25"
+```
+
+## Requirements
+
+- Python 3.10+
+- CMDOP agent running locally or API key for remote

{cmdop-0.1.23.dist-info → cmdop-0.1.25.dist-info}/RECORD

@@ -1,4 +1,4 @@
-cmdop/__init__.py,sha256=eqEIR3w99NYHsoGF6FioESxTgQhB2yWiARNYWbmNdkk,5200
+cmdop/__init__.py,sha256=JAH5EagCk6WJ2i-OiE7QofeEi9LjaaHbvECewfdvOsg,5200
 cmdop/client.py,sha256=nTotStZPBfYN3TrHH-OlEJMSVAXskYMQRkocsFmyaBY,14601
 cmdop/config.py,sha256=vpw1aGCyS4NKlZyzVur81Lt06QmN3FnscZji0bypUi0,4398
 cmdop/discovery.py,sha256=HNxSOa5tSuG7ppfFs21XdviW5ucjpRswVPguhX5j8Dg,7479
@@ -150,9 +150,10 @@ cmdop/api/generated/workspaces/workspaces__api__workspaces/__init__.py,sha256=Wo
 cmdop/api/generated/workspaces/workspaces__api__workspaces/client.py,sha256=A1c5s8FJQ7vJRjReO7QQ8D6tPN-6PudxQXLYP6EGE2I,9861
 cmdop/api/generated/workspaces/workspaces__api__workspaces/models.py,sha256=3UFJFLWWQs_jzSmFstJ5T1lsaVp9TYSb1u6YFFq5RSk,9501
 cmdop/api/generated/workspaces/workspaces__api__workspaces/sync_client.py,sha256=KfWxpSjZyfZLjonHRFwk0a1eUmOZHuky4ZySo11wTWg,9639
-cmdop/helpers/__init__.py,sha256=a1GXe7vxVYsfOTR-n_m9NkxoqZYn1fiFuEVe0bMTV2g,176
+cmdop/helpers/__init__.py,sha256=fxzHT-O9D4HbvSU4qcQ9Ce3Q0Y5dZV-nQHVuoMpahCw,355
 cmdop/helpers/cleaner.py,sha256=3XWB3KpRSMgJ1Go0G7rE9bgDGy1bshk9PtWWB6pL7AU,1792
 cmdop/helpers/formatting.py,sha256=lLYUEyzZLUSXq2xHB2w3i72QoP_baHjtFpP-7mb-V-s,341
+cmdop/helpers/network_analyzer.py,sha256=ZiTRv39S_kTAppTVbq97DYLExS2WsDLCxf_N4rtnkf0,13025
 cmdop/models/__init__.py,sha256=W6P1oo6JkUAeVEV59HzFT646hXM0pk_obXHfHbX4tAc,1594
 cmdop/models/agent.py,sha256=Z1QDfr1-DTFVl5oPvbH2ZUBLXPHUlitiCRfG7y_OzYg,5495
 cmdop/models/base.py,sha256=1SR1ka5p-rHHkk4k9pPwbraxX_CsTG830CosGNPn1JA,7425
@@ -169,8 +170,8 @@ cmdop/services/terminal.py,sha256=9SSWBexe2rWgMd-hGBEs9mcax3l7x_U84VHZpMC4xK8,17
 cmdop/services/browser/__init__.py,sha256=31Ofu9RCYTAedPKLvnor8J7oGDgTjbqJ58OkxxHYwdk,1270
 cmdop/services/browser/models.py,sha256=9MpNFgSgZDIznmTmsCUByEN31t_iQ6kAza1BsPSsuJs,5320
 cmdop/services/browser/parsing.py,sha256=0hQAy-0ZwJqtmhEqHO3EEdVB3iYmyhXRdouN_dCbig8,3820
-cmdop/services/browser/session.py,sha256=atSDDrTdkVJ6OrTiz8OaifegedZvbkUZUpfxGKUrDw8,6403
-cmdop/services/browser/capabilities/__init__.py,sha256=UFmqG3XB2xm0MI2jRmsSXyvFyREPbfJnXLzgaragpbU,398
+cmdop/services/browser/session.py,sha256=4_g-vPiiFBTiz5pbaOSxEKsjgkjEPU949jby2B15eWQ,6771
+cmdop/services/browser/capabilities/__init__.py,sha256=GfLhrQ_z-g22OwlZQt8KpQltA61SLSgV4cSsY284DUI,459
 cmdop/services/browser/capabilities/_base.py,sha256=mW0jKa2CyvK-8cjenv5JYvuCKiO3rpt5F7WtWFXBitA,749
 cmdop/services/browser/capabilities/_helpers.py,sha256=jXqYbeDocAHec2GwF2_BNnJ78vTyUnHteQoS-RSG00k,488
 cmdop/services/browser/capabilities/dom.py,sha256=DuXfildga23wGBNJWtNzx-t2Cq553HC48o9KAWAlyC0,2612
@@ -179,6 +180,7 @@ cmdop/services/browser/capabilities/input.py,sha256=uYmWGqturMDent44Us80oT_nk4kF
 cmdop/services/browser/capabilities/network.py,sha256=tZV4Oh_J5zUjEe9GBLQBDXEVh9EVTecPbyjE7lIUrd0,7775
 cmdop/services/browser/capabilities/scroll.py,sha256=sh0VuOPOv81BZg80-n8TABOj5RpshJT12qJwm4F_OY0,4808
 cmdop/services/browser/capabilities/timing.py,sha256=NH34G_4Kfukh6JCdhLRGoouA-uNTbx9ly7ybP9Kh558,1868
+cmdop/services/browser/capabilities/visual.py,sha256=AecHna1jqIzgQdsYHiPlZjp-Rr8ivW4EE7IWf1Hyeko,3671
 cmdop/services/browser/js/__init__.py,sha256=gTiZguikKfztDtggZTux2FqhT8YTjyHCzQR4TEnT7z4,1177
 cmdop/services/browser/js/core.py,sha256=QXCCX_al5tMgz7aCwMqhIs1aRe_IdG8teOJniaumA5Q,995
 cmdop/services/browser/js/fetch.py,sha256=WPy_H4LLkneSx06wpfnx4Sx_0Okf2ENXi6bveCd9ZCg,2188
@@ -198,7 +200,7 @@ cmdop/transport/base.py,sha256=2pkV8i9epgp_21dyReCfX47abRUrnALm0W5BXb-Fuz0,5571
 cmdop/transport/discovery.py,sha256=rcGAuVrR1l6jwcP0dqZxVhX1NsFK7sRHygFMCLmmUbA,10673
 cmdop/transport/local.py,sha256=ob6tWVxSdKwblHSMK8CkgjyuSdQoAeWgy5OAUd5ZNuE,7411
 cmdop/transport/remote.py,sha256=FNVqus9wOv7LlxKarXjLmSyvJiHwhvPbNDOPv1IQkmE,4329
-cmdop-0.1.23.dist-info/METADATA,sha256=3BVnbTuAgOy-U2nU1g7gpiE1n1E81AZjepAvHM1N0hA,8929
-cmdop-0.1.23.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-cmdop-0.1.23.dist-info/licenses/LICENSE,sha256=6hyzbI1QVXW6B-XT7PaQ6UG9lns11Y_nnap8uUKGUqo,1062
-cmdop-0.1.23.dist-info/RECORD,,
+cmdop-0.1.25.dist-info/METADATA,sha256=zU53FzmNQTtobkEzWTWOnYCYiB80P6sER5Ovmq0WcoU,9284
+cmdop-0.1.25.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cmdop-0.1.25.dist-info/licenses/LICENSE,sha256=6hyzbI1QVXW6B-XT7PaQ6UG9lns11Y_nnap8uUKGUqo,1062
+cmdop-0.1.25.dist-info/RECORD,,

cmdop-0.1.23.dist-info/METADATA

@@ -1,330 +0,0 @@
-Metadata-Version: 2.4
-Name: cmdop
-Version: 0.1.23
-Summary: Python SDK for CMDOP agent interaction
-Project-URL: Homepage, https://cmdop.com
-Project-URL: Documentation, https://cmdop.com
-Project-URL: Repository, https://github.com/markolofsen/cmdop-client
-Author: CMDOP Team
-License: MIT
-License-File: LICENSE
-Keywords: agent,automation,cmdop,terminal
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: beautifulsoup4>=4.12.0
-Requires-Dist: grpcio>=1.60.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: lxml>=5.0.0
-Requires-Dist: protobuf>=4.25.0
-Requires-Dist: pydantic-settings>=2.0.0
-Requires-Dist: pydantic>=2.5.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: toon-python>=0.1.2
-Provides-Extra: dev
-Requires-Dist: beautifulsoup4>=4.12.0; extra == 'dev'
-Requires-Dist: grpcio-tools>=1.60.0; extra == 'dev'
-Requires-Dist: mypy>=1.8.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
-Requires-Dist: pytest-grpc-aio>=0.3.0; extra == 'dev'
-Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.1.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# cmdop
-
-**Any machine. One API.**
-
-```python
-from cmdop import CMDOPClient
-
-with CMDOPClient.remote(api_key="cmd_xxx") as server:
-    server.terminal.execute("docker restart app")
-    server.files.write("/etc/nginx/nginx.conf", new_config)
-    logs = server.files.read("/var/log/app.log")
-```
-
-No SSH. No VPN. No open ports.
-
----
-
-## How
-
-```
-Your Code ──── Cloud Relay ──── Agent (on server)
-                    │
-        Outbound only, works through any NAT/firewall
-```
-
-Agent connects out. Your code connects to relay. Done.
-
----
-
-## Install
-
-```bash
-pip install cmdop
-```
-
-```python
-from cmdop import CMDOPClient, AsyncCMDOPClient
-
-# Remote (via cloud relay)
-with CMDOPClient.remote(api_key="cmd_xxx") as client:
-    client.files.list("/home")
-
-# Local (direct IPC)
-with CMDOPClient.local() as client:
-    client.terminal.execute("ls -la")
-
-# Async
-async with AsyncCMDOPClient.remote(api_key="cmd_xxx") as client:
-    await client.files.read("/etc/hostname")
-```
-
----
-
-## Terminal
-
-```python
-session = server.terminal.create()
-server.terminal.send_input(session.session_id, "kubectl get pods\n")
-output = server.terminal.get_history(session.session_id)
-```
-
-| Method | Description |
-|--------|-------------|
-| `create(shell)` | Start session |
-| `send_input(id, data)` | Send commands |
-| `get_history(id)` | Get output |
-| `resize(id, cols, rows)` | Resize |
-| `send_signal(id, signal)` | SIGINT/SIGTERM |
-| `close(id)` | End session |
-
-## Files
-
-```python
-server.files.list("/var/log")
-server.files.read("/etc/nginx/nginx.conf")
-server.files.write("/tmp/config.json", b'{"key": "value"}')
-```
-
-| Method | Description |
-|--------|-------------|
-| `list(path)` | List dir |
-| `read(path)` | Read file |
-| `write(path, content)` | Write file |
-| `delete(path)` | Delete |
-| `copy/move(src, dst)` | Copy/Move |
-| `mkdir(path)` | Create dir |
-| `info(path)` | Metadata |
-
-## Agent
-
-```python
-from pydantic import BaseModel
-
-class Health(BaseModel):
-    status: str
-    cpu: float
-    issues: list[str]
-
-result = server.agent.run("Check server health", output_schema=Health)
-health: Health = result.output  # Typed!
-```
-
----
-
-## Browser
-
-Capability-based API for browser automation.
-
-```python
-from cmdop.services.browser.models import WaitUntil
-
-with client.browser.create_session() as s:
-    s.navigate("https://shop.com/products", wait_until=WaitUntil.NETWORKIDLE)
-    s.dom.close_modal()  # Close popups
-
-    # BeautifulSoup parsing
-    soup = s.dom.soup()  # SoupWrapper with chainable API
-    for item in soup.select(".product"):
-        title = item.select_one("h2").text()
-        price = item.attr("data-price")
-
-    # Scrolling with random delays
-    for _ in range(10):
-        soup = s.dom.soup(".listings")
-        s.scroll.js("down", 700)
-        s.timing.random(0.8, 1.5)
-
-    # Click with cursor movement
-    s.click("button.buy", move_cursor=True)
-
-    # Click all "See more" buttons
-    s.input.click_all("See more")
-
-    # Mouse operations
-    s.input.mouse_move(500, 300)
-    s.input.hover(".tooltip-trigger")
-
-    # JS fetch (bypass CORS, inherit cookies)
-    data = s.fetch.json("/api/items")
-```
-
-### Core Methods (on session)
-
-| Method | Description |
-|--------|-------------|
-| `navigate(url, wait_until)` | Go to URL (wait_until: LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT) |
-| `click(selector, move_cursor)` | Click element |
-| `type(selector, text)` | Type text |
-| `wait_for(selector)` | Wait for element |
-| `execute_script(js)` | Run JavaScript |
-| `screenshot()` | PNG bytes |
-| `get_state()` | URL + title |
-| `get_page_info()` | Full page info |
-| `get/set_cookies()` | Cookie management |
-
-### Capabilities
-
-**`session.scroll`** - Scrolling
-| Method | Description |
-|--------|-------------|
-| `js(dir, amount)` | JS scroll (works on complex sites) |
-| `native(dir, amount)` | Browser API scroll |
-| `to_bottom()` | Scroll to page bottom |
-| `to_element(selector)` | Scroll element into view |
-| `info()` | Get scroll position |
-| `infinite(extract_fn)` | Smart infinite scroll with extraction |
-
-**`session.input`** - Input operations
-| Method | Description |
-|--------|-------------|
-| `click_js(selector)` | JS click (reliable) |
-| `click_all(text, role)` | Click all matching elements |
-| `key(key, selector)` | Press keyboard key |
-| `hover(selector)` | Hover over element (native) |
-| `hover_js(selector)` | Hover via JS |
-| `mouse_move(x, y)` | Move cursor to coordinates |
-
-**`session.timing`** - Delays
-| Method | Description |
-|--------|-------------|
-| `wait(ms)` | Wait milliseconds |
-| `seconds(n)` | Wait seconds |
-| `random(min, max)` | Random delay |
-| `timeout(fn, sec, cleanup)` | Run with timeout |
-
-**`session.dom`** - DOM operations
-| Method | Description |
-|--------|-------------|
-| `html(selector)` | Get HTML |
-| `text(selector)` | Get text content |
-| `soup(selector)` | → SoupWrapper |
-| `parse(html)` | → BeautifulSoup |
-| `extract(selector, attr)` | Get text/attr list |
-| `select(selector, value)` | Dropdown select |
-| `close_modal()` | Close dialogs |
-
-**`session.fetch`** - HTTP from browser context
-| Method | Description |
-|--------|-------------|
-| `json(url)` | Fetch JSON |
-| `all(requests)` | Parallel fetch |
-| `execute(js_code)` | Custom JS fetch code |
-
-**`session.network`** - Network capture (v2.19.0)
-| Method | Description |
-|--------|-------------|
-| `enable(max_exchanges)` | Start capturing HTTP traffic |
-| `disable()` | Stop capturing |
-| `get_all()` | Get all captured exchanges |
-| `filter(url_pattern, methods, status_codes)` | Filter exchanges |
-| `last(url_pattern)` | Get most recent matching exchange |
-| `api_calls(url_pattern)` | Get XHR/Fetch calls matching pattern |
-| `last_json(url_pattern)` | Get JSON body from last matching response |
-| `wait_for(url_pattern, timeout_ms)` | Wait for matching request |
-| `stats()` | Capture statistics |
-| `export_har()` | Export to HAR format |
-| `clear()` | Clear captured data |
-
-```python
-# Example: Intercept API responses
-from cmdop.services.browser.models import WaitUntil
-
-with client.browser.create_session() as s:
-    s.network.enable()
-    s.navigate("https://app.example.com", wait_until=WaitUntil.NETWORKIDLE)
-
-    # Get last API response
-    api = s.network.last("/api/data")
-    data = api.json_body()
-
-    # Filter by criteria
-    posts = s.network.filter(
-        url_pattern="/api/posts",
-        methods=["GET"],
-        status_codes=[200],
-    )
-
-    s.network.disable()
-```
-
-## SDKBaseModel
-
-Auto-cleaning Pydantic model for scraped data:
-
-```python
-from cmdop import SDKBaseModel
-
-class Product(SDKBaseModel):
-    __base_url__ = "https://shop.com"
-    name: str = ""    # "  iPhone 15  \n" → "iPhone 15"
-    price: int = 0    # "$1,299.00" → 1299
-    rating: float = 0 # "4.5 stars" → 4.5
-    url: str = ""     # "/p/123" → "https://shop.com/p/123"
-
-products = Product.from_list(raw["items"])  # Auto dedupe + filter
-```
-
----
-
-## Utilities
-
-**Logging:**
-```python
-from cmdop import get_logger
-log = get_logger(__name__)
-log.info("Starting")  # Rich console + auto file logging
-```
-
-**TOON Format (30-50% token savings):**
-```python
-from cmdop import json_to_toon, JsonCleaner
-toon = json_to_toon({"name": "Alice", "age": 25})
-# → "name: Alice\nage: 25"
-```
-
----
-
-## Requirements
-
-- Python 3.10+
-- CMDOP agent on target
-
-## Links
-
-[cmdop.com](https://cmdop.com)
-
-## License
-
-MIT