Skip to content

Commit 5851829

Browse files
Merge pull request #1 from Devotel/feature/modular-examples-sms
feat: implement modular example structure with SMS resource
2 parents b98114d + 5211757 commit 5851829

File tree

14 files changed

+1620
-274
lines changed

14 files changed

+1620
-274
lines changed

.pre-commit-config.yaml

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,23 +14,23 @@ repos:
1414
hooks:
1515
- id: black
1616
language_version: python3
17-
args: [--line-length=88]
17+
args: [--line-length=120]
1818

1919
- repo: https://github.com/pycqa/isort
2020
rev: 5.12.0
2121
hooks:
2222
- id: isort
23-
args: [--profile=black, --line-length=88]
23+
args: [--profile=black, --line-length=120]
2424

2525
- repo: https://github.com/pycqa/flake8
2626
rev: 6.0.0
2727
hooks:
2828
- id: flake8
29-
args: [--max-line-length=88, --extend-ignore=E203,W503]
29+
args: ["--max-line-length=120", "--extend-ignore=E203,W503"]
3030

31-
- repo: https://github.com/pre-commit/mirrors-mypy
32-
rev: v1.3.0
33-
hooks:
34-
- id: mypy
35-
additional_dependencies: [pydantic, requests, types-requests]
36-
args: [--ignore-missing-imports]
31+
# - repo: https://github.com/pre-commit/mirrors-mypy
32+
# rev: v1.3.0
33+
# hooks:
34+
# - id: mypy
35+
# additional_dependencies: [pydantic, requests, types-requests]
36+
# args: [--ignore-missing-imports, --python-version=3.9]

examples/README.md

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Devo Global Communications SDK - Examples
2+
3+
This directory contains comprehensive examples for using the Devo Global Communications SDK. Each resource has its own dedicated example file with detailed demonstrations of the available functionality.
4+
5+
## 📁 Example Files
6+
7+
### 🚀 Overview
8+
- **`basic_usage.py`** - Interactive overview and launcher for all examples
9+
10+
### 📱 Communication Resources
11+
- **`sms_example.py`** - ✅ **Complete SMS API implementation**
12+
- Send SMS messages via quick-send API
13+
- Get available senders
14+
- Search and purchase phone numbers
15+
- Legacy compatibility methods
16+
17+
- **`email_example.py`** - 🚧 **Placeholder** (Email functionality)
18+
- **`whatsapp_example.py`** - 🚧 **Placeholder** (WhatsApp functionality)
19+
- **`rcs_example.py`** - 🚧 **Placeholder** (RCS functionality)
20+
21+
### 👥 Management Resources
22+
- **`contacts_example.py`** - 🚧 **Placeholder** (Contact management)
23+
24+
## 🚀 Getting Started
25+
26+
### Prerequisites
27+
1. **API Key**: Get your API key from the Devo dashboard
28+
2. **Environment**: Set the `DEVO_API_KEY` environment variable
29+
```bash
30+
# Windows (PowerShell)
31+
$env:DEVO_API_KEY = "your_api_key_here"
32+
33+
# Windows (Command Prompt)
34+
set DEVO_API_KEY=your_api_key_here
35+
36+
# Unix/Linux/macOS
37+
export DEVO_API_KEY=your_api_key_here
38+
```
39+
40+
### Running Examples
41+
42+
#### Option 1: Interactive Overview (Recommended)
43+
```bash
44+
python examples/basic_usage.py
45+
```
46+
This provides an interactive menu to choose and run specific examples.
47+
48+
#### Option 2: Run Individual Examples
49+
```bash
50+
# SMS functionality (fully implemented)
51+
python examples/sms_example.py
52+
53+
# Other resources (placeholder examples)
54+
python examples/email_example.py
55+
python examples/whatsapp_example.py
56+
python examples/contacts_example.py
57+
python examples/rcs_example.py
58+
```
59+
60+
## 📱 SMS Examples (Fully Implemented)
61+
62+
The SMS resource is fully implemented with all four API endpoints:
63+
64+
### 🔧 Available Functions
65+
1. **Send SMS** - `client.sms.send_sms()`
66+
- Uses POST `/user-api/sms/quick-send`
67+
- High-quality routing validation
68+
- Comprehensive response data
69+
70+
2. **Get Senders** - `client.sms.get_senders()`
71+
- Uses GET `/user-api/me/senders`
72+
- Lists all available sender numbers/IDs
73+
74+
3. **Search Numbers** - `client.sms.get_available_numbers()`
75+
- Uses GET `/user-api/numbers`
76+
- Filter by region, type, and limit results
77+
78+
4. **Purchase Numbers** - `client.sms.buy_number()`
79+
- Uses POST `/user-api/numbers/buy`
80+
- Complete number purchasing workflow
81+
82+
### 🔄 Legacy Compatibility
83+
The SMS resource maintains backward compatibility with legacy methods while using the new API implementation underneath.
84+
85+
## 🚧 Placeholder Examples
86+
87+
The following examples show the structure and planned functionality but are not yet implemented:
88+
89+
- **Email**: Send emails, attachments, templates
90+
- **WhatsApp**: Text messages, media, templates, business features
91+
- **RCS**: Rich messaging, cards, carousels, capability checks
92+
- **Contacts**: CRUD operations, contact management
93+
94+
## 🔧 Configuration Notes
95+
96+
### Phone Numbers
97+
- Replace placeholder phone numbers (`+1234567890`) with actual numbers
98+
- Ensure phone numbers are in E.164 format (e.g., `+1234567890`)
99+
- Use valid sender numbers from your Devo dashboard
100+
101+
### Testing vs Production
102+
- Some examples include test mode flags
103+
- Number purchase examples are commented out to prevent accidental charges
104+
- Always test with small limits when exploring available numbers
105+
106+
### Error Handling
107+
All examples include comprehensive error handling with:
108+
- Detailed error messages
109+
- HTTP status codes
110+
- API-specific error codes
111+
- Response data debugging
112+
113+
## 🆔 Authentication
114+
115+
All examples use API key authentication:
116+
```python
117+
from devo_global_comms_python import DevoClient
118+
119+
client = DevoClient(api_key="your_api_key_here")
120+
```
121+
122+
## 📋 Example Output
123+
124+
### SMS Example Output
125+
```
126+
📱 SMS QUICK-SEND API EXAMPLE
127+
------------------------------
128+
📤 Sending SMS to +1234567890...
129+
✅ SMS sent successfully!
130+
📋 Message ID: msg_123456789
131+
📊 Status: sent
132+
📱 Recipient: +1234567890
133+
🔄 Direction: outbound
134+
135+
👥 GET AVAILABLE SENDERS EXAMPLE
136+
------------------------------
137+
✅ Found 3 available senders:
138+
1. 📞 Phone: +0987654321
139+
🏷️ Type: longcode
140+
🧪 Test Mode: No
141+
```
142+
143+
## 🤝 Contributing
144+
145+
When implementing new resources:
146+
147+
1. **Create Resource Example**: Copy the structure from `sms_example.py`
148+
2. **Update Basic Usage**: Add the new resource to `basic_usage.py`
149+
3. **Update This README**: Document the new functionality
150+
4. **Follow Patterns**: Use consistent emoji, formatting, and error handling
151+
152+
## 📚 Additional Resources
153+
154+
- **SDK Documentation**: [Link to main documentation]
155+
- **API Reference**: [Link to API docs]
156+
- **Devo Dashboard**: [Link to dashboard]
157+
- **Support**: [Link to support]
158+
159+
---
160+
161+
**Need help?** Check the individual example files for detailed comments and error handling patterns.

examples/basic_usage.py

Lines changed: 111 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,126 @@
11
import os
2+
import subprocess
3+
import sys
24

35
from devo_global_comms_python import DevoClient, DevoException
46

57

68
def main():
7-
# Initialize the client with your API key
8-
# You can get your API key from the Devo dashboard
9+
print("🚀 Devo Global Communications SDK")
10+
print("=" * 60)
11+
12+
# Check if API key is set
913
api_key = os.getenv("DEVO_API_KEY")
1014
if not api_key:
11-
print("Please set DEVO_API_KEY environment variable")
15+
print("❌ Please set DEVO_API_KEY environment variable")
16+
print(" You can get your API key from the Devo dashboard")
17+
return
18+
19+
# Initialize the client
20+
try:
21+
client = DevoClient(api_key=api_key)
22+
print("✅ Devo SDK Client initialized successfully")
23+
except Exception as e:
24+
print(f"❌ Failed to initialize client: {e}")
1225
return
1326

14-
client = DevoClient(api_key=api_key)
27+
print("\n📋 Available Resources:")
28+
print("-" * 30)
29+
30+
# Check available resources
31+
resources = []
32+
if hasattr(client, "sms"):
33+
resources.append(("📱 SMS", "Implemented", "sms_example.py"))
34+
if hasattr(client, "email"):
35+
resources.append(("📧 Email", "Placeholder", "email_example.py"))
36+
if hasattr(client, "whatsapp"):
37+
resources.append(("💬 WhatsApp", "Placeholder", "whatsapp_example.py"))
38+
if hasattr(client, "contacts"):
39+
resources.append(("👥 Contacts", "Placeholder", "contacts_example.py"))
40+
if hasattr(client, "rcs"):
41+
resources.append(("🎴 RCS", "Placeholder", "rcs_example.py"))
42+
43+
for resource, status, example_file in resources:
44+
print(f" {resource:<12} - {status:<12} -> {example_file}")
45+
46+
# Quick SMS test if available
47+
if hasattr(client, "sms"):
48+
print("\n🧪 Quick SMS Test:")
49+
print("-" * 30)
50+
try:
51+
# Try to get senders as a connectivity test
52+
senders = client.sms.get_senders()
53+
print(f"✅ SMS connection successful - {len(senders.senders)} senders available")
54+
55+
if senders.senders:
56+
print(" Sample senders:")
57+
for i, sender in enumerate(senders.senders[:3], 1):
58+
print(f" {i}. {sender.phone_number} ({sender.type})")
59+
if len(senders.senders) > 3:
60+
print(f" ... and {len(senders.senders) - 3} more")
61+
62+
except DevoException as e:
63+
print(f"⚠️ SMS connection test failed: {e}")
64+
65+
# Show example usage
66+
print("\n💡 Getting Started:")
67+
print("-" * 30)
68+
print("1. Run individual resource examples:")
69+
print(" python examples/sms_example.py # Complete SMS functionality")
70+
print(" python examples/email_example.py # Email examples (placeholder)")
71+
print(" python examples/whatsapp_example.py # WhatsApp examples (placeholder)")
72+
print(" python examples/contacts_example.py # Contact management (placeholder)")
73+
print(" python examples/rcs_example.py # RCS examples (placeholder)")
74+
print()
75+
print("2. Quick SMS example:")
76+
print(" from devo_global_comms_python import DevoClient")
77+
print(" client = DevoClient(api_key='your_api_key')")
78+
print(" response = client.sms.send_sms(")
79+
print(" recipient='+1234567890',")
80+
print(" message='Hello from Devo!',")
81+
print(" sender='your_sender_id'")
82+
print(" )")
83+
84+
# Interactive menu
85+
print("\n🎯 Interactive Examples:")
86+
print("-" * 30)
87+
print("Would you like to run a specific example?")
88+
print("1. SMS Example (full functionality)")
89+
print("2. Email Example (placeholder)")
90+
print("3. WhatsApp Example (placeholder)")
91+
print("4. Contacts Example (placeholder)")
92+
print("5. RCS Example (placeholder)")
93+
print("0. Exit")
1594

1695
try:
17-
# Example 1: Send an SMS
18-
print("Sending SMS...")
19-
sms = client.sms.send(
20-
to="+1234567890", # Replace with actual phone number
21-
body="Hello from Devo SDK! This is a test SMS message.",
22-
)
23-
print(f"SMS sent successfully! Message SID: {sms.sid}")
24-
print(f"Status: {sms.status}")
25-
26-
# Example 2: Send an email
27-
print("\nSending email...")
28-
email = client.email.send(
29-
to="recipient@example.com", # Replace with actual email
30-
subject="Test Email from Devo SDK",
31-
body="This is a test email sent using the Devo Global Communications SDK.",
32-
html_body="<h1>Test Email</h1><p>This is a <strong>test email</strong> sent using the Devo SDK.</p>",
33-
)
34-
print(f"Email sent successfully! Message ID: {email.id}")
35-
print(f"Status: {email.status}")
36-
37-
# Example 3: Send a WhatsApp message
38-
print("\nSending WhatsApp message...")
39-
whatsapp = client.whatsapp.send_text(
40-
to="+1234567890", # Replace with actual WhatsApp number
41-
text="Hello from Devo SDK! This is a WhatsApp message.",
42-
)
43-
print(f"WhatsApp message sent successfully! Message ID: {whatsapp.id}")
44-
print(f"Status: {whatsapp.status}")
45-
46-
# Example 4: Create a contact
47-
print("\nCreating contact...")
48-
contact = client.contacts.create(
49-
phone_number="+1234567890",
50-
email="contact@example.com",
51-
first_name="John",
52-
last_name="Doe",
53-
company="Example Corp",
54-
metadata={"source": "sdk_example"},
55-
)
56-
print(f"Contact created successfully! Contact ID: {contact.id}")
57-
print(f"Name: {contact.first_name} {contact.last_name}")
58-
59-
# Example 5: List recent messages
60-
print("\nListing recent messages...")
61-
messages = client.messages.list(limit=5, date_sent_after="2024-01-01")
62-
print(f"Found {len(messages)} recent messages:")
63-
for message in messages:
64-
print(f" - {message.channel}: {message.id} ({message.status})")
65-
66-
except DevoException as e:
67-
print(f"Error: {e}")
96+
choice = input("\nEnter your choice (0-5): ").strip()
97+
example_files = {
98+
"1": "sms_example.py",
99+
"2": "email_example.py",
100+
"3": "whatsapp_example.py",
101+
"4": "contacts_example.py",
102+
"5": "rcs_example.py",
103+
}
104+
105+
if choice in example_files:
106+
example_file = example_files[choice]
107+
example_path = os.path.join(os.path.dirname(__file__), example_file)
108+
109+
if os.path.exists(example_path):
110+
print(f"\n🚀 Running {example_file}...")
111+
print("=" * 60)
112+
subprocess.run([sys.executable, example_path], check=True)
113+
else:
114+
print(f"❌ Example file {example_file} not found")
115+
elif choice == "0":
116+
print("👋 Goodbye!")
117+
else:
118+
print("❌ Invalid choice")
119+
120+
except KeyboardInterrupt:
121+
print("\n👋 Goodbye!")
122+
except Exception as e:
123+
print(f"❌ Error running example: {e}")
68124

69125

70126
if __name__ == "__main__":

0 commit comments

Comments
 (0)