clawifi 0.1.0__py3-none-any.whl

clawifi/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from clawifi.client import AsyncClawifi, Clawifi, ClawifiConfig
+from clawifi.errors import ClawifiAPIError, ClawifiError, ClawifiTransportError
+
+__all__ = [
+    "AsyncClawifi",
+    "Clawifi",
+    "ClawifiAPIError",
+    "ClawifiConfig",
+    "ClawifiError",
+    "ClawifiTransportError",
+]

clawifi/cli.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import urllib.error
+import urllib.request
+
+
+DEFAULT_API_BASE = "https://api.clawifi.qzz.io"
+
+
+def run(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="clawifi", description="Clawifi cloud CLI for agent internet reach.")
+    parser.add_argument("--api-base", default=os.getenv("CLAWIFI_API_BASE", DEFAULT_API_BASE))
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    signup = subcommands.add_parser("signup", help="Create a Clawifi account and first API key.")
+    signup.add_argument("--email", required=True)
+    signup.add_argument("--password", required=True)
+    signup.add_argument("--display-name")
+
+    login = subcommands.add_parser("login", help="Create an account session token.")
+    login.add_argument("--email", required=True)
+    login.add_argument("--password", required=True)
+
+    verify = subcommands.add_parser("verify-email", help="Verify your Clawifi email token and create an API key.")
+    verify.add_argument("--token", required=True)
+
+    quicktest = subcommands.add_parser("quicktest", help="Verify your API key against the Clawifi API.")
+    quicktest.add_argument("--url", default="https://example.com")
+
+    mcp = subcommands.add_parser("mcp", help="Print MCP setup helpers.")
+    mcp_subcommands = mcp.add_subparsers(dest="mcp_command", required=True)
+    mcp_subcommands.add_parser("config", help="Print a minimal MCP server config.")
+
+    browser = subcommands.add_parser("browser", help="Manage Clawifi browser runtime sessions.")
+    browser_subcommands = browser.add_subparsers(dest="browser_command", required=True)
+    browser_pair = browser_subcommands.add_parser("pair", help="Create a short-lived WebBridge pairing code.")
+    browser_pair.add_argument(
+        "--local-api-base",
+        default=os.getenv("CLAWIFI_LOCAL_API_BASE", "http://127.0.0.1:8000"),
+    )
+    browser_doctor = browser_subcommands.add_parser(
+        "doctor", help="Run browser runtime and agent configuration diagnostics."
+    )
+    browser_doctor.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Include the complete check report (currently the default output).",
+    )
+    browser_doctor.add_argument(
+        "--local-api-base",
+        default=os.getenv("CLAWIFI_LOCAL_API_BASE", "http://127.0.0.1:8000"),
+    )
+    browser_start = browser_subcommands.add_parser("start", help="Start a managed headed or headless browser session.")
+    browser_start.add_argument("--url", required=True)
+    browser_start.add_argument("--mode", choices=("headless", "headed"), default="headless")
+    browser_start.add_argument("--profile-id")
+    browser_start.add_argument("--ttl-seconds", type=int, default=300)
+    browser_start.add_argument(
+        "--local-api-base",
+        default=os.getenv("CLAWIFI_LOCAL_API_BASE", "http://127.0.0.1:8000"),
+    )
+    browser_status = browser_subcommands.add_parser("status", help="List browser sessions or inspect one session.")
+    browser_status.add_argument("session_id", nargs="?")
+    browser_status.add_argument(
+        "--local-api-base",
+        default=os.getenv("CLAWIFI_LOCAL_API_BASE", "http://127.0.0.1:8000"),
+    )
+    browser_stop = browser_subcommands.add_parser("stop", help="Close one or all browser sessions.")
+    browser_stop_target = browser_stop.add_mutually_exclusive_group(required=True)
+    browser_stop_target.add_argument("session_id", nargs="?")
+    browser_stop_target.add_argument("--all", action="store_true")
+    browser_stop.add_argument(
+        "--local-api-base",
+        default=os.getenv("CLAWIFI_LOCAL_API_BASE", "http://127.0.0.1:8000"),
+    )
+    browser_smoke = browser_subcommands.add_parser("smoke", help="Create, verify, and always close a browser session.")
+    browser_smoke.add_argument("--url", default="https://example.com")
+    browser_smoke.add_argument("--mode", choices=("headless", "headed"), default="headless")
+    browser_smoke.add_argument("--profile-id")
+    browser_smoke.add_argument("--ttl-seconds", type=int, default=300)
+    browser_smoke.add_argument(
+        "--local-api-base",
+        default=os.getenv("CLAWIFI_LOCAL_API_BASE", "http://127.0.0.1:8000"),
+    )
+
+    monitors = subcommands.add_parser("monitors", help="Manage Evidence Monitor checks.")
+    monitor_subcommands = monitors.add_subparsers(dest="monitor_command", required=True)
+    monitor_create = monitor_subcommands.add_parser("create", help="Create a monitor.")
+    monitor_create.add_argument("--name", required=True)
+    monitor_create.add_argument("--url", required=True)
+    monitor_create.add_argument("--interval-seconds", type=int, default=900)
+    monitor_create.add_argument("--format", dest="formats", action="append", default=None)
+    monitor_create.add_argument("--diff-mode", dest="diff_modes", action="append", default=None)
+    monitor_create.add_argument("--json", action="store_true")
+    monitor_list = monitor_subcommands.add_parser("list", help="List monitors.")
+    monitor_list.add_argument("--include-deleted", action="store_true")
+    monitor_list.add_argument("--json", action="store_true")
+    monitor_get = monitor_subcommands.add_parser("get", help="Get one monitor.")
+    monitor_get.add_argument("monitor_id")
+    monitor_get.add_argument("--json", action="store_true")
+    monitor_pause = monitor_subcommands.add_parser("pause", help="Pause a monitor.")
+    monitor_pause.add_argument("monitor_id")
+    monitor_pause.add_argument("--json", action="store_true")
+    monitor_resume = monitor_subcommands.add_parser("resume", help="Resume a monitor.")
+    monitor_resume.add_argument("monitor_id")
+    monitor_resume.add_argument("--run-immediately", action="store_true")
+    monitor_resume.add_argument("--json", action="store_true")
+    monitor_delete = monitor_subcommands.add_parser("delete", help="Delete a monitor.")
+    monitor_delete.add_argument("monitor_id")
+    monitor_delete.add_argument("--json", action="store_true")
+    monitor_run = monitor_subcommands.add_parser("run", help="Run a monitor now.")
+    monitor_run.add_argument("monitor_id")
+    monitor_run.add_argument("--json", action="store_true")
+
+    args = parser.parse_args(argv)
+    api_base = args.api_base.rstrip("/")
+
+    if args.command == "signup":
+        payload = _request(
+            "POST",
+            f"{api_base}/auth/signup",
+            json_body={"email": args.email, "password": args.password, "display_name": args.display_name},
+        )
+        print("Clawifi account created.")
+        print(f"Email: {payload['account']['email']}")
+        print(f"Credits: {payload['credits']['available']}")
+        if payload.get("requires_email_verification"):
+            print("Email verification is required before an API key is issued.")
+            return
+        print("Set this key in your agent runtime:")
+        print(f"export CLAWIFI_API_KEY={payload['api_key']}")
+        raise SystemExit(0)
+
+    if args.command == "verify-email":
+        payload = _request("POST", f"{api_base}/auth/verify-email", json_body={"token": args.token})
+        print("Clawifi email verified.")
+        print(f"Email: {payload['account']['email']}")
+        print(f"Credits: {payload['credits']['available']}")
+        print(f"export CLAWIFI_SESSION_TOKEN={payload['session_token']}")
+        print(f"export CLAWIFI_API_KEY={payload['api_key']}")
+        raise SystemExit(0)
+
+    if args.command == "login":
+        payload = _request(
+            "POST",
+            f"{api_base}/auth/login",
+            json_body={"email": args.email, "password": args.password},
+        )
+        print("Clawifi session created.")
+        print(f"Session expires: {payload['session_expires_at']}")
+        print(f"export CLAWIFI_SESSION_TOKEN={payload['session_token']}")
+        raise SystemExit(0)
+
+    if args.command == "quicktest":
+        api_key = _required_api_key()
+        payload = _request(
+            "POST",
+            f"{api_base}/fetch",
+            token=api_key,
+            json_body={"url": args.url, "timeout_seconds": 15},
+        )
+        print(json.dumps({"ok": True, "success": payload.get("success"), "source": payload.get("source")}, indent=2))
+        raise SystemExit(0)
+
+    if args.command == "mcp" and args.mcp_command == "config":
+        _required_api_key()
+        print(json.dumps({
+            "mcpServers": {
+                "clawifi": {
+                    "command": "clawifi-mcp",
+                    "env": {
+                        "CLAWIFI_API_KEY": "${CLAWIFI_API_KEY}",
+                        "CLAWIFI_API_BASE": api_base
+                    }
+                }
+            }
+        }, indent=2))
+        raise SystemExit(0)
+
+    if args.command == "browser":
+        api_key = _required_api_key()
+        local_api_base = args.local_api_base.rstrip("/")
+        if args.browser_command == "pair":
+            payload = _request(
+                "POST",
+                f"{local_api_base}/browser/bridge/pairing",
+                token=api_key,
+                json_body={},
+            )
+            print("One-time WebBridge pairing code:")
+            print(payload["code"])
+            print(f"Expires in {payload['expires_in_seconds']} seconds.")
+            print("Paste it into the Clawifi WebBridge extension. It can be used once.")
+        elif args.browser_command == "doctor":
+            payload = _request("GET", f"{local_api_base}/browser/doctor", token=api_key)
+            print(json.dumps(payload, indent=2, sort_keys=True))
+            if not payload.get("ok", False):
+                raise SystemExit(1)
+        elif args.browser_command == "start":
+            request_payload = {
+                "url": args.url,
+                "mode": args.mode,
+                "ttl_seconds": args.ttl_seconds,
+                **({"profile_id": args.profile_id} if args.profile_id else {}),
+            }
+            payload = _request(
+                "POST",
+                f"{local_api_base}/browser/sessions",
+                token=api_key,
+                json_body=request_payload,
+            )
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        elif args.browser_command == "status":
+            suffix = f"/{args.session_id}" if args.session_id else ""
+            payload = _request("GET", f"{local_api_base}/browser/sessions{suffix}", token=api_key)
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        elif args.browser_command == "stop":
+            if args.all:
+                payload = _request(
+                    "DELETE",
+                    f"{local_api_base}/browser/sessions",
+                    token=api_key,
+                    json_body={"session_ids": None},
+                )
+            else:
+                payload = _request(
+                    "DELETE",
+                    f"{local_api_base}/browser/sessions/{args.session_id}",
+                    token=api_key,
+                )
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        elif args.browser_command == "smoke":
+            request_payload = {
+                "url": args.url,
+                "mode": args.mode,
+                "ttl_seconds": args.ttl_seconds,
+                **({"profile_id": args.profile_id} if args.profile_id else {}),
+            }
+            created = _request(
+                "POST",
+                f"{local_api_base}/browser/sessions",
+                token=api_key,
+                json_body=request_payload,
+            )
+            session_id = created.get("session_id")
+            cleanup = None
+            try:
+                if not session_id or created.get("status") != "ready":
+                    raise SystemExit("Browser smoke failed: session did not become ready")
+            finally:
+                if session_id:
+                    cleanup = _request(
+                        "DELETE",
+                        f"{local_api_base}/browser/sessions/{session_id}",
+                        token=api_key,
+                    )
+            print(json.dumps({"ok": True, "session": created, "cleanup": cleanup}, indent=2, sort_keys=True))
+        raise SystemExit(0)
+
+    if args.command == "monitors":
+        api_key = _required_api_key()
+        if args.monitor_command == "create":
+            payload = _request(
+                "POST",
+                f"{api_base}/monitors",
+                token=api_key,
+                json_body={
+                    "name": args.name,
+                    "url": args.url,
+                    "schedule": {"interval_seconds": args.interval_seconds},
+                    "formats": args.formats or ["markdown", "text", "metadata", "links"],
+                    "diff_modes": args.diff_modes or ["text"],
+                },
+            )
+            _print_monitor_payload(payload, as_json=args.json)
+        elif args.monitor_command == "list":
+            suffix = "?include_deleted=true" if args.include_deleted else ""
+            payload = _request("GET", f"{api_base}/monitors{suffix}", token=api_key)
+            _print_monitor_payload(payload, as_json=args.json)
+        elif args.monitor_command == "get":
+            payload = _request("GET", f"{api_base}/monitors/{args.monitor_id}", token=api_key)
+            _print_monitor_payload(payload, as_json=args.json)
+        elif args.monitor_command == "pause":
+            payload = _request("POST", f"{api_base}/monitors/{args.monitor_id}/pause", token=api_key, json_body={})
+            _print_monitor_payload(payload, as_json=args.json)
+        elif args.monitor_command == "resume":
+            payload = _request(
+                "POST",
+                f"{api_base}/monitors/{args.monitor_id}/resume",
+                token=api_key,
+                json_body={"run_immediately": args.run_immediately},
+            )
+            _print_monitor_payload(payload, as_json=args.json)
+        elif args.monitor_command == "delete":
+            payload = _request("DELETE", f"{api_base}/monitors/{args.monitor_id}", token=api_key)
+            _print_monitor_payload(payload, as_json=args.json)
+        elif args.monitor_command == "run":
+            payload = _request("POST", f"{api_base}/monitors/{args.monitor_id}/run", token=api_key)
+            _print_monitor_payload(payload, as_json=args.json)
+        raise SystemExit(0)
+
+
+def _required_api_key() -> str:
+    api_key = os.getenv("CLAWIFI_API_KEY", "").strip()
+    if not api_key:
+        raise SystemExit("CLAWIFI_API_KEY is required. Run `clawifi signup --email you@example.com --password ...` first.")
+    return api_key
+
+
+def _request(method: str, url: str, *, json_body: dict | None = None, token: str | None = None) -> dict:
+    body = json.dumps(json_body or {}, separators=(",", ":")).encode("utf-8") if json_body is not None else None
+    headers = {"Content-Type": "application/json", "User-Agent": "clawifi-cli/0.1.0 (+https://clawifi.qzz.io)"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    request = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise SystemExit(f"Clawifi API error {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise SystemExit(f"Clawifi API unreachable: {exc.reason}") from exc
+
+
+def _print_monitor_payload(payload: dict, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    if "monitors" in payload:
+        print(f"Monitors: {payload.get('total', len(payload['monitors']))}")
+        for monitor in payload["monitors"]:
+            print(f"- {monitor.get('monitor_id')} {monitor.get('status')} {monitor.get('name')}")
+        return
+    label = payload.get("monitor_id") or payload.get("tick_id") or payload.get("status") or "ok"
+    print(f"Monitor result: {label}")
+
+
+if __name__ == "__main__":
+    run()

clawifi/client.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, Iterator
+
+import httpx
+
+from clawifi.errors import ClawifiAPIError, ClawifiTransportError
+
+DEFAULT_API_BASE = "https://api.clawifi.qzz.io"
+RETRYABLE_STATUS_CODES = {408, 425, 429, 500, 502, 503, 504}
+TERMINAL_JOB_STATUSES = {"succeeded", "failed", "cancelled"}
+TERMINAL_CRAWL_STATUSES = {"succeeded", "partial", "failed", "stopped", "interrupted"}
+
+
+@dataclass(frozen=True)
+class ClawifiConfig:
+    api_key: str | None = None
+    api_base: str = DEFAULT_API_BASE
+    timeout: float = 30.0
+    max_retries: int = 2
+
+    @classmethod
+    def from_env(cls) -> "ClawifiConfig":
+        timeout = float(os.getenv("CLAWIFI_TIMEOUT", "30"))
+        max_retries = int(os.getenv("CLAWIFI_MAX_RETRIES", "2"))
+        return cls(
+            api_key=os.getenv("CLAWIFI_API_KEY"),
+            api_base=os.getenv("CLAWIFI_API_BASE", DEFAULT_API_BASE).rstrip("/"),
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    def __repr__(self) -> str:
+        masked = "***" if self.api_key else None
+        return f"ClawifiConfig(api_key={masked!r}, api_base={self.api_base!r}, timeout={self.timeout!r}, max_retries={self.max_retries!r})"
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_base: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        config: ClawifiConfig | None = None,
+    ) -> None:
+        env_config = config or ClawifiConfig.from_env()
+        self.config = ClawifiConfig(
+            api_key=api_key if api_key is not None else env_config.api_key,
+            api_base=(api_base or env_config.api_base).rstrip("/"),
+            timeout=timeout if timeout is not None else env_config.timeout,
+            max_retries=max_retries if max_retries is not None else env_config.max_retries,
+        )
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/json", "User-Agent": "clawifi/0.1.0"}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self.config.api_base}/{path.lstrip('/')}"
+
+    @staticmethod
+    def _should_retry(method: str, idempotent: bool, status_code: int) -> bool:
+        return (method.upper() in {"GET", "HEAD"} or idempotent) and status_code in RETRYABLE_STATUS_CODES
+
+
+class Clawifi(_BaseClient):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_base: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        config: ClawifiConfig | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, api_base=api_base, timeout=timeout, max_retries=max_retries, config=config)
+        self._client = httpx.Client(timeout=self.config.timeout, transport=transport, headers=self._headers())
+
+    @property
+    def is_closed(self) -> bool:
+        return self._client.is_closed
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Clawifi":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, *, json: dict[str, Any] | None = None, params: dict[str, Any] | None = None, idempotent: bool = False) -> dict[str, Any]:
+        attempts = self.config.max_retries + 1
+        for attempt in range(attempts):
+            try:
+                response = self._client.request(method, self._url(path), json=json, params=params)
+            except httpx.HTTPError as exc:
+                raise ClawifiTransportError(str(exc)) from exc
+            if response.status_code < 400:
+                return _decode_response(response)
+            payload = _decode_response(response)
+            if attempt < attempts - 1 and self._should_retry(method, idempotent, response.status_code):
+                continue
+            raise ClawifiAPIError.from_response(response.status_code, payload, request_id=response.headers.get("X-Clawifi-Request-ID"))
+        raise ClawifiTransportError("request retry loop exited unexpectedly")
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, *, json: dict[str, Any] | None = None, idempotent: bool = False) -> dict[str, Any]:
+        return self.request("POST", path, json=json, idempotent=idempotent)
+
+    def fetch(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/fetch", json={"url": url, **kwargs}, idempotent=True)
+
+    def scrape(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/scrape", json={"url": url, **kwargs}, idempotent=True)
+
+    def schema_assist(self, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/schema/assist", json=kwargs, idempotent=True)
+
+    def search_free(self, query: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/search/free", json={"query": query, **kwargs}, idempotent=True)
+
+    def extract(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/extract", json={"url": url, **kwargs}, idempotent=True)
+
+    def map(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/map", json={"url": url, **kwargs}, idempotent=True)
+
+    def crawl(self, seed_url: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/crawl", json={"seed_url": seed_url, **kwargs}, idempotent=True)
+
+    def create_job(self, operation: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.post("/jobs", json={"operation": operation, "payload": payload})
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        return self.get(f"/jobs/{job_id}")
+
+    def poll_job(self, job_id: str, *, interval_seconds: float = 0.5, timeout_seconds: float = 60.0) -> dict[str, Any]:
+        return _poll(lambda: self.get_job(job_id), status_key="status", terminal=TERMINAL_JOB_STATUSES, interval_seconds=interval_seconds, timeout_seconds=timeout_seconds)
+
+    def get_crawl(self, crawl_id: str) -> dict[str, Any]:
+        return self.get(f"/crawls/{crawl_id}")
+
+    def poll_crawl(self, crawl_id: str, *, interval_seconds: float = 0.5, timeout_seconds: float = 60.0) -> dict[str, Any]:
+        return _poll(lambda: self.get_crawl(crawl_id), status_key="status", terminal=TERMINAL_CRAWL_STATUSES, interval_seconds=interval_seconds, timeout_seconds=timeout_seconds)
+
+    def list_history(self, **params: Any) -> dict[str, Any]:
+        return self.get("/history", params=params)
+
+    def iter_history(self, **params: Any) -> Iterator[dict[str, Any]]:
+        yield from _iter_cursor(lambda cursor: self.list_history(**({**params, "cursor": cursor} if cursor else params)), "items")
+
+    def list_monitors(self, **params: Any) -> dict[str, Any]:
+        return self.get("/monitors", params=params)
+
+    def iter_monitors(self, **params: Any) -> Iterator[dict[str, Any]]:
+        yield from _iter_cursor(lambda cursor: self.list_monitors(**({**params, "cursor": cursor} if cursor else params)), "monitors")
+
+    def account(self) -> dict[str, Any]:
+        return self.get("/account/me")
+
+    def credits(self) -> dict[str, Any]:
+        return self.get("/usage")
+
+
+class AsyncClawifi(_BaseClient):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_base: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        config: ClawifiConfig | None = None,
+        transport: httpx.AsyncBaseTransport | httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, api_base=api_base, timeout=timeout, max_retries=max_retries, config=config)
+        self._client = httpx.AsyncClient(timeout=self.config.timeout, transport=transport, headers=self._headers())
+
+    @property
+    def is_closed(self) -> bool:
+        return self._client.is_closed
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncClawifi":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    async def request(self, method: str, path: str, *, json: dict[str, Any] | None = None, params: dict[str, Any] | None = None, idempotent: bool = False) -> dict[str, Any]:
+        attempts = self.config.max_retries + 1
+        for attempt in range(attempts):
+            try:
+                response = await self._client.request(method, self._url(path), json=json, params=params)
+            except httpx.HTTPError as exc:
+                raise ClawifiTransportError(str(exc)) from exc
+            if response.status_code < 400:
+                return _decode_response(response)
+            payload = _decode_response(response)
+            if attempt < attempts - 1 and self._should_retry(method, idempotent, response.status_code):
+                continue
+            raise ClawifiAPIError.from_response(response.status_code, payload, request_id=response.headers.get("X-Clawifi-Request-ID"))
+        raise ClawifiTransportError("request retry loop exited unexpectedly")
+
+    async def get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, *, json: dict[str, Any] | None = None, idempotent: bool = False) -> dict[str, Any]:
+        return await self.request("POST", path, json=json, idempotent=idempotent)
+
+    async def fetch(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/fetch", json={"url": url, **kwargs}, idempotent=True)
+
+    async def scrape(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/scrape", json={"url": url, **kwargs}, idempotent=True)
+
+    async def schema_assist(self, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/schema/assist", json=kwargs, idempotent=True)
+
+    async def search_free(self, query: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/search/free", json={"query": query, **kwargs}, idempotent=True)
+
+    async def extract(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/extract", json={"url": url, **kwargs}, idempotent=True)
+
+    async def map(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/map", json={"url": url, **kwargs}, idempotent=True)
+
+    async def crawl(self, seed_url: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.post("/crawl", json={"seed_url": seed_url, **kwargs}, idempotent=True)
+
+    async def create_job(self, operation: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return await self.post("/jobs", json={"operation": operation, "payload": payload})
+
+    async def get_job(self, job_id: str) -> dict[str, Any]:
+        return await self.get(f"/jobs/{job_id}")
+
+    async def poll_job(self, job_id: str, *, interval_seconds: float = 0.5, timeout_seconds: float = 60.0) -> dict[str, Any]:
+        return await _apoll(lambda: self.get_job(job_id), status_key="status", terminal=TERMINAL_JOB_STATUSES, interval_seconds=interval_seconds, timeout_seconds=timeout_seconds)
+
+    async def get_crawl(self, crawl_id: str) -> dict[str, Any]:
+        return await self.get(f"/crawls/{crawl_id}")
+
+    async def poll_crawl(self, crawl_id: str, *, interval_seconds: float = 0.5, timeout_seconds: float = 60.0) -> dict[str, Any]:
+        return await _apoll(lambda: self.get_crawl(crawl_id), status_key="status", terminal=TERMINAL_CRAWL_STATUSES, interval_seconds=interval_seconds, timeout_seconds=timeout_seconds)
+
+    async def list_history(self, **params: Any) -> dict[str, Any]:
+        return await self.get("/history", params=params)
+
+    async def iter_history(self, **params: Any) -> AsyncIterator[dict[str, Any]]:
+        async for item in _aiter_cursor(lambda cursor: self.list_history(**({**params, "cursor": cursor} if cursor else params)), "items"):
+            yield item
+
+    async def list_monitors(self, **params: Any) -> dict[str, Any]:
+        return await self.get("/monitors", params=params)
+
+    async def iter_monitors(self, **params: Any) -> AsyncIterator[dict[str, Any]]:
+        async for item in _aiter_cursor(lambda cursor: self.list_monitors(**({**params, "cursor": cursor} if cursor else params)), "monitors"):
+            yield item
+
+    async def account(self) -> dict[str, Any]:
+        return await self.get("/account/me")
+
+    async def credits(self) -> dict[str, Any]:
+        return await self.get("/usage")
+
+
+def _decode_response(response: httpx.Response) -> dict[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ClawifiTransportError("Clawifi response was not JSON") from exc
+    if not isinstance(payload, dict):
+        raise ClawifiTransportError("Clawifi response JSON must be an object")
+    return payload
+
+
+def _poll(fetch_status, *, status_key: str, terminal: set[str], interval_seconds: float, timeout_seconds: float) -> dict[str, Any]:
+    deadline = time.monotonic() + timeout_seconds
+    while True:
+        payload = fetch_status()
+        if str(payload.get(status_key)) in terminal:
+            return payload
+        if time.monotonic() >= deadline:
+            raise TimeoutError("poll timed out")
+        time.sleep(interval_seconds)
+
+
+async def _apoll(fetch_status, *, status_key: str, terminal: set[str], interval_seconds: float, timeout_seconds: float) -> dict[str, Any]:
+    deadline = time.monotonic() + timeout_seconds
+    while True:
+        payload = await fetch_status()
+        if str(payload.get(status_key)) in terminal:
+            return payload
+        if time.monotonic() >= deadline:
+            raise TimeoutError("poll timed out")
+        await asyncio.sleep(interval_seconds)
+
+
+def _iter_cursor(fetch_page, item_key: str) -> Iterator[dict[str, Any]]:
+    cursor: str | None = None
+    seen_cursors: set[str] = set()
+    while True:
+        page = fetch_page(cursor)
+        yield from page.get(item_key, [])
+        cursor = page.get("next_cursor")
+        if not cursor or cursor in seen_cursors:
+            break
+        seen_cursors.add(cursor)
+
+
+async def _aiter_cursor(fetch_page, item_key: str) -> AsyncIterator[dict[str, Any]]:
+    cursor: str | None = None
+    seen_cursors: set[str] = set()
+    while True:
+        page = await fetch_page(cursor)
+        for item in page.get(item_key, []):
+            yield item
+        cursor = page.get("next_cursor")
+        if not cursor or cursor in seen_cursors:
+            break
+        seen_cursors.add(cursor)

clawifi/errors.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ClawifiError(Exception):
+    """Base SDK error."""
+
+
+class ClawifiTransportError(ClawifiError):
+    """Raised when the HTTP transport fails before Clawifi returns an error payload."""
+
+
+class ClawifiAPIError(ClawifiError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.details = details or {}
+        self.response = response or {}
+
+    @classmethod
+    def from_response(cls, status_code: int, payload: dict[str, Any], *, request_id: str | None = None) -> "ClawifiAPIError":
+        error = payload.get("error") if isinstance(payload, dict) else None
+        if not isinstance(error, dict):
+            return cls("Clawifi API request failed", status_code=status_code, request_id=request_id, response=payload)
+        details = error.get("details") if isinstance(error.get("details"), dict) else {}
+        error_request_id = error.get("request_id") or details.get("request_id") or request_id
+        return cls(
+            str(error.get("message") or "Clawifi API request failed"),
+            status_code=status_code,
+            code=error.get("code"),
+            request_id=str(error_request_id) if error_request_id else None,
+            details=details,
+            response=payload,
+        )

clawifi/mcp_server.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from clawifi.client import Clawifi
+
+mcp = FastMCP("clawifi")
+
+
+def _client() -> Clawifi:
+    return Clawifi()
+
+
+@mcp.tool()
+def fetch(url: str, timeout_seconds: int = 15) -> dict[str, Any]:
+    """Fetch a single URL and return its extracted content."""
+    with _client() as client:
+        return client.fetch(url, timeout_seconds=timeout_seconds)
+
+
+@mcp.tool()
+def scrape(url: str, **kwargs: Any) -> dict[str, Any]:
+    """Scrape a URL with source-aware routing and return structured content."""
+    with _client() as client:
+        return client.scrape(url, **kwargs)
+
+
+@mcp.tool()
+def search_free(query: str) -> dict[str, Any]:
+    """Run a free-tier web search and return results."""
+    with _client() as client:
+        return client.search_free(query)
+
+
+@mcp.tool()
+def extract(url: str, **kwargs: Any) -> dict[str, Any]:
+    """Extract structured data from a URL."""
+    with _client() as client:
+        return client.extract(url, **kwargs)
+
+
+@mcp.tool()
+def map_site(url: str, **kwargs: Any) -> dict[str, Any]:
+    """Map a site's discoverable URLs starting from a seed URL."""
+    with _client() as client:
+        return client.map(url, **kwargs)
+
+
+@mcp.tool()
+def crawl(seed_url: str, **kwargs: Any) -> dict[str, Any]:
+    """Start an asynchronous crawl from a seed URL. Returns a crawl_id to poll."""
+    with _client() as client:
+        return client.crawl(seed_url, **kwargs)
+
+
+@mcp.tool()
+def get_crawl(crawl_id: str) -> dict[str, Any]:
+    """Get the current status and results of a crawl."""
+    with _client() as client:
+        return client.get_crawl(crawl_id)
+
+
+@mcp.tool()
+def create_job(operation: str, payload: dict[str, Any]) -> dict[str, Any]:
+    """Create an asynchronous job for a billable operation. Returns a job_id to poll."""
+    with _client() as client:
+        return client.create_job(operation, payload)
+
+
+@mcp.tool()
+def get_job(job_id: str) -> dict[str, Any]:
+    """Get the current status and results of a job."""
+    with _client() as client:
+        return client.get_job(job_id)
+
+
+@mcp.tool()
+def account() -> dict[str, Any]:
+    """Get the authenticated account's profile and plan."""
+    with _client() as client:
+        return client.account()
+
+
+@mcp.tool()
+def credits() -> dict[str, Any]:
+    """Get the authenticated account's credit usage and remaining balance."""
+    with _client() as client:
+        return client.credits()
+
+
+@mcp.tool()
+def list_history(**params: Any) -> dict[str, Any]:
+    """List past requests for the authenticated account."""
+    with _client() as client:
+        return client.list_history(**params)
+
+
+@mcp.tool()
+def list_monitors(**params: Any) -> dict[str, Any]:
+    """List configured Evidence Monitor checks for the authenticated account."""
+    with _client() as client:
+        return client.list_monitors(**params)
+
+
+def run() -> None:
+    if not os.getenv("CLAWIFI_API_KEY"):
+        raise SystemExit(
+            "CLAWIFI_API_KEY is required. Get one at https://clawifi.qzz.io/signup, "
+            "then export CLAWIFI_API_KEY=... before starting this MCP server."
+        )
+    mcp.run()
+
+
+if __name__ == "__main__":
+    run()

clawifi/py.typed

@@ -0,0 +1 @@
+

clawifi/testing.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+def fixture_root(start: Path | None = None) -> Path:
+    current = (start or Path(__file__).resolve()).parent
+    for candidate in [current, *current.parents]:
+        manifest = candidate / "tests" / "fixtures" / "sdk" / "manifest.json"
+        if manifest.exists():
+            return manifest.parent
+    raise FileNotFoundError("could not locate tests/fixtures/sdk/manifest.json")
+
+
+def load_fixture_manifest(root: Path | None = None) -> dict[str, Any]:
+    manifest_path = (root or fixture_root()) / "manifest.json"
+    return _load_json(manifest_path)
+
+
+def fixture_transport(*, errors: set[str] | None = None, root: Path | None = None) -> httpx.MockTransport:
+    fixture_dir = root or fixture_root()
+    manifest = load_fixture_manifest(fixture_dir)
+    routes = _routes_from_manifest(manifest)
+    error_routes = errors or set()
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        route_key = f"{request.method.upper()} {request.url.path}"
+        metadata = routes.get(route_key)
+        if metadata is None and route_key.startswith("GET /jobs/"):
+            metadata = routes["POST /jobs"]
+        if metadata is None and route_key.startswith("GET /crawls/"):
+            metadata = routes["POST /crawl"]
+        if metadata is None:
+            return httpx.Response(404, json=_not_found_payload(route_key), headers={"X-Clawifi-Request-ID": "req_sdk_fixture"})
+
+        fixture_name = metadata["error_fixture"] if route_key in error_routes else metadata["success_fixture"]
+        status_code = 422 if route_key in error_routes else 200
+        return httpx.Response(
+            status_code,
+            json=_load_json(fixture_dir / fixture_name),
+            headers={"X-Clawifi-Request-ID": "req_sdk_fixture"},
+        )
+
+    return httpx.MockTransport(handler)
+
+
+def _routes_from_manifest(manifest: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    operations = manifest.get("operations", {})
+    return {f"{metadata['method'].upper()} {metadata['path']}": metadata for metadata in operations.values()}
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"fixture must be a JSON object: {path}")
+    return payload
+
+
+def _not_found_payload(route_key: str) -> dict[str, Any]:
+    return {
+        "error": {
+            "code": "fixture_not_found",
+            "message": f"No SDK fixture exists for {route_key}",
+            "details": {"request_id": "req_sdk_fixture", "retryable": False},
+        }
+    }

clawifi-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: clawifi
+Version: 0.1.0
+Summary: Official Python SDK, CLI, and MCP server for Clawifi, the agent-native internet gateway.
+License-Expression: MIT
+Project-URL: Homepage, https://clawifi.qzz.io
+Project-URL: Documentation, https://clawifi.qzz.io/docs
+Project-URL: Repository, https://github.com/atakanelik34/clawifi-mcp
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.3; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "test"
+Dynamic: license-file
+
+# clawifi
+
+<!-- mcp-name: io.github.atakanelik34/clawifi-mcp -->
+
+Official Python SDK, CLI, and MCP server for [Clawifi](https://clawifi.qzz.io), the agent-native internet gateway.
+
+This package is a thin client over the hosted Clawifi API. It does not include the Clawifi server, browser runtime, or Playwright — those run on Clawifi's infrastructure.
+
+## Install
+
+```bash
+pip install clawifi
+```
+
+## Get an API key
+
+```bash
+clawifi signup --email you@example.com --password "a strong password"
+```
+
+This creates an account, grants 1,000 free credits, and prints an API key. Export it:
+
+```bash
+export CLAWIFI_API_KEY="clawifi_live_..."
+```
+
+## Quicktest
+
+```bash
+clawifi quicktest --url https://example.com
+```
+
+## Use as an MCP server
+
+```bash
+clawifi mcp config
+```
+
+prints a ready-to-paste MCP client config. The MCP server itself runs as:
+
+```bash
+clawifi-mcp
+```
+
+reading `CLAWIFI_API_KEY` from the environment.
+
+## Use as a Python SDK
+
+```python
+from clawifi import Clawifi
+
+client = Clawifi()  # reads CLAWIFI_API_KEY from the environment
+page = client.fetch("https://example.com")
+print(page["success"])
+```
+
+An async client is also available as `clawifi.AsyncClawifi`.
+
+## Documentation
+
+See [clawifi.qzz.io/docs](https://clawifi.qzz.io/docs) for the full API reference, MCP tool list, and CLI command reference.
+
+## License
+
+MIT

clawifi-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+clawifi/__init__.py,sha256=KtRFoqeDwHlolHjqGOZFQ7HDbXT0EntsNX2CZ5sbFvo,323
+clawifi/cli.py,sha256=OVamRM8xlv74Dq3o9HFEn1VMh_du1OZKXxd1KiDIXMk,16110
+clawifi/client.py,sha256=JC-Mw1PdqijLLQZzWcX8Dn8_DGd1j8dKui1-s9rkxTo,14885
+clawifi/errors.py,sha256=7r9l8jaXnmLhl-rVftmMDYuQ1_3IkixQuLzuXSfUScg,1659
+clawifi/mcp_server.py,sha256=v8U9ybLLzM-zLt0hhm5egVV729QT65Hpo_tUCuJt0D8,3233
+clawifi/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+clawifi/testing.py,sha256=gApEtg1hxsBhG_o0PfCcBGAzxt6qGm1UST2MPi1GI0M,2671
+clawifi-0.1.0.dist-info/licenses/LICENSE,sha256=SSB7B93_fwJ_sqzycDbpfLT6gR3B4RMbZSfgESGe8EU,1067
+clawifi-0.1.0.dist-info/METADATA,sha256=0uT4zumL5fhU_S4-urroq9zB8JUoZYQs-WLBnQU_c6E,2199
+clawifi-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+clawifi-0.1.0.dist-info/entry_points.txt,sha256=4KexgBzTL7fkNLviv38_ffSZlYB1nNJP55D6qx10sSA,81
+clawifi-0.1.0.dist-info/top_level.txt,sha256=14GNHtu-AfvixW5yZpzkhClCs4X-Y0L925aFr8CBDuw,8
+clawifi-0.1.0.dist-info/RECORD,,

clawifi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clawifi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clawifi = clawifi.cli:run
+clawifi-mcp = clawifi.mcp_server:run

clawifi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReARC Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clawifi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clawifi