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

cmdop/services/browser/capabilities/scroll.py

@@ -0,0 +1,147 @@
+"""Scroll capability."""
+
+import time
+from typing import Any, Callable
+
+from cmdop.services.browser.js import (
+    build_scroll_js,
+    build_scroll_to_bottom_js,
+    build_get_scroll_info_js,
+    build_infinite_scroll_js,
+)
+from cmdop.services.browser.models import ScrollResult, ScrollInfo, InfiniteScrollResult
+
+from ._base import BaseCapability
+from ._helpers import to_dict
+
+
+class ScrollCapability(BaseCapability):
+    """Scroll operations.
+
+    Usage:
+        session.scroll.js("down", 500)
+        session.scroll.to_bottom()
+        info = session.scroll.info()
+    """
+
+    def js(
+        self,
+        direction: str = "down",
+        amount: int = 500,
+        selector: str | None = None,
+        smooth: bool = True,
+        human_like: bool = False,
+        container: str | None = None,
+    ) -> ScrollResult:
+        """Scroll using JavaScript. Use when native scroll doesn't work."""
+        js = build_scroll_js(direction, amount, selector, smooth, human_like, container)
+        data = to_dict(self._js(js))
+        return ScrollResult(
+            success=data.get("success", False),
+            scroll_y=int(data.get("scrollY", 0)),
+            scrolled_by=int(data.get("scrolledBy", 0)),
+            at_bottom=data.get("atBottom", False),
+            error=data.get("error"),
+        )
+
+    def to_bottom(self) -> ScrollResult:
+        """Scroll to page bottom."""
+        data = to_dict(self._js(build_scroll_to_bottom_js()))
+        return ScrollResult(
+            success=data.get("success", False),
+            scroll_y=int(data.get("scrollY", 0)),
+            scrolled_by=int(data.get("scrolledBy", 0)),
+            at_bottom=True,
+        )
+
+    def to_element(self, selector: str) -> ScrollResult:
+        """Scroll element into view."""
+        return self.js(selector=selector)
+
+    def info(self) -> ScrollInfo:
+        """Get scroll position and page dimensions."""
+        data = to_dict(self._js(build_get_scroll_info_js()))
+        return ScrollInfo(
+            scroll_x=int(data.get("scrollX", 0)),
+            scroll_y=int(data.get("scrollY", 0)),
+            page_height=int(data.get("pageHeight", 0)),
+            page_width=int(data.get("pageWidth", 0)),
+            viewport_height=int(data.get("viewportHeight", 0)),
+            viewport_width=int(data.get("viewportWidth", 0)),
+            at_bottom=data.get("atBottom", False),
+            at_top=data.get("atTop", True),
+        )
+
+    def native(
+        self,
+        direction: str = "down",
+        amount: int = 500,
+        selector: str | None = None,
+        smooth: bool = True,
+    ) -> ScrollResult:
+        """Scroll using native browser API."""
+        data = self._call("scroll", direction, amount, selector, smooth)
+        return ScrollResult(
+            success=True,
+            scroll_y=data.get("scroll_y", 0),
+            scrolled_by=data.get("scrolled_by", 0),
+            at_bottom=data.get("at_bottom", False),
+        )
+
+    def collect(
+        self,
+        seen_keys: set[str],
+        key_selector: str = "a[href]",
+        key_attr: str = "href",
+        container_selector: str = "body",
+    ) -> InfiniteScrollResult:
+        """Extract new keys for infinite scroll patterns. Updates seen_keys in-place."""
+        js = build_infinite_scroll_js(list(seen_keys), key_selector, key_attr, container_selector)
+        data = to_dict(self._js(js))
+        new_keys = data.get("new_keys", [])
+        seen_keys.update(new_keys)
+        return InfiniteScrollResult(
+            new_keys=new_keys,
+            at_bottom=data.get("at_bottom", False),
+            total_seen=data.get("total_seen", len(seen_keys)),
+            error=data.get("error"),
+        )
+
+    def infinite(
+        self,
+        extract_fn: Callable[[], list[Any]],
+        limit: int = 100,
+        max_scrolls: int = 50,
+        max_no_new: int = 3,
+        scroll_amount: int = 800,
+        delay: float = 1.0,
+    ) -> list[Any]:
+        """Smart infinite scroll with extraction.
+
+        Args:
+            extract_fn: Returns new items each call (dedup is caller's job)
+            limit: Stop after this many items
+            max_scrolls: Max scroll attempts
+            max_no_new: Stop after N scrolls with no new items
+            scroll_amount: Pixels per scroll
+            delay: Seconds between scrolls
+        """
+        items: list[Any] = []
+        no_new = 0
+
+        for _ in range(max_scrolls):
+            new = extract_fn()
+            if new:
+                items.extend(new)
+                no_new = 0
+                if len(items) >= limit:
+                    break
+            else:
+                no_new += 1
+                if no_new >= max_no_new:
+                    break
+
+            self.js("down", scroll_amount)
+            time.sleep(delay)
+
+        return items[:limit]

cmdop/services/browser/capabilities/timing.py

@@ -0,0 +1,66 @@
+"""Timing capability."""
+
+import random
+import time
+import threading
+from typing import Callable, TypeVar
+
+from ._base import BaseCapability
+
+T = TypeVar("T")
+
+
+class TimingCapability(BaseCapability):
+    """Timing operations: wait, delays, timeouts.
+
+    Usage:
+        session.timing.wait(1000)
+        session.timing.random(0.5, 2.0)
+        result, ok = session.timing.timeout(lambda: slow_fn(), 30)
+    """
+
+    def wait(self, ms: int, jitter: float = 0.1) -> None:
+        """Wait milliseconds with jitter (±10% by default)."""
+        actual = (ms / 1000) * (1 + random.uniform(-jitter, jitter))
+        time.sleep(actual)
+
+    def seconds(self, sec: float, jitter: float = 0.1) -> None:
+        """Wait seconds with jitter."""
+        self.wait(int(sec * 1000), jitter)
+
+    def random(self, min_sec: float = 0.5, max_sec: float = 1.5) -> None:
+        """Wait random time between min and max seconds."""
+        time.sleep(min_sec + random.random() * (max_sec - min_sec))
+
+    def timeout(
+        self,
+        fn: Callable[[], T],
+        seconds: float = 60.0,
+        on_timeout: Callable[[], None] | None = None,
+    ) -> tuple[T | None, bool]:
+        """Run function with timeout. Returns (result, success)."""
+        result: list[T | None] = [None]
+        error: list[Exception | None] = [None]
+        done = threading.Event()
+
+        def run():
+            try:
+                result[0] = fn()
+            except Exception as e:
+                error[0] = e
+            finally:
+                done.set()
+
+        threading.Thread(target=run, daemon=True).start()
+
+        if done.wait(timeout=seconds):
+            if error[0]:
+                raise error[0]
+            return result[0], True
+
+        if on_timeout:
+            try:
+                on_timeout()
+            except Exception:
+                pass
+        return None, False

cmdop/services/browser/js/__init__.py

@@ -7,29 +7,30 @@ This module provides JavaScript code generators for common browser operations:
 - Interaction: Hover, select, modals
 """
 
-from cmdop.services.browser.js.core import (
+from .core import (
     parse_json_result,
     build_async_js,
 )
 
-from cmdop.services.browser.js.fetch import (
+from .fetch import (
     build_fetch_js,
     build_fetch_all_js,
 )
 
-from cmdop.services.browser.js.scroll import (
+from .scroll import (
     build_scroll_js,
     build_scroll_to_bottom_js,
     build_infinite_scroll_js,
     build_get_scroll_info_js,
 )
 
-from cmdop.services.browser.js.interaction import (
+from .interaction import (
     build_hover_js,
     build_select_js,
     build_close_modal_js,
     build_click_all_by_text_js,
     build_press_key_js,
+    build_click_js,
 )
 
 __all__ = [
@@ -50,4 +51,5 @@ __all__ = [
     "build_close_modal_js",
     "build_click_all_by_text_js",
     "build_press_key_js",
+    "build_click_js",
 ]

cmdop/services/browser/js/interaction.py

@@ -178,3 +178,37 @@ def build_click_all_by_text_js(text: str, role: str = "button") -> str:
         return JSON.stringify({{ clicked: clicked }});
     }})()
     """
+
+
+def build_click_js(selector: str, scroll_into_view: bool = True) -> str:
+    """
+    Build JS to click element via JavaScript (more reliable than CDP click).
+
+    This is useful when native CDP click hangs or doesn't work properly.
+    Uses document.querySelector to find element and calls .click() directly.
+
+    Args:
+        selector: CSS selector for the element to click
+        scroll_into_view: If True, scroll element into view before clicking (default: True)
+
+    Returns:
+        JS code that returns { success: true/false, error?: string }
+    """
+    scroll_code = 'el.scrollIntoView({block: "center", behavior: "instant"});' if scroll_into_view else ''
+    selector_escaped = json.dumps(selector)
+
+    return f"""
+    (function() {{
+        const el = document.querySelector({selector_escaped});
+        if (!el) {{
+            return JSON.stringify({{ success: false, error: 'Element not found' }});
+        }}
+        try {{
+            {scroll_code}
+            el.click();
+            return JSON.stringify({{ success: true }});
+        }} catch (e) {{
+            return JSON.stringify({{ success: false, error: e.message }});
+        }}
+    }})()
+    """

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,7 +6,7 @@ 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.service._helpers import BaseServiceMixin, cookie_to_pb, pb_to_cookie
 from cmdop.services.browser.models import BrowserCookie, BrowserState, PageInfo, raise_browser_error
 
 if TYPE_CHECKING:
@@ -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,
@@ -88,11 +88,16 @@ class BrowserService(BaseService, BaseServiceMixin):
 
         return response.final_url
 
-    def click(self, session_id: str, selector: str, timeout_ms: int = 5000) -> None:
+    def click(
+        self, session_id: str, selector: str, timeout_ms: int = 5000, move_cursor: bool = False
+    ) -> None:
         from cmdop._generated.rpc_messages.browser_pb2 import BrowserClickRequest
 
         request = BrowserClickRequest(
-            browser_session_id=session_id, selector=selector, timeout_ms=timeout_ms
+            browser_session_id=session_id,
+            selector=selector,
+            timeout_ms=timeout_ms,
+            move_cursor=move_cursor,
         )
         response = self._call_sync(self._get_stub.BrowserClick, request)
 

cmdop/services/browser/session.py

@@ -0,0 +1,166 @@
+"""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
+
+from .capabilities import (
+    ScrollCapability,
+    InputCapability,
+    TimingCapability,
+    DOMCapability,
+    FetchCapability,
+)
+
+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",
+    )
+
+    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
+
+    @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
+
+    # === 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 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()

{cmdop-0.1.20.dist-info → cmdop-0.1.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmdop
-Version: 0.1.20
+Version: 0.1.22
 Summary: Python SDK for CMDOP agent interaction
 Project-URL: Homepage, https://cmdop.com
 Project-URL: Documentation, https://cmdop.com
@@ -145,71 +145,100 @@ health: Health = result.output  # Typed!
 
 ## Browser
 
+Capability-based API for browser automation.
+
 ```python
-with client.browser.create_session() as b:
-    b.navigate("https://shop.com/products")
-    b.close_modal()  # Close popups
+with client.browser.create_session() as s:
+    s.navigate("https://shop.com/products")
+    s.dom.close_modal()  # Close popups
 
     # BeautifulSoup parsing
-    soup = b.soup()  # SoupWrapper with chainable API
+    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 = b.soup(".listings")
-        # ... parse ...
-        b.scroll("down", 700)
-        b.wait_random(0.8, 1.5)  # Random delay
+        soup = s.dom.soup(".listings")
+        s.scroll.js("down", 700)
+        s.timing.random(0.8, 1.5)
 
-    # Click with cursor movement (human-like)
-    b.click("button.buy", move_cursor=True)  # Moves cursor before clicking
+    # Click with cursor movement
+    s.click("button.buy", move_cursor=True)
 
     # Click all "See more" buttons
-    b.click_all_by_text("See more")
+    s.input.click_all("See more")
 
-    # Native mouse operations
-    b.mouse_move(500, 300)  # Smooth cursor movement
-    b.hover(".tooltip-trigger")  # Hover to reveal tooltip
+    # Mouse operations
+    s.input.mouse_move(500, 300)
+    s.input.hover(".tooltip-trigger")
 
     # JS fetch (bypass CORS, inherit cookies)
-    data = b.fetch_json("https://api.site.com/v1/items")
+    data = s.fetch.json("/api/items")
 ```
 
+### Core Methods (on session)
+
 | Method | Description |
 |--------|-------------|
 | `navigate(url)` | Go to URL |
-| `click(selector, move_cursor)` | Click element (optionally move cursor first) |
-| `click_all_by_text(text, role)` | Click all matching elements |
+| `click(selector, move_cursor)` | Click element |
 | `type(selector, text)` | Type text |
-| `wait_for(selector, ms)` | Wait for element |
-| `wait_seconds(n)` | Sleep |
-| `wait_random(min, max)` | Random sleep |
-| `extract(selector, attr)` | Get text/attr |
-| `get_html(selector)` | Get HTML |
-| `soup(selector)` | → SoupWrapper |
-| `parse_html(html)` | → BeautifulSoup |
-| `fetch_json(url)` | JS fetch → dict |
-| `fetch_all(urls)` | Parallel fetch |
-| `execute_js(code)` | Run async JS |
+| `wait_for(selector)` | Wait for element |
+| `execute_script(js)` | Run JavaScript |
 | `screenshot()` | PNG bytes |
-| `scroll(dir, amount, ...)` | Native scroll page |
-| `scroll_to(selector)` | Scroll element into view |
-| `get_scroll_info()` | Position + page size |
-| `get_page_info()` | Comprehensive page info |
-| `mouse_move(x, y, steps)` | Move cursor to coordinates |
-| `hover(selector)` | Hover over element |
+| `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 |
-| `press_key(key, selector)` | Press keyboard key |
-| `get/set_cookies()` | Cookie management |
 
-**scroll() parameters:**
-- `direction`: "up", "down", "left", "right"
-- `amount`: pixels to scroll
-- `smooth`: animate scroll (default True)
-- `selector`: scroll element into view (alternative to direction/amount)
+**`session.fetch`** - HTTP from browser context
+| Method | Description |
+|--------|-------------|
+| `json(url)` | Fetch JSON |
+| `all(requests)` | Parallel fetch |
+| `execute(method, url, ...)` | Custom request |
 
 ## SDKBaseModel