tinyfish 0.2.2__py3-none-any.whl

tinyfish/_utils/exceptions.py

@@ -0,0 +1,159 @@
+"""Exception hierarchy for SDK errors.
+
+All exceptions inherit from SDKError for easy catching.
+
+Hierarchy:
+    SDKError
+    ├─ SSEParseError
+    └─ APIError
+       ├─ APIConnectionError
+       │  └─ APITimeoutError
+       └─ APIStatusError
+          ├─ BadRequestError (400)
+          ├─ AuthenticationError (401)
+          ├─ PermissionDeniedError (403)
+          ├─ NotFoundError (404)
+          ├─ RequestTimeoutError (408)
+          ├─ ConflictError (409)
+          ├─ UnprocessableEntityError (422)
+          ├─ RateLimitError (429)
+          └─ InternalServerError (500+)
+"""
+
+from __future__ import annotations
+
+import httpx
+
+
+class SDKError(Exception):
+    """Base exception for all SDK errors."""
+
+    pass
+
+
+class SSEParseError(SDKError):
+    """Raised when a malformed SSE event cannot be parsed.
+
+    Attributes:
+        line: The raw SSE data line that failed to parse.
+    """
+
+    def __init__(self, message: str, *, line: str) -> None:
+        super().__init__(message)
+        self.line = line
+
+    def __repr__(self) -> str:
+        return f"SSEParseError(message={str(self)!r}, line={self.line!r})"
+
+
+class APIError(SDKError):
+    """Base exception for all API-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request: httpx.Request | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = request
+        self.response = response
+
+
+class APIConnectionError(APIError):
+    """Network or connection failure."""
+
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    """Request timeout."""
+
+    pass
+
+
+class APIStatusError(APIError):
+    """API returned error status code (4xx or 5xx)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: httpx.Response,
+        status_code: int,
+        request: httpx.Request | None = None,
+    ) -> None:
+        super().__init__(message, request=request, response=response)
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(status_code={self.status_code}, message={self.message!r})"
+
+
+class BadRequestError(APIStatusError):
+    """400 Bad Request."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.BAD_REQUEST), request=request)
+
+
+class AuthenticationError(APIStatusError):
+    """401 Unauthorized."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.UNAUTHORIZED), request=request)
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 Forbidden."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.FORBIDDEN), request=request)
+
+
+class NotFoundError(APIStatusError):
+    """404 Not Found."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.NOT_FOUND), request=request)
+
+
+class RequestTimeoutError(APIStatusError):
+    """408 Request Timeout."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.REQUEST_TIMEOUT), request=request)
+
+
+class ConflictError(APIStatusError):
+    """409 Conflict."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.CONFLICT), request=request)
+
+
+class UnprocessableEntityError(APIStatusError):
+    """422 Unprocessable Entity."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.UNPROCESSABLE_ENTITY), request=request)
+
+
+class RateLimitError(APIStatusError):
+    """429 Too Many Requests."""
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=int(httpx.codes.TOO_MANY_REQUESTS), request=request)
+
+
+class InternalServerError(APIStatusError):
+    """500+ Server Error.
+
+    Catches all 5xx status codes. The actual status code (500, 502, 503, etc.)
+    is preserved in the status_code attribute for accurate monitoring/alerting.
+    """
+
+    def __init__(self, message: str, *, response: httpx.Response, request: httpx.Request | None = None) -> None:
+        super().__init__(message, response=response, status_code=response.status_code, request=request)

tinyfish/_utils/resource.py

@@ -0,0 +1,23 @@
+"""Base classes for API resources."""
+
+from .client import BaseAsyncAPIClient, BaseSyncAPIClient
+
+
+class BaseSyncAPIResource:
+    """Base class for synchronous API resources."""
+
+    def __init__(self, client: BaseSyncAPIClient) -> None:
+        self._client = client
+        self._get = client._get
+        self._post = client._post
+        self._post_stream = client._post_stream
+
+
+class BaseAsyncAPIResource:
+    """Base class for asynchronous API resources."""
+
+    def __init__(self, client: BaseAsyncAPIClient) -> None:
+        self._client = client
+        self._get = client._get
+        self._post = client._post
+        self._post_stream = client._post_stream

tinyfish/_utils/sse_parser.py

@@ -0,0 +1,62 @@
+"""Simple Server-Sent Events (SSE) parser."""
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from .exceptions import SSEParseError
+
+_DATA_PREFIX = "data:"
+
+
+def parse_sse_line_stream(lines: Iterator[str]) -> Iterator[dict[str, Any]]:
+    """
+    Parse SSE stream and yield JSON event data.
+
+    SSE Format:
+        event: STARTED
+        data: {"type":"STARTED","run_id":"123",...}
+
+        event: PROGRESS
+        data: {"type":"PROGRESS",...}
+
+    Yields:
+        Parsed JSON objects from 'data:' lines
+    """
+    for line in lines:
+        line = line.strip()
+
+        # Skip empty lines and comments
+        if not line or line.startswith(":"):
+            continue
+
+        # Parse data lines (the actual event payload)
+        if line.startswith("data:"):
+            data_str = line[len(_DATA_PREFIX) :].strip()  # Remove 'data:' prefix
+
+            try:
+                event_data = json.loads(data_str)
+                yield event_data
+            except json.JSONDecodeError as e:
+                raise SSEParseError(f"Malformed JSON in SSE event: {e}", line=line) from e
+
+        # Ignore 'event:', 'id:', 'retry:' lines for now
+        # (we get event type from the JSON data itself)
+
+
+async def async_parse_sse_line_stream(lines: AsyncIterator[str]) -> AsyncIterator[dict[str, Any]]:
+    """Async version of parse_sse_line_stream."""
+    async for line in lines:
+        line = line.strip()
+
+        if not line or line.startswith(":"):
+            continue
+
+        if line.startswith("data:"):
+            data_str = line[len(_DATA_PREFIX) :].strip()
+
+            try:
+                event_data = json.loads(data_str)
+                yield event_data
+            except json.JSONDecodeError as e:
+                raise SSEParseError(f"Malformed JSON in SSE event: {e}", line=line) from e

tinyfish/agent/__init__.py

@@ -0,0 +1,368 @@
+"""Browser automation resource."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Any
+
+from tinyfish._utils.resource import BaseAsyncAPIResource, BaseSyncAPIResource
+from tinyfish._utils.sse_parser import async_parse_sse_line_stream, parse_sse_line_stream
+
+from .types import (
+    AgentRunAsyncResponse,
+    AgentRunResponse,
+    AgentRunWithStreamingResponse,
+    BrowserProfile,
+    CompleteEvent,
+    HeartbeatEvent,
+    ProgressEvent,
+    ProxyConfig,
+    StartedEvent,
+    StreamingUrlEvent,
+)
+
+
+def _build_run_body(
+    goal: str,
+    url: str,
+    browser_profile: BrowserProfile | None,
+    proxy_config: ProxyConfig | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"goal": goal, "url": url}
+    if browser_profile is not None:
+        body["browser_profile"] = browser_profile
+    if proxy_config is not None:
+        body["proxy_config"] = proxy_config.model_dump(exclude_none=True)
+    return body
+
+
+class AgentStream:
+    """Context manager for a synchronous streaming agent run.
+
+    Use as::
+
+        with client.agent.stream(goal=..., url=...) as stream:
+            for event in stream:
+                ...
+    """
+
+    def __init__(self, iterator: Iterator[AgentRunWithStreamingResponse]) -> None:
+        self._iterator = iterator
+
+    def __enter__(self) -> AgentStream:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self._iterator.close()
+
+    def __iter__(self) -> Iterator[AgentRunWithStreamingResponse]:
+        return self._iterator
+
+
+class AsyncAgentStream:
+    """Context manager for an asynchronous streaming agent run.
+
+    Use as::
+
+        async with client.agent.stream(goal=..., url=...) as stream:
+            async for event in stream:
+                ...
+    """
+
+    def __init__(self, iterator: AsyncIterator[AgentRunWithStreamingResponse]) -> None:
+        self._iterator = iterator
+
+    async def __aenter__(self) -> AsyncAgentStream:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self._iterator.aclose()
+
+    def __aiter__(self) -> AsyncIterator[AgentRunWithStreamingResponse]:
+        return self._iterator
+
+
+class AgentResource(BaseSyncAPIResource):
+    """Browser automation methods."""
+
+    def run(
+        self,
+        *,
+        goal: str,
+        url: str,
+        browser_profile: BrowserProfile | None = None,
+        proxy_config: ProxyConfig | None = None,
+    ) -> AgentRunResponse:
+        """Run a browser automation and wait for it to finish.
+
+        Blocks until the automation completes or fails. Use `queue()` instead
+        if you want to kick off the run and check back later.
+
+        Args:
+            goal: Natural language description of what to do on the page.
+            url: The URL to open the browser on.
+            browser_profile: "lite" (default) or "stealth" (anti-detection).
+            proxy_config: Optional proxy settings (enabled, country_code).
+
+        Returns:
+            AgentRunResponse with status, result, and timing info.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+            InternalServerError: Something went wrong on the server.
+        """
+        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        return self._post("/v1/automation/run", json=body, cast_to=AgentRunResponse)
+
+    def queue(
+        self,
+        *,
+        goal: str,
+        url: str,
+        browser_profile: BrowserProfile | None = None,
+        proxy_config: ProxyConfig | None = None,
+    ) -> AgentRunAsyncResponse:
+        """Queue a browser automation and return immediately.
+
+        Does not wait for the run to complete — returns a run_id straight away.
+        Use `client.runs.get(run_id)` to poll for the result.
+
+        Args:
+            goal: Natural language description of what to do on the page.
+            url: The URL to open the browser on.
+            browser_profile: "lite" (default) or "stealth" (anti-detection).
+            proxy_config: Optional proxy settings (enabled, country_code).
+
+        Returns:
+            AgentRunAsyncResponse with the run_id to poll later.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+            InternalServerError: Something went wrong on the server.
+        """
+        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        return self._post("/v1/automation/run-async", json=body, cast_to=AgentRunAsyncResponse)
+
+    def stream(
+        self,
+        *,
+        goal: str,
+        url: str,
+        browser_profile: BrowserProfile | None = None,
+        proxy_config: ProxyConfig | None = None,
+        on_started: Callable[[StartedEvent], None] | None = None,
+        on_streaming_url: Callable[[StreamingUrlEvent], None] | None = None,
+        on_progress: Callable[[ProgressEvent], None] | None = None,
+        on_heartbeat: Callable[[HeartbeatEvent], None] | None = None,
+        on_complete: Callable[[CompleteEvent], None] | None = None,
+    ) -> AgentStream:
+        """Stream live events from a browser automation run.
+
+        Returns a context manager that yields SSE events in real time:
+        STARTED → STREAMING_URL → PROGRESS (repeated) → COMPLETE.
+
+        Use the on_* callbacks for a reactive style, or iterate over
+        the stream for a sequential style::
+
+            with client.agent.stream(goal=..., url=...) as stream:
+                for event in stream:
+                    if isinstance(event, ProgressEvent):
+                        print(event.purpose)
+
+        Args:
+            goal: Natural language description of what to do on the page.
+            url: The URL to open the browser on.
+            browser_profile: "lite" (default) or "stealth" (anti-detection).
+            proxy_config: Optional proxy settings (enabled, country_code).
+            on_started: Called when the run starts (receives StartedEvent).
+            on_streaming_url: Called with the live browser stream URL (receives StreamingUrlEvent).
+            on_progress: Called on each automation step (receives ProgressEvent).
+            on_heartbeat: Called on keepalive pings (receives HeartbeatEvent).
+            on_complete: Called when the run finishes (receives CompleteEvent).
+
+        Returns:
+            AgentStream context manager — iterate over it to receive events.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+            InternalServerError: Something went wrong on the server.
+        """
+        body = _build_run_body(goal, url, browser_profile, proxy_config)
+
+        def _generate() -> Iterator[AgentRunWithStreamingResponse]:
+            lines = self._post_stream("/v1/automation/run-sse", json=body)
+            for event_data in parse_sse_line_stream(lines):
+                event_type = event_data.get("type")
+                if event_type == "STARTED":
+                    event = StartedEvent.model_validate(event_data)
+                    if on_started:
+                        on_started(event)
+                    yield event
+                elif event_type == "STREAMING_URL":
+                    event = StreamingUrlEvent.model_validate(event_data)
+                    if on_streaming_url:
+                        on_streaming_url(event)
+                    yield event
+                elif event_type == "PROGRESS":
+                    event = ProgressEvent.model_validate(event_data)
+                    if on_progress:
+                        on_progress(event)
+                    yield event
+                elif event_type == "HEARTBEAT":
+                    event = HeartbeatEvent.model_validate(event_data)
+                    if on_heartbeat:
+                        on_heartbeat(event)
+                    yield event
+                elif event_type == "COMPLETE":
+                    event = CompleteEvent.model_validate(event_data)
+                    if on_complete:
+                        on_complete(event)
+                    yield event
+
+        return AgentStream(_generate())
+
+
+class AsyncAgentResource(BaseAsyncAPIResource):
+    """Async browser automation methods."""
+
+    async def run(
+        self,
+        *,
+        goal: str,
+        url: str,
+        browser_profile: BrowserProfile | None = None,
+        proxy_config: ProxyConfig | None = None,
+    ) -> AgentRunResponse:
+        """Run a browser automation and wait for it to finish.
+
+        Async version of `AgentResource.run()`. Awaits until the automation
+        completes or fails. Use `queue()` instead if you want to fire and poll.
+
+        Args:
+            goal: Natural language description of what to do on the page.
+            url: The URL to open the browser on.
+            browser_profile: "lite" (default) or "stealth" (anti-detection).
+            proxy_config: Optional proxy settings (enabled, country_code).
+
+        Returns:
+            AgentRunResponse with status, result, and timing info.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+            InternalServerError: Something went wrong on the server.
+        """
+        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        return await self._post("/v1/automation/run", json=body, cast_to=AgentRunResponse)
+
+    async def queue(
+        self,
+        *,
+        goal: str,
+        url: str,
+        browser_profile: BrowserProfile | None = None,
+        proxy_config: ProxyConfig | None = None,
+    ) -> AgentRunAsyncResponse:
+        """Queue a browser automation and return immediately.
+
+        Async version of `AgentResource.queue()`. Returns a run_id without
+        waiting for completion. Use `client.runs.get(run_id)` to poll.
+
+        Args:
+            goal: Natural language description of what to do on the page.
+            url: The URL to open the browser on.
+            browser_profile: "lite" (default) or "stealth" (anti-detection).
+            proxy_config: Optional proxy settings (enabled, country_code).
+
+        Returns:
+            AgentRunAsyncResponse with the run_id to poll later.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+            InternalServerError: Something went wrong on the server.
+        """
+        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        return await self._post("/v1/automation/run-async", json=body, cast_to=AgentRunAsyncResponse)
+
+    def stream(
+        self,
+        *,
+        goal: str,
+        url: str,
+        browser_profile: BrowserProfile | None = None,
+        proxy_config: ProxyConfig | None = None,
+        on_started: Callable[[StartedEvent], None] | None = None,
+        on_streaming_url: Callable[[StreamingUrlEvent], None] | None = None,
+        on_progress: Callable[[ProgressEvent], None] | None = None,
+        on_heartbeat: Callable[[HeartbeatEvent], None] | None = None,
+        on_complete: Callable[[CompleteEvent], None] | None = None,
+    ) -> AsyncAgentStream:
+        """Stream live events from a browser automation run.
+
+        Returns an async context manager that yields SSE events in real time:
+        STARTED → STREAMING_URL → PROGRESS (repeated) → COMPLETE.
+
+        Use the on_* callbacks for a reactive style, or iterate over
+        the stream for a sequential style::
+
+            async with client.agent.stream(goal=..., url=...) as stream:
+                async for event in stream:
+                    if isinstance(event, ProgressEvent):
+                        print(event.purpose)
+
+        Args:
+            goal: Natural language description of what to do on the page.
+            url: The URL to open the browser on.
+            browser_profile: "lite" (default) or "stealth" (anti-detection).
+            proxy_config: Optional proxy settings (enabled, country_code).
+            on_started: Called when the run starts (receives StartedEvent).
+            on_streaming_url: Called with the live browser stream URL (receives StreamingUrlEvent).
+            on_progress: Called on each automation step (receives ProgressEvent).
+            on_heartbeat: Called on keepalive pings (receives HeartbeatEvent).
+            on_complete: Called when the run finishes (receives CompleteEvent).
+
+        Returns:
+            AsyncAgentStream context manager — async-iterate over it to receive events.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+            InternalServerError: Something went wrong on the server.
+        """
+        body = _build_run_body(goal, url, browser_profile, proxy_config)
+
+        async def _generate() -> AsyncIterator[AgentRunWithStreamingResponse]:
+            lines = self._post_stream("/v1/automation/run-sse", json=body)
+            async for event_data in async_parse_sse_line_stream(lines):
+                event_type = event_data.get("type")
+                if event_type == "STARTED":
+                    event = StartedEvent.model_validate(event_data)
+                    if on_started:
+                        on_started(event)
+                    yield event
+                elif event_type == "STREAMING_URL":
+                    event = StreamingUrlEvent.model_validate(event_data)
+                    if on_streaming_url:
+                        on_streaming_url(event)
+                    yield event
+                elif event_type == "PROGRESS":
+                    event = ProgressEvent.model_validate(event_data)
+                    if on_progress:
+                        on_progress(event)
+                    yield event
+                elif event_type == "HEARTBEAT":
+                    event = HeartbeatEvent.model_validate(event_data)
+                    if on_heartbeat:
+                        on_heartbeat(event)
+                    yield event
+                elif event_type == "COMPLETE":
+                    event = CompleteEvent.model_validate(event_data)
+                    if on_complete:
+                        on_complete(event)
+                    yield event
+
+        return AsyncAgentStream(_generate())