voicetel-api 2.2.10__py3-none-any.whl

voicetel/__init__.py

@@ -0,0 +1,46 @@
+"""Official Python SDK for the VoiceTel REST API.
+
+Quickstart::
+
+    from voicetel import Client
+
+    with Client() as c:
+        c.login(username=1234567890, password="...")
+        for n in c.numbers.list():
+            print(n["number"])
+"""
+
+from __future__ import annotations
+
+from . import models
+from ._version import __version__
+from .client import AsyncClient, Client
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    BadRequestError,
+    ConfigurationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    VoiceTelError,
+)
+
+__all__ = [
+    "ApiError",
+    "AsyncClient",
+    "AuthenticationError",
+    "BadRequestError",
+    "Client",
+    "ConfigurationError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "VoiceTelError",
+    "__version__",
+    "models",
+]

voicetel/_http.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .exceptions import ApiError, ConfigurationError, from_response
+
+DEFAULT_BASE_URL = "https://api.voicetel.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_USER_AGENT = f"voicetel-python/{__version__} (+https://github.com/voicetel/python-sdk)"
+
+_RETRYABLE_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+class Transport:
+    """Sync HTTP transport. Owns an :class:`httpx.Client` and the retry/auth policy.
+
+    The Bearer token is mutable: :meth:`set_bearer` lets the auth flow swap it in after the
+    api-key exchange runs.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        if max_retries < 0:
+            raise ConfigurationError("max_retries must be >= 0")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._user_agent = user_agent
+        self._owns_client = http_client is None
+        self._http: httpx.Client = http_client or httpx.Client(
+            base_url=self._base_url, timeout=timeout
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def api_key(self) -> str | None:
+        return self._api_key
+
+    def set_bearer(self, api_key: str) -> None:
+        self._api_key = api_key
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        require_auth: bool = True,
+    ) -> Any:
+        headers = self._headers(require_auth=require_auth)
+        if method.upper() in ("POST", "PUT", "PATCH"):
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._http.request(
+                    method,
+                    path,
+                    params=_clean_params(params),
+                    json=json,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt >= self._max_retries:
+                    raise ApiError(
+                        f"transport error after {attempt + 1} attempts: {exc}",
+                        status_code=0,
+                    ) from exc
+                _sleep_backoff(attempt)
+                continue
+            if response.status_code in _RETRYABLE_STATUSES and attempt < self._max_retries:
+                _sleep_backoff(attempt, response)
+                continue
+            return _parse(response)
+        # unreachable: the loop always returns or raises
+        assert last_exc is not None  # pragma: no cover
+        raise last_exc  # pragma: no cover
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> Transport:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _headers(self, *, require_auth: bool) -> dict[str, str]:
+        headers = {
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+            "Accept-Encoding": "gzip",
+        }
+        if require_auth:
+            if not self._api_key:
+                raise ConfigurationError(
+                    "no api_key set; pass api_key= to Client(...) or call client.login()"
+                )
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+
+class AsyncTransport:
+    """Async counterpart to :class:`Transport`. Same surface, awaitable :meth:`request`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        if max_retries < 0:
+            raise ConfigurationError("max_retries must be >= 0")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._user_agent = user_agent
+        self._owns_client = http_client is None
+        self._http: httpx.AsyncClient = http_client or httpx.AsyncClient(
+            base_url=self._base_url, timeout=timeout
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def api_key(self) -> str | None:
+        return self._api_key
+
+    def set_bearer(self, api_key: str) -> None:
+        self._api_key = api_key
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        require_auth: bool = True,
+    ) -> Any:
+        headers = self._headers(require_auth=require_auth)
+        if method.upper() in ("POST", "PUT", "PATCH"):
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._http.request(
+                    method,
+                    path,
+                    params=_clean_params(params),
+                    json=json,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt >= self._max_retries:
+                    raise ApiError(
+                        f"transport error after {attempt + 1} attempts: {exc}",
+                        status_code=0,
+                    ) from exc
+                await asyncio.sleep(_backoff_delay(attempt))
+                continue
+            if response.status_code in _RETRYABLE_STATUSES and attempt < self._max_retries:
+                await asyncio.sleep(_backoff_delay(attempt, response))
+                continue
+            return _parse(response)
+        assert last_exc is not None  # pragma: no cover
+        raise last_exc  # pragma: no cover
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTransport:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    def _headers(self, *, require_auth: bool) -> dict[str, str]:
+        headers = {
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+            "Accept-Encoding": "gzip",
+        }
+        if require_auth:
+            if not self._api_key:
+                raise ConfigurationError(
+                    "no api_key set; pass api_key= to AsyncClient(...) or call client.login()"
+                )
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+
+def _clean_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _parse(response: httpx.Response) -> Any:
+    if 200 <= response.status_code < 300:
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise ApiError(
+                f"non-JSON success response: {response.text[:200]}",
+                status_code=response.status_code,
+                body=response.text,
+            ) from exc
+    body: Any
+    try:
+        body = response.json()
+    except ValueError:
+        body = response.text
+    code = None
+    message = f"HTTP {response.status_code}"
+    if isinstance(body, dict):
+        code = body.get("code") or body.get("error")
+        message = body.get("message") or body.get("error") or message
+    raise from_response(response.status_code, code, body, message)
+
+
+def _backoff_delay(attempt: int, response: httpx.Response | None = None) -> float:
+    if response is not None:
+        retry_after = response.headers.get("Retry-After")
+        if retry_after:
+            try:
+                return max(0.0, float(retry_after))
+            except ValueError:
+                pass
+    return float(min(8.0, 0.5 * (2**attempt)))
+
+
+def _sleep_backoff(attempt: int, response: httpx.Response | None = None) -> None:
+    time.sleep(_backoff_delay(attempt, response))

voicetel/_version.py

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

voicetel/auth.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._http import AsyncTransport, Transport
+from .exceptions import ApiError, AuthenticationError
+
+API_KEY_PATH = "/v2.2/account/api-key"
+
+
+def exchange_api_key(transport: Transport, username: int | str, password: str) -> str:
+    """Exchange username/password for a 32-hex API key and install it on ``transport``.
+
+    This is the only endpoint that does not require an Authorization header. Subject to the
+    6 req/hour/IP rate limit shared by all ``account/*`` endpoints.
+    """
+    body = transport.request(
+        "POST",
+        API_KEY_PATH,
+        json={"username": username, "password": password},
+        require_auth=False,
+    )
+    key = _extract_key(body)
+    transport.set_bearer(key)
+    return key
+
+
+async def aexchange_api_key(
+    transport: AsyncTransport, username: int | str, password: str
+) -> str:
+    """Async counterpart to :func:`exchange_api_key`."""
+    body = await transport.request(
+        "POST",
+        API_KEY_PATH,
+        json={"username": username, "password": password},
+        require_auth=False,
+    )
+    key = _extract_key(body)
+    transport.set_bearer(key)
+    return key
+
+
+def _extract_key(body: Any) -> str:
+    if isinstance(body, dict):
+        data = body.get("data")
+        if isinstance(data, dict):
+            key = data.get("apikey")
+            if isinstance(key, str) and key:
+                return key
+    raise AuthenticationError(
+        "api-key response did not contain data.apikey",
+        status_code=200,
+        body=body,
+    )
+
+
+__all__ = ["ApiError", "aexchange_api_key", "exchange_api_key"]

voicetel/client.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    AsyncTransport,
+    Transport,
+)
+from .auth import aexchange_api_key, exchange_api_key
+from .resources import (
+    AccountAsyncResource,
+    AccountResource,
+    AclAsyncResource,
+    AclResource,
+    AuthenticationAsyncResource,
+    AuthenticationResource,
+    E911AsyncResource,
+    E911Resource,
+    GatewaysAsyncResource,
+    GatewaysResource,
+    INumberingAsyncResource,
+    INumberingResource,
+    LookupsAsyncResource,
+    LookupsResource,
+    MessagingAsyncResource,
+    MessagingResource,
+    NumbersAsyncResource,
+    NumbersResource,
+    SupportAsyncResource,
+    SupportResource,
+)
+
+
+class Client:
+    """Synchronous client for the VoiceTel REST API.
+
+    Construct with an existing ``api_key`` or call :meth:`login` to exchange username/password.
+    All resource groups are exposed as attributes (``client.numbers``, ``client.account``, ...).
+
+    Usage as a context manager closes the underlying ``httpx.Client``::
+
+        with Client(api_key=key) as c:
+            account = c.account.get()
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = Transport(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.account = AccountResource(self._transport)
+        self.acl = AclResource(self._transport)
+        self.authentication = AuthenticationResource(self._transport)
+        self.e911 = E911Resource(self._transport)
+        self.gateways = GatewaysResource(self._transport)
+        self.inumbering = INumberingResource(self._transport)
+        self.lookups = LookupsResource(self._transport)
+        self.messaging = MessagingResource(self._transport)
+        self.numbers = NumbersResource(self._transport)
+        self.support = SupportResource(self._transport)
+
+    @property
+    def api_key(self) -> str | None:
+        return self._transport.api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._transport.base_url
+
+    def login(self, username: int | str, password: str) -> str:
+        """Exchange username/password for an API key and install it. Returns the new key."""
+        return exchange_api_key(self._transport, username, password)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class AsyncClient:
+    """Async counterpart to :class:`Client`. Same surface; methods are awaitable.
+
+    Use as an async context manager::
+
+        async with AsyncClient(api_key=key) as c:
+            account = await c.account.get()
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.account = AccountAsyncResource(self._transport)
+        self.acl = AclAsyncResource(self._transport)
+        self.authentication = AuthenticationAsyncResource(self._transport)
+        self.e911 = E911AsyncResource(self._transport)
+        self.gateways = GatewaysAsyncResource(self._transport)
+        self.inumbering = INumberingAsyncResource(self._transport)
+        self.lookups = LookupsAsyncResource(self._transport)
+        self.messaging = MessagingAsyncResource(self._transport)
+        self.numbers = NumbersAsyncResource(self._transport)
+        self.support = SupportAsyncResource(self._transport)
+
+    @property
+    def api_key(self) -> str | None:
+        return self._transport.api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._transport.base_url
+
+    async def login(self, username: int | str, password: str) -> str:
+        return await aexchange_api_key(self._transport, username, password)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

voicetel/exceptions.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class VoiceTelError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class ConfigurationError(VoiceTelError):
+    """Raised when the client is constructed with conflicting or missing config."""
+
+
+class ApiError(VoiceTelError):
+    """Raised when the API returns a non-2xx response.
+
+    Subclasses cover specific status families; catch :class:`ApiError` to handle them all.
+    """
+
+    status_code: int
+    code: str | None
+    body: Any
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status_code={self.status_code}, code={self.code!r})"
+
+
+class BadRequestError(ApiError):
+    """HTTP 400 — the request was malformed or failed server-side validation."""
+
+
+class AuthenticationError(ApiError):
+    """HTTP 401 — bearer token is missing, expired, or invalid."""
+
+
+class PermissionDeniedError(ApiError):
+    """HTTP 403 — authenticated, but not allowed to perform this action."""
+
+
+class NotFoundError(ApiError):
+    """HTTP 404 — the resource does not exist."""
+
+
+class ConflictError(ApiError):
+    """HTTP 409 — request conflicts with current resource state."""
+
+
+class RateLimitError(ApiError):
+    """HTTP 429 — too many requests. The `account/*` endpoints allow only 6 req/hour/IP."""
+
+
+class ServerError(ApiError):
+    """HTTP 5xx — the server hit an error processing the request."""
+
+
+def from_response(status_code: int, code: str | None, body: Any, message: str) -> ApiError:
+    """Map an HTTP status to the most specific :class:`ApiError` subclass."""
+    cls: type[ApiError]
+    if status_code == 400:
+        cls = BadRequestError
+    elif status_code == 401:
+        cls = AuthenticationError
+    elif status_code == 403:
+        cls = PermissionDeniedError
+    elif status_code == 404:
+        cls = NotFoundError
+    elif status_code == 409:
+        cls = ConflictError
+    elif status_code == 429:
+        cls = RateLimitError
+    elif 500 <= status_code < 600:
+        cls = ServerError
+    else:
+        cls = ApiError
+    return cls(message, status_code=status_code, code=code, body=body)