python-termii 0.1.0__py3-none-any.whl

termii_py/http/request_response.py

@@ -0,0 +1,64 @@
+"""
+RequestResponse class for handling API responses.
+Classes:
+    RequestResponse
+Methods:
+    handle_response: Processes an HTTP response and returns a RequestResponse instance.
+"""
+from hmac import compare_digest
+
+
+class RequestResponse:
+    """
+    Represents a standardized API response.
+
+    Attributes:
+        status_code (int): The HTTP status code of the response.
+        status (str): A string indicating the status of the response (e.g., "ok" or "error").
+        message (str | dict): The response message, which can be a string or a dictionary.
+    """
+
+    def __init__(self, status_code: int, status, message: str | dict):
+        """
+        Initializes a RequestResponse instance.
+
+        Args:
+            status_code (int): The HTTP status code of the response.
+            status (str): A string indicating the status of the response.
+            message (str | dict): The response message.
+        """
+        self.status_code = status_code
+        self.status = status
+        self.message = message
+
+    @staticmethod
+    def handle_response(response):
+        """
+        Processes an HTTP response and returns a RequestResponse instance.
+
+        Args:
+            response: The HTTP response object.
+
+        Returns:
+            RequestResponse: An instance representing the API response.
+
+        Notes:
+            This method checks the HTTP status code of the response and returns a RequestResponse instance with a
+            standardized status and message.
+        """
+
+        if compare_digest(str(response.status_code), "200") or compare_digest(str(response.status_code), "201"):
+            return RequestResponse(
+                status_code=response.status_code,
+                status="ok",
+                message=response.text
+            )
+
+        if not compare_digest(str(response.status_code), "200"):
+            return RequestResponse(
+                status_code=response.status_code,
+                status="error",
+                message=response.text
+            )
+
+        return None

termii_py/services/__init__.py

@@ -0,0 +1,14 @@
+"""
+This module contains the service classes for interacting with the Termii API. Each service class corresponds to a
+specific aspect of the Termii platform, such as managing campaigns, contacts, messages, numbers, phonebooks, sender IDs,
+and templates. These classes provide methods to perform various operations related to their respective domains,
+allowing users to easily integrate Termii's functionality into their applications.
+"""
+
+from .campaign import CampaignService
+from .contact import ContactService
+from .message import MessageService
+from .number import NumberService
+from .phonebook import PhonebookService
+from .sender_id import SenderIDService
+from .template import TemplateService

termii_py/services/campaign.py

@@ -0,0 +1,175 @@
+"""
+This module provides the CampaignService class, which allows you to send SMS campaigns, fetch campaign details, and
+retry failed campaigns using the Termii API. The service includes methods to send campaigns with various options such
+as scheduling, link tracking, and channel selection. It also provides functionality to retrieve campaign history and
+ retry campaigns that may have failed.
+
+References:
+    - https://developer.termii.com/campaign
+
+Classes:
+    CampaignService: A service class that provides methods to manage SMS campaigns via Termii's API
+"""
+from termii_py.http import RequestHandler
+
+
+class CampaignService:
+    """
+    Provides methods to manage SMS campaigns through Termii's API. The class includes methods to send SMS campaigns
+    with various options, fetch campaign details, and retry failed campaigns. 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 CampaignService instance. This constructor takes an HTTP client instance as an argument, which
+        is used to perform network requests to the Termii API.
+
+        Args:
+            http (object): An HTTP client instance (e.g., `requests.Session`) used to perform network requests to the Termii API.
+        """
+
+        self.http = http
+
+    def send_campaign(self, country_code: str, sender_id: str, message: str, message_type: str, phonebook_id: str,
+                      enable_link_tracking: bool, campaign_type: str, schedule_sms_status: str,
+                      schedule_time: str = None, channel: str = "dnd"):
+        """
+            Sends an SMS campaign using the Termii API. This method constructs a payload with the provided parameters
+            and sends a POST request to the `/api/sms/campaigns/send` endpoint. The method includes validation for the
+            input parameters to ensure they meet the required criteria before making the API call.
+
+            Args:
+                country_code (str): The country code for the recipients of the campaign (e.g., "234" for Nigeria).
+                sender_id (str): The sender ID to be displayed on the recipient's device (must be between 3 and 11 characters).
+                message (str): The content of the SMS message to be sent in the campaign.
+                message_type (str): The type of message, either "plain" for standard text or "unicode" for messages containing special characters.
+                phonebook_id (str): The unique identifier of the phonebook containing the recipients of the campaign.
+                enable_link_tracking (bool): A flag indicating whether link tracking should be enabled for the campaign.
+                campaign_type (str): The type of campaign, which can be "promotional" or "transactional".
+                schedule_sms_status (str): The scheduling status of the campaign, either "scheduled" for campaigns that should be sent at a later time or "regular" for immediate sending.
+                schedule_time (str, optional): The scheduled time for the campaign to be sent, required if `schedule_sms_status` is "scheduled". The format should be in ISO 8601 (e.g., "2024-12-31T23:59:00Z").
+                channel (str, optional): The channel through which the campaign should be sent, either "dnd" for Do Not Disturb compliant messages or "generic" for standard messages. Default is "dnd".
+
+            Raises:
+                ValueError: If any of the input parameters do not meet the required criteria (e.g., invalid country code,
+                sender ID length, message type, campaign type, scheduling status, or missing schedule time when required).
+
+            Returns:
+                A response object containing the result of the campaign send operation, including status and any relevant metadata
+
+            References:
+                - https://developer.termii.com/campaign#:~:text=a%20specified%20phonebook.-,Send%20a%20campaign,-This%20endpoint%20allows
+        """
+
+        if country_code.startswith("+"):
+            raise ValueError("country code should not start with '+' sign.")
+
+        if len(sender_id) < 3 or len(sender_id) > 11:
+            raise ValueError("sender id should be between 3 and 11 characters.")
+
+        if message_type not in ["plain", "unicode"]:
+            raise ValueError("message type should be either 'plain' or 'unicode'.")
+
+        if channel not in ["dnd", "generic"]:
+            raise ValueError("channel should be either 'dnd' or 'generic'.")
+
+        if schedule_sms_status not in ["scheduled", "regular"]:
+            raise ValueError("schedule sms status should be either 'scheduled' or 'regular'.")
+
+        if schedule_sms_status == "scheduled" and not schedule_time:
+            raise ValueError("schedule time is required when schedule sms status is 'scheduled'.")
+
+        payload = {
+            "country_code": country_code,
+            "sender_id": sender_id,
+            "message": message,
+            "message_type": message_type,
+            "phonebook_id": phonebook_id,
+            "enable_link_tracking": enable_link_tracking,
+            "campaign_type": campaign_type,
+            "schedule_sms_status": schedule_sms_status,
+            "schedule_time": schedule_time,
+            "channel": channel,
+            "remove_duplicate": "yes",
+            "delimiter": ","
+        }
+
+        return self.http.post("/api/sms/campaigns/send", payload)
+
+    def fetch_campaigns(self):
+        """
+            Fetches a list of all SMS campaigns that have been sent or are scheduled to be sent using the Termii
+            API. This method sends a GET request to the `/api/sms/campaigns` endpoint and retrieves the campaign
+            history, including details such as campaign ID, status, message content, recipient information, and
+            scheduling details. The response will contain an array of campaign objects, each representing a
+            specific campaign with its associated metadata.
+
+            Returns:
+                A response object containing a list of SMS campaigns, including details such as campaign ID, status,
+                message content, recipient information, and scheduling details.
+
+            References:
+                - https://developer.termii.com/campaign#fetch-campaigns:~:text=C714360330258%22%2C%0A%20%20%20%20%22status%22%3A%20%22success%22%0A%20%20%7D-,Fetch%20campaigns,-This%20endpoint%20retrieves
+        """
+
+        return self.http.fetch("/api/sms/campaigns")
+
+    def fetch_campaign_history(self, campaign_id: str):
+        """
+            Fetches the details of a specific SMS campaign using its unique identifier (campaign ID). This method sends
+            a GET request to the `/api/sms/campaigns/{campaign_id}` endpoint, where `{campaign_id}` is the unique
+            identifier of the campaign whose details you want to retrieve. The response will contain comprehensive
+            information about the specified campaign, including its status, message content, recipient
+            information, scheduling details, and any relevant metadata.
+
+            Args:
+                campaign_id (str): The unique identifier of the SMS campaign for which to fetch details. This ID is
+                typically returned when a campaign is created or can be obtained from the list of campaigns.
+
+            Raises:
+                ValueError: If the `campaign_id` is not provided or is invalid. The campaign ID is required to fetch
+                the details of a specific campaign, and it must be a valid identifier that exists in the system.
+
+            Returns:
+                A response object containing the details of the specified SMS campaign, including its status, message
+                content, recipient information, scheduling details, and any relevant metadata.
+        """
+
+        if not campaign_id:
+            raise ValueError("campaign id is required")
+
+        return self.http.fetch(f"/api/sms/campaigns/{campaign_id}")
+
+    def retry_campaign(self, campaign_id: str):
+        """
+            Retries a specific SMS campaign that may have failed or encountered issues during its initial sending attempt.
+            This method sends a PATCH request to the `/api/sms/campaigns/{campaign_id}` endpoint, where `{campaign_id}`
+            is the unique identifier of the campaign you wish to retry. The response will indicate whether the retry
+            attempt was successful and may include updated campaign details or status information. This functionality
+            is useful for campaigns that may have failed due to temporary issues such as network errors or recipient
+            device problems, allowing you to attempt sending the campaign again without having to create a new one.
+
+            Args:
+                campaign_id (str): The unique identifier of the SMS campaign that you want to retry. This ID is typically
+                returned when a campaign is created or can be obtained from the list of campaigns. It must be a valid
+                identifier corresponding to an existing campaign in the system.
+
+            Raises:
+                ValueError: If the `campaign_id` is not provided or is invalid. The campaign ID is required to identify
+                which campaign to retry, and it must be a valid identifier that exists in the system.
+
+            Returns:
+                A response object indicating the result of the retry attempt, including whether it was successful and
+                any relevant details about the campaign's updated status or information.
+        """
+
+        if not campaign_id:
+            raise ValueError("campaign id is required")
+
+        payload = {}
+
+        return self.http.patch(f"/api/sms/campaigns/{campaign_id}", json=payload)

termii_py/services/contact.py

@@ -0,0 +1,167 @@
+"""
+This module provides the ContactService class, which allows you to manage contacts within a phonebook. You can fetch
+existing contacts, create new contacts (individually or in bulk), and delete contacts from a specified phonebook.
+The service interacts with the Termii API to perform these operations.
+
+References:
+    - https://developer.termii.com/contacts
+
+Classes:
+    ContactService: A service class that provides methods to manage contacts within a phonebook via Termii's API.
+"""
+from termii_py.http import RequestHandler
+
+
+class ContactService:
+    """
+    Provides methods to manage contacts within a phonebook through Termii's API.
+    The class includes methods to fetch contacts, create new contacts (individually or in bulk), and delete contacts from a specified 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 ContactService 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_contacts(self, phonebook_id: str):
+        """
+            Fetches all contacts associated with a specific phonebook. This method sends a GET request to
+            the `/api/phonebooks/{phonebook_id}/contacts` endpoint, where `{phonebook_id}` is the unique identifier of
+            the phonebook whose contacts you want to retrieve. The response will contain a list of contacts along with
+            their details.
+
+            Args:
+                phonebook_id (str): The unique identifier of the phonebook for which to fetch contacts.
+
+            Raises:
+                ValueError: If the `phonebook_id` is not provided or is invalid.
+
+            Returns:
+                A response object containing the list of contacts and associated metadata for the specified phonebook.
+
+            References:
+                - https://developer.termii.com/contacts#:~:text=within%20your%20phonebooks.-,Fetch%20contacts%20by%20phonebook%20ID,-This%20endpoint%20retrieves
+        """
+
+        if not phonebook_id:
+            raise ValueError("phonebook_id is required")
+
+        return self.http.fetch(f"/api/phonebooks/{phonebook_id}/contacts")
+
+    def create_contact(self, phonebook_id, phone_number: str, country_code: str, email_address: str = None,
+                       first_name: str = None, last_name: str = None, company: str = None):
+        """
+            Creates a new contact within a specified phonebook. This method sends a POST request to
+            the `/api/phonebooks/{phonebook_id}/contacts` endpoint, where `{phonebook_id}` is the unique identifier of
+            the phonebook to which the contact will be added. The request body should include the contact's
+            phone number, country code, and optionally their email address, first name, last name, and company. The
+            response will contain the details of the newly created contact.
+
+            Args:
+                phonebook_id (str): The unique identifier of the phonebook to which the contact will be added.
+                phone_number (str): The contact's phone number (without the country code).
+                country_code (str): The country code for the contact's phone number (without the '+' sign).
+                email_address (str, optional): The contact's email address. This field is optional.
+                first_name (str, optional): The contact's first name. This field is optional.
+                last_name (str, optional): The contact's last name. This field is optional.
+                company (str, optional): The contact's company name. This field is optional.
+
+            Raises:
+                ValueError: If the `phonebook_id` is not provided or is invalid.
+                ValueError: If the `country_code` starts with a '+' sign. The country code should be provided without the '+' sign.
+
+            Returns:
+                A response object containing the details of the newly created contact, including its unique identifier and any associated metadata.
+
+            References:
+                - https://developer.termii.com/contacts#add-single-contacts-to-phonebook:~:text=12%2C%0A%20%20%20%20%22empty%22%3A%20false%0A%20%20%7D%0A%7D-,Add%20single%20contacts%20to%20phonebook,-This%20endpoint%20allows
+        """
+
+        if not phonebook_id:
+            raise ValueError("phonebook_id is required")
+
+        if country_code.startswith("+"):
+            raise ValueError("country code should not start with '+' sign.")
+
+        payload = {
+            "phone_number": phone_number,
+            "country_code": country_code,
+            "email_address": email_address,
+            "first_name": first_name,
+            "last_name": last_name,
+            "company": company,
+        }
+
+        return self.http.post(f"/api/phonebooks/{phonebook_id}/contacts", json=payload)
+
+    def create_multiple_contacts(self, phonebook_id, country_code: str, file_path: str, ):
+        """
+            Creates multiple contacts in bulk by uploading a CSV file containing the contact details. This method sends
+            a POST request to the `/api/phonebooks/contacts/upload` endpoint with the specified phonebook ID, country
+            code, and file path. The CSV file should be formatted according to Termii's requirements, with columns for
+            phone number, email address, first name, last name, and company. The response will indicate the success or
+            failure of the bulk upload operation.
+
+            Args:
+                phonebook_id (str): The unique identifier of the phonebook to which the contacts will be added.
+                country_code (str): The country code for the contacts' phone numbers (without the '+' sign).
+                file_path (str): The file path to the CSV file containing the contact details to be uploaded.
+
+            Raises:
+                ValueError: If the `phonebook_id` is not provided or is invalid.
+                ValueError: If the `country_code` starts with a '+' sign. The country code should be provided without the '+' sign.
+                ValueError: If the `file_path` is not provided or is invalid. The file path must point to a valid CSV file containing the contact details.
+
+            Returns:
+                A response object indicating the success or failure of the bulk contact upload operation, along with any relevant metadata or error messages.
+
+            References:
+                - https://developer.termii.com/contacts#add-single-contacts-to-phonebook:~:text=Promise%22%2C%0A%20%20%20%20%22last_name%22%3A%20%22John%22%0A%20%20%7D%0A%7D-,Add%20multiple%20contacts%20to%20phonebook,-This%20endpoint%20allows
+        """
+
+        if not phonebook_id:
+            raise ValueError("phonebook_id is required")
+
+        if country_code.startswith("+"):
+            raise ValueError("country code should not start with '+' sign.")
+
+        data = {
+            "phonebook_id": phonebook_id,
+            "country_code": country_code,
+        }
+
+        return self.http.post_file(f"/api/phonebooks/contacts/upload", data=data, file_path=file_path)
+
+    def delete_contact(self, phonebook_id):
+        """
+            Deletes all contacts associated with a specific phonebook. This method sends a DELETE request to the
+            `/api/phonebooks/{phonebook_id}/contacts` endpoint, where `{phonebook_id}` is the unique identifier of the
+            phonebook from which to delete contacts. The response will indicate the success or failure of the delete
+            operation. Note that this action will remove all contacts from the specified phonebook, so use it with
+            caution.
+
+            Args:
+                phonebook_id (str): The unique identifier of the phonebook from which to delete contacts.
+
+            Raises:
+                ValueError: If the `phonebook_id` is not provided or is invalid. The `phonebook_id` is required to identify which phonebook's contacts should be deleted.
+
+            Returns:
+                A response object indicating the success or failure of the delete operation, along with any relevant metadata or error messages. The response may include information about the number of contacts deleted or any issues encountered during the process.
+
+            References:
+                - https://developer.termii.com/contacts#add-single-contacts-to-phonebook:~:text=get%20it%20done.%22%0A%20%20%7D-,Delete%20Contact%20in%20a%20Phonebook,-This%20endpoint%20allows
+        """
+
+        if not phonebook_id:
+            raise ValueError("phonebook_id is required to delete contacts.")
+
+        return self.http.delete(f"/api/phonebooks/{phonebook_id}/contacts")

termii_py/services/message.py

@@ -0,0 +1,191 @@
+"""
+This module defines the `MessageService` class, which provides an interface for sending messages
+through Termii's Messaging API.
+
+It supports sending single SMS messages, WhatsApp messages, and bulk messages while ensuring
+parameter validation and correct channel-type combinations before making HTTP requests to the API.
+
+References:
+    - https://developer.termii.com/messaging-api
+
+Classes:
+    MessageService: Handles message dispatch operations via Termii's Messaging API.
+"""
+
+from hmac import compare_digest
+
+from termii_py.http import RequestHandler
+from termii_py.value_object import PhoneNumber
+
+
+class MessageService:
+    """
+    Provides methods for sending SMS, WhatsApp, and bulk messages via Termii's Messaging API.
+
+    The class ensures data validation and enforces correct message channel and type usage.
+    Each method constructs the appropriate request payload and sends it using the injected
+    HTTP client.
+
+    Attributes:
+        http (object): An HTTP client instance responsible for making API requests.
+    """
+
+    def __init__(self, http: RequestHandler):
+        """
+        Initializes the MessageService 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 send_message(self, sent_to: str, sent_from: str, message: str, channel: str, type: str):
+        """
+        Sends a single SMS message through Termii's Messaging API.
+
+        This method supports the following channels:
+        - "generic" (for standard messaging)
+        - "dnd" (for messages that bypass Do-Not-Disturb filters)
+        - "voice" (for voice call messages)
+
+        Notes:
+            - WhatsApp messages must be sent using `send_whatsapp_message()`.
+            - For voice messages, the `type` parameter must explicitly be set to "voice".
+
+        Args:
+            sent_to (str): Recipient’s phone number in international format.
+            sent_from (str): The sender ID registered on Termii.
+            message (str): The content of the message to be sent.
+            channel (str): The communication channel. Must be one of ["generic", "dnd", "voice"].
+            type (str): The message type (e.g., "plain", "voice").
+
+        Raises:
+            ValueError: If an invalid channel-type combination is provided.
+            ValueError: If attempting to send WhatsApp messages via this method.
+            ValueError: If `channel` or `type` parameters are invalid.
+
+        Returns:
+            dict: The JSON response returned by the Termii API.
+
+        References:
+            https://developer.termii.com/messaging-api#:~:text=Send%20message
+        """
+
+        PhoneNumber(sent_to)
+
+        if compare_digest("whatsapp", str(channel).strip().lower()):
+            raise ValueError("For WhatsApp messages, please use the 'send_whatsapp_message' method.")
+
+        if compare_digest("voice", str(channel).strip().lower()) and not compare_digest("voice",
+                                                                                        str(type).strip().lower()):
+            raise ValueError("For voice channel, the 'type' parameter must be set to 'voice'.")
+
+        if not compare_digest("generic", str(channel).strip().lower()) and not compare_digest("dnd",
+                                                                                              str(channel).strip().lower() or not compare_digest(
+                                                                                                  "voice",
+                                                                                                  str(channel).strip().lower())):
+            raise ValueError("The 'channel' parameter must be either 'generic' or 'dnd' or voice.")
+
+        payload = {
+            "to": sent_to,
+            "from": sent_from,
+            "sms": message,
+            "channel": channel,
+            "type": type
+        }
+
+        return self.http.post("/api/sms/send", json=payload)
+
+    def send_whatsapp_message(self, sent_to: str, sent_from: str, message: str, url: str = None, caption: str = None):
+        """
+       Sends a WhatsApp message through Termii's Messaging API.
+
+        This endpoint supports text-only and media messages (e.g., image or document links).
+
+        Args:
+            sent_to (str): Recipient’s phone number in international format.
+            sent_from (str): The sender ID or WhatsApp business number.
+            message (str): Text message to be sent.
+            url (str, optional): Media URL for attachments (image, document, etc.).
+            caption (str, optional): Caption for the media file (if applicable).
+
+        Raises:
+            ValueError: If the recipient phone number is invalid.
+
+        Returns:
+            dict: The JSON response from the Termii API.
+
+        References:
+            https://developer.termii.com/messaging-api#:~:text=Send%20WhatsApp%20Message%20(Conversational)
+       """
+
+        PhoneNumber(sent_to)
+
+        payload = {
+            "to": sent_to,
+            "from": sent_from,
+            "sms": message,
+            "channel": "whatsapp",
+            "type": "plain",
+            "media": {
+                "url": url,
+                "caption": caption,
+            }
+        }
+
+        return self.http.post("/api/sms/send", json=payload)
+
+    def send_bulk_message(self, sent_to: list, sent_from: str, message: str, channel: str, type: str):
+        """
+        Sends bulk SMS messages to multiple recipients using Termii's Messaging API.
+
+        This method supports sending to multiple phone numbers in one request. Only the "generic"
+        and "dnd" channels are supported for bulk operations.
+
+        Notes:
+            - Voice and WhatsApp messages cannot be sent in bulk.
+            - Each recipient number is validated before sending.
+
+        Args:
+            sent_to (list): A list of recipient phone numbers in international format.
+            sent_from (str): The sender ID registered on Termii.
+            message (str): The content of the message to be sent.
+            channel (str): The message channel. Must be either "generic" or "dnd".
+            type (str): The message type (e.g., "plain").
+
+        Raises:
+            ValueError: If any recipient number is invalid.
+            ValueError: If attempting to send WhatsApp or voice messages in bulk.
+            ValueError: If an invalid channel is specified.
+
+        Returns:
+            dict: The JSON response returned by the Termii API.
+
+        References:
+            https://developer.termii.com/messaging-api#:~:text=Send%20Bulk%20message
+        """
+
+        for x in sent_to:
+            PhoneNumber(x)
+
+        if compare_digest("whatsapp", str(channel).strip().lower()):
+            raise ValueError("For WhatsApp messages, please use the 'send_whatsapp_message' method.")
+
+        if compare_digest("voice", str(channel).strip().lower()) or compare_digest("voice", str(type).strip().lower()):
+            raise ValueError("Voice messages are not supported in bulk messaging.")
+
+        if not compare_digest("generic", str(channel).strip().lower()) and not compare_digest("dnd",
+                                                                                              str(channel).strip().lower()):
+            raise ValueError("The 'channel' parameter must be either 'generic' or 'dnd' or voice.")
+
+        payload = {
+            "to": sent_to,
+            "from": sent_from,
+            "sms": message,
+            "channel": channel,
+            "type": type
+        }
+
+        return self.http.post("/api/sms/send/bulk", json=payload)