mirror of
https://github.com/andwati/telecom-platform.git
synced 2026-10-18 11:02:54 +00:00
nutcas3
d846c304a4
- Add README.md with installation instructions, architecture overview, and API examples for all SDK modules - Add AuthProvider class with API key and JWT token support (GenerateJWTToken, ValidateJWTToken, GetHeaders, ClearTokenCache methods) - Add HTTPClient base class with retry logic, error handling, and timeout management - Add GraphQLAPI, PaymentsAPI, RatingPlansAPI
311 lines
7.2 KiB
Markdown
311 lines
7.2 KiB
Markdown
# Telecom Platform Python SDK
|
|
|
|
Async Python SDK for the Telecom Platform with full type hints and modern async/await support.
|
|
|
|
## Features
|
|
|
|
- **Modular Architecture**: Separate modules for authentication, API clients, and WebSocket
|
|
- **Async/Await Support**: Full async/await support with aiohttp
|
|
- **Type Safety**: Complete type hints with Pydantic models
|
|
- **WebSocket Support**: Real-time updates via WebSocket
|
|
- **GraphQL Support**: Execute GraphQL queries
|
|
- **Retry Logic**: Built-in retry mechanism with exponential backoff
|
|
- **Error Handling**: Comprehensive error handling with custom exceptions
|
|
- **Logging**: Optional debug logging
|
|
- **Context Manager**: Async context manager support
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install telecom-sdk
|
|
```
|
|
|
|
Or install from source:
|
|
|
|
```bash
|
|
git clone https://github.com/nutcas3/telecom-platform.git
|
|
cd telecom-platform/sdk/python
|
|
# Use uv for faster installation (recommended)
|
|
uv pip install -r requirements.txt
|
|
uv pip install -e .
|
|
# Or traditional pip
|
|
pip install -r requirements.txt
|
|
pip install -e .
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The SDK is organized into modular components:
|
|
|
|
- `auth.py` - Authentication provider handling API keys and JWT tokens
|
|
- `api.py` - Main API client with HTTP request handling and retry logic
|
|
- `websocket.py` - WebSocket client for real-time updates
|
|
- `types.py` - Type definitions and Pydantic models
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
import asyncio
|
|
from telecom_sdk import TelecomSDK
|
|
|
|
async def main():
|
|
async with TelecomSDK(
|
|
api_url="http://localhost:8000",
|
|
api_key="your-api-key",
|
|
enable_logging=True
|
|
) as sdk:
|
|
|
|
# Get subscriber
|
|
subscriber = await sdk.get_subscriber(1)
|
|
print(f"Subscriber: {subscriber.first_name} {subscriber.last_name}")
|
|
|
|
# Get usage stats
|
|
from datetime import datetime, timedelta
|
|
end_date = datetime.now()
|
|
start_date = end_date - timedelta(days=30)
|
|
|
|
usage = await sdk.get_usage_stats(1, start_date, end_date)
|
|
print(f"Data usage: {usage.data_up + usage.data_down} bytes")
|
|
|
|
# Create payment transaction
|
|
transaction = await sdk.create_payment_transaction(
|
|
subscriber_id=1,
|
|
amount=25.00,
|
|
currency="USD"
|
|
)
|
|
print(f"Transaction ID: {transaction.id}")
|
|
|
|
if __name__ == "__main__":
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## WebSocket Example
|
|
|
|
```python
|
|
import asyncio
|
|
from telecom_sdk import TelecomSDK, WebSocketMessage
|
|
|
|
async def handle_message(message: WebSocketMessage):
|
|
"""Handle WebSocket messages."""
|
|
print(f"Received message type: {message.type}")
|
|
print(f"Message data: {message.data}")
|
|
|
|
async def main():
|
|
sdk = TelecomSDK(api_url="http://localhost:8000")
|
|
|
|
# Connect to WebSocket
|
|
await sdk.connect_websocket(handle_message)
|
|
|
|
# Keep running
|
|
try:
|
|
while True:
|
|
await asyncio.sleep(1)
|
|
except KeyboardInterrupt:
|
|
await sdk.disconnect_websocket()
|
|
|
|
if __name__ == "__main__":
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## GraphQL Example
|
|
|
|
```python
|
|
import asyncio
|
|
from telecom_sdk import TelecomSDK
|
|
|
|
async def main():
|
|
async with TelecomSDK(api_url="http://localhost:8000") as sdk:
|
|
|
|
query = """
|
|
query GetSubscribers($first: Int, $after: String) {
|
|
subscribers(first: $first, after: $after) {
|
|
edges {
|
|
node {
|
|
id
|
|
firstName
|
|
lastName
|
|
email
|
|
status
|
|
}
|
|
}
|
|
pageInfo {
|
|
hasNextPage
|
|
endCursor
|
|
}
|
|
}
|
|
}
|
|
"""
|
|
|
|
variables = {"first": 10}
|
|
result = await sdk.execute_graphql_query(query, variables)
|
|
|
|
for edge in result["data"]["subscribers"]["edges"]:
|
|
subscriber = edge["node"]
|
|
print(f"{subscriber['firstName']} {subscriber['lastName']}")
|
|
|
|
if __name__ == "__main__":
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Subscriber Management
|
|
|
|
```python
|
|
# Get subscriber
|
|
subscriber = await sdk.get_subscriber(subscriber_id)
|
|
|
|
# List subscribers
|
|
subscribers = await sdk.list_subscribers(page=1, page_size=50, status="active")
|
|
|
|
# Create subscriber
|
|
subscriber = await sdk.create_subscriber(
|
|
imsi="208930000000001",
|
|
msisdn="+1234567890",
|
|
first_name="John",
|
|
last_name="Doe",
|
|
email="[email protected]",
|
|
plan_id=1
|
|
)
|
|
|
|
# Update subscriber
|
|
subscriber = await sdk.update_subscriber(subscriber_id, first_name="Jane")
|
|
|
|
# Suspend subscriber
|
|
subscriber = await sdk.suspend_subscriber(subscriber_id)
|
|
|
|
# Activate subscriber
|
|
subscriber = await sdk.activate_subscriber(subscriber_id)
|
|
|
|
# Terminate subscriber
|
|
success = await sdk.terminate_subscriber(subscriber_id)
|
|
```
|
|
|
|
### Usage Management
|
|
|
|
```python
|
|
from datetime import datetime, timedelta
|
|
|
|
# Get usage stats
|
|
usage = await sdk.get_usage_stats(
|
|
subscriber_id=1,
|
|
start_date=datetime.now() - timedelta(days=30),
|
|
end_date=datetime.now()
|
|
)
|
|
|
|
# List usage events
|
|
events = await sdk.list_usage_events(
|
|
subscriber_id=1,
|
|
usage_type="data",
|
|
page=1,
|
|
page_size=50
|
|
)
|
|
|
|
# Get real-time usage
|
|
realtime = await sdk.get_real_time_usage(subscriber_id)
|
|
```
|
|
|
|
### Payment Management
|
|
|
|
```python
|
|
# Create payment transaction
|
|
transaction = await sdk.create_payment_transaction(
|
|
subscriber_id=1,
|
|
amount=25.00,
|
|
currency="USD",
|
|
gateway="stripe",
|
|
metadata={"description": "Monthly plan"}
|
|
)
|
|
|
|
# Get transaction
|
|
transaction = await sdk.get_payment_transaction(transaction_id)
|
|
|
|
# List transactions
|
|
transactions = await sdk.list_payment_transactions(
|
|
subscriber_id=1,
|
|
status="completed"
|
|
)
|
|
```
|
|
|
|
### System Management
|
|
|
|
```python
|
|
# Get system stats
|
|
stats = await sdk.get_system_stats()
|
|
|
|
# Get health status
|
|
health = await sdk.get_health_status()
|
|
```
|
|
|
|
### Rating Plans
|
|
|
|
```python
|
|
# List rating plans
|
|
plans = await sdk.list_rating_plans()
|
|
|
|
# Get specific plan
|
|
plan = await sdk.get_rating_plan(plan_id)
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```python
|
|
from telecom_sdk import TelecomSDK, AuthenticationError, APIError, NetworkError
|
|
|
|
async def main():
|
|
try:
|
|
async with TelecomSDK(api_url="http://localhost:8000") as sdk:
|
|
subscriber = await sdk.get_subscriber(1)
|
|
except AuthenticationError:
|
|
print("Authentication failed")
|
|
except APIError as e:
|
|
print(f"API error: {e}")
|
|
except NetworkError as e:
|
|
print(f"Network error: {e}")
|
|
except TelecomError as e:
|
|
print(f"Telecom error: {e}")
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The SDK can be configured with the following options:
|
|
|
|
- `api_url`: Base URL for the API server (default: "http://localhost:8000")
|
|
- `api_key`: API key for authentication
|
|
- `timeout`: Request timeout in seconds (default: 30)
|
|
- `max_retries`: Maximum number of retry attempts (default: 3)
|
|
- `retry_delay`: Delay between retries in seconds (default: 1.0)
|
|
- `enable_logging`: Enable debug logging (default: False)
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Install development dependencies
|
|
pip install -r requirements-dev.txt
|
|
|
|
# Run tests
|
|
pytest tests/
|
|
|
|
# Run tests with coverage
|
|
pytest tests/ --cov=telecom_sdk
|
|
```
|
|
|
|
### Code Style
|
|
|
|
```bash
|
|
# Format code
|
|
black telecom_sdk/
|
|
|
|
# Lint code
|
|
flake8 telecom_sdk/
|
|
|
|
# Type checking
|
|
mypy telecom_sdk/
|
|
```
|
|
|
|
## License
|
|
|
|
This SDK is licensed under the MIT License.
|