python-termii 0.1.0__py3-none-any.whl

python_termii-0.1.0.dist-info/METADATA

@@ -0,0 +1,388 @@
+Metadata-Version: 2.4
+Name: python-termii
+Version: 0.1.0
+Summary: A clean Python SDK for the Termii API (SMS, Voice, and OTP)
+Author-email: Samuel Doghor Destiny <labs@amdoghor.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/samdoghor/python-termii
+Project-URL: Repository, https://github.com/samdoghor/python-termii
+Keywords: termii,whatsapp,sms,otp,sdk,python,library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+Dynamic: license-file
+
+# python-termii
+
+A clean and lightweight Python SDK for [Termii](https://termii.com) — send SMS, WhatsApp messages, manage phonebooks,
+contacts, campaigns, and more.
+
+[![PyPI version](https://img.shields.io/pypi/v/python-termii)](https://pypi.org/project/python-termii/)
+[![Python](https://img.shields.io/pypi/pyversions/python-termii)](https://pypi.org/project/python-termii/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Development Status](https://img.shields.io/badge/status-alpha-orange)](https://pypi.org/project/python-termii/)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Services](#services)
+    - [Sender ID](#sender-id)
+    - [Messaging](#messaging)
+    - [Number](#number)
+    - [Template](#template)
+    - [Phonebook](#phonebook)
+    - [Contact](#contact)
+    - [Campaign](#campaign)
+- [Error Handling](#error-handling)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+pip install python-termii
+```
+
+---
+
+## Configuration
+
+Initialize the client with your API key and base URL. Both can be passed directly or loaded from environment variables.
+
+```python
+from termii_py import TermiiClient
+
+# Pass credentials directly
+client = TermiiClient(api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL")
+
+# Or set environment variables and call with no arguments
+client = TermiiClient()
+```
+
+**Using a `.env` file (recommended):**
+
+```env
+TERMII_API_KEY=your_api_key
+TERMII_BASE_URL=your_base_url
+```
+
+```python
+from termii_py import TermiiClient
+
+client = TermiiClient()
+```
+
+> Get your API key and base URL from your [Termii dashboard](https://app.termii.com). A `ClientConfigError` is raised if
+> either value is missing.
+
+---
+
+## Services
+
+All services are available as attributes on the `TermiiClient` instance.
+
+### Sender ID
+
+**Fetch sender IDs** — optionally filter by name or status:
+
+```python
+# Fetch all
+client.sender_id.fetch_id()
+
+# Filter by name or status
+client.sender_id.fetch_id(name="MyBrand", status="approved")
+```
+
+**Request a new sender ID:**
+
+```python
+client.sender_id.request_id(
+    sender_id="MyBrand",
+    usecase="Transactional alerts for order confirmations",
+    company="Acme Ltd"
+)
+```
+
+---
+
+### Messaging
+
+**Send a single SMS:**
+
+```python
+client.message.send_message(
+    sent_to="2348012345678",
+    sent_from="MyBrand",
+    message="Your order has been confirmed.",
+    channel="generic",  # "generic", "dnd", or "voice"
+    type="plain"
+)
+```
+
+> For voice channel, `type` must be `"voice"`. WhatsApp messages must use `send_whatsapp_message()`.
+
+**Send a WhatsApp message:**
+
+```python
+# Text only
+client.message.send_whatsapp_message(
+    sent_to="2348012345678",
+    sent_from="MyBrand",
+    message="Hello! Your appointment is confirmed."
+)
+
+# With media attachment
+client.message.send_whatsapp_message(
+    sent_to="2348012345678",
+    sent_from="MyBrand",
+    message="Here is your receipt.",
+    url="https://example.com/receipt.pdf",
+    caption="Receipt - March 2025"
+)
+```
+
+**Send a bulk SMS:**
+
+```python
+client.message.send_bulk_message(
+    sent_to=["2348012345678", "2349087654321"],
+    sent_from="MyBrand",
+    message="Our sale starts today!",
+    channel="generic",  # "generic" or "dnd" only
+    type="plain"
+)
+```
+
+> Voice and WhatsApp are not supported for bulk messaging.
+
+---
+
+### Number
+
+Send a message directly to a phone number without a sender ID:
+
+```python
+client.number.send_message(
+    sent_to="2348012345678",
+    message="Your verification code is 123456."
+)
+```
+
+---
+
+### Template
+
+Send a message using a pre-approved WhatsApp template:
+
+```python
+# Text template
+client.template.send_message(
+    sent_to="2348012345678",
+    device_id="your-device-id",
+    template_id="your-template-id",
+    data={"studname": "Victor", "average": "30"}
+)
+
+# Media template (url and caption must be provided together)
+client.template.send_message(
+    sent_to="2348012345678",
+    device_id="your-device-id",
+    template_id="your-template-id",
+    data={"name": "Victor"},
+    url="https://example.com/document.pdf",
+    caption="Course Result"
+)
+```
+
+> `device_id` is found on the Manage Device page of your Termii dashboard.
+
+---
+
+### Phonebook
+
+**Fetch all phonebooks:**
+
+```python
+client.phonebook.fetch_phonebooks()
+```
+
+**Create a phonebook:**
+
+```python
+client.phonebook.create_phonebooks(
+    phonebook_name="Newsletter Subscribers",
+    description="Users opted in for weekly updates"
+)
+```
+
+**Update a phonebook:**
+
+```python
+client.phonebook.update_phonebook(
+    phonebook_id="abc123",
+    phonebook_name="VIP Customers",
+    description="High-value customer segment"
+)
+```
+
+**Delete a phonebook:**
+
+```python
+client.phonebook.delete_phonebook(phonebook_id="abc123")
+```
+
+---
+
+### Contact
+
+**Fetch contacts in a phonebook:**
+
+```python
+client.contact.fetch_contacts(phonebook_id="abc123")
+```
+
+**Add a single contact:**
+
+```python
+client.contact.create_contact(
+    phonebook_id="abc123",
+    phone_number="8012345678",
+    country_code="234",  # No leading "+"
+    first_name="Ada",
+    last_name="Obi",
+    email_address="ada@example.com",
+    company="Acme Ltd"
+)
+```
+
+**Add multiple contacts via CSV upload:**
+
+```python
+client.contact.create_multiple_contacts(
+    phonebook_id="abc123",
+    country_code="234",  # No leading "+"
+    file_path="/path/to/contacts.csv"
+)
+```
+
+**Delete all contacts in a phonebook:**
+
+```python
+client.contact.delete_contact(phonebook_id="abc123")
+```
+
+> ⚠️ `delete_contact` removes **all** contacts in the specified phonebook. Use with caution.
+
+---
+
+### Campaign
+
+**Send a campaign:**
+
+```python
+# Send immediately
+client.campaign.send_campaign(
+    country_code="234",  # No leading "+"
+    sender_id="MyBrand",  # 3–11 characters
+    message="Big sale — ends tonight!",
+    message_type="plain",  # "plain" or "unicode"
+    phonebook_id="abc123",
+    enable_link_tracking=False,
+    campaign_type="promotional",
+    schedule_sms_status="regular",  # "regular" or "scheduled"
+    channel="dnd"  # "dnd" or "generic"
+)
+
+# Schedule for later
+client.campaign.send_campaign(
+    country_code="234",
+    sender_id="MyBrand",
+    message="Your monthly statement is ready.",
+    message_type="plain",
+    phonebook_id="abc123",
+    enable_link_tracking=True,
+    campaign_type="transactional",
+    schedule_sms_status="scheduled",
+    schedule_time="2025-12-31T23:59:00Z",  # Required when schedule_sms_status is "scheduled"
+    channel="dnd"
+)
+```
+
+**Fetch all campaigns:**
+
+```python
+client.campaign.fetch_campaigns()
+```
+
+**Fetch a specific campaign's history:**
+
+```python
+client.campaign.fetch_campaign_history(campaign_id="camp_xyz")
+```
+
+**Retry a failed campaign:**
+
+```python
+client.campaign.retry_campaign(campaign_id="camp_xyz")
+```
+
+---
+
+## Error Handling
+
+The SDK validates inputs before making any network call and raises `ValueError` for invalid parameters. Wrap calls
+accordingly:
+
+```python
+try:
+    response = client.message.send_message(
+        sent_to="2348012345678",
+        sent_from="MyBrand",
+        message="Hello!",
+        channel="generic",
+        type="plain"
+    )
+except ValueError as e:
+    print(f"Validation error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+---
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Commit your changes: `git commit -m "feat: describe your change"`
+4. Push: `git push origin feature/your-feature`
+5. Open a Pull Request
+
+Please open an issue first for significant changes.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+Built by [Samuel Doghor](https://github.com/samdoghor) · Powered by the [Termii API](https://developer.termii.com)

python_termii-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+python_termii-0.1.0.dist-info/licenses/LICENSE,sha256=b7acqh5qV1IWkKNwyZRWTytZ7eFj2_5UG1m8e178Rb8,1091
+termii_py/__init__.py,sha256=371P5uXNLQcBi8uLGiWQphteTbWDqPU0jco8uQDswtk,388
+termii_py/client.py,sha256=2OoyRENsMF2ebKqTJR9eb9wCNx8zOalwrMPwP_7wDyY,2609
+termii_py/config.py,sha256=sIJFELvqthOAcO4kQ3wcXUvwa5UTS_2zta1w9ATHCWE,314
+termii_py/http/__init__.py,sha256=dNBPmB1ay13NOhIusHq4F0fyo7NyXtyYPM2jLUNb_Zo,416
+termii_py/http/request_handler.py,sha256=qrCsMEHRwwHZW34ObVOplj6w1INaqrYnsUhgz2XMmos,6947
+termii_py/http/request_response.py,sha256=-YVjwBhRhqVkr91hZ-3WHavF75uRaJQPJNEHKrSMkXE,2108
+termii_py/services/__init__.py,sha256=g3yWvS79cBh2wgaSGg-urEiJK4O64uksjQxytepAA04,714
+termii_py/services/campaign.py,sha256=a-48qcZzaSebKYjyxB49lLuC1mJFm_7HfMWBdxpuAwg,10080
+termii_py/services/contact.py,sha256=5GNgRDyonSEZ-goy4ZJfYA1Qkqd64MqG2zvQA-OEM1g,9082
+termii_py/services/message.py,sha256=IbJS7P1nodoIrWjFtbbPE_wM1PENLnREY29pDMJUsQE,7919
+termii_py/services/number.py,sha256=xWqZhdgFGnxnZ-nv1DceZuE_-hUWadna7n07rPFJPms,2653
+termii_py/services/phonebook.py,sha256=bVAXaIVa_h3rrVdWj5Mr8ptt6tVkkVYkuT-YWlCZok4,6743
+termii_py/services/sender_id.py,sha256=SndQSAo0Ix1UsUeH92sxwAA_9kKiPF9uBz67SQSjyRs,2233
+termii_py/services/template.py,sha256=gGyA8qZLNrA4WIZ-Cb-hT7TjdjBUJhd-Gir9ZpQ3xzo,4000
+termii_py/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+termii_py/utils/exception.py,sha256=CMmjcp4dmvh3CjBpBNTux_h42_xpwmy3UWiGdYED-QQ,227
+termii_py/value_object/__init__.py,sha256=M6w20-8yAl4V_ufsAcyfng1xVnv3CWVsud_I5O_E7OA,51
+termii_py/value_object/phone_number.py,sha256=2GynZLKhQlzu0k6SyiYKO2aOaHvlBCghybYhLk8b4cY,2600
+python_termii-0.1.0.dist-info/METADATA,sha256=iBlvTUD0-Zafkp7mibYelk6cb_D83KtFWPLQMZ4s2iA,9178
+python_termii-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+python_termii-0.1.0.dist-info/top_level.txt,sha256=TwVUsl84CnJtPudsMuFpoXgw_D_8pfNyME8GMoqIxtw,10
+python_termii-0.1.0.dist-info/RECORD,,

python_termii-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_termii-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Samuel Doghor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_termii-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+termii_py

termii_py/__init__.py

@@ -0,0 +1,10 @@
+"""
+This module provides a client for interacting with the Termii API, which allows you to send SMS messages, manage
+contacts, and perform other communication-related tasks. The TermiiClient class encapsulates the functionality needed
+to make API requests and handle responses effectively.
+"""
+
+from .client import TermiiClient
+
+__all__ = ["TermiiClient"]
+__version__ = "0.1.0"

termii_py/client.py

@@ -0,0 +1,64 @@
+""" Termii API Client Module
+This module provides the main client interface for interacting with the Termii API.
+"""
+from termii_py import config
+from .http import RequestHandler
+from .services import CampaignService, \
+    ContactService, \
+    MessageService, \
+    NumberService, \
+    PhonebookService, \
+    SenderIDService, \
+    TemplateService
+from .utils.exception import ClientConfigError
+
+
+class TermiiClient:
+    """ This client provides access to various Termii services including sender ID management, messaging, and other
+    communication features.
+
+    Args:
+        api_key (str, optional): Your Termii API key. If not provided, will attempt to
+            read from TERMII_API_KEY environment variable.
+        base_url (str, optional): The Termii API base URL. If not provided, will attempt
+            to read from TERMII_BASE_URL environment variable.
+
+    Raises:
+        TermiiConfigError: If api_key or base_url is not provided and cannot be found
+            in environment variables.
+
+    Attributes:
+        api_key (str): The API key used for authentication.
+        base_url (str): The base URL for API requests.
+
+    Example:
+        Using args in Termii Client (api_key & base_url):
+            ``client = TermiiClient(api_key="your_api_key", base_url="your_base_url")``
+
+        Or using environment variables (TERMII_API_KEY & TERMII_BASE_URL):
+            ``client = TermiiClient()``
+    """
+
+    def __init__(self, api_key: str = None, base_url: str = None):
+        self.api_key = api_key or config.TERMII_API_KEY
+        self.base_url = base_url or config.TERMII_BASE_URL
+        self.http = RequestHandler(self.api_key, self.base_url)
+        self.sender_id = SenderIDService(self.http)
+        self.message = MessageService(self.http)
+        self.number = NumberService(self.http)
+        self.template = TemplateService(self.http)
+        self.phonebook = PhonebookService(self.http)
+        self.contact = ContactService(self.http)
+        self.campaign = CampaignService(self.http)
+
+        if not self.api_key:
+            raise ClientConfigError(
+                "Missing TERMII_API_KEY. Provide via api_key parameter or TERMII_API_KEY environment variable. "
+                "Get your API key at: https://app.termii.com/"
+            )
+
+        if not self.base_url:
+            raise ClientConfigError(
+                "Missing TERMII_BASE_URL. Provide via base_url parameter or TERMII_BASE_URL environment variable. "
+                "Get your base url at: https://app.termii.com/"
+            )

termii_py/config.py

@@ -0,0 +1,12 @@
+"""
+Environment variable loader for Termii API settings.
+Loads environment variables from a .env file and sets up Termii API configuration.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+TERMII_API_KEY: str = os.getenv("TERMII_API_KEY")
+TERMII_BASE_URL: str = os.getenv("TERMII_BASE_URL")

termii_py/http/__init__.py

@@ -0,0 +1,8 @@
+"""
+This module contains the HTTP request handler and response classes for the Termii Python SDK. The RequestHandler class
+is responsible for making HTTP requests to the Termii API, while the RequestResponse class encapsulates the response
+received from the API, including status code, headers, and body content.
+"""
+
+from .request_handler import RequestHandler
+from .request_response import RequestResponse

termii_py/http/request_handler.py

@@ -0,0 +1,141 @@
+"""
+RequestHandler class for interacting with the Termii API.
+Classes:
+    RequestHandler
+Methods:
+    fetch: Sends a GET request to the Termii API.
+    post: Sends a POST request to the Termii API.
+"""
+import requests
+
+from .request_response import RequestResponse
+
+
+class RequestHandler:
+    """
+    Initializes a RequestHandler instance.
+
+    Attributes:
+        api_key (str): The API key for authentication.
+        base_url (str): The base URL of the Termii API.
+    """
+
+    def __init__(self, api_key, base_url):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def fetch(self, endpoint, params=None):
+        """
+       Sends a GET request to the Termii API.
+
+        Args:
+            endpoint (str): The endpoint to query.
+            params (dict, optional): Query parameters. Defaults to None.
+
+        Returns:
+            RequestResponse: The response from the API.
+        """
+
+        params = params or {}
+        params["api_key"] = self.api_key
+        response = requests.get(f"{self.base_url}{endpoint}", params=params)
+
+        return RequestResponse.handle_response(response)
+
+    def post(self, endpoint, json: dict):
+        """
+        Sends a POST request to the Termii API.
+
+        Args:
+            endpoint (str): The endpoint to query.
+            json (dict): The JSON payload.
+
+        Returns:
+            RequestResponse: The response from the API.
+        """
+
+        json["api_key"] = self.api_key
+        response = requests.post(f"{self.base_url}{endpoint}", json=json)
+
+        return RequestResponse.handle_response(response)
+
+    def patch(self, endpoint, json: dict):
+        """
+        Sends a PATCH request to the Termii API. This method is used for updating existing resources on the Termii platform.
+        The `endpoint` parameter specifies the API endpoint to which the request will be sent, while the `json`
+        parameter contains the data to be updated in JSON format. The method automatically includes the API key for
+        authentication in the request payload. The response from the API is processed and returned as a
+        `RequestResponse` object, which encapsulates the status and data of the API response.
+
+        Args:
+            endpoint (str): The API endpoint to which the PATCH request will be sent (e.g., "/api/phonebooks/{phonebook_id}").
+            json (dict): A dictionary containing the data to be updated, which will be sent as a JSON payload in the
+            request body. This should include the fields that need to be updated along with their new values.
+
+        Returns:
+            RequestResponse: An object representing the response from the Termii API, which includes the status code,
+            response data, and any relevant metadata. The `RequestResponse` class is responsible for handling the
+            parsing and interpretation of the API response, allowing for consistent error handling and data extraction
+            across different API endpoints.
+        """
+
+        json["api_key"] = self.api_key
+        response = requests.patch(f"{self.base_url}{endpoint}", json=json)
+
+        return RequestResponse.handle_response(response)
+
+    def delete(self, endpoint, params=None):
+        """
+        Sends a DELETE request to the Termii API. This method is used for deleting resources from the Termii platform.
+        The `endpoint` parameter specifies the API endpoint to which the request will be sent, while the `params`
+        parameter contains any query parameters that need to be included in the request URL. The method automatically
+        includes the API key for authentication in the query parameters. The response from the API is processed and
+        returned as a `RequestResponse` object, which encapsulates the status and data of the API response.
+
+        Args:
+            endpoint (str): The API endpoint to which the DELETE request will be sent (e.g., "/api/phonebooks/{phonebook_id}").
+            params (dict, optional): A dictionary of query parameters to be included in the request URL. This can include
+            any additional parameters required by the API endpoint, such as filters or identifiers. If no parameters are needed, this can be left as None.
+
+        Returns:
+            RequestResponse: An object representing the response from the Termii API, which includes the status code,
+            response data, and any relevant metadata. The `RequestResponse` class is responsible for handling the
+            parsing and interpretation of the API response, allowing for consistent error handling and data extraction
+            across different API endpoints.
+        """
+
+        params = params or {}
+        params["api_key"] = self.api_key
+        response = requests.delete(f"{self.base_url}{endpoint}", params=params)
+
+        return RequestResponse.handle_response(response)
+
+    def post_file(self, endpoint, file_path: str, data: dict):
+        """
+        Sends a POST request to the Termii API with a file upload. This method is used for endpoints that require file
+        uploads, such as creating multiple contacts from a CSV file. The `endpoint` parameter specifies the API
+        endpoint to which the request will be sent, while the `file_path` parameter specifies the local path to the
+        file that needs to be uploaded. The `data` parameter contains any additional form data that needs to be
+        included in the request body. The method automatically includes the API key for authentication in the form
+        data. The response from the API is processed and returned as a `RequestResponse` object, which encapsulates
+        the status and data of the API response.
+
+        Args:
+            endpoint (str): The API endpoint to which the POST request will be sent (e.g., "/api/contacts/upload").
+            file_path (str): The local file path of the file to be uploaded (e.g., "C:/path/to/contacts.csv").
+            data (dict): A dictionary containing any additional form data to be included in the request body. This can include
+            fields such as "country_code" or "phonebook_id" that are required by the API endpoint.
+
+        Returns:
+            RequestResponse: An object representing the response from the Termii API, which includes the status code,
+            response data, and any relevant metadata. The `RequestResponse` class is responsible for handling the
+            parsing and interpretation of the API response, allowing for consistent error handling and data extraction
+            across different API endpoints.
+        """
+
+        data["api_key"] = self.api_key
+
+        files = {"file": open(file_path, "rb")}
+        response = requests.post(f"{self.base_url}{endpoint}", files=files, data=data)
+
+        return RequestResponse.handle_response(response)