citeflow-python 0.1.0__tar.gz

citeflow_python-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.venv/
+.tox/
+htmlcov/
+.coverage

citeflow_python-0.1.0/LICENSE

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

citeflow_python-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: citeflow-python
+Version: 0.1.0
+Summary: Official Python SDK for the CiteFlow API (SEO, AEO, GEO audits).
+Project-URL: Homepage, https://citeflow.io
+Project-URL: Documentation, https://citeflow.io/help/partner-api
+Author-email: CiteFlow <support@citeflow.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aeo,api,audit,citeflow,geo,sdk,seo
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# citeflow-python
+
+Official Python SDK for the **[CiteFlow](https://citeflow.io)** Partner
+API — programmatic SEO, AEO, and GEO audits.
+
+[CiteFlow](https://citeflow.io) is an AI-visibility scanner: it audits how
+well a website can be crawled, understood, and cited by AI search engines
+(ChatGPT, Claude, Perplexity, Google AI Overviews). This SDK lets partners
+run those audits from their own products via the CiteFlow Partner API.
+
+- Website: <https://citeflow.io>
+- API docs & getting started: <https://citeflow.io/help/partner-api>
+- Dashboard (API keys, billing, webhooks): <https://citeflow.io/dashboard/api>
+
+## Install
+
+```bash
+pip install citeflow-python
+```
+
+Python 3.9+ required. Depends on `requests`.
+
+## Quickstart
+
+```python
+import os
+from citeflow import Citeflow
+
+client = Citeflow(api_key=os.environ["CITEFLOW_API_KEY"])
+
+# Create an audit and wait for the result (~30s for SEO).
+audit = client.audits.create(url="https://example.com", type="seo")
+result = client.audits.wait_for_completion(audit["audit_id"], timeout=90)
+
+if result["status"] == "complete":
+    print("Scores:", result["scores"])
+elif result["status"] == "failed":
+    print("Failure:", result["failure_reason"])
+
+# Check remaining balance.
+b = client.balance.retrieve()
+print(f"Balance: {b['balance_usd']} ({b['balance']} credits)")
+```
+
+## Features
+
+- **Auto-retry** on `429` and `5xx` with exponential back-off + jitter.
+  Honors `Retry-After`.
+- **Auto Idempotency-Key** on every POST — safe to retry on network
+  failure without double-charging.
+- **`wait_for_completion`** polling helper with configurable timeout.
+- **HMAC webhook verification** with timestamp tolerance + rotation
+  grace handling.
+- Pluggable `requests.Session` for custom proxies / adapters.
+
+## Webhook verification
+
+```python
+from citeflow import verify_webhook_signature, parse_webhook_event, CiteflowSignatureError
+
+# In your webhook handler (Flask, FastAPI, Django, …):
+raw_body = request.get_data()  # bytes — do NOT JSON-parse first
+try:
+    event = parse_webhook_event(
+        raw_body=raw_body,
+        headers=request.headers,
+        secret=os.environ["CITEFLOW_WEBHOOK_SECRET"],
+    )
+    # event["type"] in {"audit.completed", "audit.failed", "audit.cancelled", "balance.low"}
+    print(event["id"], event["type"], event["data"])
+    return "", 200
+except CiteflowSignatureError:
+    return "", 400
+```
+
+## Errors
+
+```python
+from citeflow import CiteflowError
+
+try:
+    client.audits.create(url="invalid", type="seo")
+except CiteflowError as err:
+    print(err.code, err.request_id)
+    if err.code == "INSUFFICIENT_CREDITS":
+        print(f"Need {err.required} more credits")
+```
+
+Full error catalog: https://citeflow.io/help/partner-api#troubleshooting.
+
+## Configuration
+
+```python
+client = Citeflow(
+    api_key="ckf_…",
+    base_url="https://citeflow.io/api/v1",  # override for staging
+    timeout=30.0,                            # per-request seconds
+    max_retries=3,                           # for 429 + 5xx + network
+)
+```
+
+## License
+
+MIT. CiteFlow API itself is a paid service — see
+https://citeflow.io/terms-of-service.

citeflow_python-0.1.0/README.md

@@ -0,0 +1,105 @@
+# citeflow-python
+
+Official Python SDK for the **[CiteFlow](https://citeflow.io)** Partner
+API — programmatic SEO, AEO, and GEO audits.
+
+[CiteFlow](https://citeflow.io) is an AI-visibility scanner: it audits how
+well a website can be crawled, understood, and cited by AI search engines
+(ChatGPT, Claude, Perplexity, Google AI Overviews). This SDK lets partners
+run those audits from their own products via the CiteFlow Partner API.
+
+- Website: <https://citeflow.io>
+- API docs & getting started: <https://citeflow.io/help/partner-api>
+- Dashboard (API keys, billing, webhooks): <https://citeflow.io/dashboard/api>
+
+## Install
+
+```bash
+pip install citeflow-python
+```
+
+Python 3.9+ required. Depends on `requests`.
+
+## Quickstart
+
+```python
+import os
+from citeflow import Citeflow
+
+client = Citeflow(api_key=os.environ["CITEFLOW_API_KEY"])
+
+# Create an audit and wait for the result (~30s for SEO).
+audit = client.audits.create(url="https://example.com", type="seo")
+result = client.audits.wait_for_completion(audit["audit_id"], timeout=90)
+
+if result["status"] == "complete":
+    print("Scores:", result["scores"])
+elif result["status"] == "failed":
+    print("Failure:", result["failure_reason"])
+
+# Check remaining balance.
+b = client.balance.retrieve()
+print(f"Balance: {b['balance_usd']} ({b['balance']} credits)")
+```
+
+## Features
+
+- **Auto-retry** on `429` and `5xx` with exponential back-off + jitter.
+  Honors `Retry-After`.
+- **Auto Idempotency-Key** on every POST — safe to retry on network
+  failure without double-charging.
+- **`wait_for_completion`** polling helper with configurable timeout.
+- **HMAC webhook verification** with timestamp tolerance + rotation
+  grace handling.
+- Pluggable `requests.Session` for custom proxies / adapters.
+
+## Webhook verification
+
+```python
+from citeflow import verify_webhook_signature, parse_webhook_event, CiteflowSignatureError
+
+# In your webhook handler (Flask, FastAPI, Django, …):
+raw_body = request.get_data()  # bytes — do NOT JSON-parse first
+try:
+    event = parse_webhook_event(
+        raw_body=raw_body,
+        headers=request.headers,
+        secret=os.environ["CITEFLOW_WEBHOOK_SECRET"],
+    )
+    # event["type"] in {"audit.completed", "audit.failed", "audit.cancelled", "balance.low"}
+    print(event["id"], event["type"], event["data"])
+    return "", 200
+except CiteflowSignatureError:
+    return "", 400
+```
+
+## Errors
+
+```python
+from citeflow import CiteflowError
+
+try:
+    client.audits.create(url="invalid", type="seo")
+except CiteflowError as err:
+    print(err.code, err.request_id)
+    if err.code == "INSUFFICIENT_CREDITS":
+        print(f"Need {err.required} more credits")
+```
+
+Full error catalog: https://citeflow.io/help/partner-api#troubleshooting.
+
+## Configuration
+
+```python
+client = Citeflow(
+    api_key="ckf_…",
+    base_url="https://citeflow.io/api/v1",  # override for staging
+    timeout=30.0,                            # per-request seconds
+    max_retries=3,                           # for 429 + 5xx + network
+)
+```
+
+## License
+
+MIT. CiteFlow API itself is a paid service — see
+https://citeflow.io/terms-of-service.

citeflow_python-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "citeflow-python"
+version = "0.1.0"
+description = "Official Python SDK for the CiteFlow API (SEO, AEO, GEO audits)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "CiteFlow", email = "support@citeflow.io" }]
+keywords = ["citeflow", "seo", "aeo", "geo", "audit", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "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",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://citeflow.io"
+Documentation = "https://citeflow.io/help/partner-api"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-mock>=3.12", "responses>=0.25", "mypy>=1.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/citeflow"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/citeflow", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+strict = true
+python_version = "3.9"

citeflow_python-0.1.0/src/citeflow/__init__.py

@@ -0,0 +1,25 @@
+"""CiteFlow Python SDK.
+
+Public surface mirrors @citeflow/sdk for Node. See https://docs.citeflow.io.
+"""
+
+from .client import Citeflow
+from .errors import (
+    CiteflowError,
+    CiteflowNetworkError,
+    CiteflowSignatureError,
+    CiteflowTimeoutError,
+)
+from .webhooks import parse_webhook_event, verify_webhook_signature
+
+__all__ = [
+    "Citeflow",
+    "CiteflowError",
+    "CiteflowNetworkError",
+    "CiteflowSignatureError",
+    "CiteflowTimeoutError",
+    "parse_webhook_event",
+    "verify_webhook_signature",
+]
+
+__version__ = "0.1.0"

citeflow_python-0.1.0/src/citeflow/_http.py

@@ -0,0 +1,125 @@
+"""Base HTTP client with retry + auto Idempotency-Key.
+
+Internal — use Citeflow.* facades, not HttpClient directly.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+import uuid
+from typing import Any, Optional
+
+import requests
+
+from .errors import CiteflowError, CiteflowNetworkError
+
+DEFAULT_BASE_URL = "https://citeflow.io/api/v1"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "`api_key` is required. Generate one at "
+                "https://citeflow.io/dashboard/api/keys"
+            )
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        # Caller can inject a configured session (e.g., with custom adapters
+        # or proxy settings); otherwise use a fresh one we own.
+        self._session = session or requests.Session()
+
+    def request(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+        idempotency_key: Optional[str] = None,
+        auto_idempotency: bool = True,
+    ) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": "citeflow-python",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if method == "POST" and auto_idempotency:
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+
+        attempt = 0
+        while True:
+            try:
+                response = self._session.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    json=body if body is not None else None,
+                    timeout=self._timeout,
+                )
+            except requests.RequestException as exc:
+                if self._should_retry_network(attempt):
+                    self._sleep_backoff(None, attempt)
+                    attempt += 1
+                    continue
+                raise CiteflowNetworkError(
+                    f"Network error calling {method} {path}", cause=exc
+                ) from exc
+
+            if response.ok:
+                try:
+                    return response.json()
+                except ValueError as exc:
+                    raise CiteflowNetworkError(
+                        f"Failed to parse JSON from {method} {path}", cause=exc
+                    ) from exc
+
+            try:
+                err_body = response.json()
+            except ValueError:
+                err_body = {
+                    "error": {
+                        "code": "INTERNAL_ERROR",
+                        "message": f"Non-JSON {response.status_code} response",
+                        "doc_url": "https://docs.citeflow.io/errors",
+                    },
+                    "request_id": response.headers.get("X-Request-Id", "unknown"),
+                }
+            error = CiteflowError.from_api_response(response.status_code, err_body)
+
+            if self._should_retry_api(error, attempt):
+                self._sleep_backoff(error, attempt)
+                attempt += 1
+                continue
+            raise error
+
+    def _should_retry_network(self, attempt: int) -> bool:
+        return attempt < self._max_retries
+
+    def _should_retry_api(self, error: CiteflowError, attempt: int) -> bool:
+        if attempt >= self._max_retries:
+            return False
+        return error.status == 429 or error.status >= 500
+
+    def _sleep_backoff(self, error: Optional[CiteflowError], attempt: int) -> None:
+        # Server-supplied Retry-After always wins.
+        if error is not None and error.retry_after:
+            time.sleep(error.retry_after)
+            return
+        # 250ms · 1s · 4s with ±25% jitter.
+        base = 0.250 * (4**attempt)
+        jitter = base * (random.random() * 0.5 - 0.25)
+        time.sleep(max(0.0, base + jitter))

citeflow_python-0.1.0/src/citeflow/audits.py

@@ -0,0 +1,72 @@
+"""Audits resource."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from ._http import HttpClient
+from .errors import CiteflowTimeoutError
+
+
+class AuditsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        url: str,
+        type: str,  # noqa: A002 — mirror API field name
+        metadata: Optional[dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"url": url, "type": type}
+        if metadata is not None:
+            body["metadata"] = metadata
+        envelope = self._http.request(
+            method="POST",
+            path="/audit",
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+        return envelope["data"]
+
+    def get(self, audit_id: str) -> dict[str, Any]:
+        envelope = self._http.request(
+            method="GET",
+            path=f"/audit/{audit_id}",
+            auto_idempotency=False,
+        )
+        return envelope["data"]
+
+    def cancel(self, audit_id: str) -> dict[str, Any]:
+        envelope = self._http.request(
+            method="POST",
+            path=f"/audit/{audit_id}:cancel",
+            auto_idempotency=False,
+        )
+        return envelope["data"]
+
+    def wait_for_completion(
+        self,
+        audit_id: str,
+        *,
+        timeout: float = 90.0,
+        interval: float = 2.0,
+    ) -> dict[str, Any]:
+        """Poll until terminal status reached.
+
+        Raises CiteflowTimeoutError if `timeout` seconds elapse first.
+        Webhooks are preferred for long-running flows; use this only when
+        synchronous callers need the result.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            audit = self.get(audit_id)
+            status = audit.get("status")
+            if status not in ("queued", "processing"):
+                return audit
+            if time.monotonic() + interval > deadline:
+                raise CiteflowTimeoutError(audit_id, timeout)
+            time.sleep(interval)

citeflow_python-0.1.0/src/citeflow/balance.py

@@ -0,0 +1,20 @@
+"""Balance resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._http import HttpClient
+
+
+class BalanceResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def retrieve(self) -> dict[str, Any]:
+        envelope = self._http.request(
+            method="GET",
+            path="/balance",
+            auto_idempotency=False,
+        )
+        return envelope["data"]

citeflow_python-0.1.0/src/citeflow/billing.py

@@ -0,0 +1,29 @@
+"""Billing resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._http import HttpClient
+
+
+class BillingResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create_topup(
+        self,
+        *,
+        tier: str,
+        success_url: str,
+        cancel_url: str,
+    ) -> dict[str, Any]:
+        # Each call legitimately mints a fresh Stripe Checkout Session;
+        # auto Idempotency-Key would actively confuse partners.
+        envelope = self._http.request(
+            method="POST",
+            path="/billing/topup",
+            body={"tier": tier, "success_url": success_url, "cancel_url": cancel_url},
+            auto_idempotency=False,
+        )
+        return envelope["data"]

citeflow_python-0.1.0/src/citeflow/client.py

@@ -0,0 +1,44 @@
+"""Top-level Citeflow client.
+
+Usage:
+
+    from citeflow import Citeflow
+    client = Citeflow(api_key="ckf_…")
+    audit = client.audits.create(url="https://example.com", type="seo")
+    result = client.audits.wait_for_completion(audit["audit_id"])
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from ._http import HttpClient
+from .audits import AuditsResource
+from .balance import BalanceResource
+from .billing import BillingResource
+from .webhooks import WebhooksResource
+
+
+class Citeflow:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://citeflow.io/api/v1",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            session=session,
+        )
+        self.audits = AuditsResource(self._http)
+        self.balance = BalanceResource(self._http)
+        self.billing = BillingResource(self._http)
+        self.webhooks = WebhooksResource(self._http)

citeflow_python-0.1.0/src/citeflow/errors.py

@@ -0,0 +1,72 @@
+"""Exception hierarchy.
+
+All API-level errors raise CiteflowError carrying the stable `code`
+attribute. Branch on `code`, not on HTTP status — codes are versioned
+with the API path (`/api/v1`).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class CiteflowError(Exception):
+    """Raised on any non-2xx response from the CiteFlow API."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        status: int,
+        message: str,
+        request_id: str,
+        doc_url: str,
+        retry_after: Optional[int] = None,
+        required: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.retry_after = retry_after
+        self.required = required
+
+    @classmethod
+    def from_api_response(cls, status: int, body: dict[str, Any]) -> "CiteflowError":
+        err = body.get("error", {})
+        return cls(
+            code=err.get("code", "INTERNAL_ERROR"),
+            status=status,
+            message=err.get("message", "Unknown error"),
+            request_id=body.get("request_id", "unknown"),
+            doc_url=err.get("doc_url", "https://docs.citeflow.io/errors"),
+            retry_after=err.get("retryAfter"),
+            required=err.get("required"),
+        )
+
+    def __repr__(self) -> str:
+        return f"CiteflowError(code={self.code!r}, status={self.status}, request_id={self.request_id!r})"
+
+
+class CiteflowNetworkError(Exception):
+    """Raised on transport-layer failures (DNS, timeout, connection reset)."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class CiteflowTimeoutError(Exception):
+    """`wait_for_completion` exhausted its budget before reaching a terminal status."""
+
+    def __init__(self, audit_id: str, timeout_seconds: float) -> None:
+        super().__init__(
+            f"Audit {audit_id} did not reach terminal state within {timeout_seconds}s"
+        )
+        self.audit_id = audit_id
+        self.timeout_seconds = timeout_seconds
+
+
+class CiteflowSignatureError(Exception):
+    """Webhook signature verification failed."""

citeflow_python-0.1.0/src/citeflow/webhooks.py

@@ -0,0 +1,118 @@
+"""Webhook verification + replay."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping, Union
+
+from ._http import HttpClient
+from .errors import CiteflowSignatureError
+
+ID_HEADER = "x-citeflow-webhook-id"
+TIMESTAMP_HEADER = "x-citeflow-webhook-timestamp"
+SIGNATURE_HEADER = "x-citeflow-webhook-signature"
+
+HeaderInput = Mapping[str, Union[str, list[str]]]
+
+
+def _get(headers: HeaderInput, name: str) -> Union[str, None]:
+    """Case-insensitive header read across dict / Flask / FastAPI shapes."""
+    target = name.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            if isinstance(value, list):
+                return value[0] if value else None
+            return value
+    return None
+
+
+def verify_webhook_signature(
+    *,
+    raw_body: Union[str, bytes],
+    headers: HeaderInput,
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> None:
+    """Verify a CiteFlow webhook signature.
+
+    Raises CiteflowSignatureError on any mismatch / drift / missing header.
+    During the 7-day secret-rotation grace window the header may carry
+    comma-separated `v1=` values; any matching value succeeds.
+    """
+    event_id = _get(headers, ID_HEADER)
+    timestamp = _get(headers, TIMESTAMP_HEADER)
+    signature = _get(headers, SIGNATURE_HEADER)
+
+    if not event_id or not timestamp or not signature:
+        raise CiteflowSignatureError(
+            f"Missing webhook headers (id={bool(event_id)}, "
+            f"ts={bool(timestamp)}, sig={bool(signature)})"
+        )
+
+    try:
+        ts_num = int(timestamp)
+    except ValueError as exc:
+        raise CiteflowSignatureError("Webhook timestamp is not a number") from exc
+
+    skew = abs(int(time.time()) - ts_num)
+    if skew > tolerance_seconds:
+        raise CiteflowSignatureError(
+            f"Webhook timestamp drift {skew}s exceeds tolerance {tolerance_seconds}s"
+        )
+
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    signed_payload = f"{event_id}.{ts_num}.".encode("utf-8") + body_bytes
+    expected = base64.b64encode(
+        hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).digest()
+    ).decode("ascii")
+
+    candidates = [
+        part.strip()[3:]
+        for part in signature.split(",")
+        if part.strip().startswith("v1=")
+    ]
+    if not candidates:
+        raise CiteflowSignatureError("No v1= signature values present in header")
+
+    for cand in candidates:
+        if hmac.compare_digest(cand, expected):
+            return
+    raise CiteflowSignatureError("Webhook signature mismatch")
+
+
+def parse_webhook_event(
+    *,
+    raw_body: str,
+    headers: HeaderInput,
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> dict[str, Any]:
+    """Verify + JSON-parse in one call. Returns the event envelope dict."""
+    verify_webhook_signature(
+        raw_body=raw_body,
+        headers=headers,
+        secret=secret,
+        tolerance_seconds=tolerance_seconds,
+    )
+    return json.loads(raw_body)
+
+
+class WebhooksResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def replay(self, delivery_id: str) -> dict[str, Any]:
+        envelope = self._http.request(
+            method="POST",
+            path=f"/webhooks/deliveries/{delivery_id}/replay",
+            auto_idempotency=False,
+        )
+        return envelope["data"]
+
+    # Mirror the Node SDK's static helpers for symmetry.
+    verify = staticmethod(verify_webhook_signature)
+    parse_and_verify = staticmethod(parse_webhook_event)