getanyapi 0.9.2__tar.gz → 0.9.6__tar.gz

{getanyapi-0.9.2 → getanyapi-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getanyapi
-Version: 0.9.2
+Version: 0.9.6
 Summary: Official typed Python SDK for AnyAPI: any API, one wallet, USD, no subscriptions.
 Project-URL: Homepage, https://getanyapi.com
 Project-URL: Documentation, https://getanyapi.com/docs
@@ -138,13 +138,23 @@ res = client.google.search(
 | `ResultNotFoundError`      | -    | `unwrap` on an empty found-data result     |
 | `RateLimitedError`         | 429  | Too many requests (retried automatically)  |
 | `UpstreamError`            | 502  | An upstream backend failed                 |
-| `ConnectionError`          | 0    | Network or transport failure (retried)     |
+| `ConnectionError`          | 0    | Network or transport failure               |
 | `TimeoutError`             | 0    | Request exceeded its timeout (not retried) |
 
 All extend `AnyAPIError` (with `.status` and `.request_id`). Retries cover only 429 and network
-failures, with jittered exponential backoff honoring `Retry-After`. Default `max_retries` is 2
-(up to 3 attempts); set it on the client (`AnyAPI(max_retries=...)`) or per request via
-`options`. Timeouts are never retried.
+failures proven to happen before a request was sent, with jittered exponential backoff honoring
+`Retry-After`. Default `max_retries` is 2 (up to 3 attempts); set it on the client
+(`AnyAPI(max_retries=...)`) or per request via `options`. Timeouts are never retried. Connection
+failures during or after a billed `POST /v1/run` are not retried because the call may already have
+been charged. When the send phase is unknown, the SDK does not retry.
+
+Automatic retry of a billed `run()` requires structured transport evidence that the request was
+not delivered. Python's `httpx` transport provides that evidence for `ConnectError`, so DNS
+resolution failures and refused or unreachable connections retry. `ConnectTimeout` is a
+`TimeoutException` and does not retry. `ReadError` does not retry: it can mean either that a
+connection closed before the server read the request or that the connection failed after delivery.
+If a custom transport hides the connection phase, handle retries explicitly and only when your
+application can establish non-delivery.
 
 ## Agent signup
 

{getanyapi-0.9.2 → getanyapi-0.9.6}/README.md

@@ -109,13 +109,23 @@ res = client.google.search(
 | `ResultNotFoundError`      | -    | `unwrap` on an empty found-data result     |
 | `RateLimitedError`         | 429  | Too many requests (retried automatically)  |
 | `UpstreamError`            | 502  | An upstream backend failed                 |
-| `ConnectionError`          | 0    | Network or transport failure (retried)     |
+| `ConnectionError`          | 0    | Network or transport failure               |
 | `TimeoutError`             | 0    | Request exceeded its timeout (not retried) |
 
 All extend `AnyAPIError` (with `.status` and `.request_id`). Retries cover only 429 and network
-failures, with jittered exponential backoff honoring `Retry-After`. Default `max_retries` is 2
-(up to 3 attempts); set it on the client (`AnyAPI(max_retries=...)`) or per request via
-`options`. Timeouts are never retried.
+failures proven to happen before a request was sent, with jittered exponential backoff honoring
+`Retry-After`. Default `max_retries` is 2 (up to 3 attempts); set it on the client
+(`AnyAPI(max_retries=...)`) or per request via `options`. Timeouts are never retried. Connection
+failures during or after a billed `POST /v1/run` are not retried because the call may already have
+been charged. When the send phase is unknown, the SDK does not retry.
+
+Automatic retry of a billed `run()` requires structured transport evidence that the request was
+not delivered. Python's `httpx` transport provides that evidence for `ConnectError`, so DNS
+resolution failures and refused or unreachable connections retry. `ConnectTimeout` is a
+`TimeoutException` and does not retry. `ReadError` does not retry: it can mean either that a
+connection closed before the server read the request or that the connection failed after delivery.
+If a custom transport hides the connection phase, handle retries explicitly and only when your
+application can establish non-delivery.
 
 ## Agent signup
 

{getanyapi-0.9.2 → getanyapi-0.9.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getanyapi"
-version = "0.9.2"
+version = "0.9.6"
 description = "Official typed Python SDK for AnyAPI: any API, one wallet, USD, no subscriptions."
 readme = "README.md"
 requires-python = ">=3.10"

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/__init__.py

@@ -49,7 +49,7 @@ from .types import (
     unwrap,
 )
 
-__version__ = "0.9.2"
+__version__ = "0.9.6"
 
 __all__ = [
     # clients + top-level functions

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/_account.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import Any, cast
 
 from ._errors import AnyAPIError, error_for_status
-from ._transport import as_dict, error_message
+from ._transport import as_dict, error_details
 from .types import (
     AccountProfile,
     AgentSignupResult,
@@ -141,4 +141,7 @@ def parse_signup(body: Any) -> AgentSignupResult:
 
 def map_error(status: int, body: object, request_id: str | None) -> AnyAPIError:
     """Map a non-2xx account/catalog response to the frozen error hierarchy."""
-    return error_for_status(status, error_message(body, status), request_id=request_id)
+    message, code = error_details(body, status)
+    return error_for_status(
+        status, message, request_id=request_id, code=code
+    )

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/_async_client.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import asyncio
 import importlib
 import os
-from typing import Any
+from typing import Any, Literal
 
 import httpx
 
@@ -57,12 +57,16 @@ class AsyncAnyAPI:
         base_url: str = _DEFAULT_BASE_URL,
         timeout: float = 60.0,
         max_retries: int = 2,
+        idempotency: Literal["auto", "off"] = "auto",
         http_client: httpx.AsyncClient | None = None,
     ) -> None:
         self._api_key = _resolve_api_key(api_key)
         self._base_url = base_url.rstrip("/")
         self._timeout = timeout
         self._max_retries = max_retries
+        if idempotency not in ("auto", "off"):
+            raise ValueError('idempotency must be "auto" or "off"')
+        self._idempotency = idempotency
         self._owns_client = http_client is None
         self._http = http_client or httpx.AsyncClient(timeout=timeout)
         self._namespaces: dict[str, Any] = {}
@@ -115,6 +119,7 @@ class AsyncAnyAPI:
             api_key=self._api_key,
             options=options,
             timeout=timeout,
+            idempotency=self._idempotency,
         )
         retry = RetryState(max_retries)
         while True:
@@ -130,7 +135,10 @@ class AsyncAnyAPI:
             except httpx.TimeoutException as exc:
                 raise TimeoutError(str(exc) or "request timed out", status=0) from exc
             except httpx.HTTPError as exc:
-                if retry.can_retry:
+                if (
+                    is_retryable_error(exc, request_may_be_billed=True)
+                    and retry.can_retry
+                ):
                     await asyncio.sleep(retry.next_delay(None))
                     continue
                 raise ConnectionError(
@@ -165,8 +173,30 @@ class AsyncAnyAPI:
             "Authorization": f"Bearer {self._api_key}",
             "Accept": "application/json",
         }
-        response = await self._http.get(url, params=params or {}, headers=headers)
-        return self._json_or_raise(response)
+        retry = RetryState(self._max_retries)
+        while True:
+            response: httpx.Response | None = None
+            try:
+                response = await self._http.get(
+                    url, params=params or {}, headers=headers
+                )
+                return self._json_or_raise(response)
+            except AnyAPIError as exc:
+                if is_retryable_error(exc) and retry.can_retry:
+                    await asyncio.sleep(retry.next_delay(response))
+                    continue
+                raise
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(
+                    str(exc) or "request timed out", status=0
+                ) from exc
+            except httpx.HTTPError as exc:
+                if is_retryable_error(exc) and retry.can_retry:
+                    await asyncio.sleep(retry.next_delay(None))
+                    continue
+                raise ConnectionError(
+                    str(exc) or "connection failed", status=0
+                ) from exc
 
     def _json_or_raise(self, response: httpx.Response) -> object:
         request_id = response.headers.get("x-request-id")

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/_client.py

@@ -32,7 +32,7 @@ from __future__ import annotations
 
 import importlib
 import os
-from typing import Any
+from typing import Any, Literal
 
 import httpx
 
@@ -91,12 +91,16 @@ class AnyAPI:
         base_url: str = _DEFAULT_BASE_URL,
         timeout: float = 60.0,
         max_retries: int = 2,
+        idempotency: Literal["auto", "off"] = "auto",
         http_client: httpx.Client | None = None,
     ) -> None:
         self._api_key = _resolve_api_key(api_key)
         self._base_url = base_url.rstrip("/")
         self._timeout = timeout
         self._max_retries = max_retries
+        if idempotency not in ("auto", "off"):
+            raise ValueError('idempotency must be "auto" or "off"')
+        self._idempotency = idempotency
         self._owns_client = http_client is None
         self._http = http_client or httpx.Client(timeout=timeout)
         self._namespaces: dict[str, Any] = {}
@@ -150,6 +154,7 @@ class AnyAPI:
             api_key=self._api_key,
             options=options,
             timeout=timeout,
+            idempotency=self._idempotency,
         )
         retry = RetryState(max_retries)
         while True:
@@ -165,7 +170,10 @@ class AnyAPI:
             except httpx.TimeoutException as exc:
                 raise TimeoutError(str(exc) or "request timed out", status=0) from exc
             except httpx.HTTPError as exc:
-                if retry.can_retry:
+                if (
+                    is_retryable_error(exc, request_may_be_billed=True)
+                    and retry.can_retry
+                ):
                     _transport.sleep(retry.next_delay(None))
                     continue
                 raise ConnectionError(
@@ -200,8 +208,30 @@ class AnyAPI:
             "Authorization": f"Bearer {self._api_key}",
             "Accept": "application/json",
         }
-        response = self._http.get(url, params=params or {}, headers=headers)
-        return self._json_or_raise(response)
+        retry = RetryState(self._max_retries)
+        while True:
+            response: httpx.Response | None = None
+            try:
+                response = self._http.get(
+                    url, params=params or {}, headers=headers
+                )
+                return self._json_or_raise(response)
+            except AnyAPIError as exc:
+                if is_retryable_error(exc) and retry.can_retry:
+                    _transport.sleep(retry.next_delay(response))
+                    continue
+                raise
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(
+                    str(exc) or "request timed out", status=0
+                ) from exc
+            except httpx.HTTPError as exc:
+                if is_retryable_error(exc) and retry.can_retry:
+                    _transport.sleep(retry.next_delay(None))
+                    continue
+                raise ConnectionError(
+                    str(exc) or "connection failed", status=0
+                ) from exc
 
     def _json_or_raise(self, response: httpx.Response) -> object:
         request_id = response.headers.get("x-request-id")

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/_errors.py

@@ -39,14 +39,21 @@ class AnyAPIError(Exception):
     Attributes:
         status: HTTP status code, or 0 for transport-level failures.
         request_id: The x-request-id response header when present, else None.
+        code: Stable gateway error code when the JSON body includes one, else None.
     """
 
     def __init__(
-        self, message: str, *, status: int, request_id: str | None = None
+        self,
+        message: str,
+        *,
+        status: int,
+        request_id: str | None = None,
+        code: str | None = None,
     ) -> None:
         super().__init__(message)
         self.status = status
         self.request_id = request_id
+        self.code = code
 
 
 class BadRequestError(AnyAPIError):
@@ -108,8 +115,12 @@ _STATUS_MAP: dict[int, type[AnyAPIError]] = {
 
 
 def error_for_status(
-    status: int, message: str, *, request_id: str | None = None
+    status: int,
+    message: str,
+    *,
+    request_id: str | None = None,
+    code: str | None = None,
 ) -> AnyAPIError:
     """Build the mapped error for a non-2xx HTTP status (SPEC 3.6)."""
     cls = _STATUS_MAP.get(status, AnyAPIError)
-    return cls(message, status=status, request_id=request_id)
+    return cls(message, status=status, request_id=request_id, code=code)

getanyapi-0.9.6/src/getanyapi/_idempotency.py

@@ -0,0 +1,34 @@
+"""Idempotency-key generation and pagination derivation."""
+
+from __future__ import annotations
+
+import uuid
+
+_MAX_KEY_BYTES = 255
+
+
+def generate_idempotency_key() -> str:
+    """Return a stdlib UUID token without separators."""
+    return uuid.uuid4().hex
+
+
+def validate_idempotency_key(key: str) -> None:
+    """Enforce the gateway's 1-255 byte visible-ASCII wire contract."""
+    if (
+        not key
+        or len(key) > _MAX_KEY_BYTES
+        or any(ord(char) < 0x21 or ord(char) > 0x7E for char in key)
+    ):
+        raise ValueError(
+            "idempotency_key must be 1-255 bytes of visible ASCII (0x21-0x7e)"
+        )
+
+
+def page_idempotency_key(key: str, page_number: int) -> str:
+    """Derive a distinct, valid key for one explicitly keyed page."""
+    validate_idempotency_key(key)
+    suffix = f"-p{page_number}"
+    prefix_length = _MAX_KEY_BYTES - len(suffix)
+    if prefix_length < 1:
+        raise ValueError("pagination page number is too large for an idempotency key")
+    return f"{key[:prefix_length]}{suffix}"

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/_pagination.py

@@ -36,6 +36,7 @@ from typing import (
 
 from pydantic import BaseModel
 
+from ._idempotency import page_idempotency_key
 from ._transport import as_dict, validate_run_result
 from .types import (
     AnyBareRunResult,
@@ -135,6 +136,7 @@ class Paginator(Generic[Item, Data]):
         self,
     ) -> Iterator[tuple[RunResult[Data] | BareRunResult[Data], dict[str, Any] | None]]:
         cursor: str | None = None
+        page_number = 1
         while True:
             page_input = dict(self._input)
             if cursor is not None:
@@ -142,7 +144,10 @@ class Paginator(Generic[Item, Data]):
             raw = self._client._run_raw(  # pyright: ignore[reportPrivateUsage]
                 self._slug,
                 page_input,
-                cast("RequestOptions | None", self._page_options),
+                cast(
+                    "RequestOptions | None",
+                    _options_for_page(self._page_options, page_number),
+                ),
             )
             page = _validate_page(raw, self._data_model, self._bare)
             data = _raw_page_data(raw, self._bare)
@@ -150,6 +155,7 @@ class Paginator(Generic[Item, Data]):
             cursor = _next_cursor(data)
             if cursor is None:
                 return
+            page_number += 1
 
     def pages(self) -> Iterator[RunResult[Data] | BareRunResult[Data]]:
         """Yield whole run-result pages (read ``cost_usd`` per page)."""
@@ -199,6 +205,7 @@ class AsyncPaginator(Generic[Item, Data]):
         tuple[RunResult[Data] | BareRunResult[Data], dict[str, Any] | None]
     ]:
         cursor: str | None = None
+        page_number = 1
         while True:
             page_input = dict(self._input)
             if cursor is not None:
@@ -206,7 +213,10 @@ class AsyncPaginator(Generic[Item, Data]):
             raw = await self._client._arun_raw(  # pyright: ignore[reportPrivateUsage]
                 self._slug,
                 page_input,
-                cast("RequestOptions | None", self._page_options),
+                cast(
+                    "RequestOptions | None",
+                    _options_for_page(self._page_options, page_number),
+                ),
             )
             page = _validate_page(raw, self._data_model, self._bare)
             data = _raw_page_data(raw, self._bare)
@@ -214,6 +224,7 @@ class AsyncPaginator(Generic[Item, Data]):
             cursor = _next_cursor(data)
             if cursor is None:
                 return
+            page_number += 1
 
     async def pages(self) -> AsyncIterator[RunResult[Data] | BareRunResult[Data]]:
         """Yield whole run-result pages (read ``cost_usd`` per page)."""
@@ -263,6 +274,19 @@ def _page_options(options: object) -> object:
     return stripped or None
 
 
+def _options_for_page(options: object, page_number: int) -> object:
+    """Derive a distinct explicit key for one page, preserving other options."""
+    if not isinstance(options, dict):
+        return options
+    source = as_dict(cast("object", options))
+    key = source.get("idempotency_key")
+    if not isinstance(key, str):
+        return source
+    page_options: dict[str, object] = dict(source)
+    page_options["idempotency_key"] = page_idempotency_key(key, page_number)
+    return page_options
+
+
 def paginate(
     client: AnyAPI,
     slug: str,

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/_transport.py

@@ -7,12 +7,17 @@ through here. The wire contract is frozen:
     Authorization: Bearer <api_key>
     Content-Type: application/json
     Accept: application/json
+    Idempotency-Key: <per-call key> (unless the client kill switch is off)
     body = json(input)
     query params (only when set): fields (comma-joined), max_items, summary=true
 
 HTTP 200 parses into ``RunResult[Any]``; any other status maps to the frozen
-error hierarchy. Retries cover only HTTP 429 and network failures, never
-timeouts, with jittered exponential backoff honoring ``Retry-After`` on 429.
+error hierarchy. Retries cover HTTP 429 and retry-safe transport failures,
+never timeouts. Billed POSTs retry only connection-establishment failures that
+prove no request was delivered. A ``ReadError`` is ambiguous: it can occur
+before the server reads the request, as well as after a body was sent, so it
+must not retry. Idempotent or bodyless requests retry any transport failure.
+Backoff is jittered exponential and honors ``Retry-After`` on 429.
 """
 
 from __future__ import annotations
@@ -33,6 +38,10 @@ from ._errors import (
     TimeoutError,
     error_for_status,
 )
+from ._idempotency import (
+    generate_idempotency_key,
+    validate_idempotency_key,
+)
 from .types import RequestOptions, RunResult
 
 __all__ = [
@@ -42,6 +51,7 @@ __all__ = [
     "compute_delay",
     "RetryState",
     "error_message",
+    "error_details",
     "as_dict",
     "is_retryable_error",
     "sleep",
@@ -77,6 +87,7 @@ def build_request(
     api_key: str,
     options: RequestOptions | None,
     timeout: float,
+    idempotency: str,
 ) -> httpx.Request:
     """Assemble the httpx.Request for a SKU run (no client bound).
 
@@ -89,6 +100,16 @@ def build_request(
         "Content-Type": "application/json",
         "Accept": "application/json",
     }
+    if idempotency == "auto":
+        key = (
+            options["idempotency_key"]
+            if options is not None and "idempotency_key" in options
+            else generate_idempotency_key()
+        )
+        validate_idempotency_key(key)
+        headers["Idempotency-Key"] = key
+    # This request is built once before the retry loop. httpx serializes ``json``
+    # here, so every send reuses the exact raw body bytes used for fingerprinting.
     return httpx.Request(
         "POST",
         url,
@@ -111,11 +132,19 @@ def as_dict(value: object) -> dict[str, object]:
 
 
 def error_message(body: object, status: int) -> str:
-    """Extract the ``{error}`` string from a JSON body, else a generic message."""
-    err = as_dict(body).get("error")
+    """Extract the ``{error, code}`` details and return the message."""
+    return error_details(body, status)[0]
+
+
+def error_details(body: object, status: int) -> tuple[str, str | None]:
+    """Extract the error message and stable code from a JSON body."""
+    body_dict = as_dict(body)
+    err = body_dict.get("error")
+    code = body_dict.get("code")
+    parsed_code = code if isinstance(code, str) and code else None
     if isinstance(err, str):
-        return err
-    return _fallback_message(status)
+        return err, parsed_code
+    return _fallback_message(status), parsed_code
 
 
 def parse_raw(response: httpx.Response) -> dict[str, Any]:
@@ -149,9 +178,9 @@ def parse_raw(response: httpx.Response) -> dict[str, Any]:
         err_body = response.json()
     except ValueError:
         err_body = None
-    message = error_message(err_body, response.status_code)
+    message, code = error_details(err_body, response.status_code)
     raise error_for_status(
-        response.status_code, message, request_id=request_id
+        response.status_code, message, request_id=request_id, code=code
     )
 
 
@@ -227,11 +256,34 @@ class RetryState:
         return delay
 
 
-def is_retryable_error(exc: AnyAPIError) -> bool:
-    """Retry only rate limits and connection failures, never timeouts."""
-    if isinstance(exc, TimeoutError):
+def is_retryable_error(
+    exc: AnyAPIError | httpx.HTTPError,
+    *,
+    request_may_be_billed: bool = False,
+) -> bool:
+    """Retry 429s and transport failures that are safe for this request shape.
+
+    Idempotent or bodyless requests retry any non-timeout transport failure.
+    A billed request retries only ``httpx.ConnectError``, the reliable pre-send
+    signal. ``httpx.ReadError`` does not establish that bytes were delivered:
+    an accept-then-close race or a stale keepalive connection can raise it
+    before the server reads the request. It is still unsafe to retry because
+    the same type can also represent a failure after delivery. The default
+    preserves the one-argument behavior for callers passing an ``AnyAPIError``.
+    """
+    # ConnectTimeout is a TimeoutException, not a ConnectError. The billed POST
+    # loops catch all TimeoutException instances before calling this predicate,
+    # so the httpx term is unreachable there. Retain it so direct callers stay
+    # timeout-safe and the predicate does not depend on caller catch ordering.
+    if isinstance(exc, (TimeoutError, httpx.TimeoutException)):
         return False
-    return isinstance(exc, (RateLimitedError, ConnectionError))
+    if isinstance(exc, RateLimitedError):
+        return True
+    if isinstance(exc, ConnectionError):
+        return not request_may_be_billed
+    if isinstance(exc, httpx.HTTPError):
+        return not request_may_be_billed or isinstance(exc, httpx.ConnectError)
+    return False
 
 
 def sleep(seconds: float) -> None:

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/platforms/bluesky.py

@@ -155,7 +155,7 @@ class BlueskyNamespace:
         """Bluesky User Posts
 
         List a Bluesky account's recent posts (text, author handle, like, reply, and
-        repost counts) by handle as clean JSON, normalized across providers.
+        repost counts) by handle as clean JSON.
 
         Price: $0.002 per request.
 
@@ -225,7 +225,7 @@ class AsyncBlueskyNamespace:
         """Bluesky User Posts
 
         List a Bluesky account's recent posts (text, author handle, like, reply, and
-        repost counts) by handle as clean JSON, normalized across providers.
+        repost counts) by handle as clean JSON.
 
         Price: $0.002 per request.
 

{getanyapi-0.9.2 → getanyapi-0.9.6}/src/getanyapi/platforms/email.py

@@ -26,7 +26,7 @@ class EmailVerifyInput(TypedDict, total=False):
     """Input for Email Verifier."""
 
     email: Required[str]
-    """The email address to verify (e.g. jane.doe@acme.com)."""
+    """The email address to verify (e.g. jane.doe@acme.com). Exactly one @, a dotted domain, no whitespace or angle brackets. Addresses on reserved, never-deliverable TLDs (.invalid, .test, .example, .localhost, .local, .internal, .blink) and HTML/JSON escape artifacts (a u003e prefix) are rejected locally with no charge."""
 
 
 class EmailFindData(BaseModel):
@@ -52,7 +52,7 @@ class EmailFindItem(BaseModel):
 
 class EmailVerifyData(BaseModel):
     items: list[EmailVerifyItem] = Field(
-        description="Verification records: the email address with its deliverability verdict and syntax, domain, and mailbox check details. Populated whenever the provider has data for the entity."
+        description="Verification records: the email address with its deliverability verdict and the domain, mailbox, and reputation signals behind it. A record is returned for every syntactically valid address, including ones the verdict marks undeliverable. Populated whenever the provider has data for the entity."
     )
 
 
@@ -109,8 +109,11 @@ class EmailNamespace:
     ) -> RunResult[EmailVerifyData]:
         """Email Verifier
 
-        Verify any email address for deliverability: syntax, domain, and mailbox
-        checks in one normalized response.
+        Verify an email address for deliverability: a status verdict (valid, risky,
+        or invalid) with domain, mailbox, catch-all, disposable, and role signals
+        plus a confidence score. Malformed addresses are rejected by the input
+        schema with no charge; every syntactically valid address returns a billed
+        verdict, including undeliverable ones.
 
         Price: $0 per request plus $0.0008 per result (maximum $0.0008).
 
@@ -154,8 +157,11 @@ class AsyncEmailNamespace:
     ) -> RunResult[EmailVerifyData]:
         """Email Verifier
 
-        Verify any email address for deliverability: syntax, domain, and mailbox
-        checks in one normalized response.
+        Verify an email address for deliverability: a status verdict (valid, risky,
+        or invalid) with domain, mailbox, catch-all, disposable, and role signals
+        plus a confidence score. Malformed addresses are rejected by the input
+        schema with no charge; every syntactically valid address returns a billed
+        verdict, including undeliverable ones.
 
         Price: $0 per request plus $0.0008 per result (maximum $0.0008).