rendex 0.1.0__py3-none-any.whl

rendex/__init__.py

@@ -0,0 +1,29 @@
+"""Rendex — Official Python SDK for the Rendex screenshot API."""
+
+from .client import Rendex
+from .errors import RendexApiError, RendexError, RendexNetworkError
+from .types import (
+    ScreenshotData,
+    ScreenshotJsonResponse,
+    ScreenshotMetadata,
+    ScreenshotOptions,
+    ScreenshotResult,
+    ResponseMeta,
+    UsageInfo,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Rendex",
+    "RendexError",
+    "RendexApiError",
+    "RendexNetworkError",
+    "ScreenshotOptions",
+    "ScreenshotResult",
+    "ScreenshotMetadata",
+    "ScreenshotJsonResponse",
+    "ScreenshotData",
+    "ResponseMeta",
+    "UsageInfo",
+]

rendex/client.py

@@ -0,0 +1,187 @@
+"""Rendex SDK client."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from .errors import RendexApiError, RendexError, RendexNetworkError
+from .types import (
+    ScreenshotJsonResponse,
+    ScreenshotMetadata,
+    ScreenshotResult,
+    _build_body,
+    _to_camel,
+)
+
+DEFAULT_BASE_URL = "https://api.rendex.dev"
+
+
+class Rendex:
+    """Official Python client for the Rendex screenshot API.
+
+    Usage::
+
+        from rendex import Rendex
+
+        rendex = Rendex("your-api-key")
+        result = rendex.screenshot("https://example.com", full_page=True)
+        Path("screenshot.png").write_bytes(result.image)
+
+    Or as a context manager::
+
+        with Rendex("your-api-key") as rendex:
+            result = rendex.screenshot("https://example.com")
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL) -> None:
+        if not api_key:
+            raise RendexError("API key is required. Get one at https://rendex.dev")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=90.0,
+        )
+
+    def screenshot(self, url: str, **options: Any) -> ScreenshotResult:
+        """Capture a screenshot and return the binary image with metadata.
+
+        Args:
+            url: The webpage URL to capture.
+            **options: Screenshot options (snake_case). See ScreenshotOptions.
+
+        Returns:
+            ScreenshotResult with ``image`` (bytes) and ``metadata``.
+        """
+        body = _build_body(url, options)
+        response = self._request("/v1/screenshot", body)
+
+        metadata = self._parse_metadata_headers(response.headers, len(response.content))
+
+        return ScreenshotResult(image=response.content, metadata=metadata)
+
+    def screenshot_json(self, url: str, **options: Any) -> ScreenshotJsonResponse:
+        """Capture a screenshot and return JSON with a base64-encoded image.
+
+        Args:
+            url: The webpage URL to capture.
+            **options: Screenshot options (snake_case). See ScreenshotOptions.
+
+        Returns:
+            ScreenshotJsonResponse with ``data`` and ``meta``.
+        """
+        body = _build_body(url, options)
+        response = self._request("/v1/screenshot/json", body)
+        data = response.json()
+
+        if not data.get("success"):
+            error = data.get("error", {})
+            meta = data.get("meta", {})
+            raise RendexApiError(
+                message=error.get("message", "Unknown error"),
+                status_code=response.status_code,
+                error_code=error.get("code", "UNKNOWN"),
+                request_id=meta.get("requestId"),
+                details=error.get("details"),
+            )
+
+        return data  # type: ignore[return-value]
+
+    def screenshot_url(self, url: str, **options: Any) -> str:
+        """Generate a signed GET URL for embedding (no network call).
+
+        Useful for ``<img>`` tags, OpenGraph images, or anywhere you need a URL.
+
+        **Note**: The API key is included in the URL. Use server-side only.
+
+        Args:
+            url: The webpage URL to capture.
+            **options: Screenshot options (snake_case).
+
+        Returns:
+            A complete URL string to the screenshot endpoint.
+        """
+        params: list[tuple[str, str]] = [("key", self._api_key), ("url", url)]
+
+        for key, value in options.items():
+            if value is None:
+                continue
+            camel_key = _to_camel(key)
+            if isinstance(value, list):
+                for item in value:
+                    params.append((camel_key, str(item)))
+            elif isinstance(value, bool):
+                params.append((camel_key, str(value).lower()))
+            else:
+                params.append((camel_key, str(value)))
+
+        return f"{self._base_url}/v1/screenshot?{urlencode(params)}"
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Rendex:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ─── Private ─────────────────────────────────────────────────────
+
+    def _request(self, path: str, body: dict[str, Any]) -> httpx.Response:
+        try:
+            response = self._client.post(path, json=body)
+        except httpx.HTTPError as exc:
+            raise RendexNetworkError(
+                f"Network request to {self._base_url}{path} failed: {exc}",
+                cause=exc,
+            ) from exc
+
+        if response.status_code >= 400:
+            self._handle_error_response(response)
+
+        return response
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        try:
+            data = response.json()
+        except Exception:
+            raise RendexApiError(
+                message=f"HTTP {response.status_code}",
+                status_code=response.status_code,
+                error_code="UNKNOWN",
+            )
+
+        error = data.get("error", {})
+        meta = data.get("meta", {})
+
+        raise RendexApiError(
+            message=error.get("message", f"HTTP {response.status_code}"),
+            status_code=response.status_code,
+            error_code=error.get("code", "UNKNOWN"),
+            request_id=meta.get("requestId"),
+            details=error.get("details"),
+        )
+
+    @staticmethod
+    def _parse_metadata_headers(headers: httpx.Headers, fallback_size: int) -> ScreenshotMetadata:
+        return ScreenshotMetadata(
+            url=headers.get("x-screenshot-url", ""),
+            width=int(headers.get("x-screenshot-width", "0")),
+            height=int(headers.get("x-screenshot-height", "0")),
+            format=headers.get("x-rendex-format", "png"),
+            bytes_size=int(headers.get("x-screenshot-size", str(fallback_size))),
+            captured_at=headers.get("x-screenshot-captured-at", ""),
+            quality=headers.get("x-rendex-quality", "full"),
+            wait_strategy=headers.get("x-rendex-wait-strategy", "unknown"),
+            load_time_ms=int(headers.get("x-rendex-load-time-ms", "0")),
+            truncated=headers.get("x-rendex-truncated") == "true",
+        )

rendex/errors.py

@@ -0,0 +1,47 @@
+"""Rendex SDK error classes."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class RendexError(Exception):
+    """Base error for all Rendex SDK errors."""
+
+    pass
+
+
+class RendexApiError(RendexError):
+    """Error returned by the Rendex API (non-2xx response with a parsed body)."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        error_code: str,
+        request_id: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        """HTTP status code (e.g. 400, 401, 429, 500)."""
+        self.error_code = error_code
+        """API error code (e.g. "RATE_LIMITED", "VALIDATION_ERROR")."""
+        self.request_id = request_id
+        """Unique request ID for debugging with Rendex support."""
+        self.details = details
+        """Additional error details (e.g. validation field errors)."""
+
+    def __str__(self) -> str:
+        parts = [f"[{self.error_code}] {super().__str__()}"]
+        if self.request_id:
+            parts.append(f"(request: {self.request_id})")
+        return " ".join(parts)
+
+
+class RendexNetworkError(RendexError):
+    """Network-level error (DNS failure, timeout, connection refused, etc.)."""
+
+    def __init__(self, message: str, cause: Optional[Exception] = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause

rendex/types.py

@@ -0,0 +1,102 @@
+"""Rendex SDK type definitions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Literal, Optional, TypedDict
+
+
+class ScreenshotOptions(TypedDict, total=False):
+    """Options for capturing a screenshot. Only ``url`` is required."""
+
+    url: str  # Required — set via positional arg in client methods
+    format: Literal["png", "jpeg", "webp"]
+    width: int
+    height: int
+    full_page: bool
+    quality: int
+    delay: int
+    dark_mode: bool
+    device_scale_factor: float
+    block_ads: bool
+    block_resource_types: List[Literal["font", "image", "media", "stylesheet", "other"]]
+    timeout: int
+    wait_until: Literal["load", "domcontentloaded", "networkidle0", "networkidle2"]
+    wait_for_selector: str
+    best_attempt: bool
+    selector: str
+
+
+class UsageInfo(TypedDict):
+    credits: int
+    remaining: int
+
+
+class ResponseMeta(TypedDict, total=False):
+    requestId: str
+    timestamp: str
+    usage: UsageInfo
+
+
+class ScreenshotData(TypedDict, total=False):
+    image: str  # base64
+    contentType: str
+    url: str
+    width: int
+    height: int
+    format: str
+    bytesSize: int
+    capturedAt: str
+    quality: Literal["full", "degraded", "best_attempt"]
+    waitStrategy: str
+    loadTimeMs: int
+    truncated: bool
+
+
+class ScreenshotJsonResponse(TypedDict):
+    success: bool
+    data: ScreenshotData
+    meta: ResponseMeta
+
+
+@dataclass(frozen=True)
+class ScreenshotMetadata:
+    """Metadata from response headers for binary screenshots."""
+
+    url: str
+    width: int
+    height: int
+    format: str
+    bytes_size: int
+    captured_at: str
+    quality: str  # "full", "degraded", or "best_attempt"
+    wait_strategy: str
+    load_time_ms: int
+    truncated: bool
+
+
+@dataclass(frozen=True)
+class ScreenshotResult:
+    """Result from ``Rendex.screenshot()`` — binary image with metadata."""
+
+    image: bytes
+    """Raw image bytes. Write to file, upload to S3, etc."""
+
+    metadata: ScreenshotMetadata
+    """Capture metadata extracted from response headers."""
+
+
+# camelCase conversion for API requests
+def _to_camel(key: str) -> str:
+    """Convert snake_case to camelCase."""
+    parts = key.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def _build_body(url: str, options: Any) -> dict[str, Any]:
+    """Build the JSON request body from url + snake_case kwargs."""
+    body: dict[str, Any] = {"url": url}
+    for key, value in options.items():
+        if value is not None:
+            body[_to_camel(key)] = value
+    return body

rendex-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: rendex
+Version: 0.1.0
+Summary: Official Python SDK for the Rendex screenshot API — capture any webpage as an image
+Project-URL: Homepage, https://rendex.dev
+Project-URL: Documentation, https://rendex.dev/docs
+Project-URL: Repository, https://github.com/copperline-labs/copperline-labs
+Project-URL: Issues, https://github.com/copperline-labs/copperline-labs/issues
+Author-email: Copperline Labs LLC <support@rendex.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,rendex,screenshot,screenshot-api,sdk,webpage-capture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# rendex
+
+Official Python SDK for the [Rendex](https://rendex.dev) screenshot API. Capture any webpage as a high-quality image with a single function call.
+
+- Full type hints (PEP 561 compatible)
+- Single dependency (`httpx`)
+- Sync API with context manager support
+- Typed error handling with API error codes
+
+## Install
+
+```bash
+pip install rendex
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from rendex import Rendex
+
+rendex = Rendex("your-api-key")
+
+# Capture a screenshot (returns binary image)
+result = rendex.screenshot("https://example.com", format="png", full_page=True)
+Path("screenshot.png").write_bytes(result.image)
+
+print(f"{result.metadata.bytes_size} bytes, loaded in {result.metadata.load_time_ms}ms")
+```
+
+## API Reference
+
+### `Rendex(api_key, *, base_url="https://api.rendex.dev")`
+
+Create a new Rendex client.
+
+```python
+rendex = Rendex("your-api-key")
+
+# Or with context manager for connection reuse
+with Rendex("your-api-key") as rendex:
+    result = rendex.screenshot("https://example.com")
+```
+
+### `rendex.screenshot(url, **options)`
+
+Capture a screenshot and return the binary image with metadata.
+
+```python
+result = rendex.screenshot(
+    "https://example.com",
+    format="webp",
+    width=1920,
+    height=1080,
+    dark_mode=True,
+)
+Path("screenshot.webp").write_bytes(result.image)
+print(result.metadata.load_time_ms)  # 350
+```
+
+**Returns** `ScreenshotResult`:
+- `image` — `bytes` of the captured image
+- `metadata` — `ScreenshotMetadata` with url, dimensions, format, bytes_size, load_time_ms, quality, etc.
+
+### `rendex.screenshot_json(url, **options)`
+
+Capture a screenshot and return JSON with a base64-encoded image.
+
+```python
+result = rendex.screenshot_json("https://example.com")
+print(result["data"]["bytesSize"])        # 45823
+print(result["meta"]["usage"]["remaining"])  # 499
+```
+
+**Returns** `ScreenshotJsonResponse` dict with `data` (image + metadata) and `meta` (request ID, usage).
+
+### `rendex.screenshot_url(url, **options)`
+
+Generate a GET URL for embedding. No network call — pure URL builder.
+
+```python
+url = rendex.screenshot_url("https://example.com", format="png", width=1200)
+# Use in <img> tags, OpenGraph, etc.
+```
+
+> **Note**: The API key is included in the URL. Use server-side only.
+
+### Screenshot Options
+
+All options are keyword arguments in snake_case. Only `url` (positional) is required:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `format` | `str` | `"png"` | `"png"`, `"jpeg"`, or `"webp"` |
+| `width` | `int` | `1280` | Viewport width (320–3840) |
+| `height` | `int` | `800` | Viewport height (240–2160) |
+| `full_page` | `bool` | `False` | Capture the full scrollable page |
+| `quality` | `int` | — | JPEG/WebP quality (1–100) |
+| `delay` | `int` | `0` | Delay before capture in ms (0–10000) |
+| `dark_mode` | `bool` | `False` | Emulate dark mode |
+| `device_scale_factor` | `float` | `1` | Device pixel ratio (1–3) for Retina |
+| `block_ads` | `bool` | `True` | Block ads and trackers |
+| `block_resource_types` | `list` | — | Block: `"font"`, `"image"`, `"media"`, `"stylesheet"`, `"other"` |
+| `timeout` | `int` | `30` | Page load timeout in seconds (5–60) |
+| `wait_until` | `str` | `"networkidle2"` | `"load"`, `"domcontentloaded"`, `"networkidle0"`, `"networkidle2"` |
+| `wait_for_selector` | `str` | — | CSS selector to wait for |
+| `best_attempt` | `bool` | `True` | Return best-effort screenshot on timeout |
+| `selector` | `str` | — | Capture a specific element by CSS selector |
+
+## Error Handling
+
+```python
+from rendex import Rendex, RendexApiError, RendexNetworkError
+
+rendex = Rendex("your-api-key")
+
+try:
+    rendex.screenshot("https://example.com")
+except RendexApiError as e:
+    # API returned an error
+    print(e.error_code)   # "RATE_LIMITED", "VALIDATION_ERROR", etc.
+    print(e.status_code)  # 429, 400, etc.
+    print(e.request_id)   # For debugging with Rendex support
+    print(e.details)      # Validation details (if any)
+except RendexNetworkError as e:
+    # Network failure (DNS, timeout, connection refused)
+    print(f"Network error: {e}")
+```
+
+### Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `VALIDATION_ERROR` | 400 | Invalid request parameters |
+| `INVALID_URL` | 400 | URL failed SSRF validation |
+| `TIMEOUT` | 408 | Page took too long to load |
+| `CAPTURE_FAILED` | 500 | Browser rendering error |
+| `RATE_LIMITED` | 429 | Rate limit exceeded |
+| `USAGE_EXCEEDED` | 429 | Monthly credit limit reached |
+| `MISSING_API_KEY` | 401 | No API key provided |
+| `INVALID_API_KEY` | 401 | API key verification failed |
+
+## License
+
+MIT - [Copperline Labs LLC](https://copperlinelabs.com)

rendex-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+rendex/__init__.py,sha256=NN-y-lNUDI3zrcvviX8OTkVlE_nwkBwXHa0ZbG1YOzQ,620
+rendex/client.py,sha256=EwEO5zHny2knZrhv_NUAHBbeKsH7yphUb3RUKaOrqEs,6533
+rendex/errors.py,sha256=jQPHPmu9nerZZLS8sf0SwW2FCv_1LMYg9TjMrOOBtFQ,1426
+rendex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rendex/types.py,sha256=wHhkU-7cUYnZK6IXptztEc3RKJOPJ4bTutVq8TyFBx4,2553
+rendex-0.1.0.dist-info/METADATA,sha256=5DOYPfCek-xEiIN9XIKIMp19rymMk82M7DCcmDBzJxo,5844
+rendex-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+rendex-0.1.0.dist-info/licenses/LICENSE,sha256=dxFNlrSgJ6--KVwaItmS-RsYzgkAbOUasB8Xj8j_iLQ,1076
+rendex-0.1.0.dist-info/RECORD,,

rendex-0.1.0.dist-info/WHEEL

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

rendex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Copperline Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.