aivisibilityskill 1.0.0__tar.gz

aivisibilityskill-1.0.0/.gitignore

@@ -0,0 +1,24 @@
+node_modules/
+.turbo/
+.wrangler/
+dist/
+coverage/
+*.log
+.DS_Store
+
+# secrets — never commit
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+.env
+.env.*
+!.env.example
+
+# review account passwords
+.review-credentials*
+
+# Python SDK
+packages/sdk-python/.venv/
+packages/sdk-python/dist/
+**/__pycache__/
+*.egg-info/

aivisibilityskill-1.0.0/LICENSE

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

aivisibilityskill-1.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: aivisibilityskill
+Version: 1.0.0
+Summary: Official Python client for the aivisibilityskill API: see how ChatGPT, Gemini, AI Overviews, Perplexity, Claude and Grok answer about any brand.
+Project-URL: Homepage, https://aivisibilityskill.com/sdk
+Project-URL: Documentation, https://api.aivisibilityskill.com/docs
+Author-email: aivisibilityskill <support@aivisibilityskill.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai overviews,ai visibility,chatgpt,generative engine optimization,geo,llm,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aivisibilityskill
+
+The official Python client for the [aivisibilityskill](https://aivisibilityskill.com) API. Ask ChatGPT, Gemini, Google AI Overviews and AI Mode, Perplexity, Claude and Grok about any brand, in any country, and get back what they said, who they cited and what to fix.
+
+- Safe retries: every check carries an idempotency key, so a retry is never charged twice.
+- Webhook signature verification included.
+- One dependency (httpx). Python 3.9+. Typed (`py.typed`).
+
+```sh
+pip install aivisibilityskill
+```
+
+## Quick start
+
+```python
+import os
+from aivisibilityskill import Aiv
+
+aiv = Aiv(api_key=os.environ["AIV_KEY"])  # aiv_live_... or aiv_test_... (free sample data)
+
+job = aiv.checks.create(
+    ["best invoicing app for freelancers"],
+    engines=["chatgpt", "gemini", "ai_overview", "perplexity"],
+    locale="en-US",
+)
+done = aiv.jobs.wait(job["id"])
+for answer in done["answers"]:
+    print(answer["engine"], [b["name"] for b in answer["brands"]])
+```
+
+Get a key at [app.aivisibilityskill.com](https://app.aivisibilityskill.com). Test keys (`aiv_test_...`) are free and return sample answers, so you can build without spending credits.
+
+## Building for your own customers
+
+```python
+aiv.checks.create(questions, customer="cus_8421", metadata={"workspace": "acme"})
+
+key = aiv.keys.create("acme", customer="cus_8421", allowed_ips=["203.0.113.0/24"])
+
+csv_text = aiv.usage.csv(from_="2026-11-01", to="2026-11-30", group_by="customer")
+
+# Everything stored for a customer, deleted (runs in the background):
+deletion = aiv.customers.delete_data("cus_8421")
+aiv.data_deletions.wait(deletion["id"])
+```
+
+## Thousands of answers at once
+
+```python
+batch = aiv.batches.create(
+    two_thousand_questions,
+    engines=["chatgpt", "ai_overviews"],
+    mode="batch",        # cheapest
+    max_age_hours=24,    # reuse answers from the last day at half price
+)
+done = aiv.batches.wait(batch["id"])  # or listen for the batch.completed webhook
+for job_id in done["checks"]:
+    job = aiv.jobs.get(job_id)
+```
+
+## Webhooks
+
+```python
+from aivisibilityskill import verify_webhook, WebhookVerificationError
+
+# Flask: request.get_data(), Django: request.body, FastAPI: await request.body()
+try:
+    event = verify_webhook(raw_body, request.headers, os.environ["AIV_WEBHOOK_SECRET"])
+except WebhookVerificationError:
+    return "", 400
+if event["type"] == "check.completed":
+    job = aiv.jobs.get(event["data"]["id"])
+```
+
+During a secret rotation, pass both secrets: `verify_webhook(body, headers, [new_secret, old_secret])`. Deliveries older than 5 minutes are refused as replays.
+
+## Lists
+
+Lists are paged. `iterate()` follows the pages for you:
+
+```python
+for job in aiv.jobs.iterate(customer="cus_8421"): ...
+for event in aiv.events.iterate(type="check.failed"): ...
+for entry in aiv.audit_log.iterate(): ...
+```
+
+## Errors
+
+Every failure raises `AivError` with the HTTP `status`, a stable `code` (`insufficient_credits`, `budget_exceeded`, `rate_limited`, ...), a readable `detail` and the `request_id` to quote to support.
+
+```python
+from aivisibilityskill import AivError
+try:
+    aiv.checks.create(questions)
+except AivError as err:
+    if err.code == "insufficient_credits": ...
+```
+
+GET requests and checks are retried on 429, 502, 503, 504 and network errors (twice by default, honouring `Retry-After`). Set `max_retries` and `timeout` in the constructor, or pass your own `httpx.Client`. Use it as a context manager (`with Aiv(...) as aiv:`) to close connections when done.
+
+## Everything else
+
+`aiv.projects` (tracking, schedules, visibility, competitors, sources, facts, history, site checks, research), `aiv.opportunities` and `aiv.fixes` (what to fix and proof it worked), `aiv.actions`, `aiv.webhooks`, `aiv.events`, `aiv.keys`, `aiv.account`, `aiv.locales`, `aiv.pricing()` and `aiv.estimate()`. Responses are the API's JSON as dicts. For anything not wrapped yet: `aiv.request("GET", "/v1/...")`.
+
+API reference: [api.aivisibilityskill.com/docs](https://api.aivisibilityskill.com/docs). Support: support@aivisibilityskill.com.
+
+MIT licensed.

aivisibilityskill-1.0.0/README.md

@@ -0,0 +1,107 @@
+# aivisibilityskill
+
+The official Python client for the [aivisibilityskill](https://aivisibilityskill.com) API. Ask ChatGPT, Gemini, Google AI Overviews and AI Mode, Perplexity, Claude and Grok about any brand, in any country, and get back what they said, who they cited and what to fix.
+
+- Safe retries: every check carries an idempotency key, so a retry is never charged twice.
+- Webhook signature verification included.
+- One dependency (httpx). Python 3.9+. Typed (`py.typed`).
+
+```sh
+pip install aivisibilityskill
+```
+
+## Quick start
+
+```python
+import os
+from aivisibilityskill import Aiv
+
+aiv = Aiv(api_key=os.environ["AIV_KEY"])  # aiv_live_... or aiv_test_... (free sample data)
+
+job = aiv.checks.create(
+    ["best invoicing app for freelancers"],
+    engines=["chatgpt", "gemini", "ai_overview", "perplexity"],
+    locale="en-US",
+)
+done = aiv.jobs.wait(job["id"])
+for answer in done["answers"]:
+    print(answer["engine"], [b["name"] for b in answer["brands"]])
+```
+
+Get a key at [app.aivisibilityskill.com](https://app.aivisibilityskill.com). Test keys (`aiv_test_...`) are free and return sample answers, so you can build without spending credits.
+
+## Building for your own customers
+
+```python
+aiv.checks.create(questions, customer="cus_8421", metadata={"workspace": "acme"})
+
+key = aiv.keys.create("acme", customer="cus_8421", allowed_ips=["203.0.113.0/24"])
+
+csv_text = aiv.usage.csv(from_="2026-11-01", to="2026-11-30", group_by="customer")
+
+# Everything stored for a customer, deleted (runs in the background):
+deletion = aiv.customers.delete_data("cus_8421")
+aiv.data_deletions.wait(deletion["id"])
+```
+
+## Thousands of answers at once
+
+```python
+batch = aiv.batches.create(
+    two_thousand_questions,
+    engines=["chatgpt", "ai_overviews"],
+    mode="batch",        # cheapest
+    max_age_hours=24,    # reuse answers from the last day at half price
+)
+done = aiv.batches.wait(batch["id"])  # or listen for the batch.completed webhook
+for job_id in done["checks"]:
+    job = aiv.jobs.get(job_id)
+```
+
+## Webhooks
+
+```python
+from aivisibilityskill import verify_webhook, WebhookVerificationError
+
+# Flask: request.get_data(), Django: request.body, FastAPI: await request.body()
+try:
+    event = verify_webhook(raw_body, request.headers, os.environ["AIV_WEBHOOK_SECRET"])
+except WebhookVerificationError:
+    return "", 400
+if event["type"] == "check.completed":
+    job = aiv.jobs.get(event["data"]["id"])
+```
+
+During a secret rotation, pass both secrets: `verify_webhook(body, headers, [new_secret, old_secret])`. Deliveries older than 5 minutes are refused as replays.
+
+## Lists
+
+Lists are paged. `iterate()` follows the pages for you:
+
+```python
+for job in aiv.jobs.iterate(customer="cus_8421"): ...
+for event in aiv.events.iterate(type="check.failed"): ...
+for entry in aiv.audit_log.iterate(): ...
+```
+
+## Errors
+
+Every failure raises `AivError` with the HTTP `status`, a stable `code` (`insufficient_credits`, `budget_exceeded`, `rate_limited`, ...), a readable `detail` and the `request_id` to quote to support.
+
+```python
+from aivisibilityskill import AivError
+try:
+    aiv.checks.create(questions)
+except AivError as err:
+    if err.code == "insufficient_credits": ...
+```
+
+GET requests and checks are retried on 429, 502, 503, 504 and network errors (twice by default, honouring `Retry-After`). Set `max_retries` and `timeout` in the constructor, or pass your own `httpx.Client`. Use it as a context manager (`with Aiv(...) as aiv:`) to close connections when done.
+
+## Everything else
+
+`aiv.projects` (tracking, schedules, visibility, competitors, sources, facts, history, site checks, research), `aiv.opportunities` and `aiv.fixes` (what to fix and proof it worked), `aiv.actions`, `aiv.webhooks`, `aiv.events`, `aiv.keys`, `aiv.account`, `aiv.locales`, `aiv.pricing()` and `aiv.estimate()`. Responses are the API's JSON as dicts. For anything not wrapped yet: `aiv.request("GET", "/v1/...")`.
+
+API reference: [api.aivisibilityskill.com/docs](https://api.aivisibilityskill.com/docs). Support: support@aivisibilityskill.com.
+
+MIT licensed.

aivisibilityskill-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aivisibilityskill"
+version = "1.0.0"
+description = "Official Python client for the aivisibilityskill API: see how ChatGPT, Gemini, AI Overviews, Perplexity, Claude and Grok answer about any brand."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "aivisibilityskill", email = "support@aivisibilityskill.com" }]
+keywords = ["ai visibility", "geo", "generative engine optimization", "chatgpt", "ai overviews", "llm", "sdk"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.urls]
+Homepage = "https://aivisibilityskill.com/sdk"
+Documentation = "https://api.aivisibilityskill.com/docs"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aivisibilityskill"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

aivisibilityskill-1.0.0/src/aivisibilityskill/__init__.py

@@ -0,0 +1,13 @@
+"""Official Python client for the aivisibilityskill API.
+
+    from aivisibilityskill import Aiv
+    aiv = Aiv(api_key="aiv_test_...")
+    job = aiv.checks.create(["best invoicing app for freelancers"])
+    done = aiv.jobs.wait(job["id"])
+"""
+
+from ._client import Aiv, AivError
+from ._version import __version__
+from ._webhooks import WebhookVerificationError, verify_webhook
+
+__all__ = ["Aiv", "AivError", "WebhookVerificationError", "verify_webhook", "__version__"]

aivisibilityskill-1.0.0/src/aivisibilityskill/_client.py

@@ -0,0 +1,529 @@
+"""The aivisibilityskill API client."""
+
+from __future__ import annotations
+
+import re
+import time
+import uuid
+from typing import Any, Callable, Dict, Iterator, Mapping, Optional, Sequence
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+from ._webhooks import verify_webhook
+
+JSON = Dict[str, Any]
+_RETRYABLE = {429, 502, 503, 504}
+_KEY = re.compile(r"^aiv_(live|test)_")
+
+
+def _p(value: str) -> str:
+    return quote(str(value), safe="")
+
+
+class AivError(Exception):
+    """An API error. ``code`` is stable (insufficient_credits, budget_exceeded, rate_limited, ...)."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        detail: Optional[str],
+        request_id: Optional[str],
+        body: Mapping[str, Any],
+    ) -> None:
+        super().__init__(f"{status} {code}" + (f": {detail}" if detail else ""))
+        self.status = status
+        self.code = code
+        self.detail = detail
+        self.request_id = request_id
+        self.body = dict(body)
+
+
+class _Resource:
+    def __init__(self, client: "Aiv") -> None:
+        self._c = client
+
+
+def _pages(fetch: Callable[[Optional[Any]], JSON], key: str) -> Iterator[JSON]:
+    before: Optional[Any] = None
+    while True:
+        page = fetch(before)
+        for item in page.get(key) or []:
+            yield item
+        before = page.get("next")
+        if before in (None, ""):
+            return
+
+
+def _wait(get: Callable[[], JSON], done: Callable[[JSON], bool], timeout: float, interval: Callable[[JSON], float]) -> JSON:
+    deadline = time.monotonic() + timeout
+    while True:
+        item = get()
+        if done(item) or time.monotonic() >= deadline:
+            return item
+        time.sleep(max(0.0, min(interval(item), deadline - time.monotonic())))
+
+
+def _analytics(question_id: Optional[str], engines: Optional[Sequence[str]], days: Optional[int]) -> JSON:
+    return {
+        "question_id": question_id,
+        "engines": ",".join(engines) if engines else None,
+        "days": days,
+    }
+
+
+class Account(_Resource):
+    def get(self) -> JSON:
+        return self._c.request("GET", "/v1/account")
+
+    def update(self, **fields: Any) -> JSON:
+        """For example ``update(balance_alert_below=10_000)``."""
+        return self._c.request("PATCH", "/v1/account", json=fields)
+
+
+class Locales(_Resource):
+    def list(self) -> JSON:
+        return self._c.request("GET", "/v1/locales")
+
+    def get(self, locale: str) -> JSON:
+        return self._c.request("GET", f"/v1/locales/{_p(locale)}")
+
+
+class Checks(_Resource):
+    def create(
+        self,
+        questions: Sequence[str],
+        *,
+        idempotency_key: Optional[str] = None,
+        **fields: Any,
+    ) -> JSON:
+        """Starts a check: ``create(["best crm"], engines=["chatgpt"], locale="en-US", customer="cus_1")``.
+
+        A retry with the same idempotency key is never charged twice (one is made for you).
+        """
+        return self._c.request(
+            "POST",
+            "/v1/checks",
+            json={"questions": list(questions), **fields},
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+
+
+class Batches(_Resource):
+    def create(self, questions: Sequence[str], *, idempotency_key: Optional[str] = None, **fields: Any) -> JSON:
+        """Thousands of answers in one request, run as checks of up to 200 as your plan's
+        concurrency allows: ``create(questions, engines=["chatgpt"], mode="batch")``. Retrying
+        with the same idempotency key never starts a second batch."""
+        return self._c.request(
+            "POST",
+            "/v1/batches",
+            json={"questions": list(questions), **fields},
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+
+    def get(self, batch_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/batches/{_p(batch_id)}")
+
+    def list(self, *, limit: Optional[int] = None, before: Optional[str] = None, customer: Optional[str] = None) -> JSON:
+        return self._c.request("GET", "/v1/batches", params={"limit": limit, "before": before, "customer": customer})
+
+    def iterate(self, *, customer: Optional[str] = None, limit: Optional[int] = None) -> Iterator[JSON]:
+        return _pages(lambda b: self.list(limit=limit, before=b, customer=customer), "batches")
+
+    def cancel(self, batch_id: str) -> JSON:
+        """Stops starting new checks; running ones finish and nothing more is charged."""
+        return self._c.request("POST", f"/v1/batches/{_p(batch_id)}/cancel")
+
+    def wait(self, batch_id: str, *, timeout: float = 7200) -> JSON:
+        """Polls until the batch completes or stops."""
+        return _wait(
+            lambda: self.get(batch_id),
+            lambda b: b.get("poll_after_seconds") is None,
+            timeout,
+            lambda b: float(b.get("poll_after_seconds") or 30),
+        )
+
+
+class Jobs(_Resource):
+    def get(self, job_id: str, *, text: bool = True) -> JSON:
+        return self._c.request("GET", f"/v1/jobs/{_p(job_id)}", params={"text": None if text else "false"})
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        before: Optional[str] = None,
+        project_id: Optional[str] = None,
+        customer: Optional[str] = None,
+    ) -> JSON:
+        return self._c.request(
+            "GET",
+            "/v1/jobs",
+            params={"limit": limit, "before": before, "project_id": project_id, "customer": customer},
+        )
+
+    def iterate(self, *, project_id: Optional[str] = None, customer: Optional[str] = None, limit: Optional[int] = None) -> Iterator[JSON]:
+        """Every job, newest first, across pages."""
+        return _pages(lambda b: self.list(limit=limit, before=b, project_id=project_id, customer=customer), "jobs")
+
+    def wait(self, job_id: str, *, timeout: float = 600) -> JSON:
+        """Polls at the pace the API suggests until the job finishes (or ``timeout`` seconds)."""
+        return _wait(
+            lambda: self.get(job_id),
+            lambda j: bool(j.get("finished_at")) or j.get("poll_after_seconds") is None,
+            timeout,
+            lambda j: float(j.get("poll_after_seconds") or 1),
+        )
+
+
+class Answers(_Resource):
+    def get(self, answer_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/answers/{_p(answer_id)}")
+
+    def receipt(self, answer_id: str) -> Any:
+        """The engine's raw response, as stored when the answer was collected."""
+        return self._c.request("GET", f"/v1/answers/{_p(answer_id)}/receipt")
+
+
+class Projects(_Resource):
+    def create(self, *, idempotency_key: Optional[str] = None, **fields: Any) -> JSON:
+        """``create(name="Acme", brand={"name": "Acme", "domains": ["acme.com"]}, questions=[...])``."""
+        return self._c.request("POST", "/v1/projects", json=fields, idempotency_key=idempotency_key or str(uuid.uuid4()))
+
+    def list(self, *, customer: Optional[str] = None) -> JSON:
+        return self._c.request("GET", "/v1/projects", params={"customer": customer})
+
+    def get(self, project_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/projects/{_p(project_id)}")
+
+    def update(self, project_id: str, **fields: Any) -> JSON:
+        return self._c.request("PATCH", f"/v1/projects/{_p(project_id)}", json=fields)
+
+    def archive(self, project_id: str) -> None:
+        self._c.request("DELETE", f"/v1/projects/{_p(project_id)}")
+
+    def _analytics(self, kind: str, project_id: str, question_id: Optional[str], engines: Optional[Sequence[str]], days: Optional[int], **extra: Any) -> JSON:
+        return self._c.request(
+            "GET",
+            f"/v1/projects/{_p(project_id)}/{kind}",
+            params={**_analytics(question_id, engines, days), **extra},
+        )
+
+    def visibility(self, project_id: str, *, question_id: Optional[str] = None, engines: Optional[Sequence[str]] = None, days: Optional[int] = None) -> JSON:
+        return self._analytics("visibility", project_id, question_id, engines, days)
+
+    def competitors(self, project_id: str, *, question_id: Optional[str] = None, engines: Optional[Sequence[str]] = None, days: Optional[int] = None) -> JSON:
+        return self._analytics("competitors", project_id, question_id, engines, days)
+
+    def sources(self, project_id: str, *, question_id: Optional[str] = None, engines: Optional[Sequence[str]] = None, days: Optional[int] = None) -> JSON:
+        return self._analytics("sources", project_id, question_id, engines, days)
+
+    def facts(self, project_id: str, *, question_id: Optional[str] = None, engines: Optional[Sequence[str]] = None, days: Optional[int] = None) -> JSON:
+        return self._analytics("facts", project_id, question_id, engines, days)
+
+    def history(self, project_id: str, *, question_id: Optional[str] = None, engines: Optional[Sequence[str]] = None, days: Optional[int] = None, bucket: Optional[str] = None) -> JSON:
+        return self._analytics("history", project_id, question_id, engines, days, bucket=bucket)
+
+    def site_check(self, project_id: str, **fields: Any) -> JSON:
+        """Paid action: robots.txt, llms.txt, sitemaps and key pages, as AI crawlers see them."""
+        return self._c.request("POST", f"/v1/projects/{_p(project_id)}/site-check", json=fields)
+
+    def research(self, project_id: str, **fields: Any) -> JSON:
+        """Paid action: what ranks on Google for a question and what those pages say."""
+        return self._c.request("POST", f"/v1/projects/{_p(project_id)}/research", json=fields)
+
+    def find_opportunities(self, project_id: str, **fields: Any) -> JSON:
+        """Paid action: ranks what to fix first from the project's answers and checks."""
+        return self._c.request("POST", f"/v1/projects/{_p(project_id)}/opportunities", json=fields)
+
+    def opportunities(self, project_id: str, *, status: Optional[str] = None) -> JSON:
+        return self._c.request("GET", f"/v1/projects/{_p(project_id)}/opportunities", params={"status": status})
+
+
+class Opportunities(_Resource):
+    def get(self, opportunity_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/opportunities/{_p(opportunity_id)}")
+
+    def update(self, opportunity_id: str, **fields: Any) -> JSON:
+        return self._c.request("PATCH", f"/v1/opportunities/{_p(opportunity_id)}", json=fields)
+
+    def brief(self, opportunity_id: str, **fields: Any) -> JSON:
+        """Paid action: a step-by-step fix brief for one opportunity."""
+        return self._c.request("POST", f"/v1/opportunities/{_p(opportunity_id)}/brief", json=fields)
+
+    def record_fix(self, opportunity_id: str, **fields: Any) -> JSON:
+        """Records a fix you shipped; it's verified on the site and later in AI answers."""
+        return self._c.request("POST", f"/v1/opportunities/{_p(opportunity_id)}/fixes", json=fields)
+
+
+class Fixes(_Resource):
+    def get(self, fix_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/fixes/{_p(fix_id)}")
+
+    def verify(self, fix_id: str, **fields: Any) -> JSON:
+        return self._c.request("POST", f"/v1/fixes/{_p(fix_id)}/verify", json=fields)
+
+
+class Actions(_Resource):
+    def get(self, job_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/actions/{_p(job_id)}")
+
+    def wait(self, job_id: str, *, timeout: float = 600) -> JSON:
+        """Polls a paid action (site check, research, brief...) until it's done."""
+        return _wait(
+            lambda: self.get(job_id),
+            lambda a: a.get("poll_after_seconds") is None,
+            timeout,
+            lambda a: float(a.get("poll_after_seconds") or 1),
+        )
+
+
+class Keys(_Resource):
+    def list(self, *, limit: Optional[int] = None, before: Optional[str] = None, customer: Optional[str] = None) -> JSON:
+        return self._c.request("GET", "/v1/keys", params={"limit": limit, "before": before, "customer": customer})
+
+    def iterate(self, *, customer: Optional[str] = None, limit: Optional[int] = None) -> Iterator[JSON]:
+        return _pages(lambda b: self.list(limit=limit, before=b, customer=customer), "keys")
+
+    def create(self, name: str, **fields: Any) -> JSON:
+        """The response's ``secret`` is shown once. ``customer=`` locks the key to one customer,
+        ``allowed_ips=["203.0.113.0/24"]`` to your servers."""
+        return self._c.request("POST", "/v1/keys", json={"name": name, **fields})
+
+    def update(self, key_id: str, **fields: Any) -> JSON:
+        return self._c.request("PATCH", f"/v1/keys/{_p(key_id)}", json=fields)
+
+    def revoke(self, key_id: str) -> None:
+        self._c.request("DELETE", f"/v1/keys/{_p(key_id)}")
+
+
+class UsageReports(_Resource):
+    def _params(self, **q: Any) -> JSON:
+        return {k: v for k, v in q.items() if v is not None}
+
+    def get(self, *, from_: Optional[str] = None, to: Optional[str] = None, group_by: Optional[str] = None, customer: Optional[str] = None, project_id: Optional[str] = None) -> JSON:
+        return self._c.request(
+            "GET",
+            "/v1/usage",
+            params=self._params(**{"from": from_, "to": to, "group_by": group_by, "customer": customer, "project_id": project_id}),
+        )
+
+    def csv(self, *, from_: Optional[str] = None, to: Optional[str] = None, group_by: Optional[str] = None, customer: Optional[str] = None, project_id: Optional[str] = None) -> str:
+        """The same report as CSV text, ready for a spreadsheet or an invoice."""
+        return self._c.request(
+            "GET",
+            "/v1/usage",
+            params=self._params(**{"from": from_, "to": to, "group_by": group_by, "customer": customer, "project_id": project_id, "format": "csv"}),
+            text=True,
+        )
+
+
+class Deliveries(_Resource):
+    def list(self, webhook_id: str, *, status: Optional[str] = None, limit: Optional[int] = None, before: Optional[str] = None) -> JSON:
+        return self._c.request("GET", f"/v1/webhooks/{_p(webhook_id)}/deliveries", params={"status": status, "limit": limit, "before": before})
+
+    def get(self, webhook_id: str, delivery_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/webhooks/{_p(webhook_id)}/deliveries/{_p(delivery_id)}")
+
+    def resend(self, webhook_id: str, delivery_id: str) -> JSON:
+        return self._c.request("POST", f"/v1/webhooks/{_p(webhook_id)}/deliveries/{_p(delivery_id)}/resend")
+
+
+class Webhooks(_Resource):
+    def __init__(self, client: "Aiv") -> None:
+        super().__init__(client)
+        self.deliveries = Deliveries(client)
+
+    def list(self) -> JSON:
+        return self._c.request("GET", "/v1/webhooks")
+
+    def create(self, url: str, **fields: Any) -> JSON:
+        """The response's ``secret`` (whsec_...) is shown once: store it to verify deliveries."""
+        return self._c.request("POST", "/v1/webhooks", json={"url": url, **fields})
+
+    def get(self, webhook_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/webhooks/{_p(webhook_id)}")
+
+    def update(self, webhook_id: str, **fields: Any) -> JSON:
+        return self._c.request("PATCH", f"/v1/webhooks/{_p(webhook_id)}", json=fields)
+
+    def delete(self, webhook_id: str) -> None:
+        self._c.request("DELETE", f"/v1/webhooks/{_p(webhook_id)}")
+
+    def rotate_secret(self, webhook_id: str, **fields: Any) -> JSON:
+        """A new secret; the old one keeps working for 24 hours."""
+        return self._c.request("POST", f"/v1/webhooks/{_p(webhook_id)}/rotate-secret", json=fields)
+
+    def test(self, webhook_id: str, **fields: Any) -> JSON:
+        """Sends a ``ping`` event to this endpoint only."""
+        return self._c.request("POST", f"/v1/webhooks/{_p(webhook_id)}/test", json=fields)
+
+    def recover(self, webhook_id: str, since: str) -> JSON:
+        """Re-sends everything the endpoint missed since ``since`` (ISO date), and re-enables it."""
+        return self._c.request("POST", f"/v1/webhooks/{_p(webhook_id)}/recover", json={"since": since})
+
+
+class Events(_Resource):
+    def list(self, *, type: Optional[str] = None, customer: Optional[str] = None, limit: Optional[int] = None, before: Optional[str] = None, after: Optional[str] = None) -> JSON:  # noqa: A002
+        return self._c.request("GET", "/v1/events", params={"type": type, "customer": customer, "limit": limit, "before": before, "after": after})
+
+    def get(self, event_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/events/{_p(event_id)}")
+
+    def iterate(self, *, type: Optional[str] = None, customer: Optional[str] = None, limit: Optional[int] = None) -> Iterator[JSON]:  # noqa: A002
+        """Every event, newest first (the last 30 days)."""
+        return _pages(lambda b: self.list(type=type, customer=customer, limit=limit, before=b), "events")
+
+
+class AuditLog(_Resource):
+    def list(self, *, limit: Optional[int] = None, before: Optional[int] = None, action: Optional[str] = None, target_id: Optional[str] = None) -> JSON:
+        return self._c.request("GET", "/v1/audit-log", params={"limit": limit, "before": before, "action": action, "target_id": target_id})
+
+    def iterate(self, *, action: Optional[str] = None, target_id: Optional[str] = None, limit: Optional[int] = None) -> Iterator[JSON]:
+        return _pages(lambda b: self.list(limit=limit, before=b, action=action, target_id=target_id), "entries")
+
+
+class Customers(_Resource):
+    def delete_data(self, customer: str) -> JSON:
+        """Deletes everything stored for one of your customers (irreversible). Runs in the
+        background: poll ``data_deletions.wait(id)``."""
+        return self._c.request("POST", f"/v1/customers/{_p(customer)}/delete-data", json={"confirm": True})
+
+
+class DataDeletions(_Resource):
+    def get(self, deletion_id: str) -> JSON:
+        return self._c.request("GET", f"/v1/data-deletions/{_p(deletion_id)}")
+
+    def wait(self, deletion_id: str, *, timeout: float = 1800, interval: float = 30) -> JSON:
+        return _wait(
+            lambda: self.get(deletion_id),
+            lambda d: d.get("status") in ("completed", "failed"),
+            timeout,
+            lambda _d: interval,
+        )
+
+
+class Aiv:
+    """aivisibilityskill API client.
+
+        from aivisibilityskill import Aiv
+        aiv = Aiv(api_key=os.environ["AIV_KEY"])
+        job = aiv.checks.create(["best invoicing app for freelancers"], engines=["chatgpt", "gemini"])
+        done = aiv.jobs.wait(job["id"])
+
+    GETs and checks are retried on 429/502/503/504 and network errors (``max_retries``, default
+    2), honouring Retry-After. Every check carries an idempotency key, so a retry never charges
+    twice. Errors raise AivError with the API's stable ``code``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.aivisibilityskill.com",
+        max_retries: int = 2,
+        timeout: float = 120.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not isinstance(api_key, str) or not _KEY.match(api_key):
+            raise ValueError("api_key must start with aiv_live_ or aiv_test_")
+        self._key = api_key
+        self._base = base_url.rstrip("/")
+        self._retries = max(0, max_retries)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+        self.account = Account(self)
+        self.locales = Locales(self)
+        self.checks = Checks(self)
+        self.jobs = Jobs(self)
+        self.batches = Batches(self)
+        self.answers = Answers(self)
+        self.projects = Projects(self)
+        self.opportunities = Opportunities(self)
+        self.fixes = Fixes(self)
+        self.actions = Actions(self)
+        self.keys = Keys(self)
+        self.usage = UsageReports(self)
+        self.webhooks = Webhooks(self)
+        self.events = Events(self)
+        self.audit_log = AuditLog(self)
+        self.customers = Customers(self)
+        self.data_deletions = DataDeletions(self)
+
+    verify_webhook = staticmethod(verify_webhook)
+
+    def __enter__(self) -> "Aiv":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def pricing(self) -> JSON:
+        return self.request("GET", "/v1/pricing")
+
+    def estimate(self, questions: Sequence[str], **fields: Any) -> JSON:
+        """What a check would cost, and whether this key may run it. Free."""
+        return self.request("POST", "/v1/estimate", json={"questions": list(questions), **fields})
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        text: bool = False,
+    ) -> Any:
+        """Any endpoint, for ones this version doesn't wrap yet."""
+        query = {k: ("true" if v is True else "false" if v is False else v) for k, v in (params or {}).items() if v is not None}
+        headers = {
+            "Authorization": f"Bearer {self._key}",
+            "Accept": "text/csv" if text else "application/json",
+            "User-Agent": f"aivisibilityskill-python/{__version__}",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        retryable = method == "GET" or idempotency_key is not None
+        attempt = 0
+        while True:
+            try:
+                res = self._http.request(method, self._base + path, params=query, json=json, headers=headers)
+            except httpx.TransportError:
+                if retryable and attempt < self._retries:
+                    time.sleep(0.5 * 2**attempt)
+                    attempt += 1
+                    continue
+                raise
+            if res.is_success:
+                if res.status_code == 204:
+                    return None
+                return res.text if text else res.json()
+            if retryable and res.status_code in _RETRYABLE and attempt < self._retries:
+                after = res.headers.get("Retry-After", "")
+                delay = min(float(after), 60.0) if after.replace(".", "", 1).isdigit() and float(after) > 0 else float(2**attempt)
+                time.sleep(delay)
+                attempt += 1
+                continue
+            try:
+                body = res.json()
+            except ValueError:
+                body = {}
+            if not isinstance(body, dict):
+                body = {}
+            raise AivError(
+                res.status_code,
+                body.get("code") if isinstance(body.get("code"), str) else "http_error",
+                body.get("detail") if isinstance(body.get("detail"), str) else None,
+                body.get("request_id") if isinstance(body.get("request_id"), str) else res.headers.get("X-Request-Id"),
+                body,
+            )
+
+
+__all__ = ["Aiv", "AivError", "JSON"]

aivisibilityskill-1.0.0/src/aivisibilityskill/_version.py

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

aivisibilityskill-1.0.0/src/aivisibilityskill/_webhooks.py

@@ -0,0 +1,96 @@
+"""Webhook signature verification (Standard Webhooks, https://www.standardwebhooks.com)."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Iterable, Mapping, Optional, Sequence, Union
+
+TOLERANCE_SECONDS = 300
+
+
+class WebhookVerificationError(Exception):
+    """The delivery isn't from aivisibilityskill, was changed, or is a replay."""
+
+
+def _header(headers: Any, name: str) -> Optional[str]:
+    getter = getattr(headers, "get", None)
+    if getter is not None and not isinstance(headers, Mapping):
+        value = getter(name)
+        return None if value is None else str(value)
+    for key, value in dict(headers).items():
+        if str(key).lower() == name:
+            if isinstance(value, (list, tuple)):
+                return str(value[0]) if value else None
+            return None if value is None else str(value)
+    return None
+
+
+def _secret_bytes(secret: str) -> bytes:
+    raw = secret[len("whsec_") :] if secret.startswith("whsec_") else secret
+    try:
+        key = base64.b64decode(raw, validate=True)
+    except Exception as err:  # noqa: BLE001
+        raise WebhookVerificationError("That webhook secret isn't valid (expected whsec_...).") from err
+    if len(key) < 16:
+        # An empty or tiny key would let anyone forge a signature.
+        raise WebhookVerificationError("That webhook secret isn't valid (expected whsec_...).")
+    return key
+
+
+def _signatures(header: str) -> Iterable[bytes]:
+    for part in header.split(" "):
+        version, _, value = part.partition(",")
+        if version != "v1" or not value:
+            continue
+        try:
+            yield base64.b64decode(value, validate=True)
+        except Exception:  # noqa: BLE001
+            continue
+
+
+def verify_webhook(
+    body: Union[str, bytes],
+    headers: Any,
+    secret: Union[str, Sequence[str]],
+    *,
+    tolerance_seconds: int = TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> dict:
+    """Checks a delivery's signature and returns the parsed event.
+
+    Pass the raw request body exactly as received (before JSON parsing) and the request headers
+    (a dict, or any object with ``.get``). During a secret rotation pass both secrets as a list.
+    Raises WebhookVerificationError for a bad signature, a missing header or a timestamp more
+    than 5 minutes off.
+
+        event = verify_webhook(request.body, request.headers, os.environ["AIV_WEBHOOK_SECRET"])
+        if event["type"] == "check.completed": ...
+    """
+    text = body.decode("utf-8") if isinstance(body, (bytes, bytearray)) else body
+    msg_id = _header(headers, "webhook-id")
+    timestamp = _header(headers, "webhook-timestamp")
+    signature = _header(headers, "webhook-signature")
+    if not msg_id or not timestamp or not signature:
+        raise WebhookVerificationError(
+            "Missing webhook-id, webhook-timestamp or webhook-signature header."
+        )
+    if not timestamp.isdigit():
+        raise WebhookVerificationError("Bad webhook-timestamp.")
+    current = time.time() if now is None else now
+    if abs(current - int(timestamp)) > tolerance_seconds:
+        raise WebhookVerificationError("Timestamp too old or in the future (possible replay).")
+    signed = f"{msg_id}.{timestamp}.{text}".encode("utf-8")
+    given = list(_signatures(signature))
+    secrets = [secret] if isinstance(secret, str) else list(secret)
+    for s in secrets:
+        expected = hmac.new(_secret_bytes(s), signed, hashlib.sha256).digest()
+        if any(hmac.compare_digest(expected, g) for g in given):
+            try:
+                return json.loads(text)
+            except ValueError as err:
+                raise WebhookVerificationError("The body isn't JSON.") from err
+    raise WebhookVerificationError("No signature matches this secret.")

aivisibilityskill-1.0.0/tests/signing_vector.json

@@ -0,0 +1,9 @@
+{
+  "secret": "whsec_+t4MGGyo+JRFitNHxDOuM9A7onK222XBs0KtHP5WvhQ=",
+  "other": "whsec_C0mtcEamIZA8tqUhP20/Q9giEDpCF2hlxrLUI8wBBUI=",
+  "body": "{\"id\":\"evt_vec\",\"type\":\"check.completed\",\"timestamp\":\"2030-01-01T00:00:00.000Z\",\"sandbox\":false,\"data\":{\"id\":\"job_vec\"}}",
+  "ts": 1893456000,
+  "id": "evt_vec",
+  "sig": "v1,0FbJHa49Y+z3wi2IR+xHrugWUvYRqnfH23A/B+475Zg=",
+  "both": "v1,+Jxq04BhLDxhKUPEWenAXlsdV+9KJ73UmzTBMJAHTXk= v1,0FbJHa49Y+z3wi2IR+xHrugWUvYRqnfH23A/B+475Zg="
+}

aivisibilityskill-1.0.0/tests/test_client.py

@@ -0,0 +1,236 @@
+import json
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+
+from aivisibilityskill import Aiv, AivError, WebhookVerificationError, verify_webhook
+
+VECTOR = json.loads((Path(__file__).parent / "signing_vector.json").read_text())
+
+
+def client(handler, **kw):
+    return Aiv(
+        api_key="aiv_test_abc",
+        base_url="https://api.test/",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+        **kw,
+    )
+
+
+def test_rejects_bad_keys():
+    with pytest.raises(ValueError):
+        Aiv(api_key="sk_123")
+
+
+def test_sends_auth_idempotency_and_json(monkeypatch):
+    seen = []
+
+    def handler(req: httpx.Request):
+        seen.append(req)
+        return httpx.Response(202, json={"id": "job_1", "status": "running"})
+
+    aiv = client(handler)
+    job = aiv.checks.create(["best crm"], engines=["chatgpt"], customer="cus_1")
+    assert job["id"] == "job_1"
+    req = seen[0]
+    assert req.url == "https://api.test/v1/checks"
+    assert req.headers["authorization"] == "Bearer aiv_test_abc"
+    assert req.headers["user-agent"].startswith("aivisibilityskill-python/")
+    assert len(req.headers["idempotency-key"]) == 36
+    assert json.loads(req.content) == {"questions": ["best crm"], "engines": ["chatgpt"], "customer": "cus_1"}
+
+
+def test_retries_safe_requests_with_the_same_idempotency_key(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    keys = []
+
+    def handler(req: httpx.Request):
+        keys.append(req.headers.get("idempotency-key"))
+        if len(keys) < 3:
+            return httpx.Response(503, json={"code": "vendor_unavailable"}, headers={"Retry-After": "1"})
+        return httpx.Response(202, json={"id": "job_2"})
+
+    aiv = client(handler)
+    assert aiv.checks.create(["q"])["id"] == "job_2"
+    assert len(keys) == 3 and len(set(keys)) == 1  # one charge, whatever the retries
+
+
+def test_never_retries_unkeyed_writes(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    calls = []
+
+    def handler(req):
+        calls.append(req)
+        return httpx.Response(503, json={"code": "vendor_unavailable", "detail": "down"})
+
+    with pytest.raises(AivError) as err:
+        client(handler).keys.create("k")
+    assert len(calls) == 1
+    assert err.value.status == 503 and err.value.code == "vendor_unavailable"
+
+
+def test_retries_network_errors_on_gets(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    n = {"i": 0}
+
+    def handler(req):
+        n["i"] += 1
+        if n["i"] == 1:
+            raise httpx.ConnectError("boom", request=req)
+        return httpx.Response(200, json={"account": {"plan": "pro"}})
+
+    assert client(handler).account.get()["account"]["plan"] == "pro"
+    assert n["i"] == 2
+
+
+def test_errors_carry_code_detail_and_request_id():
+    def handler(req):
+        return httpx.Response(
+            402,
+            json={"code": "insufficient_credits", "detail": "Needs 50.", "request_id": "req_1", "credits": 50},
+        )
+
+    with pytest.raises(AivError) as err:
+        client(handler).checks.create(["q"])
+    e = err.value
+    assert (e.status, e.code, e.detail, e.request_id) == (402, "insufficient_credits", "Needs 50.", "req_1")
+    assert e.body["credits"] == 50
+    assert "insufficient_credits" in str(e)
+
+
+def test_non_json_errors():
+    with pytest.raises(AivError) as err:
+        client(lambda req: httpx.Response(500, text="oops", headers={"X-Request-Id": "r9"})).pricing()
+    assert err.value.code == "http_error" and err.value.request_id == "r9"
+
+
+def test_pages_follow_next_and_build_query():
+    pages = {
+        None: {"keys": [{"id": "k1"}, {"id": "k2"}], "next": "k2"},
+        "k2": {"keys": [{"id": "k3"}], "next": None},
+    }
+    urls = []
+
+    def handler(req: httpx.Request):
+        urls.append(str(req.url))
+        return httpx.Response(200, json=pages[req.url.params.get("before")])
+
+    ids = [k["id"] for k in client(handler).keys.iterate(customer="c1", limit=2)]
+    assert ids == ["k1", "k2", "k3"]
+    assert "customer=c1" in urls[0] and "limit=2" in urls[0] and "before" not in urls[0]
+
+
+def test_wait_polls_until_finished(monkeypatch):
+    sleeps = []
+    monkeypatch.setattr("time.sleep", lambda s: sleeps.append(s))
+    states = iter(
+        [
+            {"id": "j", "finished_at": None, "poll_after_seconds": 3},
+            {"id": "j", "finished_at": "2030-01-01", "poll_after_seconds": None},
+        ]
+    )
+    done = client(lambda req: httpx.Response(200, json=next(states))).jobs.wait("j")
+    assert done["finished_at"] and sleeps == [3.0]
+
+
+def test_usage_csv_and_path_escaping():
+    seen = []
+
+    def handler(req):
+        seen.append(req)
+        if req.url.path == "/v1/usage":
+            return httpx.Response(200, text="day,credits\n2030-01-01,5\n", headers={"Content-Type": "text/csv"})
+        return httpx.Response(202, json={"id": "del_1", "status": "pending"})
+
+    aiv = client(handler)
+    assert aiv.usage.csv(group_by="day").startswith("day,credits")
+    assert seen[0].url.params["format"] == "csv" and seen[0].headers["accept"] == "text/csv"
+    aiv.customers.delete_data("cus/../x y")
+    assert seen[1].url.raw_path == b"/v1/customers/cus%2F..%2Fx%20y/delete-data"
+    assert json.loads(seen[1].content) == {"confirm": True}
+
+
+def test_batches_create_with_an_idempotency_key_and_wait(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    seen = []
+    states = iter([{"id": "bat_1", "poll_after_seconds": 30}, {"id": "bat_1", "poll_after_seconds": None, "status": "completed"}])
+
+    def handler(req):
+        seen.append(req)
+        if req.method == "POST":
+            return httpx.Response(202, json={"id": "bat_1", "status": "running", "poll_after_seconds": 30})
+        return httpx.Response(200, json=next(states))
+
+    aiv = client(handler)
+    b = aiv.batches.create(["q1", "q2"], engines=["chatgpt"], mode="batch")
+    assert b["id"] == "bat_1"
+    assert json.loads(seen[0].content) == {"questions": ["q1", "q2"], "engines": ["chatgpt"], "mode": "batch"}
+    assert len(seen[0].headers["idempotency-key"]) == 36
+    assert aiv.batches.wait("bat_1")["status"] == "completed"
+
+
+def test_204_returns_none():
+    assert client(lambda req: httpx.Response(204)).keys.revoke("key_1") is None
+
+
+class TestWebhooks:
+    headers = {
+        "webhook-id": VECTOR["id"],
+        "webhook-timestamp": str(VECTOR["ts"]),
+        "webhook-signature": VECTOR["sig"],
+    }
+
+    def test_verifies_a_signature_made_by_the_engine(self):
+        event = verify_webhook(VECTOR["body"], self.headers, VECTOR["secret"], now=VECTOR["ts"])
+        assert event["type"] == "check.completed" and event["data"]["id"] == "job_vec"
+        # bytes body and case-insensitive header names
+        mixed = {k.title(): v for k, v in self.headers.items()}
+        assert verify_webhook(VECTOR["body"].encode(), mixed, VECTOR["secret"], now=VECTOR["ts"])
+        assert Aiv.verify_webhook is verify_webhook
+
+    def test_rotation_both_signatures(self):
+        h = {**self.headers, "webhook-signature": VECTOR["both"]}
+        assert verify_webhook(VECTOR["body"], h, [VECTOR["other"]], now=VECTOR["ts"])
+        assert verify_webhook(VECTOR["body"], h, [VECTOR["secret"]], now=VECTOR["ts"])
+
+    def test_refuses_tampering_wrong_secret_replays_and_missing_headers(self):
+        with pytest.raises(WebhookVerificationError):
+            verify_webhook(VECTOR["body"] + " ", self.headers, VECTOR["secret"], now=VECTOR["ts"])
+        with pytest.raises(WebhookVerificationError, match="No signature"):
+            verify_webhook(VECTOR["body"], self.headers, VECTOR["other"], now=VECTOR["ts"])
+        with pytest.raises(WebhookVerificationError, match="replay"):
+            verify_webhook(VECTOR["body"], self.headers, VECTOR["secret"], now=VECTOR["ts"] + 301)
+        with pytest.raises(WebhookVerificationError, match="Missing"):
+            verify_webhook(VECTOR["body"], {}, VECTOR["secret"])
+        with pytest.raises(WebhookVerificationError, match="secret"):
+            verify_webhook(VECTOR["body"], self.headers, "whsec_not base64!", now=VECTOR["ts"])
+
+    def test_an_empty_secret_never_verifies(self):
+        # A forger signs with an empty key; an unset env var must not accept it.
+        import base64, hashlib, hmac as _hmac
+        signed = f"{VECTOR['id']}.{VECTOR['ts']}.{VECTOR['body']}".encode()
+        forged = "v1," + base64.b64encode(_hmac.new(b"", signed, hashlib.sha256).digest()).decode()
+        h = {**self.headers, "webhook-signature": forged}
+        for empty in ("", "whsec_", "whsec_AAAA"):
+            with pytest.raises(WebhookVerificationError, match="secret"):
+                verify_webhook(VECTOR["body"], h, empty, now=VECTOR["ts"])
+
+
+@pytest.mark.skipif(not os.environ.get("AIV_LIVE_TEST_KEY"), reason="set AIV_LIVE_TEST_KEY (a test key) to run")
+def test_against_a_real_api_with_a_test_key():
+    base = os.environ.get("AIV_BASE", "https://api.aivisibilityskill.com")
+    with Aiv(api_key=os.environ["AIV_LIVE_TEST_KEY"], base_url=base) as aiv:
+        me = aiv.account.get()
+        assert me["account"]["mode"] == "test"
+        job = aiv.checks.create(["best invoicing app for freelancers"], engines=["chatgpt", "gemini"])
+        done = aiv.jobs.wait(job["id"], timeout=60)
+        assert done["status"] == "succeeded" and len(done["answers"]) == 2
+        assert all(a["brands"] for a in done["answers"])
+        assert len(aiv.locales.list()["countries"]) > 200
+        batch = aiv.batches.create(["best crm", "best vpn"], engines=["chatgpt"])
+        assert batch["status"] == "completed" and batch["answers"]["succeeded"] == 2
+        with pytest.raises(AivError) as err:
+            aiv.jobs.get("job_nope")
+        assert err.value.status == 404