tzafon 0.1.1__py3-none-any.whl

tzafon/__init__.py

@@ -0,0 +1,3 @@
+from .client import Waypoint
+
+__all__ = ["Waypoint"]

tzafon/_connection.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+import asyncio
+import traceback
+import websockets
+from websockets.connection import State
+
+from .models import Command, Result
+
+
+class _WsConnection:
+    def __init__(self, url: str, *, ping_interval: int = 20):
+        if not url.startswith(("ws://", "wss://")):
+            raise ValueError(f"Invalid websocket URL '{url}'")
+        self._url = url
+        self._conn: websockets.WebSocketClientProtocol | None = None
+        self._ping = ping_interval
+
+    async def connect(self) -> None:
+        if self.is_open:
+            return
+        self._conn = await websockets.connect(
+            self._url,
+            max_size=2**24,  # 16 MiB
+            ping_interval=self._ping,
+            ping_timeout=self._ping,
+        )
+
+    async def close(self) -> None:
+        if self._conn and self._conn.state is State.OPEN:
+            try:
+                await self._conn.close(code=1000, reason="Client shutting down")
+                await asyncio.wait_for(self._conn.wait_closed(), timeout=5)
+            except Exception:
+                traceback.print_exc()
+        self._conn = None
+
+    async def send(self, cmd: Command) -> Result:
+        if not self.is_open:
+            raise RuntimeError("Websocket not connected")
+        await self._conn.send(cmd.dump())
+        raw = await self._conn.recv()
+        if isinstance(raw, str):
+            raw = raw.encode()
+        return Result.load(raw)
+
+    @property
+    def is_open(self) -> bool:
+        return (
+            self._conn is not None and getattr(self._conn, "state", None) is State.OPEN
+        )

tzafon/client.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+import asyncio
+import logging
+import os
+from typing import Optional
+
+from .models import Command, Result, ActionType
+from ._connection import _WsConnection
+from .exceptions import ScreenshotFailed
+
+
+log = logging.getLogger("waypoint")
+_DEFAULT_VIEWPORT = {"width": 1280, "height": 720}
+
+
+class Waypoint:
+    def __init__(
+        self,
+        token: str,
+        *,
+        url_template: str = "wss://api.tzafon.ai/ephemeral-tzafonwright?token={token}",
+        connect_timeout: float = 10.0,
+    ):
+        if not token or not token.startswith("wpk_"):
+            raise ValueError("token must look like 'wpk_…'")
+        self._ws_url = url_template.format(token=token)
+        self._timeout = connect_timeout
+        self._ws: Optional[_WsConnection] = None
+
+    async def __aenter__(self) -> "Waypoint":
+        self._ws = _WsConnection(self._ws_url)
+        await asyncio.wait_for(self._ws.connect(), timeout=self._timeout)
+        # one-time only
+        await self.set_viewport(**_DEFAULT_VIEWPORT)
+        return self
+
+    async def __aexit__(self, exc_t, exc, tb) -> None:
+        if self._ws:
+            await self._ws.close()
+            self._ws = None
+
+    async def goto(self, url: str, *, timeout: int = 5_000) -> Result:
+        return await self._send(Command(ActionType.GOTO, url=url, timeout=timeout))
+
+    async def click(self, x: float, y: float) -> Result:
+        return await self._send(Command(ActionType.CLICK, x=x, y=y))
+
+    async def type(self, text: str) -> Result:
+        return await self._send(Command(ActionType.TYPE, text=text))
+
+    async def scroll(self, dx: int = 0, dy: int = 100) -> Result:
+        return await self._send(Command(ActionType.SCROLL, delta_x=dx, delta_y=dy))
+
+    async def screenshot(
+        self,
+        path: str | os.PathLike | None = None,
+        *,
+        mkdir: bool = True,
+    ) -> bytes:
+        """
+        Grab a **JPEG** screenshot.
+
+        Parameters
+        path:
+            Optional file destination. If provided the image is written to disk
+            *and* the raw bytes are still returned.
+        mkdir:
+            Automatically create parent folders if they do not exist.
+        """
+        res = await self._send(Command(ActionType.SCREENSHOT))
+        if not (res.success and res.image):
+            raise ScreenshotFailed(res.error_message or "unknown error")
+
+        if path is not None:
+            from pathlib import Path
+
+            p = Path(path)
+            if mkdir:
+                p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_bytes(res.image)
+        return res.image
+
+    async def set_viewport(self, *, width: int, height: int) -> Result:
+        return await self._send(
+            Command(ActionType.SET_VIEWPORT_SIZE, width=width, height=height)
+        )
+
+    async def _send(self, cmd: Command) -> Result:
+        if self._ws is None:
+            raise RuntimeError("Waypoint must be used inside 'async with'")
+        res = await self._ws.send(cmd)
+        if not res.success:
+            log.warning("Command %s failed: %s", cmd.action_type, res.error_message)
+        return res

tzafon/exceptions.py

@@ -0,0 +1,6 @@
+class WaypointError(Exception):
+    """Base for all SDK exceptions."""
+
+
+class ScreenshotFailed(WaypointError):
+    """Raised when screenshot returns success=False."""

tzafon/models.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+import json
+import base64
+from dataclasses import dataclass, asdict
+from enum import Enum
+from typing import Optional, Dict, Any, Self
+
+
+class ActionType(str, Enum):
+    CLICK = "click"
+    TYPE = "type"
+    SCROLL = "scroll"
+    GOTO = "goto"
+    SCREENSHOT = "screenshot"
+    SET_VIEWPORT_SIZE = "set_viewport_size"
+
+
+@dataclass(slots=True)
+class Command:
+    action_type: ActionType
+    # optional payload
+    x: Optional[float] = None
+    y: Optional[float] = None
+    text: Optional[str] = None
+    delta_x: Optional[int] = None
+    delta_y: Optional[int] = None
+    url: Optional[str] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
+    timeout: int = 5000  # ms
+
+    @classmethod
+    def load(cls, body: bytes) -> Self:
+        data = json.loads(body.decode("utf-8"))
+        action_str = data.pop("action_type", None)
+        if action_str is None:
+            raise ValueError("Command missing 'action_type'")
+        try:
+            action_enum = ActionType(action_str)
+        except ValueError as e:
+            raise ValueError(f"Unknown action_type '{action_str}'") from e
+        return cls(action_type=action_enum, **data)
+
+    def dump(self) -> bytes:
+        d = asdict(self)
+        d["action_type"] = self.action_type.value
+        d = {k: v for k, v in d.items() if v is not None}
+        return json.dumps(d).encode("utf-8")
+
+
+@dataclass(slots=True)
+class Result:
+    success: bool
+    image: Optional[bytes] = None  # jpeg bytes
+    error_message: Optional[str] = None
+
+    @classmethod
+    def load(cls, body: bytes) -> Self:
+        data = json.loads(body.decode("utf-8"))
+        img_b64 = data.get("image")
+        img = base64.b64decode(img_b64) if img_b64 else None
+        return cls(
+            success=data.get("success", False),
+            image=img,
+            error_message=data.get("error_message"),
+        )
+
+    def dump(self) -> bytes:
+        d: Dict[str, Any] = {
+            "success": self.success,
+            "error_message": self.error_message,
+            "image": base64.b64encode(self.image).decode() if self.image else None,
+        }
+        return json.dumps({k: v for k, v in d.items() if v is not None}).encode()
+
+    def __str__(self) -> str:
+        ok = "✅" if self.success else "❌"
+        img = "🖼️" if self.image else "—"
+        return f"<Result {ok} image:{img} msg:{self.error_message!r}>"

tzafon-0.1.1.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: tzafon
+Version: 0.1.1
+Summary: Tzafon Waypoint – browser automation
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: twine>=6.1.0
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# Tzafon Waypoint
+
+A Python client for interacting with the tzafon.ai API for web automation.
+
+## Installation
+
+```bash
+pip install tzafon
+```
+
+## Usage
+
+```python
+import asyncio
+from tzafon import Waypoint
+
+async def main():
+    async with Waypoint(token="wpk_your_token_here") as wp:
+        # Navigate to a website
+        await wp.goto("https://example.com")
+
+        # Take a screenshot
+        image_bytes = await wp.screenshot("screenshot.jpg")
+
+        # Click at a specific position
+        await wp.click(100, 200)
+
+        # Type some text
+        await wp.type("Hello world")
+
+        # Scroll down
+        await wp.scroll(dy=200)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Features
+
+- Web navigation
+- Screenshots
+- Clicking and typing
+- Scrolling
+- Viewport control
+
+## License
+
+MIT

tzafon-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+tzafon/__init__.py,sha256=QpZABzfciDC1uUdoRHp5tW0694ZJGtHNF9ieGilnt94,53
+tzafon/_connection.py,sha256=HmmnHjO0N9pN3esCsVucws7lm1ZfyB6F0G8GMZoOCXw,1602
+tzafon/client.py,sha256=NUwXgrGPhoFbmHq122ZtSLBJvs2hiz1d8EbaRsGDW8o,3149
+tzafon/exceptions.py,sha256=SeeZRBAsyeogXXcfF3b3IaKUsehWNeNZAgxbmrzjI48,168
+tzafon/models.py,sha256=woHESkPE3R2TbiQoZjlknz7VR938WU5ZYlPFCh0Td9U,2428
+tzafon-0.1.1.dist-info/METADATA,sha256=nJmiwa8WRJFuQvhPtxTqWDl4ugGMlZsfmzXtBZo2ooE,1052
+tzafon-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+tzafon-0.1.1.dist-info/RECORD,,

tzafon-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any