reader-py 0.2.0__py3-none-any.whl

reader_py/__init__.py

@@ -0,0 +1,87 @@
+"""Reader Python SDK."""
+
+from .async_client import AsyncReaderClient
+from .client import ReaderClient
+from .errors import (
+    ConcurrencyLimitedError,
+    ConflictError,
+    InsufficientCreditsError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitedError,
+    ReaderApiError,
+    ReaderError,
+    ScrapeTimeoutError,
+    UnauthenticatedError,
+    UpstreamUnavailableError,
+    UrlBlockedError,
+    to_reader_api_error,
+)
+from .types import (
+    CreditInfo,
+    Credits,
+    DoneEvent,
+    ErrorEvent,
+    Job,
+    JobInfo,
+    JobReadResult,
+    Page,
+    PageEvent,
+    Pagination,
+    ProgressEvent,
+    ReadParams,
+    ReadResult,
+    ScrapeMetadata,
+    ScrapeReadResult,
+    ScrapeResult,
+    SessionInfo,
+    StopSessionResult,
+    StreamEvent,
+    UsageEntry,
+    WebhookConfig,
+)
+
+__all__ = [
+    "ReaderClient",
+    "AsyncReaderClient",
+    # Errors
+    "ReaderApiError",
+    "ReaderError",
+    "InvalidRequestError",
+    "UnauthenticatedError",
+    "InsufficientCreditsError",
+    "UrlBlockedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitedError",
+    "ConcurrencyLimitedError",
+    "InternalServerError",
+    "UpstreamUnavailableError",
+    "ScrapeTimeoutError",
+    "to_reader_api_error",
+    # Types
+    "ReadParams",
+    "ReadResult",
+    "ScrapeReadResult",
+    "JobReadResult",
+    "ScrapeResult",
+    "ScrapeMetadata",
+    "Page",
+    "Job",
+    "JobInfo",
+    "Credits",
+    "CreditInfo",
+    "Pagination",
+    "UsageEntry",
+    # Stream events
+    "StreamEvent",
+    "ProgressEvent",
+    "PageEvent",
+    "ErrorEvent",
+    "DoneEvent",
+    "WebhookConfig",
+    # Sessions
+    "SessionInfo",
+    "StopSessionResult",
+]

reader_py/async_client.py

@@ -0,0 +1,373 @@
+"""Async Reader SDK client."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any, AsyncIterator, Optional
+
+import httpx
+
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_POLL_TIMEOUT,
+    DEFAULT_STREAM_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    _parse_sse_event,
+    _to_camel_case,
+    _to_snake_case,
+)
+from .errors import (
+    RateLimitedError,
+    ReaderApiError,
+    ScrapeTimeoutError,
+    to_reader_api_error,
+)
+from .types import (
+    Credits,
+    DoneEvent,
+    Job,
+    JobReadResult,
+    Page,
+    ReadParams,
+    ReadResult,
+    ScrapeReadResult,
+    ScrapeResult,
+    SessionInfo,
+    StopSessionResult,
+    StreamEvent,
+)
+
+
+class AsyncReaderClient:
+    """Async Reader API client.
+
+    Example::
+
+        async with AsyncReaderClient(api_key="rdr_your_key") as client:
+            result = await client.read(url="https://example.com")
+            if result.kind == "scrape":
+                print(result.data.markdown)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        if not api_key:
+            raise ReaderApiError(
+                "API key is required",
+                code="unauthenticated",
+                http_status=401,
+            )
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "x-api-key": api_key,
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+        self.sessions = AsyncSessionsAPI(self._request)
+
+    async def read(self, **kwargs: Any) -> ReadResult:
+        """Read (scrape, batch, or crawl) URLs."""
+        params = ReadParams(**kwargs)
+        body = params.model_dump(exclude_none=True)
+        api_body = _to_camel_case(body)
+
+        envelope = await self._request("POST", "/v1/read", json=api_body)
+        data = envelope.get("data") or {}
+
+        if "status" in data and "mode" in data and "metadata" not in data:
+            job = await self.wait_for_job(str(data["id"]))
+            return JobReadResult(kind="job", data=job)
+
+        scrape = ScrapeResult(**_to_snake_case(data))
+        return ScrapeReadResult(kind="scrape", data=scrape)
+
+    async def get_job(
+        self,
+        job_id: str,
+        skip: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> tuple[Job, bool]:
+        params: dict[str, Any] = {}
+        if skip is not None:
+            params["skip"] = skip
+        if limit is not None:
+            params["limit"] = limit
+
+        envelope = await self._request("GET", f"/v1/jobs/{job_id}", params=params or None)
+        job = Job(**_to_snake_case(envelope["data"]))
+        pagination = envelope.get("pagination") or {}
+        return job, bool(pagination.get("hasMore"))
+
+    async def get_all_job_results(self, job_id: str) -> list[Page]:
+        pages: list[Page] = []
+        skip = 0
+        limit = 100
+        while True:
+            job, has_more = await self.get_job(job_id, skip=skip, limit=limit)
+            pages.extend(job.results)
+            if not has_more:
+                break
+            skip += limit
+        return pages
+
+    async def cancel_job(self, job_id: str) -> None:
+        await self._request("DELETE", f"/v1/jobs/{job_id}")
+
+    async def retry_job(self, job_id: str) -> dict[str, Any]:
+        envelope = await self._request("POST", f"/v1/jobs/{job_id}/retry")
+        return envelope["data"]
+
+    async def get_credits(self) -> Credits:
+        envelope = await self._request("GET", "/v1/usage/credits")
+        return Credits(**_to_snake_case(envelope["data"]))
+
+    async def wait_for_job(
+        self,
+        job_id: str,
+        poll_interval: int = DEFAULT_POLL_INTERVAL,
+        timeout: int = DEFAULT_POLL_TIMEOUT,
+    ) -> Job:
+        start = time.time()
+        while time.time() - start < timeout:
+            job, _ = await self.get_job(job_id, limit=1)
+            if job.status in ("completed", "failed", "cancelled"):
+                if job.status == "completed":
+                    job.results = await self.get_all_job_results(job_id)
+                return job
+            await asyncio.sleep(poll_interval)
+
+        raise ScrapeTimeoutError(
+            f"Job {job_id} polling timed out after {timeout}s",
+            code="scrape_timeout",
+            http_status=504,
+            details={"timeoutMs": timeout * 1000},
+        )
+
+    async def stream(
+        self,
+        job_id: str,
+        timeout: int = DEFAULT_STREAM_TIMEOUT,
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream real-time events for a running job via Server-Sent Events.
+
+        Yields parsed :class:`StreamEvent` instances as the job makes progress.
+        The stream closes automatically when the job reaches a terminal state.
+
+        Example::
+
+            async for event in client.stream(job_id):
+                if event.type == "page":
+                    print("page:", event.data.url)
+                elif event.type == "done":
+                    break
+        """
+        url = f"{self._base_url}/v1/jobs/{job_id}/stream"
+        headers = {"x-api-key": self._api_key, "Accept": "text/event-stream"}
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(None, connect=10.0),
+            ) as sse_client:
+                async with sse_client.stream("GET", url, headers=headers) as response:
+                    if response.status_code >= 400:
+                        body_bytes = b""
+                        async for chunk in response.aiter_bytes():
+                            body_bytes += chunk
+                        try:
+                            body = json.loads(body_bytes.decode("utf-8"))
+                        except (ValueError, UnicodeDecodeError):
+                            body = None
+                        request_id = response.headers.get("x-request-id")
+                        if (
+                            isinstance(body, dict)
+                            and "error" in body
+                            and isinstance(body["error"], dict)
+                        ):
+                            raise to_reader_api_error(
+                                body["error"], response.status_code, request_id
+                            )
+                        raise ReaderApiError(
+                            f"Stream failed with status {response.status_code}",
+                            code="internal_error",
+                            http_status=response.status_code,
+                            request_id=request_id,
+                        )
+
+                    async for event in _parse_async_sse_stream(
+                        response.aiter_lines(),
+                        timeout,
+                    ):
+                        yield event
+        except httpx.TimeoutException as exc:
+            raise ScrapeTimeoutError(
+                f"Job {job_id} stream timed out",
+                code="scrape_timeout",
+                http_status=504,
+            ) from exc
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Send a request with retries on transient failures.
+
+        Retries on 5xx and 429 with exponential backoff (1s, 2s, 4s...).
+        For 429 the ``Retry-After`` header (seconds) overrides the backoff.
+        Client errors (4xx other than 429) are raised immediately.
+        """
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                res = await self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                last_error = ScrapeTimeoutError(
+                    "Request timed out",
+                    code="scrape_timeout",
+                    http_status=504,
+                )
+                last_error.__cause__ = exc
+            except httpx.ConnectError as exc:
+                last_error = ReaderApiError(
+                    "Connection failed",
+                    code="upstream_unavailable",
+                    http_status=502,
+                )
+                last_error.__cause__ = exc
+            else:
+                request_id = res.headers.get("x-request-id")
+                try:
+                    data = res.json()
+                except Exception:
+                    data = None
+
+                if res.status_code < 400:
+                    if not isinstance(data, dict):
+                        raise ReaderApiError(
+                            "Invalid response from Reader API",
+                            code="internal_error",
+                            http_status=res.status_code,
+                            request_id=request_id,
+                        )
+                    return data
+
+                if isinstance(data, dict) and isinstance(data.get("error"), dict):
+                    err: ReaderApiError = to_reader_api_error(
+                        data["error"], res.status_code, request_id
+                    )
+                else:
+                    err = ReaderApiError(
+                        f"Request failed with status {res.status_code}",
+                        code="internal_error",
+                        http_status=res.status_code,
+                        request_id=request_id,
+                    )
+
+                if res.status_code < 500 and res.status_code != 429:
+                    raise err
+
+                if isinstance(err, RateLimitedError) and err.retry_after_seconds:
+                    if attempt < self._max_retries:
+                        await asyncio.sleep(err.retry_after_seconds)
+                        last_error = err
+                        continue
+
+                last_error = err
+
+            if attempt < self._max_retries:
+                await asyncio.sleep(2 ** attempt)
+
+        assert last_error is not None
+        raise last_error
+
+
+async def _parse_async_sse_stream(
+    lines: AsyncIterator[str],
+    timeout: int,
+) -> AsyncIterator[StreamEvent]:
+    """Async variant of client._parse_sse_stream — accumulates SSE lines
+    into frames and yields parsed StreamEvents. Uses the same frame parser
+    helper (_parse_sse_event) as the sync client.
+    """
+    start = time.time()
+    current_event = ""
+    current_data: list[str] = []
+
+    async for line in lines:
+        if time.time() - start > timeout:
+            raise ScrapeTimeoutError(
+                "Stream read timed out",
+                code="scrape_timeout",
+                http_status=504,
+            )
+
+        if line == "":
+            if current_event and current_data:
+                parsed = _parse_sse_event(current_event, "\n".join(current_data))
+                if parsed is not None:
+                    yield parsed
+                    if isinstance(parsed, DoneEvent):
+                        return
+            current_event = ""
+            current_data = []
+            continue
+
+        if line.startswith(":"):
+            continue
+
+        if line.startswith("event:"):
+            current_event = line[len("event:") :].strip()
+        elif line.startswith("data:"):
+            current_data.append(line[len("data:") :].strip())
+
+
+class AsyncSessionsAPI:
+    """Browser sessions API (async)."""
+
+    def __init__(self, request_fn: Any):
+        self._request = request_fn
+
+    async def create(self, **kwargs: Any) -> SessionInfo:
+        """Create a browser session. Returns a CDP WebSocket URL."""
+        body = _to_camel_case(kwargs) if kwargs else {}
+        envelope = await self._request("POST", "/v1/sessions", json=body)
+        return SessionInfo(**_to_snake_case(envelope["data"]))
+
+    async def get(self, session_id: str) -> SessionInfo:
+        """Get session status."""
+        envelope = await self._request("GET", f"/v1/sessions/{session_id}")
+        return SessionInfo(**_to_snake_case(envelope["data"]))
+
+    async def stop(self, session_id: str) -> StopSessionResult:
+        """Stop a browser session."""
+        envelope = await self._request("DELETE", f"/v1/sessions/{session_id}")
+        return StopSessionResult(**_to_snake_case(envelope["data"]))
+
+    async def list(self) -> list[SessionInfo]:
+        """List active sessions."""
+        envelope = await self._request("GET", "/v1/sessions")
+        data = envelope["data"]
+        return [SessionInfo(**_to_snake_case(s)) for s in data]

reader_py/client.py

@@ -0,0 +1,434 @@
+"""Synchronous Reader SDK client."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Iterator, Optional
+
+import httpx
+
+from .errors import (
+    RateLimitedError,
+    ReaderApiError,
+    ScrapeTimeoutError,
+    to_reader_api_error,
+)
+from .types import (
+    Credits,
+    DoneEvent,
+    ErrorEvent,
+    Job,
+    JobReadResult,
+    Page,
+    PageEvent,
+    ProgressEvent,
+    ReadParams,
+    ReadResult,
+    ScrapeReadResult,
+    ScrapeResult,
+    SessionInfo,
+    StopSessionResult,
+    StreamEvent,
+)
+
+DEFAULT_BASE_URL = "https://api.reader.dev"
+DEFAULT_TIMEOUT = 60
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_POLL_INTERVAL = 2
+DEFAULT_POLL_TIMEOUT = 300
+DEFAULT_STREAM_TIMEOUT = 600  # per-job stream can run longer than a poll
+
+
+class ReaderClient:
+    """Synchronous Reader API client.
+
+    Example::
+
+        client = ReaderClient(api_key="rdr_your_key")
+        result = client.read(url="https://example.com")
+        if result.kind == "scrape":
+            print(result.data.markdown)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        if not api_key:
+            raise ReaderApiError(
+                "API key is required",
+                code="unauthenticated",
+                http_status=401,
+            )
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "x-api-key": api_key,
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+        self.sessions = SessionsAPI(self._request)
+
+    def read(self, **kwargs: Any) -> ReadResult:
+        """Read (scrape, batch, or crawl) URLs.
+
+        Single URL → sync scrape, returned immediately.
+        Multiple URLs or ``max_depth``/``max_pages`` → async job, polled to
+        completion.
+        """
+        params = ReadParams(**kwargs)
+        body = params.model_dump(exclude_none=True)
+        api_body = _to_camel_case(body)
+
+        envelope = self._request("POST", "/v1/read", json=api_body)
+        data = envelope.get("data") or {}
+
+        # Async job: data has status + mode, no markdown/metadata
+        if "status" in data and "mode" in data and "metadata" not in data:
+            job = self.wait_for_job(str(data["id"]))
+            return JobReadResult(kind="job", data=job)
+
+        # Sync scrape
+        scrape = ScrapeResult(**_to_snake_case(data))
+        return ScrapeReadResult(kind="scrape", data=scrape)
+
+    def get_job(
+        self,
+        job_id: str,
+        skip: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> tuple[Job, bool]:
+        """Get a single page of job results. Returns ``(job, has_more)``."""
+        params: dict[str, Any] = {}
+        if skip is not None:
+            params["skip"] = skip
+        if limit is not None:
+            params["limit"] = limit
+
+        envelope = self._request("GET", f"/v1/jobs/{job_id}", params=params or None)
+        job = Job(**_to_snake_case(envelope["data"]))
+        pagination = envelope.get("pagination") or {}
+        return job, bool(pagination.get("hasMore"))
+
+    def get_all_job_results(self, job_id: str) -> list[Page]:
+        """Fetch every page result by following pagination."""
+        pages: list[Page] = []
+        skip = 0
+        limit = 100
+        while True:
+            job, has_more = self.get_job(job_id, skip=skip, limit=limit)
+            pages.extend(job.results)
+            if not has_more:
+                break
+            skip += limit
+        return pages
+
+    def cancel_job(self, job_id: str) -> None:
+        """Cancel a running job. Raises :class:`ConflictError` if terminal."""
+        self._request("DELETE", f"/v1/jobs/{job_id}")
+
+    def retry_job(self, job_id: str) -> dict[str, Any]:
+        """Retry the failed URLs in a job."""
+        envelope = self._request("POST", f"/v1/jobs/{job_id}/retry")
+        return envelope["data"]
+
+    def get_credits(self) -> Credits:
+        """Get the current credit balance for this workspace."""
+        envelope = self._request("GET", "/v1/usage/credits")
+        return Credits(**_to_snake_case(envelope["data"]))
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        poll_interval: int = DEFAULT_POLL_INTERVAL,
+        timeout: int = DEFAULT_POLL_TIMEOUT,
+    ) -> Job:
+        """Poll a job until it terminates. Collects all results when done."""
+        start = time.time()
+        while time.time() - start < timeout:
+            job, _ = self.get_job(job_id, limit=1)
+            if job.status in ("completed", "failed", "cancelled"):
+                if job.status == "completed":
+                    job.results = self.get_all_job_results(job_id)
+                return job
+            time.sleep(poll_interval)
+
+        raise ScrapeTimeoutError(
+            f"Job {job_id} polling timed out after {timeout}s",
+            code="scrape_timeout",
+            http_status=504,
+            details={"timeoutMs": timeout * 1000},
+        )
+
+    def stream(
+        self,
+        job_id: str,
+        timeout: int = DEFAULT_STREAM_TIMEOUT,
+    ) -> Iterator[StreamEvent]:
+        """Stream real-time events for a running job via Server-Sent Events.
+
+        Yields parsed :class:`StreamEvent` instances as the job makes progress.
+        The stream closes automatically when the job reaches a terminal state.
+
+        Example::
+
+            for event in client.stream(job_id):
+                if event.type == "page":
+                    print("page:", event.data.url)
+                elif event.type == "done":
+                    print("finished:", event.status)
+                    break
+        """
+        # SSE uses a long-lived connection; disconnect the default httpx
+        # read-timeout (otherwise idle keep-alives trigger a timeout).
+        url = f"{self._base_url}/v1/jobs/{job_id}/stream"
+        headers = {"x-api-key": self._api_key, "Accept": "text/event-stream"}
+
+        try:
+            with httpx.Client(timeout=httpx.Timeout(None, connect=10.0)) as sse_client:
+                with sse_client.stream("GET", url, headers=headers) as response:
+                    if response.status_code >= 400:
+                        # Drain the body so we can parse an error envelope
+                        body_bytes = b"".join(response.iter_bytes())
+                        try:
+                            body = json.loads(body_bytes.decode("utf-8"))
+                        except (ValueError, UnicodeDecodeError):
+                            body = None
+                        request_id = response.headers.get("x-request-id")
+                        if (
+                            isinstance(body, dict)
+                            and "error" in body
+                            and isinstance(body["error"], dict)
+                        ):
+                            raise to_reader_api_error(
+                                body["error"], response.status_code, request_id
+                            )
+                        raise ReaderApiError(
+                            f"Stream failed with status {response.status_code}",
+                            code="internal_error",
+                            http_status=response.status_code,
+                            request_id=request_id,
+                        )
+
+                    yield from _parse_sse_stream(response.iter_lines(), timeout)
+        except httpx.TimeoutException as exc:
+            raise ScrapeTimeoutError(
+                f"Job {job_id} stream timed out",
+                code="scrape_timeout",
+                http_status=504,
+            ) from exc
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # ── Internal ─────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Send a request with retries on transient failures.
+
+        Retries on 5xx and 429 with exponential backoff (1s, 2s, 4s...).
+        For 429 the ``Retry-After`` header (seconds) overrides the backoff.
+        Client errors (4xx other than 429) are raised immediately.
+        """
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                res = self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                last_error = ScrapeTimeoutError(
+                    "Request timed out",
+                    code="scrape_timeout",
+                    http_status=504,
+                )
+                last_error.__cause__ = exc
+            except httpx.ConnectError as exc:
+                last_error = ReaderApiError(
+                    "Connection failed",
+                    code="upstream_unavailable",
+                    http_status=502,
+                )
+                last_error.__cause__ = exc
+            else:
+                request_id = res.headers.get("x-request-id")
+                try:
+                    data = res.json()
+                except Exception:
+                    data = None
+
+                if res.status_code < 400:
+                    if not isinstance(data, dict):
+                        raise ReaderApiError(
+                            "Invalid response from Reader API",
+                            code="internal_error",
+                            http_status=res.status_code,
+                            request_id=request_id,
+                        )
+                    return data
+
+                # Error response — build typed exception
+                if isinstance(data, dict) and isinstance(data.get("error"), dict):
+                    err: ReaderApiError = to_reader_api_error(
+                        data["error"], res.status_code, request_id
+                    )
+                else:
+                    err = ReaderApiError(
+                        f"Request failed with status {res.status_code}",
+                        code="internal_error",
+                        http_status=res.status_code,
+                        request_id=request_id,
+                    )
+
+                # Never retry 4xx except 429
+                if res.status_code < 500 and res.status_code != 429:
+                    raise err
+
+                # Honor Retry-After header on 429
+                if isinstance(err, RateLimitedError) and err.retry_after_seconds:
+                    if attempt < self._max_retries:
+                        time.sleep(err.retry_after_seconds)
+                        last_error = err
+                        continue
+
+                last_error = err
+
+            # Exponential backoff before next attempt
+            if attempt < self._max_retries:
+                time.sleep(2 ** attempt)
+
+        assert last_error is not None
+        raise last_error
+
+
+class SessionsAPI:
+    """Browser sessions API (synchronous)."""
+
+    def __init__(self, request_fn: Any):
+        self._request = request_fn
+
+    def create(self, **kwargs: Any) -> SessionInfo:
+        """Create a browser session. Returns a CDP WebSocket URL."""
+        body = _to_camel_case(kwargs) if kwargs else {}
+        envelope = self._request("POST", "/v1/sessions", json=body)
+        return SessionInfo(**_to_snake_case(envelope["data"]))
+
+    def get(self, session_id: str) -> SessionInfo:
+        """Get session status."""
+        envelope = self._request("GET", f"/v1/sessions/{session_id}")
+        return SessionInfo(**_to_snake_case(envelope["data"]))
+
+    def stop(self, session_id: str) -> StopSessionResult:
+        """Stop a browser session."""
+        envelope = self._request("DELETE", f"/v1/sessions/{session_id}")
+        return StopSessionResult(**_to_snake_case(envelope["data"]))
+
+    def list(self) -> list[SessionInfo]:
+        """List active sessions."""
+        envelope = self._request("GET", "/v1/sessions")
+        data = envelope["data"]
+        return [SessionInfo(**_to_snake_case(s)) for s in data]
+
+
+def _to_camel_case(data: dict[str, Any]) -> dict[str, Any]:
+    """Convert snake_case dict keys to camelCase (top-level only)."""
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        parts = key.split("_")
+        camel = parts[0] + "".join(p.capitalize() for p in parts[1:])
+        result[camel] = value
+    return result
+
+
+def _to_snake_case(data: Any) -> Any:
+    """Recursively convert camelCase dict keys to snake_case."""
+    import re
+
+    if isinstance(data, dict):
+        result: dict[str, Any] = {}
+        for key, value in data.items():
+            snake = re.sub(r"(?<!^)(?=[A-Z])", "_", key).lower()
+            result[snake] = _to_snake_case(value)
+        return result
+    if isinstance(data, list):
+        return [_to_snake_case(v) for v in data]
+    return data
+
+
+def _parse_sse_event(event_name: str, raw_data: str) -> Optional[StreamEvent]:
+    """Parse a single SSE frame into a typed StreamEvent, or None if unknown."""
+    try:
+        payload = json.loads(raw_data)
+    except json.JSONDecodeError:
+        return None
+
+    snake = _to_snake_case(payload)
+
+    if event_name == "progress":
+        return ProgressEvent(**snake)
+    if event_name == "page":
+        return PageEvent(data=Page(**snake))
+    if event_name == "error":
+        return ErrorEvent(**snake)
+    if event_name == "done":
+        return DoneEvent(**snake)
+    return None
+
+
+def _parse_sse_stream(lines: Iterator[str], timeout: int) -> Iterator[StreamEvent]:
+    """Accumulate SSE lines into frames and yield parsed StreamEvents.
+
+    SSE frames are separated by blank lines. Each frame has `event: <name>`
+    and `data: <json>` lines. Comment lines (starting with `:`) are keep-alive
+    pings and skipped. The generator completes when it yields a ``done`` event
+    or the stream closes.
+    """
+    start = time.time()
+    current_event = ""
+    current_data: list[str] = []
+
+    for line in lines:
+        if time.time() - start > timeout:
+            raise ScrapeTimeoutError(
+                "Stream read timed out",
+                code="scrape_timeout",
+                http_status=504,
+            )
+
+        # Blank line = frame boundary
+        if line == "":
+            if current_event and current_data:
+                parsed = _parse_sse_event(current_event, "\n".join(current_data))
+                if parsed is not None:
+                    yield parsed
+                    if isinstance(parsed, DoneEvent):
+                        return
+            current_event = ""
+            current_data = []
+            continue
+
+        # Comment / keep-alive
+        if line.startswith(":"):
+            continue
+
+        if line.startswith("event:"):
+            current_event = line[len("event:") :].strip()
+        elif line.startswith("data:"):
+            current_data.append(line[len("data:") :].strip())

reader_py/errors.py

@@ -0,0 +1,135 @@
+"""Typed error classes mirroring the reader-api error code catalog.
+
+The API returns a stable ``code`` field on every error response. The SDK
+branches on that code and raises a specific subclass so callers can write::
+
+    try:
+        client.read(url=url)
+    except InsufficientCreditsError as err:
+        print(err.required, err.available, err.reset_at)
+
+There is one subclass per code. Unknown codes fall through to the base
+:class:`ReaderApiError`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ReaderApiError(Exception):
+    """Base error for all Reader API responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "internal_error",
+        http_status: int = 0,
+        details: Optional[dict[str, Any]] = None,
+        docs_url: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.http_status = http_status
+        self.details = details or {}
+        self.docs_url = docs_url
+        self.request_id = request_id
+
+
+class InvalidRequestError(ReaderApiError):
+    pass
+
+
+class UnauthenticatedError(ReaderApiError):
+    pass
+
+
+class InsufficientCreditsError(ReaderApiError):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.required: Optional[int] = self.details.get("required")
+        self.available: Optional[int] = self.details.get("available")
+        self.reset_at: Optional[str] = self.details.get("resetAt")
+
+
+class UrlBlockedError(ReaderApiError):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.url: Optional[str] = self.details.get("url")
+        self.reason: Optional[str] = self.details.get("reason")
+
+
+class NotFoundError(ReaderApiError):
+    pass
+
+
+class ConflictError(ReaderApiError):
+    pass
+
+
+class RateLimitedError(ReaderApiError):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after_seconds: Optional[int] = self.details.get("retryAfterSeconds")
+        self.limit: Optional[int] = self.details.get("limit")
+        self.window_seconds: Optional[int] = self.details.get("windowSeconds")
+
+
+class ConcurrencyLimitedError(ReaderApiError):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.active: Optional[int] = self.details.get("active")
+        self.max: Optional[int] = self.details.get("max")
+
+
+class InternalServerError(ReaderApiError):
+    pass
+
+
+class UpstreamUnavailableError(ReaderApiError):
+    pass
+
+
+class ScrapeTimeoutError(ReaderApiError):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.timeout_ms: Optional[int] = self.details.get("timeoutMs")
+
+
+_CODE_MAP: dict[str, type[ReaderApiError]] = {
+    "invalid_request": InvalidRequestError,
+    "unauthenticated": UnauthenticatedError,
+    "insufficient_credits": InsufficientCreditsError,
+    "url_blocked": UrlBlockedError,
+    "not_found": NotFoundError,
+    "conflict": ConflictError,
+    "rate_limited": RateLimitedError,
+    "concurrency_limited": ConcurrencyLimitedError,
+    "internal_error": InternalServerError,
+    "upstream_unavailable": UpstreamUnavailableError,
+    "scrape_timeout": ScrapeTimeoutError,
+}
+
+
+def to_reader_api_error(
+    body: dict[str, Any],
+    http_status: int,
+    request_id: Optional[str] = None,
+) -> ReaderApiError:
+    """Build the right error subclass from an error envelope body."""
+    code = body.get("code", "internal_error")
+    cls = _CODE_MAP.get(code, ReaderApiError)
+    return cls(
+        body.get("message", "Reader API error"),
+        code=code,
+        http_status=http_status,
+        details=body.get("details") or {},
+        docs_url=body.get("docsUrl"),
+        request_id=request_id,
+    )
+
+
+# Backwards-compat alias for users still catching the old class name.
+ReaderError = ReaderApiError

reader_py/types.py

@@ -0,0 +1,213 @@
+"""Reader SDK types — mirror the reader-api envelope contract."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+ProxyMode = Literal["standard", "stealth", "auto"]
+ResolvedProxyMode = Literal["standard", "stealth"]
+JobStatus = Literal["queued", "processing", "completed", "failed", "cancelled"]
+JobMode = Literal["scrape", "batch", "crawl"]
+
+
+class WebhookConfig(BaseModel):
+    """Per-request webhook configuration for async job notifications."""
+
+    url: str
+    events: Optional[list[str]] = None
+    secret: Optional[str] = None
+
+
+class ReadParams(BaseModel):
+    url: Optional[str] = None
+    urls: Optional[list[str]] = None
+    formats: list[str] = ["markdown"]
+    only_main_content: bool = True
+    include_tags: Optional[list[str]] = None
+    exclude_tags: Optional[list[str]] = None
+    wait_for_selector: Optional[str] = None
+    timeout_ms: int = 30000
+    proxy_mode: Optional[ProxyMode] = None
+    max_depth: Optional[int] = None
+    max_pages: Optional[int] = None
+    cache: bool = True
+    webhook: Optional[WebhookConfig] = None
+    batch_concurrency: Optional[int] = None
+
+
+class ScrapeMetadata(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    status_code: Optional[int] = None
+    duration: int
+    cached: bool
+    proxy_mode: Optional[ResolvedProxyMode] = None
+    proxy_escalated: Optional[bool] = None
+    scraped_at: str
+
+
+class ScrapeResult(BaseModel):
+    """Result of a synchronous single-URL scrape."""
+
+    kind: Literal["scrape"] = "scrape"
+    url: str
+    final_url: Optional[str] = None  # Present if URL redirected
+    markdown: Optional[str] = None
+    html: Optional[str] = None
+    metadata: ScrapeMetadata
+
+
+class Page(BaseModel):
+    """An individual result inside a job's `results` array."""
+
+    url: str
+    markdown: Optional[str] = None
+    html: Optional[str] = None
+    status_code: Optional[int] = None
+    proxy_mode: Optional[ResolvedProxyMode] = None
+    proxy_escalated: Optional[bool] = None
+    credits: Optional[int] = None
+    metadata: Optional[dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+class Job(BaseModel):
+    """Job as returned by GET /v1/jobs/:id (the `data` portion of the envelope)."""
+
+    kind: Literal["job"] = "job"
+    id: str
+    status: JobStatus
+    mode: JobMode
+    completed: int = 0
+    total: int = 0
+    credits_used: int = 0
+    error: Optional[str] = None
+    results: list[Page] = Field(default_factory=list)
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+class Pagination(BaseModel):
+    total: int
+    skip: int
+    limit: int
+    has_more: bool
+    next: Optional[str] = None
+
+
+class Credits(BaseModel):
+    balance: int
+    limit: int
+    used: int
+    tier: str
+    reset_at: str
+
+
+class UsageEntry(BaseModel):
+    id: str
+    url: str
+    duration: int
+    status: Literal["success", "error"]
+    cached: bool
+    proxy_mode: Optional[ResolvedProxyMode] = None
+    credits: int
+    error: Optional[str] = None
+    created_at: str
+
+
+# Backwards-compat aliases — older code used these names.
+JobInfo = Job
+CreditInfo = Credits
+
+
+class ScrapeReadResult(BaseModel):
+    """ReadResult variant returned by single-URL scrapes."""
+
+    kind: Literal["scrape"]
+    data: ScrapeResult
+
+
+class JobReadResult(BaseModel):
+    """ReadResult variant returned by async batch and crawl jobs."""
+
+    kind: Literal["job"]
+    data: Job
+
+
+# Discriminated union: the `kind` field selects the variant. The explicit
+# Field(discriminator="kind") annotation tells Pydantic v2 to dispatch on
+# `kind` at validation time (faster and gives better error messages than
+# structural matching) and enables IDE / mypy narrowing on `result.data`
+# once the caller has branched on `result.kind`.
+ReadResult = Annotated[
+    Union[ScrapeReadResult, JobReadResult],
+    Field(discriminator="kind"),
+]
+
+
+# ──────────────────────────────────────────────────────────────
+# Streaming events (yielded by client.stream / AsyncReaderClient.stream)
+# ──────────────────────────────────────────────────────────────
+
+
+class ProgressEvent(BaseModel):
+    type: Literal["progress"] = "progress"
+    status: JobStatus
+    completed: int
+    total: int
+
+
+class PageEvent(BaseModel):
+    type: Literal["page"] = "page"
+    data: Page
+
+
+class ErrorEvent(BaseModel):
+    type: Literal["error"] = "error"
+    url: str
+    error: str
+
+
+class DoneEvent(BaseModel):
+    type: Literal["done"] = "done"
+    status: JobStatus
+    completed: int
+    total: int
+
+
+StreamEvent = Union[ProgressEvent, PageEvent, ErrorEvent, DoneEvent]
+
+
+# ─── Browser Sessions ────────────────────────────────────────────────
+
+SessionStatus = Literal["active", "stopped", "expired"]
+
+
+class SessionInfo(BaseModel):
+    """Active browser session with a CDP WebSocket endpoint."""
+
+    session_id: str
+    ws_endpoint: str
+    token: str
+    status: SessionStatus
+    created_at: str
+    expires_at: str
+
+
+class CreateSessionParams(BaseModel):
+    """Options for creating a browser session."""
+
+    max_duration_ms: Optional[int] = None
+
+
+class StopSessionResult(BaseModel):
+    """Result from stopping a browser session."""
+
+    session_id: str
+    status: Literal["stopped"]
+    duration_ms: int
+    credits_charged: int

reader_py-0.2.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: reader-py
+Version: 0.2.0
+Summary: Python SDK for the Reader API
+License: MIT
+Keywords: reader,scraper,web-scraping,markdown,llm,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# reader-py
+
+Python SDK for the [Reader API](https://reader.dev) — content extraction for LLMs. Wraps `POST /v1/read`, parses responses into Pydantic models, raises typed exceptions, and auto-polls async jobs to completion.
+
+**Version:** 0.2.0 · **Python:** 3.9+
+
+## Install
+
+```bash
+pip install reader-py
+```
+
+## Quick start (sync)
+
+```python
+import os
+from reader_py import ReaderClient
+
+reader = ReaderClient(api_key=os.environ["READER_KEY"])
+
+result = reader.read(url="https://example.com")
+if result.kind == "scrape":
+    print(result.data.markdown)
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+import os
+from reader_py import AsyncReaderClient
+
+async def main():
+    async with AsyncReaderClient(api_key=os.environ["READER_KEY"]) as reader:
+        result = await reader.read(url="https://example.com")
+        if result.kind == "scrape":
+            print(result.data.markdown)
+
+asyncio.run(main())
+```
+
+`reader.read(...)` returns a discriminated union (Pydantic):
+
+- `ScrapeReadResult(kind="scrape", data=ScrapeResult)` — single-URL requests, returned immediately
+- `JobReadResult(kind="job", data=Job)` — batch and crawl requests, auto-polled to completion
+
+## Features
+
+- **Sync and async clients** — `ReaderClient` (blocking, backed by `httpx.Client`) and `AsyncReaderClient` (backed by `httpx.AsyncClient`). Same method surface.
+- **Typed errors for all 11 Reader error codes.** `InsufficientCreditsError`, `RateLimitedError`, `UrlBlockedError`, `ScrapeTimeoutError`, and more. Each subclass exposes the relevant fields (e.g. `err.required`, `err.retry_after_seconds`).
+- **Automatic retries with exponential backoff** for transient codes. Honors the `Retry-After` header on 429.
+- **Pagination-aware job collection.** `wait_for_job()` returns the full job with every page result.
+- **SSE streaming.** `for event in reader.stream(job_id)` (sync) or `async for` (async) yields `ProgressEvent` / `PageEvent` / `ErrorEvent` / `DoneEvent`.
+- **Pydantic models everywhere** — all responses are parsed into typed models with IDE autocomplete.
+- **Request ID tracing.** Every error carries the `x-request-id` header value on `err.request_id` for support tickets.
+
+## Browser Sessions
+
+Launch a stealthed Chrome and connect Playwright:
+
+```python
+session = reader.sessions.create()
+
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.ws_endpoint)
+    page = browser.contexts[0].new_page()
+    page.goto("https://example.com")
+    print(page.title())
+    browser.close()
+
+reader.sessions.stop(session.session_id)
+```
+
+Async:
+
+```python
+session = await reader.sessions.create()
+# ... use async playwright ...
+await reader.sessions.stop(session.session_id)
+```
+
+Methods: `reader.sessions.create()`, `.get(id)`, `.stop(id)`, `.list()`
+
+## Errors
+
+```python
+from reader_py import (
+    ReaderApiError,
+    InsufficientCreditsError,
+    RateLimitedError,
+    UrlBlockedError,
+)
+
+try:
+    reader.read(url=url)
+except InsufficientCreditsError as err:
+    print(f"Need {err.required}, have {err.available}")
+except RateLimitedError as err:
+    print(f"Retry after {err.retry_after_seconds}s")
+except UrlBlockedError as err:
+    print(f"Blocked: {err.reason}")
+except ReaderApiError as err:
+    print(f"[{err.code}] {err} — see {err.docs_url}")
+```
+
+`ReaderError` is re-exported as an alias for `ReaderApiError` so code written against the 0.1 SDK continues to work. New code should use `ReaderApiError`.
+
+Full catalog of error codes: https://reader.dev/docs/home/concepts/errors
+
+## Links
+
+- **Docs:** https://reader.dev/docs
+- **SDK reference:** https://reader.dev/docs/sdk/python
+- **API reference:** https://reader.dev/docs/api-reference/read
+- **Discord:** https://discord.gg/6tjkq7J5WV
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e .[dev]
+pytest
+```

reader_py-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+reader_py/__init__.py,sha256=YUumSMGdwuL5iLtCnxQhft2-JYyI-Bk0s_F9yFyIico,1694
+reader_py/async_client.py,sha256=u4atvVKRgyYdwuwD-Cyi58i3R7EkfEbM1lbV_Aoz4Eg,12846
+reader_py/client.py,sha256=8I585bzIYVjw7357FHORYZwtWPQ_rmYfpPwf11w_fuk,15247
+reader_py/errors.py,sha256=p6JeE4ga_4nCizDhQ4uv7CWiuiptoiIxk5k36Itoogs,4053
+reader_py/types.py,sha256=sPHtQ47bMskzJZHcUAlIo5fDuNfd4XJf1VdXn6RJgWQ,5695
+reader_py-0.2.0.dist-info/METADATA,sha256=T57wx2JXGnsFTO49ipN-wTfzJ9s0GmK0f5eXdbUWgWU,4280
+reader_py-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+reader_py-0.2.0.dist-info/top_level.txt,sha256=7oV7DerbpeN6_gURVfw80HLHOoagNvXRd4pcrFopnBU,10
+reader_py-0.2.0.dist-info/RECORD,,

reader_py-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reader_py-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+reader_py