reversal-sdk 1.0.1__tar.gz

reversal_sdk-1.0.1/.gitignore

@@ -0,0 +1,75 @@
+# ── Python ────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+
+# ── Virtual environments ──────────────────────
+.venv/
+venv/
+env/
+ENV/
+.env/
+
+# ── Environment variables ─────────────────────
+.env
+.env.local
+.env.*.local
+
+# ── IDE ───────────────────────────────────────
+.vscode/settings.json
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ── Test / coverage artefacts ─────────────────
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.cover
+
+# ── Jupyter ───────────────────────────────────
+.ipynb_checkpoints/
+*.ipynb
+
+# ── Misc ──────────────────────────────────────
+*.log
+*.tmp
+*.bak
+
+# ── Reversal Engine — runtime data ────────────
+reversal.db
+reversal*.db
+uploads/
+
+# ── SDK build artefacts ───────────────────────
+sdk/python/dist/
+sdk/python/build/
+sdk/python/*.egg-info/
+sdk/typescript/dist/
+sdk/typescript/node_modules/
+
+# ── Test assets (images, screenshots) ─────────
+tests/*.png
+tests/*.jpg
+tests/*.jpeg
+tests/*.webp
+tests/*.gif
+
+# ── Prometheus / metrics ──────────────────────
+*.prom
+
+# ── macOS / Linux ─────────────────────────────
+.DS_Store
+Thumbs.db
+*.swp

reversal_sdk-1.0.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: reversal-sdk
+Version: 1.0.1
+Summary: Official Python SDK for the Reversal Engine API
+Project-URL: Homepage, https://github.com/Etytabs/REVERSAL
+Project-URL: Repository, https://github.com/Etytabs/REVERSAL
+Project-URL: Issues, https://github.com/Etytabs/REVERSAL/issues
+Project-URL: Changelog, https://github.com/Etytabs/REVERSAL/releases
+License: MIT
+Keywords: agent,ai,html,json,llm,mcp,pdf,reversal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pydantic>=2; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Reversal SDK — Python
+
+Client Python officiel pour l'API [Reversal Engine](https://github.com/Etytabs/REVERSAL).
+
+## Installation
+
+```bash
+pip install reversal-sdk
+```
+
+Ou depuis les sources :
+
+```bash
+pip install ./sdk/python
+```
+
+## Démarrage rapide
+
+```python
+from reversal_sdk import ReversalClient
+
+client = ReversalClient(api_key="sk-rev-...")
+
+# Analyser une URL
+result = client.reverse("https://example.com")
+print(result["content_type"], result["content"])
+
+# Analyser un fichier local (upload automatique)
+result = client.reverse("rapport.pdf")
+
+# Mode asynchrone — soumettre un job
+job = client.submit_job("gros-fichier.pdf")
+# … attendre le résultat en polling
+result = client.wait_for_job(job["job_id"])
+
+# Ou streamer les événements en temps réel
+for event in client.stream_job(job["job_id"]):
+    print(event["event"], event["data"])
+
+# Uploader un fichier manuellement
+info = client.upload("document.pdf")
+result = client.reverse(f"file:{info['file_id']}")
+
+# Batch (jusqu'à 10 sources)
+results = client.batch(["https://a.com", "https://b.com"])
+
+# Infos compte
+me = client.me()
+print(me["plan"], me["usage"], "/", me["quota"])
+```
+
+## Référence API
+
+| Méthode | Description |
+|---|---|
+| `reverse(source, *, async_mode, extra)` | Parse une source, retourne le résultat structuré |
+| `submit_job(source)` | Équivalent à `reverse(..., async_mode=True)` |
+| `wait_for_job(job_id, *, poll_interval, timeout)` | Polling jusqu'à `done` ou `failed` |
+| `get_job(job_id)` | Récupère l'état courant d'un job |
+| `stream_job(job_id)` | Générateur d'événements SSE |
+| `upload(path)` | Upload un fichier local |
+| `batch(sources, *, async_mode)` | Parse plusieurs sources en une requête |
+| `detect(source)` | Détecte le type sans parser |
+| `delete_file(file_id)` | Supprime un fichier uploadé |
+| `me()` | Infos compte (plan, usage, quota) |
+
+## Exceptions
+
+```python
+from reversal_sdk import (
+    ReversalError,   # base
+    AuthError,       # 401 / 403
+    NotFoundError,   # 404
+    RateLimitError,  # 429
+    QuotaError,      # 402
+    ServerError,     # 5xx
+)
+```
+
+## Variables d'environnement
+
+| Variable | Description |
+|---|---|
+| `REVERSAL_API_KEY` | Clé API (alternative à `api_key=`) |

reversal_sdk-1.0.1/README.md

@@ -0,0 +1,84 @@
+# Reversal SDK — Python
+
+Client Python officiel pour l'API [Reversal Engine](https://github.com/Etytabs/REVERSAL).
+
+## Installation
+
+```bash
+pip install reversal-sdk
+```
+
+Ou depuis les sources :
+
+```bash
+pip install ./sdk/python
+```
+
+## Démarrage rapide
+
+```python
+from reversal_sdk import ReversalClient
+
+client = ReversalClient(api_key="sk-rev-...")
+
+# Analyser une URL
+result = client.reverse("https://example.com")
+print(result["content_type"], result["content"])
+
+# Analyser un fichier local (upload automatique)
+result = client.reverse("rapport.pdf")
+
+# Mode asynchrone — soumettre un job
+job = client.submit_job("gros-fichier.pdf")
+# … attendre le résultat en polling
+result = client.wait_for_job(job["job_id"])
+
+# Ou streamer les événements en temps réel
+for event in client.stream_job(job["job_id"]):
+    print(event["event"], event["data"])
+
+# Uploader un fichier manuellement
+info = client.upload("document.pdf")
+result = client.reverse(f"file:{info['file_id']}")
+
+# Batch (jusqu'à 10 sources)
+results = client.batch(["https://a.com", "https://b.com"])
+
+# Infos compte
+me = client.me()
+print(me["plan"], me["usage"], "/", me["quota"])
+```
+
+## Référence API
+
+| Méthode | Description |
+|---|---|
+| `reverse(source, *, async_mode, extra)` | Parse une source, retourne le résultat structuré |
+| `submit_job(source)` | Équivalent à `reverse(..., async_mode=True)` |
+| `wait_for_job(job_id, *, poll_interval, timeout)` | Polling jusqu'à `done` ou `failed` |
+| `get_job(job_id)` | Récupère l'état courant d'un job |
+| `stream_job(job_id)` | Générateur d'événements SSE |
+| `upload(path)` | Upload un fichier local |
+| `batch(sources, *, async_mode)` | Parse plusieurs sources en une requête |
+| `detect(source)` | Détecte le type sans parser |
+| `delete_file(file_id)` | Supprime un fichier uploadé |
+| `me()` | Infos compte (plan, usage, quota) |
+
+## Exceptions
+
+```python
+from reversal_sdk import (
+    ReversalError,   # base
+    AuthError,       # 401 / 403
+    NotFoundError,   # 404
+    RateLimitError,  # 429
+    QuotaError,      # 402
+    ServerError,     # 5xx
+)
+```
+
+## Variables d'environnement
+
+| Variable | Description |
+|---|---|
+| `REVERSAL_API_KEY` | Clé API (alternative à `api_key=`) |

reversal_sdk-1.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reversal-sdk"
+version = "1.0.1"
+description = "Official Python SDK for the Reversal Engine API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["ai", "llm", "mcp", "pdf", "html", "json", "agent", "reversal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "responses>=0.25",
+    "pydantic>=2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Etytabs/REVERSAL"
+Repository = "https://github.com/Etytabs/REVERSAL"
+Issues = "https://github.com/Etytabs/REVERSAL/issues"
+Changelog = "https://github.com/Etytabs/REVERSAL/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["reversal_sdk"]

reversal_sdk-1.0.1/reversal_sdk/__init__.py

@@ -0,0 +1,30 @@
+"""Reversal SDK — Python client package."""
+
+from .client import ReversalClient
+from .exceptions import (
+    AuthError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ReversalError,
+    ServerError,
+)
+from .models import BatchResult, FileUpload, JobInfo, ReverseResult, SSEEvent, UserInfo
+
+__all__ = [
+    "ReversalClient",
+    # exceptions
+    "ReversalError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "QuotaError",
+    "ServerError",
+    # models
+    "JobInfo",
+    "ReverseResult",
+    "FileUpload",
+    "BatchResult",
+    "SSEEvent",
+    "UserInfo",
+]

reversal_sdk-1.0.1/reversal_sdk/client.py

@@ -0,0 +1,259 @@
+"""
+Reversal SDK — Python client.
+
+Usage::
+
+    from reversal_sdk import ReversalClient
+
+    client = ReversalClient(api_key="sk-rev-...")
+    result = client.reverse("https://example.com")
+    result = client.reverse("path/to/file.pdf", async_mode=True)
+    job    = client.submit_job("path/to/big.pdf")
+    result = client.wait_for_job(job["job_id"])
+    fid    = client.upload("path/to/file.pdf")
+    client.batch(["https://a.com", "https://b.com"])
+    for event in client.stream_job(job["job_id"]):
+        print(event)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Generator, Iterator
+from urllib.parse import urljoin
+
+from .exceptions import AuthError, NotFoundError, QuotaError, RateLimitError, ReversalError, ServerError
+
+try:
+    import requests as _requests
+    _REQUESTS_OK = True
+except ImportError:  # pragma: no cover
+    _REQUESTS_OK = False
+
+_DEFAULT_BASE_URL = "https://api.reversal.dev/v1"
+_DEFAULT_TIMEOUT = 30
+_DEFAULT_POLL_INTERVAL = 2.0
+_DEFAULT_POLL_MAX_WAIT = 300.0
+
+
+class ReversalClient:
+    """Synchronous HTTP client for the Reversal Engine API.
+
+    Parameters
+    ----------
+    api_key:
+        Your Reversal API key (``sk-rev-...``).  Falls back to the
+        ``REVERSAL_API_KEY`` environment variable when omitted.
+    base_url:
+        Base URL of the API server (default: ``https://api.reversal.dev/v1``).
+        Override for self-hosted deployments.
+    timeout:
+        Default HTTP timeout in seconds (default: ``30``).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int | float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not _REQUESTS_OK:  # pragma: no cover
+            raise ImportError("The 'requests' package is required. Run: pip install requests")
+
+        self._api_key = api_key or os.environ.get("REVERSAL_API_KEY", "")
+        if not self._api_key:
+            raise AuthError("No API key provided. Pass api_key= or set REVERSAL_API_KEY.")
+
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = _requests.Session()
+        self._session.headers.update({"Authorization": f"Bearer {self._api_key}"})
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def reverse(
+        self,
+        source: str,
+        *,
+        async_mode: bool = False,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Parse *source* (URL, ``file:<file_id>``, or local path) and return
+        the structured result.
+
+        When *async_mode* is ``True`` the server queues the job and this
+        method returns the raw job dict; use :meth:`wait_for_job` to poll.
+        """
+        payload: dict[str, Any] = {"source": self._resolve_source(source), "async_mode": async_mode}
+        if extra:
+            payload.update(extra)
+        return self._post("/reverse", json=payload)
+
+    def submit_job(self, source: str, **extra: Any) -> dict[str, Any]:
+        """Queue a heavy job and return immediately with job metadata.
+
+        Equivalent to ``reverse(source, async_mode=True)``.
+        """
+        return self.reverse(source, async_mode=True, extra=extra or None)
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+        timeout: float = _DEFAULT_POLL_MAX_WAIT,
+    ) -> dict[str, Any]:
+        """Poll ``GET /jobs/{job_id}`` until *done* or *failed*, then return.
+
+        Raises :class:`~reversal_sdk.exceptions.ReversalError` on timeout or
+        if the job fails.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            status = job.get("status", "")
+            if status == "done":
+                return job
+            if status == "failed":
+                raise ReversalError(
+                    f"Job {job_id} failed: {job.get('error', 'unknown error')}",
+                    response=job,
+                )
+            if time.monotonic() > deadline:
+                raise ReversalError(f"Timeout waiting for job {job_id} after {timeout}s")
+            time.sleep(poll_interval)
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        """Fetch the current state of a job."""
+        return self._get(f"/jobs/{job_id}")
+
+    def stream_job(self, job_id: str) -> Iterator[dict[str, Any]]:
+        """Open an SSE stream for *job_id* and yield parsed event dicts.
+
+        Each yielded dict has ``event`` (str) and ``data`` (dict) keys.
+
+        Example::
+
+            for event in client.stream_job(job_id):
+                print(event["event"], event["data"]["status"])
+        """
+        url = self._url(f"/jobs/{job_id}/stream")
+        with self._session.get(url, stream=True, timeout=self._timeout,
+                               headers={"Accept": "text/event-stream"}) as resp:
+            self._raise_for_status(resp)
+            yield from _parse_sse_stream(resp.iter_lines(decode_unicode=True))
+
+    def upload(self, path: str | Path) -> dict[str, Any]:
+        """Upload a local file and return ``{"file_id": ..., "filename": ..., "size": ...}``."""
+        path = Path(path)
+        with path.open("rb") as fh:
+            return self._post("/upload", files={"file": (path.name, fh, "application/octet-stream")})
+
+    def batch(
+        self,
+        sources: list[str],
+        *,
+        async_mode: bool = False,
+    ) -> dict[str, Any]:
+        """Parse up to 10 *sources* in one request and return aggregated results."""
+        resolved = [self._resolve_source(s) for s in sources]
+        return self._post("/batch", json={"sources": resolved, "async_mode": async_mode})
+
+    def detect(self, source: str) -> dict[str, Any]:
+        """Detect the content type of *source* without full parsing."""
+        return self._post("/detect", json={"source": self._resolve_source(source)})
+
+    def delete_file(self, file_id: str) -> dict[str, Any]:
+        """Delete a previously uploaded file."""
+        return self._delete(f"/files/{file_id}")
+
+    def me(self) -> dict[str, Any]:
+        """Return the current user's account information (plan, usage, quota)."""
+        return self._get("/me")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    def _resolve_source(self, source: str) -> str:
+        """If *source* is an existing local path, upload it first."""
+        p = Path(source)
+        if p.exists() and p.is_file():
+            result = self.upload(p)
+            return f"file:{result['file_id']}"
+        return source
+
+    def _get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        resp = self._session.get(self._url(path), timeout=self._timeout, **kwargs)
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def _post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        resp = self._session.post(self._url(path), timeout=self._timeout, **kwargs)
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def _delete(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        resp = self._session.delete(self._url(path), timeout=self._timeout, **kwargs)
+        self._raise_for_status(resp)
+        return resp.json()
+
+    @staticmethod
+    def _raise_for_status(resp: Any) -> None:  # noqa: ANN401
+        if resp.status_code < 400:
+            return
+        body: dict[str, Any] = {}
+        try:
+            body = resp.json()
+        except Exception:
+            pass
+        detail = body.get("detail", resp.text or "Unknown error")
+        code = resp.status_code
+        if code in (401, 403):
+            raise AuthError(detail, status_code=code, response=body)
+        if code == 404:
+            raise NotFoundError(detail, status_code=code, response=body)
+        if code == 402:
+            raise QuotaError(detail, status_code=code, response=body)
+        if code == 429:
+            raise RateLimitError(detail, status_code=code, response=body)
+        if code >= 500:
+            raise ServerError(detail, status_code=code, response=body)
+        raise ReversalError(detail, status_code=code, response=body)
+
+
+# ---------------------------------------------------------------------------
+# SSE parser (minimal, no external dependency)
+# ---------------------------------------------------------------------------
+
+def _parse_sse_stream(lines: Iterator[str]) -> Generator[dict[str, Any], None, None]:
+    """Parse a stream of SSE text lines into event dicts."""
+    event_name = "message"
+    data_buf: list[str] = []
+
+    for line in lines:
+        if not line:
+            # blank line = dispatch event
+            if data_buf:
+                raw = "\n".join(data_buf)
+                try:
+                    parsed = json.loads(raw)
+                except json.JSONDecodeError:
+                    parsed = raw  # type: ignore[assignment]
+                yield {"event": event_name, "data": parsed}
+                event_name = "message"
+                data_buf = []
+            continue
+
+        if line.startswith("event:"):
+            event_name = line[len("event:"):].strip()
+        elif line.startswith("data:"):
+            data_buf.append(line[len("data:"):].strip())

reversal_sdk-1.0.1/reversal_sdk/exceptions.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by the Reversal SDK."""
+
+from __future__ import annotations
+
+
+class ReversalError(Exception):
+    """Base exception for all SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, response: dict | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response or {}
+
+
+class AuthError(ReversalError):
+    """Raised when the API key is missing, invalid, or expired (HTTP 401/403)."""
+
+
+class NotFoundError(ReversalError):
+    """Raised when a resource is not found (HTTP 404)."""
+
+
+class RateLimitError(ReversalError):
+    """Raised when the rate limit for the current plan is exceeded (HTTP 429)."""
+
+
+class QuotaError(ReversalError):
+    """Raised when the monthly quota is exhausted (HTTP 402)."""
+
+
+class ServerError(ReversalError):
+    """Raised for unexpected server-side errors (HTTP 5xx)."""

reversal_sdk-1.0.1/reversal_sdk/models.py

@@ -0,0 +1,58 @@
+"""Pydantic response models for the Reversal SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from pydantic import BaseModel, Field
+    _PYDANTIC = True
+except ImportError:  # pragma: no cover
+    _PYDANTIC = False
+
+
+if _PYDANTIC:
+    class JobInfo(BaseModel):
+        job_id: str
+        status: str  # "pending" | "running" | "done" | "failed"
+        result: dict[str, Any] | None = None
+        error: str | None = None
+        content_type: str | None = None
+        created_at: str | None = None
+        updated_at: str | None = None
+
+    class ReverseResult(BaseModel):
+        content_type: str
+        content: Any
+        metadata: dict[str, Any] = Field(default_factory=dict)
+
+    class FileUpload(BaseModel):
+        file_id: str
+        filename: str
+        size: int
+
+    class BatchResult(BaseModel):
+        results: list[dict[str, Any]]
+
+    class SSEEvent(BaseModel):
+        event: str          # "status" | "result" | "error" | "timeout"
+        data: dict[str, Any]
+
+    class UserInfo(BaseModel):
+        user_id: int
+        email: str
+        plan: str
+        usage: int
+        quota: int
+
+else:  # pragma: no cover — fallback when pydantic is not installed
+    class _Namespace:
+        def __init__(self, **kwargs: Any) -> None:
+            for k, v in kwargs.items():
+                setattr(self, k, v)
+
+        def __repr__(self) -> str:
+            attrs = ", ".join(f"{k}={v!r}" for k, v in self.__dict__.items())
+            return f"{self.__class__.__name__}({attrs})"
+
+    JobInfo = ReverseResult = FileUpload = BatchResult = SSEEvent = UserInfo = _Namespace  # type: ignore[misc,assignment]

reversal_sdk-1.0.1/tests/test_client.py

@@ -0,0 +1,225 @@
+"""Tests for the Python Reversal SDK client."""
+
+from __future__ import annotations
+
+import json
+import pytest
+
+try:
+    import responses as resp_mock
+    _RESPONSES_OK = True
+except ImportError:
+    _RESPONSES_OK = False
+
+from reversal_sdk import ReversalClient
+from reversal_sdk.exceptions import (
+    AuthError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ReversalError,
+    ServerError,
+)
+
+pytestmark = pytest.mark.skipif(not _RESPONSES_OK, reason="'responses' package required")
+
+BASE = "https://api.reversal.dev/v1"
+
+
+@pytest.fixture
+def client():
+    return ReversalClient(api_key="sk-rev-test", base_url=BASE)
+
+
+# ---------------------------------------------------------------------------
+# Helper
+# ---------------------------------------------------------------------------
+
+def _add(method, path, body, status=200):
+    resp_mock.add(method, f"{BASE}{path}", json=body, status=status)
+
+
+# ---------------------------------------------------------------------------
+# No API key
+# ---------------------------------------------------------------------------
+
+def test_no_api_key_raises():
+    import os
+    old = os.environ.pop("REVERSAL_API_KEY", None)
+    try:
+        with pytest.raises(AuthError):
+            ReversalClient(api_key="")
+    finally:
+        if old is not None:
+            os.environ["REVERSAL_API_KEY"] = old
+
+
+def test_env_api_key(monkeypatch):
+    monkeypatch.setenv("REVERSAL_API_KEY", "sk-rev-env")
+    c = ReversalClient()
+    assert c._api_key == "sk-rev-env"
+
+
+# ---------------------------------------------------------------------------
+# reverse
+# ---------------------------------------------------------------------------
+
+@resp_mock.activate
+def test_reverse_url(client):
+    _add(resp_mock.POST, "/reverse", {"content_type": "webpage", "content": "hello", "metadata": {}})
+    result = client.reverse("https://example.com")
+    assert result["content_type"] == "webpage"
+    assert resp_mock.calls[0].request.headers["Authorization"] == "Bearer sk-rev-test"
+
+
+@resp_mock.activate
+def test_reverse_async_mode(client):
+    _add(resp_mock.POST, "/reverse", {"job_id": "job-1", "status": "pending"})
+    result = client.reverse("https://example.com", async_mode=True)
+    assert result["job_id"] == "job-1"
+    sent = json.loads(resp_mock.calls[0].request.body)
+    assert sent["async_mode"] is True
+
+
+@resp_mock.activate
+def test_reverse_local_file_uploads_first(client, tmp_path):
+    f = tmp_path / "doc.pdf"
+    f.write_bytes(b"%PDF fake")
+    _add(resp_mock.POST, "/upload", {"file_id": "fid-42", "filename": "doc.pdf", "size": 9})
+    _add(resp_mock.POST, "/reverse", {"content_type": "pdf", "content": {}, "metadata": {}})
+    result = client.reverse(str(f))
+    assert result["content_type"] == "pdf"
+    sent = json.loads(resp_mock.calls[1].request.body)
+    assert sent["source"] == "file:fid-42"
+
+
+# ---------------------------------------------------------------------------
+# upload
+# ---------------------------------------------------------------------------
+
+@resp_mock.activate
+def test_upload(client, tmp_path):
+    f = tmp_path / "test.png"
+    f.write_bytes(b"\x89PNG")
+    _add(resp_mock.POST, "/upload", {"file_id": "fid-99", "filename": "test.png", "size": 4})
+    result = client.upload(f)
+    assert result["file_id"] == "fid-99"
+
+
+# ---------------------------------------------------------------------------
+# batch
+# ---------------------------------------------------------------------------
+
+@resp_mock.activate
+def test_batch(client):
+    _add(resp_mock.POST, "/batch", {"results": [{"content_type": "url"}, {"content_type": "url"}]})
+    result = client.batch(["https://a.com", "https://b.com"])
+    assert len(result["results"]) == 2
+
+
+# ---------------------------------------------------------------------------
+# get_job / wait_for_job
+# ---------------------------------------------------------------------------
+
+@resp_mock.activate
+def test_get_job(client):
+    _add(resp_mock.GET, "/jobs/job-1", {"job_id": "job-1", "status": "running"})
+    job = client.get_job("job-1")
+    assert job["status"] == "running"
+
+
+@resp_mock.activate
+def test_wait_for_job_done(client):
+    _add(resp_mock.GET, "/jobs/job-1", {"job_id": "job-1", "status": "done", "result": {"x": 1}})
+    job = client.wait_for_job("job-1", poll_interval=0)
+    assert job["result"] == {"x": 1}
+
+
+@resp_mock.activate
+def test_wait_for_job_failed(client):
+    _add(resp_mock.GET, "/jobs/job-1", {"job_id": "job-1", "status": "failed", "error": "boom"})
+    with pytest.raises(ReversalError, match="boom"):
+        client.wait_for_job("job-1", poll_interval=0)
+
+
+@resp_mock.activate
+def test_wait_for_job_timeout(client):
+    _add(resp_mock.GET, "/jobs/job-1", {"job_id": "job-1", "status": "pending"})
+    with pytest.raises(ReversalError, match="Timeout"):
+        client.wait_for_job("job-1", poll_interval=0, timeout=0)
+
+
+# ---------------------------------------------------------------------------
+# delete_file
+# ---------------------------------------------------------------------------
+
+@resp_mock.activate
+def test_delete_file(client):
+    _add(resp_mock.DELETE, "/files/fid-1", {"deleted": True})
+    result = client.delete_file("fid-1")
+    assert result["deleted"] is True
+
+
+# ---------------------------------------------------------------------------
+# me / detect
+# ---------------------------------------------------------------------------
+
+@resp_mock.activate
+def test_me(client):
+    _add(resp_mock.GET, "/me", {"user_id": 1, "email": "a@b.com", "plan": "pro", "usage": 10, "quota": 600})
+    info = client.me()
+    assert info["plan"] == "pro"
+
+
+@resp_mock.activate
+def test_detect(client):
+    _add(resp_mock.POST, "/detect", {"content_type": "pdf"})
+    r = client.detect("https://example.com/file.pdf")
+    assert r["content_type"] == "pdf"
+
+
+# ---------------------------------------------------------------------------
+# Error mapping
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("code,exc", [
+    (401, AuthError),
+    (403, AuthError),
+    (404, NotFoundError),
+    (402, QuotaError),
+    (429, RateLimitError),
+    (500, ServerError),
+    (400, ReversalError),
+])
+@resp_mock.activate
+def test_error_mapping(client, code, exc):
+    _add(resp_mock.GET, "/me", {"detail": "error"}, status=code)
+    with pytest.raises(exc):
+        client.me()
+
+
+# ---------------------------------------------------------------------------
+# SSE parser
+# ---------------------------------------------------------------------------
+
+def test_parse_sse_stream():
+    from reversal_sdk.client import _parse_sse_stream
+    lines = iter([
+        "event: status",
+        'data: {"status": "running"}',
+        "",
+        "event: result",
+        'data: {"status": "done", "result": {}}',
+        "",
+    ])
+    events = list(_parse_sse_stream(lines))
+    assert events[0] == {"event": "status", "data": {"status": "running"}}
+    assert events[1] == {"event": "result", "data": {"status": "done", "result": {}}}
+
+
+def test_parse_sse_stream_no_event():
+    from reversal_sdk.client import _parse_sse_stream
+    lines = iter(['data: {"x": 1}', ""])
+    events = list(_parse_sse_stream(lines))
+    assert events[0]["event"] == "message"
+    assert events[0]["data"] == {"x": 1}