rendex 0.1.0__tar.gz

rendex-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

rendex-0.1.0/CLAUDE.md

@@ -0,0 +1,40 @@
+# Rendex Python SDK
+
+**Package**: `rendex` (PyPI)
+**Parent**: Copperline Labs LLC
+**Product**: Rendex (rendex.dev)
+
+## Overview
+
+Official Python SDK for the Rendex screenshot API. Thin wrapper (~80 lines of core logic) around the REST API at api.rendex.dev. Single dependency: `httpx`.
+
+## Architecture
+
+- `src/rendex/client.py` — `Rendex` class with 3 methods: `screenshot`, `screenshot_json`, `screenshot_url`
+- `src/rendex/types.py` — TypedDict/dataclass definitions + camelCase conversion helpers
+- `src/rendex/errors.py` — Exception hierarchy: `RendexError` → `RendexApiError` / `RendexNetworkError`
+- `src/rendex/__init__.py` — Public exports
+- `tests/test_client.py` — Unit tests with httpx MockTransport
+
+## Key Design Decisions
+
+- **snake_case API**: Python-idiomatic (`full_page`, `dark_mode`), auto-converts to camelCase for the API.
+- **httpx over requests**: Supports sync + async, HTTP/2, modern timeout handling.
+- **Context manager**: `with Rendex("key") as r:` for connection reuse.
+- **Positional url arg**: `rendex.screenshot("https://example.com")` reads naturally.
+
+## Development
+
+```bash
+pip install -e ".[dev]"     # Install in development mode
+python -m pytest tests/      # Run tests
+python -m mypy src/rendex/   # Type-check
+```
+
+## Publishing
+
+Push a `sdk-py-v*` tag to trigger `.github/workflows/publish-sdk-python.yml`.
+
+## Type Sync
+
+Options must match `ScreenshotRequestSchema` in `packages/screenshot-api/src/services/screenshot.ts`. If the API adds new parameters, update `src/rendex/types.py` (snake_case version).

rendex-0.1.0/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.

rendex-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,145 @@
+# 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/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@copperline/rendex-python",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Python SDK for Rendex — managed via pyproject.toml, not npm"
+}

rendex-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rendex"
+version = "0.1.0"
+description = "Official Python SDK for the Rendex screenshot API — capture any webpage as an image"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Copperline Labs LLC", email = "support@rendex.dev" }]
+keywords = ["rendex", "screenshot", "screenshot-api", "webpage-capture", "sdk", "ai-agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://rendex.dev"
+Documentation = "https://rendex.dev/docs"
+Repository = "https://github.com/copperline-labs/copperline-labs"
+Issues = "https://github.com/copperline-labs/copperline-labs/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rendex"]

rendex-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,239 @@
+"""Tests for the Rendex Python SDK."""
+
+import json
+from unittest.mock import MagicMock
+
+import httpx
+import pytest
+
+from rendex import Rendex, RendexApiError, RendexError, RendexNetworkError
+
+
+# ─── Constructor ──────────────────────────────────────────────────────
+
+
+def test_missing_api_key():
+    with pytest.raises(RendexError, match="API key is required"):
+        Rendex("")
+
+
+def test_custom_base_url():
+    client = Rendex("test-key", base_url="https://custom.api.dev/")
+    assert client._base_url == "https://custom.api.dev"
+    client.close()
+
+
+# ─── screenshot_url ───────────────────────────────────────────────────
+
+
+def test_screenshot_url_basic():
+    client = Rendex("test-key")
+    url = client.screenshot_url("https://example.com")
+    assert "key=test-key" in url
+    assert "url=https" in url
+    assert url.startswith("https://api.rendex.dev/v1/screenshot?")
+    client.close()
+
+
+def test_screenshot_url_with_options():
+    client = Rendex("test-key")
+    url = client.screenshot_url(
+        "https://example.com",
+        format="webp",
+        full_page=True,
+        width=1920,
+    )
+    assert "format=webp" in url
+    assert "fullPage=true" in url
+    assert "width=1920" in url
+    client.close()
+
+
+def test_screenshot_url_array_params():
+    client = Rendex("test-key")
+    url = client.screenshot_url(
+        "https://example.com",
+        block_resource_types=["font", "image"],
+    )
+    assert "blockResourceTypes=font" in url
+    assert "blockResourceTypes=image" in url
+    client.close()
+
+
+# ─── camelCase conversion ────────────────────────────────────────────
+
+
+def test_to_camel():
+    from rendex.types import _to_camel
+
+    assert _to_camel("full_page") == "fullPage"
+    assert _to_camel("dark_mode") == "darkMode"
+    assert _to_camel("device_scale_factor") == "deviceScaleFactor"
+    assert _to_camel("url") == "url"
+    assert _to_camel("block_resource_types") == "blockResourceTypes"
+
+
+def test_build_body():
+    from rendex.types import _build_body
+
+    body = _build_body("https://example.com", {"full_page": True, "dark_mode": False, "quality": None})
+    assert body == {"url": "https://example.com", "fullPage": True, "darkMode": False}
+
+
+# ─── Error handling ──────────────────────────────────────────────────
+
+
+def test_api_error_str():
+    err = RendexApiError(
+        message="Rate limit exceeded",
+        status_code=429,
+        error_code="RATE_LIMITED",
+        request_id="req-123",
+    )
+    assert "[RATE_LIMITED]" in str(err)
+    assert "req-123" in str(err)
+    assert err.status_code == 429
+    assert err.error_code == "RATE_LIMITED"
+
+
+def test_api_error_no_request_id():
+    err = RendexApiError(
+        message="Bad request",
+        status_code=400,
+        error_code="VALIDATION_ERROR",
+    )
+    assert "[VALIDATION_ERROR]" in str(err)
+    assert "request:" not in str(err)
+
+
+# ─── Context manager ────────────────────────────────────────────────
+
+
+def test_context_manager():
+    with Rendex("test-key") as client:
+        assert client._api_key == "test-key"
+    # Should not raise after close
+
+
+# ─── Mocked HTTP tests ──────────────────────────────────────────────
+
+
+def test_screenshot_json_success():
+    """Test screenshotJson with a mocked transport."""
+    mock_response_data = {
+        "success": True,
+        "data": {
+            "image": "iVBORw0KGgo=",
+            "contentType": "image/png",
+            "url": "https://example.com",
+            "width": 1280,
+            "height": 800,
+            "format": "png",
+            "bytesSize": 1234,
+            "capturedAt": "2026-04-02T00:00:00Z",
+            "quality": "full",
+            "waitStrategy": "networkidle2",
+            "loadTimeMs": 500,
+        },
+        "meta": {
+            "requestId": "req-abc",
+            "timestamp": "2026-04-02T00:00:00Z",
+            "usage": {"credits": 1, "remaining": 499},
+        },
+    }
+
+    transport = httpx.MockTransport(
+        lambda request: httpx.Response(
+            200,
+            json=mock_response_data,
+        )
+    )
+
+    client = Rendex("test-key")
+    client._client = httpx.Client(
+        base_url="https://api.rendex.dev",
+        headers={"Authorization": "Bearer test-key", "Content-Type": "application/json"},
+        transport=transport,
+        timeout=90.0,
+    )
+
+    result = client.screenshot_json("https://example.com")
+    assert result["success"] is True
+    assert result["data"]["bytesSize"] == 1234
+    assert result["meta"]["usage"]["remaining"] == 499
+    client.close()
+
+
+def test_screenshot_binary_success():
+    """Test screenshot with mocked binary response + headers."""
+    fake_image = b"\x89PNG\r\n\x1a\n" + b"\x00" * 100
+
+    transport = httpx.MockTransport(
+        lambda request: httpx.Response(
+            200,
+            content=fake_image,
+            headers={
+                "content-type": "image/png",
+                "x-screenshot-url": "https://example.com",
+                "x-screenshot-width": "1280",
+                "x-screenshot-height": "800",
+                "x-screenshot-size": str(len(fake_image)),
+                "x-screenshot-captured-at": "2026-04-02T00:00:00Z",
+                "x-rendex-format": "png",
+                "x-rendex-quality": "full",
+                "x-rendex-wait-strategy": "networkidle2",
+                "x-rendex-load-time-ms": "350",
+            },
+        )
+    )
+
+    client = Rendex("test-key")
+    client._client = httpx.Client(
+        base_url="https://api.rendex.dev",
+        headers={"Authorization": "Bearer test-key", "Content-Type": "application/json"},
+        transport=transport,
+        timeout=90.0,
+    )
+
+    result = client.screenshot("https://example.com")
+    assert result.image == fake_image
+    assert result.metadata.width == 1280
+    assert result.metadata.format == "png"
+    assert result.metadata.load_time_ms == 350
+    assert result.metadata.truncated is False
+    client.close()
+
+
+def test_api_error_response():
+    """Test that API errors are properly parsed."""
+    error_body = {
+        "success": False,
+        "error": {
+            "code": "RATE_LIMITED",
+            "message": "Rate limit exceeded",
+        },
+        "meta": {
+            "requestId": "req-xyz",
+            "timestamp": "2026-04-02T00:00:00Z",
+        },
+    }
+
+    transport = httpx.MockTransport(
+        lambda request: httpx.Response(429, json=error_body)
+    )
+
+    client = Rendex("test-key")
+    client._client = httpx.Client(
+        base_url="https://api.rendex.dev",
+        headers={"Authorization": "Bearer test-key", "Content-Type": "application/json"},
+        transport=transport,
+        timeout=90.0,
+    )
+
+    with pytest.raises(RendexApiError) as exc_info:
+        client.screenshot("https://example.com")
+
+    assert exc_info.value.status_code == 429
+    assert exc_info.value.error_code == "RATE_LIMITED"
+    assert exc_info.value.request_id == "req-xyz"
+    client.close()