keres-sdk 0.1.0__tar.gz

keres_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: keres-sdk
+Version: 0.1.0
+Summary: Playwright-compatible automation client for Keres Browser. Connects to the local Keres Automation Gateway; Keres owns profiles, sessions, and the browser runtime.
+License: MIT
+Keywords: keres,playwright,automation,browser
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets<16,>=12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# keres-playwright
+
+Playwright-compatible automation client for [Keres Browser](https://keres.browser).
+Connects to the local Keres Automation Gateway; Keres owns profiles, sessions,
+and the browser runtime (Chromium, Gecko, Camoufox).
+
+> Keres is a web browser, profile manager, and automation platform. This client
+> drives browsers through a governed local API — it makes no claims about
+> bypassing third-party systems.
+
+## Install
+
+Until the package is published to PyPI (tracked in Stage 17), install from the
+repository checkout:
+
+```bash
+pip install -e path/to/keres/compatibility/python
+```
+
+Requires Python 3.10+ and the Keres desktop app running locally.
+
+## Quickstart
+
+```python
+from keres_playwright import keres
+
+browser = keres.connect({"profile": "sales-profile"})
+page = browser.new_page()
+page.goto("https://example.com")
+print(page.title())
+page.get_by_role("button", name="Sign in").click()
+browser.close()  # disconnects; the profile stays alive in Keres
+```
+
+Async flavor:
+
+```python
+import asyncio
+from keres_playwright.async_api import keres
+
+async def main():
+    browser = await keres.connect({"profile": "sales-profile"})
+    page = await browser.new_page()
+    await page.goto("https://example.com")
+    print(await page.title())
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Concepts
+
+- **Profile ≠ Context.** A `Browser` maps onto one Keres session bound to the
+  profile chosen at connect time. Persistent identity (cookies, storage,
+  network configuration) lives with the Keres profile — not with this handle.
+- **`close()` is disconnect-only.** Sessions and profiles remain managed by
+  Keres after the client disconnects.
+- **Explicit profiles.** `connect` requires `{"profile": ...}`; desktop-user
+  sessions are never adopted silently.
+- **Auto-waiting is server-side**, delegated to the Keres Automation API wait
+  engine. The client builds no second waiting implementation.
+
+## Errors
+
+Error names follow Playwright conventions (`TimeoutError`, ...) while every
+error carries the original structured Keres code:
+
+```python
+from keres_playwright import TimeoutError, KeresError
+
+try:
+    page.goto("https://example.com", timeout_ms=5000)
+except TimeoutError as exc:
+    print(exc.code)  # e.g. NAVIGATION_TIMEOUT
+```
+
+## Endpoint and token resolution
+
+1. Explicit options: `connect({"endpoint": ..., "token": ...})`
+2. Environment: `KERES_GATEWAY_ENDPOINT`, `KERES_GATEWAY_TOKEN`
+3. Discovery file published by the running app:
+   `%APPDATA%\com.keres.browser\gateway\endpoint.json` (Windows),
+   `~/Library/Application Support/com.keres.browser/gateway/endpoint.json`
+   (macOS), `$XDG_CONFIG_HOME/com.keres.browser/gateway/endpoint.json`
+   (Linux). Reveal the token in Keres Settings → Developer automation.
+
+The token is sent as the first WebSocket frame — never placed in URLs or logs.
+
+## Capability matrix
+
+Engine support per operation is documented in
+[`api/PLAYWRIGHT_API.md`](../../api/PLAYWRIGHT_API.md); unsupported operations
+raise `UnsupportedCapabilityError` naming the engine.
+
+## License
+
+MIT

keres_sdk-0.1.0/README.md

@@ -0,0 +1,97 @@
+# keres-playwright
+
+Playwright-compatible automation client for [Keres Browser](https://keres.browser).
+Connects to the local Keres Automation Gateway; Keres owns profiles, sessions,
+and the browser runtime (Chromium, Gecko, Camoufox).
+
+> Keres is a web browser, profile manager, and automation platform. This client
+> drives browsers through a governed local API — it makes no claims about
+> bypassing third-party systems.
+
+## Install
+
+Until the package is published to PyPI (tracked in Stage 17), install from the
+repository checkout:
+
+```bash
+pip install -e path/to/keres/compatibility/python
+```
+
+Requires Python 3.10+ and the Keres desktop app running locally.
+
+## Quickstart
+
+```python
+from keres_playwright import keres
+
+browser = keres.connect({"profile": "sales-profile"})
+page = browser.new_page()
+page.goto("https://example.com")
+print(page.title())
+page.get_by_role("button", name="Sign in").click()
+browser.close()  # disconnects; the profile stays alive in Keres
+```
+
+Async flavor:
+
+```python
+import asyncio
+from keres_playwright.async_api import keres
+
+async def main():
+    browser = await keres.connect({"profile": "sales-profile"})
+    page = await browser.new_page()
+    await page.goto("https://example.com")
+    print(await page.title())
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Concepts
+
+- **Profile ≠ Context.** A `Browser` maps onto one Keres session bound to the
+  profile chosen at connect time. Persistent identity (cookies, storage,
+  network configuration) lives with the Keres profile — not with this handle.
+- **`close()` is disconnect-only.** Sessions and profiles remain managed by
+  Keres after the client disconnects.
+- **Explicit profiles.** `connect` requires `{"profile": ...}`; desktop-user
+  sessions are never adopted silently.
+- **Auto-waiting is server-side**, delegated to the Keres Automation API wait
+  engine. The client builds no second waiting implementation.
+
+## Errors
+
+Error names follow Playwright conventions (`TimeoutError`, ...) while every
+error carries the original structured Keres code:
+
+```python
+from keres_playwright import TimeoutError, KeresError
+
+try:
+    page.goto("https://example.com", timeout_ms=5000)
+except TimeoutError as exc:
+    print(exc.code)  # e.g. NAVIGATION_TIMEOUT
+```
+
+## Endpoint and token resolution
+
+1. Explicit options: `connect({"endpoint": ..., "token": ...})`
+2. Environment: `KERES_GATEWAY_ENDPOINT`, `KERES_GATEWAY_TOKEN`
+3. Discovery file published by the running app:
+   `%APPDATA%\com.keres.browser\gateway\endpoint.json` (Windows),
+   `~/Library/Application Support/com.keres.browser/gateway/endpoint.json`
+   (macOS), `$XDG_CONFIG_HOME/com.keres.browser/gateway/endpoint.json`
+   (Linux). Reveal the token in Keres Settings → Developer automation.
+
+The token is sent as the first WebSocket frame — never placed in URLs or logs.
+
+## Capability matrix
+
+Engine support per operation is documented in
+[`api/PLAYWRIGHT_API.md`](../../api/PLAYWRIGHT_API.md); unsupported operations
+raise `UnsupportedCapabilityError` naming the engine.
+
+## License
+
+MIT

keres_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keres-sdk"
+version = "0.1.0"
+description = "Playwright-compatible automation client for Keres Browser. Connects to the local Keres Automation Gateway; Keres owns profiles, sessions, and the browser runtime."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = ["websockets>=12,<16"]
+keywords = ["keres", "playwright", "automation", "browser"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+keres_sdk = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

keres_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

keres_sdk-0.1.0/src/keres_sdk/__init__.py

@@ -0,0 +1,38 @@
+"""keres-sdk — Playwright-compatible automation client for Keres Browser.
+
+Connects to the local Keres Automation Gateway; Keres owns profiles, sessions,
+and the browser runtime. See ``sync_api`` / ``async_api`` for entry points.
+"""
+
+from ._errors import (
+    ConnectionError,
+    KeresError,
+    PermissionDeniedError,
+    ProfileError,
+    ServerBusyError,
+    TargetClosedError,
+    TimeoutError,
+    UnsupportedCapabilityError,
+    from_gateway_error,
+)
+from .sync_api import keres
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "keres",
+    "KeresError",
+    "ConnectionError",
+    "TimeoutError",
+    "UnsupportedCapabilityError",
+    "PermissionDeniedError",
+    "TargetClosedError",
+    "ProfileError",
+    "ServerBusyError",
+    "from_gateway_error",
+    "__version__",
+]
+from ._expect import expect, KeresExpectationError
+
+__all__ = [name for name in dir() if not name.startswith("_")]
+

keres_sdk-0.1.0/src/keres_sdk/_errors.py

@@ -0,0 +1,115 @@
+"""Typed errors for the keres-playwright client.
+
+Error names follow Playwright conventions (TimeoutError, ...) so existing
+`try/except` code keeps working, while every error carries the original
+structured Keres code under ``code`` for precise handling.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._protocol import ErrorShape
+
+_CAPABILITY_CODES = frozenset(
+    {
+        "CAPABILITY_UNSUPPORTED",
+        "ENGINE_FEATURE_UNSUPPORTED",
+        "ENGINE_PROTOCOL_UNSUPPORTED",
+        "ENGINE_VARIANT_UNAVAILABLE",
+    }
+)
+
+_PROFILE_CODES = frozenset(
+    {
+        "PROFILE_NOT_FOUND",
+        "PROFILE_ACTIVE",
+        "PROFILE_LOCKED",
+        "PROFILE_DATA_MISSING",
+        "PROFILE_DATA_CORRUPTED",
+        "INVALID_PROFILE",
+    }
+)
+
+_TARGET_CLOSED_CODES = frozenset(
+    {
+        "SESSION_CLOSED",
+        "SESSION_NOT_READY",
+        "SESSION_INTERRUPTED",
+        "PAGE_CLOSED",
+        "PAGE_NOT_FOUND",
+    }
+)
+
+
+class KeresError(Exception):
+    """Base class for every error raised by this client."""
+
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape.message)
+        self.name = "KeresError"
+        self.code = shape.code
+        self.category = shape.category
+        self.recoverable = shape.recoverable
+
+
+class ConnectionError(KeresError):
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            ErrorShape(code="GATEWAY_CONNECTION_FAILED", message=message, category="GATEWAY")
+        )
+        self.name = "ConnectionError"
+
+
+class TimeoutError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "TimeoutError"
+
+
+class UnsupportedCapabilityError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "UnsupportedCapabilityError"
+
+
+class PermissionDeniedError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "PermissionDeniedError"
+
+
+class TargetClosedError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "TargetClosedError"
+
+
+class ProfileError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "ProfileError"
+
+
+class ServerBusyError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "ServerBusyError"
+
+
+def from_gateway_error(error: ErrorShape) -> KeresError:
+    """Maps a structured gateway error onto the typed surface above."""
+    code = error.code
+    if code.endswith("_TIMEOUT"):
+        return TimeoutError(error)
+    if code in _CAPABILITY_CODES:
+        return UnsupportedCapabilityError(error)
+    if code in ("GATEWAY_PERMISSION_DENIED", "SESSION_PERMISSION_DENIED"):
+        return PermissionDeniedError(error)
+    if code == "GATEWAY_SERVER_BUSY":
+        return ServerBusyError(error)
+    if code in _PROFILE_CODES:
+        return ProfileError(error)
+    if code in _TARGET_CLOSED_CODES:
+        return TargetClosedError(error)
+    return KeresError(error)

keres_sdk-0.1.0/src/keres_sdk/_expect.py

@@ -0,0 +1,236 @@
+"""Web-first auto-retrying assertions (Playwright ``expect`` shape).
+
+Polling is client-side over governed read operations — no new wire semantics.
+Works from both API flavors: probes transparently await async locator/page
+methods when driven through :mod:`keres_playwright.async_api`, and run
+synchronously through the sync facade.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import inspect
+import time
+from typing import Any, Callable, Optional
+
+DEFAULT_TIMEOUT_MS = 5_000
+DEFAULT_INTERVAL_MS = 100
+
+
+class KeresExpectationError(AssertionError):
+    """Raised when an assertion does not pass within its deadline."""
+
+    def __init__(self, assertion: str, expected: str, received: str) -> None:
+        super().__init__(
+            f"expect({assertion}) failed\n\nExpected: {expected}\nReceived: {received}"
+        )
+        self.assertion = assertion
+        self.expected = expected
+        self.received = received
+
+
+async def _poll_until(
+    assertion: str,
+    expected_description: str,
+    deadline_ms: float,
+    interval_ms: float,
+    probe: Callable[[], Any],
+) -> None:
+    """``probe`` returns an ``(ok, received)`` tuple or an awaitable of one."""
+    started_ms = time.monotonic() * 1000
+    received = "unknown"
+    while time.monotonic() * 1000 - started_ms < deadline_ms:
+        result = probe()
+        if inspect.isawaitable(result):
+            result = await result
+        ok, received = result
+        if ok:
+            return
+        await asyncio.sleep(interval_ms / 1000)
+    raise KeresExpectationError(assertion, expected_description, received)
+
+
+def _bool_probe(value: Any) -> Any:
+    """Adapts a sync-or-async boolean into an ``(ok, received)`` tuple."""
+    if inspect.isawaitable(value):
+
+        async def runner() -> tuple:
+            got = bool(await value)
+            return got, str(got)
+
+        return runner()
+    got = bool(value)
+    return got, str(got)
+
+
+def _text_probe(value: Any, predicate: Callable[[str], bool]) -> Any:
+    """Adapts a sync-or-async text into a predicate-checked tuple."""
+    if inspect.isawaitable(value):
+
+        async def runner() -> tuple:
+            text = (await value) or ""
+            return predicate(text), text
+
+        return runner()
+    text = value or ""
+    return predicate(text), text
+
+
+def _opts(options: Optional[dict]) -> dict:
+    return options or {}
+
+
+def expect(target: Any) -> Any:
+    """Playwright-style entry point. Returns an assertion object."""
+    if target.__class__.__name__ in ("Page", "SyncPage"):
+        return PageAssertions(target)
+    return LocatorAssertions(target)
+
+
+class LocatorAssertions:
+    def __init__(self, locator: Any) -> None:
+        self._locator = locator
+
+    def to_be_visible(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_visible",
+            "visible",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_visible()),
+        )
+
+    def to_be_hidden(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+
+        def probe() -> Any:
+            value = self._locator.is_visible()
+            if inspect.isawaitable(value):
+
+                async def runner() -> tuple:
+                    visible = bool(await value)
+                    return not visible, "hidden" if not visible else "visible"
+
+                return runner()
+            return not value, "hidden" if not value else "visible"
+
+        return _poll_until(
+            "locator.to_be_hidden",
+            "hidden",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            probe,
+        )
+
+    def to_be_enabled(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_enabled",
+            "enabled",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_enabled()),
+        )
+
+    def to_be_checked(self, expected: bool = True, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_checked",
+            str(expected),
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_checked() == expected),
+        )
+
+    def to_be_editable(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_editable",
+            "editable",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_editable()),
+        )
+
+    def to_have_text(self, text: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        exact = o.get("exact", True)
+        return _poll_until(
+            "locator.to_have_text",
+            text,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._locator.text_content(options=o),
+                (lambda actual: actual == text) if exact else (lambda actual: text in actual),
+            ),
+        )
+
+    def to_contain_text(self, text: str, options: Optional[dict] = None) -> Any:
+        merged = dict(_opts(options))
+        merged["exact"] = False
+        return self.to_have_text(text, merged)
+
+    def to_have_value(self, value: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_have_value",
+            value,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._locator.get_property("value", options=o),
+                lambda actual: str(actual) == value,
+            ),
+        )
+
+    def to_have_attribute(self, name: str, value: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_have_attribute",
+            f'{name}="{value}"',
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._locator.get_attribute(name, options=o),
+                lambda actual: str(actual) == value,
+            ),
+        )
+
+
+class PageAssertions:
+    def __init__(self, page: Any) -> None:
+        self._page = page
+
+    def to_have_title(self, title: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        exact = o.get("exact", True)
+        return _poll_until(
+            "page.to_have_title",
+            title,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._page.title(options=o),
+                (lambda actual: actual == title) if exact else (lambda actual: title in actual),
+            ),
+        )
+
+    def to_have_url(self, pattern: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        use_glob = o.get("glob", "*" in pattern)
+
+        def matcher(candidate: str) -> bool:
+            if use_glob:
+                return fnmatch.fnmatchcase(candidate, pattern)
+            return candidate == pattern
+
+        return _poll_until(
+            "page.to_have_url",
+            pattern,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: (matcher(self._page.url()), self._page.url()),
+        )