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

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/__init__.py

@@ -0,0 +1,5 @@
+"""Browser service layer (gRPC)."""
+
+from .sync import BrowserService
+
+__all__ = ["BrowserService"]

cmdop/services/browser/service/aio.py

@@ -0,0 +1,30 @@
+"""Async browser service stub.
+
+Async browser is not implemented yet. Use sync BrowserService instead.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NoReturn
+
+if TYPE_CHECKING:
+    from cmdop.transport.base import BaseTransport
+
+
+class AsyncBrowserService:
+    """
+    Async browser service stub.
+
+    Not implemented yet. Use sync CMDOPClient.browser instead.
+    """
+
+    def __init__(self, transport: BaseTransport) -> None:
+        self._transport = transport
+
+    def _not_implemented(self) -> NoReturn:
+        raise NotImplementedError(
+            "Async browser is not implemented. Use sync CMDOPClient.browser instead."
+        )
+
+    async def create_session(self, *args, **kwargs) -> NoReturn:
+        self._not_implemented()

cmdop/services/browser/{sync/service.py → service/sync.py}

@@ -6,8 +6,8 @@ import json
 from typing import TYPE_CHECKING, Any
 
 from cmdop.services.base import BaseService
-from cmdop.services.browser.base.service import BaseServiceMixin, cookie_to_pb, pb_to_cookie
-from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, raise_browser_error
+from cmdop.services.browser.service._helpers import BaseServiceMixin, cookie_to_pb, pb_to_cookie
+from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, WaitUntil, raise_browser_error
 
 if TYPE_CHECKING:
     from cmdop.transport.base import BaseTransport
@@ -47,7 +47,7 @@ class BrowserService(BaseService, BaseServiceMixin):
         height: int = 800,
     ) -> "BrowserSession":
         from cmdop._generated.rpc_messages.browser_pb2 import BrowserCreateSessionRequest
-        from cmdop.services.browser.sync.session import BrowserSession
+        from cmdop.services.browser.session import BrowserSession
 
         request = BrowserCreateSessionRequest(
             provider=provider,
@@ -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

@@ -0,0 +1,194 @@
+"""Browser session with capability-based API."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+
+from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, WaitUntil
+
+from .capabilities import (
+    ScrollCapability,
+    InputCapability,
+    TimingCapability,
+    DOMCapability,
+    FetchCapability,
+    NetworkCapability,
+)
+
+if TYPE_CHECKING:
+    from cmdop.services.browser.service.sync import BrowserService
+
+
+class BrowserSession:
+    """Browser session with grouped capabilities.
+
+    Core methods (on session directly):
+        session.navigate(url)
+        session.click(selector)
+        session.type(selector, text)
+        session.wait_for(selector)
+        session.execute_script(js)
+
+    Capabilities (grouped by function):
+        session.scroll.js("down", 500)
+        session.scroll.to_bottom()
+        session.input.click_js(selector)
+        session.input.key("Escape")
+        session.timing.wait(1000)
+        session.dom.soup()
+        session.fetch.json("/api/data")
+
+    Usage:
+        with service.create_session() as session:
+            session.navigate("https://example.com")
+            session.scroll.js("down", 500)
+            session.input.click_js(".button")
+    """
+
+    __slots__ = (
+        "_service",
+        "_session_id",
+        "_scroll",
+        "_input",
+        "_timing",
+        "_dom",
+        "_fetch",
+        "_network",
+    )
+
+    def __init__(self, service: "BrowserService", session_id: str) -> None:
+        self._service = service
+        self._session_id = session_id
+        self._scroll: ScrollCapability | None = None
+        self._input: InputCapability | None = None
+        self._timing: TimingCapability | None = None
+        self._dom: DOMCapability | None = None
+        self._fetch: FetchCapability | None = None
+        self._network: NetworkCapability | None = None
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    # === Capabilities (lazy init) ===
+
+    @property
+    def scroll(self) -> ScrollCapability:
+        """Scroll: js(), to_bottom(), to_element(), info(), native(), collect()"""
+        if self._scroll is None:
+            self._scroll = ScrollCapability(self)
+        return self._scroll
+
+    @property
+    def input(self) -> InputCapability:
+        """Input: click_js(), key(), click_all(), hover(), hover_js()"""
+        if self._input is None:
+            self._input = InputCapability(self)
+        return self._input
+
+    @property
+    def timing(self) -> TimingCapability:
+        """Timing: wait(), seconds(), random(), timeout()"""
+        if self._timing is None:
+            self._timing = TimingCapability(self)
+        return self._timing
+
+    @property
+    def dom(self) -> DOMCapability:
+        """DOM: html(), text(), soup(), parse(), select(), close_modal(), extract()"""
+        if self._dom is None:
+            self._dom = DOMCapability(self)
+        return self._dom
+
+    @property
+    def fetch(self) -> FetchCapability:
+        """Fetch: json(), all(), execute()"""
+        if self._fetch is None:
+            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
+
+    # === Core Methods ===
+
+    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."""
+        self._service.click(self._session_id, selector, timeout_ms, move_cursor)
+
+    def type(self, selector: str, text: str, human_like: bool = False, clear_first: bool = True) -> None:
+        """Type text into element."""
+        self._service.type(self._session_id, selector, text, human_like, clear_first)
+
+    def wait_for(self, selector: str, timeout_ms: int = 30000) -> bool:
+        """Wait for element to appear."""
+        return self._service.wait_for(self._session_id, selector, timeout_ms)
+
+    def execute_script(self, script: str) -> str:
+        """Execute raw JavaScript."""
+        return self._service.execute_script(self._session_id, script)
+
+    # === State ===
+
+    def screenshot(self, full_page: bool = False) -> bytes:
+        """Take screenshot."""
+        return self._service.screenshot(self._session_id, full_page)
+
+    def get_state(self) -> BrowserState:
+        """Get browser state."""
+        return self._service.get_state(self._session_id)
+
+    def get_cookies(self, domain: str = "") -> list[BrowserCookie]:
+        """Get cookies."""
+        return self._service.get_cookies(self._session_id, domain)
+
+    def set_cookies(self, cookies: list[BrowserCookie | dict]) -> None:
+        """Set cookies."""
+        self._service.set_cookies(self._session_id, cookies)
+
+    def get_page_info(self) -> PageInfo:
+        """Get page info."""
+        return self._service.get_page_info(self._session_id)
+
+    # === Internal ===
+
+    def _call_service(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        """Call service method (used by capabilities)."""
+        return getattr(self._service, method)(self._session_id, *args, **kwargs)
+
+    # === Context Manager ===
+
+    def close(self) -> None:
+        """Close session."""
+        self._service.close_session(self._session_id)
+
+    def __enter__(self) -> "BrowserSession":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()