spacerouter-cli 0.1.0__tar.gz

spacerouter_cli-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_cli-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: spacerouter-cli
+Version: 0.1.0
+Summary: CLI for the Space Router residential proxy network — designed for AI agents
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: rich<14.0,>=13.0
+Requires-Dist: spacerouter>=0.1.0
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'

spacerouter_cli-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spacerouter-cli"
+version = "0.1.0"
+description = "CLI for the Space Router residential proxy network — designed for AI agents"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "typer>=0.12,<1.0",
+    "httpx>=0.27,<1.0",
+    "spacerouter>=0.1.0",
+    "rich>=13.0,<14.0",
+]
+
+[project.scripts]
+spacerouter = "spacerouter_cli.main:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.22",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spacerouter_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spacerouter_cli-0.1.0/src/spacerouter_cli/__init__.py

@@ -0,0 +1,3 @@
+"""SpaceRouter CLI — AI-agent-friendly tool for residential proxy requests."""
+
+__version__ = "0.1.0"

spacerouter_cli-0.1.0/src/spacerouter_cli/commands/api_key.py

@@ -0,0 +1,63 @@
+"""``spacerouter api-key`` — manage API keys."""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+import typer
+
+from spacerouter import SpaceRouterAdmin
+
+from spacerouter_cli.config import resolve_config
+from spacerouter_cli.output import cli_error_handler, print_json
+
+app = typer.Typer(no_args_is_help=True)
+
+CoordinationUrlOpt = Annotated[
+    Optional[str],
+    typer.Option("--coordination-url", help="Coordination API URL."),
+]
+
+
+@app.command()
+@cli_error_handler
+def create(
+    name: Annotated[str, typer.Option("--name", help="Human-readable key name.")],
+    rate_limit: Annotated[int, typer.Option("--rate-limit", help="Requests per minute.")] = 60,
+    coordination_url: CoordinationUrlOpt = None,
+) -> None:
+    """Create a new API key."""
+    cfg = resolve_config(coordination_api_url=coordination_url)
+    with SpaceRouterAdmin(cfg.coordination_api_url) as admin:
+        key = admin.create_api_key(name, rate_limit_rpm=rate_limit)
+    print_json({
+        "id": key.id,
+        "name": key.name,
+        "api_key": key.api_key,
+        "rate_limit_rpm": key.rate_limit_rpm,
+    })
+
+
+@app.command("list")
+@cli_error_handler
+def list_keys(
+    coordination_url: CoordinationUrlOpt = None,
+) -> None:
+    """List all API keys."""
+    cfg = resolve_config(coordination_api_url=coordination_url)
+    with SpaceRouterAdmin(cfg.coordination_api_url) as admin:
+        keys = admin.list_api_keys()
+    print_json([k.model_dump() for k in keys])
+
+
+@app.command()
+@cli_error_handler
+def revoke(
+    key_id: Annotated[str, typer.Argument(help="ID of the API key to revoke.")],
+    coordination_url: CoordinationUrlOpt = None,
+) -> None:
+    """Revoke (soft-delete) an API key."""
+    cfg = resolve_config(coordination_api_url=coordination_url)
+    with SpaceRouterAdmin(cfg.coordination_api_url) as admin:
+        admin.revoke_api_key(key_id)
+    print_json({"ok": True, "revoked_key_id": key_id})

spacerouter_cli-0.1.0/src/spacerouter_cli/commands/config_cmd.py

@@ -0,0 +1,52 @@
+"""``spacerouter config`` — configuration management."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from spacerouter_cli.config import (
+    ALLOWED_CONFIG_KEYS,
+    CONFIG_FILE,
+    mask_key,
+    resolve_config,
+    save_config,
+)
+from spacerouter_cli.output import print_error, print_json
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def show() -> None:
+    """Display the resolved configuration (API key is masked)."""
+    cfg = resolve_config()
+    print_json({
+        "api_key": mask_key(cfg.api_key),
+        "gateway_url": cfg.gateway_url,
+        "coordination_api_url": cfg.coordination_api_url,
+        "gateway_management_url": cfg.gateway_management_url,
+        "timeout": cfg.timeout,
+        "config_file": str(CONFIG_FILE),
+        "config_file_exists": CONFIG_FILE.exists(),
+    })
+
+
+@app.command("set")
+def set_value(
+    key: Annotated[str, typer.Argument(help=f"Config key. Allowed: {', '.join(sorted(ALLOWED_CONFIG_KEYS))}.")],
+    value: Annotated[str, typer.Argument(help="Value to set.")],
+) -> None:
+    """Set a configuration value in ~/.spacerouter/config.json."""
+    if key not in ALLOWED_CONFIG_KEYS:
+        print_error(
+            "invalid_config_key",
+            f"Unknown key: {key}",
+            allowed_keys=sorted(ALLOWED_CONFIG_KEYS),
+        )
+        raise typer.Exit(code=1)
+
+    save_config({key: value})
+    display_value = mask_key(value) if "key" in key else value
+    print_json({"ok": True, "key": key, "value": display_value})

spacerouter_cli-0.1.0/src/spacerouter_cli/commands/node.py

@@ -0,0 +1,30 @@
+"""``spacerouter node`` — view node information."""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+import httpx
+import typer
+
+from spacerouter_cli.config import resolve_config
+from spacerouter_cli.output import cli_error_handler, print_json
+
+app = typer.Typer(no_args_is_help=True)
+
+CoordinationUrlOpt = Annotated[
+    Optional[str],
+    typer.Option("--coordination-url", help="Coordination API URL."),
+]
+
+
+@app.command("list")
+@cli_error_handler
+def list_nodes(
+    coordination_url: CoordinationUrlOpt = None,
+) -> None:
+    """List all registered nodes."""
+    cfg = resolve_config(coordination_api_url=coordination_url)
+    response = httpx.get(f"{cfg.coordination_api_url}/nodes", timeout=10.0)
+    response.raise_for_status()
+    print_json(response.json())

spacerouter_cli-0.1.0/src/spacerouter_cli/commands/request.py

@@ -0,0 +1,220 @@
+"""``spacerouter request`` — make proxied HTTP requests."""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Annotated, Optional
+
+import typer
+
+from spacerouter import SpaceRouter
+
+from spacerouter_cli.config import resolve_config
+from spacerouter_cli.output import cli_error_handler, print_error, print_json
+
+app = typer.Typer(no_args_is_help=True)
+
+# -- shared option types -----------------------------------------------------
+
+ApiKeyOpt = Annotated[Optional[str], typer.Option("--api-key", help="API key for proxy auth.")]
+GatewayOpt = Annotated[Optional[str], typer.Option("--gateway-url", help="Proxy gateway URL.")]
+HeaderOpt = Annotated[Optional[list[str]], typer.Option("--header", "-H", help="Custom header (Name: Value). Repeatable.")]
+IpTypeOpt = Annotated[Optional[str], typer.Option("--ip-type", help="IP type filter: residential, mobile, datacenter, business.")]
+RegionOpt = Annotated[Optional[str], typer.Option("--region", help="Region filter substring.")]
+TimeoutOpt = Annotated[Optional[float], typer.Option("--timeout", help="Request timeout in seconds.")]
+OutputOpt = Annotated[str, typer.Option("--output", help="Output mode: json (structured) or raw (body only).")]
+FollowOpt = Annotated[bool, typer.Option("--follow-redirects", help="Follow HTTP redirects.")]
+DataOpt = Annotated[Optional[str], typer.Option("--data", "-d", help="JSON request body.")]
+
+
+def _parse_headers(raw: list[str] | None) -> dict[str, str]:
+    """Parse ``["Name: Value", ...]`` into a dict."""
+    if not raw:
+        return {}
+    headers: dict[str, str] = {}
+    for item in raw:
+        name, _, value = item.partition(":")
+        headers[name.strip()] = value.strip()
+    return headers
+
+
+def _try_parse_json(text: str):
+    """Attempt to parse *text* as JSON; return raw string on failure."""
+    try:
+        return _json.loads(text)
+    except (ValueError, TypeError):
+        return text
+
+
+def _do_request(
+    method: str,
+    url: str,
+    *,
+    api_key: str | None,
+    gateway_url: str | None,
+    header: list[str] | None,
+    ip_type: str | None,
+    region: str | None,
+    timeout: float | None,
+    output: str,
+    follow_redirects: bool,
+    data: str | None = None,
+) -> None:
+    cfg = resolve_config(api_key=api_key, gateway_url=gateway_url, timeout=timeout)
+
+    if not cfg.api_key:
+        print_error("configuration_error", "API key is required. Set SR_API_KEY or pass --api-key.")
+        raise typer.Exit(code=1)
+
+    headers = _parse_headers(header)
+    kwargs: dict = {"headers": headers}
+    if data is not None:
+        try:
+            kwargs["json"] = _json.loads(data)
+        except (ValueError, TypeError):
+            print_error("configuration_error", "Invalid JSON in --data flag.")
+            raise typer.Exit(code=1)
+
+    with SpaceRouter(
+        cfg.api_key,
+        gateway_url=cfg.gateway_url,
+        ip_type=ip_type,
+        region=region,
+        timeout=cfg.timeout,
+        coordination_url=cfg.coordination_api_url,
+        follow_redirects=follow_redirects,
+    ) as client:
+        resp = client.request(method, url, **kwargs)
+
+    if output == "raw":
+        typer.echo(resp.text)
+    else:
+        print_json({
+            "status_code": resp.status_code,
+            "headers": dict(resp.headers),
+            "body": _try_parse_json(resp.text),
+            "spacerouter": {
+                "node_id": resp.node_id,
+                "request_id": resp.request_id,
+            },
+        })
+
+
+# -- subcommands --------------------------------------------------------------
+
+
+@app.command()
+@cli_error_handler
+def get(
+    url: str,
+    api_key: ApiKeyOpt = None,
+    gateway_url: GatewayOpt = None,
+    header: HeaderOpt = None,
+    ip_type: IpTypeOpt = None,
+    region: RegionOpt = None,
+    timeout: TimeoutOpt = None,
+    output: OutputOpt = "json",
+    follow_redirects: FollowOpt = False,
+) -> None:
+    """Send a GET request through the residential proxy."""
+    _do_request("GET", url, api_key=api_key, gateway_url=gateway_url, header=header,
+                ip_type=ip_type, region=region, timeout=timeout, output=output,
+                follow_redirects=follow_redirects)
+
+
+@app.command()
+@cli_error_handler
+def post(
+    url: str,
+    api_key: ApiKeyOpt = None,
+    gateway_url: GatewayOpt = None,
+    header: HeaderOpt = None,
+    data: DataOpt = None,
+    ip_type: IpTypeOpt = None,
+    region: RegionOpt = None,
+    timeout: TimeoutOpt = None,
+    output: OutputOpt = "json",
+    follow_redirects: FollowOpt = False,
+) -> None:
+    """Send a POST request through the residential proxy."""
+    _do_request("POST", url, api_key=api_key, gateway_url=gateway_url, header=header,
+                ip_type=ip_type, region=region, timeout=timeout, output=output,
+                follow_redirects=follow_redirects, data=data)
+
+
+@app.command()
+@cli_error_handler
+def put(
+    url: str,
+    api_key: ApiKeyOpt = None,
+    gateway_url: GatewayOpt = None,
+    header: HeaderOpt = None,
+    data: DataOpt = None,
+    ip_type: IpTypeOpt = None,
+    region: RegionOpt = None,
+    timeout: TimeoutOpt = None,
+    output: OutputOpt = "json",
+    follow_redirects: FollowOpt = False,
+) -> None:
+    """Send a PUT request through the residential proxy."""
+    _do_request("PUT", url, api_key=api_key, gateway_url=gateway_url, header=header,
+                ip_type=ip_type, region=region, timeout=timeout, output=output,
+                follow_redirects=follow_redirects, data=data)
+
+
+@app.command()
+@cli_error_handler
+def patch(
+    url: str,
+    api_key: ApiKeyOpt = None,
+    gateway_url: GatewayOpt = None,
+    header: HeaderOpt = None,
+    data: DataOpt = None,
+    ip_type: IpTypeOpt = None,
+    region: RegionOpt = None,
+    timeout: TimeoutOpt = None,
+    output: OutputOpt = "json",
+    follow_redirects: FollowOpt = False,
+) -> None:
+    """Send a PATCH request through the residential proxy."""
+    _do_request("PATCH", url, api_key=api_key, gateway_url=gateway_url, header=header,
+                ip_type=ip_type, region=region, timeout=timeout, output=output,
+                follow_redirects=follow_redirects, data=data)
+
+
+@app.command()
+@cli_error_handler
+def delete(
+    url: str,
+    api_key: ApiKeyOpt = None,
+    gateway_url: GatewayOpt = None,
+    header: HeaderOpt = None,
+    ip_type: IpTypeOpt = None,
+    region: RegionOpt = None,
+    timeout: TimeoutOpt = None,
+    output: OutputOpt = "json",
+    follow_redirects: FollowOpt = False,
+) -> None:
+    """Send a DELETE request through the residential proxy."""
+    _do_request("DELETE", url, api_key=api_key, gateway_url=gateway_url, header=header,
+                ip_type=ip_type, region=region, timeout=timeout, output=output,
+                follow_redirects=follow_redirects)
+
+
+@app.command()
+@cli_error_handler
+def head(
+    url: str,
+    api_key: ApiKeyOpt = None,
+    gateway_url: GatewayOpt = None,
+    header: HeaderOpt = None,
+    ip_type: IpTypeOpt = None,
+    region: RegionOpt = None,
+    timeout: TimeoutOpt = None,
+    output: OutputOpt = "json",
+    follow_redirects: FollowOpt = False,
+) -> None:
+    """Send a HEAD request through the residential proxy."""
+    _do_request("HEAD", url, api_key=api_key, gateway_url=gateway_url, header=header,
+                ip_type=ip_type, region=region, timeout=timeout, output=output,
+                follow_redirects=follow_redirects)

spacerouter_cli-0.1.0/src/spacerouter_cli/commands/status.py

@@ -0,0 +1,71 @@
+"""``spacerouter status`` — check service health."""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+import httpx
+import typer
+
+from spacerouter_cli.config import resolve_config
+from spacerouter_cli.output import cli_error_handler, print_json
+
+CoordinationUrlOpt = Annotated[
+    Optional[str],
+    typer.Option("--coordination-url", help="Coordination API URL."),
+]
+GatewayMgmtOpt = Annotated[
+    Optional[str],
+    typer.Option("--gateway-management-url", help="Gateway management API URL."),
+]
+
+
+@cli_error_handler
+def status(
+    coordination_url: CoordinationUrlOpt = None,
+    gateway_management_url: GatewayMgmtOpt = None,
+) -> None:
+    """Check Coordination API and Proxy Gateway health."""
+    cfg = resolve_config(
+        coordination_api_url=coordination_url,
+        gateway_management_url=gateway_management_url,
+    )
+    results: dict = {}
+
+    # Coordination API
+    try:
+        resp = httpx.get(f"{cfg.coordination_api_url}/healthz", timeout=5.0)
+        results["coordination_api"] = {
+            "url": cfg.coordination_api_url,
+            "status": "healthy" if resp.status_code == 200 else "unhealthy",
+            "status_code": resp.status_code,
+        }
+    except httpx.HTTPError as e:
+        results["coordination_api"] = {
+            "url": cfg.coordination_api_url,
+            "status": "unreachable",
+            "error": str(e),
+        }
+
+    # Proxy Gateway management
+    try:
+        health = httpx.get(f"{cfg.gateway_management_url}/healthz", timeout=5.0)
+        ready = httpx.get(f"{cfg.gateway_management_url}/readyz", timeout=5.0)
+        results["gateway"] = {
+            "url": cfg.gateway_management_url,
+            "healthy": health.status_code == 200,
+            "ready": ready.json().get("status") == "ready",
+        }
+    except httpx.HTTPError as e:
+        results["gateway"] = {
+            "url": cfg.gateway_management_url,
+            "status": "unreachable",
+            "error": str(e),
+        }
+
+    coord_ok = results.get("coordination_api", {}).get("status") == "healthy"
+    gw_ok = results.get("gateway", {}).get("healthy", False)
+    results["overall"] = "healthy" if (coord_ok and gw_ok) else "degraded"
+
+    print_json(results)
+    raise typer.Exit(code=0 if results["overall"] == "healthy" else 1)

spacerouter_cli-0.1.0/src/spacerouter_cli/config.py

@@ -0,0 +1,110 @@
+"""Configuration resolution for the SpaceRouter CLI.
+
+Priority (highest to lowest):
+  1. CLI flags (--api-key, --gateway-url, etc.)
+  2. Environment variables (SR_API_KEY, SR_GATEWAY_URL, SR_COORDINATION_API_URL)
+  3. Config file (~/.spacerouter/config.json)
+  4. Built-in defaults
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".spacerouter"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+ENV_API_KEY = "SR_API_KEY"
+ENV_GATEWAY_URL = "SR_GATEWAY_URL"
+ENV_COORDINATION_API_URL = "SR_COORDINATION_API_URL"
+ENV_GATEWAY_MANAGEMENT_URL = "SR_GATEWAY_MANAGEMENT_URL"
+
+DEFAULT_GATEWAY_URL = "https://gateway.spacerouter.org:8080"
+DEFAULT_COORDINATION_API_URL = "https://coordination.spacerouter.org"
+DEFAULT_GATEWAY_MANAGEMENT_URL = "http://gateway.spacerouter.org:8081"
+DEFAULT_TIMEOUT = 30.0
+
+ALLOWED_CONFIG_KEYS = {
+    "api_key",
+    "gateway_url",
+    "coordination_api_url",
+    "gateway_management_url",
+    "timeout",
+}
+
+
+@dataclass
+class CLIConfig:
+    api_key: str | None = None
+    gateway_url: str = DEFAULT_GATEWAY_URL
+    coordination_api_url: str = DEFAULT_COORDINATION_API_URL
+    gateway_management_url: str = DEFAULT_GATEWAY_MANAGEMENT_URL
+    timeout: float = DEFAULT_TIMEOUT
+
+
+def load_config_file() -> dict:
+    """Load config file, returning empty dict if missing or invalid."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def resolve_config(**cli_overrides: str | float | None) -> CLIConfig:
+    """Merge config file -> env vars -> CLI overrides.
+
+    Values that are ``None`` in a higher-priority layer are skipped so
+    lower-priority values can fill in.
+    """
+    file_cfg = load_config_file()
+
+    def _pick(key: str, env_var: str | None = None, default: str | float | None = None):
+        # CLI flag first
+        cli_val = cli_overrides.get(key)
+        if cli_val is not None:
+            return cli_val
+        # Env var second
+        if env_var:
+            env_val = os.environ.get(env_var)
+            if env_val is not None:
+                return env_val
+        # Config file third
+        file_val = file_cfg.get(key)
+        if file_val is not None:
+            return file_val
+        # Default last
+        return default
+
+    return CLIConfig(
+        api_key=_pick("api_key", ENV_API_KEY),
+        gateway_url=_pick("gateway_url", ENV_GATEWAY_URL, DEFAULT_GATEWAY_URL),
+        coordination_api_url=_pick(
+            "coordination_api_url", ENV_COORDINATION_API_URL, DEFAULT_COORDINATION_API_URL
+        ),
+        gateway_management_url=_pick(
+            "gateway_management_url", ENV_GATEWAY_MANAGEMENT_URL, DEFAULT_GATEWAY_MANAGEMENT_URL
+        ),
+        timeout=float(_pick("timeout", None, DEFAULT_TIMEOUT)),
+    )
+
+
+def save_config(updates: dict) -> None:
+    """Write *updates* into ~/.spacerouter/config.json (merge, not overwrite)."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    existing = load_config_file()
+    existing.update(updates)
+    CONFIG_FILE.write_text(json.dumps(existing, indent=2) + "\n")
+
+
+def mask_key(value: str | None) -> str | None:
+    """Mask an API key for display: ``sr_live_abc1****``."""
+    if not value:
+        return value
+    if len(value) <= 12:
+        return value[:4] + "****"
+    return value[:12] + "****"

spacerouter_cli-0.1.0/src/spacerouter_cli/main.py

@@ -0,0 +1,39 @@
+"""SpaceRouter CLI — AI-agent-friendly tool for residential proxy requests."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from spacerouter_cli import __version__
+from spacerouter_cli.commands import api_key, config_cmd, node, request, status
+
+app = typer.Typer(
+    name="spacerouter",
+    help="CLI for the Space Router residential proxy network. Designed for AI agents.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+app.add_typer(request.app, name="request", help="Make proxied HTTP requests")
+app.add_typer(api_key.app, name="api-key", help="Manage API keys")
+app.add_typer(node.app, name="node", help="View node information")
+app.add_typer(config_cmd.app, name="config", help="Configuration management")
+app.command(name="status", help="Check service health")(status.status)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(json.dumps({"version": __version__}))
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show CLI version and exit.",
+    ),
+) -> None:
+    """SpaceRouter CLI — residential proxy requests for AI agents."""