sellerclaw-cli 0.0.0__py3-none-any.whl

sellerclaw_cli/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("sellerclaw-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

sellerclaw_cli/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from sellerclaw_cli.cli import app
+
+if __name__ == "__main__":
+    app()

sellerclaw_cli/_auth.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from sellerclaw_cli._client import Client
+from sellerclaw_cli._errors import AuthError
+
+_DEVICE_CODE_PATH = "/agent/auth/device/code"
+_DEVICE_TOKEN_PATH = "/agent/auth/device/token"
+_PASSWORD_TOKEN_PATH = "/agent/auth/token"
+_SLOW_DOWN_STEP_SECONDS = 5
+
+
+@dataclass(frozen=True)
+class DeviceCode:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    expires_in: int
+    interval: int
+
+
+def request_device_code(api_url: str) -> DeviceCode:
+    """POST /agent/auth/device/code. Returns parsed DeviceCode."""
+    with Client(base_url=api_url, token=None) as client:
+        body = client.request("POST", _DEVICE_CODE_PATH)
+    return DeviceCode(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri=body["verification_uri"],
+        expires_in=int(body["expires_in"]),
+        interval=int(body["interval"]),
+    )
+
+
+def poll_device_token(
+    api_url: str,
+    device_code: str,
+    *,
+    interval: int,
+    expires_in: int,
+) -> str:
+    """Poll /agent/auth/device/token until granted or expired. Returns the agent_token (sca_...)."""
+    current_interval = interval
+    started = time.monotonic()
+
+    with Client(base_url=api_url, token=None) as client:
+        while True:
+            if time.monotonic() - started >= expires_in:
+                raise AuthError("Device code expired before authorization was granted.")
+
+            body = client.request("POST", _DEVICE_TOKEN_PATH, json={"device_code": device_code})
+
+            token = body.get("agent_token") if isinstance(body, dict) else None
+            if isinstance(token, str) and token:
+                return token
+
+            err = body.get("error") if isinstance(body, dict) else None
+            if err is None or err == "authorization_pending":
+                pass
+            elif err == "slow_down":
+                current_interval += _SLOW_DOWN_STEP_SECONDS
+            else:
+                raise AuthError(f"Device authorization failed: {err}")
+
+            time.sleep(current_interval)
+
+
+def password_login(api_url: str, email: str, password: str) -> str:
+    """POST /agent/auth/token with email+password. Returns the agent_token."""
+    with Client(base_url=api_url, token=None) as client:
+        body = client.request("POST", _PASSWORD_TOKEN_PATH, json={"email": email, "password": password})
+
+    token = body.get("agent_token") if isinstance(body, dict) else None
+    if not isinstance(token, str) or not token:
+        raise AuthError("Login response did not include an agent_token.")
+    return token

sellerclaw_cli/_client.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from sellerclaw_cli._errors import ApiError, AuthError, NetworkError, ServerError
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+RETRY_STATUS_CODES = frozenset({429, 502, 503, 504})
+MAX_RETRIES = 3
+_BACKOFF_CAP_SECONDS = 10.0
+_BACKOFF_JITTER_MAX = 0.25
+
+
+@dataclass
+class Client:
+    """Thin HTTP client for the SellerClaw Agent API. Shared between CLI and (future) MCP server."""
+
+    base_url: str
+    token: str | None
+    timeout: float = DEFAULT_TIMEOUT_SECONDS
+    _http: httpx.Client | None = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=self.timeout,
+        )
+
+    @classmethod
+    def from_env(cls) -> Client:
+        """Build a Client from Config.load() results."""
+        from sellerclaw_cli import _config
+
+        cfg = _config.load()
+        return cls(base_url=cfg.api_url, token=cfg.token)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> Any:
+        """Execute an HTTP request and return the parsed JSON body.
+
+        Raises AuthError (401/403), ApiError (other 4xx), ServerError (5xx after retries),
+        NetworkError (timeout/connection) — never raises httpx exceptions directly.
+        """
+        assert self._http is not None  # noqa: S101 — invariant from __post_init__
+        last_transport_error: httpx.HTTPError | None = None
+
+        for attempt in range(MAX_RETRIES):
+            is_last = attempt == MAX_RETRIES - 1
+            try:
+                response = self._http.request(method, path, params=params, json=json)
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.ReadError, httpx.WriteError) as exc:
+                last_transport_error = exc
+                if is_last:
+                    raise NetworkError(str(exc) or exc.__class__.__name__) from exc
+                time.sleep(_backoff_seconds(attempt))
+                continue
+            except httpx.HTTPError as exc:
+                # Anything else from httpx we consider a network-ish failure, but don't retry — it's unknown.
+                raise NetworkError(str(exc) or exc.__class__.__name__) from exc
+
+            status = response.status_code
+
+            if 200 <= status < 300:
+                return _decode_body(response)
+
+            if status in RETRY_STATUS_CODES and not is_last:
+                time.sleep(_retry_delay(response, attempt))
+                continue
+
+            raise _error_for_response(response)
+
+        # Loop exhausted only via transport errors; the `raise NetworkError` above should have fired.
+        raise NetworkError(str(last_transport_error) if last_transport_error else "exhausted retries")
+
+    def close(self) -> None:
+        if self._http is not None:
+            self._http.close()
+            self._http = None
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def _decode_body(response: httpx.Response) -> Any:
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return response.text
+
+
+def _error_for_response(response: httpx.Response) -> Exception:
+    status = response.status_code
+    message, details = _parse_error_body(response)
+
+    if status in (401, 403):
+        return AuthError(message, status=status, details=details)
+    if 400 <= status < 500:
+        return ApiError(message, status=status, details=details)
+    if 500 <= status < 600:
+        return ServerError(message, status=status, details=details)
+    return ApiError(message or f"unexpected status {status}", status=status, details=details)
+
+
+def _parse_error_body(response: httpx.Response) -> tuple[str, dict | None]:
+    if not response.content:
+        return f"HTTP {response.status_code}", None
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text or f"HTTP {response.status_code}", None
+
+    if isinstance(body, dict):
+        message = (
+            body.get("message")
+            or body.get("detail")
+            or body.get("error")
+            or f"HTTP {response.status_code}"
+        )
+        if not isinstance(message, str):
+            message = f"HTTP {response.status_code}"
+        return message, body
+    return f"HTTP {response.status_code}", {"body": body}
+
+
+def _retry_delay(response: httpx.Response, attempt: int) -> float:
+    retry_after = response.headers.get("Retry-After")
+    if retry_after is not None:
+        try:
+            return float(retry_after)
+        except ValueError:
+            pass
+    return _backoff_seconds(attempt)
+
+
+def _backoff_seconds(attempt: int) -> float:
+    base = min(2.0**attempt, _BACKOFF_CAP_SECONDS)
+    return base + random.uniform(0, _BACKOFF_JITTER_MAX)

sellerclaw_cli/_config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+import tomli_w
+
+DEFAULT_API_URL = "https://api.sellerclaw.com"
+ENV_TOKEN = "SELLERCLAW_TOKEN"
+ENV_API_URL = "SELLERCLAW_API_URL"
+ENV_XDG_CONFIG_HOME = "XDG_CONFIG_HOME"
+
+_CONFIG_DIR = "sellerclaw"
+_CONFIG_FILE = "config.toml"
+
+
+@dataclass(frozen=True)
+class Config:
+    api_url: str
+    token: str | None
+
+
+def config_path() -> Path:
+    """Return the absolute path to the config.toml file, respecting XDG_CONFIG_HOME."""
+    xdg = os.environ.get(ENV_XDG_CONFIG_HOME)
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / _CONFIG_DIR / _CONFIG_FILE
+
+
+def load() -> Config:
+    """Resolve config from env > config file > defaults."""
+    file_values = _read_file()
+    api_url = os.environ.get(ENV_API_URL) or file_values.get("api_url") or DEFAULT_API_URL
+    token = os.environ.get(ENV_TOKEN) or file_values.get("token") or None
+    return Config(api_url=api_url, token=token)
+
+
+def save_token(token: str) -> None:
+    """Persist the token to config.toml with 0600 permissions. Preserves any existing api_url."""
+    values = _read_file()
+    values["token"] = token
+    _write_file(values)
+
+
+def clear_token() -> None:
+    """Remove the token key from config.toml. No-op if file or key is missing."""
+    path = config_path()
+    if not path.exists():
+        return
+    values = _read_file()
+    if "token" not in values:
+        return
+    values.pop("token", None)
+    _write_file(values)
+
+
+def _read_file() -> dict[str, str]:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            parsed = tomllib.load(fh)
+    except tomllib.TOMLDecodeError:
+        return {}
+    return {k: v for k, v in parsed.items() if isinstance(v, str)}
+
+
+def _write_file(values: dict[str, str]) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as fh:
+        tomli_w.dump(values, fh)
+    # chmod after write — trade-off: tiny window where the file is world-readable on permissive umasks,
+    # but avoids platform-specific os.open(..., O_CREAT, 0o600) dance. Acceptable for a CLI.
+    try:
+        path.chmod(0o600)
+    except OSError:
+        # Non-POSIX filesystems may not support chmod; silently skip.
+        pass

sellerclaw_cli/_errors.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+class CliError(Exception):
+    """Base class for all CLI-raised errors that should be translated into the structured stderr contract."""
+
+    exit_code: int = 1
+    code: str = "error"
+
+    def __init__(self, message: str, *, status: int | None = None, details: dict | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.details = details
+
+
+class UserInputError(CliError):
+    exit_code = 1
+    code = "user_error"
+
+
+class ApiError(CliError):
+    exit_code = 1
+    code = "api_error"
+
+
+class AuthError(CliError):
+    exit_code = 3
+    code = "auth_error"
+
+
+class ServerError(CliError):
+    exit_code = 2
+    code = "server_error"
+
+
+class NetworkError(CliError):
+    exit_code = 2
+    code = "network_error"

sellerclaw_cli/_output.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import sys
+from enum import StrEnum
+from typing import IO, Any
+
+import yaml
+
+from sellerclaw_cli._errors import AuthError, CliError
+
+
+class OutputFormat(StrEnum):
+    JSON = "json"
+    PRETTY = "pretty"
+    YAML = "yaml"
+    TABLE = "table"
+
+
+AUTH_HINT = "Run `sellerclaw auth login` to authenticate."
+
+
+def print_ok(
+    data: Any,
+    *,
+    fmt: OutputFormat = OutputFormat.JSON,
+    stdout: IO[str] | None = None,
+) -> int:
+    """Serialize a successful response and write it to stdout. Returns exit code 0."""
+    out = stdout if stdout is not None else sys.stdout
+    envelope = {"data": data}
+
+    if fmt is OutputFormat.JSON:
+        out.write(json.dumps(envelope, separators=(",", ":"), ensure_ascii=False) + "\n")
+    elif fmt is OutputFormat.PRETTY:
+        out.write(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+    elif fmt is OutputFormat.YAML:
+        out.write(yaml.safe_dump(envelope, sort_keys=False, allow_unicode=True))
+    elif fmt is OutputFormat.TABLE:
+        out.write(_format_table(data))
+    else:  # pragma: no cover — enum exhaustiveness
+        raise ValueError(f"unsupported format: {fmt}")
+
+    return 0
+
+
+def print_error(
+    error: CliError,
+    *,
+    stderr: IO[str] | None = None,
+) -> int:
+    """Serialize a CliError as compact JSON to stderr. Returns the error's exit code."""
+    err_out = stderr if stderr is not None else sys.stderr
+
+    payload: dict[str, Any] = {"code": error.code, "message": error.message}
+    if error.status is not None:
+        payload["status"] = error.status
+    if error.details is not None:
+        payload["details"] = error.details
+    if isinstance(error, AuthError):
+        payload["hint"] = AUTH_HINT
+
+    envelope = {"error": payload}
+    err_out.write(json.dumps(envelope, separators=(",", ":"), ensure_ascii=False) + "\n")
+    return error.exit_code
+
+
+def _format_table(data: Any) -> str:
+    """Cheap ASCII table for a list of flat dicts; falls back to pretty JSON otherwise."""
+    if isinstance(data, list) and data and all(isinstance(row, dict) for row in data):
+        columns = list(data[0].keys())
+        rows = [[str(row.get(c, "")) for c in columns] for row in data]
+        widths = [max(len(c), *(len(r[i]) for r in rows)) for i, c in enumerate(columns)]
+        sep = "  "
+        lines = [sep.join(c.ljust(w) for c, w in zip(columns, widths, strict=True))]
+        lines.append(sep.join("-" * w for w in widths))
+        lines.extend(sep.join(r[i].ljust(widths[i]) for i in range(len(columns))) for r in rows)
+        return "\n".join(lines) + "\n"
+    return json.dumps({"data": data}, indent=2, ensure_ascii=False) + "\n"

sellerclaw_cli/_runtime.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from sellerclaw_cli._client import Client
+from sellerclaw_cli._errors import CliError, UserInputError
+from sellerclaw_cli._output import OutputFormat, print_error, print_ok
+
+
+def run_operation(
+    ctx: typer.Context,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json_body: Any = None,
+) -> None:
+    """Execute an API call and print its result in the user-selected format.
+
+    On any CliError, prints the structured error to stderr and exits with the mapped code —
+    generated commands should never need their own try/except.
+    """
+    try:
+        with Client.from_env() as client:
+            result = client.request(method, path, params=params, json=json_body)
+    except CliError as err:
+        code = print_error(err)
+        raise typer.Exit(code=code) from err
+    print_ok(result, fmt=_format_from_ctx(ctx))
+
+
+def parse_json_body(arg: str | None) -> Any:
+    """Parse the --json-body flag: literal JSON, '@-' for stdin, or '@/path' for a file."""
+    if arg is None:
+        return None
+    if arg == "@-":
+        return _decode_json(sys.stdin.read(), source="stdin")
+    if arg.startswith("@"):
+        path = Path(arg[1:]).expanduser()
+        if not path.exists():
+            raise UserInputError(f"--json-body file not found: {path}")
+        return _decode_json(path.read_text(), source=str(path))
+    return _decode_json(arg, source="--json-body")
+
+
+def emit_error(err: CliError) -> None:
+    """Write a CliError to stderr and raise typer.Exit with its mapped code."""
+    code = print_error(err)
+    raise typer.Exit(code=code)
+
+
+def _format_from_ctx(ctx: typer.Context) -> OutputFormat:
+    if ctx.obj is None:
+        return OutputFormat.JSON
+    return ctx.obj.get("format", OutputFormat.JSON)
+
+
+def _decode_json(text: str, *, source: str) -> Any:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as err:
+        raise UserInputError(
+            f"invalid JSON from {source}: {err.msg} (line {err.lineno}, col {err.colno})"
+        ) from err