rayon-sdk-py 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+rayon_sdk_py/__init__.py,sha256=eCgjTsOFv8Ysk8fmUxDC7myKKNuZbLZSKFvNdA-FRec,495
+rayon_sdk_py/client.py,sha256=D5ahI-kRqRG9j-yQrDR8Op2ywbxODEzGZdQuEU5Ryq4,2652
+rayon_sdk_py/errors.py,sha256=P44laeaBsQVqp3e4aBJEUGYJMj7XhuQvYwULI6zC4XQ,1264
+rayon_sdk_py/models.py,sha256=b7WBlRkzqZ1Qdckw493GkLNkLDyu9Pqnv_RF3QgXmAM,467
+rayon_sdk_py/validation.py,sha256=vSZNUuTaPjyPd0QaoSlq9ZPktQ35IiPuWF7JYB3Ks-4,6999
+rayon_sdk_py-0.1.0.dist-info/licenses/LICENSE,sha256=ZpwTpWfU2CEge2rhxDciRXkJlbzTCrWgKA75VTgfHsQ,1065
+rayon_sdk_py-0.1.0.dist-info/METADATA,sha256=Wdxwy-aomnUR8aWDJfxX7tXKQurjyDcPnVoW-PZ7iB8,4821
+rayon_sdk_py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rayon_sdk_py-0.1.0.dist-info/top_level.txt,sha256=2eDfZYL46oPSnsHv430ZRt5iyKl2zAk2ilIemakP05U,13
+rayon_sdk_py-0.1.0.dist-info/RECORD,,

rayon_sdk_py-0.1.0.dist-info/WHEEL

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

rayon_sdk_py-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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