web-auditor 0.1.0__py3-none-any.whl

web_auditor/__init__.py

@@ -0,0 +1,42 @@
+"""Official Python client for the Web Auditor public API."""
+
+from . import webhooks
+from ._client import Page, WebAuditor
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    PollTimeoutError,
+    RateLimitError,
+    WebAuditorError,
+)
+from ._object import ApiObject
+from ._resources import NOT_GIVEN
+from ._version import __version__
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "ApiObject",
+    "AuthenticationError",
+    "ConflictError",
+    "InsufficientCreditsError",
+    "InvalidRequestError",
+    "NOT_GIVEN",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "PollTimeoutError",
+    "RateLimitError",
+    "WebAuditor",
+    "WebAuditorError",
+    "__version__",
+    "webhooks",
+]

web_auditor/_client.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import os
+import platform
+import random
+import time
+import uuid
+from collections.abc import Iterator
+from typing import Any, Callable
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import APIConnectionError, APITimeoutError, WebAuditorError, error_for_status
+from ._object import ApiObject
+from ._operations import OPERATIONS
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.web-auditor.enfection.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+# Retry-After longer than this (e.g. a site's hourly audit limit) is returned to the caller instead of slept on.
+MAX_RETRY_AFTER_SECONDS = 60
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+class WebAuditor:
+    """Client for the Web Auditor public API.
+
+    >>> client = WebAuditor(api_key="wa_test_…")  # or set WEB_AUDITOR_API_KEY
+    >>> audit = client.url_audits.create(url="https://example.com/pricing")
+    >>> audit = client.url_audits.wait(audit.id)
+    >>> audit.report.score
+
+    Failed requests (network errors, 429 and 5xx) are retried `max_retries` times with backoff, honouring
+    `Retry-After`. Every POST carries an `Idempotency-Key`, so a retry never starts a second audit.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+        _sleep: Callable[[float], None] = time.sleep,
+        _monotonic: Callable[[], float] = time.monotonic,
+    ):
+        from ._resources import (  # noqa: PLC0415 — resources import this module
+            BrandAudits,
+            Checks,
+            Monitors,
+            ReportShares,
+            SiteAudits,
+            Status,
+            UrlAuditBatches,
+            UrlAudits,
+            Usage,
+            WebhookDeliveries,
+            WebhookEndpoints,
+        )
+
+        api_key = api_key or os.environ.get("WEB_AUDITOR_API_KEY")
+        if not api_key:
+            raise WebAuditorError("No API key: pass api_key=... or set WEB_AUDITOR_API_KEY.")
+        self.api_key = api_key
+        self.base_url = (base_url or os.environ.get("WEB_AUDITOR_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._sleep = _sleep
+        self._monotonic = _monotonic
+        self._user_agent = f"web-auditor-python/{__version__} python/{platform.python_version()}"
+
+        self.status = Status(self)
+        self.usage = Usage(self)
+        self.checks = Checks(self)
+        self.url_audits = UrlAudits(self)
+        self.report_shares = ReportShares(self)
+        self.url_audit_batches = UrlAuditBatches(self)
+        self.site_audits = SiteAudits(self)
+        self.brand_audits = BrandAudits(self)
+        self.monitors = Monitors(self)
+        self.webhook_endpoints = WebhookEndpoints(self)
+        self.webhook_deliveries = WebhookDeliveries(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> WebAuditor:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    # ── Transport ────────────────────────────────────────────
+
+    def request(
+        self,
+        operation_id: str,
+        path_params: dict[str, str] | None = None,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        accept: str = "application/json",
+        raw: bool = False,
+        timeout: float | None = None,
+        retry_timeouts: bool = True,
+    ) -> Any:
+        """Call one operation by its operationId. Returns an ApiObject, bytes (`raw=True`) or None (204)."""
+        method, template = OPERATIONS[operation_id]
+        path = template.format(**{name: quote(str(value), safe="") for name, value in (path_params or {}).items()})
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": self._user_agent,
+            "Accept": accept,
+        }
+        if method == "POST":
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        query = {key: value for key, value in (params or {}).items() if value is not None}
+
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    method,
+                    self.base_url + path,
+                    params=query or None,
+                    json=json,
+                    headers=headers,
+                    **({"timeout": timeout} if timeout is not None else {}),
+                )
+            except httpx.TimeoutException as exc:
+                if retry_timeouts and attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError(f"Request to {path} timed out.") from exc
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Couldn't reach the Web Auditor API: {exc}") from exc
+
+            if response.status_code < 400:
+                if response.status_code == 204:
+                    return None
+                return response.content if raw else ApiObject(response.json())
+
+            retry_after = _retry_after(response)
+            retryable = response.status_code in RETRY_STATUSES and (
+                retry_after is None or retry_after <= MAX_RETRY_AFTER_SECONDS
+            )
+            if retryable and attempt < self.max_retries:
+                self._sleep(retry_after if retry_after is not None else _backoff(attempt))
+                attempt += 1
+                continue
+            raise _error_from(response, retry_after)
+
+
+class Page(ApiObject):
+    """One page of a list (`data`, `has_more`). `auto_paging_iter()` walks every following page too."""
+
+    def __init__(self, data: dict, *, fetch: Callable[[str], Page]):
+        super().__init__(data)
+        object.__setattr__(self, "_fetch", fetch)
+
+    def auto_paging_iter(self) -> Iterator[ApiObject]:
+        page: Page | None = self
+        while page is not None:
+            yield from page.data
+            cursor = _cursor(page.get("next")) if page.get("has_more") else None
+            page = page._fetch(cursor) if cursor else None
+
+
+def _cursor(next_link: str | None) -> str | None:
+    # The link names the host the API saw; only its cursor matters, so pages follow this client's base_url.
+    return httpx.URL(next_link).params.get("cursor") if next_link else None
+
+
+def _backoff(attempt: int) -> float:
+    return min(0.5 * 2**attempt, 8.0) * random.uniform(0.75, 1.0)
+
+
+def _retry_after(response: httpx.Response) -> int | None:
+    value = response.headers.get("Retry-After")
+    try:
+        return max(0, int(value)) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _error_from(response: httpx.Response, retry_after: int | None) -> WebAuditorError:
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    envelope = body.get("error") if isinstance(body, dict) and isinstance(body.get("error"), dict) else {}
+    message = envelope.get("message") or f"The API returned HTTP {response.status_code}."
+    return error_for_status(
+        response.status_code,
+        message,
+        retry_after=retry_after,
+        code=envelope.get("code"),
+        type=envelope.get("type"),
+        param=envelope.get("param"),
+        request_id=envelope.get("request_id") or response.headers.get("X-Request-Id"),
+        doc_url=envelope.get("doc_url"),
+        body=body,
+    )

web_auditor/_errors.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class WebAuditorError(Exception):
+    """Base class for every error the SDK raises.
+
+    API errors carry the fields of the error envelope: `code` (branch on this), `type`, `param`, `request_id`
+    (quote it to support) and `doc_url`, plus the HTTP `status`.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        type: str | None = None,
+        param: str | None = None,
+        request_id: str | None = None,
+        doc_url: str | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.type = type
+        self.param = param
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.body = body
+
+
+class APIConnectionError(WebAuditorError):
+    """The API couldn't be reached (DNS, connection refused, TLS...). Retried automatically first."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out. Retried automatically first."""
+
+
+class APIError(WebAuditorError):
+    """The API failed on its side (5xx). Retried automatically first."""
+
+
+class InvalidRequestError(WebAuditorError):
+    """The request was rejected (400, 409, 422...). `param` names the offending field when there is one."""
+
+
+class ConflictError(InvalidRequestError):
+    """409: the resource isn't in a state that allows this, e.g. `audit_not_cancelable`, `delivery_pending`."""
+
+
+class AuthenticationError(WebAuditorError):
+    """401: the API key is missing, malformed, revoked or expired."""
+
+
+class PermissionDeniedError(WebAuditorError):
+    """403: a missing scope, a disallowed IP, a feature outside the plan, or an inactive account."""
+
+
+class NotFoundError(WebAuditorError):
+    """404: no such object for this key's account and mode (test keys can't see live objects)."""
+
+
+class InsufficientCreditsError(WebAuditorError):
+    """402 `credits_exhausted`: not enough credits left this period."""
+
+
+class RateLimitError(WebAuditorError):
+    """429: `rate_limited`, `host_rate_limit` or `concurrent_audit_limit`. `retry_after` is in seconds when known."""
+
+    def __init__(self, message: str, *, retry_after: int | None = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class PollTimeoutError(WebAuditorError, TimeoutError):
+    """`wait()` gave up before the object finished. `last` is the most recent state seen; the work continues."""
+
+    def __init__(self, message: str, *, last: Any):
+        super().__init__(message)
+        self.last = last
+
+
+_BY_STATUS = {
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+}
+
+
+def error_for_status(status: int, message: str, *, retry_after: int | None = None, **fields: Any) -> WebAuditorError:
+    if status == 429:
+        return RateLimitError(message, retry_after=retry_after, status=status, **fields)
+    if status >= 500:
+        return APIError(message, status=status, **fields)
+    return _BY_STATUS.get(status, InvalidRequestError)(message, status=status, **fields)

web_auditor/_object.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ApiObject(dict):
+    """A JSON object from the API: a dict that also allows attribute access (`audit.report.score`).
+
+    Unknown fields added to the API later simply appear, so upgrading the API never breaks old SDK versions.
+    """
+
+    def __init__(self, data: dict | None = None):
+        super().__init__({key: _wrap(value) for key, value in (data or {}).items()})
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(f"{type(self).__name__} has no field {name!r}") from None
+
+    def to_dict(self) -> dict:
+        return {key: _unwrap(value) for key, value in self.items()}
+
+
+def _wrap(value: Any) -> Any:
+    if isinstance(value, dict) and not isinstance(value, ApiObject):
+        return ApiObject(value)
+    if isinstance(value, list):
+        return [_wrap(item) for item in value]
+    return value
+
+
+def _unwrap(value: Any) -> Any:
+    if isinstance(value, ApiObject):
+        return value.to_dict()
+    if isinstance(value, list):
+        return [_unwrap(item) for item in value]
+    return value

web_auditor/_operations.py

@@ -0,0 +1,44 @@
+"""Every public API operation the SDK calls, by the operationId published in /v1/openapi.json."""
+
+OPERATIONS = {
+    "retrieveStatus": ("GET", "/v1/status"),
+    "retrieveUsage": ("GET", "/v1/usage"),
+    "listChecks": ("GET", "/v1/checks"),
+    "listUrlAudits": ("GET", "/v1/url-audits"),
+    "createUrlAudit": ("POST", "/v1/url-audits"),
+    "retrieveUrlAudit": ("GET", "/v1/url-audits/{audit_id}"),
+    "cancelUrlAudit": ("POST", "/v1/url-audits/{audit_id}/cancel"),
+    "listUrlAuditArtifacts": ("GET", "/v1/url-audits/{audit_id}/artifacts"),
+    "downloadUrlAuditReportPdf": ("GET", "/v1/url-audits/{audit_id}/report.pdf"),
+    "listReportShares": ("GET", "/v1/url-audits/{audit_id}/shares"),
+    "createReportShare": ("POST", "/v1/url-audits/{audit_id}/shares"),
+    "revokeReportShare": ("DELETE", "/v1/url-audits/{audit_id}/shares/{share_id}"),
+    "listUrlAuditBatches": ("GET", "/v1/url-audit-batches"),
+    "createUrlAuditBatch": ("POST", "/v1/url-audit-batches"),
+    "retrieveUrlAuditBatch": ("GET", "/v1/url-audit-batches/{batch_id}"),
+    "cancelUrlAuditBatch": ("POST", "/v1/url-audit-batches/{batch_id}/cancel"),
+    "listBrandAudits": ("GET", "/v1/brand-audits"),
+    "createBrandAudit": ("POST", "/v1/brand-audits"),
+    "retrieveBrandAudit": ("GET", "/v1/brand-audits/{brand_audit_id}"),
+    "listSiteAudits": ("GET", "/v1/site-audits"),
+    "createSiteAudit": ("POST", "/v1/site-audits"),
+    "retrieveSiteAudit": ("GET", "/v1/site-audits/{site_audit_id}"),
+    "listSiteAuditPages": ("GET", "/v1/site-audits/{site_audit_id}/pages"),
+    "cancelSiteAudit": ("POST", "/v1/site-audits/{site_audit_id}/cancel"),
+    "listMonitors": ("GET", "/v1/monitors"),
+    "createMonitor": ("POST", "/v1/monitors"),
+    "retrieveMonitor": ("GET", "/v1/monitors/{monitor_id}"),
+    "updateMonitor": ("PATCH", "/v1/monitors/{monitor_id}"),
+    "deleteMonitor": ("DELETE", "/v1/monitors/{monitor_id}"),
+    "listMonitorRuns": ("GET", "/v1/monitors/{monitor_id}/runs"),
+    "createMonitorRun": ("POST", "/v1/monitors/{monitor_id}/runs"),
+    "listWebhookEndpoints": ("GET", "/v1/webhook-endpoints"),
+    "createWebhookEndpoint": ("POST", "/v1/webhook-endpoints"),
+    "retrieveWebhookEndpoint": ("GET", "/v1/webhook-endpoints/{endpoint_id}"),
+    "deleteWebhookEndpoint": ("DELETE", "/v1/webhook-endpoints/{endpoint_id}"),
+    "sendWebhookTestEvent": ("POST", "/v1/webhook-endpoints/{endpoint_id}/test"),
+    "rotateWebhookEndpointSecret": ("POST", "/v1/webhook-endpoints/{endpoint_id}/rotate-secret"),
+    "listWebhookDeliveries": ("GET", "/v1/webhook-deliveries"),
+    "retrieveWebhookDelivery": ("GET", "/v1/webhook-deliveries/{delivery_id}"),
+    "replayWebhookDelivery": ("POST", "/v1/webhook-deliveries/{delivery_id}/replay"),
+}

web_auditor/_resources.py

@@ -0,0 +1,402 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from ._client import Page
+from ._errors import PollTimeoutError
+from ._object import ApiObject
+
+if TYPE_CHECKING:
+    from ._client import WebAuditor
+
+AUDIT_FINAL_STATUSES = frozenset({"completed", "failed", "canceled"})
+BATCH_FINAL_STATUSES = frozenset({"completed", "canceled"})
+SITE_AUDIT_FINAL_STATUSES = frozenset({"completed", "canceled", "failed"})
+BRAND_AUDIT_FINAL_STATUSES = frozenset({"completed", "failed"})
+# Longer than the API's 90-second PDF wait, so a busy worker comes back as a clear 503 rather than a timeout.
+PDF_TIMEOUT_SECONDS = 120
+
+
+class _NotGiven:
+    """Marks an update argument that wasn't passed, so `None` can mean "clear this field"."""
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN: Any = _NotGiven()
+
+
+def _given(**fields: Any) -> dict[str, Any]:
+    return {key: value for key, value in fields.items() if value is not NOT_GIVEN}
+
+
+def _compact(**fields: Any) -> dict[str, Any]:
+    return {key: value for key, value in fields.items() if value is not None}
+
+
+class _Resource:
+    def __init__(self, client: WebAuditor):
+        self._client = client
+
+    def _list(self, operation_id: str, path_params: dict[str, str] | None = None, **params: Any) -> Page:
+        def fetch(cursor: str | None) -> Page:
+            query = {**params, "cursor": cursor} if cursor else params
+            return Page(self._client.request(operation_id, path_params, params=query), fetch=fetch)
+
+        return fetch(None)
+
+    def _wait(
+        self, retrieve, object_id: str, final: frozenset, timeout: float | None, poll_interval: float
+    ) -> ApiObject:
+        deadline = None if timeout is None else self._client._monotonic() + timeout
+        while True:
+            current = retrieve(object_id)
+            if current.status in final:
+                return current
+            if deadline is not None and self._client._monotonic() >= deadline:
+                raise PollTimeoutError(
+                    f"{object_id} was still {current.status} after {timeout:g} seconds.",
+                    last=current,
+                )
+            self._client._sleep(poll_interval)
+
+
+class Status(_Resource):
+    def retrieve(self) -> ApiObject:
+        """Service health. Needs no scope."""
+        return self._client.request("retrieveStatus")
+
+
+class Usage(_Resource):
+    def retrieve(self) -> ApiObject:
+        """Plan limits and credits for the current period."""
+        return self._client.request("retrieveUsage")
+
+
+class Checks(_Resource):
+    def list(self) -> ApiObject:
+        """The catalogue of every check an audit can run, with severity and how to fix it."""
+        return self._client.request("listChecks")
+
+
+class UrlAudits(_Resource):
+    def create(
+        self,
+        *,
+        url: str,
+        render: str | None = None,
+        geo: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiObject:
+        """Start an audit (202). `render`: "always" | "auto" | "never". `geo` turns on AI-engine probes."""
+        return self._client.request(
+            "createUrlAudit",
+            json=_compact(url=url, render=render, geo=geo),
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, audit_id: str) -> ApiObject:
+        return self._client.request("retrieveUrlAudit", {"audit_id": audit_id})
+
+    def list(self, *, status: str | None = None, limit: int | None = None) -> Page:
+        return self._list("listUrlAudits", status=status, limit=limit)
+
+    def cancel(self, audit_id: str, *, idempotency_key: str | None = None) -> ApiObject:
+        """Cancel a waiting, queued or running audit; its credits are refunded."""
+        return self._client.request("cancelUrlAudit", {"audit_id": audit_id}, idempotency_key=idempotency_key)
+
+    def artifacts(self, audit_id: str) -> ApiObject:
+        """Raw/rendered HTML and screenshots, as download links valid for 15 minutes."""
+        return self._client.request("listUrlAuditArtifacts", {"audit_id": audit_id})
+
+    def report_pdf(self, audit_id: str) -> bytes:
+        """The finished report as PDF bytes.
+
+        Printing can take the API up to 90 seconds when its PDF workers are busy (then 503 `pdf_unavailable`), so
+        this call waits longer than the client timeout and doesn't retry a timeout — each retry would print again.
+        """
+        return self._client.request(
+            "downloadUrlAuditReportPdf",
+            {"audit_id": audit_id},
+            accept="application/pdf, application/json",
+            raw=True,
+            timeout=PDF_TIMEOUT_SECONDS,
+            retry_timeouts=False,
+        )
+
+    def wait(self, audit_id: str, *, timeout: float | None = 900, poll_interval: float = 3) -> ApiObject:
+        """Poll until the audit is completed, failed or canceled. Raises PollTimeoutError after `timeout` seconds."""
+        return self._wait(self.retrieve, audit_id, AUDIT_FINAL_STATUSES, timeout, poll_interval)
+
+
+class ReportShares(_Resource):
+    def create(
+        self, audit_id: str, *, expires_in_days: int | None = None, idempotency_key: str | None = None
+    ) -> ApiObject:
+        """A read-only report link for people without a key. `url` is returned only now."""
+        return self._client.request(
+            "createReportShare",
+            {"audit_id": audit_id},
+            json=_compact(expires_in_days=expires_in_days),
+            idempotency_key=idempotency_key,
+        )
+
+    def list(self, audit_id: str, *, limit: int | None = None) -> Page:
+        return self._list("listReportShares", {"audit_id": audit_id}, limit=limit)
+
+    def revoke(self, audit_id: str, share_id: str) -> None:
+        return self._client.request("revokeReportShare", {"audit_id": audit_id, "share_id": share_id})
+
+
+class UrlAuditBatches(_Resource):
+    def create(
+        self,
+        *,
+        urls: Sequence[str],
+        render: str | None = None,
+        geo: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiObject:
+        """Audit many URLs with the same options. Credits for all of them are reserved up front."""
+        return self._client.request(
+            "createUrlAuditBatch",
+            json=_compact(urls=list(urls), render=render, geo=geo),
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, batch_id: str) -> ApiObject:
+        return self._client.request("retrieveUrlAuditBatch", {"batch_id": batch_id})
+
+    def list(self, *, limit: int | None = None) -> Page:
+        return self._list("listUrlAuditBatches", limit=limit)
+
+    def cancel(self, batch_id: str, *, idempotency_key: str | None = None) -> ApiObject:
+        return self._client.request("cancelUrlAuditBatch", {"batch_id": batch_id}, idempotency_key=idempotency_key)
+
+    def wait(self, batch_id: str, *, timeout: float | None = 3600, poll_interval: float = 10) -> ApiObject:
+        """Poll until the batch is completed or canceled. Single-site batches wait on hourly limits, so allow time."""
+        return self._wait(self.retrieve, batch_id, BATCH_FINAL_STATUSES, timeout, poll_interval)
+
+
+class BrandAudits(_Resource):
+    def create(
+        self,
+        *,
+        brand: str,
+        category: str,
+        domain: str | None = None,
+        competitors: Sequence[dict[str, Any]] | None = None,
+        engines: Sequence[str] | None = None,
+        prompts: Sequence[str] | None = None,
+        prompt_count: int | None = None,
+        region: str | None = None,
+        language: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiObject:
+        """Measure how AI engines mention and cite `brand` versus `competitors` ([{"name", "domain"}], up to 5)."""
+        return self._client.request(
+            "createBrandAudit",
+            json=_compact(
+                brand=brand,
+                category=category,
+                domain=domain,
+                competitors=list(competitors) if competitors is not None else None,
+                engines=list(engines) if engines is not None else None,
+                prompts=list(prompts) if prompts is not None else None,
+                prompt_count=prompt_count,
+                region=region,
+                language=language,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, brand_audit_id: str) -> ApiObject:
+        return self._client.request("retrieveBrandAudit", {"brand_audit_id": brand_audit_id})
+
+    def list(self, *, status: str | None = None, limit: int | None = None) -> Page:
+        return self._list("listBrandAudits", status=status, limit=limit)
+
+    def wait(self, brand_audit_id: str, *, timeout: float | None = 900, poll_interval: float = 5) -> ApiObject:
+        """Poll until the brand audit is completed or failed."""
+        return self._wait(self.retrieve, brand_audit_id, BRAND_AUDIT_FINAL_STATUSES, timeout, poll_interval)
+
+
+class SiteAudits(_Resource):
+    def create(
+        self,
+        *,
+        url: str,
+        max_pages: int | None = None,
+        render: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiObject:
+        """Crawl the site (or the section under `url`'s directory) and audit up to `max_pages` pages, politely.
+
+        Credits for `max_pages` are reserved up front and unused pages refunded.
+        """
+        return self._client.request(
+            "createSiteAudit",
+            json=_compact(url=url, max_pages=max_pages, render=render),
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, site_audit_id: str) -> ApiObject:
+        return self._client.request("retrieveSiteAudit", {"site_audit_id": site_audit_id})
+
+    def list(self, *, status: str | None = None, limit: int | None = None) -> Page:
+        return self._list("listSiteAudits", status=status, limit=limit)
+
+    def list_pages(self, site_audit_id: str, *, limit: int | None = None) -> Page:
+        """Pages in the order they were found, with each page audit's status and score."""
+        return self._list("listSiteAuditPages", {"site_audit_id": site_audit_id}, limit=limit)
+
+    def cancel(self, site_audit_id: str, *, idempotency_key: str | None = None) -> ApiObject:
+        return self._client.request(
+            "cancelSiteAudit", {"site_audit_id": site_audit_id}, idempotency_key=idempotency_key
+        )
+
+    def wait(self, site_audit_id: str, *, timeout: float | None = 7200, poll_interval: float = 15) -> ApiObject:
+        """Poll until the site audit is completed, canceled or failed; pages are audited seconds apart."""
+        return self._wait(self.retrieve, site_audit_id, SITE_AUDIT_FINAL_STATUSES, timeout, poll_interval)
+
+
+class Monitors(_Resource):
+    def create(
+        self,
+        *,
+        url: str,
+        cadence: str | None = None,
+        render: str | None = None,
+        geo: dict[str, Any] | None = None,
+        score_drop_threshold: int | None = None,
+        description: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiObject:
+        """Audit `url` on a schedule. `cadence`: "daily" (default) | "weekly". The first run is due straight away."""
+        return self._client.request(
+            "createMonitor",
+            json=_compact(
+                url=url,
+                cadence=cadence,
+                render=render,
+                geo=geo,
+                score_drop_threshold=score_drop_threshold,
+                description=description,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, monitor_id: str) -> ApiObject:
+        return self._client.request("retrieveMonitor", {"monitor_id": monitor_id})
+
+    def list(self, *, status: str | None = None, limit: int | None = None) -> Page:
+        return self._list("listMonitors", status=status, limit=limit)
+
+    def update(
+        self,
+        monitor_id: str,
+        *,
+        cadence: str = NOT_GIVEN,
+        status: str = NOT_GIVEN,
+        render: str = NOT_GIVEN,
+        geo: dict[str, Any] | None = NOT_GIVEN,
+        score_drop_threshold: int = NOT_GIVEN,
+        description: str = NOT_GIVEN,
+    ) -> ApiObject:
+        """Change only the fields you pass. `geo=None` stops GEO probes. The URL can't change."""
+        return self._client.request(
+            "updateMonitor",
+            {"monitor_id": monitor_id},
+            json=_given(
+                cadence=cadence,
+                status=status,
+                render=render,
+                geo=geo,
+                score_drop_threshold=score_drop_threshold,
+                description=description,
+            ),
+        )
+
+    def pause(self, monitor_id: str) -> ApiObject:
+        return self.update(monitor_id, status="paused")
+
+    def resume(self, monitor_id: str) -> ApiObject:
+        """Resume scheduled runs; an overdue monitor runs at the next scheduler pass."""
+        return self.update(monitor_id, status="active")
+
+    def delete(self, monitor_id: str) -> None:
+        return self._client.request("deleteMonitor", {"monitor_id": monitor_id})
+
+    def run(self, monitor_id: str, *, idempotency_key: str | None = None) -> ApiObject:
+        """Start a run now without moving the schedule. InsufficientCreditsError / ConflictError when it can't.
+
+        Follow the run's audit with `client.url_audits.wait(run.audit.id)`.
+        """
+        return self._client.request("createMonitorRun", {"monitor_id": monitor_id}, idempotency_key=idempotency_key)
+
+    def list_runs(self, monitor_id: str, *, limit: int | None = None) -> Page:
+        """Runs newest first: `status` is `skipped` (see `skip_reason`), the audit's status, or `expired`."""
+        return self._list("listMonitorRuns", {"monitor_id": monitor_id}, limit=limit)
+
+
+class WebhookEndpoints(_Resource):
+    def create(
+        self,
+        *,
+        url: str,
+        events: Sequence[str] | None = None,
+        description: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiObject:
+        """Register an HTTPS endpoint. The signing `secret` is returned only now; store it."""
+        return self._client.request(
+            "createWebhookEndpoint",
+            json=_compact(url=url, description=description, events=list(events) if events is not None else None),
+            idempotency_key=idempotency_key,
+        )
+
+    def list(self, *, limit: int | None = None) -> Page:
+        return self._list("listWebhookEndpoints", limit=limit)
+
+    def retrieve(self, endpoint_id: str) -> ApiObject:
+        return self._client.request("retrieveWebhookEndpoint", {"endpoint_id": endpoint_id})
+
+    def delete(self, endpoint_id: str) -> None:
+        return self._client.request("deleteWebhookEndpoint", {"endpoint_id": endpoint_id})
+
+    def send_test_event(self, endpoint_id: str, *, event_type: str | None = None) -> ApiObject:
+        """Queue a sample event (default `url_audit.completed`) to check your receiver."""
+        return self._client.request(
+            "sendWebhookTestEvent",
+            {"endpoint_id": endpoint_id},
+            json=_compact(event_type=event_type),
+        )
+
+    def rotate_secret(self, endpoint_id: str) -> ApiObject:
+        """Replace the signing secret; the new one is returned only now."""
+        return self._client.request("rotateWebhookEndpointSecret", {"endpoint_id": endpoint_id})
+
+
+class WebhookDeliveries(_Resource):
+    def list(
+        self,
+        *,
+        endpoint: str | None = None,
+        status: str | None = None,
+        event_type: str | None = None,
+        limit: int | None = None,
+    ) -> Page:
+        return self._list("listWebhookDeliveries", endpoint=endpoint, status=status, event_type=event_type, limit=limit)
+
+    def retrieve(self, delivery_id: str) -> ApiObject:
+        return self._client.request("retrieveWebhookDelivery", {"delivery_id": delivery_id})
+
+    def replay(self, delivery_id: str, *, idempotency_key: str | None = None) -> ApiObject:
+        """Send the same event again (same event ID). Conflict (409 `delivery_pending`) while it's still pending."""
+        return self._client.request(
+            "replayWebhookDelivery",
+            {"delivery_id": delivery_id},
+            idempotency_key=idempotency_key,
+        )

web_auditor/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

web_auditor/webhooks.py

@@ -0,0 +1,65 @@
+"""Verify webhook deliveries from Web Auditor.
+
+    event = webhooks.construct_event(request.body, request.headers["WA-Signature"], secret)
+
+Always pass the raw request body, before any JSON parsing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+
+from ._errors import WebAuditorError
+from ._object import ApiObject
+
+SIGNATURE_HEADER = "WA-Signature"
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+class WebhookSignatureError(WebAuditorError):
+    """The payload doesn't match its WA-Signature, or the signature is too old."""
+
+
+def verify_signature(
+    payload: bytes | str,
+    header: str | None,
+    secret: str,
+    *,
+    tolerance: int | None = DEFAULT_TOLERANCE_SECONDS,
+) -> bool:
+    """True when `header` (`t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<payload>">`) signs `payload`.
+
+    Timestamps more than `tolerance` seconds from now are rejected to stop replays; pass None to skip that.
+    """
+    if not header:
+        return False
+    timestamp, signatures = None, []
+    for part in header.split(","):
+        key, _, value = part.strip().partition("=")
+        if key == "t":
+            timestamp = value
+        elif key == "v1" and value:
+            signatures.append(value)
+    if not signatures or timestamp is None or not timestamp.isdigit():
+        return False
+    if tolerance is not None and abs(time.time() - int(timestamp)) > tolerance:
+        return False
+    body = payload.encode() if isinstance(payload, str) else payload
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
+    return any(hmac.compare_digest(expected, signature) for signature in signatures)
+
+
+def construct_event(
+    payload: bytes | str,
+    header: str | None,
+    secret: str,
+    *,
+    tolerance: int | None = DEFAULT_TOLERANCE_SECONDS,
+) -> ApiObject:
+    """Verify the delivery and return the event (`id`, `type`, `mode`, `data`), or raise WebhookSignatureError."""
+    if not verify_signature(payload, header, secret, tolerance=tolerance):
+        raise WebhookSignatureError("Webhook signature verification failed.")
+    return ApiObject(json.loads(payload))

web_auditor-0.1.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: web-auditor
+Version: 0.1.0
+Summary: Official Python client for the Web Auditor public API: AI-visibility (AEO/GEO) audits of web pages.
+Project-URL: Documentation, https://api.web-auditor.enfection.com/docs
+Author: Enfection
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aeo,ai-search,api,geo,seo,web-auditor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Web Auditor Python SDK
+
+The official Python client for the [Web Auditor public API](https://api.web-auditor.enfection.com/docs): audit how
+well a page can be found, read and cited by AI answer engines.
+
+```bash
+pip install web-auditor
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from web_auditor import WebAuditor
+
+client = WebAuditor(api_key="wa_test_…")  # or set WEB_AUDITOR_API_KEY
+
+audit = client.url_audits.create(url="https://example.com/pricing")
+audit = client.url_audits.wait(audit.id)
+
+print(audit.status, audit.report.score)
+for check in audit.report.checks:
+    if check.status == "fail":
+        print(check.id, check.fix)
+```
+
+Test keys (`wa_test_…`) return a realistic sample report immediately and cost nothing — build your integration with
+one, then switch to a live key.
+
+Responses are `ApiObject`s: dicts that also allow attribute access (`audit.report.score` or
+`audit["report"]["score"]`). `to_dict()` returns plain dicts.
+
+## What's covered
+
+| Resource | Methods |
+|---|---|
+| `client.url_audits` | `create`, `retrieve`, `list`, `cancel`, `artifacts`, `report_pdf`, `wait` |
+| `client.url_audit_batches` | `create`, `retrieve`, `list`, `cancel`, `wait` |
+| `client.report_shares` | `create`, `list`, `revoke` |
+| `client.site_audits` | `create`, `retrieve`, `list`, `list_pages`, `cancel`, `wait` |
+| `client.brand_audits` | `create`, `retrieve`, `list`, `wait` |
+| `client.monitors` | `create`, `retrieve`, `list`, `update`, `pause`, `resume`, `delete`, `run`, `list_runs` |
+| `client.webhook_endpoints` | `create`, `retrieve`, `list`, `delete`, `send_test_event`, `rotate_secret` |
+| `client.webhook_deliveries` | `list`, `retrieve`, `replay` |
+| `client.usage`, `client.status` | `retrieve` |
+| `client.checks` | `list` |
+
+### GEO probes and batches
+
+```python
+audit = client.url_audits.create(
+    url="https://example.com/pricing",
+    geo={"engines": ["chatgpt", "gemini"], "prompt_count": 3},
+)
+
+batch = client.url_audit_batches.create(urls=["https://example.com/a", "https://example.com/b"])
+batch = client.url_audit_batches.wait(batch.id)
+for member in batch.audits:
+    print(member.url, member.status, member.score)
+```
+
+### Site audits
+
+```python
+site = client.site_audits.create(url="https://example.com/docs/", max_pages=50)
+site = client.site_audits.wait(site.id)
+for page in client.site_audits.list_pages(site.id).auto_paging_iter():
+    print(page.url, page.status, page.audit and page.audit.score)
+
+print(site.report.score)
+for issue in site.report.top_issues:
+    print(issue.id, issue.failed, issue.examples)
+```
+
+Pages are found from sitemaps, respect robots.txt and are audited one at a time per site, a few seconds apart.
+
+### Brand audits
+
+```python
+brand = client.brand_audits.create(
+    brand="Acme Payroll",
+    domain="acmepayroll.com",
+    category="payroll software for small businesses",
+    competitors=[{"name": "Gusto", "domain": "gusto.com"}],
+)
+brand = client.brand_audits.wait(brand.id)
+print(brand.report.summary.brand.share_of_voice, brand.report.summary.gaps)
+```
+
+### Monitors
+
+```python
+monitor = client.monitors.create(url="https://example.com/pricing", cadence="weekly", score_drop_threshold=5)
+client.monitors.update(monitor.id, geo=None)  # only the fields you pass change; None clears geo
+client.monitors.pause(monitor.id)
+```
+
+Each run is compared with the previous completed run; `run.regressions` lists what got worse (and the `monitor.regression_detected` webhook announces it).
+
+```python
+for run in client.monitors.list_runs(monitor.id).auto_paging_iter():
+    for regression in run.regressions or []:
+        print(run.id, regression.type)  # score_drop, ai_bot_blocked, schema_removed, citation_lost, render_regression
+```
+
+### Pagination
+
+`list()` returns one page (`page.data`, `page.has_more`); `auto_paging_iter()` walks all of them:
+
+```python
+for audit in client.url_audits.list(status="completed").auto_paging_iter():
+    print(audit.id, audit.url)
+```
+
+## Errors, retries and idempotency
+
+Network errors, `429` and `5xx` responses are retried twice (`max_retries=`) with backoff, honouring `Retry-After`.
+A `Retry-After` longer than a minute — such as a site's hourly audit limit — is raised straight away so you can
+decide. Every POST sends an `Idempotency-Key` (pass `idempotency_key=` to choose it), so a retry can never start a
+second audit.
+
+```python
+from web_auditor import InsufficientCreditsError, RateLimitError, WebAuditorError
+
+try:
+    client.url_audits.create(url="https://example.com")
+except InsufficientCreditsError:
+    ...
+except RateLimitError as error:
+    print(error.code, error.retry_after)  # rate_limited | host_rate_limit | concurrent_audit_limit
+except WebAuditorError as error:
+    print(error.status, error.code, error.message, error.request_id)
+```
+
+| Exception | When |
+|---|---|
+| `InvalidRequestError` / `ConflictError` | 400, 409 (`param` names the field) |
+| `AuthenticationError` | 401 |
+| `InsufficientCreditsError` | 402 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `APIError` | 5xx |
+| `APIConnectionError` / `APITimeoutError` | the API couldn't be reached |
+| `PollTimeoutError` | `wait()` ran out of time (`error.last` is the latest state) |
+
+## Webhooks
+
+Verify every delivery with the endpoint's signing secret, over the **raw** request body:
+
+```python
+from web_auditor import webhooks
+
+@app.post("/webhooks/web-auditor")
+def receive(request):
+    try:
+        event = webhooks.construct_event(request.body, request.headers.get("WA-Signature"), WEBHOOK_SECRET)
+    except webhooks.WebhookSignatureError:
+        return Response(status=400)
+    if event.type == "url_audit.completed":
+        ...
+    return Response(status=204)
+```
+
+Deliveries can arrive more than once (retries and replays keep the same `event.id`), so deduplicate on it.
+
+## Configuration
+
+```python
+WebAuditor(
+    api_key="wa_live_…",
+    base_url="https://api.web-auditor.enfection.com",  # or WEB_AUDITOR_BASE_URL
+    timeout=60,
+    max_retries=2,
+    http_client=None,  # your own httpx.Client (proxies, custom transport)
+)
+```
+
+`WebAuditor` can be used as a context manager to close its connections.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+`tests/test_contract.py` checks the SDK against `../openapi.json`, which the backend regenerates with
+`python manage.py export_public_openapi`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Release notes are in [CHANGELOG.md](CHANGELOG.md).

web_auditor-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+web_auditor/__init__.py,sha256=7cstv0xYXJbW6pIdPplSh5Rg2sDJMdaqPgvx2KDNwOg,919
+web_auditor/_client.py,sha256=JbIC0DWLYlq6DIzNZmFvZzGaXy4UaRw6a6sjWUESUok,7983
+web_auditor/_errors.py,sha256=1OCENivN7g-KgJPr1k0LUNO2rCqcGVPtVmXJMeLjpdw,3277
+web_auditor/_object.py,sha256=hdwMNkTPH6Dy-HkYagHy1d-i-olwU7AAz_ftlt4k1cc,1172
+web_auditor/_operations.py,sha256=tBjLkukYZYoUNoK422ivU3WwqszqdnOYDmmVASKwgig,2738
+web_auditor/_resources.py,sha256=Sb_8pdJN-7dR2E2TEDmlc81Z0d0u8ImoOJYat066wXs,16278
+web_auditor/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+web_auditor/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+web_auditor/webhooks.py,sha256=QX-A1Yzdo_32ADrLa1rRJccuySLQukh8PzZmJSqrffo,2161
+web_auditor-0.1.0.dist-info/METADATA,sha256=7qR7SFeJOcAmUl7h0xNSHpLKNxIYisfrazLl9p_q0QU,7194
+web_auditor-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+web_auditor-0.1.0.dist-info/licenses/LICENSE,sha256=3-NjXzwp-pdbFX6LwAnEp2mdSrxych-aHgM7K0xy1VM,1066
+web_auditor-0.1.0.dist-info/RECORD,,

web_auditor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

web_auditor-0.1.0.dist-info/licenses/LICENSE

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