answerline 0.1.0__py3-none-any.whl

answerline/__init__.py

@@ -0,0 +1,548 @@
+"""Client for the answer and search monitoring API, on httpx.
+
+`Client` blocks and `AsyncClient` runs on asyncio; both have the same methods (awaitable on `AsyncClient`) and one
+implementation. Each holds one httpx client: keep-alive connections, HTTPS, proxies from the environment. A `Client`
+can be shared across threads, an `AsyncClient` across tasks of one event loop. Close it with `close()` / `aclose()` or
+a `with` / `async with` block. Pass `http_client` (an `httpx.Client` or `httpx.AsyncClient`) to set TLS trust, proxies
+or connection limits; closing the SDK client closes it.
+
+Retries (`max_retries`, default 2, capped exponential backoff with full jitter):
+- 429 is always retried: the request was not admitted, so nothing ran or was charged. `Retry-After` is honoured when
+  the server sends one (up to 8 s; a longer one raises).
+- 5xx, timeouts and dropped connections are retried only for requests that are safe to repeat: GET, and async task
+  creation — a task without an `idempotencyKey` is given a generated one, and each creation call sends an
+  `Idempotency-Key` header of its own, so a repeat after a lost answer returns what the first attempt created. (Without
+  that header a repeat of a created task would answer 409 `RESOURCE_CONFLICT`, a batch item
+  `RESOURCE_ALREADY_EXISTS`): the task exists.
+- Sync monitor calls are charged on success and may already be running when a connection drops or a read times out,
+  so they are retried after a transport error only when no connection was made (nothing sent). A 500 or 502 from them
+  is a final failure the server has already retried. Clearing the queue is treated the same way: the server finishes a
+  clear it has started, and a repeat would also delete tasks queued since.
+- Other 4xx are never retried.
+
+Timeouts are httpx timeouts per attempt: connecting, each read and write, and waiting for a pooled connection each get
+the whole value. Transport failures raise TimeoutError or ConnectionError, chained to the httpx error.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import email.utils
+import json
+import random
+import time
+import urllib.parse
+import uuid
+from datetime import timezone
+from dataclasses import dataclass
+from typing import Any, Dict, Generator, List, Optional, Tuple, TypeVar, Union
+
+import httpx
+
+from .webhooks import SIGNATURE_HEADER, verify_webhook
+
+__all__ = ["MAX_BATCH", "ApiError", "AsyncClient", "Client", "Meta", "SIGNATURE_HEADER", "verify_webhook"]
+
+# Sent as `answerline-py/<version>`; keep in step with pyproject.toml.
+__version__ = "0.1.0"
+MAX_BATCH = 500
+DEFAULT_BASE_URL = "https://api.answerline.dev"
+TIMEOUT_S = 30.0
+# Sync monitor calls and task creation: the server answers a sync call within its 330 s deadline plus one result read
+# (6.5 s), and keeps resending a creation through a failover until 330 s, so the client never gives up just as the
+# server answers.
+SYNC_TIMEOUT_S = 360.0
+# The server resends a clear that did not reach its dispatcher for up to 120 s, then allows the clear 120 s.
+CLEAR_QUEUE_TIMEOUT_S = 270.0
+# A task's longest run once started (5 minutes) and a wait for a slot, plus margin.
+WAIT_TIMEOUT_S = 660.0
+MAX_RETRIES = 2
+_BACKOFF_S = 0.5
+_MAX_DELAY_S = 8.0
+# Not DELETE: repeating DELETE /v1/async/queue deletes tasks queued since the first attempt.
+_IDEMPOTENT = frozenset({"GET", "HEAD", "PUT", "OPTIONS"})
+# No connection was made, so the request never left.
+_NOT_SENT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
+# The request may have reached the server.
+_TRANSIENT = (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)
+_TERMINAL = frozenset({"COMPLETED", "FAILED"})
+_LIMIT_HEADERS = {
+    "rate_limit_limit": "X-RateLimit-Limit",
+    "rate_limit_remaining": "X-RateLimit-Remaining",
+    "concurrent_limit": "X-Concurrent-Limit",
+    "concurrent_current": "X-Concurrent-Current",
+    "concurrent_remaining": "X-Concurrent-Remaining",
+    "credits_remaining": "X-Credits-Remaining",
+    "credits_charged": "X-Credits-Charged",
+    "latency_ms": "X-Latency-Ms",
+}
+
+T = TypeVar("T")
+# A call is a generator of steps: it yields a request to send (and is sent back the response, or the exception sending
+# raised) or a delay in seconds to wait. `Client` and `AsyncClient` differ only in how they run the steps.
+Steps = Generator[Union[httpx.Request, float], Any, T]
+
+
+@dataclass(frozen=True)
+class Meta:
+    """A response's status, headers, its X-Request-Id (quote it to support), and the limit and cost headers it carried
+    (absent or malformed ones are None)."""
+
+    status: int
+    headers: httpx.Headers
+    request_id: Optional[str] = None
+    rate_limit_limit: Optional[int] = None
+    rate_limit_remaining: Optional[int] = None
+    concurrent_limit: Optional[int] = None
+    concurrent_current: Optional[int] = None
+    concurrent_remaining: Optional[int] = None
+    credits_remaining: Optional[int] = None
+    credits_charged: Optional[int] = None
+    latency_ms: Optional[int] = None
+
+
+class ApiError(Exception):
+    """Non-2xx response, or a body that is not JSON. `code` is the stable machine-readable error code when present;
+    `body` is the parsed JSON or the raw text."""
+
+    def __init__(self, status: int, code: Optional[str], body: Any, meta: Meta):
+        request = f" (request {meta.request_id})" if meta.request_id else ""
+        super().__init__((f"{status} {code}" if code else f"HTTP {status}") + request)
+        self.status = status
+        self.code = code
+        self.body = body
+        self.meta = meta
+
+
+class _Api:
+    """Methods shared by both clients. Each returns `_run(steps)`: the result, or an awaitable of it."""
+
+    _http_class: Any
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = TIMEOUT_S,
+                 sync_timeout: float = SYNC_TIMEOUT_S, max_retries: int = MAX_RETRIES, http_client: Any = None):
+        """`timeout` applies to every call except sync monitor calls and task creation, which get `sync_timeout`, and
+        clearing the queue, which gets `CLEAR_QUEUE_TIMEOUT_S`."""
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.sync_timeout = sync_timeout
+        self.max_retries = max_retries
+        self._http = http_client if http_client is not None else self._http_class()
+        self._owns_http = True
+
+    def _run(self, steps: Steps[T]) -> Any:
+        raise NotImplementedError
+
+    def with_options(self, timeout: Optional[float] = None, sync_timeout: Optional[float] = None,
+                     max_retries: Optional[int] = None) -> Any:
+        """A client sharing this one's connections, with the given options replaced. A clone does not own the
+        pool: `close()` on it is a no-op — close the client it was made from."""
+        clone = copy.copy(self)
+        changes = {"timeout": timeout, "sync_timeout": sync_timeout, "max_retries": max_retries}
+        clone.__dict__.update((name, value) for name, value in changes.items() if value is not None)
+        clone.__dict__["_owns_http"] = False
+        return clone
+
+    def request(self, method: str, path: str, body: Any = None, headers: Optional[Dict[str, str]] = None) -> Any:
+        """The parsed body and response metadata, with the retry policy above. Raises ApiError on non-2xx or a non-JSON
+        body, TimeoutError when an attempt times out, and ConnectionError on another transport failure.
+
+        `headers` are sent with the request, such as your own `X-Request-Id`; the SDK's Authorization, Accept,
+        User-Agent and Content-Type take precedence."""
+        return self._run(self._request(method, path, body, headers=headers))
+
+    def _request(self, method: str, path: str, body: Any, timeout: Optional[float] = None,
+                 headers: Optional[Dict[str, str]] = None) -> Steps[Tuple[Any, Meta]]:
+        headers = httpx.Headers(headers or {})
+        headers.update({"Authorization": f"Bearer {self.api_key}", "Accept": "application/json",
+                        "User-Agent": f"answerline-py/{__version__}"})
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if timeout is None:
+            long = path.startswith("/v1/monitor/") or (method.upper() == "POST" and path.startswith("/v1/async/task"))
+            timeout = self.sync_timeout if long else self.timeout
+        # NaN/Infinity would serialize as bare tokens the server cannot parse: fail before sending.
+        request = self._http.build_request(method, self.base_url + path, headers=headers, timeout=httpx.Timeout(timeout),
+                                           content=None if body is None else json.dumps(body, allow_nan=False).encode())
+        replayable = _replayable(method, body)
+        attempt = 0
+        while True:
+            try:
+                return _parse((yield request))
+            except (ApiError, httpx.TransportError) as err:
+                delay = _retry_delay(err, replayable, attempt, _MAX_DELAY_S) if attempt < self.max_retries else None
+                if delay is None:
+                    raise
+            yield delay
+            attempt += 1
+
+    def _data(self, method: str, path: str, body: Any = None, timeout: Optional[float] = None,
+              headers: Optional[Dict[str, str]] = None) -> Steps[Any]:
+        return (yield from self._request(method, path, body, timeout, headers))[0]
+
+    def _create(self, path: str, body: Any) -> Steps[Any]:
+        """Task creation under an `Idempotency-Key` naming this call: every retry sends it, so the API answers a repeat
+        with what the first attempt created."""
+        return (yield from self._data("POST", path, body, headers={"Idempotency-Key": str(uuid.uuid4())}))
+
+    # -- sync monitor calls -------------------------------------------------
+    @property
+    def monitor(self) -> "_Monitor":
+        """Namespaced monitor calls: `client.monitor.chatgpt(prompt=..., country=...)`; also callable as
+        `monitor(engine, **body)`."""
+        return _Monitor(self)
+
+    @property
+    def async_tasks(self) -> "_AsyncTasks":
+        """Namespaced async-task calls: `client.async_tasks.create_batch(tasks)`, `.run(...)`, `.wait(id)`."""
+        return _AsyncTasks(self)
+
+    def chatgpt(self, prompt: str, country: str, **options: Any) -> Any:
+        return self.monitor("chatgpt", prompt=prompt, country=country, **options)
+
+    def perplexity(self, prompt: str, country: str, **options: Any) -> Any:
+        return self.monitor("perplexity", prompt=prompt, country=country, **options)
+
+    def gemini(self, prompt: str, country: str, **options: Any) -> Any:
+        return self.monitor("gemini", prompt=prompt, country=country, **options)
+
+    def copilot(self, prompt: str, country: str, **options: Any) -> Any:
+        return self.monitor("copilot", prompt=prompt, country=country, **options)
+
+    def grok(self, prompt: str, country: str, **options: Any) -> Any:
+        return self.monitor("grok", prompt=prompt, country=country, **options)
+
+    def ai_mode(self, prompt: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("aimode", **_geo({"prompt": prompt}, country, gl, options))
+
+    def google(self, **options: Any) -> Any:
+        return self.monitor("google", **options)
+
+    def google_news(self, query: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("google/news", **_geo({"query": query}, country, gl, options))
+
+    # -- async tasks ----------------------------------------------------------
+    def create_task(self, task_type: str, payload: Dict[str, Any], priority: Optional[int] = None,
+                    idempotency_key: Optional[str] = None, webhook_url: Optional[str] = None) -> Any:
+        return self._run(self._create("/v1/async/task", _task(task_type, payload, priority, idempotency_key, webhook_url)))
+
+    def create_batch(self, tasks: List[Dict[str, Any]]) -> Any:
+        """1 to MAX_BATCH tasks, each shaped like the create_task body (taskType, payload, ...). Raises ValueError outside
+        that range, before sending. A task without an idempotencyKey is given a generated one, so retrying the call
+        never creates it twice."""
+        if not 1 <= len(tasks) <= MAX_BATCH:
+            raise ValueError(f"a batch holds 1 to {MAX_BATCH} tasks, got {len(tasks)}")
+        tasks = [{**t, "idempotencyKey": t.get("idempotencyKey") or str(uuid.uuid4())} for t in tasks]
+        return self._run(self._create("/v1/async/task/batch", tasks))
+
+    def get_task(self, task_id: str) -> Any:
+        return self._run(self._data("GET", _task_path(task_id)))
+
+    def wait_for_task(self, task_id: str, timeout: float = WAIT_TIMEOUT_S, interval: float = 10.0) -> Any:
+        """Polls until COMPLETED or FAILED, waiting with jittered backoff from 0.5 s up to `interval` seconds between
+        polls. Rate limits, server errors, timeouts and connection errors are polled through; other errors raise.
+        Raises TimeoutError after `timeout` seconds. For many tasks, prefer a webhook (`webhook_url`, verified with
+        `verify_webhook`) over polling."""
+        return self._run(self._wait(task_id, timeout, interval))
+
+    def _wait(self, task_id: str, timeout: float, interval: float) -> Steps[Dict[str, Any]]:
+        deadline = time.monotonic() + timeout
+        last: Optional[Exception] = None
+        poll = 0
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"task {task_id} did not finish in time") from last
+            poller = self.with_options(timeout=min(remaining, self.timeout), max_retries=0)
+            try:
+                task, meta = yield from poller._request("GET", _task_path(task_id), None)
+            except (ApiError, httpx.TransportError) as err:
+                delay = _retry_delay(err, True, poll, interval)
+                if delay is None:
+                    raise
+                last = err
+            else:
+                status = task.get("task", {}).get("status") if isinstance(task, dict) else None
+                if status in _TERMINAL:
+                    return task
+                if status is None:
+                    raise ApiError(meta.status, "MALFORMED_RESPONSE", task, meta)
+                delay = _backoff(poll, interval)
+            yield max(0.0, min(delay, deadline - time.monotonic()))
+            poll += 1
+
+    def async_status(self) -> Any:
+        return self._run(self._data("GET", "/v1/async/status"))
+
+    def clear_queue(self) -> Any:
+        """Deletes QUEUED tasks (never charged). Clearing a full queue takes a while, so it gets a longer timeout
+        (the larger of `CLEAR_QUEUE_TIMEOUT_S` and the client's `timeout`)."""
+        return self._run(self._data("DELETE", "/v1/async/queue", timeout=max(CLEAR_QUEUE_TIMEOUT_S, self.timeout)))
+
+    # -- utility ----------------------------------------------------------------
+    def credits(self) -> Any:
+        return self._run(self._data("GET", "/v1/credits"))
+
+    def countries(self, model: Optional[str] = None) -> Any:
+        query = f"?model={urllib.parse.quote(model, safe='')}" if model else ""
+        return self._run(self._data("GET", f"/v1/countries{query}"))
+
+    def states(self, country: str = "US") -> Any:
+        return self._run(self._data("GET", f"/v1/states?country={urllib.parse.quote(country, safe='')}"))
+
+    def google_goto(self, url: str) -> Any:
+        """Resolves a Google result URL; the server answers within ~10 s, so this gets a short timeout,
+        not the sync-monitor one its `/v1/monitor/` prefix would give it."""
+        def steps() -> Steps[str]:
+            return (yield from self._data("POST", "/v1/monitor/google/goto", {"url": url}, timeout=15.0))["url"]
+
+        return self._run(steps())
+
+
+class _Monitor:
+    """The `client.monitor` namespace: one method per engine, each a thin wrapper over POST /v1/monitor/<engine>.
+    Calling it directly — `monitor(engine, **body)` — is the generic form."""
+
+    def __init__(self, api: _Api):
+        self._api = api
+
+    def __call__(self, engine: str, **body: Any) -> Any:
+        return self._api._run(self._api._data("POST", f"/v1/monitor/{engine}", body))
+
+    def chatgpt(self, prompt: str, country: str, **options: Any) -> Any:
+        return self("chatgpt", prompt=prompt, country=country, **options)
+
+    def perplexity(self, prompt: str, country: str, **options: Any) -> Any:
+        return self("perplexity", prompt=prompt, country=country, **options)
+
+    def gemini(self, prompt: str, country: str, **options: Any) -> Any:
+        return self("gemini", prompt=prompt, country=country, **options)
+
+    def copilot(self, prompt: str, country: str, **options: Any) -> Any:
+        return self("copilot", prompt=prompt, country=country, **options)
+
+    def grok(self, prompt: str, country: str, **options: Any) -> Any:
+        return self("grok", prompt=prompt, country=country, **options)
+
+    def aimode(self, prompt: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
+        return self("aimode", **_geo({"prompt": prompt}, country, gl, options))
+
+    def google(self, query: Optional[str] = None, country: Optional[str] = None, **options: Any) -> Any:
+        body = {**options}
+        if query is not None:
+            body["query"] = query
+        if country is not None:
+            body["country"] = country
+        return self("google", **body)
+
+    def google_news(self, query: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
+        return self("google/news", **_geo({"query": query}, country, gl, options))
+
+
+class _AsyncTasks:
+    """The `client.async_tasks` namespace: `create`/`create_batch`/`get`/`wait`/`run`/`status`/`clear_queue`."""
+
+    def __init__(self, api: _Api):
+        self._api = api
+
+    def create(self, task_type: str, payload: Dict[str, Any], priority: Optional[int] = None,
+               idempotency_key: Optional[str] = None, webhook_url: Optional[str] = None) -> Any:
+        return self._api.create_task(task_type, payload, priority, idempotency_key, webhook_url)
+
+    def create_batch(self, tasks: List[Dict[str, Any]]) -> Any:
+        """Like `create_batch`, also accepting snake_case keys (`task_type`, `idempotency_key`, `webhook_url`)
+        in each item."""
+        return self._api.create_batch([_task_keys(t) for t in tasks])
+
+    def get(self, task_id: str) -> Any:
+        return self._api.get_task(task_id)
+
+    def wait(self, task_id: str, timeout: float = WAIT_TIMEOUT_S, interval: float = 10.0) -> Any:
+        """Polls to a terminal status, like `wait_for_task`."""
+        return self._api.wait_for_task(task_id, timeout, interval)
+
+    def run(self, task_type: str, payload: Dict[str, Any], priority: Optional[int] = None,
+            idempotency_key: Optional[str] = None, webhook_url: Optional[str] = None,
+            timeout: float = WAIT_TIMEOUT_S, interval: float = 10.0) -> Any:
+        """Creates the task and returns once it reaches a terminal status (COMPLETED or FAILED)."""
+        api = self._api
+
+        def steps() -> Steps[Dict[str, Any]]:
+            created = yield from api._create("/v1/async/task", _task(task_type, payload, priority, idempotency_key, webhook_url))
+            return (yield from api._wait(created["task"]["id"], timeout, interval))
+
+        return api._run(steps())
+
+    def status(self) -> Any:
+        return self._api.async_status()
+
+    def clear_queue(self) -> Any:
+        """Deletes QUEUED tasks (never charged)."""
+        return self._api.clear_queue()
+
+
+class Client(_Api):
+    _http_class = httpx.Client
+
+    def _run(self, steps: Steps[T]) -> T:
+        outcome: Any = None
+        try:
+            while True:
+                step = steps.send(outcome)
+                try:
+                    outcome = self._http.send(step) if isinstance(step, httpx.Request) else time.sleep(step)
+                except Exception as err:  # handed to the call, which retries or raises it
+                    outcome = err
+        except StopIteration as done:
+            return done.value
+        except httpx.TransportError as err:
+            raise _builtin(err) from err
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncClient(_Api):
+    _http_class = httpx.AsyncClient
+
+    async def _run(self, steps: Steps[T]) -> T:
+        outcome: Any = None
+        try:
+            while True:
+                step = steps.send(outcome)
+                try:
+                    outcome = await (self._http.send(step) if isinstance(step, httpx.Request) else asyncio.sleep(step))
+                except Exception as err:  # handed to the call, which retries or raises it
+                    outcome = err
+        except StopIteration as done:
+            return done.value
+        except httpx.TransportError as err:
+            raise _builtin(err) from err
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+def _geo(body: Dict[str, Any], country: Optional[str], gl: Optional[str], options: Dict[str, Any]) -> Dict[str, Any]:
+    """The spec's country/gl either-of: one must be given, both may be (`gl` then serves the engine's locale)."""
+    body = {**body, **options}
+    if country is not None:
+        body["country"] = country
+    if gl is not None:
+        body["gl"] = gl
+    if "country" not in body and "gl" not in body:
+        raise ValueError("country or gl is required")
+    return body
+
+
+def _task_keys(task: Dict[str, Any]) -> Dict[str, Any]:
+    """Translate snake_case keys in one async-task item to the wire's camelCase."""
+    out = dict(task)
+    for snake, camel in (("task_type", "taskType"), ("idempotency_key", "idempotencyKey")):
+        if snake in out:
+            out.setdefault(camel, out.pop(snake))
+    if "webhook_url" in out:
+        out.setdefault("webhook", {"url": out.pop("webhook_url")})
+    return out
+
+
+def _parse(outcome: Union[httpx.Response, Exception]) -> Tuple[Any, Meta]:
+    if isinstance(outcome, Exception):
+        raise outcome
+    headers = outcome.headers
+    meta = Meta(outcome.status_code, headers, headers.get("X-Request-Id"),
+                **{name: _int(headers.get(header)) for name, header in _LIMIT_HEADERS.items()})
+    is_json, parsed = _decode(outcome.content)
+    if not outcome.is_success or not is_json:
+        error = parsed.get("error") if isinstance(parsed, dict) else None
+        code = error.get("code") if isinstance(error, dict) and isinstance(error.get("code"), str) else None
+        raise ApiError(outcome.status_code, code, parsed, meta)
+    return parsed, meta
+
+
+def _builtin(err: httpx.TransportError) -> OSError:
+    return TimeoutError(str(err)) if isinstance(err, httpx.TimeoutException) else ConnectionError(str(err))
+
+
+def _int(value: Optional[str]) -> Optional[int]:
+    try:
+        return int(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _decode(raw: bytes) -> Tuple[bool, Any]:
+    """(True, value) for an empty or JSON body, (False, text) otherwise."""
+    try:
+        return True, (json.loads(raw) if raw else None)
+    except ValueError:
+        return False, raw.decode("utf-8", "replace")
+
+
+def _retry_after(value: Optional[str]) -> Optional[float]:
+    """`Retry-After` as delta-seconds or an HTTP date."""
+    if value is None:
+        return None
+    if value.strip().isdigit():
+        return float(value)
+    try:
+        at = email.utils.parsedate_to_datetime(value)
+        # A date without a zone is naive; `timestamp()` would read it as local time.
+        return max(0.0, (at if at.tzinfo else at.replace(tzinfo=timezone.utc)).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+def _backoff(attempt: int, cap: float) -> float:
+    return random.uniform(0, min(cap, _BACKOFF_S * 2 ** min(attempt, 16)))
+
+
+def _replayable(method: str, body: Any) -> bool:
+    """Whether repeating the request cannot create a second effect."""
+    if method.upper() in _IDEMPOTENT:
+        return True
+    tasks = body if isinstance(body, list) else [body]
+    return bool(tasks) and all(isinstance(t, dict) and isinstance(t.get("idempotencyKey"), str) for t in tasks)
+
+
+def _retry_delay(err: Exception, replayable: bool, attempt: int, cap: float) -> Optional[float]:
+    """Seconds to wait before repeating after `err`, or None when it must not be repeated."""
+    if isinstance(err, ApiError):
+        if err.status != 429:
+            return _backoff(attempt, cap) if err.status >= 500 and replayable else None
+        after = _retry_after(err.meta.headers.get("Retry-After"))
+        return _backoff(attempt, cap) if after is None else (after if after <= _MAX_DELAY_S else None)
+    retry = isinstance(err, _NOT_SENT) or (replayable and isinstance(err, _TRANSIENT))
+    return _backoff(attempt, cap) if retry else None
+
+
+def _task_path(task_id: str) -> str:
+    return f"/v1/async/task/{urllib.parse.quote(task_id, safe='')}"
+
+
+def _task(task_type: str, payload: Dict[str, Any], priority: Optional[int], idempotency_key: Optional[str], webhook_url: Optional[str]) -> Dict[str, Any]:
+    body: Dict[str, Any] = {"taskType": task_type, "payload": payload}
+    if priority is not None:
+        body["priority"] = priority
+    # A task without a key (None or empty, as in a batch) gets a generated one, so retrying the call never creates it
+    # twice and two keyless calls never share a key.
+    body["idempotencyKey"] = idempotency_key or str(uuid.uuid4())
+    if webhook_url is not None:
+        body["webhook"] = {"url": webhook_url}
+    return body

answerline/webhooks.py

@@ -0,0 +1,28 @@
+"""Webhook signature verification."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import time
+from typing import Optional, Union
+
+SIGNATURE_HEADER = "Webhook-Signature"
+
+_TIMESTAMP = re.compile(r"t=([0-9]+)")
+_SIGNATURE = re.compile(r"v1=([0-9a-f]{64})")
+
+
+def verify_webhook(body: Union[bytes, str], header: Optional[str], secret: str, tolerance_seconds: float = 300) -> bool:
+    """Whether `header` (the Webhook-Signature request header) signs the raw request `body` with `secret`, at a time
+    within `tolerance_seconds` of now. Pass the body exactly as received: parsed and re-serialized JSON does not verify.
+    During a secret rotation deliveries carry a signature for each secret, so either secret verifies."""
+    parts = (header or "").split(",")
+    timestamps = [m.group(1) for m in map(_TIMESTAMP.fullmatch, parts) if m]
+    signatures = [m.group(1) for m in map(_SIGNATURE.fullmatch, parts) if m]
+    if len(timestamps) != 1 or not signatures or abs(time.time() - int(timestamps[0])) > tolerance_seconds:
+        return False
+    content = body.encode() if isinstance(body, str) else body
+    expected = hmac.new(secret.encode(), f"{timestamps[0]}.".encode() + content, hashlib.sha256).hexdigest()
+    return any(hmac.compare_digest(expected, signature) for signature in signatures)

answerline-0.1.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: answerline
+Version: 0.1.0
+Summary: Python client for the AnswerLine answer and search monitoring API.
+Author-email: AnswerLine <support@answerline.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://answerline.dev
+Project-URL: Repository, https://github.com/hsdxpro/answerline
+Keywords: answerline,ai,llm,search-api,monitoring,chatgpt,perplexity,gemini
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# answerline
+
+Python client for the [AnswerLine](https://answerline.dev) API — structured JSON answers from AI assistants
+(ChatGPT, Perplexity, Gemini, Copilot, Grok) and Google surfaces (Search, News, AI Overview, AI Mode), on httpx.
+
+```bash
+pip install answerline
+```
+
+```python
+from answerline import Client
+
+with Client("sk_...") as client:
+    # Synchronous monitor calls: one method per engine (chatgpt, perplexity, gemini,
+    # copilot, grok, aimode, google, google_news), or client.monitor(engine, **body).
+    answer = client.monitor.chatgpt(prompt="Best CRM for a 5-person team?", country="US")
+
+    # Async tasks: create, poll, or run to a terminal status.
+    task = client.async_tasks.run(
+        "CHATGPT",
+        {"prompt": "Best CRM for a 5-person team?", "country": "US"},
+        idempotency_key="crm-1",
+    )
+
+    client.credits()  # {"remaining", "perCycle", "cycleResetsAt"}
+```
+
+`AsyncClient` has the same methods, awaitable. `async_tasks.create_batch` submits up to 500 tasks in one call;
+`async_tasks.wait` polls a task to COMPLETED or FAILED; `async_tasks.status` and `async_tasks.clear_queue` manage
+the queue. Prefer a webhook (`webhook_url=` on the task) over polling for many tasks — verify deliveries with
+`verify_webhook(body, header, secret)` against the `Webhook-Signature` header.
+
+Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, credit
+and request-id headers); transport failures raise `TimeoutError` or `ConnectionError`. 429s and safely replayable
+failures are retried with jittered backoff; `timeout`, `sync_timeout`, `max_retries` and `http_client` are
+constructor options.

answerline-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+answerline/__init__.py,sha256=jo_jb533_CU6dDtPlWLTPR7XZU_SyPHDjbVL59ESaQQ,26053
+answerline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+answerline/webhooks.py,sha256=QpjzmRgBVId_SjNqdJZCCDiBihfo3kIXPN33p6WXI8s,1329
+answerline-0.1.0.dist-info/licenses/LICENSE,sha256=WEk3fXEcZoGoQtMd3Cu5aLyGrVtKajmtDHZaUlpSvEE,1067
+answerline-0.1.0.dist-info/METADATA,sha256=k426Kzvmp3PiA7yyaaN9lrsSMQsA6oCz9hdt5EkXDJg,2546
+answerline-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+answerline-0.1.0.dist-info/top_level.txt,sha256=wUm1n1JjUDO4D_566FKGRgzdrz1gJK13l3n2tRYNGKY,11
+answerline-0.1.0.dist-info/RECORD,,

answerline-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

answerline-0.1.0.dist-info/licenses/LICENSE

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

answerline-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+answerline