mobilevalidate-sdk 1.0.0__py3-none-any.whl

mobilevalidate/_constants.py

@@ -0,0 +1,42 @@
+"""Public constants: the sandbox key and the documented test values (magic numbers and e-mail addresses)."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://api.mobilevalidate.com"
+
+#: Public sandbox key — public by design. It answers ONLY the documented test values below (any other input is
+#: refused with ``sandbox_magic_only``), is limited per client IP, never billed and never reaches a network.
+SANDBOX_PUBLIC_KEY = "mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym"
+
+#: Server-enforced sandbox limits (per client IP; the key is shared by everyone).
+SANDBOX_LIMITS: Dict[str, int] = {"per_minute": 30, "per_day": 1000, "max_job_rows": 10}
+
+#: Magic phone numbers (E.164) → documented answer in test mode (sandbox key and personal test keys).
+TEST_NUMBERS: Dict[str, str] = {
+    # Magic test numbers: the same answer for every phone service, with any test key (including the sandbox key).
+    "registered": "+447700900001",
+    "not_registered": "+447700900002",
+    "unknown": "+447700900003",  # reason UPSTREAM_TIMEOUT
+    "pending": "+447700900004",  # pending for about 5 s, then registered
+    "unsupported_country": "+447700900005",
+    "business": "+447700900006",  # registered; a business account for whatsapp.business
+    "rate_limited": "+447700900429",  # the request fails with rate_limited
+    "insufficient_balance": "+447700900402",  # the request fails with insufficient_balance
+}
+
+TEST_EMAIL_DOMAIN = "test.mobilevalidate.com"
+
+TEST_EMAILS: Dict[str, str] = {
+    # Magic test e-mail addresses: the same answer for every e-mail service.
+    "registered": "registered@test.mobilevalidate.com",
+    "not_registered": "not-registered@test.mobilevalidate.com",
+    "unknown": "unknown@test.mobilevalidate.com",  # reason UPSTREAM_TIMEOUT
+    "pending": "pending@test.mobilevalidate.com",  # pending for about 5 s, then registered
+    "unsupported": "unsupported@test.mobilevalidate.com",  # unknown, reason UNSUPPORTED_PROVIDER
+    "rate_limited": "rate-limited@test.mobilevalidate.com",  # the request fails with rate_limited
+    "insufficient_balance": "no-balance@test.mobilevalidate.com",  # the request fails with insufficient_balance
+}

mobilevalidate/_errors.py

@@ -0,0 +1,364 @@
+"""Typed errors. Every API error code has its own class; all derive from :class:`MobileValidateError`."""
+
+from __future__ import annotations
+
+import email.utils
+import time
+from typing import Any, Dict, Mapping, Optional, Type
+
+__all__ = [
+    "MobileValidateError",
+    "APIError",
+    "InvalidRequestError",
+    "TooManyNumbersError",
+    "TestNumberOnlyError",
+    "InvalidCursorError",
+    "UnauthorizedError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "CostLimitExceededError",
+    "InsufficientScopeError",
+    "ServiceDisabledError",
+    "SandboxMagicOnlyError",
+    "SuspectedEnumerationError",
+    "NotFoundError",
+    "IdempotencyKeyReusedError",
+    "IdempotencyRequestInProgressError",
+    "TestKeyExistsError",
+    "PayloadTooLargeError",
+    "RateLimitedError",
+    "RateLimitError",
+    "DailyCapReachedError",
+    "SpendCapReachedError",
+    "InternalServerError",
+    "TemporarilyUnavailableError",
+    "InvalidResponseError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "MissingApiKeyError",
+    "InvalidArgumentError",
+    "WebhookVerificationError",
+]
+
+# Retryability per code, used when the error body does not say.
+_RETRYABLE = {
+    "idempotency_request_in_progress": True,
+    "rate_limited": True,
+    "daily_cap_reached": True,
+    "internal_error": True,
+    "temporarily_unavailable": True,
+    "connection_error": True,
+    "timeout": True,
+}
+
+
+class MobileValidateError(Exception):
+    """Base class of every error raised by the SDK (except :class:`WebhookVerificationError`)."""
+
+    default_code = "error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        retryable: Optional[bool] = None,
+        request_id: Optional[str] = None,
+        param: Optional[str] = None,
+        doc_url: Optional[str] = None,
+        suggestion: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code: str = code or self.default_code
+        #: HTTP status, or ``None`` when no response was received.
+        self.status = status
+        self.retryable: bool = retryable if retryable is not None else _RETRYABLE.get(self.code, False)
+        self.request_id = request_id
+        self.param = param
+        self.doc_url = doc_url
+        #: Plain-English hint on how to fix the request (may be ``None``).
+        self.suggestion = suggestion
+        #: Server ``Retry-After`` hint in seconds (may be ``None``).
+        self.retry_after = retry_after
+        self.body = body
+
+    def __str__(self) -> str:
+        s = f"{self.code}: {self.message}"
+        if self.suggestion:
+            s += f" (suggestion: {self.suggestion})"
+        if self.request_id:
+            s += f" [request {self.request_id}]"
+        return s
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(code={self.code!r}, status={self.status!r}, message={self.message!r})"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "status": self.status,
+            "retryable": self.retryable,
+            "request_id": self.request_id,
+            "param": self.param,
+            "doc_url": self.doc_url,
+            "suggestion": self.suggestion,
+        }
+
+
+class APIError(MobileValidateError):
+    """The API answered with an error response. Unknown codes are raised as this class."""
+
+    default_code = "api_error"
+
+
+
+class InvalidRequestError(APIError):
+    """400 invalid_request: the request is malformed or a parameter is invalid (see ``param``)."""
+
+    default_code = "invalid_request"
+
+
+class TooManyNumbersError(APIError):
+    """400 too_many_numbers: too many identifiers in one request."""
+
+    default_code = "too_many_numbers"
+
+
+class TestNumberOnlyError(APIError):
+    """400 test_number_only: test values used with a live key (or vice versa)."""
+
+    __test__ = False  # not a pytest test class
+    default_code = "test_number_only"
+
+
+class InvalidCursorError(APIError):
+    """400 invalid_cursor: the pagination cursor is invalid or expired."""
+
+    default_code = "invalid_cursor"
+
+
+class UnauthorizedError(APIError):
+    """401 unauthorized: missing, malformed or revoked API key."""
+
+    default_code = "unauthorized"
+
+
+AuthenticationError = UnauthorizedError
+
+
+class InsufficientBalanceError(APIError):
+    """402 insufficient_balance: not enough credit for this request."""
+
+    default_code = "insufficient_balance"
+
+
+class CostLimitExceededError(APIError):
+    """402 cost_limit_exceeded: the maximum possible cost is above ``max_cost``."""
+
+    default_code = "cost_limit_exceeded"
+
+
+class InsufficientScopeError(APIError):
+    """403 insufficient_scope: the key may not use this endpoint."""
+
+    default_code = "insufficient_scope"
+
+
+class ServiceDisabledError(APIError):
+    """403 service_disabled: a requested check is not available (or bulk only)."""
+
+    default_code = "service_disabled"
+
+
+class SandboxMagicOnlyError(APIError):
+    """403 sandbox_magic_only: the public sandbox key only answers the documented test values."""
+
+    default_code = "sandbox_magic_only"
+
+
+class SuspectedEnumerationError(APIError):
+    """403 suspected_enumeration: the input looks like a generated list."""
+
+    default_code = "suspected_enumeration"
+
+
+class NotFoundError(APIError):
+    """404 not_found: unknown resource or route."""
+
+    default_code = "not_found"
+
+
+class IdempotencyKeyReusedError(APIError):
+    """409 idempotency_key_reused: the key was used with a different request body."""
+
+    default_code = "idempotency_key_reused"
+
+
+class IdempotencyRequestInProgressError(APIError):
+    """409 idempotency_request_in_progress: the same request is still running (retryable)."""
+
+    default_code = "idempotency_request_in_progress"
+
+
+class TestKeyExistsError(APIError):
+    """409 test_key_exists: this e-mail address already has an active test key."""
+
+    __test__ = False
+    default_code = "test_key_exists"
+
+
+class PayloadTooLargeError(APIError):
+    """413 payload_too_large."""
+
+    default_code = "payload_too_large"
+
+
+class RateLimitedError(APIError):
+    """429 rate_limited: slow down (retryable; honours Retry-After)."""
+
+    default_code = "rate_limited"
+
+
+RateLimitError = RateLimitedError
+
+
+class DailyCapReachedError(APIError):
+    """429 daily_cap_reached."""
+
+    default_code = "daily_cap_reached"
+
+
+class SpendCapReachedError(APIError):
+    """429 spend_cap_reached: the key's spend cap is reached (not retryable)."""
+
+    default_code = "spend_cap_reached"
+
+
+class InternalServerError(APIError):
+    """500 internal_error (retryable)."""
+
+    default_code = "internal_error"
+
+
+class TemporarilyUnavailableError(APIError):
+    """503 temporarily_unavailable (retryable)."""
+
+    default_code = "temporarily_unavailable"
+
+
+class InvalidResponseError(APIError):
+    """The response was not valid JSON."""
+
+    default_code = "invalid_response"
+
+
+class APIConnectionError(MobileValidateError):
+    """No usable response: network failure (retryable)."""
+
+    default_code = "connection_error"
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out (retryable)."""
+
+    default_code = "timeout"
+
+
+class MissingApiKeyError(MobileValidateError):
+    """No API key: pass ``api_key=``, set ``MOBILEVALIDATE_API_KEY`` or use ``sandbox=True``."""
+
+    default_code = "missing_api_key"
+
+
+class InvalidArgumentError(MobileValidateError):
+    """An argument was rejected by the SDK before any request was sent."""
+
+    default_code = "invalid_argument"
+
+
+class WebhookVerificationError(Exception):
+    """A webhook signature, timestamp or body could not be verified."""
+
+
+ERROR_CLASSES: Dict[str, Type[MobileValidateError]] = {
+    c.default_code: c
+    for c in (
+        InvalidRequestError, TooManyNumbersError, TestNumberOnlyError, InvalidCursorError, UnauthorizedError,
+        InsufficientBalanceError, CostLimitExceededError, InsufficientScopeError, ServiceDisabledError,
+        SandboxMagicOnlyError, SuspectedEnumerationError, NotFoundError, IdempotencyKeyReusedError,
+        IdempotencyRequestInProgressError, TestKeyExistsError, PayloadTooLargeError, RateLimitedError,
+        DailyCapReachedError, SpendCapReachedError, InternalServerError, TemporarilyUnavailableError,
+        InvalidResponseError, APIConnectionError, APITimeoutError, MissingApiKeyError, InvalidArgumentError,
+    )
+}
+
+
+def _code_for_status(status: int) -> str:
+    if status == 400:
+        return "invalid_request"
+    if status == 401:
+        return "unauthorized"
+    if status == 403:
+        return "insufficient_scope"
+    if status == 404:
+        return "not_found"
+    if status == 413:
+        return "payload_too_large"
+    if status == 429:
+        return "rate_limited"
+    if status == 503:
+        return "temporarily_unavailable"
+    return "internal_error" if status >= 500 else "invalid_request"
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Retry-After as seconds or an HTTP date → seconds (``None`` if absent/invalid)."""
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        dt = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if dt is None:
+        return None
+    return max(0.0, dt.timestamp() - time.time())
+
+
+def make_error(code: str, message: str, **kw: Any) -> MobileValidateError:
+    cls = ERROR_CLASSES.get(code, APIError)
+    return cls(message, code=code, **kw)
+
+
+def error_from_response(status: int, body: Any, headers: Mapping[str, str]) -> MobileValidateError:
+    raw = body.get("error") if isinstance(body, dict) else None
+    e: Dict[str, Any] = raw if isinstance(raw, dict) else {}
+
+    def s(k: str) -> Optional[str]:
+        v = e.get(k)
+        return v if isinstance(v, str) else None
+
+    code = s("code") or _code_for_status(status)
+    retryable = e.get("retryable")
+    if not isinstance(retryable, bool):
+        retryable = _RETRYABLE.get(code, status == 408 or status >= 500)
+    return make_error(
+        code,
+        s("message") or f"Request failed with status {status}",
+        status=status,
+        retryable=retryable,
+        request_id=s("request_id") or headers.get("x-request-id"),
+        param=s("param"),
+        doc_url=s("doc_url"),
+        suggestion=s("suggestion"),
+        retry_after=parse_retry_after(headers.get("retry-after")),
+        body=body,
+    )

mobilevalidate/_http.py

@@ -0,0 +1,285 @@
+"""HTTP transport (sync + async) with retries, jittered backoff, Retry-After and automatic idempotency keys."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import math
+import random as _random
+import time
+import uuid
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, Mapping, Optional, Tuple
+
+import httpx
+
+from ._constants import __version__
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    InvalidResponseError,
+    MissingApiKeyError,
+    MobileValidateError,
+    error_from_response,
+)
+from .types import APIObject
+
+MAX_BACKOFF_S = 8.0
+#: Server hints longer than this are not worth blocking a caller for (e.g. daily caps): the error is raised instead.
+MAX_RETRY_AFTER_S = 60.0
+
+Query = Optional[Mapping[str, Any]]
+
+
+def backoff_seconds(attempt: int, retry_after: Optional[float], rnd: Callable[[], float]) -> float:
+    """Exponential backoff with full jitter; Retry-After wins when present."""
+    if retry_after is not None:
+        return retry_after
+    return float(rnd()) * min(MAX_BACKOFF_S, math.ldexp(0.5, attempt))
+
+
+def _qs_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)
+
+
+class _Base:
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str],
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        rnd: Callable[[], float] = _random.random,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.random = rnd
+
+    def _prepare(
+        self, method: str, path: str, query: Query, body: Any, idempotency_key: Optional[str],
+        accept: str = "application/json",
+    ) -> Tuple[str, Dict[str, str], Optional[Dict[str, str]], Optional[bytes]]:
+        if not self.api_key:
+            raise MissingApiKeyError(
+                "No API key. Pass api_key=..., set MOBILEVALIDATE_API_KEY, or use sandbox=True for the public sandbox key."
+            )
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": accept,
+            "User-Agent": f"mobilevalidate-python/{__version__}",
+        }
+        content = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            content = json.dumps(body, separators=(",", ":")).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        params = {k: _qs_value(v) for k, v in (query or {}).items() if v is not None}
+        return self.base_url + path, headers, params or None, content
+
+    @staticmethod
+    def _idempotency(method: str, key: Optional[str]) -> Optional[str]:
+        # One key per logical call, reused across retries so the server can deduplicate.
+        return (key or str(uuid.uuid4())) if method == "POST" else None
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> APIObject:
+        headers = response.headers
+        text = response.text
+        body: Any = None
+        parse_failed = False
+        if text:
+            try:
+                body = json.loads(text)
+            except ValueError:
+                parse_failed = True
+        if response.status_code >= 400:
+            raise error_from_response(response.status_code, body, headers)
+        request_id = headers.get("x-request-id")
+        if parse_failed:
+            raise InvalidResponseError("Response was not valid JSON", status=response.status_code, request_id=request_id)
+        if isinstance(body, dict):
+            rid = request_id or (body.get("request_id") if isinstance(body.get("request_id"), str) else None)
+            return APIObject(body, rid)
+        obj = APIObject({}, request_id)
+        if body is not None:
+            obj["data"] = body
+        return obj
+
+    @staticmethod
+    def _wrap_transport_error(e: Exception, timeout: float) -> MobileValidateError:
+        if isinstance(e, httpx.TimeoutException):
+            return APITimeoutError(f"Request timed out after {timeout:g} s")
+        return APIConnectionError(f"Network error: {e}")
+
+    def _should_retry(self, err: MobileValidateError, attempt: int, max_retries: int) -> bool:
+        if not err.retryable or attempt >= max_retries:
+            return False
+        return not (err.retry_after is not None and err.retry_after > MAX_RETRY_AFTER_S)
+
+
+class SyncTransport(_Base):
+    def __init__(
+        self,
+        *,
+        http_client: Optional[httpx.Client] = None,
+        sleep: Callable[[float], None] = time.sleep,
+        **kw: Any,
+    ) -> None:
+        super().__init__(**kw)
+        self._owns_client = http_client is None
+        self.client = http_client or httpx.Client()
+        self.sleep = sleep
+
+    def close(self) -> None:
+        if self._owns_client:
+            self.client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Query = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        extra_timeout: float = 0,
+        max_retries: Optional[int] = None,
+    ) -> APIObject:
+        key = self._idempotency(method, idempotency_key)
+        url, headers, params, content = self._prepare(method, path, query, body, key)
+        total_timeout = (self.timeout if timeout is None else timeout) + extra_timeout
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                try:
+                    response = self.client.request(
+                        method, url, headers=headers, params=params, content=content, timeout=total_timeout
+                    )
+                except httpx.TransportError as e:
+                    raise self._wrap_transport_error(e, total_timeout) from e
+                return self._parse(response)
+            except MobileValidateError as err:
+                if not self._should_retry(err, attempt, retries):
+                    raise
+                self.sleep(backoff_seconds(attempt, err.retry_after, self.random))
+                attempt += 1
+
+
+    @contextlib.contextmanager
+    def stream(
+        self, path: str, *, query: Query = None, accept: str, timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> Iterator[httpx.Response]:
+        """GET a streamed (non-JSON) body. Error responses are parsed and raised like :meth:`request`; the timeout
+        covers each read, not the whole transfer."""
+        url, headers, params, _ = self._prepare("GET", path, query, None, None, accept)
+        total_timeout = self.timeout if timeout is None else timeout
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                with self.client.stream("GET", url, headers=headers, params=params, timeout=total_timeout) as response:
+                    if response.status_code >= 400:
+                        response.read()
+                        self._parse(response)
+                    yield response
+                    return
+            except httpx.TransportError as e:
+                err: MobileValidateError = self._wrap_transport_error(e, total_timeout)
+                if not self._should_retry(err, attempt, retries):
+                    raise err from e
+            except MobileValidateError as e:
+                if not self._should_retry(e, attempt, retries):
+                    raise
+                err = e
+            self.sleep(backoff_seconds(attempt, err.retry_after, self.random))
+            attempt += 1
+
+
+class AsyncTransport(_Base):
+    def __init__(
+        self,
+        *,
+        http_client: Optional[httpx.AsyncClient] = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        **kw: Any,
+    ) -> None:
+        super().__init__(**kw)
+        self._owns_client = http_client is None
+        self.client = http_client or httpx.AsyncClient()
+        self.sleep = sleep
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self.client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Query = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        extra_timeout: float = 0,
+        max_retries: Optional[int] = None,
+    ) -> APIObject:
+        key = self._idempotency(method, idempotency_key)
+        url, headers, params, content = self._prepare(method, path, query, body, key)
+        total_timeout = (self.timeout if timeout is None else timeout) + extra_timeout
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                try:
+                    response = await self.client.request(
+                        method, url, headers=headers, params=params, content=content, timeout=total_timeout
+                    )
+                except httpx.TransportError as e:
+                    raise self._wrap_transport_error(e, total_timeout) from e
+                return self._parse(response)
+            except MobileValidateError as err:
+                if not self._should_retry(err, attempt, retries):
+                    raise
+                await self.sleep(backoff_seconds(attempt, err.retry_after, self.random))
+                attempt += 1
+
+
+    @contextlib.asynccontextmanager
+    async def stream(
+        self, path: str, *, query: Query = None, accept: str, timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> AsyncIterator[httpx.Response]:
+        """GET a streamed (non-JSON) body; see :meth:`SyncTransport.stream`."""
+        url, headers, params, _ = self._prepare("GET", path, query, None, None, accept)
+        total_timeout = self.timeout if timeout is None else timeout
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                async with self.client.stream("GET", url, headers=headers, params=params,
+                                              timeout=total_timeout) as response:
+                    if response.status_code >= 400:
+                        await response.aread()
+                        self._parse(response)
+                    yield response
+                    return
+            except httpx.TransportError as e:
+                err: MobileValidateError = self._wrap_transport_error(e, total_timeout)
+                if not self._should_retry(err, attempt, retries):
+                    raise err from e
+            except MobileValidateError as e:
+                if not self._should_retry(e, attempt, retries):
+                    raise
+                err = e
+            await self.sleep(backoff_seconds(attempt, err.retry_after, self.random))
+            attempt += 1