cmdop 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

cmdop/__init__.py

@@ -116,8 +116,14 @@ from cmdop.discovery import (
     get_online_agents,
     list_agents,
 )
+from cmdop.helpers import (
+    JSONFormatter,
+    flatten_json,
+    json_to_yaml,
+    json_to_text,
+)
 
-__version__ = "0.1.13"
+__version__ = "0.1.15"
 
 __all__ = [
     # Version
@@ -210,4 +216,9 @@ __all__ = [
     "BrowserSessionClosedError",
     "BrowserNavigationError",
     "BrowserElementNotFoundError",
+    # Helpers
+    "JSONFormatter",
+    "flatten_json",
+    "json_to_yaml",
+    "json_to_text",
 ]

cmdop/helpers/__init__.py

@@ -0,0 +1,15 @@
+"""CMDOP SDK helpers."""
+
+from cmdop.helpers.formatting import (
+    JSONFormatter,
+    flatten_json,
+    json_to_yaml,
+    json_to_text,
+)
+
+__all__ = [
+    "JSONFormatter",
+    "flatten_json",
+    "json_to_yaml",
+    "json_to_text",
+]

cmdop/helpers/formatting.py

@@ -0,0 +1,70 @@
+"""JSON formatting utilities."""
+
+import json
+
+import yaml
+from flatten_json import flatten
+
+
+class JSONFormatter:
+    """
+    JSON to various formats converter.
+
+    Usage:
+        fmt = JSONFormatter()
+
+        flat = fmt.flatten({"a": {"b": 1}})  # {"a.b": 1}
+        yaml_str = fmt.to_yaml(data)
+        text = fmt.to_text(data)  # key: value lines
+    """
+
+    def __init__(self, separator: str = "."):
+        self.separator = separator
+
+    def flatten(self, data: dict | list) -> dict:
+        """
+        Flatten nested JSON to flat dict with dot notation.
+
+        {"a": {"b": 1}} -> {"a.b": 1}
+        """
+        if isinstance(data, list):
+            data = {"items": data}
+        return flatten(data, self.separator)
+
+    def to_yaml(self, data: dict | list) -> str:
+        """Convert to YAML string."""
+        return yaml.dump(
+            data,
+            allow_unicode=True,
+            default_flow_style=False,
+            sort_keys=False,
+            indent=2,
+        )
+
+    def to_text(self, data: dict | list) -> str:
+        """Convert to flat text (key: value per line)."""
+        flat = self.flatten(data)
+        lines = []
+        for key, value in flat.items():
+            if isinstance(value, str):
+                val_str = value
+            elif value is None:
+                val_str = "null"
+            elif isinstance(value, bool):
+                val_str = "true" if value else "false"
+            else:
+                val_str = str(value)
+            lines.append(f"{key}: {val_str}")
+        return "\n".join(lines)
+
+    def to_json(self, data: dict | list, indent: int = 2) -> str:
+        """Convert to formatted JSON string."""
+        return json.dumps(data, indent=indent, ensure_ascii=False)
+
+
+# Default instance
+_fmt = JSONFormatter()
+
+flatten_json = _fmt.flatten
+json_to_yaml = _fmt.to_yaml
+json_to_text = _fmt.to_text

cmdop/services/browser/__init__.py

@@ -0,0 +1,17 @@
+"""Browser service module."""
+
+from cmdop.services.browser.models import BrowserCookie, BrowserState, raise_browser_error
+from cmdop.services.browser.session import BrowserSession
+from cmdop.services.browser.service import BrowserService
+from cmdop.services.browser.async_session import AsyncBrowserSession
+from cmdop.services.browser.async_service import AsyncBrowserService
+
+__all__ = [
+    "BrowserCookie",
+    "BrowserState",
+    "BrowserSession",
+    "BrowserService",
+    "AsyncBrowserSession",
+    "AsyncBrowserService",
+    "raise_browser_error",
+]

cmdop/services/browser/_base.py

@@ -0,0 +1,109 @@
+"""Shared browser utilities."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cmdop.services.browser.models import BrowserCookie
+
+
+def build_fetch_js(url: str) -> str:
+    """Build JS for single fetch."""
+    return f"""
+    (async function() {{
+        try {{
+            const resp = await fetch("{url}");
+            if (!resp.ok) return JSON.stringify({{__error: resp.status}});
+            return JSON.stringify(await resp.json());
+        }} catch(e) {{
+            return JSON.stringify({{__error: e.message}});
+        }}
+    }})()
+    """
+
+
+def build_fetch_all_js(urls: dict[str, str]) -> tuple[str, list[str]]:
+    """Build JS for parallel fetch. Returns (js_code, keys)."""
+    keys = list(urls.keys())
+    fetches = [
+        f'fetch("{urls[k]}").then(r => r.ok ? r.json() : null).catch(() => null)'
+        for k in keys
+    ]
+
+    js = f"""
+    (async function() {{
+        try {{
+            const results = await Promise.all([{", ".join(fetches)}]);
+            return JSON.stringify(results);
+        }} catch(e) {{
+            return JSON.stringify({{__error: e.message}});
+        }}
+    }})()
+    """
+    return js, keys
+
+
+def parse_fetch_result(result: str) -> dict | list | None:
+    """Parse single fetch result."""
+    if result:
+        try:
+            data = json.loads(result)
+            if isinstance(data, dict) and "__error" in data:
+                return None
+            return data
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+def parse_fetch_all_result(result: str, keys: list[str]) -> dict[str, Any]:
+    """Parse parallel fetch result."""
+    if result:
+        try:
+            data = json.loads(result)
+            if isinstance(data, dict) and "__error" in data:
+                return {k: None for k in keys}
+            return {k: data[i] for i, k in enumerate(keys)}
+        except json.JSONDecodeError:
+            return {k: None for k in keys}
+    return {k: None for k in keys}
+
+
+def cookie_to_pb(c: BrowserCookie | dict, PbCookie: type) -> Any:
+    """Convert cookie to protobuf."""
+    if isinstance(c, dict):
+        return PbCookie(
+            name=c.get("name", ""),
+            value=c.get("value", ""),
+            domain=c.get("domain", ""),
+            path=c.get("path", "/"),
+            secure=c.get("secure", False),
+            http_only=c.get("http_only", False),
+            same_site=c.get("same_site", ""),
+            expires=c.get("expires", 0),
+        )
+    return PbCookie(
+        name=c.name,
+        value=c.value,
+        domain=c.domain,
+        path=c.path,
+        secure=c.secure,
+        http_only=c.http_only,
+        same_site=c.same_site,
+        expires=c.expires,
+    )
+
+
+def pb_to_cookie(c: Any) -> BrowserCookie:
+    """Convert protobuf to cookie."""
+    return BrowserCookie(
+        name=c.name,
+        value=c.value,
+        domain=c.domain,
+        path=c.path,
+        secure=c.secure,
+        http_only=c.http_only,
+        same_site=c.same_site,
+        expires=c.expires,
+    )

cmdop/services/browser/async_service.py

@@ -0,0 +1,311 @@
+"""Browser service (async)."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from cmdop.services.base import BaseService
+from cmdop.services.browser.models import BrowserCookie, BrowserState, raise_browser_error
+from cmdop.services.browser.async_session import AsyncBrowserSession
+from cmdop.services.browser._base import cookie_to_pb, pb_to_cookie
+
+if TYPE_CHECKING:
+    from cmdop.transport.base import BaseTransport
+
+
+class AsyncBrowserService(BaseService):
+    """
+    Async browser service.
+
+    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")
+    """
+
+    def __init__(self, transport: BaseTransport) -> None:
+        super().__init__(transport)
+        self._stub: Any = None
+
+    @property
+    def _get_stub(self) -> Any:
+        if self._stub is None:
+            from cmdop._generated.service_pb2_grpc import TerminalStreamingServiceStub
+            self._stub = TerminalStreamingServiceStub(self._async_channel)
+        return self._stub
+
+    async def create_session(
+        self,
+        start_url: str | None = None,
+        provider: str = "camoufox",
+        profile_id: str | None = None,
+        headless: bool = False,
+        width: int = 1280,
+        height: int = 800,
+    ) -> AsyncBrowserSession:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserCreateSessionRequest
+
+        request = BrowserCreateSessionRequest(
+            provider=provider,
+            profile_id=profile_id or "",
+            start_url=start_url or "",
+            headless=headless,
+            width=width,
+            height=height,
+        )
+        response = await self._call_async(self._get_stub.BrowserCreateSession, request)
+
+        if not response.success:
+            raise_browser_error(response.error, "create_session")
+
+        return AsyncBrowserSession(self, response.browser_session_id)
+
+    async def close_session(self, session_id: str) -> None:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserCloseSessionRequest
+
+        request = BrowserCloseSessionRequest(browser_session_id=session_id)
+        response = await self._call_async(self._get_stub.BrowserCloseSession, request)
+
+        if not response.success:
+            raise RuntimeError(f"Failed to close browser session: {response.error}")
+
+    async def navigate(self, session_id: str, url: str, timeout_ms: int = 30000) -> str:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserNavigateRequest
+
+        request = BrowserNavigateRequest(
+            browser_session_id=session_id, url=url, timeout_ms=timeout_ms
+        )
+        response = await self._call_async(self._get_stub.BrowserNavigate, request)
+
+        if not response.success:
+            raise_browser_error(response.error, "navigate", url=url)
+
+        return response.final_url
+
+    async def click(self, session_id: str, selector: str, timeout_ms: int = 5000) -> None:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserClickRequest
+
+        request = BrowserClickRequest(
+            browser_session_id=session_id, selector=selector, timeout_ms=timeout_ms
+        )
+        response = await self._call_async(self._get_stub.BrowserClick, request)
+
+        if not response.success:
+            raise_browser_error(response.error, "click", selector=selector)
+
+    async def type(
+        self,
+        session_id: str,
+        selector: str,
+        text: str,
+        human_like: bool = False,
+        clear_first: bool = True,
+    ) -> None:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserTypeRequest
+
+        request = BrowserTypeRequest(
+            browser_session_id=session_id,
+            selector=selector,
+            text=text,
+            human_like=human_like,
+            clear_first=clear_first,
+        )
+        response = await self._call_async(self._get_stub.BrowserType, request)
+
+        if not response.success:
+            raise_browser_error(response.error, "type", selector=selector)
+
+    async def wait_for(
+        self, session_id: str, selector: str, timeout_ms: int = 30000
+    ) -> bool:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserWaitRequest
+
+        request = BrowserWaitRequest(
+            browser_session_id=session_id, selector=selector, timeout_ms=timeout_ms
+        )
+        response = await self._call_async(self._get_stub.BrowserWait, request)
+
+        if not response.success:
+            raise_browser_error(response.error, "wait_for", selector=selector)
+
+        return response.found
+
+    async def extract(
+        self, session_id: str, selector: str, attr: str | None = None, limit: int = 100
+    ) -> list[str]:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserExtractRequest
+
+        request = BrowserExtractRequest(
+            browser_session_id=session_id,
+            selector=selector,
+            attribute=attr or "",
+            limit=limit,
+        )
+        response = await self._call_async(self._get_stub.BrowserExtract, request)
+
+        if not response.success:
+            raise RuntimeError(f"Extract failed: {response.error}")
+
+        return list(response.values)
+
+    async def extract_regex(
+        self, session_id: str, pattern: str, from_html: bool = False, limit: int = 100
+    ) -> list[str]:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserExtractRegexRequest
+
+        request = BrowserExtractRegexRequest(
+            browser_session_id=session_id,
+            pattern=pattern,
+            from_html=from_html,
+            limit=limit,
+        )
+        response = await self._call_async(self._get_stub.BrowserExtractRegex, request)
+
+        if not response.success:
+            raise RuntimeError(f"ExtractRegex failed: {response.error}")
+
+        return list(response.matches)
+
+    async def get_html(self, session_id: str, selector: str | None = None) -> str:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserGetHTMLRequest
+
+        request = BrowserGetHTMLRequest(
+            browser_session_id=session_id, selector=selector or ""
+        )
+        response = await self._call_async(self._get_stub.BrowserGetHTML, request)
+
+        if not response.success:
+            raise RuntimeError(f"GetHTML failed: {response.error}")
+
+        return response.html
+
+    async def get_text(self, session_id: str, selector: str | None = None) -> str:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserGetTextRequest
+
+        request = BrowserGetTextRequest(
+            browser_session_id=session_id, selector=selector or ""
+        )
+        response = await self._call_async(self._get_stub.BrowserGetText, request)
+
+        if not response.success:
+            raise RuntimeError(f"GetText failed: {response.error}")
+
+        return response.text
+
+    async def execute_script(self, session_id: str, script: str) -> str:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserExecuteScriptRequest
+
+        request = BrowserExecuteScriptRequest(
+            browser_session_id=session_id, script=script
+        )
+        response = await self._call_async(
+            self._get_stub.BrowserExecuteScript, request
+        )
+
+        if not response.success:
+            raise RuntimeError(f"ExecuteScript failed: {response.error}")
+
+        return response.result
+
+    async def screenshot(self, session_id: str, full_page: bool = False) -> bytes:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserScreenshotRequest
+
+        request = BrowserScreenshotRequest(
+            browser_session_id=session_id, full_page=full_page
+        )
+        response = await self._call_async(self._get_stub.BrowserScreenshot, request)
+
+        if not response.success:
+            raise RuntimeError(f"Screenshot failed: {response.error}")
+
+        return response.data
+
+    async def get_state(self, session_id: str) -> BrowserState:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserGetStateRequest
+
+        request = BrowserGetStateRequest(browser_session_id=session_id)
+        response = await self._call_async(self._get_stub.BrowserGetState, request)
+
+        if not response.success:
+            raise RuntimeError(f"GetState failed: {response.error}")
+
+        return BrowserState(url=response.url, title=response.title)
+
+    async def set_cookies(
+        self, session_id: str, cookies: list[BrowserCookie | dict]
+    ) -> None:
+        from cmdop._generated.rpc_messages.browser_pb2 import (
+            BrowserCookie as PbCookie,
+            BrowserSetCookiesRequest,
+        )
+
+        pb_cookies = [cookie_to_pb(c, PbCookie) for c in cookies]
+        request = BrowserSetCookiesRequest(
+            browser_session_id=session_id, cookies=pb_cookies
+        )
+        response = await self._call_async(self._get_stub.BrowserSetCookies, request)
+
+        if not response.success:
+            raise RuntimeError(f"SetCookies failed: {response.error}")
+
+    async def get_cookies(
+        self, session_id: str, domain: str = ""
+    ) -> list[BrowserCookie]:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserGetCookiesRequest
+
+        request = BrowserGetCookiesRequest(
+            browser_session_id=session_id, domain=domain
+        )
+        response = await self._call_async(self._get_stub.BrowserGetCookies, request)
+
+        if not response.success:
+            raise RuntimeError(f"GetCookies failed: {response.error}")
+
+        return [pb_to_cookie(c) for c in response.cookies]
+
+    async def validate_selectors(
+        self, session_id: str, item: str, fields: dict[str, str]
+    ) -> dict:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserValidateSelectorsRequest
+
+        request = BrowserValidateSelectorsRequest(
+            browser_session_id=session_id,
+            item=item,
+            fields=fields,
+        )
+        response = await self._call_async(
+            self._get_stub.BrowserValidateSelectors, request
+        )
+
+        if not response.success:
+            raise RuntimeError(f"ValidateSelectors failed: {response.error}")
+
+        return {
+            "valid": response.valid,
+            "counts": dict(response.counts),
+            "samples": dict(response.samples),
+            "errors": list(response.errors),
+        }
+
+    async def extract_data(
+        self, session_id: str, item: str, fields_json: str, limit: int = 100
+    ) -> dict:
+        from cmdop._generated.rpc_messages.browser_pb2 import BrowserExtractDataRequest
+
+        request = BrowserExtractDataRequest(
+            browser_session_id=session_id,
+            item=item,
+            fields_json=fields_json,
+            limit=limit,
+        )
+        response = await self._call_async(self._get_stub.BrowserExtractData, request)
+
+        if not response.success:
+            raise RuntimeError(f"ExtractData failed: {response.error}")
+
+        return {
+            "items": json.loads(response.items_json) if response.items_json else [],
+            "count": response.count,
+        }

cmdop/services/browser/async_session.py

@@ -0,0 +1,119 @@
+"""Browser session (async)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cmdop.services.browser.models import BrowserCookie, BrowserState
+from cmdop.services.browser._base import (
+    build_fetch_js,
+    build_fetch_all_js,
+    parse_fetch_result,
+    parse_fetch_all_result,
+)
+
+if TYPE_CHECKING:
+    from cmdop.services.browser.async_service import AsyncBrowserService
+
+
+class AsyncBrowserSession:
+    """
+    Async browser session with fluent API.
+
+    Use as async context manager:
+        async with client.browser.create_session() as session:
+            await session.navigate("https://example.com")
+            await session.click("button.submit")
+    """
+
+    def __init__(self, service: AsyncBrowserService, session_id: str) -> None:
+        self._service = service
+        self._session_id = session_id
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    async def navigate(self, url: str, timeout_ms: int = 30000) -> str:
+        return await self._service.navigate(self._session_id, url, timeout_ms)
+
+    async def click(self, selector: str, timeout_ms: int = 5000) -> None:
+        await self._service.click(self._session_id, selector, timeout_ms)
+
+    async def type(
+        self,
+        selector: str,
+        text: str,
+        human_like: bool = False,
+        clear_first: bool = True,
+    ) -> None:
+        await self._service.type(
+            self._session_id, selector, text, human_like, clear_first
+        )
+
+    async def wait_for(self, selector: str, timeout_ms: int = 30000) -> bool:
+        return await self._service.wait_for(self._session_id, selector, timeout_ms)
+
+    async def extract(
+        self, selector: str, attr: str | None = None, limit: int = 100
+    ) -> list[str]:
+        return await self._service.extract(self._session_id, selector, attr, limit)
+
+    async def extract_regex(
+        self, pattern: str, from_html: bool = False, limit: int = 100
+    ) -> list[str]:
+        return await self._service.extract_regex(
+            self._session_id, pattern, from_html, limit
+        )
+
+    async def get_html(self, selector: str | None = None) -> str:
+        return await self._service.get_html(self._session_id, selector)
+
+    async def get_text(self, selector: str | None = None) -> str:
+        return await self._service.get_text(self._session_id, selector)
+
+    async def execute_script(self, script: str) -> str:
+        return await self._service.execute_script(self._session_id, script)
+
+    async def fetch_json(self, url: str) -> dict | list | None:
+        """Fetch JSON from URL using JS fetch()."""
+        js = build_fetch_js(url)
+        result = await self.execute_script(js)
+        return parse_fetch_result(result)
+
+    async def fetch_all(self, urls: dict[str, str]) -> dict[str, Any]:
+        """Fetch multiple URLs in parallel using Promise.all."""
+        if not urls:
+            return {}
+        js, keys = build_fetch_all_js(urls)
+        result = await self.execute_script(js)
+        return parse_fetch_all_result(result, keys)
+
+    async def screenshot(self, full_page: bool = False) -> bytes:
+        return await self._service.screenshot(self._session_id, full_page)
+
+    async def get_state(self) -> BrowserState:
+        return await self._service.get_state(self._session_id)
+
+    async def set_cookies(self, cookies: list[BrowserCookie | dict]) -> None:
+        await self._service.set_cookies(self._session_id, cookies)
+
+    async def get_cookies(self, domain: str = "") -> list[BrowserCookie]:
+        return await self._service.get_cookies(self._session_id, domain)
+
+    async def validate_selectors(self, item: str, fields: dict[str, str]) -> dict:
+        return await self._service.validate_selectors(self._session_id, item, fields)
+
+    async def extract_data(self, item: str, fields_json: str, limit: int = 100) -> dict:
+        return await self._service.extract_data(
+            self._session_id, item, fields_json, limit
+        )
+
+    async def close(self) -> None:
+        await self._service.close_session(self._session_id)
+
+    async def __aenter__(self) -> "AsyncBrowserSession":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()