hiws 0.1.0__tar.gz

hiws-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tomas Santana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hiws-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hiws
+Version: 0.1.0
+Summary: A wrapper for WhatsApp's Cloud API
+Home-page: https://github.com/cervant-ai/hiws
+Author: Tomas Santana
+Author-email: Tomas Santana <tomas@cervant.chat>
+License: MIT
+Project-URL: Homepage, https://github.com/cervant-ai/hiws
+Project-URL: Repository, https://github.com/cervant-ai/hiws.git
+Project-URL: Issues, https://github.com/cervant-ai/hiws/issues
+Keywords: hiws,python,package
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# hiws
+
+A Python package for interacting with WhatsApp's Cloud API.
+
+## Installation
+
+```bash
+pip install hiws
+```
+
+## Usage
+
+```python
+from hiws import WhatsAppMessenger
+
+messenger = WhatsAppMessenger(access_token="YOUR_ACCESS_TOKEN", phone_number_id="YOUR_PHONE_NUMBER_ID")
+
+# Example usage
+message_id = await messenger.send_text("Hello, World!", recipient_id="RECIPIENT_ID")
+
+print(message_id)
+```
+
+## Development
+
+To install in development mode:
+
+```bash
+git clone https://github.com/cervant-ai/hiws.git
+cd hiws
+pip install -e .
+```
+
+To install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

hiws-0.1.0/README.md

@@ -0,0 +1,58 @@
+# hiws
+
+A Python package for interacting with WhatsApp's Cloud API.
+
+## Installation
+
+```bash
+pip install hiws
+```
+
+## Usage
+
+```python
+from hiws import WhatsAppMessenger
+
+messenger = WhatsAppMessenger(access_token="YOUR_ACCESS_TOKEN", phone_number_id="YOUR_PHONE_NUMBER_ID")
+
+# Example usage
+message_id = await messenger.send_text("Hello, World!", recipient_id="RECIPIENT_ID")
+
+print(message_id)
+```
+
+## Development
+
+To install in development mode:
+
+```bash
+git clone https://github.com/cervant-ai/hiws.git
+cd hiws
+pip install -e .
+```
+
+To install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

hiws-0.1.0/hiws/WhatsappMessenger.py

@@ -0,0 +1,436 @@
+import httpx
+from hiws.types.exceptions import WhatsappApiException
+from hiws.types import Contact
+from typing import Optional, Any, Dict
+
+
+BASE_URL = "https://graph.facebook.com/{API_VERSION}"
+MESSAGES_ENDPOINT = "/{phone_number_id}/messages"
+DEFAULT_TIMEOUT = 15.0
+
+
+class WhatsappMessenger:
+    """
+    A class to interact with the WhatsApp Cloud API.
+    
+    Attributes:
+        access_token (str): The access token for authentication.
+        phone_number_id (str): The phone number ID associated with the WhatsApp Business account.
+        api_version (str): The version of the WhatsApp API to use.
+        request_timeout (float): Timeout for HTTP requests in seconds. Default is 15.0 seconds.
+    """
+
+    access_token: str
+    phone_number_id: str
+    api_version: str
+    request_timeout: float = DEFAULT_TIMEOUT
+
+    def __init__(
+        self,
+        access_token: str,
+        phone_number_id: str,
+        api_version: str = "v23.0",
+        request_timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.access_token = access_token
+        self.phone_number_id = phone_number_id
+        self.api_version = api_version
+        self.base_url = BASE_URL.format(API_VERSION=self.api_version)
+        self.messages_endpoint = MESSAGES_ENDPOINT.format(phone_number_id=self.phone_number_id)
+        self.request_timeout = request_timeout
+
+    async def send_text(
+        self, 
+        recipient_phone_number: str, 
+        text: str, 
+        enable_link_preview: bool = True,
+        reply_to: Optional[str] = None
+    ) -> str:
+        """
+        Send a text message.
+        Args:
+            recipient_phone_number (str): The recipient's phone number in international format (without leading '+').
+            text (str): The text message to send.
+            enable_link_preview (bool): Whether to enable link preview. Default is True.
+            reply_to (Optional[str]): Message ID to reply to. Default is None.
+            
+        Returns:
+            str: The message ID of the sent message.
+            
+        Raises:
+            WhatsappApiException: If there is an error sending the message.
+            
+        ## Note
+            WhatsApp Cloud API has a limit of 4096 characters for text messages.
+            Messages longer than this will not be sent.
+            
+        ## Documentation
+            https://developers.facebook.com/docs/whatsapp/cloud-api/messages/text-messages
+        """
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": recipient_phone_number,
+            "type": "text",
+            "text": {"preview_url": enable_link_preview, "body": text},
+        }
+        
+        if reply_to:
+            payload["context"] = {"message_id": reply_to}
+
+        return await self._send_message_payload(payload)
+
+    async def send_image(
+        self,
+        recipient_phone_number: str,
+        image_link: Optional[str] = None,
+        media_id: Optional[str] = None,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None
+    ) -> str:
+        """
+        Send an image.
+        Args:
+            recipient_phone_number (str): The recipient's phone number in international format (without leading '+').
+            image_link (Optional[str]): The URL of the image to send. Default is None.
+            media_id (Optional[str]): The media ID of a previously uploaded image. Default is None.
+            caption (Optional[str]): Caption for the image. Default is None.
+            reply_to (Optional[str]): Message ID to reply to. Default is None.
+        Returns:
+            str: The message ID of the sent message.
+        Raises:
+            ValueError: If neither image_link nor media_id is provided.
+            WhatsappApiException: If there is an error sending the message.
+        ## Note
+            Supported formats: JPEG, PNG.
+            Max file size: 5 MB.
+        ## Documentation
+            https://developers.facebook.com/docs/whatsapp/cloud-api/messages/image-messages
+        """
+        return await self._send_media(
+            media_type="image",
+            media_link=image_link,
+            media_id=media_id,
+            caption=caption,
+            recipient_phone_number=recipient_phone_number,
+            reply_to=reply_to
+        )
+
+    async def send_document(
+        self,
+        recipient_phone_number: str,
+        document_link: Optional[str] = None,
+        media_id: Optional[str] = None,
+        caption: Optional[str] = None,
+        filename: Optional[str] = None,
+        reply_to: Optional[str] = None
+    ) -> str:
+        """
+        Send a document.
+        Args:
+            recipient_phone_number (str): The recipient's phone number in international format (without leading '+').
+            document_link (Optional[str]): The URL of the document to send. Default is None.
+            media_id (Optional[str]): The media ID of a previously uploaded document. Default is None.
+            caption (Optional[str]): Caption for the document. Default is None.
+            filename (Optional[str]): Filename for the document. Default is None.
+            reply_to (Optional[str]): Message ID to reply to. Default is None.
+        Returns:
+            str: The message ID of the sent message.
+        Raises:
+            ValueError: If neither document_link nor media_id is provided.
+            WhatsappApiException: If there is an error sending the message.
+        ## Note
+            Supported formats: PDF, XLS, XLSX, DOC, DOCX, PPT, PPTX, TXT.
+            Max file size: 100 MB.
+        ## Documentation
+            https://developers.facebook.com/docs/whatsapp/cloud-api/messages/document-messages
+        """
+        return await self._send_media(
+            media_type="document",
+            media_link=document_link,
+            media_id=media_id,
+            caption=caption,
+            filename=filename,
+            recipient_phone_number=recipient_phone_number,
+            reply_to=reply_to
+        )
+        
+    async def send_audio(
+        self,
+        recipient_phone_number: str,
+        audio_link: Optional[str] = None,
+        media_id: Optional[str] = None,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None
+    ) -> str:
+        """
+        Send an audio message.
+        Args:
+            recipient_phone_number (str): The recipient's phone number in international format (without leading '+').
+            audio_link (Optional[str]): The URL of the audio to send. Default is None.
+            media_id (Optional[str]): The media ID of a previously uploaded audio. Default is None.
+            caption (Optional[str]): Caption for the audio. Default is None.
+            reply_to (Optional[str]): Message ID to reply to. Default is None.
+        Returns:
+            str: The message ID of the sent message.
+        Raises:
+            ValueError: If neither audio_link nor media_id is provided.
+            WhatsappApiException: If there is an error sending the message.
+        ## Note
+            Supported formats: AAC, AMR, MP3, M4A, OGG (only OPUS codec).
+            Max file size: 16 MB.
+        """
+        return await self._send_media(
+            media_type="audio",
+            media_link=audio_link,
+            media_id=media_id,
+            caption=caption,
+            recipient_phone_number=recipient_phone_number,
+            reply_to=reply_to
+        )
+        
+    async def send_video(
+        self,
+        recipient_phone_number: str,
+        video_link: Optional[str] = None,
+        media_id: Optional[str] = None,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None
+    ) -> str:
+        """
+        Send a video message.
+        Args:
+            recipient_phone_number (str): The recipient's phone number in international format (without leading '+').
+            video_link (Optional[str]): The URL of the video to send. Default is None.
+            media_id (Optional[str]): The media ID of a previously uploaded video. Default is None.
+            caption (Optional[str]): Caption for the video. Default is None.
+            reply_to (Optional[str]): Message ID to reply to. Default is None.
+        Returns:
+            str: The message ID of the sent message.
+        Raises:
+            ValueError: If neither video_link nor media_id is provided.
+            WhatsappApiException: If there is an error sending the message.
+        ## Note
+            Supported formats: MP4, 3GPP.
+            Max file size: 16 MB.
+        ## Documentation
+            https://developers.facebook.com/docs/whatsapp/cloud-api/messages/video-messages
+        """
+        return await self._send_media(
+            media_type="video",
+            media_link=video_link,
+            media_id=media_id,
+            caption=caption,
+            recipient_phone_number=recipient_phone_number,
+            reply_to=reply_to
+        )
+        
+    async def send_contact(
+        self,
+        recipient_phone_number: str,
+        contact: Contact | Dict[str, Any],
+    ) -> str:
+        """
+        Send a contact message.
+        Args:
+            recipient_phone_number (str): The recipient's phone number in international format (without leading '+').
+            contact (Contact | Dict[str, Any]): The contact information to send.
+        Returns:
+            str: The message ID of the sent message.
+        Raises:
+            ValueError: If contact is invalid.
+            WhatsappApiException: If there is an error sending the message.
+        """
+        if isinstance(contact, Contact):
+            contact = contact.model_dump(mode="json", exclude_none=True)
+
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": recipient_phone_number,
+            "type": "contact",
+            "contact": contact,
+        }
+
+        return await self._send_message_payload(payload)
+
+    async def mark_as_read(
+        self,
+        message_id: str
+    ) -> None:
+        """
+        Mark a message as read.
+        Args:
+            message_id (str): The ID of the message to mark as read.
+        Returns:
+            str: The message ID of the read receipt.
+        Raises:
+            WhatsappApiException: If there is an error sending the read receipt.
+        ## Documentation
+            https://developers.facebook.com/docs/whatsapp/cloud-api/guides/mark-message-as-read
+        """
+        payload = {
+            "messaging_product": "whatsapp",
+            "status": "read",
+            "message_id": message_id
+        }
+
+        await self._send_mark_as_read_payload(payload)
+
+    async def send_typing_indicator(
+        self,
+        message_id: str
+    ) -> None:
+        """
+        Send a typing indicator.
+        Args:
+            message_id (str): The ID of the message to which the typing indicator relates. This message will be marked as read.
+        Returns:
+            str: The message ID of the typing indicator.
+        """
+        payload = {
+            "messaging_product": "whatsapp",
+            "status": "read",
+            "message_id": message_id,
+            "typing_indicator": {
+                "type": "text",
+            }
+        }
+        
+        await self._send_mark_as_read_payload(payload)
+        
+        
+    
+    
+
+    async def _send_media(
+        self,
+        recipient_phone_number: str,
+        media_type: str,
+        media_link: Optional[str] = None,
+        media_id: Optional[str] = None,
+        caption: Optional[str] = None,
+        filename: Optional[str] = None,
+        reply_to: Optional[str] = None
+    ) -> str:
+        if not media_link and not media_id:
+            raise ValueError("Either media_link or media_id must be provided.")
+
+        media_payload = {}
+        if media_link:
+            media_payload["link"] = media_link
+        if media_id:
+            media_payload["id"] = media_id
+        if caption:
+            media_payload["caption"] = caption
+        if filename and media_type == "document":
+            media_payload["filename"] = filename
+
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": recipient_phone_number,
+            "type": media_type,
+            media_type: media_payload,
+        }
+        
+        if reply_to:
+            payload["context"] = {"message_id": reply_to}
+
+        return await self._send_message_payload(payload)
+
+    async def _send_message_payload(self, payload: dict) -> str:
+        """
+        Send a custom payload to WhatsApp's API messages endpoint with robust error handling.
+
+        Args:
+            payload (dict): The payload to send.
+            timeout (Optional[float]): Request timeout in seconds. Defaults to DEFAULT_TIMEOUT.
+
+        Returns:
+            SendResponse: A mapping with at least the "message_id" and, when available, "recipient_id".
+
+        Raises:
+            WhatsappApiException: For network errors, non-2xx responses, or malformed responses.
+        """
+        url = f"{self.base_url}{self.messages_endpoint}"
+        response = await self._send_payload(self.messages_endpoint, payload)
+        
+        try:
+            data = response.json()
+        except ValueError as e:
+            raise WhatsappApiException(
+                message="Failed to parse JSON response",
+                endpoint=self.messages_endpoint,
+                method="POST",
+                payload=payload,
+                status_code=response.status_code,
+                details=str(e),
+            ) from e
+
+        message_id = data.get("message_id") or data.get("id")
+        if not message_id:
+            raise WhatsappApiException(
+                message="Missing message_id in successful response",
+                endpoint=url,
+                method="POST",
+                payload=payload,
+                status_code=response.status_code,
+                response_json=data,
+            )
+
+        return message_id
+
+    async def _send_mark_as_read_payload(self, payload: dict) -> None: 
+        response = await self._send_payload(self.messages_endpoint, payload)
+        try:
+            data = response.json()
+        except ValueError as e:
+            raise WhatsappApiException(
+                message="Failed to parse JSON response",
+                endpoint=self.messages_endpoint,
+                method="POST",
+                payload=payload,
+                status_code=response.status_code,
+                details=str(e),
+            ) from e
+        success = data.get("success")
+        if not success:
+            raise WhatsappApiException(
+                message="Failed to mark message as read",
+                endpoint=self.messages_endpoint,
+                method="POST",
+                payload=payload,
+                status_code=response.status_code,
+                response_json=data,
+            )
+
+    async def _send_payload(self, endpoint: str, payload: dict) -> httpx.Response:
+        url = f"{self.base_url}{endpoint}"
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.request_timeout) as client:
+                response = await client.post(url, json=payload, headers=headers)
+        except httpx.RequestError as e:
+            raise WhatsappApiException(
+                message="Network error while sending payload",
+                endpoint=url,
+                method="POST",
+                payload=payload,
+                details=str(e),
+            ) from e
+
+        # Non-2xx -> raise a structured exception with parsed error body when possible
+        if response.status_code < 200 or response.status_code >= 300:
+            raise WhatsappApiException.from_httpx_response(
+                response,
+                endpoint=url,
+                method="POST",
+                payload=payload,
+            )
+
+        return response

hiws-0.1.0/hiws/__init__.py

@@ -0,0 +1,4 @@
+from .types import Update
+from .WhatsappMessenger import WhatsappMessenger
+
+__all__ = ["Update", "WhatsappMessenger"]

hiws-0.1.0/hiws/types/__init__.py

@@ -0,0 +1,5 @@
+from .update import Update
+from .message import Message
+from .message.contact import Contact
+
+__all__ = ["Update", "Message", "Contact"]

hiws-0.1.0/hiws/types/exceptions/WhatsappApiException.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class WhatsappApiException(Exception):
+    """Exception raised for Instagram API errors.
+
+    Captures HTTP details, endpoint, method, payload, and parsed error body when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        endpoint: Optional[str] = None,
+        method: Optional[str] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        response_text: Optional[str] = None,
+        response_json: Optional[Dict[str, Any]] = None,
+        details: Optional[str] = None,
+        error_code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.endpoint = endpoint
+        self.method = method
+        self.payload = payload
+        self.response_text = response_text
+        self.response_json = response_json
+        self.details = details
+        self.error_code = error_code
+
+    def __str__(self) -> str:
+        base = self.message
+        parts = []
+        if self.status_code is not None:
+            parts.append(f"status={self.status_code}")
+        if self.endpoint:
+            parts.append(f"endpoint={self.endpoint}")
+        if self.method:
+            parts.append(f"method={self.method}")
+        if self.error_code:
+            parts.append(f"error_code={self.error_code}")
+        if self.details:
+            parts.append(f"details={self.details}")
+        if parts:
+            base += " (" + ", ".join(parts) + ")"
+        return base
+
+    @classmethod
+    def from_httpx_response(
+        cls,
+        response: Any,
+        *,
+        endpoint: Optional[str] = None,
+        method: Optional[str] = None,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> "WhatsappApiException":
+        """
+        Build an exception from an httpx.Response, attempting to parse JSON error details.
+        """
+        status = getattr(response, "status_code", None)
+        text = None
+        data: Optional[Dict[str, Any]] = None
+        code: Optional[str] = None
+        message: str = "Instagram API request failed"
+
+        try:
+            data = response.json()
+            # Graph API errors are often under { "error": { "message": "...", "code": 190, ... } }
+            err = data.get("error") if isinstance(data, dict) else None
+            if isinstance(err, dict):
+                message = err.get("message") or message
+                code_value = err.get("code")
+                code = str(code_value) if code_value is not None else None
+        except Exception:
+            text = getattr(response, "text", None)
+
+        return cls(
+            message=message,
+            status_code=status,
+            endpoint=endpoint,
+            method=method,
+            payload=payload,
+            response_text=text,
+            response_json=data,
+            error_code=code,
+        )

hiws-0.1.0/hiws/types/exceptions/__init__.py

@@ -0,0 +1,3 @@
+from .WhatsappApiException import WhatsappApiException
+
+__all__ = ["WhatsappApiException"]

hiws-0.1.0/hiws/types/message/__init__.py

@@ -0,0 +1,81 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from hiws.types.message.contact import Contact
+
+
+class BaseMessage(BaseModel):
+    from_phone_number: str = Field(alias="from")
+    id: str
+    timestamp: str
+
+class Text(BaseModel):
+    body: str
+
+class TextMessage(BaseMessage):
+    text: Text
+    type: str = "text"
+    
+class Reaction(BaseModel):
+    message_id: str
+    emoji: str
+    
+class ReactionMessage(BaseMessage):
+    reaction: Reaction
+    type: str = "reaction"
+    
+class Media(BaseModel):
+    id: str
+    mime_type: str
+    caption: str
+    sha256: str
+    
+class ImageMessage(BaseMessage):
+    image: Media
+    type: str = "image"
+    
+class StickerMessage(BaseMessage):
+    sticker: Media
+    type: str = "sticker"
+    
+class MessageError(BaseModel):
+    code: int
+    details: str
+    title: str
+
+class UnknownMessage(BaseModel):
+    errors: List[MessageError]
+    type: str = "unknown"
+    
+class Location(BaseModel):
+    latitude: float
+    longitude: float
+    name: Optional[str]
+    address: Optional[str]
+    
+class LocationMessage(BaseMessage):
+    location: Location
+    type: str = "location"
+    
+class ContactMessage(BaseMessage):
+    contacts: List[Contact]
+    type: str = "contacts"
+    
+class Button(BaseModel):
+    text: str
+    payload: Optional[str]
+    
+class QuickReplyButtonMessage(BaseMessage):
+    button: Button
+    type: str = "button"
+    
+class SystemUpdate(BaseModel):
+    body: str
+    type: str = "system"
+    new_wa_id: Optional[str]
+    
+class SystemMessage(BaseMessage):
+    system: SystemUpdate
+    type: str = "system"
+    
+
+type Message = TextMessage | ReactionMessage | ImageMessage | StickerMessage | LocationMessage | QuickReplyButtonMessage | SystemMessage | UnknownMessage

hiws-0.1.0/hiws/types/message/contact.py

@@ -0,0 +1,53 @@
+from pydantic import BaseModel, Field
+from typing import List, Literal, Optional
+
+
+class Address(BaseModel):
+    city: Optional[str]
+    country: Optional[str]
+    country_code: Optional[str]
+    state: Optional[str]
+    street: Optional[str]
+    type: Literal["HOME", "WORK"] = "HOME"
+    zip: Optional[str]
+
+
+class Email(BaseModel):
+    email: str
+    type: Literal["HOME", "WORK"] = "HOME"
+
+
+class Name(BaseModel):
+    formatted_name: Optional[str]
+    first_name: Optional[str]
+    last_name: Optional[str]
+    middle_name: Optional[str]
+    prefix: Optional[str]
+    suffix: Optional[str]
+
+
+class Org(BaseModel):
+    company: Optional[str]
+    department: Optional[str]
+    title: Optional[str]
+
+
+class Phone(BaseModel):
+    phone: str
+    wa_id: Optional[str]
+    type: Literal["HOME", "WORK", "MOBILE"] = "HOME"
+
+
+class Url(BaseModel):
+    url: str
+    type: Literal["HOME", "WORK"] = "HOME"
+
+
+class Contact(BaseModel):
+    addresses: Optional[List[Address]]
+    birthday: Optional[str]
+    emails: Optional[List[Email]]
+    name: Optional[Name]
+    org: Optional[Org]
+    phones: List[Phone]
+    urls: Optional[List[Url]]

hiws-0.1.0/hiws/types/status/__init__.py

@@ -0,0 +1,54 @@
+from pydantic import BaseModel
+from typing import List, Literal, Optional
+
+class StatusPricing(BaseModel):
+    pricing_model: str
+    billable: bool
+    category: Optional[str]
+
+class StatusConversationOrigin(BaseModel):
+    type: str
+    
+class StatusConversation(BaseModel):
+    id: str
+    expiration_timestamp: Optional[str]
+    origin: Optional[StatusConversationOrigin]
+    
+class StatusErrorData(BaseModel):
+    details: str
+    
+class StatusError(BaseModel):
+    code: int
+    title: str
+    message: Optional[str]
+    error_data: Optional[StatusErrorData]
+    href: Optional[str]
+    
+
+class BaseStatus(BaseModel):
+    id: str
+    status: Literal["delivered", "read", "failed", "sent"]
+    timestamp: str
+    recipient_id: str
+    
+class SentStatus(BaseStatus):
+    status: Literal["sent"]
+    conversation: StatusConversation
+    pricing: StatusPricing
+    
+class DeliveredStatus(BaseStatus):
+    status: Literal["delivered"]
+    conversation: StatusConversation
+    pricing: StatusPricing
+    
+class ReadStatus(BaseStatus):
+    status: Literal["read"]
+    
+class FailedStatus(BaseStatus):
+    status: Literal["failed"]
+    errors: List[StatusError]
+    
+type Status = SentStatus | DeliveredStatus | ReadStatus | FailedStatus
+    
+
+    

hiws-0.1.0/hiws/types/update.py

@@ -0,0 +1,41 @@
+from typing import List, Optional
+from pydantic import BaseModel
+from hiws.types.message import Message
+from hiws.types.status import Status
+
+
+class Profile(BaseModel):
+    name: str
+
+
+class RequestContact(BaseModel):
+    profile: Profile
+    wa_id: str
+
+
+class Metadata(BaseModel):
+    display_phone_number: str
+    phone_number_id: str
+
+
+class Value(BaseModel):
+    messaging_product: str
+    metadata: Metadata
+    contacts: List[RequestContact]
+    messages: Optional[List[Message]] = None
+    statuses: Optional[List[Status]] = None
+
+
+class Change(BaseModel):
+    value: Value
+    field: str
+
+
+class Entry(BaseModel):
+    id: str
+    changes: List[Change]
+
+
+class Update(BaseModel):
+    object: str
+    entry: List[Entry]

hiws-0.1.0/hiws.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hiws
+Version: 0.1.0
+Summary: A wrapper for WhatsApp's Cloud API
+Home-page: https://github.com/cervant-ai/hiws
+Author: Tomas Santana
+Author-email: Tomas Santana <tomas@cervant.chat>
+License: MIT
+Project-URL: Homepage, https://github.com/cervant-ai/hiws
+Project-URL: Repository, https://github.com/cervant-ai/hiws.git
+Project-URL: Issues, https://github.com/cervant-ai/hiws/issues
+Keywords: hiws,python,package
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# hiws
+
+A Python package for interacting with WhatsApp's Cloud API.
+
+## Installation
+
+```bash
+pip install hiws
+```
+
+## Usage
+
+```python
+from hiws import WhatsAppMessenger
+
+messenger = WhatsAppMessenger(access_token="YOUR_ACCESS_TOKEN", phone_number_id="YOUR_PHONE_NUMBER_ID")
+
+# Example usage
+message_id = await messenger.send_text("Hello, World!", recipient_id="RECIPIENT_ID")
+
+print(message_id)
+```
+
+## Development
+
+To install in development mode:
+
+```bash
+git clone https://github.com/cervant-ai/hiws.git
+cd hiws
+pip install -e .
+```
+
+To install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

hiws-0.1.0/hiws.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+hiws/WhatsappMessenger.py
+hiws/__init__.py
+hiws.egg-info/PKG-INFO
+hiws.egg-info/SOURCES.txt
+hiws.egg-info/dependency_links.txt
+hiws.egg-info/requires.txt
+hiws.egg-info/top_level.txt
+hiws/types/__init__.py
+hiws/types/update.py
+hiws/types/exceptions/WhatsappApiException.py
+hiws/types/exceptions/__init__.py
+hiws/types/message/__init__.py
+hiws/types/message/contact.py
+hiws/types/status/__init__.py

hiws-0.1.0/hiws.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hiws-0.1.0/hiws.egg-info/requires.txt

@@ -0,0 +1,9 @@
+pydantic>=2.11.7
+httpx>=0.28.1
+
+[dev]
+pytest>=6.0
+pytest-asyncio>=0.23
+black>=21.0
+flake8>=3.8.0
+mypy>=0.800

hiws-0.1.0/hiws.egg-info/top_level.txt

@@ -0,0 +1 @@
+hiws

hiws-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hiws"
+version = "0.1.0"
+description = "A wrapper for WhatsApp's Cloud API"
+readme = "README.md"
+requires-python = ">=3.7"
+license = {text = "MIT"}
+authors = [
+    {name = "Tomas Santana", email = "tomas@cervant.chat"},
+]
+keywords = ["hiws", "python", "package"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "pydantic>=2.11.7",
+    "httpx>=0.28.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0",
+    "pytest-asyncio>=0.23",
+    "black>=21.0",
+    "flake8>=3.8.0",
+    "mypy>=0.800",
+]
+
+[project.urls]
+Homepage = "https://github.com/cervant-ai/hiws"
+Repository = "https://github.com/cervant-ai/hiws.git"
+Issues = "https://github.com/cervant-ai/hiws/issues"
+
+[tool.black]
+line-length = 88
+target-version = ['py37']
+
+[tool.mypy]
+python_version = "3.7"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

hiws-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hiws-0.1.0/setup.py

@@ -0,0 +1,41 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="hiws",
+    version="0.1.0",
+    author="Tomas Santana",
+    author_email="tomas@cervant.chat",
+    description="A simple Python wrapper for WhatsApp's Cloud API",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/cervant-ai/hiws",
+    packages=find_packages(),
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.7",
+    install_requires=[
+        "pydantic>=2.11.7",
+        "httpx>=0.28.1",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=6.0",
+            "pytest-asyncio>=0.23",
+            "black>=21.0",
+            "flake8>=3.8.0",
+            "mypy>=0.800",
+        ],
+    },
+)