waclient 0.1.3__tar.gz

waclient-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Surenthar S
+
+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.

waclient-0.1.3/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: waclient
+Version: 0.1.3
+Summary: Simplified Python SDK for WhatsApp Business Cloud API
+Author-email: Surenthar <surentharsenthilkumar2003@gmail.com>
+License-Expression: MIT
+Project-URL: Bug Reports, https://github.com/Start-up-Kraft/waclient/issues
+Project-URL: Source, https://github.com/Start-up-Kraft/waclient
+Project-URL: Documentation, https://github.com/Start-up-Kraft/waclient#readme
+Keywords: whatsapp,business,api,cloud,meta,facebook,messaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Communications :: Chat
+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
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.9; extra == "dev"
+Dynamic: license-file
+
+# WhatsApp Biz
+
+**Simplified Python SDK for WhatsApp Business Cloud API**
+
+[![PyPI version](https://badge.fury.io/py/waclient.svg)](https://badge.fury.io/py/waclient)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Versions](https://img.shields.io/pypi/pyversions/waclient.svg)](https://pypi.org/project/waclient/)
+
+`waclient` is a clean, easy-to-use Python wrapper for the WhatsApp Business Cloud API. It handles authentication, message composition (text, media, interactive), and media management, allowing you to build WhatsApp bots and integrations quickly.
+
+## Features
+
+- **Easy Authentication**: Simple client initialization.
+- **Rich Messaging**: Send Text, Image, Video, Audio, Document, Sticker, Location, and Contact messages.
+- **Interactive Elements**: Support for Reply Buttons and List Messages.
+- **Templates**: Full support for WhatsApp Template Messages.
+- **Media Handling**: Upload and retrieve media easily.
+
+## Installation
+
+```bash
+pip install waclient
+```
+
+## Quick Start
+
+```python
+from waclient import WhatsAppClient
+
+client = WhatsAppClient(
+    phone_number_id="YOUR_PHONE_ID",
+    access_token="YOUR_ACCESS_TOKEN"
+)
+
+client.messages.send_text(to="15551234567", body="Hello form WhatsApp Biz!")
+```
+
+## Documentation
+
+- **[User Manual](USER_MANUAL.md)**: Detailed verification of all features, code examples, and configuration.
+- **[Developer Guide](DEVELOPER_GUIDE.md)**: Setup for contributors, running tests, and project structure.
+
+## Examples
+
+Check the `examples/` directory for ready-to-run scripts:
+- `examples/verify_features.py`: comprehensive tour of features.
+- `examples/verify_delivery.py`: delivery status verification.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Author
+
+**Surenthar**  
+Email: surentharsenthilkumar2003@gmail.com

waclient-0.1.3/README.md

@@ -0,0 +1,56 @@
+# WhatsApp Biz
+
+**Simplified Python SDK for WhatsApp Business Cloud API**
+
+[![PyPI version](https://badge.fury.io/py/waclient.svg)](https://badge.fury.io/py/waclient)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Versions](https://img.shields.io/pypi/pyversions/waclient.svg)](https://pypi.org/project/waclient/)
+
+`waclient` is a clean, easy-to-use Python wrapper for the WhatsApp Business Cloud API. It handles authentication, message composition (text, media, interactive), and media management, allowing you to build WhatsApp bots and integrations quickly.
+
+## Features
+
+- **Easy Authentication**: Simple client initialization.
+- **Rich Messaging**: Send Text, Image, Video, Audio, Document, Sticker, Location, and Contact messages.
+- **Interactive Elements**: Support for Reply Buttons and List Messages.
+- **Templates**: Full support for WhatsApp Template Messages.
+- **Media Handling**: Upload and retrieve media easily.
+
+## Installation
+
+```bash
+pip install waclient
+```
+
+## Quick Start
+
+```python
+from waclient import WhatsAppClient
+
+client = WhatsAppClient(
+    phone_number_id="YOUR_PHONE_ID",
+    access_token="YOUR_ACCESS_TOKEN"
+)
+
+client.messages.send_text(to="15551234567", body="Hello form WhatsApp Biz!")
+```
+
+## Documentation
+
+- **[User Manual](USER_MANUAL.md)**: Detailed verification of all features, code examples, and configuration.
+- **[Developer Guide](DEVELOPER_GUIDE.md)**: Setup for contributors, running tests, and project structure.
+
+## Examples
+
+Check the `examples/` directory for ready-to-run scripts:
+- `examples/verify_features.py`: comprehensive tour of features.
+- `examples/verify_delivery.py`: delivery status verification.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Author
+
+**Surenthar**  
+Email: surentharsenthilkumar2003@gmail.com

waclient-0.1.3/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "waclient"
+version = "0.1.3"
+description = "Simplified Python SDK for WhatsApp Business Cloud API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+  {name = "Surenthar", email = "surentharsenthilkumar2003@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Communications :: Chat",
+    "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",
+    "Programming Language :: Python :: 3.12",
+]
+keywords = ["whatsapp", "business", "api", "cloud", "meta", "facebook", "messaging"]
+dependencies = [
+    "requests>=2.25.0",
+]
+
+[project.urls]
+"Bug Reports" = "https://github.com/Start-up-Kraft/waclient/issues"
+"Source" = "https://github.com/Start-up-Kraft/waclient"
+"Documentation" = "https://github.com/Start-up-Kraft/waclient#readme"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "black>=21.0",
+    "flake8>=3.9",
+]
+
+[tool.setuptools]
+packages = ["waclient"]

waclient-0.1.3/setup.cfg

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

waclient-0.1.3/tests/test_basic.py

@@ -0,0 +1,143 @@
+"""
+Basic tests for whatsapp-biz package
+"""
+
+
+def test_import():
+    """Test if package imports correctly"""
+    try:
+        from waclient import WhatsAppClient
+
+        print("[PASS] Import successful!")
+        return True
+    except ImportError as e:
+        print(f"[FAIL] Import failed: {e}")
+        return False
+
+
+def test_client_creation():
+    """Test if client can be instantiated"""
+    try:
+        from waclient import WhatsAppClient
+
+        client = WhatsAppClient(
+            phone_number_id="461166093735990",
+            access_token="EAAfLlnmBVq4BO75McWDhNHgL1DW9LKmdOCmLmlQbtjZBdEZCt65ub7z35gBW9gFiRjJpZC3LZA9cSTZC5Uw9lpxz3xGSyDai1FoKZAdqtRZA2huRNHrv3ymxfUljrQZAZCMs7zGEf7vzJLktSoLsZA83BHZBt9H3M06sl5ETgz4YZC7ToCBZASwnwAUC8gxGndieOSv5Y16oxhqTWPStgseH6",
+        )
+
+        print("[PASS] Client created successfully!")
+        print(f"   Phone ID: {client.phone_number_id}")
+        print(f"   Base URL: {client.base_url}")
+        return True
+    except Exception as e:
+        print(f"[FAIL] Client creation failed: {e}")
+        return False
+
+
+def test_message_builder():
+    """Test message builders"""
+    try:
+        from waclient.messages import MessageBuilder
+
+        builder = MessageBuilder()
+
+        # Test text message
+        msg = builder.text_message("919342585854", "Hello!")
+        assert msg["type"] == "text"
+        assert msg["text"]["body"] == "Hello!"
+
+        print("[PASS] Message builder works!")
+        return True
+    except Exception as e:
+        print(f"[FAIL] Message builder failed: {e}")
+        return False
+
+
+def test_template_builder():
+    """Test template builders"""
+    try:
+        from waclient.templates import TemplateBuilder
+
+        component = TemplateBuilder.body_parameters("value1", "value2")
+        assert component["type"] == "body"
+        assert len(component["parameters"]) == 2
+
+        print("[PASS] Template builder works!")
+        return True
+    except Exception as e:
+        print(f"[FAIL] Template builder failed: {e}")
+        return False
+
+
+def test_utils():
+    """Test utility functions"""
+    try:
+        from waclient.utils import format_phone_number, validate_phone_number
+
+        # Test phone formatting
+        phone = format_phone_number("9342585854")
+        assert phone == "919342585854"
+
+        # Test validation
+        assert validate_phone_number("919342585854") == True
+
+        print("[PASS] Utils work!")
+        return True
+    except Exception as e:
+        print(f"[FAIL] Utils failed: {e}")
+        return False
+
+
+def test_exceptions():
+    """Test custom exceptions"""
+    try:
+        from waclient.exceptions import (
+            WhatsAppError,
+            AuthenticationError,
+            MessageError,
+            MediaError,
+        )
+
+        # Test exception creation
+        error = WhatsAppError("Test error")
+        assert str(error) == "Test error"
+
+        print("[PASS] Exceptions work!")
+        return True
+    except Exception as e:
+        print(f"[FAIL] Exceptions test failed: {e}")
+        return False
+
+
+if __name__ == "__main__":
+    print("=" * 50)
+    print("[TEST] Testing whatsapp-biz Package")
+    print("=" * 50)
+
+    tests = [
+        test_import,
+        test_client_creation,
+        test_message_builder,
+        test_template_builder,
+        test_utils,
+        test_exceptions,
+    ]
+
+    passed = 0
+    failed = 0
+
+    for test in tests:
+        print(f"\n[RUN] Running: {test.__name__}")
+        try:
+            if test():
+                passed += 1
+            else:
+                failed += 1
+        except Exception as e:
+            print(f"[FAIL] Test crashed: {e}")
+            failed += 1
+
+    print("\n" + "=" * 50)
+    print(f"[PASS] Passed: {passed}")
+    print(f"[FAIL] Failed: {failed}")
+    print("=" * 50)

waclient-0.1.3/waclient/__init__.py

@@ -0,0 +1,22 @@
+"""WhatsApp Business Cloud API - Simplified Python SDK"""
+
+__version__ = "0.1.0"
+__author__ = "Your Name"
+
+from .client import WhatsAppClient
+from .exceptions import (
+    WhatsAppError,
+    AuthenticationError,
+    MessageError,
+    MediaError,
+    WebhookError
+)
+
+__all__ = [
+    "WhatsAppClient",
+    "WhatsAppError",
+    "AuthenticationError",
+    "MessageError",
+    "MediaError",
+    "WebhookError"
+]

waclient-0.1.3/waclient/client.py

@@ -0,0 +1,283 @@
+"""
+File: waclient/client.py
+Main WhatsApp Business Cloud API Client
+"""
+
+import requests
+import json
+from typing import Optional, Dict, List, Any
+from .exceptions import WhatsAppError, AuthenticationError, MessageError
+from .messages import MessageBuilder
+from .media import MediaHandler
+
+
+class WhatsAppClient:
+    """
+    WhatsApp Business Cloud API Client
+    
+    Example:
+        client = WhatsAppClient(
+            phone_number_id="461166093735990",
+            access_token="EAAfLlnmBVq4BO75McWDhNHgL1DW9LKmdOCmLmlQbtjZBdEZCt65ub7z35gBW9gFiRjJpZC3LZA9cSTZC5Uw9lpxz3xGSyDai1FoKZAdqtRZA2huRNHrv3ymxfUljrQZAZCMs7zGEf7vzJLktSoLsZA83BHZBt9H3M06sl5ETgz4YZC7ToCBZASwnwAUC8gxGndieOSv5Y16oxhqTWPStgseH6"
+        )
+        client.send_text("919342585854", "Hello!")
+    """
+    
+    BASE_URL = "https://graph.facebook.com/v21.0"
+    
+    def __init__(
+        self,
+        phone_number_id: str,
+        access_token: str,
+        api_version: str = "v21.0"
+    ):
+        """
+        Initialize WhatsApp Client
+        
+        Args:
+            phone_number_id: Your WhatsApp Business phone number ID
+            access_token: Your WhatsApp Business API access token
+            api_version: API version (default: v21.0)
+        """
+        self.phone_number_id = phone_number_id
+        self.access_token = access_token
+        self.api_version = api_version
+        self.base_url = f"https://graph.facebook.com/{api_version}"
+        self.headers = {
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json"
+        }
+        self.message_builder = MessageBuilder()
+        self.media_handler = MediaHandler(self)
+        
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Dict] = None,
+        params: Optional[Dict] = None
+    ) -> Dict:
+        """Make HTTP request to WhatsApp API"""
+        url = f"{self.base_url}/{self.phone_number_id}/{endpoint}"
+        
+        try:
+            response = requests.request(
+                method=method,
+                url=url,
+                headers=self.headers,
+                json=data,
+                params=params,
+                timeout=30
+            )
+            
+            response_data = response.json()
+            
+            if response.status_code >= 400:
+                error_msg = response_data.get("error", {}).get("message", "Unknown error")
+                error_code = response_data.get("error", {}).get("code", 0)
+                
+                if response.status_code == 401:
+                    raise AuthenticationError(f"Authentication failed: {error_msg}")
+                else:
+                    raise MessageError(f"API Error ({error_code}): {error_msg}")
+            
+            return response_data
+            
+        except requests.exceptions.RequestException as e:
+            raise WhatsAppError(f"Request failed: {str(e)}")
+    
+    def send_text(
+        self,
+        to: str,
+        message: str,
+        preview_url: bool = False
+    ) -> Dict:
+        """
+        Send a text message
+        
+        Args:
+            to: Recipient phone number (with country code, no + sign)
+            message: Text message to send
+            preview_url: Enable URL preview
+            
+        Returns:
+            API response with message ID
+            
+        Example:
+            response = client.send_text("919342585854", "Hello World!")
+        """
+        payload = self.message_builder.text_message(to, message, preview_url)
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_template(
+        self,
+        to: str,
+        template_name: str,
+        language: str = "en",
+        components: Optional[List[Dict]] = None,
+        **kwargs
+    ) -> Dict:
+        """
+        Send a template message
+        
+        Args:
+            to: Recipient phone number
+            template_name: Approved template name
+            language: Template language code (default: en)
+            components: Template components (parameters, buttons, etc.)
+            **kwargs: Additional template parameters
+            
+        Returns:
+            API response with message ID
+            
+        Example:
+            client.send_template(
+                to="919342585854",
+                template_name="order_confirmation",
+                language="en",
+                components=[{
+                    "type": "body",
+                    "parameters": [
+                        {"type": "text", "text": "Order123"},
+                        {"type": "text", "text": "₹499"}
+                    ]
+                }]
+            )
+        """
+        payload = self.message_builder.template_message(
+            to, template_name, language, components
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_image(
+        self,
+        to: str,
+        image_url: Optional[str] = None,
+        image_id: Optional[str] = None,
+        caption: Optional[str] = None
+    ) -> Dict:
+        """
+        Send an image message
+        
+        Args:
+            to: Recipient phone number
+            image_url: Public URL of the image (or use image_id)
+            image_id: Media ID from uploaded image
+            caption: Optional image caption
+            
+        Returns:
+            API response with message ID
+        """
+        payload = self.message_builder.media_message(
+            to, "image", image_url, image_id, caption
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_document(
+        self,
+        to: str,
+        document_url: Optional[str] = None,
+        document_id: Optional[str] = None,
+        caption: Optional[str] = None,
+        filename: Optional[str] = None
+    ) -> Dict:
+        """Send a document (PDF, DOC, etc.)"""
+        payload = self.message_builder.media_message(
+            to, "document", document_url, document_id, caption, filename
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_video(
+        self,
+        to: str,
+        video_url: Optional[str] = None,
+        video_id: Optional[str] = None,
+        caption: Optional[str] = None
+    ) -> Dict:
+        """Send a video message"""
+        payload = self.message_builder.media_message(
+            to, "video", video_url, video_id, caption
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_audio(
+        self,
+        to: str,
+        audio_url: Optional[str] = None,
+        audio_id: Optional[str] = None
+    ) -> Dict:
+        """Send an audio message"""
+        payload = self.message_builder.media_message(
+            to, "audio", audio_url, audio_id
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_location(
+        self,
+        to: str,
+        latitude: float,
+        longitude: float,
+        name: Optional[str] = None,
+        address: Optional[str] = None
+    ) -> Dict:
+        """Send a location message"""
+        payload = self.message_builder.location_message(
+            to, latitude, longitude, name, address
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_contacts(
+        self,
+        to: str,
+        contacts: List[Dict]
+    ) -> Dict:
+        """Send contact card(s)"""
+        payload = self.message_builder.contacts_message(to, contacts)
+        return self._make_request("POST", "messages", data=payload)
+    
+    def send_interactive(
+        self,
+        to: str,
+        interactive_type: str,
+        body_text: str,
+        **kwargs
+    ) -> Dict:
+        """
+        Send interactive message (buttons, lists)
+        
+        Args:
+            to: Recipient phone number
+            interactive_type: 'button' or 'list'
+            body_text: Message body text
+            **kwargs: Additional parameters (buttons, sections, etc.)
+        """
+        payload = self.message_builder.interactive_message(
+            to, interactive_type, body_text, **kwargs
+        )
+        return self._make_request("POST", "messages", data=payload)
+    
+    def mark_as_read(self, message_id: str) -> Dict:
+        """Mark a message as read"""
+        payload = {
+            "messaging_product": "whatsapp",
+            "status": "read",
+            "message_id": message_id
+        }
+        return self._make_request("POST", "messages", data=payload)
+    
+    def upload_media(self, file_path: str, mime_type: str) -> str:
+        """
+        Upload media file and get media ID
+        
+        Args:
+            file_path: Path to the media file
+            mime_type: MIME type (e.g., 'image/jpeg', 'application/pdf')
+            
+        Returns:
+            Media ID to use in send methods
+        """
+        return self.media_handler.upload(file_path, mime_type)
+    
+    def get_media_url(self, media_id: str) -> str:
+        """Get download URL for a media ID"""
+        return self.media_handler.get_url(media_id)