Skip to content

feat: Add MkDocs documentation with GitHub Pages deployment #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
parman-devotel merged 1 commit into from
Aug 31, 2025
Merged

feat: Add MkDocs documentation with GitHub Pages deployment #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
274 changes: 31 additions & 243 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
)
```

Expand All @@ -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
Expand Down Expand Up @@ -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)

Expand Down
Loading
Loading