agentdisco 0.2.0__tar.gz → 0.3.0__tar.gz

{agentdisco-0.2.0 → agentdisco-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdisco
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python client for the Agent Disco API — grade any public URL for AI-agent discoverability.
 Project-URL: Homepage, https://agentdisco.io
 Project-URL: Documentation, https://agentdisco.io/api/docs
@@ -93,6 +93,39 @@ with AgentDisco() as client:
     print(site.latest_grade, site.latest_score, site.scan_count)
 ```
 
+### Scan history + re-scan
+
+```python
+with AgentDisco() as client:
+    # Paginated history, most-recent first (per_page capped at 50).
+    for scan in client.get_scans("example.com", per_page=20):
+        print(scan.grade, scan.score)
+
+    # Queue a fresh scan of a known host (counts against your scan quota).
+    fresh = client.rescan("example.com")
+    print(fresh.id, fresh.status)
+```
+
+### Async client
+
+`AsyncAgentDisco` mirrors `AgentDisco` method-for-method over `asyncio`:
+
+```python
+import asyncio
+from agentdisco import AsyncAgentDisco
+
+async def main():
+    async with AsyncAgentDisco(token="ak_...") as client:
+        scan = await client.submit_scan("https://example.com")
+        history = await client.get_scans("example.com")
+        print(scan.id, len(history))
+
+asyncio.run(main())
+```
+
+Same arguments, return types, and exceptions as the sync client —
+including `await AsyncAgentDisco.from_colony_token(...)`.
+
 ### Sign in with the Colony (agents)
 
 Autonomous agents on [The Colony](https://thecolony.cc) can authenticate

{agentdisco-0.2.0 → agentdisco-0.3.0}/README.md

@@ -64,6 +64,39 @@ with AgentDisco() as client:
     print(site.latest_grade, site.latest_score, site.scan_count)
 ```
 
+### Scan history + re-scan
+
+```python
+with AgentDisco() as client:
+    # Paginated history, most-recent first (per_page capped at 50).
+    for scan in client.get_scans("example.com", per_page=20):
+        print(scan.grade, scan.score)
+
+    # Queue a fresh scan of a known host (counts against your scan quota).
+    fresh = client.rescan("example.com")
+    print(fresh.id, fresh.status)
+```
+
+### Async client
+
+`AsyncAgentDisco` mirrors `AgentDisco` method-for-method over `asyncio`:
+
+```python
+import asyncio
+from agentdisco import AsyncAgentDisco
+
+async def main():
+    async with AsyncAgentDisco(token="ak_...") as client:
+        scan = await client.submit_scan("https://example.com")
+        history = await client.get_scans("example.com")
+        print(scan.id, len(history))
+
+asyncio.run(main())
+```
+
+Same arguments, return types, and exceptions as the sync client —
+including `await AsyncAgentDisco.from_colony_token(...)`.
+
 ### Sign in with the Colony (agents)
 
 Autonomous agents on [The Colony](https://thecolony.cc) can authenticate

{agentdisco-0.2.0 → agentdisco-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentdisco"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python client for the Agent Disco API — grade any public URL for AI-agent discoverability."
 readme = "README.md"
 license = "MIT"

{agentdisco-0.2.0 → agentdisco-0.3.0}/src/agentdisco/__init__.py

@@ -27,6 +27,7 @@ Colony agents — sign in with your Colony token (no browser, RFC 8693):
 See https://agentdisco.io/api/docs for the full OpenAPI spec.
 """
 
+from agentdisco.async_client import AsyncAgentDisco
 from agentdisco.client import AgentDisco
 from agentdisco.exceptions import (
     AgentDiscoError,
@@ -43,6 +44,7 @@ __all__ = [
     "AgentDiscoError",
     "ApiError",
     "ApiKey",
+    "AsyncAgentDisco",
     "InvalidUrlError",
     "NotFoundError",
     "RateLimitedError",
@@ -51,4 +53,4 @@ __all__ = [
     "Website",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

agentdisco-0.3.0/src/agentdisco/_response.py

@@ -0,0 +1,78 @@
+"""Shared HTTP response handling for the sync + async clients.
+
+`parse_json` extracts the JSON body on success and maps 4xx/5xx onto the
+typed exception hierarchy. It's pure (no I/O, no awaiting) — httpx has
+already read the body by the time a non-streaming response is returned, on
+both the sync and async paths — so a single implementation serves both
+clients.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from agentdisco.exceptions import (
+    AgentDiscoError,
+    ApiError,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+    UnauthorizedError,
+)
+
+
+def parse_json(response: httpx.Response) -> dict[str, Any]:
+    """Return the JSON object body, or raise the right typed exception."""
+    if 200 <= response.status_code < 300:
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise AgentDiscoError(
+                f"server returned {response.status_code} with non-JSON body",
+            ) from exc
+        if not isinstance(body, dict):
+            raise AgentDiscoError(
+                f"server returned {response.status_code} with non-object JSON",
+            )
+        return body
+
+    payload: dict[str, Any] = {}
+    try:
+        parsed = response.json()
+        if isinstance(parsed, dict):
+            payload = parsed
+    except ValueError:
+        pass
+
+    message = str(payload.get("message") or payload.get("error") or response.text or "").strip()
+    if message == "":
+        message = f"HTTP {response.status_code} from Agent Disco API"
+    error_code = payload.get("error") if isinstance(payload.get("error"), str) else None
+
+    status = response.status_code
+    kwargs: dict[str, Any] = {
+        "status_code": status,
+        "error_code": error_code,
+        "payload": payload,
+    }
+
+    if status == 400 and error_code == "invalid_url":
+        raise InvalidUrlError(message, **kwargs)
+    if status == 401:
+        raise UnauthorizedError(message, **kwargs)
+    if status == 404:
+        raise NotFoundError(message, **kwargs)
+    if status == 429:
+        retry_after = response.headers.get("Retry-After")
+        retry_after_seconds = (
+            int(retry_after) if retry_after and retry_after.isdigit() else None
+        )
+        raise RateLimitedError(
+            message,
+            retry_after_seconds=retry_after_seconds,
+            **kwargs,
+        )
+
+    raise ApiError(message, **kwargs)

agentdisco-0.3.0/src/agentdisco/async_client.py

@@ -0,0 +1,140 @@
+"""The asynchronous Agent Disco client.
+
+`AsyncAgentDisco` mirrors the synchronous `AgentDisco` method-for-method
+over httpx's async client — same arguments, same return dataclasses, same
+typed exceptions (shared via `agentdisco._response.parse_json`). Use it
+from `asyncio` code or any concurrent runner.
+
+    import asyncio
+    from agentdisco import AsyncAgentDisco
+
+    async def main():
+        async with AsyncAgentDisco(token="ak_...") as client:
+            scan = await client.submit_scan("https://example.com")
+            print(scan.id, scan.status)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from agentdisco._response import parse_json
+from agentdisco.client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from agentdisco.models import ApiKey, Scan, Website
+
+_USER_AGENT = "agentdisco-python-async/0.3.0"
+
+
+class AsyncAgentDisco:
+    """Asynchronous Agent Disco client. The async twin of `AgentDisco`.
+
+    Construct once and reuse — httpx's async client is connection-pooled.
+    Close it with `await client.aclose()`, or use it as an async context
+    manager (`async with AsyncAgentDisco() as client: ...`).
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Construct a client. See `AgentDisco.__init__` for the arguments —
+        they're identical (`transport` here is an async transport, used by
+        the SDK's own tests to pin a `MockTransport`).
+        """
+        self._token = token
+        headers = {
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+        if token is not None:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> AsyncAgentDisco:
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP session. Safe to call twice."""
+        await self._http.aclose()
+
+    # -- Scans ----------------------------------------------------------
+
+    async def submit_scan(self, url: str) -> Scan:
+        """Queue a scan for `url`. See `AgentDisco.submit_scan`."""
+        response = await self._http.post("/api/v1/scans", json={"url": url})
+        return Scan.from_response(parse_json(response))
+
+    async def get_scan(self, scan_id: str) -> Scan:
+        """Fetch a scan by UUID. See `AgentDisco.get_scan`."""
+        response = await self._http.get(f"/api/v1/scans/{scan_id}")
+        return Scan.from_response(parse_json(response))
+
+    # -- Websites -------------------------------------------------------
+
+    async def get_website(self, host: str) -> Website:
+        """Latest grade for a scanned host. See `AgentDisco.get_website`."""
+        response = await self._http.get(f"/api/v1/websites/{host}")
+        return Website.from_response(parse_json(response))
+
+    async def get_scans(self, host: str, *, page: int = 1, per_page: int = 10) -> list[Scan]:
+        """A page of a host's completed-scan history. See `AgentDisco.get_scans`."""
+        response = await self._http.get(
+            f"/api/v1/websites/{host}/scans",
+            params={"page": page, "perPage": per_page},
+        )
+        payload = parse_json(response)
+        return [Scan.from_response(s) for s in payload.get("scans", [])]
+
+    async def rescan(self, host: str) -> Scan:
+        """Queue a fresh scan of a known host. See `AgentDisco.rescan`."""
+        response = await self._http.post(f"/api/v1/websites/{host}/rescan")
+        return Scan.from_response(parse_json(response))
+
+    # -- API keys -------------------------------------------------------
+
+    async def mint_key(self) -> ApiKey:
+        """Mint an anonymous-tier API key. See `AgentDisco.mint_key`."""
+        response = await self._http.post("/api/v1/keys")
+        return ApiKey.from_response(parse_json(response))
+
+    # -- Colony agent login (RFC 8693) ----------------------------------
+
+    async def exchange_colony_token(self, subject_token: str) -> ApiKey:
+        """Exchange a Colony agent token for an API key. See
+        `AgentDisco.exchange_colony_token`.
+        """
+        response = await self._http.post(
+            "/api/v1/auth/colony/agent",
+            json={"subject_token": subject_token},
+        )
+        return ApiKey.from_response(parse_json(response))
+
+    @classmethod
+    async def from_colony_token(
+        cls,
+        subject_token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> AsyncAgentDisco:
+        """Build an authenticated client from a Colony agent token. See
+        `AgentDisco.from_colony_token`.
+        """
+        async with cls(base_url=base_url, timeout=timeout, transport=transport) as anon:
+            key = await anon.exchange_colony_token(subject_token)
+        return cls(token=key.token, base_url=base_url, timeout=timeout, transport=transport)

{agentdisco-0.2.0 → agentdisco-0.3.0}/src/agentdisco/client.py

@@ -15,19 +15,12 @@ from typing import Any
 
 import httpx
 
-from agentdisco.exceptions import (
-    AgentDiscoError,
-    ApiError,
-    InvalidUrlError,
-    NotFoundError,
-    RateLimitedError,
-    UnauthorizedError,
-)
+from agentdisco._response import parse_json
 from agentdisco.models import ApiKey, Scan, Website
 
 DEFAULT_BASE_URL = "https://agentdisco.io"
 DEFAULT_TIMEOUT = 30.0
-_USER_AGENT = "agentdisco-python/0.2.0"
+_USER_AGENT = "agentdisco-python/0.3.0"
 
 
 class AgentDisco:
@@ -131,6 +124,31 @@ class AgentDisco:
         payload = self._parse(response)
         return Website.from_response(payload)
 
+    def get_scans(self, host: str, *, page: int = 1, per_page: int = 10) -> list[Scan]:
+        """A page of a host's completed-scan history, most-recent first.
+
+        `per_page` is capped server-side at 50. Track a grade trend by
+        paging through. Raises `NotFoundError` for an unknown/unlisted host.
+        """
+        response = self._http.get(
+            f"/api/v1/websites/{host}/scans",
+            params={"page": page, "perPage": per_page},
+        )
+        payload = self._parse(response)
+        return [Scan.from_response(s) for s in payload.get("scans", [])]
+
+    def rescan(self, host: str) -> Scan:
+        """Queue a fresh scan of an already-known host. Returns the queued
+        Scan (poll `get_scan(scan.id)` until completed).
+
+        Counts against your scan rate limit like `submit_scan` — present a
+        token for the higher per-key quota. Raises `NotFoundError` for an
+        unknown/unlisted host, `RateLimitedError` when the quota is spent.
+        """
+        response = self._http.post(f"/api/v1/websites/{host}/rescan")
+        payload = self._parse(response)
+        return Scan.from_response(payload)
+
     # -------------------------------------------------------------
     # API keys
     # -------------------------------------------------------------
@@ -209,62 +227,8 @@ class AgentDisco:
     # -------------------------------------------------------------
 
     def _parse(self, response: httpx.Response) -> dict[str, Any]:
-        """Extract JSON body; raise the right exception on 4xx/5xx.
+        """Extract the JSON body; raise the right exception on 4xx/5xx.
 
-        Returns the raw dict — each caller wraps in its dataclass.
+        Shared with the async client via {@link parse_json}.
         """
-        if 200 <= response.status_code < 300:
-            try:
-                body = response.json()
-            except ValueError as exc:
-                raise AgentDiscoError(
-                    f"server returned {response.status_code} with non-JSON body",
-                ) from exc
-            if not isinstance(body, dict):
-                raise AgentDiscoError(
-                    f"server returned {response.status_code} with non-object JSON",
-                )
-            return body
-
-        # Best-effort body parse so the error carries the server's
-        # error code + message; don't fail the wrap if the body isn't
-        # JSON (it usually is for /api/v1 but some 5xx paths return
-        # plain text).
-        payload: dict[str, Any] = {}
-        try:
-            parsed = response.json()
-            if isinstance(parsed, dict):
-                payload = parsed
-        except ValueError:
-            pass
-
-        message = str(payload.get("message") or payload.get("error") or response.text or "").strip()
-        if message == "":
-            message = f"HTTP {response.status_code} from Agent Disco API"
-        error_code = payload.get("error") if isinstance(payload.get("error"), str) else None
-
-        status = response.status_code
-        kwargs: dict[str, Any] = {
-            "status_code": status,
-            "error_code": error_code,
-            "payload": payload,
-        }
-
-        if status == 400 and error_code == "invalid_url":
-            raise InvalidUrlError(message, **kwargs)
-        if status == 401:
-            raise UnauthorizedError(message, **kwargs)
-        if status == 404:
-            raise NotFoundError(message, **kwargs)
-        if status == 429:
-            retry_after = response.headers.get("Retry-After")
-            retry_after_seconds = (
-                int(retry_after) if retry_after and retry_after.isdigit() else None
-            )
-            raise RateLimitedError(
-                message,
-                retry_after_seconds=retry_after_seconds,
-                **kwargs,
-            )
-
-        raise ApiError(message, **kwargs)
+        return parse_json(response)

agentdisco-0.3.0/tests/test_async_client.py

@@ -0,0 +1,127 @@
+"""Async client tests.
+
+Same MockTransport approach as the sync suite (the handler is a plain
+sync callable; httpx's MockTransport adapts it for the async path), driven
+through `asyncio.run` so no pytest-asyncio plugin is needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+
+from agentdisco import AsyncAgentDisco, NotFoundError
+
+
+def make_transport(handler):
+    return httpx.MockTransport(handler)
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def test_async_submit_scan_returns_scan():
+    def handler(request):
+        assert request.method == "POST"
+        assert request.url.path == "/api/v1/scans"
+        assert json.loads(request.content) == {"url": "https://example.com"}
+        return httpx.Response(202, json={
+            "id": "019d0000-0000-7000-8000-000000000001",
+            "status": "queued",
+            "statusUrl": "/api/v1/scans/019d0000-0000-7000-8000-000000000001",
+            "resultUrl": "/report/example.com",
+            "grade": None,
+            "score": None,
+        })
+
+    async def go():
+        async with AsyncAgentDisco(transport=make_transport(handler)) as client:
+            return await client.submit_scan("https://example.com")
+
+    scan = run(go())
+    assert scan.status == "queued"
+
+
+def test_async_get_scans_returns_history():
+    def handler(request):
+        assert request.url.path == "/api/v1/websites/example.com/scans"
+        return httpx.Response(200, json={
+            "host": "example.com",
+            "scans": [
+                {
+                    "id": "1", "status": "completed", "grade": "A", "score": 90,
+                    "completedAt": "2026-06-25T10:00:00+00:00", "statusUrl": "/api/v1/scans/1",
+                },
+                {
+                    "id": "2", "status": "completed", "grade": "B", "score": 70,
+                    "completedAt": "2026-06-25T09:00:00+00:00", "statusUrl": "/api/v1/scans/2",
+                },
+            ],
+            "totalCount": 2, "page": 1, "perPage": 10,
+        })
+
+    async def go():
+        async with AsyncAgentDisco(transport=make_transport(handler)) as client:
+            return await client.get_scans("example.com")
+
+    scans = run(go())
+    assert [s.grade for s in scans] == ["A", "B"]
+
+
+def test_async_rescan_returns_queued_scan():
+    def handler(request):
+        assert request.method == "POST"
+        assert request.url.path == "/api/v1/websites/example.com/rescan"
+        return httpx.Response(202, json={
+            "id": "r", "status": "queued", "statusUrl": "/api/v1/scans/r",
+            "resultUrl": "/report/example.com", "grade": None, "score": None,
+        })
+
+    async def go():
+        async with AsyncAgentDisco(transport=make_transport(handler)) as client:
+            return await client.rescan("example.com")
+
+    assert run(go()).status == "queued"
+
+
+def test_async_from_colony_token_returns_authed_client():
+    minted = "ak_asyncmintedfromcolonytokenabcdefghijklmno"
+
+    def handler(request):
+        if request.url.path == "/api/v1/auth/colony/agent":
+            return httpx.Response(201, json={
+                "id": "k", "token": minted, "tokenPrefix": "ak_async",
+                "rateLimitTier": "authenticated", "createdAt": "2026-06-25T10:00:00+00:00",
+            })
+        assert request.headers.get("Authorization") == f"Bearer {minted}"
+        return httpx.Response(202, json={
+            "id": "s", "status": "queued", "statusUrl": "/api/v1/scans/s",
+            "resultUrl": "/report/example.com", "grade": None, "score": None,
+        })
+
+    async def go():
+        client = await AsyncAgentDisco.from_colony_token(
+            "colony-jwt", transport=make_transport(handler),
+        )
+        try:
+            return await client.submit_scan("https://example.com")
+        finally:
+            await client.aclose()
+
+    assert run(go()).status == "queued"
+
+
+def test_async_404_raises_not_found():
+    def handler(_request):
+        return httpx.Response(404, json={"error": "not_found", "message": "nope"})
+
+    async def go():
+        async with AsyncAgentDisco(transport=make_transport(handler)) as client:
+            await client.get_website("nobody.example")
+
+    with pytest.raises(NotFoundError):
+        run(go())

{agentdisco-0.2.0 → agentdisco-0.3.0}/tests/test_client.py

@@ -232,6 +232,55 @@ def test_mint_key_rate_limited_after_five_per_hour():
     assert exc.value.retry_after_seconds == 1800
 
 
+# ---------------------------------------------------------------
+# Scan history + re-scan
+# ---------------------------------------------------------------
+
+
+def test_get_scans_returns_history_most_recent_first():
+    def handler(request):
+        assert request.url.path == "/api/v1/websites/example.com/scans"
+        assert request.url.params.get("perPage") == "5"
+        return httpx.Response(200, json={
+            "host": "example.com",
+            "scans": [
+                {
+                    "id": "1", "status": "completed", "grade": "A", "score": 90,
+                    "completedAt": "2026-06-25T10:00:00+00:00", "statusUrl": "/api/v1/scans/1",
+                },
+                {
+                    "id": "2", "status": "completed", "grade": "B", "score": 70,
+                    "completedAt": "2026-06-25T09:00:00+00:00", "statusUrl": "/api/v1/scans/2",
+                },
+            ],
+            "totalCount": 2, "page": 1, "perPage": 5,
+        })
+
+    scans = AgentDisco(transport=make_transport(handler)).get_scans("example.com", per_page=5)
+
+    assert [s.grade for s in scans] == ["A", "B"]
+
+
+def test_rescan_returns_queued_scan():
+    def handler(request):
+        assert request.method == "POST"
+        assert request.url.path == "/api/v1/websites/example.com/rescan"
+        return httpx.Response(202, json={
+            "id": "r", "status": "queued", "statusUrl": "/api/v1/scans/r",
+            "resultUrl": "/report/example.com", "grade": None, "score": None,
+        })
+
+    assert AgentDisco(transport=make_transport(handler)).rescan("example.com").status == "queued"
+
+
+def test_get_scans_unknown_host_raises_not_found():
+    def handler(_request):
+        return httpx.Response(404, json={"error": "not_found", "message": "nope"})
+
+    with pytest.raises(NotFoundError):
+        AgentDisco(transport=make_transport(handler)).get_scans("nobody.example")
+
+
 # ---------------------------------------------------------------
 # Colony agent login (token exchange)
 # ---------------------------------------------------------------
@@ -288,7 +337,9 @@ def test_from_colony_token_returns_client_authed_with_minted_key():
 
 def test_exchange_colony_token_rejects_non_agent_with_401():
     def handler(_request):
-        return httpx.Response(401, json={"error": "invalid_token", "message": "Colony token exchange failed."})
+        return httpx.Response(
+            401, json={"error": "invalid_token", "message": "Colony token exchange failed."},
+        )
 
     with pytest.raises(UnauthorizedError):
         AgentDisco(transport=make_transport(handler)).exchange_colony_token("a-human-token")