cmdop 0.1.21__tar.gz → 0.1.22__tar.gz

{cmdop-0.1.21 → cmdop-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmdop
-Version: 0.1.21
+Version: 0.1.22
 Summary: Python SDK for CMDOP agent interaction
 Project-URL: Homepage, https://cmdop.com
 Project-URL: Documentation, https://cmdop.com
@@ -145,91 +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 |
-| `select(selector, value)` | Dropdown select |
-| `close_modal()` | Close dialogs |
-| `press_key(key, selector)` | Press keyboard key |
+| `get_state()` | URL + title |
+| `get_page_info()` | Full page info |
 | `get/set_cookies()` | Cookie management |
-| `with_timeout(fn, sec, cleanup)` | Run with timeout, skip if hangs |
 
-**with_timeout() - Smart timeout for long operations:**
-```python
-# Sync
-result, ok = browser.with_timeout(
-    lambda: process_item(browser, item),
-    timeout_sec=60,
-    on_timeout=lambda: browser.press_key('Escape'),
-)
-if not ok:
-    print("Skipped - timed out")
+### Capabilities
 
-# Async
-result, ok = await browser.with_timeout(
-    process_item(browser, item),  # coroutine
-    timeout_sec=60,
-    on_timeout=lambda: browser.press_key('Escape'),
-)
-```
+**`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 |
 
-**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.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(method, url, ...)` | Custom request |
 
 ## SDKBaseModel
 

{cmdop-0.1.21 → cmdop-0.1.22}/README.md

@@ -104,91 +104,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 |
-| `select(selector, value)` | Dropdown select |
-| `close_modal()` | Close dialogs |
-| `press_key(key, selector)` | Press keyboard key |
+| `get_state()` | URL + title |
+| `get_page_info()` | Full page info |
 | `get/set_cookies()` | Cookie management |
-| `with_timeout(fn, sec, cleanup)` | Run with timeout, skip if hangs |
 
-**with_timeout() - Smart timeout for long operations:**
-```python
-# Sync
-result, ok = browser.with_timeout(
-    lambda: process_item(browser, item),
-    timeout_sec=60,
-    on_timeout=lambda: browser.press_key('Escape'),
-)
-if not ok:
-    print("Skipped - timed out")
+### Capabilities
 
-# Async
-result, ok = await browser.with_timeout(
-    process_item(browser, item),  # coroutine
-    timeout_sec=60,
-    on_timeout=lambda: browser.press_key('Escape'),
-)
-```
+**`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 |
 
-**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.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(method, url, ...)` | Custom request |
 
 ## SDKBaseModel
 

{cmdop-0.1.21 → cmdop-0.1.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cmdop"
-version = "0.1.21"
+version = "0.1.22"
 description = "Python SDK for CMDOP agent interaction"
 readme = "README.md"
 license = { text = "MIT" }

{cmdop-0.1.21 → cmdop-0.1.22}/src/cmdop/__init__.py

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

{cmdop-0.1.21 → cmdop-0.1.22}/src/cmdop/client.py

@@ -439,15 +439,9 @@ class AsyncCMDOPClient:
     @property
     def browser(self) -> AsyncBrowserService:
         """
-        Async browser service for direct programmatic control.
+        Async browser service (stub - not implemented).
 
-        Provides: create_session, navigate, click, type, extract, etc.
-
-        Example:
-            >>> async with client.browser.create_session() as session:
-            ...     await session.navigate("https://google.com")
-            ...     await session.type("input[name='q']", "Python")
-            ...     results = await session.extract(".result-title")
+        Use sync CMDOPClient.browser instead.
         """
         if self._browser is None:
             self._browser = AsyncBrowserService(self._transport)

cmdop-0.1.22/src/cmdop/services/browser/__init__.py

@@ -0,0 +1,59 @@
+"""Browser SDK with capability-based API.
+
+Usage:
+    from cmdop.services.browser import BrowserSession
+
+    with service.create_session() as session:
+        session.navigate("https://example.com")
+
+        # Capabilities
+        session.scroll.js("down", 500)
+        session.scroll.to_bottom()
+
+        session.input.click_js(".button")
+        session.input.key("Escape")
+
+        session.timing.wait(1000)
+
+        soup = session.dom.soup()
+        data = session.fetch.json("/api/data")
+"""
+
+from .session import BrowserSession
+from .service.sync import BrowserService
+from .service.aio import AsyncBrowserService
+from .models import (
+    BrowserCookie,
+    BrowserState,
+    PageInfo,
+    ScrollResult,
+    ScrollInfo,
+    InfiniteScrollResult,
+)
+from .capabilities import (
+    ScrollCapability,
+    InputCapability,
+    TimingCapability,
+    DOMCapability,
+    FetchCapability,
+)
+
+__all__ = [
+    # Session & Service
+    "BrowserSession",
+    "BrowserService",
+    "AsyncBrowserService",
+    # Models
+    "BrowserCookie",
+    "BrowserState",
+    "PageInfo",
+    "ScrollResult",
+    "ScrollInfo",
+    "InfiniteScrollResult",
+    # Capabilities
+    "ScrollCapability",
+    "InputCapability",
+    "TimingCapability",
+    "DOMCapability",
+    "FetchCapability",
+]

cmdop-0.1.22/src/cmdop/services/browser/capabilities/__init__.py

@@ -0,0 +1,15 @@
+"""Browser capabilities."""
+
+from .scroll import ScrollCapability
+from .input import InputCapability
+from .timing import TimingCapability
+from .dom import DOMCapability
+from .fetch import FetchCapability
+
+__all__ = [
+    "ScrollCapability",
+    "InputCapability",
+    "TimingCapability",
+    "DOMCapability",
+    "FetchCapability",
+]

cmdop-0.1.22/src/cmdop/services/browser/capabilities/_base.py

@@ -0,0 +1,28 @@
+"""Base capability class."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..session import BrowserSession
+
+
+class BaseCapability:
+    """Base class for all capabilities.
+
+    Capabilities group related browser operations and delegate
+    actual execution to the session.
+    """
+
+    __slots__ = ("_s",)
+
+    def __init__(self, session: "BrowserSession") -> None:
+        self._s = session
+
+    def _js(self, script: str) -> str:
+        """Execute JS via session."""
+        return self._s.execute_script(script)
+
+    def _call(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        """Call service method via session."""
+        return self._s._call_service(method, *args, **kwargs)

cmdop-0.1.22/src/cmdop/services/browser/capabilities/_helpers.py

@@ -0,0 +1,16 @@
+"""Shared parsing helpers for capabilities."""
+
+from typing import Any
+from cmdop.services.browser.js import parse_json_result
+
+
+def to_dict(raw: str) -> dict[str, Any]:
+    """Parse JS result to dict, default empty."""
+    result = parse_json_result(raw)
+    return result if isinstance(result, dict) else {}
+
+
+def to_list(raw: str) -> list[Any]:
+    """Parse JS result to list, default empty."""
+    result = parse_json_result(raw)
+    return result if isinstance(result, list) else []

cmdop-0.1.22/src/cmdop/services/browser/capabilities/dom.py

@@ -0,0 +1,76 @@
+"""DOM capability."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from cmdop.services.browser.js import build_select_js, build_close_modal_js
+from cmdop.services.browser.parsing import parse_html, SoupWrapper
+
+from ._base import BaseCapability
+from ._helpers import to_dict
+
+if TYPE_CHECKING:
+    from bs4 import BeautifulSoup
+
+
+class DOMCapability(BaseCapability):
+    """DOM operations: extraction, forms, modals.
+
+    Usage:
+        html = session.dom.html()
+        soup = session.dom.soup()
+        session.dom.select("#country", value="US")
+    """
+
+    def html(self, selector: str | None = None) -> str:
+        """Get page HTML."""
+        return self._call("get_html", selector)
+
+    def text(self, selector: str | None = None) -> str:
+        """Get page text content."""
+        return self._call("get_text", selector)
+
+    def soup(self, selector: str | None = None) -> SoupWrapper:
+        """Get HTML as SoupWrapper with chainable API."""
+        return SoupWrapper(html=self.html(selector))
+
+    def parse(self, html: str | None = None, selector: str | None = None) -> "BeautifulSoup":
+        """Parse HTML with BeautifulSoup."""
+        if html is None:
+            html = self.html(selector)
+        return parse_html(html)
+
+    def select(
+        self,
+        selector: str,
+        value: str | None = None,
+        text: str | None = None,
+    ) -> dict:
+        """Select dropdown option by value or text."""
+        js = build_select_js(selector, value, text)
+        return to_dict(self._js(js))
+
+    def close_modal(self, selectors: list[str] | None = None) -> bool:
+        """Try to close modal/dialog."""
+        js = build_close_modal_js(selectors)
+        return to_dict(self._js(js)).get("success", False)
+
+    def extract(
+        self, selector: str, attr: str | None = None, limit: int = 100
+    ) -> list[str]:
+        """Extract text or attribute from elements."""
+        return self._call("extract", selector, attr, limit)
+
+    def extract_regex(
+        self, pattern: str, from_html: bool = False, limit: int = 100
+    ) -> list[str]:
+        """Extract matches using regex pattern."""
+        return self._call("extract_regex", pattern, from_html, limit)
+
+    def validate_selectors(self, item: str, fields: dict[str, str]) -> dict:
+        """Validate CSS selectors on page."""
+        return self._call("validate_selectors", item, fields)
+
+    def extract_data(self, item: str, fields_json: str, limit: int = 100) -> dict:
+        """Extract structured data from page."""
+        return self._call("extract_data", item, fields_json, limit)

cmdop-0.1.22/src/cmdop/services/browser/capabilities/fetch.py

@@ -0,0 +1,46 @@
+"""Fetch capability."""
+
+from typing import Any
+
+from cmdop.services.browser.js import (
+    build_fetch_js,
+    build_fetch_all_js,
+    build_async_js,
+    parse_json_result,
+)
+
+from ._base import BaseCapability
+
+
+class FetchCapability(BaseCapability):
+    """HTTP fetch operations from browser context.
+
+    Usage:
+        data = session.fetch.json("/api/data")
+        results = session.fetch.all({"a": "/api/a", "b": "/api/b"})
+    """
+
+    def json(self, url: str) -> dict | list | None:
+        """Fetch JSON from URL."""
+        js = build_fetch_js(url)
+        return parse_json_result(self._js(js))
+
+    def all(
+        self,
+        urls: dict[str, str],
+        headers: dict[str, str] | None = None,
+        credentials: bool = False,
+    ) -> dict[str, Any]:
+        """Fetch multiple URLs in parallel. Returns {id: {data, error}}."""
+        if not urls:
+            return {}
+        js = build_fetch_all_js(urls, headers, credentials)
+        # fetch_all returns via execute_js (async wrapper)
+        wrapped = build_async_js(js.replace("return ", ""))
+        result = parse_json_result(self._js(wrapped))
+        return result if isinstance(result, dict) else {}
+
+    def execute(self, code: str) -> dict | list | str | None:
+        """Execute async JS code (can use await, fetch, etc)."""
+        js = build_async_js(code)
+        return parse_json_result(self._js(js))

cmdop-0.1.22/src/cmdop/services/browser/capabilities/input.py

@@ -0,0 +1,49 @@
+"""Input capability."""
+
+from cmdop.services.browser.js import (
+    build_click_js,
+    build_press_key_js,
+    build_click_all_by_text_js,
+    build_hover_js,
+)
+
+from ._base import BaseCapability
+from ._helpers import to_dict
+
+
+class InputCapability(BaseCapability):
+    """Input operations: clicks, keyboard, hover.
+
+    Usage:
+        session.input.click_js(".button")
+        session.input.key("Escape")
+        session.input.click_all("See more")
+    """
+
+    def click_js(self, selector: str, scroll_into_view: bool = True) -> bool:
+        """Click using JavaScript. More reliable than native click."""
+        js = build_click_js(selector, scroll_into_view)
+        return to_dict(self._js(js)).get("success", False)
+
+    def key(self, key: str, selector: str | None = None) -> bool:
+        """Press keyboard key. Keys: Escape, Enter, Tab, ArrowDown, etc."""
+        js = build_press_key_js(key, selector)
+        return to_dict(self._js(js)).get("success", False)
+
+    def click_all(self, text: str, role: str = "button") -> int:
+        """Click all elements containing text. Returns count clicked."""
+        js = build_click_all_by_text_js(text, role)
+        return to_dict(self._js(js)).get("clicked", 0)
+
+    def hover_js(self, selector: str) -> bool:
+        """Hover using JavaScript."""
+        js = build_hover_js(selector)
+        return to_dict(self._js(js)).get("success", False)
+
+    def hover(self, selector: str, timeout_ms: int = 5000) -> None:
+        """Hover using native browser API."""
+        self._call("hover", selector, timeout_ms)
+
+    def mouse_move(self, x: int, y: int, steps: int = 10) -> None:
+        """Move mouse to coordinates with human-like movement."""
+        self._call("mouse_move", x, y, steps)