waba-sdk 1.0.0__py3-none-any.whl

waba_sdk/__init__.py

@@ -0,0 +1,153 @@
+"""Async Python SDK for the WhatsApp Business Cloud API.
+
+Quickstart::
+
+    import asyncio
+    from waba_sdk import WhatsApp
+
+    async def main():
+        async with WhatsApp.from_env() as client:
+            await client.send_text("+15551234567", "hello")
+
+    asyncio.run(main())
+"""
+
+from .client import WhatsApp
+from .errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    MediaError,
+    RateLimitError,
+    ServerError,
+    WebhookVerificationError,
+    WhatsAppError,
+)
+from .media import MediaDownload, MediaInfo
+from .messages import (
+    AudioMessage,
+    BodyComponent,
+    Button,
+    ButtonComponent,
+    ButtonParameter,
+    ButtonsMessage,
+    CatalogMessage,
+    Contact,
+    ContactAddress,
+    ContactEmail,
+    ContactName,
+    ContactOrg,
+    ContactPhone,
+    ContactsMessage,
+    ContactURL,
+    Context,
+    CTAUrlMessage,
+    CurrencyParameter,
+    CurrencyValue,
+    DateTimeParameter,
+    DateTimeValue,
+    DocumentHeader,
+    DocumentMessage,
+    DocumentParameter,
+    FlowMessage,
+    Header,
+    HeaderComponent,
+    ImageHeader,
+    ImageMessage,
+    ImageParameter,
+    InteractiveMessage,
+    ListMessage,
+    ListRow,
+    ListSection,
+    LocationMessage,
+    LocationRequestMessage,
+    Message,
+    MultiProductMessage,
+    OutboundMessage,
+    Parameter,
+    ProductSection,
+    ReactionMessage,
+    SingleProductMessage,
+    StickerMessage,
+    TemplateComponent,
+    TemplateMessage,
+    TextHeader,
+    TextMessage,
+    TextParameter,
+    VideoHeader,
+    VideoMessage,
+    VideoParameter,
+)
+from .types import normalize_phone
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    # client
+    "WhatsApp",
+    "normalize_phone",
+    # errors
+    "WhatsAppError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "ServerError",
+    "MediaError",
+    "WebhookVerificationError",
+    # media value objects
+    "MediaInfo",
+    "MediaDownload",
+    # messages
+    "OutboundMessage",
+    "Context",
+    "Message",
+    "TextMessage",
+    "ImageMessage",
+    "VideoMessage",
+    "AudioMessage",
+    "DocumentMessage",
+    "StickerMessage",
+    "LocationMessage",
+    "ContactsMessage",
+    "Contact",
+    "ContactName",
+    "ContactPhone",
+    "ContactEmail",
+    "ContactAddress",
+    "ContactURL",
+    "ContactOrg",
+    "ReactionMessage",
+    "TemplateMessage",
+    "Parameter",
+    "TextParameter",
+    "CurrencyParameter",
+    "CurrencyValue",
+    "DateTimeParameter",
+    "DateTimeValue",
+    "ImageParameter",
+    "VideoParameter",
+    "DocumentParameter",
+    "HeaderComponent",
+    "BodyComponent",
+    "ButtonComponent",
+    "ButtonParameter",
+    "TemplateComponent",
+    "InteractiveMessage",
+    "Header",
+    "TextHeader",
+    "ImageHeader",
+    "VideoHeader",
+    "DocumentHeader",
+    "ButtonsMessage",
+    "Button",
+    "ListMessage",
+    "ListSection",
+    "ListRow",
+    "CTAUrlMessage",
+    "FlowMessage",
+    "SingleProductMessage",
+    "MultiProductMessage",
+    "CatalogMessage",
+    "ProductSection",
+    "LocationRequestMessage",
+]

waba_sdk/_http.py

@@ -0,0 +1,171 @@
+"""Internal HTTP client with lazy session, retries, and Graph error mapping."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from typing import Any, Mapping, Optional
+
+import aiohttp
+
+from .errors import WhatsAppError, build_error
+
+logger = logging.getLogger("waba_sdk.http")
+
+_DEFAULT_RETRY_STATUSES = (429, 500, 502, 503, 504)
+
+
+class HttpClient:
+    """Owns the shared :class:`aiohttp.ClientSession` and HTTP retry logic.
+
+    The session is created lazily on first request and reused for all
+    subsequent calls. Use ``await client.close()`` or ``async with`` to release
+    it.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        retry_statuses: tuple[int, ...] = _DEFAULT_RETRY_STATUSES,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> None:
+        if not token:
+            raise ValueError("token is required")
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._max_retries = max_retries
+        self._retry_statuses = retry_statuses
+        self._session = session
+        self._owns_session = session is None
+        self._lock = asyncio.Lock()
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is not None and not self._session.closed:
+            return self._session
+        async with self._lock:
+            if self._session is None or self._session.closed:
+                connector = aiohttp.TCPConnector(limit=100, ttl_dns_cache=300)
+                self._session = aiohttp.ClientSession(
+                    timeout=self._timeout,
+                    connector=connector,
+                )
+                self._owns_session = True
+        return self._session
+
+    async def close(self) -> None:
+        if (
+            self._session is not None
+            and self._owns_session
+            and not self._session.closed
+        ):
+            await self._session.close()
+        self._session = None
+
+    async def __aenter__(self) -> "HttpClient":
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return min(0.5 * (2**attempt), 30.0) + random.uniform(0, 0.25)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Mapping[str, Any]] = None,
+        data: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        absolute_url: Optional[str] = None,
+    ) -> aiohttp.ClientResponse:
+        """Perform a request and return the open response.
+
+        Caller is responsible for ``await response.read()`` / ``response.json()``
+        and releasing it (use ``async with`` on the return value).
+        """
+        session = await self._ensure_session()
+        url = absolute_url or f"{self._base_url}{path}"
+        merged_headers = {"Authorization": f"Bearer {self._token}"}
+        if headers:
+            merged_headers.update(headers)
+
+        attempt = 0
+        while True:
+            try:
+                resp = await session.request(
+                    method,
+                    url,
+                    json=json,
+                    data=data,
+                    params=params,
+                    headers=merged_headers,
+                )
+            except aiohttp.ClientError as exc:
+                if attempt >= self._max_retries:
+                    raise WhatsAppError(f"network error: {exc}") from exc
+                await asyncio.sleep(self._backoff(attempt))
+                attempt += 1
+                continue
+
+            if resp.status in self._retry_statuses and attempt < self._max_retries:
+                retry_after_header = resp.headers.get("Retry-After")
+                try:
+                    retry_after = (
+                        float(retry_after_header) if retry_after_header else 0.0
+                    )
+                except (TypeError, ValueError):
+                    retry_after = 0.0
+                wait = retry_after if retry_after > 0 else self._backoff(attempt)
+                resp.release()
+                await asyncio.sleep(wait)
+                attempt += 1
+                continue
+
+            if resp.status >= 400:
+                await self._raise_for_status(resp)
+
+            return resp
+
+    @staticmethod
+    async def _raise_for_status(resp: aiohttp.ClientResponse) -> None:
+        try:
+            data: Any = await resp.json()
+        except Exception:
+            try:
+                data = {"raw": await resp.text()}
+            except Exception:
+                data = None
+        raise build_error(resp.status, data, headers=dict(resp.headers))
+
+    async def post_json(self, path: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+        resp = await self.request("POST", path, json=payload)
+        async with resp:
+            return await resp.json()
+
+    async def get_json(
+        self,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> dict[str, Any]:
+        resp = await self.request("GET", path, params=params)
+        async with resp:
+            return await resp.json()
+
+
+__all__ = ["HttpClient"]