Merge pull request #12 from Devotel/feat/mkdocs-documentation

feat: Add MkDocs documentation with GitHub Pages deployment

Author: parman-devotel

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: |
+          mkdocs build --clean --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -2,6 +2,7 @@
 
 [![PyPI version](https://badge.fury.io/py/devo-global-comms-python.svg)](https://badge.fury.io/py/devo-global-comms-python)
 [![Python Support](https://img.shields.io/pypi/pyversions/devo-global-comms-python.svg)](https://pypi.org/project/devo-global-comms-python/)
+[![Documentation](https://img.shields.io/badge/docs-github%20pages-blue)](https://devotel.github.io/devo-global-comms-python/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A Python SDK for the Devo Global Communications API, supporting SMS, Email, WhatsApp, RCS, and Contact management.
@@ -14,7 +15,6 @@ A Python SDK for the Devo Global Communications API, supporting SMS, Email, What
 - **Sync-first design**: Simple, blocking API calls
 - **Type safety**: Full Pydantic model support with type hints
 - **Minimal dependencies**: Only requires `requests` and `pydantic`
-- **Resource-based pattern**: Familiar API design
 - **Python 3.8+ support**: Compatible with modern Python versions
 
 ## Installation
@@ -32,26 +32,28 @@ from devo_global_comms_python import DevoClient
 client = DevoClient(api_key="your-api-key")
 
 # Send an SMS
-sms = client.sms.send(
-    to="+1234567890",
-    body="Hello, World!"
+sms_response = client.sms.send_sms(
+    recipient="+1234567890",
+    message="Hello, World!",
+    sender="+1987654321"
 )
-print(f"SMS sent with SID: {sms.sid}")
+print(f"SMS sent with ID: {sms_response.id}")
 
 # Send an email
-email = client.email.send(
-    to="recipient@example.com",
+email_response = client.email.send_email(
+    recipient="recipient@example.com",
     subject="Hello from Devo!",
-    body="This is a test email from the Devo SDK."
+    content="This is a test email from the Devo SDK.",
+    sender_email="sender@example.com"
 )
-print(f"Email sent with ID: {email.id}")
+print(f"Email sent with ID: {email_response.id}")
 
 # Send a WhatsApp message
-whatsapp = client.whatsapp.send_text(
-    to="+1234567890",
-    text="Hello via WhatsApp!"
+whatsapp_response = client.whatsapp.send_text_message(
+    recipient="+1234567890",
+    message="Hello via WhatsApp!"
 )
-print(f"WhatsApp message sent with ID: {whatsapp.id}")
+print(f"WhatsApp message sent with ID: {whatsapp_response.id}")
 ```
 
 ## Authentication
@@ -64,214 +66,15 @@ from devo_global_comms_python import DevoClient
 client = DevoClient(api_key="your-api-key")
 ```
 
-## Usage Examples
-
-### SMS Messages
-
-```python
-# Send a simple SMS
-message = client.sms.send(
-    to="+1234567890",
-    body="Your verification code is: 123456"
-)
-
-# Send SMS with custom sender and callback
-message = client.sms.send(
-    to="+1234567890",
-    body="Hello from Devo!",
-    from_="+1987654321",
-    callback_url="https://your-app.com/webhook",
-    metadata={"campaign": "welcome_series"}
-)
-
-# Get message details
-message = client.sms.get("message_sid")
-print(f"Status: {message.status}")
-
-# List recent messages
-messages = client.sms.list(
-    date_sent_after="2024-01-01",
-    status="delivered",
-    limit=10
-)
-```
-
-### Email Messages
-
-```python
-# Send a simple email
-email = client.email.send(
-    to="user@example.com",
-    subject="Welcome to Devo!",
-    body="Thank you for signing up for our service."
-)
-
-# Send HTML email with CC and attachments
-email = client.email.send(
-    to="user@example.com",
-    subject="Monthly Newsletter",
-    body="Check out our latest updates!",
-    html_body="<h1>Monthly Newsletter</h1><p>Check out our latest updates!</p>",
-    cc=["manager@example.com"],
-    reply_to="noreply@example.com",
-    attachments=[
-        {
-            "filename": "newsletter.pdf",
-            "content": "base64-encoded-content",
-            "content_type": "application/pdf"
-        }
-    ]
-)
-
-# List emails by recipient
-emails = client.email.list(
-    to="user@example.com",
-    limit=20
-)
-```
-
-### WhatsApp Messages
-
-```python
-# Send a text message
-message = client.whatsapp.send_text(
-    to="+1234567890",
-    text="Hello from WhatsApp!"
-)
-
-# Send a template message
-message = client.whatsapp.send_template(
-    to="+1234567890",
-    template_name="welcome_message",
-    language="en",
-    parameters=["John", "Devo Platform"]
-)
-
-# Get message status
-message = client.whatsapp.get("message_id")
-print(f"Status: {message.status}")
-```
-
-### RCS Messages
-
-```python
-# Send a text message
-message = client.rcs.send_text(
-    to="+1234567890",
-    text="Hello from RCS!"
-)
-
-# Send a rich card
-message = client.rcs.send_rich_card(
-    to="+1234567890",
-    title="Special Offer",
-    description="Get 50% off your next purchase!",
-    media_url="https://example.com/image.jpg",
-    actions=[
-        {
-            "type": "url",
-            "text": "Shop Now",
-            "url": "https://example.com/shop"
-        }
-    ]
-)
-```
-
-### Contact Management
-
-```python
-# Create a contact
-contact = client.contacts.create(
-    phone_number="+1234567890",
-    email="user@example.com",
-    first_name="John",
-    last_name="Doe",
-    company="Acme Corp",
-    metadata={"source": "website_signup"}
-)
-
-# Update a contact
-updated_contact = client.contacts.update(
-    contact_id=contact.id,
-    company="New Company Inc.",
-    metadata={"updated": "2024-01-15"}
-)
-
-# Get contact details
-contact = client.contacts.get("contact_id")
-
-# List contacts
-contacts = client.contacts.list(
-    company="Acme Corp",
-    limit=50
-)
-
-# Delete a contact
-success = client.contacts.delete("contact_id")
-```
-
-### Unified Message Management
-
-```python
-# Get any message by ID
-message = client.messages.get("message_id")
-print(f"Channel: {message.channel}, Status: {message.status}")
-
-# List messages across all channels
-messages = client.messages.list(
-    channel="sms",  # Filter by channel
-    status="delivered",
-    date_sent_after="2024-01-01",
-    limit=100
-)
-
-# Get detailed delivery status
-delivery_status = client.messages.get_delivery_status("message_id")
-
-# Resend a failed message
-resent_message = client.messages.resend("failed_message_id")
-```
-
-## Error Handling
-
-The SDK provides specific exception types for different error scenarios:
-
-```python
-from devo_global_comms_python import (
-    DevoException,
-    DevoAPIException,
-    DevoAuthenticationException,
-    DevoValidationException,
-    DevoRateLimitException,
-    DevoTimeoutException,
-)
-
-try:
-    message = client.sms.send(
-        to="invalid-number",
-        body="Test message"
-    )
-except DevoValidationException as e:
-    print(f"Validation error: {e}")
-except DevoAuthenticationException as e:
-    print(f"Authentication failed: {e}")
-except DevoRateLimitException as e:
-    print(f"Rate limit exceeded. Retry after: {e.retry_after}")
-except DevoAPIException as e:
-    print(f"API error [{e.status_code}]: {e}")
-except DevoException as e:
-    print(f"General error: {e}")
-```
-
 ## Configuration
 
 ### Client Configuration
 
 ```python
 client = DevoClient(
     api_key="your-api-key",
-    timeout=30.0,
-    max_retries=3,
+    base_url="https://api.devo.com",  # Optional: custom base URL
+    timeout=30.0,  # Optional: request timeout
 )
 ```
 
@@ -294,36 +97,21 @@ client = DevoClient(
 
 ## Models
 
-All API responses are returned as Pydantic models with full type support:
+All API responses are returned as Pydantic models with full type support. The SDK includes models for:
+
+- **SMS**: `SMSQuickSendResponse`, `SenderInfo`, `AvailableNumber`
+- **Email**: `EmailSendResponse`, `EmailTemplateResponse`
+- **WhatsApp**: `WhatsAppTextResponse`, `WhatsAppMediaResponse`
+- **RCS**: `RCSMessage`, `RcsSendMessageSerializer`
+- **Contacts**: `ContactSerializer`, `CreateContactDto`, `UpdateContactDto`
+- **Contact Groups**: `ContactsGroup`, `CreateContactsGroupDto`
 
+Example usage:
 ```python
-# SMS Message model
-class SMSMessage(BaseModel):
-    sid: str
-    to: str
-    from_: Optional[str]
-    body: str
-    status: str
-    date_created: Optional[datetime]
-    # ... other fields
-
-# Email Message model
-class EmailMessage(BaseModel):
-    id: str
-    to: str
-    subject: str
-    body: str
-    status: str
-    # ... other fields
-
-# Contact model
-class Contact(BaseModel):
-    id: str
-    phone_number: Optional[str]
-    email: Optional[str]
-    first_name: Optional[str]
-    last_name: Optional[str]
-    # ... other fields
+# All responses are typed Pydantic models
+sms_response = client.sms.send_sms(recipient="+1234567890", message="Hello", sender="+1987654321")
+print(f"Message ID: {sms_response.id}")  # Type-safe access
+print(f"Status: {sms_response.status}")
 ```
 
 ## Development
@@ -384,7 +172,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-- **Documentation**: [https://devo-global-comms-python.readthedocs.io](https://devo-global-comms-python.readthedocs.io)
+- **Documentation**: [https://devotel.github.io/devo-global-comms-python/](https://devotel.github.io/devo-global-comms-python/)
 - **Issues**: [GitHub Issues](https://github.com/devotel/devo-global-comms-python/issues)
 - **Email**: [support@devotel.io](mailto:support@devotel.io)