cmdop 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

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")

cmdop/services/browser/models.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from enum import Enum
 from typing import Any
 
 from pydantic import BaseModel
@@ -14,6 +15,25 @@ from cmdop.exceptions import (
 )
 
 
+class WaitUntil(str, Enum):
+    """Wait strategy for navigation.
+
+    Determines when navigation is considered complete.
+    """
+
+    LOAD = "load"
+    """Wait for load event (default, not recommended for SPA)."""
+
+    DOMCONTENTLOADED = "domcontentloaded"
+    """Wait for DOMContentLoaded event."""
+
+    NETWORKIDLE = "networkidle"
+    """Wait until no network activity for 500ms (best for SPA)."""
+
+    COMMIT = "commit"
+    """Return immediately after navigation commits (fastest)."""
+
+
 def raise_browser_error(error: str, operation: str, **context: Any) -> None:
     """Raise appropriate browser exception based on error message."""
     error_lower = error.lower()
@@ -115,3 +135,86 @@ class InfiniteScrollResult(BaseModel):
     at_bottom: bool = False
     total_seen: int = 0
     error: str | None = None
+
+
+# =============================================================================
+# Network Capture Models (v2.19.0)
+# =============================================================================
+
+
+class NetworkRequest(BaseModel):
+    """Captured HTTP request."""
+
+    url: str = ""
+    method: str = "GET"
+    headers: dict[str, str] = {}
+    body: bytes = b""
+    content_type: str = ""
+    resource_type: str = ""  # document, script, xhr, fetch, image, etc.
+
+
+class NetworkResponse(BaseModel):
+    """Captured HTTP response."""
+
+    status: int = 0
+    status_text: str = ""
+    headers: dict[str, str] = {}
+    body: bytes = b""
+    content_type: str = ""
+    size: int = 0
+    from_cache: bool = False
+
+
+class NetworkTiming(BaseModel):
+    """Request timing data."""
+
+    started_at_ms: int = 0
+    ended_at_ms: int = 0
+    duration_ms: int = 0
+    wait_time_ms: int = 0  # Time to first byte
+    receive_time_ms: int = 0  # Time to download body
+
+
+class NetworkExchange(BaseModel):
+    """Complete request/response exchange."""
+
+    id: str = ""
+    request: NetworkRequest = NetworkRequest()
+    response: NetworkResponse | None = None
+    timing: NetworkTiming = NetworkTiming()
+    error: str = ""
+    frame_id: str = ""
+    initiator: str = ""  # URL or script that initiated
+
+    def json_body(self) -> Any:
+        """Parse response body as JSON."""
+        import json
+        if self.response and self.response.body:
+            return json.loads(self.response.body)
+        return None
+
+    def text_body(self) -> str:
+        """Get response body as text."""
+        if self.response and self.response.body:
+            return self.response.body.decode("utf-8", errors="replace")
+        return ""
+
+
+class NetworkStats(BaseModel):
+    """Network capture statistics."""
+
+    enabled: bool = False
+    total_captured: int = 0
+    total_errors: int = 0
+    total_bytes: int = 0
+    average_duration_ms: int = 0
+
+
+class NetworkFilter(BaseModel):
+    """Filter for querying captured exchanges."""
+
+    url_pattern: str = ""
+    methods: list[str] = []
+    status_codes: list[int] = []
+    resource_types: list[str] = []
+    limit: int = 0

cmdop/services/browser/service/sync.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Any
 
 from cmdop.services.base import BaseService
 from cmdop.services.browser.service._helpers import BaseServiceMixin, cookie_to_pb, pb_to_cookie
-from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, raise_browser_error
+from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, WaitUntil, raise_browser_error
 
 if TYPE_CHECKING:
     from cmdop.transport.base import BaseTransport
@@ -75,11 +75,31 @@ class BrowserService(BaseService, BaseServiceMixin):
 
     # === Navigation & Interaction ===
 
-    def navigate(self, session_id: str, url: str, timeout_ms: int = 30000) -> str:
-        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNavigateRequest
+    def navigate(
+        self,
+        session_id: str,
+        url: str,
+        timeout_ms: int = 30000,
+        wait_until: WaitUntil = WaitUntil.LOAD,
+    ) -> str:
+        from cmdop._generated.rpc_messages.browser_pb2 import (
+            BrowserNavigateRequest,
+            WaitUntil as PbWaitUntil,
+        )
+
+        # Convert Python enum to proto enum
+        pb_wait_until = {
+            WaitUntil.LOAD: PbWaitUntil.WAIT_LOAD,
+            WaitUntil.DOMCONTENTLOADED: PbWaitUntil.WAIT_DOMCONTENTLOADED,
+            WaitUntil.NETWORKIDLE: PbWaitUntil.WAIT_NETWORKIDLE,
+            WaitUntil.COMMIT: PbWaitUntil.WAIT_COMMIT,
+        }.get(wait_until, PbWaitUntil.WAIT_LOAD)
 
         request = BrowserNavigateRequest(
-            browser_session_id=session_id, url=url, timeout_ms=timeout_ms
+            browser_session_id=session_id,
+            url=url,
+            timeout_ms=timeout_ms,
+            wait_until=pb_wait_until,
         )
         response = self._call_sync(self._get_stub.BrowserNavigate, request)
 
@@ -434,3 +454,183 @@ class BrowserService(BaseService, BaseServiceMixin):
             "items": json.loads(response.items_json) if response.items_json else [],
             "count": response.count,
         }
+
+    # === Network Capture (v2.19.0) ===
+
+    def network_enable(
+        self, session_id: str, max_exchanges: int = 1000, max_response_size: int = 10_000_000
+    ) -> None:
+        """Enable network capture."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkEnableRequest
+
+        request = BrowserNetworkEnableRequest(
+            browser_session_id=session_id,
+            max_exchanges=max_exchanges,
+            max_response_size=max_response_size,
+        )
+        response = self._call_sync(self._get_stub.BrowserNetworkEnable, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkEnable failed: {response.error}")
+
+    def network_disable(self, session_id: str) -> None:
+        """Disable network capture."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkDisableRequest
+
+        request = BrowserNetworkDisableRequest(browser_session_id=session_id)
+        response = self._call_sync(self._get_stub.BrowserNetworkDisable, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkDisable failed: {response.error}")
+
+    def network_get_exchanges(
+        self,
+        session_id: str,
+        url_pattern: str = "",
+        methods: list[str] | None = None,
+        status_codes: list[int] | None = None,
+        resource_types: list[str] | None = None,
+        limit: int = 0,
+    ) -> dict:
+        """Get captured exchanges."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkGetExchangesRequest
+
+        request = BrowserNetworkGetExchangesRequest(
+            browser_session_id=session_id,
+            url_pattern=url_pattern,
+            methods=methods or [],
+            status_codes=status_codes or [],
+            resource_types=resource_types or [],
+            limit=limit,
+        )
+        response = self._call_sync(self._get_stub.BrowserNetworkGetExchanges, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkGetExchanges failed: {response.error}")
+
+        return {
+            "exchanges": [self._pb_to_exchange(e) for e in response.exchanges],
+            "count": response.count,
+        }
+
+    def network_get_exchange(self, session_id: str, exchange_id: str) -> dict:
+        """Get specific exchange by ID."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkGetExchangeRequest
+
+        request = BrowserNetworkGetExchangeRequest(
+            browser_session_id=session_id, exchange_id=exchange_id
+        )
+        response = self._call_sync(self._get_stub.BrowserNetworkGetExchange, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkGetExchange failed: {response.error}")
+
+        return {"exchange": self._pb_to_exchange(response.exchange) if response.exchange else None}
+
+    def network_get_last(self, session_id: str, url_pattern: str = "") -> dict:
+        """Get most recent exchange matching URL pattern."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkGetLastRequest
+
+        request = BrowserNetworkGetLastRequest(
+            browser_session_id=session_id, url_pattern=url_pattern
+        )
+        response = self._call_sync(self._get_stub.BrowserNetworkGetLast, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkGetLast failed: {response.error}")
+
+        return {"exchange": self._pb_to_exchange(response.exchange) if response.exchange else None}
+
+    def network_clear(self, session_id: str) -> None:
+        """Clear all captured exchanges."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkClearRequest
+
+        request = BrowserNetworkClearRequest(browser_session_id=session_id)
+        response = self._call_sync(self._get_stub.BrowserNetworkClear, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkClear failed: {response.error}")
+
+    def network_stats(self, session_id: str) -> dict:
+        """Get capture statistics."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkStatsRequest
+
+        request = BrowserNetworkStatsRequest(browser_session_id=session_id)
+        response = self._call_sync(self._get_stub.BrowserNetworkStats, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkStats failed: {response.error}")
+
+        return {
+            "enabled": response.enabled,
+            "total_captured": response.total_captured,
+            "total_errors": response.total_errors,
+            "total_bytes": response.total_bytes,
+            "average_duration_ms": response.average_duration_ms,
+        }
+
+    def network_export_har(
+        self,
+        session_id: str,
+        url_pattern: str = "",
+        methods: list[str] | None = None,
+        status_codes: list[int] | None = None,
+        resource_types: list[str] | None = None,
+    ) -> dict:
+        """Export captured exchanges to HAR format."""
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNetworkExportHARRequest
+
+        request = BrowserNetworkExportHARRequest(
+            browser_session_id=session_id,
+            url_pattern=url_pattern,
+            methods=methods or [],
+            status_codes=status_codes or [],
+            resource_types=resource_types or [],
+        )
+        response = self._call_sync(self._get_stub.BrowserNetworkExportHAR, request)
+
+        if not response.success:
+            raise RuntimeError(f"NetworkExportHAR failed: {response.error}")
+
+        return {"har_data": response.har_data}
+
+    def _pb_to_exchange(self, pb: Any) -> dict:
+        """Convert protobuf exchange to dict."""
+        result: dict[str, Any] = {
+            "id": pb.id,
+            "error": pb.error,
+            "frame_id": pb.frame_id,
+            "initiator": pb.initiator,
+        }
+
+        if pb.request:
+            result["request"] = {
+                "url": pb.request.url,
+                "method": pb.request.method,
+                "headers": dict(pb.request.headers),
+                "body": pb.request.body,
+                "content_type": pb.request.content_type,
+                "resource_type": pb.request.resource_type,
+            }
+
+        if pb.response:
+            result["response"] = {
+                "status": pb.response.status,
+                "status_text": pb.response.status_text,
+                "headers": dict(pb.response.headers),
+                "body": pb.response.body,
+                "content_type": pb.response.content_type,
+                "size": pb.response.size,
+                "from_cache": pb.response.from_cache,
+            }
+
+        if pb.timing:
+            result["timing"] = {
+                "started_at_ms": pb.timing.started_at_ms,
+                "ended_at_ms": pb.timing.ended_at_ms,
+                "duration_ms": pb.timing.duration_ms,
+                "wait_time_ms": pb.timing.wait_time_ms,
+                "receive_time_ms": pb.timing.receive_time_ms,
+            }
+
+        return result

cmdop/services/browser/session.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
-from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo
+from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, WaitUntil
 
 from .capabilities import (
     ScrollCapability,
@@ -11,6 +11,8 @@ from .capabilities import (
     TimingCapability,
     DOMCapability,
     FetchCapability,
+    NetworkCapability,
+    VisualCapability,
 )
 
 if TYPE_CHECKING:
@@ -51,6 +53,8 @@ class BrowserSession:
         "_timing",
         "_dom",
         "_fetch",
+        "_network",
+        "_visual",
     )
 
     def __init__(self, service: "BrowserService", session_id: str) -> None:
@@ -61,6 +65,8 @@ class BrowserSession:
         self._timing: TimingCapability | None = None
         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:
@@ -103,11 +109,43 @@ class BrowserSession:
             self._fetch = FetchCapability(self)
         return self._fetch
 
+    @property
+    def network(self) -> NetworkCapability:
+        """Network: enable(), disable(), get_all(), filter(), last(), clear(), stats()"""
+        if self._network is None:
+            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(self, url: str, timeout_ms: int = 30000) -> str:
-        """Navigate to URL. Returns final URL."""
-        return self._service.navigate(self._session_id, url, timeout_ms)
+    def navigate(
+        self,
+        url: str,
+        timeout_ms: int = 30000,
+        wait_until: WaitUntil = WaitUntil.LOAD,
+    ) -> str:
+        """Navigate to URL with specified wait strategy.
+
+        Args:
+            url: URL to navigate to.
+            timeout_ms: Timeout in milliseconds.
+            wait_until: When navigation is considered complete:
+                - WaitUntil.LOAD: Wait for load event (default, slow for SPA)
+                - WaitUntil.DOMCONTENTLOADED: Wait for DOMContentLoaded event
+                - WaitUntil.NETWORKIDLE: Wait until network is idle (best for SPA)
+                - WaitUntil.COMMIT: Return immediately (fastest)
+
+        Returns:
+            Final URL after navigation (may differ due to redirects).
+        """
+        return self._service.navigate(self._session_id, url, timeout_ms, wait_until)
 
     def click(self, selector: str, timeout_ms: int = 5000, move_cursor: bool = False) -> None:
         """Click element by CSS selector."""