spacerouter 0.1.0__tar.gz

spacerouter-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.venv/
+venv/
+
+# JavaScript
+node_modules/
+dist/
+*.tsbuildinfo
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

spacerouter-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: spacerouter
+Version: 0.1.0
+Summary: Python SDK for the Space Router residential proxy network
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Provides-Extra: socks
+Requires-Dist: httpx[socks]<1.0,>=0.27; extra == 'socks'
+Description-Content-Type: text/markdown
+
+# SpaceRouter Python SDK
+
+Python SDK for routing HTTP requests through the [Space Router](../../README.md) residential proxy network.
+
+## Installation
+
+```bash
+pip install spacerouter
+
+# With SOCKS5 support
+pip install spacerouter[socks]
+```
+
+## Quick Start
+
+```python
+from spacerouter import SpaceRouter
+
+with SpaceRouter("sr_live_YOUR_API_KEY", gateway_url="http://gateway:8080") as client:
+    response = client.get("https://httpbin.org/ip")
+    print(response.json())       # {"origin": "residential-ip"}
+    print(response.node_id)      # node that handled the request
+    print(response.request_id)   # unique request ID for tracing
+```
+
+## Async Usage
+
+```python
+from spacerouter import AsyncSpaceRouter
+
+async with AsyncSpaceRouter("sr_live_YOUR_API_KEY") as client:
+    response = await client.get("https://httpbin.org/ip")
+    print(response.json())
+```
+
+## IP Targeting
+
+Route requests through specific IP types or geographic regions:
+
+```python
+# Target residential IPs in the US
+client = SpaceRouter("sr_live_xxx", ip_type="residential", region="US")
+
+# Target mobile IPs in South Korea
+client = SpaceRouter("sr_live_xxx", ip_type="mobile", region="Seoul, KR")
+
+# Change routing on the fly
+mobile_client = client.with_routing(ip_type="mobile", region="JP")
+```
+
+Available IP types: `residential`, `mobile`, `datacenter`, `business`
+
+## SOCKS5 Proxy
+
+```python
+client = SpaceRouter(
+    "sr_live_xxx",
+    protocol="socks5",
+    gateway_url="socks5://gateway:1080",
+)
+response = client.get("https://httpbin.org/ip")
+```
+
+Requires the `socks` extra: `pip install spacerouter[socks]`
+
+## API Key Management
+
+```python
+from spacerouter import SpaceRouterAdmin
+
+with SpaceRouterAdmin("http://localhost:8000") as admin:
+    # Create a key (raw value only available here)
+    key = admin.create_api_key("my-agent", rate_limit_rpm=120)
+    print(key.api_key)  # sr_live_...
+
+    # List keys
+    for k in admin.list_api_keys():
+        print(k.name, k.key_prefix, k.is_active)
+
+    # Revoke a key
+    admin.revoke_api_key(key.id)
+```
+
+Async variant: `AsyncSpaceRouterAdmin`
+
+## Error Handling
+
+```python
+from spacerouter import SpaceRouter
+from spacerouter.exceptions import (
+    AuthenticationError,   # 407 - invalid API key
+    RateLimitError,        # 429 - rate limit exceeded
+    NoNodesAvailableError, # 503 - no residential nodes online
+    UpstreamError,         # 502 - target unreachable via node
+)
+
+with SpaceRouter("sr_live_xxx") as client:
+    try:
+        response = client.get("https://example.com")
+    except RateLimitError as e:
+        print(f"Rate limited, retry after {e.retry_after}s")
+    except NoNodesAvailableError:
+        print("No nodes available, try again later")
+    except UpstreamError as e:
+        print(f"Node {e.node_id} could not reach target")
+    except AuthenticationError:
+        print("Check your API key")
+```
+
+Note: HTTP errors from the target website (e.g. 404, 500) are **not** raised as exceptions. Only proxy-layer errors produce exceptions.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | (required) | API key (`sr_live_...`) |
+| `gateway_url` | `http://localhost:8080` | Proxy gateway URL |
+| `protocol` | `http` | `http` or `socks5` |
+| `ip_type` | `None` | IP type filter |
+| `region` | `None` | Region filter (substring match) |
+| `timeout` | `30.0` | Request timeout in seconds |

spacerouter-0.1.0/README.md

@@ -0,0 +1,121 @@
+# SpaceRouter Python SDK
+
+Python SDK for routing HTTP requests through the [Space Router](../../README.md) residential proxy network.
+
+## Installation
+
+```bash
+pip install spacerouter
+
+# With SOCKS5 support
+pip install spacerouter[socks]
+```
+
+## Quick Start
+
+```python
+from spacerouter import SpaceRouter
+
+with SpaceRouter("sr_live_YOUR_API_KEY", gateway_url="http://gateway:8080") as client:
+    response = client.get("https://httpbin.org/ip")
+    print(response.json())       # {"origin": "residential-ip"}
+    print(response.node_id)      # node that handled the request
+    print(response.request_id)   # unique request ID for tracing
+```
+
+## Async Usage
+
+```python
+from spacerouter import AsyncSpaceRouter
+
+async with AsyncSpaceRouter("sr_live_YOUR_API_KEY") as client:
+    response = await client.get("https://httpbin.org/ip")
+    print(response.json())
+```
+
+## IP Targeting
+
+Route requests through specific IP types or geographic regions:
+
+```python
+# Target residential IPs in the US
+client = SpaceRouter("sr_live_xxx", ip_type="residential", region="US")
+
+# Target mobile IPs in South Korea
+client = SpaceRouter("sr_live_xxx", ip_type="mobile", region="Seoul, KR")
+
+# Change routing on the fly
+mobile_client = client.with_routing(ip_type="mobile", region="JP")
+```
+
+Available IP types: `residential`, `mobile`, `datacenter`, `business`
+
+## SOCKS5 Proxy
+
+```python
+client = SpaceRouter(
+    "sr_live_xxx",
+    protocol="socks5",
+    gateway_url="socks5://gateway:1080",
+)
+response = client.get("https://httpbin.org/ip")
+```
+
+Requires the `socks` extra: `pip install spacerouter[socks]`
+
+## API Key Management
+
+```python
+from spacerouter import SpaceRouterAdmin
+
+with SpaceRouterAdmin("http://localhost:8000") as admin:
+    # Create a key (raw value only available here)
+    key = admin.create_api_key("my-agent", rate_limit_rpm=120)
+    print(key.api_key)  # sr_live_...
+
+    # List keys
+    for k in admin.list_api_keys():
+        print(k.name, k.key_prefix, k.is_active)
+
+    # Revoke a key
+    admin.revoke_api_key(key.id)
+```
+
+Async variant: `AsyncSpaceRouterAdmin`
+
+## Error Handling
+
+```python
+from spacerouter import SpaceRouter
+from spacerouter.exceptions import (
+    AuthenticationError,   # 407 - invalid API key
+    RateLimitError,        # 429 - rate limit exceeded
+    NoNodesAvailableError, # 503 - no residential nodes online
+    UpstreamError,         # 502 - target unreachable via node
+)
+
+with SpaceRouter("sr_live_xxx") as client:
+    try:
+        response = client.get("https://example.com")
+    except RateLimitError as e:
+        print(f"Rate limited, retry after {e.retry_after}s")
+    except NoNodesAvailableError:
+        print("No nodes available, try again later")
+    except UpstreamError as e:
+        print(f"Node {e.node_id} could not reach target")
+    except AuthenticationError:
+        print("Check your API key")
+```
+
+Note: HTTP errors from the target website (e.g. 404, 500) are **not** raised as exceptions. Only proxy-layer errors produce exceptions.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | (required) | API key (`sr_live_...`) |
+| `gateway_url` | `http://localhost:8080` | Proxy gateway URL |
+| `protocol` | `http` | `http` or `socks5` |
+| `ip_type` | `None` | IP type filter |
+| `region` | `None` | Region filter (substring match) |
+| `timeout` | `30.0` | Request timeout in seconds |

spacerouter-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spacerouter"
+version = "0.1.0"
+description = "Python SDK for the Space Router residential proxy network"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+socks = ["httpx[socks]>=0.27,<1.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25",
+    "respx>=0.22",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spacerouter"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

spacerouter-0.1.0/src/spacerouter/__init__.py

@@ -0,0 +1,28 @@
+"""SpaceRouter Python SDK — route HTTP requests through residential IPs."""
+
+from spacerouter.admin import AsyncSpaceRouterAdmin, SpaceRouterAdmin
+from spacerouter.client import AsyncSpaceRouter, SpaceRouter, fetch_ca_cert
+from spacerouter.exceptions import (
+    AuthenticationError,
+    NoNodesAvailableError,
+    RateLimitError,
+    SpaceRouterError,
+    UpstreamError,
+)
+from spacerouter.models import ApiKey, ApiKeyInfo, ProxyResponse
+
+__all__ = [
+    "SpaceRouter",
+    "AsyncSpaceRouter",
+    "SpaceRouterAdmin",
+    "AsyncSpaceRouterAdmin",
+    "fetch_ca_cert",
+    "ApiKey",
+    "ApiKeyInfo",
+    "ProxyResponse",
+    "SpaceRouterError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NoNodesAvailableError",
+    "UpstreamError",
+]

spacerouter-0.1.0/src/spacerouter/admin.py

@@ -0,0 +1,144 @@
+"""Admin clients for the Space Router Coordination API.
+
+Provides :class:`SpaceRouterAdmin` (sync) and :class:`AsyncSpaceRouterAdmin`
+(async) for managing API keys.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from spacerouter.models import ApiKey, ApiKeyInfo
+
+_DEFAULT_COORDINATION_URL = "https://coordination.spacerouter.org"
+
+
+class SpaceRouterAdmin:
+    """Synchronous admin client for the Coordination API.
+
+    Example::
+
+        with SpaceRouterAdmin() as admin:
+            key = admin.create_api_key("my-agent")
+            print(key.api_key)  # sr_live_...
+    """
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_COORDINATION_URL,
+        *,
+        timeout: float = 10.0,
+        **httpx_kwargs: Any,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url, timeout=timeout, **httpx_kwargs
+        )
+
+    def create_api_key(self, name: str, *, rate_limit_rpm: int = 60) -> ApiKey:
+        """Create a new API key.
+
+        The raw key value is **only** available in the returned object.
+        """
+        response = self._client.post(
+            "/api-keys",
+            json={"name": name, "rate_limit_rpm": rate_limit_rpm},
+        )
+        response.raise_for_status()
+        return ApiKey.model_validate(response.json())
+
+    def list_api_keys(self) -> list[ApiKeyInfo]:
+        """List all API keys (raw key values are never returned)."""
+        response = self._client.get("/api-keys")
+        response.raise_for_status()
+        return [ApiKeyInfo.model_validate(item) for item in response.json()]
+
+    def revoke_api_key(self, key_id: str) -> None:
+        """Revoke an API key (soft-delete)."""
+        response = self._client.delete(f"/api-keys/{key_id}")
+        response.raise_for_status()
+
+    def fetch_ca_cert(self) -> str | None:
+        """Fetch the proxy network CA certificate.
+
+        Returns the PEM-encoded certificate, or ``None`` when the proxy
+        network does not require a custom CA (HTTP 503).
+        """
+        response = self._client.get("/ca-cert")
+        if response.status_code == 503:
+            return None
+        response.raise_for_status()
+        return response.text
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> SpaceRouterAdmin:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncSpaceRouterAdmin:
+    """Asynchronous admin client for the Coordination API.
+
+    Example::
+
+        async with AsyncSpaceRouterAdmin() as admin:
+            key = await admin.create_api_key("my-agent")
+            print(key.api_key)
+    """
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_COORDINATION_URL,
+        *,
+        timeout: float = 10.0,
+        **httpx_kwargs: Any,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url, timeout=timeout, **httpx_kwargs
+        )
+
+    async def create_api_key(self, name: str, *, rate_limit_rpm: int = 60) -> ApiKey:
+        """Create a new API key."""
+        response = await self._client.post(
+            "/api-keys",
+            json={"name": name, "rate_limit_rpm": rate_limit_rpm},
+        )
+        response.raise_for_status()
+        return ApiKey.model_validate(response.json())
+
+    async def list_api_keys(self) -> list[ApiKeyInfo]:
+        """List all API keys."""
+        response = await self._client.get("/api-keys")
+        response.raise_for_status()
+        return [ApiKeyInfo.model_validate(item) for item in response.json()]
+
+    async def revoke_api_key(self, key_id: str) -> None:
+        """Revoke an API key (soft-delete)."""
+        response = await self._client.delete(f"/api-keys/{key_id}")
+        response.raise_for_status()
+
+    async def fetch_ca_cert(self) -> str | None:
+        """Fetch the proxy network CA certificate.
+
+        Returns the PEM-encoded certificate, or ``None`` when the proxy
+        network does not require a custom CA (HTTP 503).
+        """
+        response = await self._client.get("/ca-cert")
+        if response.status_code == 503:
+            return None
+        response.raise_for_status()
+        return response.text
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncSpaceRouterAdmin:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()