python-termii 0.1.0__py3-none-any.whl

termii_py/services/number.py

@@ -0,0 +1,75 @@
+"""
+This module defines the `NumberService` class, which provides functionality for sending messages
+directly to a phone number through Termii's Number Messaging API.
+
+The service validates the recipient’s phone number format before dispatching messages
+and uses the provided `RequestHandler` instance to make HTTP requests to the Termii API.
+
+References:
+    - https://developer.termii.com/number
+"""
+
+from termii_py.http import RequestHandler
+from termii_py.value_object import PhoneNumber
+
+
+class NumberService:
+    """
+    Provides functionality for sending messages to individual phone numbers
+    using Termii’s Number Messaging API endpoint.
+
+    This class ensures that phone numbers are properly validated before
+    sending and abstracts the HTTP request handling via the injected `RequestHandler`.
+
+    Attributes:
+        http (RequestHandler): The HTTP request handler instance used to communicate
+            with Termii’s API endpoints.
+
+    References:
+        - https://developer.termii.com/number#:~:text=Join%20Loop-,Number%20API,-This%20API%20allows
+    """
+
+    def __init__(self, http: RequestHandler):
+        """
+     Initializes the `NumberService` with an HTTP client for API communication.
+
+        Args:
+            http (RequestHandler): The request handler responsible for making
+                authenticated HTTP requests to Termii’s API.
+
+        References:
+            - https://developer.termii.com/number#:~:text=Join%20Loop-,Number%20API,-This%20API%20allows
+        """
+
+        self.http = http
+
+    def send_message(self, sent_to: str, message: str):
+        """
+        Sends an SMS message directly to a specific phone number using Termii’s
+        Number Messaging API endpoint.
+
+        This method validates the provided phone number using the `PhoneNumber`
+        value object before constructing the payload and dispatching the message.
+
+        Args:
+            sent_to (str): The recipient’s phone number in international format (e.g., "2348012345678").
+            message (str): The text message to send.
+
+        Raises:
+            ValueError: If the provided phone number is invalid.
+
+        Returns:
+            dict: The JSON response returned by the Termii API.
+
+        References:
+            - https://developer.termii.com/number#:~:text=to%20customers%20location.-,Send%20Message,-Endpoint%20%3A%20https
+        """
+
+        PhoneNumber(sent_to)
+
+        payload = {
+            "to": sent_to,
+            "sms": message,
+        }
+
+        return self.http.post("/api/sms/number/send", json=payload)

termii_py/services/phonebook.py

@@ -0,0 +1,137 @@
+"""
+This module defines the PhonebookService class, which provides methods to interact with Termii's phonebook API
+endpoints. It allows users to fetch, create, update, and delete phonebooks through the Termii API. Each method
+corresponds to a specific API endpoint and handles the necessary HTTP requests and payloads.
+
+References:
+    - https://developer.termii.com/phonebook
+
+Classes:
+    PhonebookService: A service class that provides methods to manage phonebooks via Termii's API.
+"""
+from termii_py.http import RequestHandler
+
+
+class PhonebookService:
+    """
+    Provides methods to manage phonebooks through Termii's API.
+
+    The class includes methods to fetch all phonebooks, create a new phonebook, update an existing phonebook, and
+    delete a phonebook. Each method constructs the appropriate API request and handles the response.
+
+    Attributes:
+        http (object): An HTTP client instance responsible for making API requests to Termii.
+
+    """
+
+    def __init__(self, http: RequestHandler):
+        """
+        Initializes the PhonebookService instance.
+
+            Args:
+                http (object): An HTTP client instance (e.g., `requests.Session`) used to perform
+                    network requests to the Termii API.
+        """
+
+        self.http = http
+
+    def fetch_phonebooks(self):
+        """
+            Fetches all phonebooks associated with the authenticated Termii account.
+            This method sends a GET request to the `/api/phonebooks` endpoint and returns the response containing the list of phonebooks.
+
+            Raise:
+                ValueError: If the API request fails or returns an error response.
+
+            Returns:
+                A response object containing the list of phonebooks and associated metadata.
+
+            References:
+                - https://developer.termii.com/phonebook#fetch-phonebooks:~:text=phonebooks%20as%20needed.-,Fetch%20Phonebooks,-This%20endpoint%20returns
+
+        """
+
+        return self.http.fetch("/api/phonebooks")
+
+    def create_phonebooks(self, phonebook_name: str, description: str = None):
+        """
+            Creates a new phonebook with the specified name and optional description.
+
+            This method sends a POST request to the `/api/phonebooks` endpoint with the provided phonebook name and description in the request body.
+
+            Args:
+                phonebook_name (str): The name of the phonebook to be created. This field is required.
+                description (str, optional): A brief description of the phonebook. This field is optional and can be left blank.
+
+            Raise:
+                ValueError: If the `phonebook_name` parameter is not provided or is empty. This field is required to create a phonebook.
+
+            Returns:
+                A response object containing the details of the newly created phonebook, including its unique identifier and any associated metadata.
+
+            References:
+                - https://developer.termii.com/phonebook#create--a-phonebook:~:text=12%2C%0A%20%20%22empty%22%3A%20false%0A%7D-,Create%20a%20Phonebook,-This%20endpoint%20creates
+        """
+
+        payload = {
+            "phonebook_name": phonebook_name,
+            "description": description,
+        }
+
+        return self.http.post("/api/phonebooks", json=payload)
+
+    def update_phonebook(self, phonebook_id, phonebook_name: str, description: str):
+        """
+            Updates the details of an existing phonebook identified by its unique ID.
+            This method sends a PATCH request to the `/api/phonebooks/{phonebook_id}` endpoint with the updated phonebook name and description in the request body.
+
+            Args:
+                    phonebook_id (str): The unique identifier of the phonebook to be updated. This field is required to specify which phonebook to update.
+                    phonebook_name (str): The new name for the phonebook. This field is required to update the phonebook's name.
+                    description (str): The new description for the phonebook. This field is required to update the phonebook's description.
+
+            Raise:
+                    ValueError: If the `phonebook_id` parameter is not provided or is empty. This field is required to
+                    identify which phonebook to update. Additionally, if either the `phonebook_name` or `description`
+                    parameters are not provided or are empty, a ValueError will be raised since both fields are
+                    required to update the phonebook's details.
+
+            Returns:
+                    A response object containing the updated details of the phonebook, including its unique identifier, new name, new description, and any associated metadata.
+
+            References:
+                    - https://developer.termii.com/phonebook#update-phonebook:~:text=successfully%22%2C%0A%20%20%20%20%22status%22%3A%20%22success%22%0A%20%20%7D-,Update%20Phonebook,-This%20endpoint%20updates
+        """
+
+        if not phonebook_id:
+            raise ValueError("phonebook_id is required to update a phonebook.")
+
+        payload = {
+            "phonebook_name": phonebook_name,
+            "description": description,
+        }
+
+        return self.http.patch(f"/api/phonebooks/{phonebook_id}", json=payload)
+
+    def delete_phonebook(self, phonebook_id):
+        """
+            Deletes an existing phonebook identified by its unique ID.
+            This method sends a DELETE request to the `/api/phonebooks/{phonebook_id}` endpoint to remove the specified phonebook from the Termii account. Once deleted, the phonebook and all associated contacts will be permanently removed.
+
+            Args:
+                    phonebook_id (str): The unique identifier of the phonebook to be deleted. This field is required to specify which phonebook to delete.
+
+            Raise:
+                    ValueError: If the `phonebook_id` parameter is not provided or is empty. This field is required to identify which phonebook to delete.
+
+            Returns:
+                    A response object indicating the success or failure of the delete operation, including any relevant status messages or error details.
+
+            References:
+                    - https://developer.termii.com/phonebook#delete-phonebook:~:text=0%2C%0A%20%20%20%20%20%20%22numberOfCampaigns%22%3A%200%0A%20%20%7D-,Delete%20phonebook,-This%20endpoint%20deletes
+        """
+
+        if not phonebook_id:
+            raise ValueError("phonebook_id is required to delete a phonebook.")
+
+        return self.http.delete(f"/api/phonebooks/{phonebook_id}")

termii_py/services/sender_id.py

@@ -0,0 +1,78 @@
+"""
+SenderIDService class for managing sender IDs.
+Classes:
+    SenderIDService
+Methods:
+    fetch_id: Retrieves a list of sender IDs based on query parameters.
+    request_id: Requests a new sender ID.
+"""
+from termii_py.http import RequestHandler
+
+
+class SenderIDService:
+    """
+    Provides methods for interacting with sender IDs.
+
+    Attributes:
+        http: An instance of the HTTP client.
+
+    References:
+        https://developer.termii.com/sender-id
+    """
+
+    def __init__(self, http: RequestHandler):
+        """
+        Initializes a SenderIDService instance.
+
+        Args:
+            http: An instance of the HTTP client.
+        """
+
+        self.http = http
+
+    def fetch_id(self, name: str = None, status: str = None):
+        """
+        Retrieves a list of sender IDs based on query parameters.
+
+        Args:
+            name (str, optional): The name of the sender ID. Defaults to None.
+            status (str, optional): The status of the sender ID. Defaults to None.
+
+        Returns:
+            The response from the API.
+
+        References:
+            https://developer.termii.com/sender-id#:~:text=request%20methods%2C%20respectively.-,Fetch%20Sender%20ID,-The%20Fetch%20Sender
+        """
+
+        params = {}
+        if name:
+            params["name"] = name
+
+        if status:
+            params["status"] = status
+
+        return self.http.fetch("/api/sender-id", params=params)
+
+    def request_id(self, sender_id: str, usecase: str, company: str):
+        """
+        Requests a new sender ID.
+
+        Args:
+            sender_id (str): The desired sender ID.
+            usecase (str): The use case for the sender ID.
+            company (str): The company name.
+
+        References:
+            https://developer.termii.com/sender-id#:~:text=5%2C%0A%20%20%20%20%22empty%22%3A%20false%0A%7D-,Request%20Sender%20ID,-The%20Request%20Sender
+        Returns:
+            The response from the API.
+        """
+
+        payload = {
+            "sender_id": sender_id,
+            "usecase": usecase,
+            "company": company
+        }
+
+        return self.http.post("/api/sender-id/request", json=payload)

termii_py/services/template.py

@@ -0,0 +1,99 @@
+"""
+This module defines the `TemplateService` class, which provides functionality for sending messages
+using predefined templates via Termii's Template Messaging API.
+
+The service validates the recipient’s phone number format before dispatching messages
+and uses the provided HTTP client instance to make requests to the Termii API.
+
+References:
+    - https://developer.termii.com/templates
+
+Classes:
+    TemplateService: Handles message dispatch operations via Termii's Template Messaging API.
+"""
+from termii_py.http import RequestHandler
+from termii_py.value_object import PhoneNumber
+
+
+class TemplateService:
+    """
+    Provides methods for sending messages using predefined templates via Termii's Template Messaging API.
+
+    The class ensures data validation before making HTTP requests to the API. Each method constructs the appropriate
+    request payload and sends it using the injected HTTP client.
+
+    Attributes:
+        http: An instance of the HTTP client.
+    """
+
+    def __init__(self, http: RequestHandler):
+        """
+        Initializes a SenderIDService instance.
+
+        Args:
+            http: An instance of the HTTP client.
+        """
+
+        self.http = http
+
+    def send_message(self, sent_to: str, device_id: str, template_id: str, data: dict, caption: str = None,
+                     url: str = None):
+        """
+
+        Sends a message using a predefined template via Termii's Template Messaging API.
+
+        Args:
+            sent_to (str): The recipient’s phone number in international format. e.g., "2348012345678".
+            device_id (str): The device ID associated with the template.
+                                (Represents the Device ID for Whatsapp. It can be Alphanumeric. It should be passed
+                                when the message is sent via whatsapp (It can be found on the manage device page on
+                                your Termii dashboard))
+            template_id (str): The ID of the message template to use.
+            data (dict): A dictionary containing placeholder values to populate the template.
+                        Represents the variables used in your WhatsApp template. These key-value pairs will dynamically
+                        populate the placeholders in your approved template message. You can find the required keys for
+                         each template on the Device Subscription page of your dashboard.
+                        (Example: {"studname": "Victor", "average": "30" })
+            caption (str, optional): The caption for the media (if sending media). Defaults to None.
+            url (str, optional): The URL of the media to send (if sending media). Defaults to None.
+
+        Raises:
+            ValueError: If the provided phone number is invalid.
+
+        Returns:
+            dict: The JSON response returned by the Termii API.
+
+        References:
+            https://developer.termii.com/templates
+
+        """
+
+        if caption is not None and url is None:
+            raise ValueError("If caption is provided, url must also be provided to send media.")
+
+        if caption is None and url is not None:
+            raise ValueError("If url is provided, caption must also be provided to send media.")
+
+        endpoint = "/api/send/template"
+
+        PhoneNumber(sent_to)
+
+        if not isinstance(data, dict):
+            raise ValueError("The 'data' parameter must be a dictionary containing template placeholder values.")
+
+        payload = {
+            "phone_number": sent_to,
+            "device_id": device_id,
+            "template_id": template_id,
+            "data": data,
+        }
+
+        if caption is not None and url is not None:
+            endpoint = "/api/send/template/media"
+
+            payload['media'] = {
+                "caption": caption,
+                "url": url
+            }
+
+        return self.http.post(endpoint, json=payload)

termii_py/utils/exception.py

@@ -0,0 +1,11 @@
+"""
+Custom exception class for Termii client configuration errors.
+Classes:
+    ClientConfigError
+"""
+
+
+class ClientConfigError(Exception):
+    """Raised when Termii configuration is invalid or missing."""
+    pass
+

termii_py/value_object/__init__.py

@@ -0,0 +1,5 @@
+"""
+
+"""
+
+from .phone_number import PhoneNumber

termii_py/value_object/phone_number.py

@@ -0,0 +1,74 @@
+"""
+This module defines the `PhoneNumber` value object, responsible for validating and encapsulating
+a properly formatted Nigerian phone number (MSISDN format).
+
+It ensures that phone numbers conform to the international dialing format beginning with
+Nigeria’s country code `234`, followed by 10 digits.
+
+Example:
+    >>> PhoneNumber("2348031234567")
+    <PhoneNumber: 2348031234567>
+
+Classes:
+    PhoneNumber: Represents a validated phone number conforming to Termii’s expected format.
+"""
+import re
+
+
+class PhoneNumber:
+    """
+    Represents and validates a phone number in international (MSISDN) format.
+
+    This class enforces that all phone numbers begin with the Nigerian country code `234`
+    and are followed by exactly 10 digits, ensuring compatibility with Termii's messaging API
+    and other telecom standards.
+
+    Attributes:
+        phone_number (str): The validated phone number string in MSISDN format.
+
+    Raises:
+        ValueError: If the provided phone number does not match the expected format.
+    """
+
+    def __init__(self, phone_number: str):
+        """
+         Initializes a new `PhoneNumber` instance after validating its format.
+
+        Args:
+            phone_number (str): A phone number string in MSISDN format (e.g., "2348031234567").
+
+        Raises:
+            ValueError: If the provided phone number is invalid or not in the expected format.
+
+        Example:
+            >>> valid = PhoneNumber("2349012345678")
+            >>> invalid = PhoneNumber("09012345678")  # Raises ValueError
+        """
+        if not self.is_valid_phone_number(phone_number):
+            raise ValueError(f"Invalid phone number: {phone_number}")
+        self.phone_number = phone_number
+
+    @staticmethod
+    def is_valid_phone_number(phone_number) -> bool:
+        """
+        Validates whether the given string is a valid Nigerian phone number in MSISDN format.
+
+        A valid phone number must:
+            - Begin with "234" (Nigeria's country code)
+            - Contain exactly 13 digits total (234 + 10 digits)
+            - Contain only numeric characters
+
+        Args:
+            phone_number (str): The phone number string to validate.
+
+        Returns:
+            bool: True if the phone number is valid, False otherwise.
+
+        Example:
+            >>> PhoneNumber.is_valid_phone_number("2348023456789")
+            True
+            >>> PhoneNumber.is_valid_phone_number("08023456789")
+            False
+        """
+
+        return bool(re.match(r"^234\d{10}$", phone_number))