rayon-sdk-py 0.1.0__tar.gz

rayon_sdk_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RayonAPI
+
+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.

rayon_sdk_py-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: rayon-sdk-py
+Version: 0.1.0
+Summary: Synchronous Python client for the Rayon API
+Author: Rayon API
+License-Expression: MIT
+Project-URL: Homepage, https://rayonapi.com
+Project-URL: Repository, https://github.com/Rayon-API/rayon-sdk-py
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curl_cffi<1,>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# Rayon Python SDK
+
+A synchronous client for `POST /solve` on the Rayon API. Python 3.10 or newer is required.
+
+Install from PyPI:
+
+```sh
+python -m pip install rayon-sdk-py
+```
+
+```python
+import os
+from rayon_sdk_py import solve
+
+result = solve(
+    "https://example.com/page",
+    os.environ["RAYON_API_KEY"],
+    # Optional JSON fingerprint values:
+    profile={"user_agent": "your browser user agent"},
+)
+print(result.status, result.method, result.duration_ms)
+```
+
+`solve(target_url, api_key, *, profile=None, base_url="https://api.rayonapi.com", timeout=150)`
+performs one request using curl_cffi Chrome impersonation. Timeout is a finite positive
+number of seconds. The SDK disables redirects and environment proxies, and never retries.
+Decoded response bodies are limited to 2 MiB; larger responses stop the transfer
+and raise `InvalidResponseError`.
+Custom API endpoints require HTTPS; HTTP is supported only for `localhost`, `127.0.0.1`,
+or `[::1]` development endpoints. URLs cannot contain credentials or fragments;
+the API base URL also cannot contain a query.
+
+The request body contains only `target_url` and, when supplied, `profile`.
+The API key is sent as a Bearer authorization header. Use an account and target
+domain approved for your application.
+
+An accepted result contains exactly one six-header family with a variable prefix
+and the suffixes `a`, `b`, `c`, `d`, `f`, and `z`; `d` may be empty.
+Acceptance means the headers were captured. It does not mean the target website
+verified them. `result.errors` can contain diagnostics from earlier solver tiers
+even when a fallback succeeds.
+
+`SolveResult` exposes `status`, `method`, `target_url`, `duration_ms`, `headers`,
+`cookies`, `profile_used`, and `errors`. Headers, cookies, URL, profile, and diagnostics
+are excluded from its repr because replay data can be sensitive.
+
+Cookies remain a list of records with required string fields `name`, `value`,
+`domain`, and `path`. Extra JSON metadata is preserved. Cookie scope matters:
+do not flatten cookies into a name/value dictionary. The SDK does not invent
+`secure`, expiry, or other browser attributes absent from the API response.
+When replaying a result, preserve cookie domains and paths and use the returned
+`profile_used` values for a compatible browser fingerprint.
+
+```python
+from curl_cffi.requests import Cookies
+
+jar = Cookies()
+for cookie in result.cookies:
+    jar.set(cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie["path"])
+# result.headers, jar, and result.profile_used are available for your replay client.
+```
+
+Handle failures explicitly:
+
+```python
+import os
+from rayon_sdk_py import HTTPError, RayonError, SolveFailedError, solve
+
+try:
+    result = solve("https://example.com/page", os.environ["RAYON_API_KEY"])
+except SolveFailedError as exc:
+    # HTTP 200 with a failed/rejected result also raises.
+    print(exc.result.status)
+except HTTPError as exc:
+    print(exc.status_code, exc.request_id, exc.retry_after)
+except RayonError as exc:
+    print(str(exc))
+```
+
+All SDK errors inherit from `RayonError`. `ValidationError` is raised before
+network access; `TransportError` covers network failures; `RedirectError` is an
+`HTTPError`; `InvalidResponseError` covers invalid JSON or malformed responses.
+Exception messages do not include response bodies, credentials, or underlying
+transport messages. HTTP response errors expose `status_code`, `request_id`, and
+`retry_after` (a validated seconds or HTTP date header string, when present).
+Invalid diagnostic headers or values reflecting the API key are discarded.
+Decide whether and when
+to retry in your application; admitted solve attempts can consume quota.
+
+For local development:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+Tests are offline and patch the transport. CI tests Python 3.10, 3.12, and 3.14
+and builds the wheel and source distribution. See [RELEASE.md](RELEASE.md) for
+the trusted publisher setup. Licensed under [MIT](LICENSE).

rayon_sdk_py-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Rayon Python SDK
+
+A synchronous client for `POST /solve` on the Rayon API. Python 3.10 or newer is required.
+
+Install from PyPI:
+
+```sh
+python -m pip install rayon-sdk-py
+```
+
+```python
+import os
+from rayon_sdk_py import solve
+
+result = solve(
+    "https://example.com/page",
+    os.environ["RAYON_API_KEY"],
+    # Optional JSON fingerprint values:
+    profile={"user_agent": "your browser user agent"},
+)
+print(result.status, result.method, result.duration_ms)
+```
+
+`solve(target_url, api_key, *, profile=None, base_url="https://api.rayonapi.com", timeout=150)`
+performs one request using curl_cffi Chrome impersonation. Timeout is a finite positive
+number of seconds. The SDK disables redirects and environment proxies, and never retries.
+Decoded response bodies are limited to 2 MiB; larger responses stop the transfer
+and raise `InvalidResponseError`.
+Custom API endpoints require HTTPS; HTTP is supported only for `localhost`, `127.0.0.1`,
+or `[::1]` development endpoints. URLs cannot contain credentials or fragments;
+the API base URL also cannot contain a query.
+
+The request body contains only `target_url` and, when supplied, `profile`.
+The API key is sent as a Bearer authorization header. Use an account and target
+domain approved for your application.
+
+An accepted result contains exactly one six-header family with a variable prefix
+and the suffixes `a`, `b`, `c`, `d`, `f`, and `z`; `d` may be empty.
+Acceptance means the headers were captured. It does not mean the target website
+verified them. `result.errors` can contain diagnostics from earlier solver tiers
+even when a fallback succeeds.
+
+`SolveResult` exposes `status`, `method`, `target_url`, `duration_ms`, `headers`,
+`cookies`, `profile_used`, and `errors`. Headers, cookies, URL, profile, and diagnostics
+are excluded from its repr because replay data can be sensitive.
+
+Cookies remain a list of records with required string fields `name`, `value`,
+`domain`, and `path`. Extra JSON metadata is preserved. Cookie scope matters:
+do not flatten cookies into a name/value dictionary. The SDK does not invent
+`secure`, expiry, or other browser attributes absent from the API response.
+When replaying a result, preserve cookie domains and paths and use the returned
+`profile_used` values for a compatible browser fingerprint.
+
+```python
+from curl_cffi.requests import Cookies
+
+jar = Cookies()
+for cookie in result.cookies:
+    jar.set(cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie["path"])
+# result.headers, jar, and result.profile_used are available for your replay client.
+```
+
+Handle failures explicitly:
+
+```python
+import os
+from rayon_sdk_py import HTTPError, RayonError, SolveFailedError, solve
+
+try:
+    result = solve("https://example.com/page", os.environ["RAYON_API_KEY"])
+except SolveFailedError as exc:
+    # HTTP 200 with a failed/rejected result also raises.
+    print(exc.result.status)
+except HTTPError as exc:
+    print(exc.status_code, exc.request_id, exc.retry_after)
+except RayonError as exc:
+    print(str(exc))
+```
+
+All SDK errors inherit from `RayonError`. `ValidationError` is raised before
+network access; `TransportError` covers network failures; `RedirectError` is an
+`HTTPError`; `InvalidResponseError` covers invalid JSON or malformed responses.
+Exception messages do not include response bodies, credentials, or underlying
+transport messages. HTTP response errors expose `status_code`, `request_id`, and
+`retry_after` (a validated seconds or HTTP date header string, when present).
+Invalid diagnostic headers or values reflecting the API key are discarded.
+Decide whether and when
+to retry in your application; admitted solve attempts can consume quota.
+
+For local development:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+Tests are offline and patch the transport. CI tests Python 3.10, 3.12, and 3.14
+and builds the wheel and source distribution. See [RELEASE.md](RELEASE.md) for
+the trusted publisher setup. Licensed under [MIT](LICENSE).

rayon_sdk_py-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rayon-sdk-py"
+version = "0.1.0"
+description = "Synchronous Python client for the Rayon API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Rayon API"}]
+dependencies = ["curl_cffi>=0.13,<1"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2", "twine>=6"]
+
+[project.urls]
+Homepage = "https://rayonapi.com"
+Repository = "https://github.com/Rayon-API/rayon-sdk-py"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

rayon_sdk_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rayon_sdk_py-0.1.0/src/rayon_sdk_py/__init__.py

@@ -0,0 +1,26 @@
+"""Synchronous client for the public Rayon API."""
+
+from .client import solve
+from .models import SolveResult
+from .errors import (
+    HTTPError,
+    InvalidResponseError,
+    RayonError,
+    RedirectError,
+    SolveFailedError,
+    TransportError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "solve",
+    "SolveResult",
+    "RayonError",
+    "ValidationError",
+    "TransportError",
+    "HTTPError",
+    "RedirectError",
+    "InvalidResponseError",
+    "SolveFailedError",
+]

rayon_sdk_py-0.1.0/src/rayon_sdk_py/client.py

@@ -0,0 +1,78 @@
+from curl_cffi import CurlOpt, requests
+from curl_cffi.curl import CURL_WRITEFUNC_ERROR
+
+from .errors import (
+    HTTPError,
+    InvalidResponseError,
+    RedirectError,
+    SolveFailedError,
+    TransportError,
+)
+from .models import SolveResult
+from .validation import parse_result, response_metadata, validate_request
+
+
+_MAX_RESPONSE_BYTES = 2 * 1024 * 1024
+
+
+def solve(
+    target_url: str,
+    api_key: str,
+    *,
+    profile: dict | None = None,
+    base_url: str = "https://api.rayonapi.com",
+    timeout: float = 150,
+) -> SolveResult:
+    """Capture a telemetry header family with one synchronous API request."""
+    profile = validate_request(target_url, api_key, profile, base_url, timeout)
+    body = {"target_url": target_url}
+    if profile is not None:
+        body["profile"] = profile
+    content = bytearray()
+    oversized = False
+
+    def collect(chunk):
+        nonlocal oversized
+        if len(content) + len(chunk) > _MAX_RESPONSE_BYTES:
+            oversized = True
+            return CURL_WRITEFUNC_ERROR
+        content.extend(chunk)
+        return len(chunk)
+
+    try:
+        # Some curl_cffi versions leave libcurl's environment proxy lookup enabled.
+        with requests.Session(
+            impersonate="chrome", trust_env=False, curl_options={CurlOpt.PROXY: ""}
+        ) as session:
+            response = session.post(
+                base_url.rstrip("/") + "/solve",
+                json=body,
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=timeout,
+                allow_redirects=False,
+                content_callback=collect,
+            )
+    except requests.exceptions.RequestException:
+        if oversized:
+            raise InvalidResponseError(
+                "Rayon API response exceeded the 2 MiB limit."
+            ) from None
+        raise TransportError("Rayon API request could not be completed.") from None
+    response.content = bytes(content)
+    metadata = response_metadata(response, api_key)
+    if 300 <= response.status_code < 400:
+        raise RedirectError(
+            "Rayon API returned a redirect; no redirect was followed.", **metadata
+        )
+    if response.status_code != 200:
+        raise HTTPError("Rayon API returned an unsuccessful HTTP status.", **metadata)
+    try:
+        body = response.json()
+    except (ValueError, UnicodeError, RecursionError):
+        raise InvalidResponseError(
+            "Rayon API returned invalid JSON.", **metadata
+        ) from None
+    result = parse_result(body, target_url, metadata)
+    if result.status != "accepted":
+        raise SolveFailedError(result, **metadata)
+    return result

rayon_sdk_py-0.1.0/src/rayon_sdk_py/errors.py

@@ -0,0 +1,46 @@
+from .models import SolveResult
+
+
+class RayonError(Exception):
+    """Base class for all SDK failures; messages never include API response bodies."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        retry_after: str | None = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.retry_after = retry_after
+
+
+class ValidationError(RayonError, ValueError):
+    """A request argument is invalid; no API request was sent."""
+
+
+class TransportError(RayonError):
+    """The API request could not be completed."""
+
+
+class HTTPError(RayonError):
+    """The API returned an unsuccessful HTTP status."""
+
+
+class RedirectError(HTTPError):
+    """The API returned a redirect, which the SDK did not follow."""
+
+
+class InvalidResponseError(RayonError):
+    """The API response was not valid JSON or did not match the contract."""
+
+
+class SolveFailedError(RayonError):
+    """The API returned a valid failed or rejected solve result."""
+
+    def __init__(self, result: SolveResult, **metadata):
+        super().__init__("Rayon solve was not accepted.", **metadata)
+        self.result = result

rayon_sdk_py-0.1.0/src/rayon_sdk_py/models.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SolveResult:
+    """Captured telemetry and the metadata needed to replay it."""
+
+    status: str
+    method: str
+    target_url: str = field(repr=False)
+    duration_ms: int
+    headers: dict[str, str] = field(repr=False)
+    cookies: list[dict[str, Any]] = field(repr=False)
+    profile_used: dict[str, Any] = field(repr=False)
+    errors: list[str] = field(repr=False)

rayon_sdk_py-0.1.0/src/rayon_sdk_py/validation.py

@@ -0,0 +1,208 @@
+import json
+import math
+import re
+from email.utils import format_datetime, parsedate_to_datetime
+from urllib.parse import urlsplit
+
+from .errors import InvalidResponseError, ValidationError
+from .models import SolveResult
+
+
+def response_metadata(response, api_key):
+    request_id = response.headers.get("X-Request-ID")
+    if (
+        not isinstance(request_id, str)
+        or api_key in request_id
+        or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}", request_id)
+    ):
+        request_id = None
+    retry_after = response.headers.get("Retry-After")
+    if (
+        not isinstance(retry_after, str)
+        or api_key in retry_after
+        or len(retry_after) > 128
+    ):
+        retry_after = None
+    elif not re.fullmatch(r"[0-9]{1,10}", retry_after):
+        try:
+            parsed = parsedate_to_datetime(retry_after)
+            if format_datetime(parsed, usegmt=True) != retry_after:
+                retry_after = None
+        except (ValueError, TypeError, OverflowError):
+            retry_after = None
+    return {
+        "status_code": response.status_code,
+        "request_id": request_id,
+        "retry_after": retry_after,
+    }
+
+
+def _json_value(value, seen=None):
+    if value is None or isinstance(value, (str, bool, int)):
+        return True
+    if isinstance(value, float):
+        return math.isfinite(value)
+    if not isinstance(value, (dict, list)):
+        return False
+    seen = set() if seen is None else seen
+    if id(value) in seen:
+        return False
+    seen.add(id(value))
+    try:
+        if isinstance(value, dict):
+            return all(
+                isinstance(k, str) and _json_value(v, seen) for k, v in value.items()
+            )
+        return all(_json_value(item, seen) for item in value)
+    finally:
+        seen.remove(id(value))
+
+
+def _valid_url(value: str, *, base=False):
+    if not isinstance(value, str) or not value or len(value) > 8192:
+        return False
+    if any(ord(char) <= 32 or ord(char) == 127 for char in value) or "\\" in value:
+        return False
+    try:
+        parts = urlsplit(value)
+        port = parts.port
+        if (
+            parts.scheme not in {"http", "https"}
+            or not parts.hostname
+            or parts.username is not None
+            or parts.password is not None
+            or "#" in value
+        ):
+            return False
+        if base and (
+            "?" in value
+            or (
+                parts.scheme == "http"
+                and parts.hostname not in {"localhost", "127.0.0.1", "::1"}
+            )
+        ):
+            return False
+        return port is None or 0 < port <= 65535
+    except ValueError:
+        return False
+
+
+def validate_request(target_url, api_key, profile, base_url, timeout):
+    if not _valid_url(target_url):
+        raise ValidationError(
+            "target_url must be an HTTP(S) URL without credentials or a fragment."
+        )
+    if (
+        not isinstance(api_key, str)
+        or not api_key
+        or any(not 33 <= ord(char) <= 126 for char in api_key)
+    ):
+        raise ValidationError(
+            "api_key must be a nonempty ASCII token without whitespace."
+        )
+    if not _valid_url(base_url, base=True):
+        raise ValidationError(
+            "base_url must be HTTPS (or local HTTP) without credentials, query, or fragment."
+        )
+    try:
+        valid_timeout = (
+            isinstance(timeout, (int, float))
+            and not isinstance(timeout, bool)
+            and math.isfinite(timeout)
+            and timeout > 0
+        )
+    except OverflowError:
+        valid_timeout = False
+    if not valid_timeout:
+        raise ValidationError("timeout must be a finite positive number of seconds.")
+    try:
+        if profile is not None and (
+            not isinstance(profile, dict)
+            or not _json_value(profile)
+            or ("profile" in profile and not isinstance(profile["profile"], dict))
+        ):
+            raise ValueError
+        return (
+            None
+            if profile is None
+            else json.loads(json.dumps(profile, allow_nan=False))
+        )
+    except (ValueError, TypeError, RecursionError, OverflowError):
+        raise ValidationError(
+            "profile must be a JSON object with finite values and string keys."
+        ) from None
+
+
+def parse_result(body, target_url, metadata):
+    required = {
+        "status",
+        "method",
+        "target_url",
+        "duration_ms",
+        "headers",
+        "cookies",
+        "profile_used",
+        "errors",
+    }
+    valid = isinstance(body, dict) and required <= body.keys()
+    if valid:
+        valid = (
+            body["status"] in ("accepted", "failed", "rejected")
+            and body["method"] in ("v8_sandbox", "playwright")
+            and body["target_url"] == target_url
+            and type(body["duration_ms"]) is int
+            and body["duration_ms"] >= 0
+            and isinstance(body["headers"], dict)
+            and isinstance(body["cookies"], list)
+            and isinstance(body["profile_used"], dict)
+            and isinstance(body["errors"], list)
+            and all(isinstance(error, str) for error in body["errors"])
+        )
+    if valid:
+        try:
+            valid = _json_value(body["profile_used"]) and all(
+                isinstance(cookie, dict)
+                and {"name", "value", "domain", "path"} <= cookie.keys()
+                and all(
+                    isinstance(cookie[field], str)
+                    for field in ("name", "value", "domain", "path")
+                )
+                and _json_value(cookie)
+                for cookie in body["cookies"]
+            )
+        except RecursionError:
+            valid = False
+    if valid:
+        headers = body["headers"]
+        valid = all(
+            isinstance(name, str)
+            and name.isascii()
+            and isinstance(value, str)
+            and not any(
+                ord(char) < 32 or ord(char) == 127 or ord(char) > 255 for char in value
+            )
+            for name, value in headers.items()
+        )
+        if valid and body["status"] == "accepted":
+            families = []
+            suffixes = []
+            for name, value in headers.items():
+                match = re.fullmatch(
+                    r"([!#$%&'*+\-.^_`|~0-9A-Za-z]+)-([abcdfz])", name, re.IGNORECASE
+                )
+                if not match or (match[2].lower() != "d" and not value.strip()):
+                    valid = False
+                    break
+                families.append(match[1].lower())
+                suffixes.append(match[2].lower())
+            valid = (
+                valid
+                and len(headers) == 6
+                and len(set(families)) == 1
+                and set(suffixes) == set("abcdfz")
+            )
+    if not valid:
+        raise InvalidResponseError(
+            "Rayon API returned an invalid solve response.", **metadata
+        )
+    return SolveResult(**{field: body[field] for field in required})

rayon_sdk_py-0.1.0/src/rayon_sdk_py.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: rayon-sdk-py
+Version: 0.1.0
+Summary: Synchronous Python client for the Rayon API
+Author: Rayon API
+License-Expression: MIT
+Project-URL: Homepage, https://rayonapi.com
+Project-URL: Repository, https://github.com/Rayon-API/rayon-sdk-py
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curl_cffi<1,>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# Rayon Python SDK
+
+A synchronous client for `POST /solve` on the Rayon API. Python 3.10 or newer is required.
+
+Install from PyPI:
+
+```sh
+python -m pip install rayon-sdk-py
+```
+
+```python
+import os
+from rayon_sdk_py import solve
+
+result = solve(
+    "https://example.com/page",
+    os.environ["RAYON_API_KEY"],
+    # Optional JSON fingerprint values:
+    profile={"user_agent": "your browser user agent"},
+)
+print(result.status, result.method, result.duration_ms)
+```
+
+`solve(target_url, api_key, *, profile=None, base_url="https://api.rayonapi.com", timeout=150)`
+performs one request using curl_cffi Chrome impersonation. Timeout is a finite positive
+number of seconds. The SDK disables redirects and environment proxies, and never retries.
+Decoded response bodies are limited to 2 MiB; larger responses stop the transfer
+and raise `InvalidResponseError`.
+Custom API endpoints require HTTPS; HTTP is supported only for `localhost`, `127.0.0.1`,
+or `[::1]` development endpoints. URLs cannot contain credentials or fragments;
+the API base URL also cannot contain a query.
+
+The request body contains only `target_url` and, when supplied, `profile`.
+The API key is sent as a Bearer authorization header. Use an account and target
+domain approved for your application.
+
+An accepted result contains exactly one six-header family with a variable prefix
+and the suffixes `a`, `b`, `c`, `d`, `f`, and `z`; `d` may be empty.
+Acceptance means the headers were captured. It does not mean the target website
+verified them. `result.errors` can contain diagnostics from earlier solver tiers
+even when a fallback succeeds.
+
+`SolveResult` exposes `status`, `method`, `target_url`, `duration_ms`, `headers`,
+`cookies`, `profile_used`, and `errors`. Headers, cookies, URL, profile, and diagnostics
+are excluded from its repr because replay data can be sensitive.
+
+Cookies remain a list of records with required string fields `name`, `value`,
+`domain`, and `path`. Extra JSON metadata is preserved. Cookie scope matters:
+do not flatten cookies into a name/value dictionary. The SDK does not invent
+`secure`, expiry, or other browser attributes absent from the API response.
+When replaying a result, preserve cookie domains and paths and use the returned
+`profile_used` values for a compatible browser fingerprint.
+
+```python
+from curl_cffi.requests import Cookies
+
+jar = Cookies()
+for cookie in result.cookies:
+    jar.set(cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie["path"])
+# result.headers, jar, and result.profile_used are available for your replay client.
+```
+
+Handle failures explicitly:
+
+```python
+import os
+from rayon_sdk_py import HTTPError, RayonError, SolveFailedError, solve
+
+try:
+    result = solve("https://example.com/page", os.environ["RAYON_API_KEY"])
+except SolveFailedError as exc:
+    # HTTP 200 with a failed/rejected result also raises.
+    print(exc.result.status)
+except HTTPError as exc:
+    print(exc.status_code, exc.request_id, exc.retry_after)
+except RayonError as exc:
+    print(str(exc))
+```
+
+All SDK errors inherit from `RayonError`. `ValidationError` is raised before
+network access; `TransportError` covers network failures; `RedirectError` is an
+`HTTPError`; `InvalidResponseError` covers invalid JSON or malformed responses.
+Exception messages do not include response bodies, credentials, or underlying
+transport messages. HTTP response errors expose `status_code`, `request_id`, and
+`retry_after` (a validated seconds or HTTP date header string, when present).
+Invalid diagnostic headers or values reflecting the API key are discarded.
+Decide whether and when
+to retry in your application; admitted solve attempts can consume quota.
+
+For local development:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+Tests are offline and patch the transport. CI tests Python 3.10, 3.12, and 3.14
+and builds the wheel and source distribution. See [RELEASE.md](RELEASE.md) for
+the trusted publisher setup. Licensed under [MIT](LICENSE).

rayon_sdk_py-0.1.0/src/rayon_sdk_py.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/rayon_sdk_py/__init__.py
+src/rayon_sdk_py/client.py
+src/rayon_sdk_py/errors.py
+src/rayon_sdk_py/models.py
+src/rayon_sdk_py/validation.py
+src/rayon_sdk_py.egg-info/PKG-INFO
+src/rayon_sdk_py.egg-info/SOURCES.txt
+src/rayon_sdk_py.egg-info/dependency_links.txt
+src/rayon_sdk_py.egg-info/requires.txt
+src/rayon_sdk_py.egg-info/top_level.txt
+tests/test_sdk.py

rayon_sdk_py-0.1.0/src/rayon_sdk_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rayon_sdk_py-0.1.0/src/rayon_sdk_py.egg-info/requires.txt

@@ -0,0 +1,6 @@
+curl_cffi<1,>=0.13
+
+[dev]
+pytest>=8
+build>=1.2
+twine>=6

rayon_sdk_py-0.1.0/src/rayon_sdk_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+rayon_sdk_py

rayon_sdk_py-0.1.0/tests/test_sdk.py

@@ -0,0 +1,481 @@
+import importlib
+
+import pytest
+from curl_cffi import requests
+
+
+TARGET = "https://example.com/page"
+KEY = "rayon_test_secret"
+
+
+def accepted(**changes):
+    body = {
+        "status": "accepted",
+        "method": "playwright",
+        "target_url": TARGET,
+        "duration_ms": 123,
+        "headers": {
+            f"X-RandomPrefix-{suffix}": "" if suffix == "d" else f"secret-{suffix}"
+            for suffix in "abcdfz"
+        },
+        "cookies": [
+            {
+                "name": "session",
+                "value": "cookie-secret",
+                "domain": ".example.com",
+                "path": "/page",
+            }
+        ],
+        "profile_used": {"user_agent": "profile-secret"},
+        "errors": ["Earlier tier failed"],
+    }
+    body.update(changes)
+    return body
+
+
+class Response:
+    def __init__(self, body=None, status=200, headers=None):
+        self.body = accepted() if body is None else body
+        self.status_code = status
+        self.headers = requests.Headers(headers or {})
+
+    def json(self):
+        if isinstance(self.body, Exception):
+            raise self.body
+        return self.body
+
+
+@pytest.fixture
+def sdk():
+    try:
+        return importlib.import_module("rayon_sdk_py")
+    except ModuleNotFoundError:
+        pytest.fail("The public SDK module is not implemented")
+
+
+@pytest.fixture
+def transport(monkeypatch):
+    state = {"response": Response(), "calls": [], "session_options": []}
+
+    class Session:
+        def __init__(self, **options):
+            state["session_options"].append(options)
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *args):
+            state["closed"] = True
+
+        def post(self, url, **options):
+            state["calls"].append((url, options))
+            if "exception" in state:
+                raise state["exception"]
+            for chunk in state.get("chunks", []):
+                callback = options.get("content_callback")
+                if callback is not None and callback(chunk) != len(chunk):
+                    state["aborted"] = True
+                    raise requests.exceptions.RequestException("Body callback aborted")
+            return state["response"]
+
+    monkeypatch.setattr(requests, "Session", Session)
+    return state
+
+
+def test_solve_sends_only_public_body_and_returns_accepted_fallback(transport):
+    try:
+        sdk = importlib.import_module("rayon_sdk_py")
+    except ModuleNotFoundError:
+        pytest.fail("The public SDK module is not implemented")
+    profile = {"user_agent": "Chrome"}
+    result = sdk.solve(TARGET, KEY, profile=profile)
+    assert isinstance(result, sdk.SolveResult)
+    assert result.status == "accepted"
+    assert result.errors == ["Earlier tier failed"]
+    assert result.headers["X-RandomPrefix-d"] == ""
+    assert result.cookies == accepted()["cookies"]
+    assert result.profile_used == accepted()["profile_used"]
+    url, options = transport["calls"][0]
+    assert url == "https://api.rayonapi.com/solve"
+    assert options["json"] == {"target_url": TARGET, "profile": profile}
+    assert options["headers"]["Authorization"] == f"Bearer {KEY}"
+    assert options["timeout"] == 150
+    assert options["allow_redirects"] is False
+    assert transport["session_options"][0]["trust_env"] is False
+    assert transport["session_options"][0]["impersonate"] == "chrome"
+    assert transport["closed"]
+
+
+def test_defaults_omit_profile_and_custom_base_is_supported(sdk, transport):
+    sdk.solve(TARGET, KEY, base_url="http://localhost:8080/api/", timeout=2.5)
+    url, options = transport["calls"][0]
+    assert url == "http://localhost:8080/api/solve"
+    assert options["json"] == {"target_url": TARGET}
+    assert options["timeout"] == 2.5
+
+
+def test_result_repr_hides_replay_credentials(sdk, transport):
+    result = sdk.solve(TARGET, KEY)
+    assert all(
+        secret not in repr(result)
+        for secret in (KEY, "cookie-secret", "profile-secret", "secret-a")
+    )
+
+
+@pytest.mark.parametrize(
+    "target",
+    [
+        None,
+        "",
+        "ftp://example.com",
+        "https:///page",
+        "https://u:p@example.com",
+        "https://example.com\n",
+        "https://example.com:bad",
+        "https://example.com/#fragment",
+    ],
+)
+def test_invalid_target_never_reaches_network(sdk, transport, target):
+    with pytest.raises(sdk.ValidationError):
+        sdk.solve(target, KEY)
+    assert not transport["calls"]
+
+
+@pytest.mark.parametrize(
+    "key", [None, "", " ", "key\r\nx: value", "key with space", "é"]
+)
+def test_invalid_api_key_never_reaches_network(sdk, transport, key):
+    with pytest.raises(sdk.ValidationError):
+        sdk.solve(TARGET, key)
+    assert not transport["calls"]
+
+
+@pytest.mark.parametrize(
+    "timeout", [0, -1, float("inf"), float("nan"), None, True, "10"]
+)
+def test_invalid_timeout_never_reaches_network(sdk, transport, timeout):
+    with pytest.raises(sdk.ValidationError):
+        sdk.solve(TARGET, KEY, timeout=timeout)
+    assert not transport["calls"]
+
+
+@pytest.mark.parametrize(
+    "base",
+    [
+        None,
+        "",
+        "ftp://example.com",
+        "http://example.com",
+        "https://u:p@example.com",
+        "https://example.com?key=secret",
+        "https://example.com#fragment",
+        "https://example.com\t",
+        "https://example.com:bad",
+    ],
+)
+def test_invalid_base_url_never_reaches_network(sdk, transport, base):
+    with pytest.raises(sdk.ValidationError):
+        sdk.solve(TARGET, KEY, base_url=base)
+    assert not transport["calls"]
+
+
+@pytest.mark.parametrize(
+    "profile",
+    [
+        [],
+        {"bad": object()},
+        {"bad": float("nan")},
+        {"profile": "bad"},
+        {1: "bad"},
+        {"nested": {1: "bad"}},
+    ],
+)
+def test_invalid_profile_never_reaches_network(sdk, transport, profile):
+    with pytest.raises(sdk.ValidationError):
+        sdk.solve(TARGET, KEY, profile=profile)
+    assert not transport["calls"]
+
+
+@pytest.mark.parametrize("status", [401, 403, 422, 429, 503])
+def test_http_errors_are_safe_and_expose_diagnostics(sdk, transport, status):
+    transport["response"] = Response(
+        {"secret": KEY}, status, {"X-Request-ID": "req-123", "Retry-After": "30"}
+    )
+    with pytest.raises(sdk.HTTPError) as caught:
+        sdk.solve(TARGET, KEY)
+    error = caught.value
+    assert error.status_code == status
+    assert error.request_id == "req-123"
+    assert error.retry_after == "30"
+    assert KEY not in str(error) + repr(error)
+    assert len(transport["calls"]) == 1
+
+
+@pytest.mark.parametrize("status", [301, 302, 307, 308])
+def test_redirects_are_typed_and_not_followed(sdk, transport, status):
+    transport["response"] = Response(
+        status=status, headers={"Location": f"https://example.com/{KEY}"}
+    )
+    with pytest.raises(sdk.RedirectError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert caught.value.status_code == status
+    assert KEY not in str(caught.value)
+    assert len(transport["calls"]) == 1
+
+
+def test_network_failure_is_typed_safe_and_not_retried(sdk, transport):
+    transport["exception"] = requests.exceptions.RequestException(
+        f"Authorization: {KEY}"
+    )
+    with pytest.raises(sdk.TransportError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert KEY not in str(caught.value) + repr(caught.value)
+    assert caught.value.__cause__ is None
+    assert len(transport["calls"]) == 1
+
+
+@pytest.mark.parametrize("failure", [ValueError, UnicodeError, RecursionError])
+def test_invalid_json_is_typed_safe(sdk, transport, failure):
+    transport["response"] = Response(failure(KEY))
+    with pytest.raises(sdk.InvalidResponseError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert KEY not in str(caught.value)
+    assert caught.value.__cause__ is None
+
+
+def test_cookie_scope_and_extra_metadata_are_preserved(sdk, transport):
+    cookies = [
+        {"name": "session", "value": "first", "domain": "example.com", "path": "/"},
+        {
+            "name": "session",
+            "value": "second",
+            "domain": ".example.com",
+            "path": "/page",
+            "future": {"flag": True},
+        },
+    ]
+    transport["response"] = Response(accepted(cookies=cookies))
+    result = sdk.solve(TARGET, KEY)
+    assert result.cookies == cookies
+    assert all(
+        "secure" not in cookie and "expiry" not in cookie for cookie in result.cookies
+    )
+
+
+def test_header_family_is_case_insensitive_and_prefix_is_variable(sdk, transport):
+    headers = {
+        f"Telemetry_9-{suffix}": "" if suffix == "D" else "value" for suffix in "ABCDfZ"
+    }
+    transport["response"] = Response(accepted(headers=headers))
+    assert sdk.solve(TARGET, KEY).headers == headers
+
+
+@pytest.mark.parametrize("value", ["value\u0100", "value\u20ac", "value\U0001f680"])
+def test_response_headers_reject_characters_outside_latin1(sdk, transport, value):
+    headers = {**accepted()["headers"], "X-RandomPrefix-a": value}
+    transport["response"] = Response(accepted(headers=headers))
+    with pytest.raises(sdk.InvalidResponseError):
+        sdk.solve(TARGET, KEY)
+
+
+def test_response_headers_allow_latin1_values(sdk, transport):
+    headers = {**accepted()["headers"], "X-RandomPrefix-a": "value\u00e9"}
+    transport["response"] = Response(accepted(headers=headers))
+    assert sdk.solve(TARGET, KEY).headers == headers
+
+
+@pytest.mark.parametrize("prefix", ["X-\u212a", "X-\u0130"])
+def test_response_header_names_reject_unicode_casefold_matches(sdk, transport, prefix):
+    headers = {f"{prefix}-{suffix}": "value" for suffix in "abcdfz"}
+    transport["response"] = Response(accepted(headers=headers))
+    with pytest.raises(sdk.InvalidResponseError):
+        sdk.solve(TARGET, KEY)
+
+
+def test_header_family_has_no_arbitrary_field_length_limits(sdk, transport):
+    prefix = "X-" + "P" * 300
+    headers = {f"{prefix}-{suffix}": "value" * 4000 for suffix in "abcdfz"}
+    transport["response"] = Response(accepted(headers=headers))
+    assert sdk.solve(TARGET, KEY).headers == headers
+
+
+def test_cycle_in_profile_is_a_validation_error(sdk, transport):
+    profile = {}
+    profile["nested"] = profile
+    with pytest.raises(sdk.ValidationError):
+        sdk.solve(TARGET, KEY, profile=profile)
+    assert not transport["calls"]
+
+
+@pytest.mark.parametrize("status", ["failed", "rejected"])
+def test_nonaccepted_200_throws_solve_failure(sdk, transport, status):
+    transport["response"] = Response(accepted(status=status, headers={}, errors=[KEY]))
+    with pytest.raises(sdk.SolveFailedError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert caught.value.result.status == status
+    assert caught.value.result.errors == [KEY]
+    assert KEY not in str(caught.value) + repr(caught.value) + repr(caught.value.result)
+
+
+@pytest.mark.parametrize(
+    "changes",
+    [
+        {"status": "unexpected"},
+        {"method": "none"},
+        {"target_url": "https://different.example/"},
+        {"duration_ms": -1},
+        {"duration_ms": True},
+        {"duration_ms": 1.5},
+        {"headers": {"X-Prefix-a": "a"}},
+        {"headers": {f"X-Prefix-{s}": "" for s in "abcdfz"}},
+        {"headers": {**accepted()["headers"], "X-Other-a": "a"}},
+        {"headers": {**accepted()["headers"], "X-RandomPrefix-a": 1}},
+        {"headers": {**accepted()["headers"], "X-RandomPrefix-a": "a\r\nBad: value"}},
+        {"cookies": {}},
+        {"cookies": [{"name": "n", "value": "v"}]},
+        {"cookies": [{"name": "n", "value": 1, "domain": "example.com", "path": "/"}]},
+        {"profile_used": []},
+        {"errors": "error"},
+        {"errors": [1]},
+    ],
+)
+def test_malformed_response_is_rejected(sdk, transport, changes):
+    transport["response"] = Response(accepted(**changes))
+    with pytest.raises(sdk.InvalidResponseError):
+        sdk.solve(TARGET, KEY)
+
+
+def test_missing_response_fields_are_not_synthesized(sdk, transport):
+    body = accepted()
+    del body["cookies"]
+    transport["response"] = Response(body)
+    with pytest.raises(sdk.InvalidResponseError):
+        sdk.solve(TARGET, KEY)
+
+
+def test_actual_curl_adapter_disables_environment_proxy_without_network(
+    sdk, monkeypatch
+):
+    from curl_cffi import Curl, CurlError, CurlOpt
+
+    options = []
+    original = Curl.setopt
+
+    def setopt(curl, option, value):
+        options.append((option, value))
+        return original(curl, option, value)
+
+    def perform(curl):
+        raise CurlError("Network disabled by test", code=7)
+
+    monkeypatch.setenv("HTTPS_PROXY", "http://proxy.invalid:3128")
+    monkeypatch.setenv("ALL_PROXY", "http://proxy.invalid:3128")
+    monkeypatch.setattr(Curl, "setopt", setopt)
+    monkeypatch.setattr(Curl, "perform", perform)
+    with pytest.raises(sdk.TransportError):
+        sdk.solve(TARGET, KEY)
+    assert (CurlOpt.PROXY, "") in options
+    assert (CurlOpt.FOLLOWLOCATION, 0) in options
+
+
+@pytest.mark.parametrize(
+    "request_id,retry_after",
+    [
+        (KEY, KEY),
+        ("prefix-" + KEY, "30\r\nBad: value"),
+        ("x" * 129, "99999999999"),
+        ("id\nsecret", "tomorrow"),
+        ("Bearer secret", "Fri, 99 Oct 2026 00:00:00 GMT"),
+    ],
+)
+def test_http_diagnostics_drop_reflected_credentials_and_invalid_headers(
+    sdk, transport, request_id, retry_after
+):
+    transport["response"] = Response(
+        status=429, headers={"X-Request-ID": request_id, "Retry-After": retry_after}
+    )
+    with pytest.raises(sdk.HTTPError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert caught.value.request_id is None
+    assert caught.value.retry_after is None
+    assert KEY not in str(caught.value.__dict__)
+
+
+def test_valid_http_date_retry_after_is_preserved(sdk, transport):
+    value = "Mon, 12 Oct 2026 10:00:00 GMT"
+    transport["response"] = Response(status=429, headers={"Retry-After": value})
+    with pytest.raises(sdk.HTTPError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert caught.value.retry_after == value
+
+
+def test_oversized_decoded_response_aborts_before_collecting_more(sdk, transport):
+    transport["chunks"] = [
+        b"x" * (1024 * 1024),
+        b"y" * (1024 * 1024),
+        b"z",
+        KEY.encode(),
+    ]
+    with pytest.raises(sdk.InvalidResponseError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert transport.get("aborted") is True
+    assert KEY not in str(caught.value)
+
+
+def test_actual_adapter_body_callback_limits_decoded_bytes_and_preserves_timeout(
+    sdk, monkeypatch
+):
+    from curl_cffi import Curl, CurlError, CurlOpt
+
+    options = {}
+    original = Curl.setopt
+
+    def setopt(curl, option, value):
+        options[option] = value
+        return original(curl, option, value)
+
+    def perform(curl):
+        callback = options.get(CurlOpt.WRITEFUNCTION)
+        if callable(callback):
+            assert callback(b"x" * (2 * 1024 * 1024)) == 2 * 1024 * 1024
+            assert callback(KEY.encode()) != len(KEY)
+        raise CurlError("Write aborted: " + KEY, code=23)
+
+    monkeypatch.setattr(Curl, "setopt", setopt)
+    monkeypatch.setattr(Curl, "perform", perform)
+    with pytest.raises(sdk.InvalidResponseError) as caught:
+        sdk.solve(TARGET, KEY)
+    assert callable(options[CurlOpt.WRITEFUNCTION])
+    assert options[CurlOpt.TIMEOUT_MS] == 150_000
+    assert KEY not in str(caught.value)
+
+
+def test_actual_adapter_parses_json_from_multiple_decoded_chunks(sdk, monkeypatch):
+    import json
+    from curl_cffi import Curl, CurlOpt
+
+    options = {}
+    original = Curl.setopt
+    payload = json.dumps(accepted()).encode()
+
+    def setopt(curl, option, value):
+        options[option] = value
+        return original(curl, option, value)
+
+    def perform(curl):
+        callback = options[CurlOpt.WRITEFUNCTION]
+        assert callback(payload[:30]) == 30
+        assert callback(payload[30:]) == len(payload) - 30
+
+    def parse_response(*args, **kwargs):
+        response = requests.Response()
+        response.status_code = 200
+        response.headers = requests.Headers({"X-Request-ID": "req-123"})
+        return response
+
+    monkeypatch.setattr(Curl, "setopt", setopt)
+    monkeypatch.setattr(Curl, "perform", perform)
+    monkeypatch.setattr(requests.Session, "_parse_response", parse_response)
+    result = sdk.solve(TARGET, KEY)
+    assert result.headers == accepted()["headers"]
+    assert result.cookies == accepted()["cookies"]