# Messaging SDK
A Python SDK designed to simplify interaction with the messaging API and webhook functionalities. It ensures seamless message management, automatic signature validation, and provides a robust foundation for developing scalable messaging applications.
[](https://github.com/shiningflash/messaging-sdk/blob/main/docs/sdk_usage.md) [](https://github.com/shiningflash/messaging-sdk/blob/main/docs/webhook_guide.md)
---
## Table of Contents
1. [Overview](#overview)
2. [Features](#features)
3. [Setup](#setup)
4. [Project Structure](#project-structure)
5. [Usage Guide](#usage-guide)
6. [Testing](#testing)
7. [Architecture Diagram](#architecture-diagram)
8. [Lifecycle with Example](#lifecycle-with-example)
9. [Future Improvements](#future-improvements)
---
## Overview
The **Messaging SDK** is a Python library that allows developers to interact with the messaging API effortlessly. It handles authentication, API endpoint management, and webhook processing while ensuring security through HMAC signature validation.
### Key Objectives
- Provide a seamless developer experience.
- Simplify API interactions with auto-completion and easy-to-use methods.
- Handle webhook signature validation and event processing.
---
## Features
- **SDK Functionalities**:
- Send messages with validation.
- List and manage contacts and messages.
- Retry mechanism for transient errors.
- **Webhook Handling**:
- Process event notifications.
- Validate requests using HMAC signatures.
- **Environment Configuration**:
- Dynamic settings via `.env` file.
- **Testing**:
- Unit, Integration, and End-to-End tests included.
---
## Setup
1. Clone the repository:
```bash
git clone https://github.com/shiningflash/messaging-sdk.git
cd messaging-sdk
```
2. Create a virtual environment and install dependencies:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```
3. Configure environment variables:
- Copy `.env.example` to `.env`: `cp .env.example .env`
- Edit `.env` and adjust the values.
4. Browse the API:
- The repository includes an **OpenAPI Specification** file located at: `./docs/openapi.yaml`.
- To explore the API visually, you can use Docker to run the provided tools:
1. Ensure Docker is installed on your machine.
2. Start the servers: `docker compose up`.
3. The following servers will be available: **Swagger UI**: [http://localhost:8080](http://localhost:8080), **Redocly**: [http://localhost:8090](http://localhost:8090), **API Server**: [http://localhost:3000](http://localhost:3000) (uses a local database).
---
## Usage Guide
### SDK Usage
1. **Initialize the SDK:**
```python
from sdk.client import ApiClient
from sdk.features.messages import Messages
# Initialize the API client and Messages module
api_client = ApiClient()
messages = Messages(api_client)
# Send a message
response = messages.send_message({
"to": {"id": "contact123"}, # Use the contact ID format for the recipient
"content": "Hello, World!",
"from": "+987654321" # Sender's phone number
})
print(response)
```
2. **List Messages:**
```python
# List sent messages with pagination
response = messages.list_messages(page=1, limit=10)
print(response)
```
**Example Response:**
```json
{
"messages": [
{
"id": "msg123",
"to": {
"id": "contact123",
"name": "John Doe",
"phone": "+1234567890"
},
"from": "+987654321",
"content": "Hello, World!",
"status": "delivered",
"createdAt": "2024-12-01T00:00:00Z"
}
],
"page": 1,
"quantityPerPage": 10
}
```
#### Additional Features
- **Contact Management:** Add, update, delete, and list contacts.
- **Webhook Integration:** Validate and handle webhook payloads with ease.
#### Comprehensive User Guide for SDK Usage
[](https://github.com/shiningflash/messaging-sdk/blob/main/docs/sdk_usage.md)
---
### Webhook Setup
1. Run the webhook server:
```bash
uvicorn src.server.app:app --reload --port 3010
```
2. Configure the API to send events to your webhook endpoint (e.g., `http://localhost:3010/webhooks`).
#### Comprehensive User Guide for Webhook
[](https://github.com/shiningflash/messaging-sdk/blob/main/docs/webhook_guide.md)
---
## Testing
1. Run all tests:
```bash
pytest
```
2. Generate a coverage report:
```bash
pytest --cov=src --cov-report=term-missing
```
3. Run specific test modules:
```bash
pytest tests/unit/test_sdk/
```
---
## Project Structure
A detailed overview of the project structure, including descriptions of key files and directories.
```plaintext
.
├── .github/ # GitHub workflows for CI/CD
│ └── workflows/
│ └── ci.yml # Continuous Integration pipeline configuration
├── docs/ # Additional documentation
│ ├── openapi.yaml # OpenAPI docs
│ ├── sdk_usage.md # Comprehensive SDK usage documentation
│ └── webhook_guide.md # Webhook-specific documentation
├── src/ # Source code directory
│ ├── core/ # Core modules for shared logic
│ │ ├── __init__.py # Core module initialization
│ │ ├── exceptions/ # Exception handling modules
│ │ │ ├── __init__.py # Consolidated exception imports
│ │ │ ├── api.py # API-specific exceptions
│ │ │ ├── decorators.py # Decorators for exception handling
│ │ │ └── resource.py # Resource-specific exceptions
│ │ ├── config.py # Global configuration file for SDK and server
│ │ ├── logger.py # Logging utilities
│ │ ├── requests.py # Request helpers for SDK
│ │ ├── retry.py # Retry logic for transient failures
│ │ ├── security.py # HMAC validation and signature generation
│ │ └── validators.py # Common validation logic
│ ├── schemas/ # Schema definitions for request/response
│ │ ├── __init__.py # Schemas initialization
│ │ ├── contacts.py # Contact-related schemas
│ │ ├── errors.py # Error schemas (aligned with OpenAPI specs)
│ │ ├── messages.py # Message-related schemas
│ │ └── webhook.py # Webhook payload schemas
│ ├── sdk/ # SDK-related functionalities
│ │ ├── __init__.py # SDK initialization
│ │ ├── client.py # API client for interacting with the server
│ │ └── features/ # API feature modules
│ │ ├── __init__.py # Features initialization
│ │ ├── contacts.py # Contacts-related SDK operations
│ │ └── messages.py # Messages-related SDK operations
│ ├── server/ # Webhook server implementation
│ │ ├── __init__.py # Server initialization
│ │ ├── app.py # Main FastAPI application
│ │ └── schemas.py # Schemas specific to the webhook server
├── tests/ # Testing files for unit, integration, and E2E
│ ├── __init__.py # Test package initialization
│ ├── conftest.py # Pytest fixtures and test setup
│ ├── e2e/ # End-to-End (E2E) tests
│ │ ├── __init__.py # E2E tests initialization
│ │ ├── test_contacts_e2e.py # E2E tests for contacts feature
│ │ └── test_messages_e2e.py # E2E tests for messages feature
│ ├── integration/ # Integration tests
│ │ ├── __init__.py # Integration tests initialization
│ │ ├── test_contacts_integration.py # Integration tests for contacts
│ │ ├── test_messages_integration.py # Integration tests for messages
│ │ └── test_webhook.py # Integration tests for webhook functionality
│ └── unit/ # Unit tests for SDK and server
│ ├── test_sdk/ # SDK-specific unit tests
│ │ ├── __init__.py # SDK unit tests initialization
│ │ ├── test_client.py # Unit tests for API client
│ │ ├── test_contacts.py # Unit tests for contacts module
│ │ └── test_messages.py # Unit tests for messages module
│ └── test_server/ # Server-specific unit tests
│ ├── __init__.py # Server unit tests initialization
│ ├── test_route.py # Unit tests for API routes
│ └── test_signature_validation.py # Unit tests for signature validation
├── venv/ # Python virtual environment (not versioned)
├── .env.example # Example environment variables
├── docker-compose.yml # Docker Compose configuration
├── pytest.ini # Pytest configuration
├── requirements.in # Base Python dependencies
├── requirements.txt # Locked Python dependencies
├── README.md # Project documentation and usage guide
├── setup.py # Setup file to enable 'pip install .'
```
---
## Architecture Diagram
Here is the comprehensive architectural diagram for better understanding.
```plaintext
+----------------------------------------------------------+
| User |
| (Uses the SDK to send messages, manage contacts, |
| and handle webhook responses programmatically) |
+----------------------------------------------------------+
|
| 1. SDK API Calls
|
+----------------------------------------------------------+
| Messaging SDK |
| |
| +---------------------------------------------+ |
| | Features: | |
| | - `messages.py`: Send/manage messages | |
| | - `contacts.py`: Manage contact lists | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Utilities: | |
| | - `logger.py`: Logs interactions | |
| | - `validators.py`: Validates signatures | |
| | - `exceptions.py`: Handles errors | |
| | - `retry.py`: Implements retry logic | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Client (`client.py`): Handles API requests | |
| | - Appends authentication headers | |
| | - Sends REST API calls (e.g., GET, POST) | |
| +---------------------------------------------+ |
+----------------------------------------------------------+
|
| 2. REST API Calls
v
+----------------------------------------------------------+
| API Server |
| |
| +---------------------------------------------+ |
| | Message Queue Simulation: | |
| | - Marks messages as `queued` | |
| | - Simulates delivery or failure | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Webhook Trigger: | |
| | - Sends event notifications to | |
| | configured Webhook Server URL | |
| +---------------------------------------------+ |
+----------------------------------------------------------+
|
| 3. Webhook Event Notifications
v
+----------------------------------------------------------+
| Webhook Server |
| |
| +---------------------------------------------+ |
| | Endpoints: `/webhooks` | |
| | - Receives POST requests | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Signature Validation: | |
| | - Validates HMAC signature from | |
| | Authorization header | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Payload Processing: | |
| | - Parses incoming JSON payload | |
| | - Logs event details | |
| | - Prints payload to console | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Error Handling: | |
| | - 401 Unauthorized: Invalid Signature | |
| | - 422 Unprocessable Entity: Bad Payload | |
| +---------------------------------------------+ |
+----------------------------------------------------------+
|
| 4. Event Logs/Responses
v
+----------------------------------------------------------+
| Logging |
| |
| - SDK Logs (via `logger.py`): |
| Logs all user interactions, API calls, |
| and errors. |
| |
| - Webhook Server Logs: |
| Logs validated events and signature failures. |
| |
+----------------------------------------------------------+
```
---
## Lifecycle with Example
Here is the comprehensive example for lifecycle of Messaging SDK and Webhook for more understanding.
```plaintext
1. User Sends a Message
+----------------------------------------------------------+
| User |
| - Calls `messages.send_message()` from the SDK |
| |
| Example Code: |
| sdk.messages.send_message( |
| to="+123456789", |
| from_sender="+987654321", |
| content="Hello, World!" |
| ) |
+----------------------------------------------------------+
|
v
2. SDK Sends API Request
+----------------------------------------------------------+
| Messaging SDK |
| |
| - Validates payload (e.g., phone number format). |
| - Prepares headers (`Authorization: Bearer <API_KEY>`). |
| - Sends HTTP POST request to the API. |
| |
| Request: |
| POST /messages |
| Headers: |
| - Authorization: Bearer <API_KEY> |
| Body: |
| { |
| "to": "+123456789", |
| "content": "Hello, World!", |
| "from_sender": "+987654321" |
| } |
+----------------------------------------------------------+
|
v
3. API Server Processes the Message
+----------------------------------------------------------+
| API Server |
| |
| - Marks message as `queued`. |
| - Simulates a delay for processing. |
| - Updates the message status to `delivered` or `failed`.|
| |
| Example Response: |
| { |
| "id": "msg123", |
| "status": "queued", |
| "createdAt": "2024-12-01T10:00:00Z" |
| } |
+----------------------------------------------------------+
|
v
4. API Triggers Webhook Notification
+----------------------------------------------------------+
| Webhook Trigger |
| |
| - Sends a POST request to the configured |
| webhook URL (e.g., `http://localhost:3010/webhooks`). |
| |
| Request: |
| POST /webhooks |
| Headers: |
| - Authorization: Bearer <HMAC-SIGNATURE> |
| Body: |
| { |
| "id": "msg123", |
| "status": "delivered", |
| "deliveredAt": "2024-12-01T12:00:00Z" |
| } |
+----------------------------------------------------------+
|
v
5. Webhook Server Processes the Event
+----------------------------------------------------------+
| Webhook Server |
| |
| - Validates the HMAC signature. |
| - Parses the payload. |
| - Logs and processes the event. |
| |
| Example Log: |
| - "Webhook received: {'id': 'msg123', 'status': 'delivered', |
| 'deliveredAt': '2024-12-01T12:00:00Z'}" |
| |
| Example Processing Code: |
| try: |
| verify_signature(payload, signature, secret) |
| print(f"Message {payload['id']} delivered.") |
| except ValueError: |
| print("Signature validation failed.") |
+----------------------------------------------------------+
|
v
6. Event Logging and Completion
+----------------------------------------------------------+
| Logging |
| |
| - SDK logs the sent message status and errors (if any). |
| - Webhook server logs validated payloads and events. |
| |
| Final Console Output: |
| "Message msg123 delivered." |
+----------------------------------------------------------+
```
---
## Future Improvements
- Add more advanced retry strategies for transient errors.
- Implement caching for frequently used API requests.
- Enhance webhook security with IP whitelisting.
- Extend SDK functionality to support additional API endpoints.
Raw data
{
"_id": null,
"home_page": "https://github.com/shiningflash/messaging-sdk",
"name": "messaging-py-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "messaging sdk python api contacts",
"author": "Amirul Islam",
"author_email": "amirulislamalmamun@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ff/cc/8498edb24bc479858d80d2793b50663ae0ad14fffcc25cf7ae88a21ed26f/messaging_py_sdk-2.1.2.tar.gz",
"platform": null,
"description": "# Messaging SDK\n\nA Python SDK designed to simplify interaction with the messaging API and webhook functionalities. It ensures seamless message management, automatic signature validation, and provides a robust foundation for developing scalable messaging applications.\n\n[](https://github.com/shiningflash/messaging-sdk/blob/main/docs/sdk_usage.md) [](https://github.com/shiningflash/messaging-sdk/blob/main/docs/webhook_guide.md)\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Features](#features)\n3. [Setup](#setup)\n4. [Project Structure](#project-structure)\n5. [Usage Guide](#usage-guide)\n6. [Testing](#testing)\n7. [Architecture Diagram](#architecture-diagram)\n8. [Lifecycle with Example](#lifecycle-with-example)\n9. [Future Improvements](#future-improvements)\n\n---\n\n## Overview\n\nThe **Messaging SDK** is a Python library that allows developers to interact with the messaging API effortlessly. It handles authentication, API endpoint management, and webhook processing while ensuring security through HMAC signature validation. \n\n### Key Objectives\n- Provide a seamless developer experience.\n- Simplify API interactions with auto-completion and easy-to-use methods.\n- Handle webhook signature validation and event processing.\n\n---\n\n## Features\n\n- **SDK Functionalities**:\n - Send messages with validation.\n - List and manage contacts and messages.\n - Retry mechanism for transient errors.\n \n- **Webhook Handling**:\n - Process event notifications.\n - Validate requests using HMAC signatures.\n \n- **Environment Configuration**:\n - Dynamic settings via `.env` file.\n \n- **Testing**:\n - Unit, Integration, and End-to-End tests included.\n\n---\n\n## Setup\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/shiningflash/messaging-sdk.git\n cd messaging-sdk\n ```\n\n2. Create a virtual environment and install dependencies:\n ```bash\n python -m venv venv\n source venv/bin/activate # On Windows: venv\\Scripts\\activate\n pip install -r requirements.txt\n ```\n\n3. Configure environment variables:\n - Copy `.env.example` to `.env`: `cp .env.example .env`\n - Edit `.env` and adjust the values.\n\n4. Browse the API:\n - The repository includes an **OpenAPI Specification** file located at: `./docs/openapi.yaml`.\n - To explore the API visually, you can use Docker to run the provided tools:\n 1. Ensure Docker is installed on your machine.\n 2. Start the servers: `docker compose up`.\n 3. The following servers will be available: **Swagger UI**: [http://localhost:8080](http://localhost:8080), **Redocly**: [http://localhost:8090](http://localhost:8090), **API Server**: [http://localhost:3000](http://localhost:3000) (uses a local database).\n\n---\n\n## Usage Guide\n\n### SDK Usage\n\n1. **Initialize the SDK:**\n\n ```python\n from sdk.client import ApiClient\n from sdk.features.messages import Messages\n\n # Initialize the API client and Messages module\n api_client = ApiClient()\n messages = Messages(api_client)\n\n # Send a message\n response = messages.send_message({\n \"to\": {\"id\": \"contact123\"}, # Use the contact ID format for the recipient\n \"content\": \"Hello, World!\",\n \"from\": \"+987654321\" # Sender's phone number\n })\n print(response)\n ```\n\n2. **List Messages:**\n\n ```python\n # List sent messages with pagination\n response = messages.list_messages(page=1, limit=10)\n print(response)\n ```\n\n **Example Response:**\n ```json\n {\n \"messages\": [\n {\n \"id\": \"msg123\",\n \"to\": {\n \"id\": \"contact123\",\n \"name\": \"John Doe\",\n \"phone\": \"+1234567890\"\n },\n \"from\": \"+987654321\",\n \"content\": \"Hello, World!\",\n \"status\": \"delivered\",\n \"createdAt\": \"2024-12-01T00:00:00Z\"\n }\n ],\n \"page\": 1,\n \"quantityPerPage\": 10\n }\n ```\n\n#### Additional Features\n\n- **Contact Management:** Add, update, delete, and list contacts.\n- **Webhook Integration:** Validate and handle webhook payloads with ease.\n\n#### Comprehensive User Guide for SDK Usage\n\n[](https://github.com/shiningflash/messaging-sdk/blob/main/docs/sdk_usage.md)\n\n---\n\n### Webhook Setup\n\n1. Run the webhook server:\n ```bash\n uvicorn src.server.app:app --reload --port 3010\n ```\n\n2. Configure the API to send events to your webhook endpoint (e.g., `http://localhost:3010/webhooks`).\n\n#### Comprehensive User Guide for Webhook\n\n[](https://github.com/shiningflash/messaging-sdk/blob/main/docs/webhook_guide.md)\n\n---\n\n## Testing\n\n1. Run all tests:\n ```bash\n pytest\n ```\n\n2. Generate a coverage report:\n ```bash\n pytest --cov=src --cov-report=term-missing\n ```\n\n3. Run specific test modules:\n ```bash\n pytest tests/unit/test_sdk/\n ```\n\n---\n\n\n## Project Structure\n\nA detailed overview of the project structure, including descriptions of key files and directories.\n\n```plaintext\n.\n\u251c\u2500\u2500 .github/ # GitHub workflows for CI/CD\n\u2502 \u2514\u2500\u2500 workflows/\n\u2502 \u2514\u2500\u2500 ci.yml # Continuous Integration pipeline configuration\n\u251c\u2500\u2500 docs/ # Additional documentation\n\u2502 \u251c\u2500\u2500 openapi.yaml # OpenAPI docs\n\u2502 \u251c\u2500\u2500 sdk_usage.md # Comprehensive SDK usage documentation\n\u2502 \u2514\u2500\u2500 webhook_guide.md # Webhook-specific documentation\n\u251c\u2500\u2500 src/ # Source code directory\n\u2502 \u251c\u2500\u2500 core/ # Core modules for shared logic\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Core module initialization\n\u2502 \u2502 \u251c\u2500\u2500 exceptions/ # Exception handling modules\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py # Consolidated exception imports\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 api.py # API-specific exceptions\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 decorators.py # Decorators for exception handling\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 resource.py # Resource-specific exceptions\n\u2502 \u2502 \u251c\u2500\u2500 config.py # Global configuration file for SDK and server\n\u2502 \u2502 \u251c\u2500\u2500 logger.py # Logging utilities\n\u2502 \u2502 \u251c\u2500\u2500 requests.py # Request helpers for SDK\n\u2502 \u2502 \u251c\u2500\u2500 retry.py # Retry logic for transient failures\n\u2502 \u2502 \u251c\u2500\u2500 security.py # HMAC validation and signature generation\n\u2502 \u2502 \u2514\u2500\u2500 validators.py # Common validation logic\n\u2502 \u251c\u2500\u2500 schemas/ # Schema definitions for request/response\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Schemas initialization\n\u2502 \u2502 \u251c\u2500\u2500 contacts.py # Contact-related schemas\n\u2502 \u2502 \u251c\u2500\u2500 errors.py # Error schemas (aligned with OpenAPI specs)\n\u2502 \u2502 \u251c\u2500\u2500 messages.py # Message-related schemas\n\u2502 \u2502 \u2514\u2500\u2500 webhook.py # Webhook payload schemas\n\u2502 \u251c\u2500\u2500 sdk/ # SDK-related functionalities\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # SDK initialization\n\u2502 \u2502 \u251c\u2500\u2500 client.py # API client for interacting with the server\n\u2502 \u2502 \u2514\u2500\u2500 features/ # API feature modules\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Features initialization\n\u2502 \u2502 \u251c\u2500\u2500 contacts.py # Contacts-related SDK operations\n\u2502 \u2502 \u2514\u2500\u2500 messages.py # Messages-related SDK operations\n\u2502 \u251c\u2500\u2500 server/ # Webhook server implementation\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Server initialization\n\u2502 \u2502 \u251c\u2500\u2500 app.py # Main FastAPI application\n\u2502 \u2502 \u2514\u2500\u2500 schemas.py # Schemas specific to the webhook server\n\u251c\u2500\u2500 tests/ # Testing files for unit, integration, and E2E\n\u2502 \u251c\u2500\u2500 __init__.py # Test package initialization\n\u2502 \u251c\u2500\u2500 conftest.py # Pytest fixtures and test setup\n\u2502 \u251c\u2500\u2500 e2e/ # End-to-End (E2E) tests\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # E2E tests initialization\n\u2502 \u2502 \u251c\u2500\u2500 test_contacts_e2e.py # E2E tests for contacts feature\n\u2502 \u2502 \u2514\u2500\u2500 test_messages_e2e.py # E2E tests for messages feature\n\u2502 \u251c\u2500\u2500 integration/ # Integration tests\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Integration tests initialization\n\u2502 \u2502 \u251c\u2500\u2500 test_contacts_integration.py # Integration tests for contacts\n\u2502 \u2502 \u251c\u2500\u2500 test_messages_integration.py # Integration tests for messages\n\u2502 \u2502 \u2514\u2500\u2500 test_webhook.py # Integration tests for webhook functionality\n\u2502 \u2514\u2500\u2500 unit/ # Unit tests for SDK and server\n\u2502 \u251c\u2500\u2500 test_sdk/ # SDK-specific unit tests\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # SDK unit tests initialization\n\u2502 \u2502 \u251c\u2500\u2500 test_client.py # Unit tests for API client\n\u2502 \u2502 \u251c\u2500\u2500 test_contacts.py # Unit tests for contacts module\n\u2502 \u2502 \u2514\u2500\u2500 test_messages.py # Unit tests for messages module\n\u2502 \u2514\u2500\u2500 test_server/ # Server-specific unit tests\n\u2502 \u251c\u2500\u2500 __init__.py # Server unit tests initialization\n\u2502 \u251c\u2500\u2500 test_route.py # Unit tests for API routes\n\u2502 \u2514\u2500\u2500 test_signature_validation.py # Unit tests for signature validation\n\u251c\u2500\u2500 venv/ # Python virtual environment (not versioned)\n\u251c\u2500\u2500 .env.example # Example environment variables\n\u251c\u2500\u2500 docker-compose.yml # Docker Compose configuration\n\u251c\u2500\u2500 pytest.ini # Pytest configuration\n\u251c\u2500\u2500 requirements.in # Base Python dependencies\n\u251c\u2500\u2500 requirements.txt # Locked Python dependencies\n\u251c\u2500\u2500 README.md # Project documentation and usage guide\n\u251c\u2500\u2500 setup.py # Setup file to enable 'pip install .'\n\n```\n\n---\n\n## Architecture Diagram\n\nHere is the comprehensive architectural diagram for better understanding.\n\n```plaintext\n+----------------------------------------------------------+\n| User |\n| (Uses the SDK to send messages, manage contacts, |\n| and handle webhook responses programmatically) |\n+----------------------------------------------------------+\n |\n | 1. SDK API Calls\n |\n+----------------------------------------------------------+\n| Messaging SDK |\n| |\n| +---------------------------------------------+ |\n| | Features: | |\n| | - `messages.py`: Send/manage messages | |\n| | - `contacts.py`: Manage contact lists | |\n| +---------------------------------------------+ |\n| |\n| +---------------------------------------------+ |\n| | Utilities: | |\n| | - `logger.py`: Logs interactions | |\n| | - `validators.py`: Validates signatures | |\n| | - `exceptions.py`: Handles errors | |\n| | - `retry.py`: Implements retry logic | |\n| +---------------------------------------------+ |\n| |\n| +---------------------------------------------+ |\n| | Client (`client.py`): Handles API requests | |\n| | - Appends authentication headers | |\n| | - Sends REST API calls (e.g., GET, POST) | |\n| +---------------------------------------------+ |\n+----------------------------------------------------------+\n |\n | 2. REST API Calls\n v\n+----------------------------------------------------------+\n| API Server |\n| |\n| +---------------------------------------------+ |\n| | Message Queue Simulation: | |\n| | - Marks messages as `queued` | |\n| | - Simulates delivery or failure | |\n| +---------------------------------------------+ |\n| |\n| +---------------------------------------------+ |\n| | Webhook Trigger: | |\n| | - Sends event notifications to | |\n| | configured Webhook Server URL | |\n| +---------------------------------------------+ |\n+----------------------------------------------------------+\n |\n | 3. Webhook Event Notifications\n v\n+----------------------------------------------------------+\n| Webhook Server |\n| |\n| +---------------------------------------------+ |\n| | Endpoints: `/webhooks` | |\n| | - Receives POST requests | |\n| +---------------------------------------------+ |\n| |\n| +---------------------------------------------+ |\n| | Signature Validation: | |\n| | - Validates HMAC signature from | |\n| | Authorization header | |\n| +---------------------------------------------+ |\n| |\n| +---------------------------------------------+ |\n| | Payload Processing: | |\n| | - Parses incoming JSON payload | |\n| | - Logs event details | |\n| | - Prints payload to console | |\n| +---------------------------------------------+ |\n| |\n| +---------------------------------------------+ |\n| | Error Handling: | |\n| | - 401 Unauthorized: Invalid Signature | |\n| | - 422 Unprocessable Entity: Bad Payload | |\n| +---------------------------------------------+ |\n+----------------------------------------------------------+\n |\n | 4. Event Logs/Responses\n v\n+----------------------------------------------------------+\n| Logging |\n| |\n| - SDK Logs (via `logger.py`): |\n| Logs all user interactions, API calls, |\n| and errors. |\n| |\n| - Webhook Server Logs: |\n| Logs validated events and signature failures. |\n| |\n+----------------------------------------------------------+\n```\n\n---\n\n## Lifecycle with Example\n\nHere is the comprehensive example for lifecycle of Messaging SDK and Webhook for more understanding.\n\n```plaintext\n1. User Sends a Message\n+----------------------------------------------------------+\n| User |\n| - Calls `messages.send_message()` from the SDK |\n| |\n| Example Code: |\n| sdk.messages.send_message( |\n| to=\"+123456789\", |\n| from_sender=\"+987654321\", |\n| content=\"Hello, World!\" |\n| ) |\n+----------------------------------------------------------+\n |\n v\n2. SDK Sends API Request\n+----------------------------------------------------------+\n| Messaging SDK |\n| |\n| - Validates payload (e.g., phone number format). |\n| - Prepares headers (`Authorization: Bearer <API_KEY>`). |\n| - Sends HTTP POST request to the API. |\n| |\n| Request: |\n| POST /messages |\n| Headers: |\n| - Authorization: Bearer <API_KEY> |\n| Body: |\n| { |\n| \"to\": \"+123456789\", |\n| \"content\": \"Hello, World!\", |\n| \"from_sender\": \"+987654321\" |\n| } |\n+----------------------------------------------------------+\n |\n v\n3. API Server Processes the Message\n+----------------------------------------------------------+\n| API Server |\n| |\n| - Marks message as `queued`. |\n| - Simulates a delay for processing. |\n| - Updates the message status to `delivered` or `failed`.|\n| |\n| Example Response: |\n| { |\n| \"id\": \"msg123\", |\n| \"status\": \"queued\", |\n| \"createdAt\": \"2024-12-01T10:00:00Z\" |\n| } |\n+----------------------------------------------------------+\n |\n v\n4. API Triggers Webhook Notification\n+----------------------------------------------------------+\n| Webhook Trigger |\n| |\n| - Sends a POST request to the configured |\n| webhook URL (e.g., `http://localhost:3010/webhooks`). |\n| |\n| Request: |\n| POST /webhooks |\n| Headers: |\n| - Authorization: Bearer <HMAC-SIGNATURE> |\n| Body: |\n| { |\n| \"id\": \"msg123\", |\n| \"status\": \"delivered\", |\n| \"deliveredAt\": \"2024-12-01T12:00:00Z\" |\n| } |\n+----------------------------------------------------------+\n |\n v\n5. Webhook Server Processes the Event\n+----------------------------------------------------------+\n| Webhook Server |\n| |\n| - Validates the HMAC signature. |\n| - Parses the payload. |\n| - Logs and processes the event. |\n| |\n| Example Log: |\n| - \"Webhook received: {'id': 'msg123', 'status': 'delivered', | \n| 'deliveredAt': '2024-12-01T12:00:00Z'}\" |\n| |\n| Example Processing Code: |\n| try: |\n| verify_signature(payload, signature, secret) |\n| print(f\"Message {payload['id']} delivered.\") |\n| except ValueError: |\n| print(\"Signature validation failed.\") |\n+----------------------------------------------------------+\n |\n v\n6. Event Logging and Completion\n+----------------------------------------------------------+\n| Logging |\n| |\n| - SDK logs the sent message status and errors (if any). |\n| - Webhook server logs validated payloads and events. |\n| |\n| Final Console Output: |\n| \"Message msg123 delivered.\" |\n+----------------------------------------------------------+\n```\n\n---\n\n## Future Improvements\n\n- Add more advanced retry strategies for transient errors.\n- Implement caching for frequently used API requests.\n- Enhance webhook security with IP whitelisting.\n- Extend SDK functionality to support additional API endpoints.\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "A Python SDK for managing messages and contacts, with webhook integration.",
"version": "2.1.2",
"project_urls": {
"Documentation": "https://github.com/shiningflash/messaging-sdk/blob/main/README.md",
"Homepage": "https://github.com/shiningflash/messaging-sdk",
"Issue Tracker": "https://github.com/shiningflash/messaging-sdk/issues",
"Source Code": "https://github.com/shiningflash"
},
"split_keywords": [
"messaging",
"sdk",
"python",
"api",
"contacts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9364f06ea4d757941b25992078c6475a8b41c1e8b26340646250a74c3f8bfba6",
"md5": "ca53e1836afc933bf65791f2e39ca94f",
"sha256": "d9848a272fc90510b44359a6cd01b4d38a8235e29b493ed4b7a7fb2a6e0f6d35"
},
"downloads": -1,
"filename": "messaging_py_sdk-2.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca53e1836afc933bf65791f2e39ca94f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22271,
"upload_time": "2024-12-06T23:58:48",
"upload_time_iso_8601": "2024-12-06T23:58:48.795809Z",
"url": "https://files.pythonhosted.org/packages/93/64/f06ea4d757941b25992078c6475a8b41c1e8b26340646250a74c3f8bfba6/messaging_py_sdk-2.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ffcc8498edb24bc479858d80d2793b50663ae0ad14fffcc25cf7ae88a21ed26f",
"md5": "8b9f34cf4a4e9e85bc049829a500cb15",
"sha256": "2cd62da64155de56ad930d1472a6c284490c81ad6e73b82dd2a45c1f9f9f012c"
},
"downloads": -1,
"filename": "messaging_py_sdk-2.1.2.tar.gz",
"has_sig": false,
"md5_digest": "8b9f34cf4a4e9e85bc049829a500cb15",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22191,
"upload_time": "2024-12-06T23:58:50",
"upload_time_iso_8601": "2024-12-06T23:58:50.245103Z",
"url": "https://files.pythonhosted.org/packages/ff/cc/8498edb24bc479858d80d2793b50663ae0ad14fffcc25cf7ae88a21ed26f/messaging_py_sdk-2.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 23:58:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shiningflash",
"github_project": "messaging-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "annotated-types",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "anyio",
"specs": [
[
"==",
"4.6.2.post1"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"24.10.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2024.8.30"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.0"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"7.6.8"
]
]
},
{
"name": "fastapi",
"specs": [
[
"==",
"0.115.5"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"7.1.1"
]
]
},
{
"name": "h11",
"specs": [
[
"==",
"0.14.0"
]
]
},
{
"name": "httpcore",
"specs": [
[
"==",
"1.0.7"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "mccabe",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"1.13.0"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.2"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.3.6"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.5.0"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.12.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.10.2"
]
]
},
{
"name": "pydantic-core",
"specs": [
[
"==",
"2.27.1"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "pyflakes",
"specs": [
[
"==",
"3.2.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.3.3"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
"==",
"0.24.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
"==",
"3.14.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "sniffio",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "starlette",
"specs": [
[
"==",
"0.41.3"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.2.3"
]
]
},
{
"name": "uvicorn",
"specs": [
[
"==",
"0.32.1"
]
]
}
],
"lcname": "messaging-py-sdk"
}
JSON
