coreclaw-client 1.0.0__tar.gz

coreclaw_client-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: coreclaw-client
+Version: 1.0.0
+Summary: CoreClaw Python SDK client.
+Author: CoreClaw maintainers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+
+# CoreClaw Python SDK
+
+CoreClaw Python SDK for running scraper scripts and reading run results.
+
+## Install
+
+```bash
+pip install coreclaw-client
+```
+
+## Run a Scraper
+
+```python
+from coreclaw import CoreClawClient
+
+client = CoreClawClient(api_key="YOUR_API_KEY")
+
+run = client.scraper("SCRAPER_SLUG").run(
+    input={
+        "parameters": {
+            "system": {
+                "proxy_region": "US",
+                "cpus": 0.125,
+                "memory": 512,
+                "execute_limit_time_seconds": 1800,
+                "max_total_charge": 0,
+                "max_total_traffic": 0,
+            },
+            "custom": {
+                "keyword": "python",
+            },
+        }
+    },
+)
+
+print(run["run_slug"])
+client.close()
+```
+
+To run a specific version:
+
+```python
+run = client.scraper("SCRAPER_SLUG").run(
+    input={...},
+    version="v1.0.1",
+)
+```
+
+If `version` is not provided, CoreClaw uses the latest available version.
+
+## Get Run Results
+
+```python
+from coreclaw import CoreClawClient
+
+client = CoreClawClient(api_key="YOUR_API_KEY")
+
+results = client.run("RUN_SLUG").list_results(limit=10, offset=0)
+
+print(results["count"])
+for item in results["list"]:
+    print(item)
+
+client.close()
+```
+
+## Async Usage
+
+Run a scraper:
+
+```python
+from coreclaw import CoreClawAsyncClient
+
+client = CoreClawAsyncClient(api_key="YOUR_API_KEY")
+run = await client.scraper("SCRAPER_SLUG").run(input={...})
+await client.close()
+```
+
+Get run results:
+
+```python
+from coreclaw import CoreClawAsyncClient
+
+client = CoreClawAsyncClient(api_key="YOUR_API_KEY")
+results = await client.run("RUN_SLUG").list_results(limit=10, offset=0)
+await client.close()
+```
+
+## More
+
+- Chinese README: [README.zh-CN.md](README.zh-CN.md)
+- Run scraper demo: [examples/run_scraper.py](examples/run_scraper.py)
+- Get results demo: [examples/get_results.py](examples/get_results.py)
+- Async run scraper demo: [examples/async_run_scraper.py](examples/async_run_scraper.py)
+- Async get results demo: [examples/async_get_results.py](examples/async_get_results.py)

coreclaw_client-1.0.0/README.md

@@ -0,0 +1,95 @@
+# CoreClaw Python SDK
+
+CoreClaw Python SDK for running scraper scripts and reading run results.
+
+## Install
+
+```bash
+pip install coreclaw-client
+```
+
+## Run a Scraper
+
+```python
+from coreclaw import CoreClawClient
+
+client = CoreClawClient(api_key="YOUR_API_KEY")
+
+run = client.scraper("SCRAPER_SLUG").run(
+    input={
+        "parameters": {
+            "system": {
+                "proxy_region": "US",
+                "cpus": 0.125,
+                "memory": 512,
+                "execute_limit_time_seconds": 1800,
+                "max_total_charge": 0,
+                "max_total_traffic": 0,
+            },
+            "custom": {
+                "keyword": "python",
+            },
+        }
+    },
+)
+
+print(run["run_slug"])
+client.close()
+```
+
+To run a specific version:
+
+```python
+run = client.scraper("SCRAPER_SLUG").run(
+    input={...},
+    version="v1.0.1",
+)
+```
+
+If `version` is not provided, CoreClaw uses the latest available version.
+
+## Get Run Results
+
+```python
+from coreclaw import CoreClawClient
+
+client = CoreClawClient(api_key="YOUR_API_KEY")
+
+results = client.run("RUN_SLUG").list_results(limit=10, offset=0)
+
+print(results["count"])
+for item in results["list"]:
+    print(item)
+
+client.close()
+```
+
+## Async Usage
+
+Run a scraper:
+
+```python
+from coreclaw import CoreClawAsyncClient
+
+client = CoreClawAsyncClient(api_key="YOUR_API_KEY")
+run = await client.scraper("SCRAPER_SLUG").run(input={...})
+await client.close()
+```
+
+Get run results:
+
+```python
+from coreclaw import CoreClawAsyncClient
+
+client = CoreClawAsyncClient(api_key="YOUR_API_KEY")
+results = await client.run("RUN_SLUG").list_results(limit=10, offset=0)
+await client.close()
+```
+
+## More
+
+- Chinese README: [README.zh-CN.md](README.zh-CN.md)
+- Run scraper demo: [examples/run_scraper.py](examples/run_scraper.py)
+- Get results demo: [examples/get_results.py](examples/get_results.py)
+- Async run scraper demo: [examples/async_run_scraper.py](examples/async_run_scraper.py)
+- Async get results demo: [examples/async_get_results.py](examples/async_get_results.py)

coreclaw_client-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coreclaw-client"
+version = "1.0.0"
+description = "CoreClaw Python SDK client."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "CoreClaw maintainers" }
+]
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.scripts]
+coreclaw = "coreclaw.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

coreclaw_client-1.0.0/setup.cfg

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

coreclaw_client-1.0.0/src/coreclaw/__init__.py

@@ -0,0 +1,16 @@
+"""CoreClaw Python SDK."""
+
+from .client import CoreClawAsyncClient, CoreClawClient
+from .exceptions import CoreClawAPIError, CoreClawError, CoreClawHTTPError, CoreClawResponseError
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "CoreClawAPIError",
+    "CoreClawAsyncClient",
+    "CoreClawClient",
+    "CoreClawError",
+    "CoreClawHTTPError",
+    "CoreClawResponseError",
+    "__version__",
+]

coreclaw_client-1.0.0/src/coreclaw/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(["--version"]))

coreclaw_client-1.0.0/src/coreclaw/cli.py

@@ -0,0 +1,26 @@
+import argparse
+from collections.abc import Sequence
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="coreclaw")
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="print the package version and exit",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print(f"coreclaw {__version__}")
+        return 0
+
+    parser.print_help()
+    return 0

coreclaw_client-1.0.0/src/coreclaw/client.py

@@ -0,0 +1,109 @@
+from typing import Any
+
+import httpx
+
+from .exceptions import CoreClawAPIError, CoreClawHTTPError, CoreClawResponseError
+from .resources import AsyncRunClient, AsyncScraperClient, RunClient, ScraperClient
+
+
+DEFAULT_BASE_URL = "https://openapi.cafescraper.com"
+
+
+class CoreClawClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=_normalize_base_url(base_url or DEFAULT_BASE_URL),
+            headers={"api-key": api_key},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def scraper(self, scraper_slug: str) -> ScraperClient:
+        return ScraperClient(self, scraper_slug)
+
+    def run(self, run_slug: str) -> RunClient:
+        return RunClient(self, run_slug)
+
+    def post(self, path: str, payload: dict[str, Any]) -> Any:
+        response = self._client.post(path, json=payload)
+        return _parse_response(response)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "CoreClawClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class CoreClawAsyncClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=_normalize_base_url(base_url or DEFAULT_BASE_URL),
+            headers={"api-key": api_key},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def scraper(self, scraper_slug: str) -> AsyncScraperClient:
+        return AsyncScraperClient(self, scraper_slug)
+
+    def run(self, run_slug: str) -> AsyncRunClient:
+        return AsyncRunClient(self, run_slug)
+
+    async def post(self, path: str, payload: dict[str, Any]) -> Any:
+        response = await self._client.post(path, json=payload)
+        return _parse_response(response)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "CoreClawAsyncClient":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/") + "/api/v1/"
+
+
+def _parse_response(response: httpx.Response) -> Any:
+    if response.status_code < 200 or response.status_code >= 300:
+        raise CoreClawHTTPError(response.status_code, response.text)
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise CoreClawResponseError("response body is not valid JSON") from exc
+
+    if not isinstance(payload, dict):
+        raise CoreClawResponseError("response body must be a JSON object")
+
+    if "code" not in payload or "message" not in payload:
+        raise CoreClawResponseError("response body is missing code or message")
+
+    code = payload["code"]
+    message = str(payload["message"])
+
+    if code != 0:
+        raise CoreClawAPIError(int(code), message, payload.get("data"))
+
+    return payload.get("data")

coreclaw_client-1.0.0/src/coreclaw/exceptions.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+
+class CoreClawError(Exception):
+    """Base class for all CoreClaw SDK errors."""
+
+
+class CoreClawHTTPError(CoreClawError):
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(f"CoreClaw HTTP error {status_code}: {message}")
+
+
+class CoreClawResponseError(CoreClawError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"CoreClaw response error: {message}")
+
+
+class CoreClawAPIError(CoreClawError):
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        self.code = code
+        self.message = message
+        self.data = data
+        super().__init__(f"CoreClaw API error {code}: {message}")

coreclaw_client-1.0.0/src/coreclaw/pagination.py

@@ -0,0 +1,9 @@
+def limit_offset_to_page(limit: int, offset: int) -> tuple[int, int]:
+    if limit < 1:
+        raise ValueError("limit must be greater than or equal to 1")
+    if offset < 0:
+        raise ValueError("offset must be greater than or equal to 0")
+    if offset % limit != 0:
+        raise ValueError("offset must be divisible by limit")
+
+    return offset // limit + 1, limit

coreclaw_client-1.0.0/src/coreclaw/resources.py

@@ -0,0 +1,118 @@
+from typing import Any
+
+from .pagination import limit_offset_to_page
+
+
+class ScraperClient:
+    def __init__(self, client: Any, scraper_slug: str) -> None:
+        self._client = client
+        self._scraper_slug = scraper_slug
+
+    def run(
+        self,
+        *,
+        input: dict[str, Any],
+        version: str | None = None,
+        callback_url: str | None = None,
+        wait_for_finish: bool = False,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> Any:
+        page_index, page_size = limit_offset_to_page(limit, offset)
+        payload = _build_scraper_run_payload(
+            self._scraper_slug,
+            input,
+            version,
+            callback_url,
+            wait_for_finish,
+            page_index,
+            page_size,
+        )
+        return self._client.post("scraper/run", payload)
+
+
+class AsyncScraperClient:
+    def __init__(self, client: Any, scraper_slug: str) -> None:
+        self._client = client
+        self._scraper_slug = scraper_slug
+
+    async def run(
+        self,
+        *,
+        input: dict[str, Any],
+        version: str | None = None,
+        callback_url: str | None = None,
+        wait_for_finish: bool = False,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> Any:
+        page_index, page_size = limit_offset_to_page(limit, offset)
+        payload = _build_scraper_run_payload(
+            self._scraper_slug,
+            input,
+            version,
+            callback_url,
+            wait_for_finish,
+            page_index,
+            page_size,
+        )
+        return await self._client.post("scraper/run", payload)
+
+
+class RunClient:
+    def __init__(self, client: Any, run_slug: str) -> None:
+        self._client = client
+        self._run_slug = run_slug
+
+    def list_results(self, *, limit: int = 10, offset: int = 0) -> Any:
+        page_index, page_size = limit_offset_to_page(limit, offset)
+        return self._client.post(
+            "run/result/list",
+            {
+                "run_slug": self._run_slug,
+                "page_index": page_index,
+                "page_size": page_size,
+            },
+        )
+
+
+class AsyncRunClient:
+    def __init__(self, client: Any, run_slug: str) -> None:
+        self._client = client
+        self._run_slug = run_slug
+
+    async def list_results(self, *, limit: int = 10, offset: int = 0) -> Any:
+        page_index, page_size = limit_offset_to_page(limit, offset)
+        return await self._client.post(
+            "run/result/list",
+            {
+                "run_slug": self._run_slug,
+                "page_index": page_index,
+                "page_size": page_size,
+            },
+        )
+
+
+def _build_scraper_run_payload(
+    scraper_slug: str,
+    input: dict[str, Any],
+    version: str | None,
+    callback_url: str | None,
+    wait_for_finish: bool,
+    page_index: int,
+    page_size: int,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "scraper_slug": scraper_slug,
+        "input": input,
+        "is_async": not wait_for_finish,
+        "page_index": page_index,
+        "page_size": page_size,
+    }
+
+    if version is not None:
+        payload["version"] = version
+    if callback_url is not None:
+        payload["callback_url"] = callback_url
+
+    return payload

coreclaw_client-1.0.0/src/coreclaw_client.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: coreclaw-client
+Version: 1.0.0
+Summary: CoreClaw Python SDK client.
+Author: CoreClaw maintainers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+
+# CoreClaw Python SDK
+
+CoreClaw Python SDK for running scraper scripts and reading run results.
+
+## Install
+
+```bash
+pip install coreclaw-client
+```
+
+## Run a Scraper
+
+```python
+from coreclaw import CoreClawClient
+
+client = CoreClawClient(api_key="YOUR_API_KEY")
+
+run = client.scraper("SCRAPER_SLUG").run(
+    input={
+        "parameters": {
+            "system": {
+                "proxy_region": "US",
+                "cpus": 0.125,
+                "memory": 512,
+                "execute_limit_time_seconds": 1800,
+                "max_total_charge": 0,
+                "max_total_traffic": 0,
+            },
+            "custom": {
+                "keyword": "python",
+            },
+        }
+    },
+)
+
+print(run["run_slug"])
+client.close()
+```
+
+To run a specific version:
+
+```python
+run = client.scraper("SCRAPER_SLUG").run(
+    input={...},
+    version="v1.0.1",
+)
+```
+
+If `version` is not provided, CoreClaw uses the latest available version.
+
+## Get Run Results
+
+```python
+from coreclaw import CoreClawClient
+
+client = CoreClawClient(api_key="YOUR_API_KEY")
+
+results = client.run("RUN_SLUG").list_results(limit=10, offset=0)
+
+print(results["count"])
+for item in results["list"]:
+    print(item)
+
+client.close()
+```
+
+## Async Usage
+
+Run a scraper:
+
+```python
+from coreclaw import CoreClawAsyncClient
+
+client = CoreClawAsyncClient(api_key="YOUR_API_KEY")
+run = await client.scraper("SCRAPER_SLUG").run(input={...})
+await client.close()
+```
+
+Get run results:
+
+```python
+from coreclaw import CoreClawAsyncClient
+
+client = CoreClawAsyncClient(api_key="YOUR_API_KEY")
+results = await client.run("RUN_SLUG").list_results(limit=10, offset=0)
+await client.close()
+```
+
+## More
+
+- Chinese README: [README.zh-CN.md](README.zh-CN.md)
+- Run scraper demo: [examples/run_scraper.py](examples/run_scraper.py)
+- Get results demo: [examples/get_results.py](examples/get_results.py)
+- Async run scraper demo: [examples/async_run_scraper.py](examples/async_run_scraper.py)
+- Async get results demo: [examples/async_get_results.py](examples/async_get_results.py)

coreclaw_client-1.0.0/src/coreclaw_client.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/coreclaw/__init__.py
+src/coreclaw/__main__.py
+src/coreclaw/cli.py
+src/coreclaw/client.py
+src/coreclaw/exceptions.py
+src/coreclaw/pagination.py
+src/coreclaw/resources.py
+src/coreclaw_client.egg-info/PKG-INFO
+src/coreclaw_client.egg-info/SOURCES.txt
+src/coreclaw_client.egg-info/dependency_links.txt
+src/coreclaw_client.egg-info/entry_points.txt
+src/coreclaw_client.egg-info/requires.txt
+src/coreclaw_client.egg-info/top_level.txt
+tests/test_client.py
+tests/test_packaging.py
+tests/test_version.py

coreclaw_client-1.0.0/src/coreclaw_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

coreclaw_client-1.0.0/src/coreclaw_client.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+coreclaw = coreclaw.cli:main

coreclaw_client-1.0.0/src/coreclaw_client.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24

coreclaw_client-1.0.0/src/coreclaw_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+coreclaw

coreclaw_client-1.0.0/tests/test_client.py

@@ -0,0 +1,268 @@
+import asyncio
+import json
+import sys
+import unittest
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+
+class RecordingTransport(httpx.MockTransport):
+    def __init__(self, payload):
+        self.requests = []
+        self.payload = payload
+        super().__init__(self._handler)
+
+    def _handler(self, request):
+        self.requests.append(request)
+        return httpx.Response(200, json=self.payload)
+
+
+class CoreClawClientTests(unittest.TestCase):
+    def test_sync_client_uses_official_base_url_by_default(self):
+        from coreclaw import CoreClawClient
+
+        transport = RecordingTransport(
+            {"code": 0, "message": "success", "data": {"run_slug": "RUN123"}}
+        )
+        client = CoreClawClient(api_key="key-123", transport=transport)
+
+        client.scraper("SCRAPER123").run(input={"parameters": {}})
+
+        request_url = transport.requests[0].url
+
+        self.assertEqual(request_url.scheme, "https")
+        self.assertEqual(request_url.host, "openapi.cafescraper.com")
+        self.assertEqual(request_url.path, "/api/v1/scraper/run")
+
+        client.close()
+
+    def test_sync_scraper_run_maps_request_fields(self):
+        from coreclaw import CoreClawClient
+
+        transport = RecordingTransport(
+            {"code": 0, "message": "success", "data": {"run_slug": "RUN123"}}
+        )
+        client = CoreClawClient(
+            api_key="key-123",
+            base_url="https://api.coreclaw.example",
+            transport=transport,
+        )
+
+        result = client.scraper("SCRAPER123").run(
+            input={"parameters": {"custom": {"keyword": "python"}}},
+            version="v1.2.3",
+            callback_url="https://example.com/callback",
+            wait_for_finish=True,
+            limit=25,
+            offset=50,
+        )
+
+        request = transport.requests[0]
+        body = json.loads(request.content)
+
+        self.assertEqual(result, {"run_slug": "RUN123"})
+        self.assertEqual(request.method, "POST")
+        self.assertEqual(urlparse(str(request.url)).path, "/api/v1/scraper/run")
+        self.assertEqual(request.headers["api-key"], "key-123")
+        self.assertEqual(body["scraper_slug"], "SCRAPER123")
+        self.assertEqual(body["input"], {"parameters": {"custom": {"keyword": "python"}}})
+        self.assertEqual(body["version"], "v1.2.3")
+        self.assertEqual(body["callback_url"], "https://example.com/callback")
+        self.assertFalse(body["is_async"])
+        self.assertEqual(body["page_index"], 3)
+        self.assertEqual(body["page_size"], 25)
+
+        client.close()
+
+    def test_sync_scraper_run_omits_version_when_not_provided(self):
+        from coreclaw import CoreClawClient
+
+        transport = RecordingTransport(
+            {"code": 0, "message": "success", "data": {"run_slug": "RUN123"}}
+        )
+        client = CoreClawClient(
+            api_key="key-123",
+            base_url="https://api.coreclaw.example",
+            transport=transport,
+        )
+
+        client.scraper("SCRAPER123").run(input={"parameters": {}})
+
+        body = json.loads(transport.requests[0].content)
+
+        self.assertNotIn("version", body)
+        self.assertTrue(body["is_async"])
+
+        client.close()
+
+    def test_sync_run_lists_results_with_limit_offset(self):
+        from coreclaw import CoreClawClient
+
+        payload = {
+            "code": 0,
+            "message": "success",
+            "data": {
+                "count": 2,
+                "headers": [{"label": "Title", "key": "title", "format": "text"}],
+                "list": [{"title": "A"}, {"title": "B"}],
+                "page_index": 2,
+                "page_size": 10,
+            },
+        }
+        transport = RecordingTransport(payload)
+        client = CoreClawClient(
+            api_key="key-123",
+            base_url="https://api.coreclaw.example/",
+            transport=transport,
+        )
+
+        result = client.run("RUN123").list_results(limit=10, offset=10)
+
+        request = transport.requests[0]
+        body = json.loads(request.content)
+
+        self.assertEqual(result, payload["data"])
+        self.assertEqual(urlparse(str(request.url)).path, "/api/v1/run/result/list")
+        self.assertEqual(body, {"run_slug": "RUN123", "page_index": 2, "page_size": 10})
+
+        client.close()
+
+    def test_limit_offset_requires_aligned_offset(self):
+        from coreclaw import CoreClawClient
+
+        client = CoreClawClient(
+            api_key="key-123",
+            base_url="https://api.coreclaw.example",
+            transport=RecordingTransport({"code": 0, "message": "success", "data": {}}),
+        )
+
+        with self.assertRaisesRegex(ValueError, "offset must be divisible by limit"):
+            client.run("RUN123").list_results(limit=10, offset=5)
+
+        client.close()
+
+    def test_api_error_is_raised_for_nonzero_code(self):
+        from coreclaw import CoreClawAPIError, CoreClawClient
+
+        transport = RecordingTransport(
+            {"code": 50003, "message": "The script version is not available", "data": None}
+        )
+        client = CoreClawClient(
+            api_key="key-123",
+            base_url="https://api.coreclaw.example",
+            transport=transport,
+        )
+
+        with self.assertRaises(CoreClawAPIError) as raised:
+            client.scraper("SCRAPER123").run(
+                input={"parameters": {}},
+                version="v9.9.9",
+            )
+
+        self.assertEqual(raised.exception.code, 50003)
+        self.assertEqual(str(raised.exception), "CoreClaw API error 50003: The script version is not available")
+
+        client.close()
+
+
+class CoreClawAsyncClientTests(unittest.TestCase):
+    def test_async_client_uses_official_base_url_by_default(self):
+        from coreclaw import CoreClawAsyncClient
+
+        async def scenario():
+            transport = RecordingTransport(
+                {"code": 0, "message": "success", "data": {"run_slug": "RUN123"}}
+            )
+            client = CoreClawAsyncClient(api_key="key-123", transport=transport)
+
+            await client.scraper("SCRAPER123").run(input={"parameters": {}})
+
+            request_url = transport.requests[0].url
+
+            self.assertEqual(request_url.scheme, "https")
+            self.assertEqual(request_url.host, "openapi.cafescraper.com")
+            self.assertEqual(request_url.path, "/api/v1/scraper/run")
+
+            await client.close()
+
+        asyncio.run(scenario())
+
+    def test_async_scraper_run_maps_request_fields(self):
+        from coreclaw import CoreClawAsyncClient
+
+        async def scenario():
+            transport = RecordingTransport(
+                {"code": 0, "message": "success", "data": {"run_slug": "RUN123"}}
+            )
+            client = CoreClawAsyncClient(
+                api_key="key-123",
+                base_url="https://api.coreclaw.example",
+                transport=transport,
+            )
+
+            result = await client.scraper("SCRAPER123").run(
+                input={"parameters": {"custom": {"keyword": "python"}}},
+                limit=20,
+                offset=40,
+            )
+
+            body = json.loads(transport.requests[0].content)
+
+            self.assertEqual(result, {"run_slug": "RUN123"})
+            self.assertEqual(urlparse(str(transport.requests[0].url)).path, "/api/v1/scraper/run")
+            self.assertEqual(transport.requests[0].headers["api-key"], "key-123")
+            self.assertEqual(body["scraper_slug"], "SCRAPER123")
+            self.assertTrue(body["is_async"])
+            self.assertEqual(body["page_index"], 3)
+            self.assertEqual(body["page_size"], 20)
+
+            await client.close()
+
+        asyncio.run(scenario())
+
+    def test_async_run_lists_results(self):
+        from coreclaw import CoreClawAsyncClient
+
+        async def scenario():
+            payload = {
+                "code": 0,
+                "message": "success",
+                "data": {
+                    "count": 1,
+                    "headers": [],
+                    "list": [{"title": "A"}],
+                    "page_index": 1,
+                    "page_size": 50,
+                },
+            }
+            transport = RecordingTransport(payload)
+            client = CoreClawAsyncClient(
+                api_key="key-123",
+                base_url="https://api.coreclaw.example",
+                transport=transport,
+            )
+
+            result = await client.run("RUN123").list_results(limit=50, offset=0)
+
+            body = json.loads(transport.requests[0].content)
+
+            self.assertEqual(result, payload["data"])
+            self.assertEqual(urlparse(str(transport.requests[0].url)).path, "/api/v1/run/result/list")
+            self.assertEqual(body, {"run_slug": "RUN123", "page_index": 1, "page_size": 50})
+
+            await client.close()
+
+        asyncio.run(scenario())
+
+
+if __name__ == "__main__":
+    unittest.main()

coreclaw_client-1.0.0/tests/test_packaging.py

@@ -0,0 +1,27 @@
+import sys
+import tomllib
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+
+class PackagingTests(unittest.TestCase):
+    def test_distribution_name_is_coreclaw_client(self):
+        pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+
+        self.assertEqual(pyproject["project"]["name"], "coreclaw-client")
+
+    def test_import_package_remains_coreclaw(self):
+        import coreclaw
+
+        self.assertEqual(coreclaw.__name__, "coreclaw")
+
+
+if __name__ == "__main__":
+    unittest.main()

coreclaw_client-1.0.0/tests/test_version.py

@@ -0,0 +1,48 @@
+import io
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+
+class VersionTests(unittest.TestCase):
+    def test_package_exposes_version(self):
+        import coreclaw
+
+        self.assertEqual(coreclaw.__version__, "1.0.0")
+
+    def test_cli_prints_version(self):
+        from coreclaw.cli import main
+
+        output = io.StringIO()
+
+        with redirect_stdout(output):
+            exit_code = main(["--version"])
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(output.getvalue().strip(), "coreclaw 1.0.0")
+
+    def test_module_prints_version(self):
+        result = subprocess.run(
+            [sys.executable, "-m", "coreclaw"],
+            check=False,
+            capture_output=True,
+            cwd=ROOT,
+            env={"PYTHONPATH": str(SRC)},
+            text=True,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(result.stdout.strip(), "coreclaw 1.0.0")
+
+
+if __name__ == "__main__":
+    unittest.main()