agentdisco 0.1.0__tar.gz

agentdisco-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install dev deps
+        run: pip install -e '.[dev]'
+      - name: Lint (ruff)
+        run: ruff check src tests
+      - name: Typecheck (mypy)
+        run: mypy src
+      - name: Test (pytest)
+        run: pytest -q

agentdisco-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python build artefacts
+/build/
+/dist/
+/*.egg-info/
+/src/*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+
+# Editor / virtualenv
+.venv/
+.env

agentdisco-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starsol Ltd
+
+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.

agentdisco-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: agentdisco
+Version: 0.1.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
+Project-URL: Repository, https://github.com/StarsolLtd/agent-disco
+Author-email: Starsol Ltd <disty@agentdisco.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentdisco,ai-agents,discoverability,llms-txt,openapi,scanner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentdisco — Python client for Agent Disco
+
+[![PyPI version](https://img.shields.io/pypi/v/agentdisco.svg)](https://pypi.org/project/agentdisco/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentdisco.svg)](https://pypi.org/project/agentdisco/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![CI](https://github.com/agentdisco/agentdisco-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/agentdisco/agentdisco-python-sdk/actions/workflows/ci.yml)
+
+Grade any public URL for AI-agent discoverability. Thin Python wrapper
+over the REST API at <https://agentdisco.io/api/v1>.
+
+## Install
+
+```bash
+pip install agentdisco
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+### Submit a scan (anonymous, 10 scans/day/IP)
+
+```python
+from agentdisco import AgentDisco
+
+with AgentDisco() as client:
+    scan = client.submit_scan("https://example.com")
+    print(scan.id, scan.status)
+```
+
+### Poll until complete
+
+```python
+import time
+
+with AgentDisco() as client:
+    scan = client.submit_scan("https://example.com")
+    while scan.status not in {"completed", "failed"}:
+        time.sleep(5)
+        scan = client.get_scan(scan.id)
+
+    print(f"grade: {scan.grade} ({scan.score}/100)")
+```
+
+### Mint a key (raises your quota to 100 scans/day)
+
+```python
+from agentdisco import AgentDisco
+
+# Unauthenticated mint — no prior token needed, rate-limited at
+# 5 keys/hour/IP. Token is shown ONCE; store it.
+key = AgentDisco().mint_key()
+print(key.token)  # ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+authed = AgentDisco(token=key.token)
+authed.submit_scan("https://your-site.example")
+```
+
+### Get summary for a previously-scanned host
+
+```python
+with AgentDisco() as client:
+    site = client.get_website("example.com")
+    print(site.latest_grade, site.latest_score, site.scan_count)
+```
+
+## Higher rate limits
+
+Authenticated-tier keys (500 scans/day/key) need a signed-in account.
+Sign up at <https://agentdisco.io/register>, then mint via the web
+form at <https://agentdisco.io/developers>.
+
+| Tier | Rate limit | How to get |
+|---|---|---|
+| Anonymous (no key) | 10 scans / day / IP | default |
+| Anonymous key | 100 scans / day / key | `mint_key()` above |
+| Authenticated key | 500 scans / day / key | sign in, mint at `/developers` |
+
+## Error handling
+
+```python
+from agentdisco import (
+    AgentDisco,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+)
+
+try:
+    scan = AgentDisco().submit_scan("https://example.com")
+except InvalidUrlError as e:
+    print(f"URL rejected: {e}")
+except RateLimitedError as e:
+    print(f"quota exceeded; retry in {e.retry_after_seconds}s")
+except NotFoundError as e:
+    print(f"not found: {e}")
+```
+
+All SDK-raised exceptions inherit from `AgentDiscoError`, so a single
+broad catch works too:
+
+```python
+from agentdisco import AgentDiscoError
+try:
+    ...
+except AgentDiscoError as e:
+    log.warning("agentdisco failure: %s", e)
+```
+
+Network-layer failures (connection timeout, DNS) leak through as raw
+`httpx.HTTPError` — they're platform issues, not API errors.
+
+## Custom base URL
+
+For self-hosted deployments or local testing:
+
+```python
+AgentDisco(base_url="http://localhost:1977")
+```
+
+## Links
+
+- API docs: <https://agentdisco.io/api/docs>
+- Check catalogue: <https://agentdisco.io/checks>
+- Live scanner: <https://agentdisco.io>
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE). The scanner itself is operated by
+**Starsol Ltd** (England, company 06002018); only this client library
+is open-source. Issues + pull requests welcome.

agentdisco-0.1.0/README.md

@@ -0,0 +1,131 @@
+# agentdisco — Python client for Agent Disco
+
+[![PyPI version](https://img.shields.io/pypi/v/agentdisco.svg)](https://pypi.org/project/agentdisco/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentdisco.svg)](https://pypi.org/project/agentdisco/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![CI](https://github.com/agentdisco/agentdisco-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/agentdisco/agentdisco-python-sdk/actions/workflows/ci.yml)
+
+Grade any public URL for AI-agent discoverability. Thin Python wrapper
+over the REST API at <https://agentdisco.io/api/v1>.
+
+## Install
+
+```bash
+pip install agentdisco
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+### Submit a scan (anonymous, 10 scans/day/IP)
+
+```python
+from agentdisco import AgentDisco
+
+with AgentDisco() as client:
+    scan = client.submit_scan("https://example.com")
+    print(scan.id, scan.status)
+```
+
+### Poll until complete
+
+```python
+import time
+
+with AgentDisco() as client:
+    scan = client.submit_scan("https://example.com")
+    while scan.status not in {"completed", "failed"}:
+        time.sleep(5)
+        scan = client.get_scan(scan.id)
+
+    print(f"grade: {scan.grade} ({scan.score}/100)")
+```
+
+### Mint a key (raises your quota to 100 scans/day)
+
+```python
+from agentdisco import AgentDisco
+
+# Unauthenticated mint — no prior token needed, rate-limited at
+# 5 keys/hour/IP. Token is shown ONCE; store it.
+key = AgentDisco().mint_key()
+print(key.token)  # ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+authed = AgentDisco(token=key.token)
+authed.submit_scan("https://your-site.example")
+```
+
+### Get summary for a previously-scanned host
+
+```python
+with AgentDisco() as client:
+    site = client.get_website("example.com")
+    print(site.latest_grade, site.latest_score, site.scan_count)
+```
+
+## Higher rate limits
+
+Authenticated-tier keys (500 scans/day/key) need a signed-in account.
+Sign up at <https://agentdisco.io/register>, then mint via the web
+form at <https://agentdisco.io/developers>.
+
+| Tier | Rate limit | How to get |
+|---|---|---|
+| Anonymous (no key) | 10 scans / day / IP | default |
+| Anonymous key | 100 scans / day / key | `mint_key()` above |
+| Authenticated key | 500 scans / day / key | sign in, mint at `/developers` |
+
+## Error handling
+
+```python
+from agentdisco import (
+    AgentDisco,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+)
+
+try:
+    scan = AgentDisco().submit_scan("https://example.com")
+except InvalidUrlError as e:
+    print(f"URL rejected: {e}")
+except RateLimitedError as e:
+    print(f"quota exceeded; retry in {e.retry_after_seconds}s")
+except NotFoundError as e:
+    print(f"not found: {e}")
+```
+
+All SDK-raised exceptions inherit from `AgentDiscoError`, so a single
+broad catch works too:
+
+```python
+from agentdisco import AgentDiscoError
+try:
+    ...
+except AgentDiscoError as e:
+    log.warning("agentdisco failure: %s", e)
+```
+
+Network-layer failures (connection timeout, DNS) leak through as raw
+`httpx.HTTPError` — they're platform issues, not API errors.
+
+## Custom base URL
+
+For self-hosted deployments or local testing:
+
+```python
+AgentDisco(base_url="http://localhost:1977")
+```
+
+## Links
+
+- API docs: <https://agentdisco.io/api/docs>
+- Check catalogue: <https://agentdisco.io/checks>
+- Live scanner: <https://agentdisco.io>
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE). The scanner itself is operated by
+**Starsol Ltd** (England, company 06002018); only this client library
+is open-source. Issues + pull requests welcome.

agentdisco-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentdisco"
+version = "0.1.0"
+description = "Python client for the Agent Disco API — grade any public URL for AI-agent discoverability."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    { name = "Starsol Ltd", email = "disty@agentdisco.io" },
+]
+keywords = ["agentdisco", "ai-agents", "discoverability", "llms-txt", "openapi", "scanner"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.25,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-httpx>=0.30",
+    "mypy>=1.8",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://agentdisco.io"
+Documentation = "https://agentdisco.io/api/docs"
+Repository = "https://github.com/StarsolLtd/agent-disco"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentdisco"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+# SDK is small and user-facing — strict typing is worth the cost.

agentdisco-0.1.0/src/agentdisco/__init__.py

@@ -0,0 +1,49 @@
+"""Agent Disco Python client.
+
+Grade any public URL for AI-agent discoverability. Wraps the REST API
+at https://agentdisco.io/api/v1.
+
+Basic usage:
+
+    >>> from agentdisco import AgentDisco
+    >>> client = AgentDisco()                        # anonymous (10 scans/day/IP)
+    >>> scan = client.submit_scan("https://example.com")
+    >>> scan.id                                      # UUID
+    >>> client.get_scan(scan.id).status              # poll: queued/running/completed
+    >>> client.get_website("example.com").grade      # summary: A..F
+
+With a key (100 or 500 scans/day depending on tier):
+
+    >>> key = AgentDisco().mint_key()
+    >>> print(key.token)                             # store this — shown once
+    >>> authed = AgentDisco(token=key.token)
+    >>> authed.submit_scan("https://example.com")
+
+See https://agentdisco.io/api/docs for the full OpenAPI spec.
+"""
+
+from agentdisco.client import AgentDisco
+from agentdisco.exceptions import (
+    AgentDiscoError,
+    ApiError,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+    UnauthorizedError,
+)
+from agentdisco.models import ApiKey, Scan, Website
+
+__all__ = [
+    "AgentDisco",
+    "AgentDiscoError",
+    "ApiError",
+    "ApiKey",
+    "InvalidUrlError",
+    "NotFoundError",
+    "RateLimitedError",
+    "Scan",
+    "UnauthorizedError",
+    "Website",
+]
+
+__version__ = "0.1.0"

agentdisco-0.1.0/src/agentdisco/client.py

@@ -0,0 +1,219 @@
+"""The AgentDisco client.
+
+Thin wrapper over the REST API. Callers construct an `AgentDisco`
+instance (with optional bearer token), then call methods that map
+1:1 to endpoints and return dataclasses.
+
+Scope is deliberately narrow — 4 endpoints today. More surface (report
+diffs, check catalogue listing, scan history) can layer on without
+breaking the existing shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from agentdisco.exceptions import (
+    AgentDiscoError,
+    ApiError,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+    UnauthorizedError,
+)
+from agentdisco.models import ApiKey, Scan, Website
+
+DEFAULT_BASE_URL = "https://agentdisco.io"
+DEFAULT_TIMEOUT = 30.0
+_USER_AGENT = "agentdisco-python/0.1.0"
+
+
+class AgentDisco:
+    """Synchronous Agent Disco client.
+
+    Construct once, reuse across calls — httpx's client is
+    connection-pooled, so per-call construction would reopen TLS on
+    every request.
+
+    An async variant (`AsyncAgentDisco`) can follow when a caller needs
+    one; today the synchronous API is enough for CI runners, CLIs,
+    notebooks.
+
+    Example:
+
+        client = AgentDisco(token="ak_...")
+        scan = client.submit_scan("https://example.com")
+        while scan.status not in {"completed", "failed"}:
+            time.sleep(5)
+            scan = client.get_scan(scan.id)
+        print(scan.grade)
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        """Construct a client.
+
+        `token` is an API key obtained via `mint_key()` or the web
+        flow at `/developers`. Absent → anonymous-tier rate limits.
+
+        `base_url` defaults to prod. Override for self-hosted
+        deployments or tests.
+
+        `transport` is an httpx transport escape-hatch used by the
+        SDK's own tests to pin a `MockTransport`. Real callers
+        shouldn't need it.
+        """
+        self._token = token
+        headers = {
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+        if token is not None:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+        )
+
+    def __enter__(self) -> AgentDisco:
+        return self
+
+    def __exit__(self, *_exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP session. Safe to call twice."""
+        self._http.close()
+
+    # -------------------------------------------------------------
+    # Scans
+    # -------------------------------------------------------------
+
+    def submit_scan(self, url: str) -> Scan:
+        """Queue a scan for `url`. Returns a Scan with status=queued.
+
+        Raises `InvalidUrlError` if the URL fails server-side validation
+        (wrong scheme, private IP, malformed, etc.). Raises
+        `RateLimitedError` when the daily quota is used up — check
+        `.retry_after_seconds` for when to retry.
+        """
+        response = self._http.post("/api/v1/scans", json={"url": url})
+        payload = self._parse(response)
+        return Scan.from_response(payload)
+
+    def get_scan(self, scan_id: str) -> Scan:
+        """Fetch a scan by UUID. Raises `NotFoundError` on unknown id."""
+        response = self._http.get(f"/api/v1/scans/{scan_id}")
+        payload = self._parse(response)
+        return Scan.from_response(payload)
+
+    # -------------------------------------------------------------
+    # Websites
+    # -------------------------------------------------------------
+
+    def get_website(self, host: str) -> Website:
+        """Latest grade + scan count for a host that's been scanned.
+
+        Raises `NotFoundError` if the host has never been scanned (or
+        has been unlisted — the API returns 404 for both, deliberately).
+        """
+        response = self._http.get(f"/api/v1/websites/{host}")
+        payload = self._parse(response)
+        return Website.from_response(payload)
+
+    # -------------------------------------------------------------
+    # API keys
+    # -------------------------------------------------------------
+
+    def mint_key(self) -> ApiKey:
+        """Mint a new anonymous-tier API key.
+
+        The response contains the plaintext token exactly once — store
+        it immediately. The server keeps only a SHA-256 hash and
+        cannot reconstruct the plaintext if you lose it.
+
+        This method works without authentication (no token needed on
+        the calling client). To mint an authenticated-tier key (500
+        scans/day vs 100), sign in via the web flow at /developers.
+
+        Rate-limited at 5 keys/hour/IP; burst-hammering trips
+        `RateLimitedError`.
+        """
+        response = self._http.post("/api/v1/keys")
+        payload = self._parse(response)
+        return ApiKey.from_response(payload)
+
+    # -------------------------------------------------------------
+    # Internal
+    # -------------------------------------------------------------
+
+    def _parse(self, response: httpx.Response) -> dict[str, Any]:
+        """Extract JSON body; raise the right exception on 4xx/5xx.
+
+        Returns the raw dict — each caller wraps in its dataclass.
+        """
+        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)

agentdisco-0.1.0/src/agentdisco/exceptions.py

@@ -0,0 +1,80 @@
+"""Exception hierarchy for the Agent Disco SDK.
+
+All SDK-raised exceptions inherit `AgentDiscoError` so a caller can
+do a single broad catch. More specific subtypes (`NotFoundError`,
+`RateLimitedError`, etc.) let callers react differently to recoverable
+vs unrecoverable failures.
+
+Network-layer errors (connection timeout, DNS failure) leak through
+as raw `httpx` exceptions — we don't wrap them because the failure
+mode is platform, not API. Application-layer errors (4xx/5xx) are
+wrapped into the `ApiError` branch.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AgentDiscoError(Exception):
+    """Root of the SDK exception hierarchy."""
+
+
+class ApiError(AgentDiscoError):
+    """An HTTP response carried a 4xx or 5xx status.
+
+    `status_code` is the HTTP status; `error_code` is the server's
+    `error` field from the JSON body when present (e.g. `invalid_url`,
+    `not_found`); `payload` is the parsed JSON for anything the SDK
+    didn't model.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        error_code: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.payload = payload or {}
+
+
+class InvalidUrlError(ApiError):
+    """HTTP 400 with error=invalid_url — the URL failed server validation."""
+
+
+class UnauthorizedError(ApiError):
+    """HTTP 401 — missing or invalid auth (ops endpoints only)."""
+
+
+class NotFoundError(ApiError):
+    """HTTP 404 — unknown scan id or host."""
+
+
+class RateLimitedError(ApiError):
+    """HTTP 429 — quota exceeded.
+
+    `retry_after_seconds` is parsed from the `Retry-After` response
+    header when present; callers can sleep that long and retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        retry_after_seconds: int | None = None,
+        error_code: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            payload=payload,
+        )
+        self.retry_after_seconds = retry_after_seconds

agentdisco-0.1.0/src/agentdisco/models.py

@@ -0,0 +1,94 @@
+"""Dataclass response models — what the REST endpoints return.
+
+Only the load-bearing fields are modelled; the full JSON payload is
+always available on `raw` for anything the SDK doesn't surface
+directly. That gives us room to grow the API without breaking existing
+callers who rely on specific fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Scan:
+    """A scan (queued, running, or completed).
+
+    `grade` and `score` are `None` while the scan is still in flight;
+    poll `get_scan(id)` until `status == "completed"`.
+    """
+
+    id: str
+    status: str
+    result_url: str
+    grade: str | None
+    score: int | None
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> Scan:
+        return cls(
+            id=str(payload["id"]),
+            status=str(payload["status"]),
+            result_url=str(payload.get("resultUrl") or payload.get("statusUrl") or ""),
+            grade=payload.get("grade"),
+            score=payload.get("score"),
+            raw=payload,
+        )
+
+
+@dataclass(frozen=True)
+class Website:
+    """Summary view of a scanned host — latest grade + activity."""
+
+    host: str
+    latest_grade: str | None
+    latest_score: int | None
+    last_scanned_at: str | None
+    scan_count: int
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> Website:
+        return cls(
+            host=str(payload["host"]),
+            latest_grade=payload.get("latestGrade"),
+            latest_score=payload.get("latestScore"),
+            last_scanned_at=payload.get("lastScannedAt"),
+            scan_count=int(payload.get("scanCount", 0)),
+            raw=payload,
+        )
+
+
+@dataclass(frozen=True)
+class ApiKey:
+    """A freshly-minted API key.
+
+    `token` is the full plaintext — the server returns this exactly
+    ONCE (at mint time) and keeps only a SHA-256 hash. Store the
+    token immediately; losing it means minting a fresh one.
+
+    `token_prefix` is the first 10 chars (`ak_XXXXXXX`) and is safe to
+    display in logs or dashboards; unlike `token`, it can't be used
+    to authenticate.
+    """
+
+    id: str
+    token: str
+    token_prefix: str
+    rate_limit_tier: str
+    created_at: str
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> ApiKey:
+        return cls(
+            id=str(payload["id"]),
+            token=str(payload["token"]),
+            token_prefix=str(payload["tokenPrefix"]),
+            rate_limit_tier=str(payload["rateLimitTier"]),
+            created_at=str(payload["createdAt"]),
+            raw=payload,
+        )

agentdisco-0.1.0/tests/test_client.py

@@ -0,0 +1,296 @@
+"""Tests for the AgentDisco client.
+
+Uses httpx's MockTransport to stub the HTTP layer. Real agentdisco.io
+isn't touched — tests need to be hermetic (CI without network,
+stable output, fast execution).
+
+Pattern: each test builds a `MockTransport(handler)` where `handler`
+is a callable that maps request → response. The client is
+constructed with `transport=transport`, which pipes all HTTP through
+the stub without any real I/O.
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from agentdisco import (
+    AgentDisco,
+    AgentDiscoError,
+    ApiError,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+    UnauthorizedError,
+)
+
+
+def make_transport(handler):
+    """Convenience wrapper: accept a `(request) -> httpx.Response` callable."""
+    return httpx.MockTransport(handler)
+
+
+# ---------------------------------------------------------------
+# Scan submit
+# ---------------------------------------------------------------
+
+
+def test_submit_scan_returns_scan_dataclass():
+    def handler(request):
+        assert request.method == "POST"
+        assert request.url.path == "/api/v1/scans"
+        body = json.loads(request.content)
+        assert body == {"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,
+            },
+        )
+
+    client = AgentDisco(transport=make_transport(handler))
+    scan = client.submit_scan("https://example.com")
+
+    assert scan.id == "019d0000-0000-7000-8000-000000000001"
+    assert scan.status == "queued"
+    assert scan.grade is None
+    assert scan.score is None
+    # The full payload stays reachable for fields the SDK doesn't surface.
+    assert scan.raw["statusUrl"].startswith("/api/v1/scans/")
+
+
+def test_submit_scan_sends_bearer_token_when_configured():
+    received_headers = {}
+
+    def handler(request):
+        received_headers.update(dict(request.headers))
+        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,
+        })
+
+    client = AgentDisco(token="ak_test12345", transport=make_transport(handler))
+    client.submit_scan("https://example.com")
+
+    assert received_headers.get("authorization") == "Bearer ak_test12345"
+
+
+def test_submit_scan_raises_invalid_url_on_400_with_error_code():
+    def handler(_request):
+        return httpx.Response(400, json={
+            "error": "invalid_url",
+            "message": "URL must use http or https scheme.",
+        })
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(InvalidUrlError) as exc:
+        client.submit_scan("file:///etc/passwd")
+
+    assert exc.value.status_code == 400
+    assert exc.value.error_code == "invalid_url"
+    assert "URL must use" in str(exc.value)
+
+
+def test_submit_scan_raises_rate_limited_on_429_with_retry_after():
+    def handler(_request):
+        return httpx.Response(
+            429,
+            json={"error": "rate_limited", "message": "Anonymous scan quota exceeded."},
+            headers={"Retry-After": "3600"},
+        )
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(RateLimitedError) as exc:
+        client.submit_scan("https://example.com")
+
+    assert exc.value.retry_after_seconds == 3600
+    assert exc.value.status_code == 429
+
+
+# ---------------------------------------------------------------
+# Scan polling
+# ---------------------------------------------------------------
+
+
+def test_get_scan_returns_completed_scan_with_grade():
+    def handler(request):
+        assert request.method == "GET"
+        assert request.url.path == "/api/v1/scans/abc"
+        return httpx.Response(200, json={
+            "id": "abc",
+            "status": "completed",
+            "statusUrl": "/api/v1/scans/abc",
+            "resultUrl": "/report/example.com",
+            "grade": "A",
+            "score": 92,
+        })
+
+    client = AgentDisco(transport=make_transport(handler))
+    scan = client.get_scan("abc")
+
+    assert scan.status == "completed"
+    assert scan.grade == "A"
+    assert scan.score == 92
+
+
+def test_get_scan_raises_not_found_on_404():
+    def handler(_request):
+        return httpx.Response(404, json={"error": "not_found", "message": "unknown scan id"})
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(NotFoundError):
+        client.get_scan("does-not-exist")
+
+
+# ---------------------------------------------------------------
+# Website summary
+# ---------------------------------------------------------------
+
+
+def test_get_website_returns_summary():
+    def handler(request):
+        assert request.url.path == "/api/v1/websites/example.com"
+        return httpx.Response(200, json={
+            "host": "example.com",
+            "latestGrade": "B",
+            "latestScore": 72,
+            "lastScannedAt": "2026-04-24T10:00:00+00:00",
+            "scanCount": 4,
+        })
+
+    client = AgentDisco(transport=make_transport(handler))
+    site = client.get_website("example.com")
+
+    assert site.host == "example.com"
+    assert site.latest_grade == "B"
+    assert site.latest_score == 72
+    assert site.scan_count == 4
+
+
+def test_get_website_raises_not_found_for_unscanned_host():
+    def handler(_request):
+        return httpx.Response(404, json={"error": "not_found"})
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(NotFoundError):
+        client.get_website("never-scanned.example")
+
+
+# ---------------------------------------------------------------
+# Mint key
+# ---------------------------------------------------------------
+
+
+def test_mint_key_returns_plaintext_once():
+    """Plaintext is server-side one-shot; SDK just surfaces it faithfully."""
+
+    def handler(request):
+        assert request.method == "POST"
+        assert request.url.path == "/api/v1/keys"
+        return httpx.Response(201, json={
+            "id": "019d0000-0000-7000-8000-000000000002",
+            "token": "ak_abcdefghijklmnopqrstuvwxyz01234567890ABCDEF",
+            "tokenPrefix": "ak_abcdef",
+            "rateLimitTier": "anonymous",
+            "createdAt": "2026-04-24T10:00:00+00:00",
+        })
+
+    client = AgentDisco(transport=make_transport(handler))
+    key = client.mint_key()
+
+    assert key.token.startswith("ak_")
+    assert len(key.token) == 46
+    assert key.token_prefix == "ak_abcdef"
+    assert key.rate_limit_tier == "anonymous"
+
+
+def test_mint_key_rate_limited_after_five_per_hour():
+    def handler(_request):
+        return httpx.Response(429, json={"error": "rate_limited"}, headers={"Retry-After": "1800"})
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(RateLimitedError) as exc:
+        client.mint_key()
+
+    assert exc.value.retry_after_seconds == 1800
+
+
+# ---------------------------------------------------------------
+# Error handling — generic paths
+# ---------------------------------------------------------------
+
+
+def test_500_raises_generic_api_error():
+    def handler(_request):
+        return httpx.Response(500, text="Internal Server Error")
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(ApiError) as exc:
+        client.submit_scan("https://example.com")
+
+    # 500 is not one of the mapped specific subtypes; generic ApiError.
+    specific = (InvalidUrlError, NotFoundError, RateLimitedError, UnauthorizedError)
+    assert not isinstance(exc.value, specific)
+    assert exc.value.status_code == 500
+
+
+def test_401_raises_unauthorized_error():
+    def handler(_request):
+        return httpx.Response(
+            401,
+            json={"error": "unauthorized", "message": "HTTP Basic auth required."},
+            headers={"WWW-Authenticate": "Basic realm=\"ops\""},
+        )
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(UnauthorizedError):
+        client.get_website("example.com")
+
+
+def test_non_json_body_on_success_raises_agentdisco_error():
+    def handler(_request):
+        return httpx.Response(200, text="not json at all", headers={"Content-Type": "text/plain"})
+
+    client = AgentDisco(transport=make_transport(handler))
+
+    with pytest.raises(AgentDiscoError):
+        client.get_website("example.com")
+
+
+def test_context_manager_closes_session():
+    handler_calls = 0
+
+    def handler(_request):
+        nonlocal handler_calls
+        handler_calls += 1
+        return httpx.Response(200, json={
+            "host": "x.com",
+            "latestGrade": "B",
+            "latestScore": 80,
+            "lastScannedAt": "2026-04-24T00:00:00+00:00",
+            "scanCount": 1,
+        })
+
+    with AgentDisco(transport=make_transport(handler)) as client:
+        client.get_website("x.com")
+
+    assert handler_calls == 1