ccai-python 1.0.0__tar.gz

ccai_python-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ccai-python
+Version: 1.0.0
+Summary: Python client for CloudContactAI API
+Author: CloudContactAI LLC
+License: MIT
+Project-URL: Homepage, https://github.com/cloudcontactai/ccai-python
+Project-URL: Bug Tracker, https://github.com/cloudcontactai/ccai-python/issues
+Keywords: sms,api,client,cloud,contact,ai,cloudcontactai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pydantic>=2.5.0
+
+# CCAI Python Client
+
+A Python client for interacting with the CloudContactAI API.
+
+## Installation
+
+```bash
+pip install ccai-python
+```
+
+## Usage
+
+```python
+from ccai_python import CCAI
+
+# Initialize the client
+ccai = CCAI(
+    client_id="YOUR-CLIENT-ID",
+    api_key="YOUR-API-KEY"
+)
+
+# Send a single SMS
+response = ccai.sms.send_single(
+    first_name="John",
+    last_name="Doe",
+    phone="+15551234567",
+    message="Hello ${first_name}, this is a test message!",
+    title="Test Campaign"
+)
+
+print(f"Message sent with ID: {response.id}")
+
+# Send to multiple recipients
+accounts = [
+    {"first_name": "John", "last_name": "Doe", "phone": "+15551234567"},
+    {"first_name": "Jane", "last_name": "Smith", "phone": "+15559876543"}
+]
+
+campaign_response = ccai.sms.send(
+    accounts=accounts,
+    message="Hello ${first_name} ${last_name}, this is a test message!",
+    title="Bulk Test Campaign"
+)
+
+print(f"Campaign sent with ID: {campaign_response.campaign_id}")
+```
+
+## Features
+
+- Send SMS messages to single or multiple recipients
+- Variable substitution in messages
+- Async support
+- Type hints for better IDE integration
+- Comprehensive error handling
+
+## Requirements
+
+- Python 3.10 or higher
+- `requests` library
+
+## License
+
+MIT

ccai_python-1.0.0/README.md

@@ -0,0 +1,63 @@
+# CCAI Python Client
+
+A Python client for interacting with the CloudContactAI API.
+
+## Installation
+
+```bash
+pip install ccai-python
+```
+
+## Usage
+
+```python
+from ccai_python import CCAI
+
+# Initialize the client
+ccai = CCAI(
+    client_id="YOUR-CLIENT-ID",
+    api_key="YOUR-API-KEY"
+)
+
+# Send a single SMS
+response = ccai.sms.send_single(
+    first_name="John",
+    last_name="Doe",
+    phone="+15551234567",
+    message="Hello ${first_name}, this is a test message!",
+    title="Test Campaign"
+)
+
+print(f"Message sent with ID: {response.id}")
+
+# Send to multiple recipients
+accounts = [
+    {"first_name": "John", "last_name": "Doe", "phone": "+15551234567"},
+    {"first_name": "Jane", "last_name": "Smith", "phone": "+15559876543"}
+]
+
+campaign_response = ccai.sms.send(
+    accounts=accounts,
+    message="Hello ${first_name} ${last_name}, this is a test message!",
+    title="Bulk Test Campaign"
+)
+
+print(f"Campaign sent with ID: {campaign_response.campaign_id}")
+```
+
+## Features
+
+- Send SMS messages to single or multiple recipients
+- Variable substitution in messages
+- Async support
+- Type hints for better IDE integration
+- Comprehensive error handling
+
+## Requirements
+
+- Python 3.10 or higher
+- `requests` library
+
+## License
+
+MIT

ccai_python-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ccai-python"
+version = "1.0.0"
+description = "Python client for CloudContactAI API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "CloudContactAI LLC"}
+]
+keywords = ["sms", "api", "client", "cloud", "contact", "ai", "cloudcontactai"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "pydantic>=2.5.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/cloudcontactai/ccai-python"
+"Bug Tracker" = "https://github.com/cloudcontactai/ccai-python/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.pytest]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 88

ccai_python-1.0.0/setup.cfg

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

ccai_python-1.0.0/src/ccai_python/__init__.py

@@ -0,0 +1,21 @@
+"""
+Main export file for the CCAI Python module
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+from .ccai import CCAI, Account, CCAIConfig
+from .sms.sms import SMS, SMSCampaign, SMSResponse, SMSOptions
+
+__all__ = [
+    'CCAI',
+    'SMS',
+    'Account',
+    'CCAIConfig',
+    'SMSCampaign',
+    'SMSResponse',
+    'SMSOptions'
+]
+
+__version__ = '1.0.0'

ccai_python-1.0.0/src/ccai_python/ccai.py

@@ -0,0 +1,149 @@
+"""
+ccai.py - A Python module for interacting with the Cloud Contact AI API
+This module provides functionality to send SMS messages through the CCAI platform.
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+from typing import Any, Dict, Optional, TypedDict, cast
+import requests
+from pydantic import BaseModel, Field
+
+from .sms.sms import SMS
+
+
+class Account(BaseModel):
+    """Account model representing a recipient"""
+    first_name: str = Field(..., description="Recipient's first name")
+    last_name: str = Field(..., description="Recipient's last name")
+    phone: str = Field(..., description="Recipient's phone number in E.164 format")
+
+
+class CCAIConfig(BaseModel):
+    """Configuration for the CCAI client"""
+    client_id: str = Field(..., description="Client ID for authentication")
+    api_key: str = Field(..., description="API key for authentication")
+    base_url: str = Field(
+        default="https://core.cloudcontactai.com/api",
+        description="Base URL for the API"
+    )
+
+
+class APIError(Exception):
+    """Exception raised for API errors"""
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"API Error: {status_code} - {message}")
+
+
+class CCAI:
+    """
+    Main client for interacting with the CloudContactAI API
+    """
+    
+    def __init__(
+        self, 
+        client_id: str, 
+        api_key: str, 
+        base_url: Optional[str] = None
+    ) -> None:
+        """
+        Create a new CCAI client instance
+        
+        Args:
+            client_id: Client ID for authentication
+            api_key: API key for authentication
+            base_url: Optional base URL for the API
+        
+        Raises:
+            ValueError: If client_id or api_key is not provided
+        """
+        if not client_id:
+            raise ValueError("Client ID is required")
+        if not api_key:
+            raise ValueError("API Key is required")
+        
+        self._config = CCAIConfig(
+            client_id=client_id,
+            api_key=api_key,
+            base_url=base_url or "https://core.cloudcontactai.com/api"
+        )
+        
+        # Initialize the SMS service
+        self.sms = SMS(self)
+    
+    @property
+    def client_id(self) -> str:
+        """Get the client ID"""
+        return self._config.client_id
+    
+    @property
+    def api_key(self) -> str:
+        """Get the API key"""
+        return self._config.api_key
+    
+    @property
+    def base_url(self) -> str:
+        """Get the base URL"""
+        return self._config.base_url
+    
+    def request(
+        self, 
+        method: str, 
+        endpoint: str, 
+        data: Optional[Dict[str, Any]] = None,
+        timeout: int = 30
+    ) -> Dict[str, Any]:
+        """
+        Make an authenticated API request to the CCAI API
+        
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint
+            data: Request data
+            timeout: Request timeout in seconds
+            
+        Returns:
+            API response as a dictionary
+            
+        Raises:
+            APIError: If the API returns an error
+            requests.RequestException: For network-related errors
+        """
+        url = f"{self.base_url}{endpoint}"
+        
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "*/*"
+        }
+        
+        try:
+            response = requests.request(
+                method=method.upper(),
+                url=url,
+                headers=headers,
+                json=data,
+                timeout=timeout
+            )
+            
+            # Raise an exception for HTTP errors
+            response.raise_for_status()
+            
+            return cast(Dict[str, Any], response.json())
+        except requests.HTTPError as e:
+            # Handle API errors with response
+            if e.response is not None:
+                try:
+                    error_data = e.response.json()
+                    error_message = str(error_data)
+                except (ValueError, TypeError):
+                    error_message = e.response.text or str(e)
+                
+                raise APIError(e.response.status_code, error_message)
+            raise
+        except requests.RequestException as e:
+            # Handle network errors
+            raise APIError(0, f"Network error: {str(e)}")

ccai_python-1.0.0/src/ccai_python/examples/async_example.py

@@ -0,0 +1,248 @@
+"""
+Async example using the CCAI Python client with asyncio
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+import asyncio
+from typing import Dict, Any, List
+
+import aiohttp
+from pydantic import BaseModel, Field
+
+# Import the synchronous client for type definitions
+from ccai_python import Account, SMSResponse, SMSOptions
+
+
+class AsyncCCAI:
+    """
+    Async version of the CCAI client for CloudContactAI API
+    """
+    
+    def __init__(
+        self, 
+        client_id: str, 
+        api_key: str, 
+        base_url: str = "https://core.cloudcontactai.com/api"
+    ) -> None:
+        """
+        Create a new async CCAI client instance
+        
+        Args:
+            client_id: Client ID for authentication
+            api_key: API key for authentication
+            base_url: Base URL for the API
+        """
+        if not client_id:
+            raise ValueError("Client ID is required")
+        if not api_key:
+            raise ValueError("API Key is required")
+        
+        self._client_id = client_id
+        self._api_key = api_key
+        self._base_url = base_url
+        self.sms = AsyncSMS(self)
+    
+    @property
+    def client_id(self) -> str:
+        """Get the client ID"""
+        return self._client_id
+    
+    async def request(
+        self, 
+        method: str, 
+        endpoint: str, 
+        data: Dict[str, Any] = None,
+        timeout: int = 30
+    ) -> Dict[str, Any]:
+        """
+        Make an authenticated API request to the CCAI API
+        
+        Args:
+            method: HTTP method
+            endpoint: API endpoint
+            data: Request data
+            timeout: Request timeout in seconds
+            
+        Returns:
+            API response as a dictionary
+        """
+        url = f"{self._base_url}{endpoint}"
+        
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "*/*"
+        }
+        
+        async with aiohttp.ClientSession() as session:
+            async with session.request(
+                method=method.upper(),
+                url=url,
+                headers=headers,
+                json=data,
+                timeout=aiohttp.ClientTimeout(total=timeout)
+            ) as response:
+                # Raise an exception for HTTP errors
+                response.raise_for_status()
+                
+                # Parse the response as JSON
+                return await response.json()
+
+
+class AsyncSMS:
+    """
+    Async SMS service for sending messages through the CCAI API
+    """
+    
+    def __init__(self, ccai: AsyncCCAI) -> None:
+        """
+        Create a new async SMS service instance
+        
+        Args:
+            ccai: The parent AsyncCCAI instance
+        """
+        self._ccai = ccai
+    
+    async def send(
+        self,
+        accounts: List[Account],
+        message: str,
+        title: str,
+        options: SMSOptions = None
+    ) -> SMSResponse:
+        """
+        Send an SMS message to one or more recipients asynchronously
+        
+        Args:
+            accounts: List of recipient accounts
+            message: Message content
+            title: Campaign title
+            options: Optional settings for the SMS send operation
+            
+        Returns:
+            API response
+        """
+        # Validate inputs
+        if not accounts:
+            raise ValueError("At least one account is required")
+        if not message:
+            raise ValueError("Message is required")
+        if not title:
+            raise ValueError("Campaign title is required")
+        
+        # Prepare the endpoint and data
+        endpoint = f"/clients/{self._ccai.client_id}/campaigns/direct"
+        
+        # Convert Account objects to dictionaries with camelCase keys for API compatibility
+        accounts_data = [
+            {
+                "firstName": account.first_name,
+                "lastName": account.last_name,
+                "phone": account.phone
+            }
+            for account in accounts
+        ]
+        
+        campaign_data = {
+            "accounts": accounts_data,
+            "message": message,
+            "title": title
+        }
+        
+        # Make the API request
+        timeout = options.timeout if options else 30
+        response_data = await self._ccai.request(
+            method="post", 
+            endpoint=endpoint, 
+            data=campaign_data,
+            timeout=timeout
+        )
+        
+        # Convert response to SMSResponse object
+        return SMSResponse(**response_data)
+    
+    async def send_single(
+        self,
+        first_name: str,
+        last_name: str,
+        phone: str,
+        message: str,
+        title: str,
+        options: SMSOptions = None
+    ) -> SMSResponse:
+        """
+        Send a single SMS message to one recipient asynchronously
+        
+        Args:
+            first_name: Recipient's first name
+            last_name: Recipient's last name
+            phone: Recipient's phone number (E.164 format)
+            message: Message content
+            title: Campaign title
+            options: Optional settings for the SMS send operation
+            
+        Returns:
+            API response
+        """
+        account = Account(
+            first_name=first_name,
+            last_name=last_name,
+            phone=phone
+        )
+        
+        return await self.send([account], message, title, options)
+
+
+async def main() -> None:
+    """Example of using the async CCAI client"""
+    # Create a new async CCAI client
+    ccai = AsyncCCAI(
+        client_id="YOUR-CLIENT-ID",
+        api_key="API-KEY-TOKEN"
+    )
+    
+    # Example recipients
+    accounts = [
+        Account(
+            first_name="John",
+            last_name="Doe",
+            phone="+15551234567"  # Use E.164 format
+        )
+    ]
+    
+    # Message with variable placeholders
+    message = "Hello ${first_name} ${last_name}, this is a test message!"
+    title = "Async Test Campaign"
+    
+    try:
+        # Send SMS to multiple recipients
+        print('Sending campaign to multiple recipients asynchronously...')
+        campaign_response = await ccai.sms.send(
+            accounts=accounts,
+            message=message,
+            title=title
+        )
+        print('SMS campaign sent successfully!')
+        print(campaign_response.model_dump())
+        
+        # Send SMS to a single recipient
+        print('\nSending message to a single recipient asynchronously...')
+        single_response = await ccai.sms.send_single(
+            first_name="Jane",
+            last_name="Smith",
+            phone="+15559876543",
+            message="Hi ${first_name}, thanks for your interest!",
+            title="Single Async Message Test"
+        )
+        print('Single SMS sent successfully!')
+        print(single_response.model_dump())
+        
+        print('\nAll messages sent successfully!')
+    except Exception as error:
+        print(f'Error sending SMS: {str(error)}')
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

ccai_python-1.0.0/src/ccai_python/examples/basic_example.py

@@ -0,0 +1,79 @@
+"""
+Basic example using the CCAI Python client
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+from ccai_python import CCAI, Account, SMSResponse
+
+# Create a new CCAI client
+ccai = CCAI(
+    client_id="YOUR-CLIENT-ID",
+    api_key="API-KEY-TOKEN"
+)
+
+# Example recipients
+accounts = [
+    Account(
+        first_name="John",
+        last_name="Doe",
+        phone="+15551234567"  # Use E.164 format
+    )
+]
+
+# Alternative dictionary format
+dict_accounts = [
+    {
+        "first_name": "John",
+        "last_name": "Doe",
+        "phone": "+15551234567"  # Use E.164 format
+    }
+]
+
+# Message with variable placeholders
+message = "Hello ${first_name} ${last_name}, this is a test message!"
+title = "Test Campaign"
+
+
+def send_messages() -> dict:
+    """Example of sending SMS messages"""
+    try:
+        # Method 1: Send SMS to multiple recipients
+        print('Sending campaign to multiple recipients...')
+        campaign_response: SMSResponse = ccai.sms.send(
+            accounts=accounts,
+            message=message,
+            title=title
+        )
+        print('SMS campaign sent successfully!')
+        print(campaign_response.model_dump())
+
+        # Method 2: Send SMS to a single recipient
+        print('\nSending message to a single recipient...')
+        single_response: SMSResponse = ccai.sms.send_single(
+            first_name="Jane",
+            last_name="Smith",
+            phone="+15559876543",
+            message="Hi ${first_name}, thanks for your interest!",
+            title="Single Message Test"
+        )
+        print('Single SMS sent successfully!')
+        print(single_response.model_dump())
+
+        return {
+            "campaign_response": campaign_response.model_dump(),
+            "single_response": single_response.model_dump()
+        }
+    except Exception as error:
+        print(f'Error sending SMS: {str(error)}')
+        raise
+
+
+if __name__ == "__main__":
+    try:
+        results = send_messages()
+        print('\nAll messages sent successfully!')
+        print(f'\nResults: {results}')
+    except Exception:
+        print('\nFailed to send one or more messages.')

ccai_python-1.0.0/src/ccai_python/sms/__init__.py

@@ -0,0 +1,10 @@
+"""
+SMS package for the CCAI Python client
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+from .sms import SMS, Account, SMSCampaign, SMSResponse, SMSOptions
+
+__all__ = ['SMS', 'Account', 'SMSCampaign', 'SMSResponse', 'SMSOptions']

ccai_python-1.0.0/src/ccai_python/sms/sms.py

@@ -0,0 +1,215 @@
+"""
+sms.py - SMS service for the CCAI API
+Handles sending SMS messages through the Cloud Contact AI platform.
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+from typing import Any, Callable, Dict, List, Optional, Protocol, TypedDict, Union, cast
+from pydantic import BaseModel, Field
+
+
+class Account(BaseModel):
+    """Account model representing a recipient"""
+    first_name: str = Field(..., description="Recipient's first name")
+    last_name: str = Field(..., description="Recipient's last name")
+    phone: str = Field(..., description="Recipient's phone number in E.164 format")
+
+
+class SMSCampaign(BaseModel):
+    """SMS campaign data model"""
+    accounts: List[Account] = Field(..., description="List of recipient accounts")
+    message: str = Field(..., description="Message content with optional variables")
+    title: str = Field(..., description="Campaign title")
+
+
+class SMSResponse(BaseModel):
+    """Response from the SMS API"""
+    id: Optional[str] = Field(None, description="Message ID")
+    status: Optional[str] = Field(None, description="Message status")
+    campaign_id: Optional[str] = Field(None, description="Campaign ID")
+    messages_sent: Optional[int] = Field(None, description="Number of messages sent")
+    timestamp: Optional[str] = Field(None, description="Timestamp of the operation")
+    
+    # Allow additional fields
+    model_config = {
+        "extra": "allow",
+    }
+
+
+class SMSOptions(BaseModel):
+    """Options for SMS operations"""
+    timeout: Optional[int] = Field(None, description="Request timeout in seconds")
+    retries: Optional[int] = Field(None, description="Number of retry attempts")
+    on_progress: Optional[Callable[[str], None]] = Field(
+        None, 
+        description="Callback for tracking progress"
+    )
+
+
+class CCAIProtocol(Protocol):
+    """Protocol defining the required methods for the CCAI client"""
+    @property
+    def client_id(self) -> str:
+        ...
+    
+    def request(
+        self, 
+        method: str, 
+        endpoint: str, 
+        data: Optional[Dict[str, Any]] = None,
+        timeout: Optional[int] = None
+    ) -> Dict[str, Any]:
+        ...
+
+
+class SMS:
+    """
+    SMS service for sending messages through the CCAI API
+    """
+    
+    def __init__(self, ccai: CCAIProtocol) -> None:
+        """
+        Create a new SMS service instance
+        
+        Args:
+            ccai: The parent CCAI instance
+        """
+        self._ccai = ccai
+    
+    def send(
+        self,
+        accounts: List[Union[Account, Dict[str, str]]],
+        message: str,
+        title: str,
+        options: Optional[SMSOptions] = None
+    ) -> SMSResponse:
+        """
+        Send an SMS message to one or more recipients
+        
+        Args:
+            accounts: List of recipient accounts
+            message: Message content (can include ${first_name} and ${last_name} variables)
+            title: Campaign title
+            options: Optional settings for the SMS send operation
+            
+        Returns:
+            API response
+            
+        Raises:
+            ValueError: If required parameters are missing or invalid
+        """
+        # Validate inputs
+        if not accounts:
+            raise ValueError("At least one account is required")
+        if not message:
+            raise ValueError("Message is required")
+        if not title:
+            raise ValueError("Campaign title is required")
+        
+        # Convert dict accounts to Account objects if needed
+        normalized_accounts: List[Account] = []
+        for idx, account in enumerate(accounts):
+            if isinstance(account, dict):
+                try:
+                    # Convert dictionary keys from snake_case to camelCase if needed
+                    account_data = {}
+                    for key, value in account.items():
+                        if key == "first_name":
+                            account_data["first_name"] = value
+                        elif key == "lastName":
+                            account_data["last_name"] = value
+                        elif key == "firstName":
+                            account_data["first_name"] = value
+                        elif key == "last_name":
+                            account_data["last_name"] = value
+                        else:
+                            account_data[key] = value
+                    
+                    normalized_accounts.append(Account(**account_data))
+                except Exception as e:
+                    raise ValueError(f"Invalid account at index {idx}: {str(e)}")
+            else:
+                normalized_accounts.append(account)
+        
+        # Notify progress if callback provided
+        if options and options.on_progress:
+            options.on_progress("Preparing to send SMS")
+        
+        # Prepare the endpoint and data
+        endpoint = f"/clients/{self._ccai.client_id}/campaigns/direct"
+        
+        # Convert Account objects to dictionaries with camelCase keys for API compatibility
+        accounts_data = [
+            {
+                "firstName": account.first_name,
+                "lastName": account.last_name,
+                "phone": account.phone
+            }
+            for account in normalized_accounts
+        ]
+        
+        campaign_data = {
+            "accounts": accounts_data,
+            "message": message,
+            "title": title
+        }
+        
+        try:
+            # Notify progress if callback provided
+            if options and options.on_progress:
+                options.on_progress("Sending SMS")
+            
+            # Make the API request
+            timeout = options.timeout if options else None
+            response_data = self._ccai.request(
+                method="post", 
+                endpoint=endpoint, 
+                data=campaign_data,
+                timeout=timeout
+            )
+            
+            # Notify progress if callback provided
+            if options and options.on_progress:
+                options.on_progress("SMS sent successfully")
+            
+            # Convert response to SMSResponse object
+            return SMSResponse(**response_data)
+        except Exception as e:
+            # Notify progress if callback provided
+            if options and options.on_progress:
+                options.on_progress("SMS sending failed")
+            
+            raise e
+    
+    def send_single(
+        self,
+        first_name: str,
+        last_name: str,
+        phone: str,
+        message: str,
+        title: str,
+        options: Optional[SMSOptions] = None
+    ) -> SMSResponse:
+        """
+        Send a single SMS message to one recipient
+        
+        Args:
+            first_name: Recipient's first name
+            last_name: Recipient's last name
+            phone: Recipient's phone number (E.164 format)
+            message: Message content (can include ${first_name} and ${last_name} variables)
+            title: Campaign title
+            options: Optional settings for the SMS send operation
+            
+        Returns:
+            API response
+        """
+        account = Account(
+            first_name=first_name,
+            last_name=last_name,
+            phone=phone
+        )
+        
+        return self.send([account], message, title, options)

ccai_python-1.0.0/src/ccai_python.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ccai-python
+Version: 1.0.0
+Summary: Python client for CloudContactAI API
+Author: CloudContactAI LLC
+License: MIT
+Project-URL: Homepage, https://github.com/cloudcontactai/ccai-python
+Project-URL: Bug Tracker, https://github.com/cloudcontactai/ccai-python/issues
+Keywords: sms,api,client,cloud,contact,ai,cloudcontactai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pydantic>=2.5.0
+
+# CCAI Python Client
+
+A Python client for interacting with the CloudContactAI API.
+
+## Installation
+
+```bash
+pip install ccai-python
+```
+
+## Usage
+
+```python
+from ccai_python import CCAI
+
+# Initialize the client
+ccai = CCAI(
+    client_id="YOUR-CLIENT-ID",
+    api_key="YOUR-API-KEY"
+)
+
+# Send a single SMS
+response = ccai.sms.send_single(
+    first_name="John",
+    last_name="Doe",
+    phone="+15551234567",
+    message="Hello ${first_name}, this is a test message!",
+    title="Test Campaign"
+)
+
+print(f"Message sent with ID: {response.id}")
+
+# Send to multiple recipients
+accounts = [
+    {"first_name": "John", "last_name": "Doe", "phone": "+15551234567"},
+    {"first_name": "Jane", "last_name": "Smith", "phone": "+15559876543"}
+]
+
+campaign_response = ccai.sms.send(
+    accounts=accounts,
+    message="Hello ${first_name} ${last_name}, this is a test message!",
+    title="Bulk Test Campaign"
+)
+
+print(f"Campaign sent with ID: {campaign_response.campaign_id}")
+```
+
+## Features
+
+- Send SMS messages to single or multiple recipients
+- Variable substitution in messages
+- Async support
+- Type hints for better IDE integration
+- Comprehensive error handling
+
+## Requirements
+
+- Python 3.10 or higher
+- `requests` library
+
+## License
+
+MIT

ccai_python-1.0.0/src/ccai_python.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/ccai_python/__init__.py
+src/ccai_python/ccai.py
+src/ccai_python.egg-info/PKG-INFO
+src/ccai_python.egg-info/SOURCES.txt
+src/ccai_python.egg-info/dependency_links.txt
+src/ccai_python.egg-info/requires.txt
+src/ccai_python.egg-info/top_level.txt
+src/ccai_python/examples/async_example.py
+src/ccai_python/examples/basic_example.py
+src/ccai_python/sms/__init__.py
+src/ccai_python/sms/sms.py
+tests/test_ccai.py
+tests/test_sms.py

ccai_python-1.0.0/src/ccai_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ccai_python-1.0.0/src/ccai_python.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+pydantic>=2.5.0

ccai_python-1.0.0/src/ccai_python.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+ccai_python
+examples
+sms

ccai_python-1.0.0/tests/test_ccai.py

@@ -0,0 +1,88 @@
+"""
+Tests for the CCAI client
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+import unittest
+from unittest.mock import patch, MagicMock
+
+from ccai_python import CCAI, Account
+
+
+class TestCCAI(unittest.TestCase):
+    """Test cases for the CCAI client"""
+    
+    def setUp(self):
+        """Set up test fixtures"""
+        self.client_id = "test-client-id"
+        self.api_key = "test-api-key"
+        self.ccai = CCAI(client_id=self.client_id, api_key=self.api_key)
+    
+    def test_initialization(self):
+        """Test client initialization"""
+        self.assertEqual(self.ccai.client_id, self.client_id)
+        self.assertEqual(self.ccai.api_key, self.api_key)
+        self.assertEqual(self.ccai.base_url, "https://core.cloudcontactai.com/api")
+        
+        # Test custom base URL
+        custom_url = "https://custom.api.example.com"
+        ccai = CCAI(client_id=self.client_id, api_key=self.api_key, base_url=custom_url)
+        self.assertEqual(ccai.base_url, custom_url)
+    
+    def test_initialization_validation(self):
+        """Test validation during initialization"""
+        with self.assertRaises(ValueError):
+            CCAI(client_id="", api_key=self.api_key)
+        
+        with self.assertRaises(ValueError):
+            CCAI(client_id=self.client_id, api_key="")
+    
+    @patch('requests.request')
+    def test_request(self, mock_request):
+        """Test the request method"""
+        # Mock response
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"status": "success"}
+        mock_response.raise_for_status.return_value = None
+        mock_request.return_value = mock_response
+        
+        # Test GET request
+        result = self.ccai.request("get", "/test-endpoint")
+        self.assertEqual(result, {"status": "success"})
+        
+        # Verify request was made correctly
+        mock_request.assert_called_with(
+            method="GET",
+            url="https://core.cloudcontactai.com/api/test-endpoint",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "*/*"
+            },
+            json=None,
+            timeout=30
+        )
+        
+        # Test POST request with data
+        data = {"key": "value"}
+        result = self.ccai.request("post", "/test-endpoint", data=data)
+        self.assertEqual(result, {"status": "success"})
+        
+        # Verify request was made correctly
+        mock_request.assert_called_with(
+            method="POST",
+            url="https://core.cloudcontactai.com/api/test-endpoint",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "*/*"
+            },
+            json=data,
+            timeout=30
+        )
+
+
+if __name__ == '__main__':
+    unittest.main()

ccai_python-1.0.0/tests/test_sms.py

@@ -0,0 +1,237 @@
+"""
+Tests for the SMS service
+
+:license: MIT
+:copyright: 2025 CloudContactAI LLC
+"""
+
+import unittest
+from unittest.mock import patch, MagicMock
+
+from ccai_python import CCAI, Account, SMSOptions
+
+
+class TestSMS(unittest.TestCase):
+    """Test cases for the SMS service"""
+    
+    def setUp(self):
+        """Set up test fixtures"""
+        self.client_id = "test-client-id"
+        self.api_key = "test-api-key"
+        self.ccai = CCAI(client_id=self.client_id, api_key=self.api_key)
+        
+        # Sample account
+        self.account = Account(
+            first_name="John",
+            last_name="Doe",
+            phone="+15551234567"
+        )
+        
+        # Sample message and title
+        self.message = "Hello ${first_name}, this is a test message!"
+        self.title = "Test Campaign"
+    
+    @patch.object(CCAI, 'request')
+    def test_send(self, mock_request):
+        """Test sending SMS to multiple recipients"""
+        # Mock response
+        mock_request.return_value = {
+            "id": "msg-123",
+            "status": "sent",
+            "campaign_id": "camp-456",
+            "messages_sent": 1,
+            "timestamp": "2025-06-06T12:00:00Z"
+        }
+        
+        # Send SMS
+        response = self.ccai.sms.send(
+            accounts=[self.account],
+            message=self.message,
+            title=self.title
+        )
+        
+        # Verify response
+        self.assertEqual(response.id, "msg-123")
+        self.assertEqual(response.status, "sent")
+        self.assertEqual(response.campaign_id, "camp-456")
+        self.assertEqual(response.messages_sent, 1)
+        self.assertEqual(response.timestamp, "2025-06-06T12:00:00Z")
+        
+        # Verify request was made correctly
+        mock_request.assert_called_with(
+            method="post",
+            endpoint=f"/clients/{self.client_id}/campaigns/direct",
+            data={
+                "accounts": [
+                    {
+                        "firstName": "John",
+                        "lastName": "Doe",
+                        "phone": "+15551234567"
+                    }
+                ],
+                "message": self.message,
+                "title": self.title
+            },
+            timeout=None
+        )
+    
+    @patch.object(CCAI, 'request')
+    def test_send_with_dict_accounts(self, mock_request):
+        """Test sending SMS with dictionary accounts"""
+        # Mock response
+        mock_request.return_value = {"id": "msg-123", "status": "sent"}
+        
+        # Send SMS with dictionary accounts
+        response = self.ccai.sms.send(
+            accounts=[{
+                "first_name": "John",
+                "last_name": "Doe",
+                "phone": "+15551234567"
+            }],
+            message=self.message,
+            title=self.title
+        )
+        
+        # Verify response
+        self.assertEqual(response.id, "msg-123")
+        self.assertEqual(response.status, "sent")
+        
+        # Verify request was made correctly
+        mock_request.assert_called_with(
+            method="post",
+            endpoint=f"/clients/{self.client_id}/campaigns/direct",
+            data={
+                "accounts": [
+                    {
+                        "firstName": "John",
+                        "lastName": "Doe",
+                        "phone": "+15551234567"
+                    }
+                ],
+                "message": self.message,
+                "title": self.title
+            },
+            timeout=None
+        )
+    
+    @patch.object(CCAI, 'request')
+    def test_send_single(self, mock_request):
+        """Test sending SMS to a single recipient"""
+        # Mock response
+        mock_request.return_value = {"id": "msg-123", "status": "sent"}
+        
+        # Send SMS to a single recipient
+        response = self.ccai.sms.send_single(
+            first_name="Jane",
+            last_name="Smith",
+            phone="+15559876543",
+            message="Hi ${first_name}, thanks for your interest!",
+            title="Single Message Test"
+        )
+        
+        # Verify response
+        self.assertEqual(response.id, "msg-123")
+        self.assertEqual(response.status, "sent")
+        
+        # Verify request was made correctly
+        mock_request.assert_called_with(
+            method="post",
+            endpoint=f"/clients/{self.client_id}/campaigns/direct",
+            data={
+                "accounts": [
+                    {
+                        "firstName": "Jane",
+                        "lastName": "Smith",
+                        "phone": "+15559876543"
+                    }
+                ],
+                "message": "Hi ${first_name}, thanks for your interest!",
+                "title": "Single Message Test"
+            },
+            timeout=None
+        )
+    
+    @patch.object(CCAI, 'request')
+    def test_send_with_options(self, mock_request):
+        """Test sending SMS with options"""
+        # Mock response
+        mock_request.return_value = {"id": "msg-123", "status": "sent"}
+        
+        # Create progress tracking callback
+        progress_updates = []
+        def track_progress(status: str):
+            progress_updates.append(status)
+        
+        # Create options
+        options = SMSOptions(
+            timeout=60,
+            retries=3,
+            on_progress=track_progress
+        )
+        
+        # Send SMS with options
+        response = self.ccai.sms.send(
+            accounts=[self.account],
+            message=self.message,
+            title=self.title,
+            options=options
+        )
+        
+        # Verify response
+        self.assertEqual(response.id, "msg-123")
+        self.assertEqual(response.status, "sent")
+        
+        # Verify progress updates
+        self.assertEqual(progress_updates, [
+            "Preparing to send SMS",
+            "Sending SMS",
+            "SMS sent successfully"
+        ])
+        
+        # Verify request was made correctly
+        mock_request.assert_called_with(
+            method="post",
+            endpoint=f"/clients/{self.client_id}/campaigns/direct",
+            data={
+                "accounts": [
+                    {
+                        "firstName": "John",
+                        "lastName": "Doe",
+                        "phone": "+15551234567"
+                    }
+                ],
+                "message": self.message,
+                "title": self.title
+            },
+            timeout=60
+        )
+    
+    def test_validation(self):
+        """Test input validation"""
+        # Test empty accounts
+        with self.assertRaises(ValueError):
+            self.ccai.sms.send(
+                accounts=[],
+                message=self.message,
+                title=self.title
+            )
+        
+        # Test empty message
+        with self.assertRaises(ValueError):
+            self.ccai.sms.send(
+                accounts=[self.account],
+                message="",
+                title=self.title
+            )
+        
+        # Test empty title
+        with self.assertRaises(ValueError):
+            self.ccai.sms.send(
+                accounts=[self.account],
+                message=self.message,
+                title=""
+            )
+
+
+if __name__ == '__main__':
+    unittest.main()