multiwa 1.0.0__py3-none-any.whl

multiwa/__init__.py

@@ -0,0 +1,31 @@
+"""
+MultiWA Python SDK
+
+Official Python SDK for MultiWA - WhatsApp Business API Gateway.
+"""
+
+from .client import MultiWA, AsyncMultiWA
+from .webhooks import verify_webhook_signature
+from .types import (
+    Message,
+    MessageResult,
+    Contact,
+    Broadcast,
+    Template,
+    Profile,
+    Webhook,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "MultiWA",
+    "AsyncMultiWA",
+    "Message",
+    "MessageResult",
+    "Contact",
+    "Broadcast",
+    "Template",
+    "Profile",
+    "Webhook",
+    "verify_webhook_signature",
+]

multiwa/broadcasts.py

@@ -0,0 +1,147 @@
+"""
+MultiWA Python SDK - Broadcasts Client
+
+Client for managing broadcast campaigns.
+"""
+
+from typing import Optional, List, Dict, Any
+import httpx
+
+from .types import Broadcast
+
+
+class BroadcastsClient:
+    """Synchronous Broadcasts API client"""
+    
+    def __init__(self, http: httpx.Client):
+        self._http = http
+    
+    def create(
+        self,
+        profile_id: str,
+        name: str,
+        recipients: List[str],
+        template_id: Optional[str] = None,
+        message: Optional[str] = None,
+        schedule_at: Optional[str] = None,
+    ) -> Broadcast:
+        """Create a new broadcast campaign"""
+        response = self._http.post("/broadcasts", json={
+            "profileId": profile_id,
+            "name": name,
+            "recipients": recipients,
+            "templateId": template_id,
+            "message": message,
+            "scheduleAt": schedule_at,
+        })
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    def get(self, broadcast_id: str) -> Broadcast:
+        """Get a broadcast by ID"""
+        response = self._http.get(f"/broadcasts/{broadcast_id}")
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    def list(
+        self,
+        profile_id: str,
+        limit: int = 50,
+        offset: int = 0,
+        status: Optional[str] = None,
+    ) -> List[Broadcast]:
+        """List broadcasts for a profile"""
+        params: Dict[str, Any] = {
+            "limit": limit,
+            "offset": offset,
+        }
+        if status:
+            params["status"] = status
+            
+        response = self._http.get(f"/broadcasts/profile/{profile_id}", params=params)
+        response.raise_for_status()
+        return [Broadcast(**b) for b in response.json()]
+    
+    def start(self, broadcast_id: str) -> Broadcast:
+        """Start a broadcast"""
+        response = self._http.post(f"/broadcasts/{broadcast_id}/start")
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    def pause(self, broadcast_id: str) -> Broadcast:
+        """Pause a broadcast"""
+        response = self._http.post(f"/broadcasts/{broadcast_id}/pause")
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    def cancel(self, broadcast_id: str) -> Broadcast:
+        """Cancel a broadcast"""
+        response = self._http.post(f"/broadcasts/{broadcast_id}/cancel")
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    def delete(self, broadcast_id: str) -> Dict[str, bool]:
+        """Delete a broadcast"""
+        response = self._http.delete(f"/broadcasts/{broadcast_id}")
+        response.raise_for_status()
+        return response.json()
+    
+    def stats(self, broadcast_id: str) -> Dict[str, Any]:
+        """Get broadcast statistics"""
+        response = self._http.get(f"/broadcasts/{broadcast_id}/stats")
+        response.raise_for_status()
+        return response.json()
+
+
+class AsyncBroadcastsClient:
+    """Asynchronous Broadcasts API client"""
+    
+    def __init__(self, http: httpx.AsyncClient):
+        self._http = http
+    
+    async def create(
+        self,
+        profile_id: str,
+        name: str,
+        recipients: List[str],
+        template_id: Optional[str] = None,
+        message: Optional[str] = None,
+        schedule_at: Optional[str] = None,
+    ) -> Broadcast:
+        """Create a new broadcast campaign"""
+        response = await self._http.post("/broadcasts", json={
+            "profileId": profile_id,
+            "name": name,
+            "recipients": recipients,
+            "templateId": template_id,
+            "message": message,
+            "scheduleAt": schedule_at,
+        })
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    async def get(self, broadcast_id: str) -> Broadcast:
+        """Get a broadcast by ID"""
+        response = await self._http.get(f"/broadcasts/{broadcast_id}")
+        response.raise_for_status()
+        return Broadcast(**response.json())
+    
+    async def list(
+        self,
+        profile_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Broadcast]:
+        """List broadcasts for a profile"""
+        response = await self._http.get(
+            f"/broadcasts/profile/{profile_id}",
+            params={"limit": limit, "offset": offset}
+        )
+        response.raise_for_status()
+        return [Broadcast(**b) for b in response.json()]
+    
+    async def start(self, broadcast_id: str) -> Broadcast:
+        """Start a broadcast"""
+        response = await self._http.post(f"/broadcasts/{broadcast_id}/start")
+        response.raise_for_status()
+        return Broadcast(**response.json())

multiwa/client.py

@@ -0,0 +1,173 @@
+"""
+MultiWA Python SDK - Core Client
+
+Main client class for synchronous and asynchronous API access.
+"""
+
+from typing import Optional, Dict, Any
+import httpx
+
+from .messages import MessagesClient, AsyncMessagesClient
+from .contacts import ContactsClient, AsyncContactsClient
+from .broadcasts import BroadcastsClient, AsyncBroadcastsClient
+from .profiles import ProfilesClient, AsyncProfilesClient
+from .webhooks import WebhooksClient, AsyncWebhooksClient
+
+
+def _normalize_base_url(base_url: str) -> str:
+    """Return ``base_url`` with exactly one trailing slash.
+
+    httpx joins ``base_url`` with the request path using URL semantics, so the
+    configured base must end with a slash. Request paths must be relative
+    (no leading slash) for the base path such as ``/api/v1`` to survive.
+    """
+    return base_url.rstrip("/") + "/"
+
+
+class _MultiWAHttpClient(httpx.Client):
+    """httpx.Client variant that preserves the API base path.
+
+    A request path that begins with ``/`` is treated by URL semantics as
+    absolute and would drop the ``/api/v1`` prefix configured on the base
+    URL. Existing endpoint methods in this SDK call the HTTP client with
+    leading-slash paths (for example ``/messages/text``). To keep them
+    working while still preserving the configured base path, we trim the
+    leading slash before httpx builds the request.
+    """
+
+    def build_request(self, method, url, **kwargs):  # type: ignore[override]
+        if isinstance(url, str) and url.startswith("/"):
+            url = url.lstrip("/")
+        return super().build_request(method, url, **kwargs)
+
+
+class _MultiWAAsyncHttpClient(httpx.AsyncClient):
+    """Async variant of ``_MultiWAHttpClient`` with the same behavior."""
+
+    def build_request(self, method, url, **kwargs):  # type: ignore[override]
+        if isinstance(url, str) and url.startswith("/"):
+            url = url.lstrip("/")
+        return super().build_request(method, url, **kwargs)
+
+
+class MultiWA:
+    """
+    Synchronous MultiWA API Client
+
+    Example:
+        client = MultiWA(
+            base_url="https://your-instance.com/api/v1",
+            api_key="your-api-key",
+        )
+        result = client.messages.send_text(profile_id, to, "Hello!")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+    ):
+        # Keep the externally-visible base_url unchanged (no trailing slash),
+        # but pass a trailing-slash version to httpx so the API prefix is
+        # preserved when endpoints use either absolute or relative paths.
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+        self._http = _MultiWAHttpClient(
+            base_url=_normalize_base_url(base_url),
+            headers={
+                "X-API-Key": api_key,
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+        # Initialize API clients
+        self.messages = MessagesClient(self._http)
+        self.contacts = ContactsClient(self._http)
+        self.broadcasts = BroadcastsClient(self._http)
+        self.profiles = ProfilesClient(self._http)
+        self.webhooks = WebhooksClient(self._http)
+
+    def close(self):
+        """Close the HTTP client"""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make a raw API request"""
+        response = self._http.request(method, path, **kwargs)
+        response.raise_for_status()
+        return response.json()
+
+
+class AsyncMultiWA:
+    """
+    Asynchronous MultiWA API Client
+
+    Example:
+        async with AsyncMultiWA(
+            base_url="https://your-instance.com/api/v1",
+            api_key="your-api-key",
+        ) as client:
+            result = await client.messages.send_text(profile_id, to, "Hello!")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+        self._http = _MultiWAAsyncHttpClient(
+            base_url=_normalize_base_url(base_url),
+            headers={
+                "X-API-Key": api_key,
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+        # Initialize API clients
+        self.messages = AsyncMessagesClient(self._http)
+        self.contacts = AsyncContactsClient(self._http)
+        self.broadcasts = AsyncBroadcastsClient(self._http)
+        self.profiles = AsyncProfilesClient(self._http)
+        self.webhooks = AsyncWebhooksClient(self._http)
+
+    async def close(self):
+        """Close the HTTP client"""
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make a raw API request"""
+        response = await self._http.request(method, path, **kwargs)
+        response.raise_for_status()
+        return response.json()

multiwa/contacts.py

@@ -0,0 +1,172 @@
+"""
+MultiWA Python SDK - Contacts Client
+
+Client for managing WhatsApp contacts.
+"""
+
+from typing import Optional, List, Dict, Any
+import httpx
+
+from .types import Contact
+
+
+class ContactsClient:
+    """Synchronous Contacts API client"""
+    
+    def __init__(self, http: httpx.Client):
+        self._http = http
+    
+    def create(
+        self,
+        profile_id: str,
+        phone: str,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Contact:
+        """Create a new contact"""
+        response = self._http.post("/contacts", json={
+            "profileId": profile_id,
+            "phone": phone,
+            "name": name,
+            "email": email,
+            "tags": tags or [],
+            "metadata": metadata or {},
+        })
+        response.raise_for_status()
+        return Contact(**response.json())
+    
+    def get(self, contact_id: str) -> Contact:
+        """Get a contact by ID"""
+        response = self._http.get(f"/contacts/{contact_id}")
+        response.raise_for_status()
+        return Contact(**response.json())
+    
+    def update(
+        self,
+        contact_id: str,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Contact:
+        """Update a contact"""
+        data = {}
+        if name is not None:
+            data["name"] = name
+        if email is not None:
+            data["email"] = email
+        if tags is not None:
+            data["tags"] = tags
+        if metadata is not None:
+            data["metadata"] = metadata
+            
+        response = self._http.patch(f"/contacts/{contact_id}", json=data)
+        response.raise_for_status()
+        return Contact(**response.json())
+    
+    def delete(self, contact_id: str) -> Dict[str, bool]:
+        """Delete a contact"""
+        response = self._http.delete(f"/contacts/{contact_id}")
+        response.raise_for_status()
+        return response.json()
+    
+    def list(
+        self,
+        profile_id: str,
+        limit: int = 50,
+        offset: int = 0,
+        search: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> List[Contact]:
+        """List contacts for a profile"""
+        params: Dict[str, Any] = {
+            "limit": limit,
+            "offset": offset,
+        }
+        if search:
+            params["search"] = search
+        if tags:
+            params["tags"] = ",".join(tags)
+            
+        response = self._http.get(f"/contacts/profile/{profile_id}", params=params)
+        response.raise_for_status()
+        return [Contact(**c) for c in response.json()]
+    
+    def add_tags(
+        self,
+        contact_id: str,
+        tags: List[str],
+    ) -> Contact:
+        """Add tags to a contact"""
+        response = self._http.post(f"/contacts/{contact_id}/tags", json={
+            "tags": tags,
+        })
+        response.raise_for_status()
+        return Contact(**response.json())
+    
+    def remove_tags(
+        self,
+        contact_id: str,
+        tags: List[str],
+    ) -> Contact:
+        """Remove tags from a contact"""
+        response = self._http.delete(f"/contacts/{contact_id}/tags", json={
+            "tags": tags,
+        })
+        response.raise_for_status()
+        return Contact(**response.json())
+
+
+class AsyncContactsClient:
+    """Asynchronous Contacts API client"""
+    
+    def __init__(self, http: httpx.AsyncClient):
+        self._http = http
+    
+    async def create(
+        self,
+        profile_id: str,
+        phone: str,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Contact:
+        """Create a new contact"""
+        response = await self._http.post("/contacts", json={
+            "profileId": profile_id,
+            "phone": phone,
+            "name": name,
+            "email": email,
+            "tags": tags or [],
+            "metadata": metadata or {},
+        })
+        response.raise_for_status()
+        return Contact(**response.json())
+    
+    async def get(self, contact_id: str) -> Contact:
+        """Get a contact by ID"""
+        response = await self._http.get(f"/contacts/{contact_id}")
+        response.raise_for_status()
+        return Contact(**response.json())
+    
+    async def list(
+        self,
+        profile_id: str,
+        limit: int = 50,
+        offset: int = 0,
+        search: Optional[str] = None,
+    ) -> List[Contact]:
+        """List contacts for a profile"""
+        params: Dict[str, Any] = {
+            "limit": limit,
+            "offset": offset,
+        }
+        if search:
+            params["search"] = search
+            
+        response = await self._http.get(f"/contacts/profile/{profile_id}", params=params)
+        response.raise_for_status()
+        return [Contact(**c) for c in response.json()]