techrecon 0.1.0__py3-none-any.whl

techrecon/__init__.py

@@ -0,0 +1,41 @@
+"""Python client for the TechRecon JA4 + web-crawl technology intelligence API.
+
+    from techrecon import TechRecon
+
+    client = TechRecon(api_key="trk_live_...")
+    result = client.lookup("t13d1516h2_8daaf6152771_b0da82dd1658")
+
+See README.md for a full quickstart and https://api.techrecon.io/v1/docs for
+the interactive API reference.
+"""
+
+from .client import TechRecon
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    PayloadTooLargeError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TechReconError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TechRecon",
+    "TechReconError",
+    "APIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "PayloadTooLargeError",
+    "ServiceUnavailableError",
+    "ConflictError",
+    "__version__",
+]

techrecon/_transport.py

@@ -0,0 +1,51 @@
+"""Stdlib-only HTTP transport used by :class:`techrecon.client.TechRecon`.
+
+The client depends on this module through a small protocol (any object with
+a ``request`` method matching :meth:`Transport.request`), so tests can pass
+a fake/mock transport instead of hitting the network. The default
+:class:`Transport` uses only ``urllib.request`` from the standard library —
+no third-party HTTP library is required to install or use this package.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, NamedTuple, Optional
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+
+
+class HTTPResponse(NamedTuple):
+    """The minimal response shape the client needs from a transport."""
+
+    status_code: int
+    body: bytes
+
+
+class Transport:
+    """Default transport: issues requests with ``urllib.request``."""
+
+    def __init__(self, timeout: float = 30.0) -> None:
+        self.timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Dict[str, str],
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> HTTPResponse:
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+
+        req = urllib_request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib_request.urlopen(req, timeout=self.timeout) as resp:
+                return HTTPResponse(status_code=resp.status, body=resp.read())
+        except urllib_error.HTTPError as exc:
+            # HTTPError is also a valid response with a body; urlopen raises
+            # it instead of returning it for non-2xx statuses.
+            return HTTPResponse(status_code=exc.code, body=exc.read())
+        except urllib_error.URLError as exc:
+            raise ConnectionError(f"failed to reach {url}: {exc.reason}") from exc

techrecon/client.py

@@ -0,0 +1,473 @@
+"""Synchronous client for the TechRecon API.
+
+Generated against docs/openapi.yaml (spec version 1.1.0). Covers the stable,
+public API surface — endpoints marked ``x-internal: true`` in the spec
+(self-serve signup/email-verify, Stripe billing, and the privacy admin
+routes) are intentionally out of scope for this client; they are beta,
+admin-only, or superseded, per the spec's own descriptions.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote, urlencode
+
+from . import models
+from ._transport import Transport
+from .exceptions import TechReconError, error_for_status
+
+DEFAULT_BASE_URL = "https://api.techrecon.io"
+USER_AGENT = "techrecon-python/0.1.0"
+
+
+class TechRecon:
+    """Client for the TechRecon JA4 + web-crawl technology intelligence API.
+
+    Args:
+        api_key: Your TechRecon API key. Sent as the ``X-API-Key`` header on
+            every request (the spec also accepts it as an ``Authorization:
+            Bearer`` token, but this client always uses ``X-API-Key``).
+        base_url: API origin. Defaults to the production server
+            (``https://api.techrecon.io``); pass
+            ``base_url="http://localhost:8080"`` for local development.
+        timeout: Per-request timeout in seconds (default 30).
+        transport: Advanced/testing hook — an object implementing the same
+            ``request(method, url, headers, json_body)`` interface as
+            :class:`techrecon._transport.Transport`. Defaults to a stdlib
+            ``urllib``-based transport; not normally needed by callers.
+
+    Example:
+        >>> client = TechRecon(api_key="trk_live_...")
+        >>> result = client.lookup("t13d1516h2_8daaf6152771_b0da82dd1658")
+        >>> result["ja4_tech_match"]["technology"]
+        'nginx'
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._transport = transport if transport is not None else Transport(timeout=timeout)
+
+    # -- internals -----------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        if query:
+            filtered = {k: v for k, v in query.items() if v is not None}
+            if filtered:
+                url = f"{url}?{urlencode(filtered)}"
+
+        response = self._transport.request(
+            method=method, url=url, headers=self._headers(), json_body=json_body
+        )
+
+        if response.status_code >= 400:
+            message = _extract_error_message(response.body)
+            raise error_for_status(response.status_code, message, response.body.decode("utf-8", "replace"))
+
+        if not response.body:
+            return None
+        try:
+            return json.loads(response.body)
+        except json.JSONDecodeError as exc:
+            raise TechReconError(
+                f"could not decode JSON response from {method} {path}: {exc}"
+            ) from exc
+
+    # -- Health / meta ---------------------------------------------------
+
+    def health(self) -> Dict[str, str]:
+        """``GET /healthz`` — liveness probe. No auth required."""
+        return self._request("GET", "/healthz")
+
+    def readiness(self) -> Dict[str, Any]:
+        """``GET /readyz`` — readiness probe (JA4 DB loaded, circuit breaker closed)."""
+        return self._request("GET", "/readyz")
+
+    # -- JA4 Lookup --------------------------------------------------------
+
+    def lookup(self, ja4_fingerprint: str, ip: Optional[str] = None) -> models.LookupResult:
+        """``POST /v1/lookup`` — look up a single JA4 fingerprint hash."""
+        body: Dict[str, Any] = {"ja4_fingerprint": ja4_fingerprint}
+        if ip is not None:
+            body["ip"] = ip
+        return self._request("POST", "/v1/lookup", json_body=body)
+
+    def bulk_lookup(self, requests: List[Dict[str, str]]) -> models.BulkLookupResponse:
+        """``POST /v1/bulk-lookup`` — look up up to 1,000 JA4 fingerprints.
+
+        Args:
+            requests: Each item is a dict like ``{"ja4_fingerprint": "...",
+                "ip": "..."}`` (``ip`` optional).
+        """
+        return self._request("POST", "/v1/bulk-lookup", json_body={"requests": requests})
+
+    def stats(self) -> models.JA4Stats:
+        """``GET /v1/stats`` — JA4 database hit/miss statistics."""
+        return self._request("GET", "/v1/stats")
+
+    def top_unknown(self) -> Dict[str, Any]:
+        """``GET /v1/unknown`` — top 10 unmatched JA4 fingerprints since startup."""
+        return self._request("GET", "/v1/unknown")
+
+    # -- Domain ------------------------------------------------------------
+
+    def get_domain(self, domain: str) -> models.DomainResponse:
+        """``GET /v1/domain/{domain}`` — technology + enrichment data for one domain."""
+        return self._request("GET", f"/v1/domain/{quote(domain, safe='')}")
+
+    def bulk_domain_lookup(self, domains: List[str]) -> models.BulkDomainResponse:
+        """``POST /v1/domains/bulk`` — detections for up to 100 domains at once."""
+        return self._request("POST", "/v1/domains/bulk", json_body={"domains": domains})
+
+    def get_domain_history(
+        self, domain: str, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> models.DomainHistoryResponse:
+        """``GET /v1/domain/{domain}/history`` — active + removed-technology history."""
+        return self._request(
+            "GET",
+            f"/v1/domain/{quote(domain, safe='')}/history",
+            query={"limit": limit, "cursor": cursor},
+        )
+
+    def get_domain_changes(
+        self,
+        domain: str,
+        since: Optional[str] = None,
+        technology: Optional[str] = None,
+        type: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> models.DomainChangesPage:
+        """``GET /v1/domain/{domain}/changes`` — change timeline for one domain."""
+        return self._request(
+            "GET",
+            f"/v1/domain/{quote(domain, safe='')}/changes",
+            query={
+                "since": since,
+                "technology": technology,
+                "type": type,
+                "limit": limit,
+                "cursor": cursor,
+            },
+        )
+
+    # -- Change feed ---------------------------------------------------------
+
+    def get_changes(
+        self,
+        since: str,
+        technology: Optional[str] = None,
+        type: Optional[str] = None,
+        domain: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> models.ChangesPage:
+        """``GET /v1/changes`` — technology change feed since an RFC3339 timestamp (max 30 days)."""
+        return self._request(
+            "GET",
+            "/v1/changes",
+            query={
+                "since": since,
+                "technology": technology,
+                "type": type,
+                "domain": domain,
+                "limit": limit,
+                "cursor": cursor,
+            },
+        )
+
+    # -- Search --------------------------------------------------------------
+
+    def search(
+        self,
+        technology: Optional[str] = None,
+        category: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        min_confidence: Optional[float] = None,
+        country: Optional[str] = None,
+        hosting_provider: Optional[str] = None,
+        min_rank: Optional[int] = None,
+        max_rank: Optional[int] = None,
+        min_security_score: Optional[int] = None,
+    ) -> models.SearchResponse:
+        """``GET /v1/search`` — search domains by technology or category.
+
+        At least one of ``technology`` or ``category`` is required by the API.
+        """
+        return self._request(
+            "GET",
+            "/v1/search",
+            query={
+                "technology": technology,
+                "category": category,
+                "cursor": cursor,
+                "limit": limit,
+                "min_confidence": min_confidence,
+                "country": country,
+                "hosting_provider": hosting_provider,
+                "min_rank": min_rank,
+                "max_rank": max_rank,
+                "min_security_score": min_security_score,
+            },
+        )
+
+    # -- Technology stats / trends --------------------------------------------
+
+    def get_tech_stats(
+        self, category: Optional[str] = None, limit: Optional[int] = None
+    ) -> models.TechStatsResponse:
+        """``GET /v1/technologies/stats`` — aggregated technology usage counts."""
+        return self._request(
+            "GET", "/v1/technologies/stats", query={"category": category, "limit": limit}
+        )
+
+    def get_tech_trend(self, tech: str, period: Optional[str] = None) -> models.TechTrendResponse:
+        """``GET /v1/technologies/{tech}/trend`` — daily adoption snapshots (e.g. ``period="90d"``)."""
+        return self._request(
+            "GET", f"/v1/technologies/{quote(tech, safe='')}/trend", query={"period": period}
+        )
+
+    # -- Exports ---------------------------------------------------------------
+
+    def create_export(
+        self,
+        technology: str,
+        format: str = "csv",
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> models.CreateExportResponse:
+        """``POST /v1/exports`` — start an async bulk export; poll ``get_export_status``."""
+        body: Dict[str, Any] = {"technology": technology, "format": format}
+        if filters is not None:
+            body["filters"] = filters
+        return self._request("POST", "/v1/exports", json_body=body)
+
+    def get_export_status(self, export_id: str) -> models.ExportJob:
+        """``GET /v1/exports/{id}`` — status/metadata of an export job."""
+        return self._request("GET", f"/v1/exports/{quote(export_id, safe='')}")
+
+    def download_export(self, export_id: str) -> bytes:
+        """``GET /v1/exports/{id}/download`` — download a completed export's raw bytes.
+
+        Returns 409 (raised as :class:`techrecon.exceptions.ConflictError`) if
+        the job hasn't finished yet. The caller is responsible for decoding
+        the bytes as CSV or JSONL per the job's ``format``.
+        """
+        url = f"{self.base_url}/v1/exports/{quote(export_id, safe='')}/download"
+        response = self._transport.request(method="GET", url=url, headers=self._headers())
+        if response.status_code >= 400:
+            message = _extract_error_message(response.body)
+            raise error_for_status(
+                response.status_code, message, response.body.decode("utf-8", "replace")
+            )
+        return response.body
+
+    # -- System monitoring -------------------------------------------------------
+
+    def get_system_stats(self) -> models.SystemStats:
+        """``GET /v1/system/stats`` — PostgreSQL pool metrics, domain/change counters."""
+        return self._request("GET", "/v1/system/stats")
+
+    def get_system_health(self) -> models.HealthResponse:
+        """``GET /v1/system/health`` — crawler + queue + storage connectivity status."""
+        return self._request("GET", "/v1/system/health")
+
+    # -- Ingestion (system identity only) -----------------------------------------
+
+    def ingest_crawl_results(self, results: List[Dict[str, Any]]) -> models.IngestResponse:
+        """``POST /v1/crawl-results`` — ingest a batch of crawl results.
+
+        Restricted to the system identity (the crawler fleet's API key); an
+        ordinary tenant key gets ``403`` (raised as
+        :class:`techrecon.exceptions.ForbiddenError`).
+        """
+        return self._request("POST", "/v1/crawl-results", json_body={"results": results})
+
+    # -- Crawl request queue -------------------------------------------------------
+
+    def create_crawl_request(self, domain: str) -> models.CreateCrawlRequestResponse:
+        """``POST /v1/crawl-requests`` — queue a domain for crawling."""
+        return self._request("POST", "/v1/crawl-requests", json_body={"domain": domain})
+
+    def list_pending_crawl_requests(self) -> models.PendingCrawlRequestsResponse:
+        """``GET /v1/crawl-requests/pending`` — up to 50 pending requests (system identity only)."""
+        return self._request("GET", "/v1/crawl-requests/pending")
+
+    def get_crawl_request_status(self, request_id: int) -> models.CrawlRequest:
+        """``GET /v1/crawl-requests/{id}`` — status of a specific crawl request."""
+        return self._request("GET", f"/v1/crawl-requests/{request_id}")
+
+    # -- Priority crawl -------------------------------------------------------------
+
+    def submit_priority_crawl(
+        self,
+        ips: List[str],
+        consumer: str,
+        priority: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        ttl_days: Optional[int] = None,
+    ) -> models.PriorityCrawlSubmitResponse:
+        """``POST /v1/priority-crawl/submit`` — push up to 50,000 IPs ahead of organic crawl."""
+        body: Dict[str, Any] = {"ips": ips, "consumer": consumer}
+        if priority is not None:
+            body["priority"] = priority
+        if callback_url is not None:
+            body["callback_url"] = callback_url
+        if ttl_days is not None:
+            body["ttl_days"] = ttl_days
+        return self._request("POST", "/v1/priority-crawl/submit", json_body=body)
+
+    def get_priority_crawl_status(self, batch_id: str) -> models.PriorityCrawlStatusResponse:
+        """``GET /v1/priority-crawl/status/{batch_id}`` — live queued/in-progress/completed counts."""
+        return self._request("GET", f"/v1/priority-crawl/status/{quote(batch_id, safe='')}")
+
+    # -- IP-keyed reverse lookup -----------------------------------------------------
+
+    def ip_batch_lookup(
+        self, ips: List[str], include_categories: Optional[List[str]] = None
+    ) -> models.IPBatchResponse:
+        """``POST /v1/ip/batch`` — up to 1,000 IPs; tech stacks observed at each."""
+        body: Dict[str, Any] = {"ips": ips}
+        if include_categories is not None:
+            body["include_categories"] = include_categories
+        return self._request("POST", "/v1/ip/batch", json_body=body)
+
+    # -- Fingerprint pivots ------------------------------------------------------------
+
+    def pivot_ja4(
+        self, ja4_hash: str, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> models.FingerprintPivotPage:
+        """``GET /v1/pivot/ja4/{hash}`` — domains observed presenting a JA4 fingerprint."""
+        return self._request(
+            "GET",
+            f"/v1/pivot/ja4/{quote(ja4_hash, safe='')}",
+            query={"limit": limit, "cursor": cursor},
+        )
+
+    def pivot_jarm(
+        self, jarm_hash: str, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> models.FingerprintPivotPage:
+        """``GET /v1/pivot/jarm/{hash}`` — domains observed presenting a JARM fingerprint."""
+        return self._request(
+            "GET",
+            f"/v1/pivot/jarm/{quote(jarm_hash, safe='')}",
+            query={"limit": limit, "cursor": cursor},
+        )
+
+    def pivot_favicon(
+        self, favicon_hash: str, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> models.FingerprintPivotPage:
+        """``GET /v1/pivot/favicon/{hash}`` — domains observed serving a favicon (mmh3 hash)."""
+        return self._request(
+            "GET",
+            f"/v1/pivot/favicon/{quote(favicon_hash, safe='')}",
+            query={"limit": limit, "cursor": cursor},
+        )
+
+    # -- Alerts -----------------------------------------------------------------------
+
+    def create_alert(
+        self,
+        channel: str,
+        endpoint: str,
+        domain: Optional[str] = None,
+        tech_filter: Optional[str] = None,
+    ) -> models.Alert:
+        """``POST /v1/alerts`` — create a webhook/Slack alert rule.
+
+        ``domain`` defaults to ``"*"`` (all domains) and ``tech_filter``
+        defaults to ``"*"`` (any change) per the spec. Alert quota (50 free
+        tier / 5000 customer tier) is enforced per API key and returns
+        ``429`` (raised as :class:`techrecon.exceptions.RateLimitError`).
+        """
+        body: Dict[str, Any] = {"channel": channel, "endpoint": endpoint}
+        if domain is not None:
+            body["domain"] = domain
+        if tech_filter is not None:
+            body["tech_filter"] = tech_filter
+        return self._request("POST", "/v1/alerts", json_body=body)
+
+    def list_alerts(self) -> models.ListAlertsResponse:
+        """``GET /v1/alerts`` — all alert rules owned by the authenticated account."""
+        return self._request("GET", "/v1/alerts")
+
+    def delete_alert(self, alert_id: str) -> None:
+        """``DELETE /v1/alerts/{id}`` — delete an alert rule you own."""
+        self._request("DELETE", f"/v1/alerts/{quote(alert_id, safe='')}")
+
+    # -- Auth (session) -----------------------------------------------------------------
+
+    def login(self) -> models.LoginResponse:
+        """``POST /v1/auth/login`` — exchange this client's API key for a session cookie.
+
+        Note: this client is API-key-only and does not manage cookies; the
+        ``Set-Cookie: tr_session=...`` response header is not captured here.
+        Provided for completeness/parity with the spec's public surface.
+        """
+        return self._request("POST", "/v1/auth/login", json_body={"api_key": self.api_key})
+
+    def logout(self) -> None:
+        """``POST /v1/auth/logout`` — revoke the current session. Idempotent."""
+        self._request("POST", "/v1/auth/logout")
+
+    # -- Account / API keys / usage -------------------------------------------------------
+
+    def get_account(self) -> models.Account:
+        """``GET /v1/account`` — the caller's own account."""
+        return self._request("GET", "/v1/account")
+
+    def list_api_keys(self) -> models.ListAPIKeysResponse:
+        """``GET /v1/account/keys`` — display-safe metadata for the caller's API keys."""
+        return self._request("GET", "/v1/account/keys")
+
+    def issue_api_key(self, label: Optional[str] = None) -> models.NewAPIKey:
+        """``POST /v1/account/keys`` — mint a new API key; the raw key is returned once."""
+        body: Dict[str, Any] = {}
+        if label is not None:
+            body["label"] = label
+        return self._request("POST", "/v1/account/keys", json_body=body or None)
+
+    def revoke_api_key(self, key_id: str) -> None:
+        """``DELETE /v1/account/keys/{key_id}`` — revoke one of the caller's own API keys."""
+        self._request("DELETE", f"/v1/account/keys/{quote(key_id, safe='')}")
+
+    def get_account_usage(self) -> models.AccountUsage:
+        """``GET /v1/account/usage`` — current UTC-month usage against the plan's quota."""
+        return self._request("GET", "/v1/account/usage")
+
+
+def _extract_error_message(body: bytes) -> str:
+    """Pull the ``error`` field out of an ErrorResponse body; fall back gracefully."""
+    if not body:
+        return "no error detail returned"
+    try:
+        parsed = json.loads(body)
+    except json.JSONDecodeError:
+        return body.decode("utf-8", "replace")
+    if isinstance(parsed, dict) and "error" in parsed:
+        return str(parsed["error"])
+    return body.decode("utf-8", "replace")

techrecon/exceptions.py

@@ -0,0 +1,98 @@
+"""Typed exceptions raised by the TechRecon client.
+
+All API errors share the same JSON body shape defined by
+``components/schemas/ErrorResponse`` in docs/openapi.yaml::
+
+    {"error": "<message>"}
+
+:class:`APIError` carries the parsed message plus the raw HTTP status code
+and response body so callers can inspect anything the typed subclasses don't
+surface directly.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class TechReconError(Exception):
+    """Base class for all errors raised by this package."""
+
+
+class APIError(TechReconError):
+    """Raised when the API responds with a non-2xx status code.
+
+    Attributes:
+        status_code: The HTTP status code returned by the server.
+        message: The ``error`` field from the JSON error body, if present.
+        body: The raw response body text (for debugging when the body isn't
+            valid JSON or doesn't match the expected error shape).
+    """
+
+    def __init__(
+        self, status_code: int, message: str, body: Optional[str] = None
+    ) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class AuthenticationError(APIError):
+    """401 Unauthorized — missing or invalid API key."""
+
+
+class ForbiddenError(APIError):
+    """403 Forbidden — authenticated but not permitted for this endpoint.
+
+    Also raised for account-suspended responses (delinquent billing), which
+    the API returns as 403 on write/quota-bearing endpoints.
+    """
+
+
+class NotFoundError(APIError):
+    """404 Not Found — the requested resource does not exist."""
+
+
+class BadRequestError(APIError):
+    """400 Bad Request — invalid request body or missing parameter."""
+
+
+class RateLimitError(APIError):
+    """429 Too Many Requests — rate limit or quota exceeded.
+
+    The spec uses 429 uniformly for both per-key rate limiting (e.g.
+    ``/v1/ip/batch``) and quota exhaustion (e.g. alert quota on
+    ``POST /v1/alerts``, API-key cap on ``POST /v1/account/keys``). There is
+    no 402 response anywhere in docs/openapi.yaml; 429 is the quota signal.
+    """
+
+
+class PayloadTooLargeError(APIError):
+    """413 Payload Too Large — request body exceeds a size/count limit."""
+
+
+class ServiceUnavailableError(APIError):
+    """503 Service Unavailable — a required storage backend isn't configured."""
+
+
+class ConflictError(APIError):
+    """409 Conflict — e.g. downloading an export that isn't finished yet."""
+
+
+_STATUS_TO_EXCEPTION = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: PayloadTooLargeError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}
+
+
+def error_for_status(status_code: int, message: str, body: Optional[str] = None) -> APIError:
+    """Return the typed exception instance appropriate for an HTTP status code."""
+    exc_cls = _STATUS_TO_EXCEPTION.get(status_code, APIError)
+    return exc_cls(status_code, message, body)