kibonet-python-sdk 0.1.0__py3-none-any.whl

kibonet_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: kibonet-python-sdk
+Version: 0.1.0
+Summary: Simple, secure Python SDK for the KiboNet SMS Gateway
+Author-email: Jackson Linus <jacksonlinus95@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JAXPARROW/kibonet-python-sdk
+Project-URL: Repository, https://github.com/JAXPARROW/kibonet-python-sdk.git
+Project-URL: Issues, https://github.com/JAXPARROW/kibonet-python-sdk/issues
+Keywords: kibonet,sms,tanzania,africa,messaging,httpx,async
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# KiboNet Python SDK
+
+Simple, secure Python SDK for the [KiboNet SMS Gateway](https://sms.kibonet.co.tz).  
+Supports both **synchronous** and **async** usage via [httpx](https://www.python-httpx.org/).
+
+[![PyPI version](https://img.shields.io/pypi/v/kibonet-python-sdk)](https://pypi.org/project/kibonet-python-sdk/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/kibonet-python-sdk)](https://pypi.org/project/kibonet-python-sdk/)
+[![License: MIT](https://img.shields.io/pypi/l/kibonet-python-sdk)](https://pypi.org/project/kibonet-python-sdk/)
+
+## Features
+
+- **Send SMS** to one or multiple recipients (comma-separated contacts)
+- **Delivery reports** retrieved by `shootId`
+- **Balance check** for your SMS credits
+- **Health check** — `is_healthy()` never raises, perfect for monitoring probes
+- **Async support** — full `async`/`await` via `AsyncKiboNetClient`
+- **httpx** under the hood — connection pooling, automatic retries, TLS verification
+- **Phone number validation** — auto-converts `0XXXXXXXXX` → `255XXXXXXXXX`
+- **Typed exceptions** — catch exactly what you need
+- **Context manager** support (both sync and async)
+- **No credentials in code** — load from environment variables
+
+## Installation
+
+```bash
+pip install kibonet-python-sdk
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from kibonet_sdk import KiboNetClient
+
+with KiboNetClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET") as client:
+    # Health check
+    if client.is_healthy():
+        print("API is up!")
+
+    # Send SMS
+    resp = client.send_sms(
+        sender_id="MyBrand",
+        message="Hello from KiboNet!",
+        contacts=["255712345678", "255798765432"],
+        delivery_report_url="https://myserver.com/delivery-callback",  # optional
+    )
+    print(f"Shoot ID: {resp['data']['shootId']}")
+    print(f"Valid: {resp['data']['validContacts']}")
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from kibonet_sdk import AsyncKiboNetClient
+
+async def main():
+    async with AsyncKiboNetClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET") as client:
+        if await client.is_healthy():
+            resp = await client.send_sms(
+                sender_id="MyBrand",
+                message="Hello async!",
+                contacts="255712345678",
+            )
+            print(resp["data"]["shootId"])
+
+asyncio.run(main())
+```
+
+## All Methods
+
+Both `KiboNetClient` and `AsyncKiboNetClient` expose the same interface:
+
+### `send_sms`
+
+```python
+resp = client.send_sms(
+    sender_id="MyBrand",        # Sender name shown to recipient
+    message="Your OTP is 1234", # SMS text
+    contacts=[                  # Single string, list, or CSV string
+        "255712345678",
+        "255798765432",
+    ],
+    delivery_report_url="https://myserver.com/callback",  # optional
+    message_type="text",        # currently only "text" is supported
+)
+
+# Response
+print(resp["data"]["shootId"])          # Use this for delivery reports
+print(resp["data"]["validContacts"])    # int
+print(resp["data"]["invalidContacts"])  # int
+print(resp["data"]["duplicatedContacts"])
+print(resp["data"]["messageSize"])      # character count
+```
+
+### `get_delivery_report`
+
+```python
+report = client.get_delivery_report("abcd1234-5678-efgh-9012-ijklmnopqrst")
+
+for record in report["data"]:
+    print(record["mobile"])      # 255712345678
+    print(record["status"])      # Delivered / Failed / Buffered
+    print(record["statusCode"])  # 000
+    print(record["sentAt"])      # "07-02-2024 07:35:08"
+```
+
+### `get_balance`
+
+```python
+result = client.get_balance()
+print(result["data"]["totalSms"])  # e.g. 30
+```
+
+### `is_healthy`
+
+```python
+if client.is_healthy():
+    print("API is reachable and credentials are valid")
+```
+
+## Phone Number Formats
+
+The SDK automatically normalises phone numbers:
+
+| Input format       | Stored as      |
+|--------------------|----------------|
+| `0712345678`       | `255712345678` |
+| `+255712345678`    | `255712345678` |
+| `255712345678`     | `255712345678` |
+
+## Error Handling
+
+```python
+from kibonet_sdk import KiboNetClient
+from kibonet_sdk.exceptions import (
+    KiboNetAuthenticationError,
+    KiboNetValidationError,
+    KiboNetRateLimitError,
+    KiboNetInsufficientBalanceError,
+    KiboNetConnectionError,
+    KiboNetServerError,
+    KiboNetAPIError,
+    KiboNetError,        # base — catch everything SDK-related
+)
+
+client = KiboNetClient(api_key="...", api_secret="...")
+
+try:
+    client.send_sms(sender_id="X", message="Hi", contacts="255712345678")
+except KiboNetAuthenticationError:
+    print("Bad credentials")
+except KiboNetValidationError as e:
+    print(f"Input error: {e}")
+except KiboNetRateLimitError:
+    print("Slow down — rate limited")
+except KiboNetConnectionError as e:
+    print(f"Network error: {e}")
+except KiboNetServerError as e:
+    print(f"KiboNet server problem: {e}")
+except KiboNetAPIError as e:
+    print(f"API error (code={e.code}): {e}")
+```
+
+## Environment Variables
+
+Keep credentials out of source code:
+
+```bash
+export KIBONET_API_KEY="your_api_key"
+export KIBONET_API_SECRET="your_api_secret"
+```
+
+```python
+import os
+from kibonet_sdk import KiboNetClient
+
+client = KiboNetClient(
+    api_key=os.environ["KIBONET_API_KEY"],
+    api_secret=os.environ["KIBONET_API_SECRET"],
+)
+```
+
+## Constructor Options
+
+```python
+KiboNetClient(
+    api_key: str,          # Required — from KiboNet portal
+    api_secret: str,       # Required — from KiboNet portal
+    timeout: float = 30.0, # Per-request timeout in seconds
+    max_retries: int = 3,  # Automatic retries on transient failures
+    logger=None,           # Optional logging.Logger
+)
+```
+
+`AsyncKiboNetClient` takes the same parameters.
+
+## Logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+client = KiboNetClient(api_key="...", api_secret="...")
+# All HTTP calls are logged at DEBUG level
+```
+
+## Development
+
+```bash
+git clone https://github.com/JAXPARROW/kibonet-python-sdk.git
+cd kibonet-python-sdk
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=kibonet_sdk --cov-report=term-missing
+
+# Build
+python -m build
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributors
+
+- **Jackson Linus** — Creator and maintainer

kibonet_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kibonet_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=iURnGbrOhoQubmqcORxyMl5RlR_uiiXwgrQC7m_mpCo,1070
+kibonet_sdk/__init__.py,sha256=N96hQ3EHlVEoqGoSjFKPNsi02fqUGxagWhQWhO-8swY,1539
+kibonet_sdk/async_client.py,sha256=RUyeR70YwnwcVfOK1_7tlipFg8tuZXu1hfHPDuY0DsA,8290
+kibonet_sdk/client.py,sha256=2bPsLGbhkCbbnREvRZC7eBLk_c82IWbpkqDpsM_hk0w,9610
+kibonet_sdk/exceptions.py,sha256=ijqq0awLmGlB6a5mipSQmTIGIa590Oxktmb3Muncg2o,1134
+kibonet_sdk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kibonet_sdk/utils/async_http_client.py,sha256=pShPDmVmt00Bo4_uG0LBv_4pI15N0liSWchKZQnI-sg,3357
+kibonet_sdk/utils/http_client.py,sha256=hnM1LfHMLJkNgGOZfjh3h7KcP2YA1AYWdXkLQSw7B84,3304
+kibonet_sdk/utils/validators.py,sha256=hTOtk0uVVwPip3gncnE_We4sFF-YD_2-jcUuSE97WKA,3138
+kibonet_python_sdk-0.1.0.dist-info/METADATA,sha256=BiilOrTNOTtpAqaUWu6XpgXLyy2ygAHS_H6Uxl7fIOM,7843
+kibonet_python_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+kibonet_python_sdk-0.1.0.dist-info/top_level.txt,sha256=EkSeCWl3t36U6xJyaOPj0Zm_leyv4lAlxN1KQ5uxVBc,12
+kibonet_python_sdk-0.1.0.dist-info/RECORD,,

kibonet_python_sdk-0.1.0.dist-info/WHEEL

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

kibonet_python_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jackson Linus
+
+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.

kibonet_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kibonet_sdk

kibonet_sdk/__init__.py

@@ -0,0 +1,61 @@
+"""
+KiboNet Python SDK — simple, secure SMS gateway client for Python.
+
+Quickstart (sync)::
+
+    from kibonet_sdk import KiboNetClient
+
+    with KiboNetClient(api_key="YOUR_KEY", api_secret="YOUR_SECRET") as client:
+        resp = client.send_sms(
+            sender_id="MyBrand",
+            message="Hello from KiboNet!",
+            contacts=["255712345678"],
+        )
+        print(resp["data"]["shootId"])
+
+Quickstart (async)::
+
+    import asyncio
+    from kibonet_sdk import AsyncKiboNetClient
+
+    async def main():
+        async with AsyncKiboNetClient(api_key="YOUR_KEY", api_secret="YOUR_SECRET") as client:
+            resp = await client.send_sms(
+                sender_id="MyBrand",
+                message="Hello async!",
+                contacts=["255712345678"],
+            )
+            print(resp["data"]["shootId"])
+
+    asyncio.run(main())
+"""
+
+from .client import KiboNetClient
+from .async_client import AsyncKiboNetClient
+from .exceptions import (
+    KiboNetError,
+    KiboNetAuthenticationError,
+    KiboNetValidationError,
+    KiboNetAPIError,
+    KiboNetRateLimitError,
+    KiboNetInsufficientBalanceError,
+    KiboNetConnectionError,
+    KiboNetServerError,
+)
+
+__all__ = [
+    # Clients
+    "KiboNetClient",
+    "AsyncKiboNetClient",
+    # Exceptions
+    "KiboNetError",
+    "KiboNetAuthenticationError",
+    "KiboNetValidationError",
+    "KiboNetAPIError",
+    "KiboNetRateLimitError",
+    "KiboNetInsufficientBalanceError",
+    "KiboNetConnectionError",
+    "KiboNetServerError",
+]
+
+__version__ = "0.1.0"

kibonet_sdk/async_client.py

@@ -0,0 +1,238 @@
+"""
+Asynchronous KiboNet SMS client.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    KiboNetAPIError,
+    KiboNetAuthenticationError,
+    KiboNetConnectionError,
+    KiboNetRateLimitError,
+    KiboNetServerError,
+    KiboNetValidationError,
+)
+from .utils.async_http_client import AsyncHTTPClient
+from .utils.validators import PhoneNumberValidator
+
+
+_SEND_ENDPOINT = "api/v1/vendor/message/send"
+_DELIVER_ENDPOINT = "api/v1/vendor/message/deliver/{shoot_id}"
+_BALANCE_ENDPOINT = "api/v1/vendor/message/balance"
+
+
+class AsyncKiboNetClient:
+    """
+    Asynchronous client for the KiboNet SMS API.
+
+    Supports the same operations as :class:`~kibonet_sdk.KiboNetClient` but
+    exposes a fully ``async``/``await`` interface powered by *httpx*.
+
+    Example::
+
+        import asyncio
+        from kibonet_sdk import AsyncKiboNetClient
+
+        async def main():
+            async with AsyncKiboNetClient(api_key="...", api_secret="...") as client:
+                if await client.is_healthy():
+                    resp = await client.send_sms(
+                        sender_id="MyBrand",
+                        message="Hello async!",
+                        contacts=["255712345678"],
+                    )
+                    print(resp["data"]["shootId"])
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        logger: Optional[logging.Logger] = None,
+    ):
+        """
+        Initialise the KiboNet asynchronous client.
+
+        Args:
+            api_key: API key from the KiboNet portal.
+            api_secret: API secret from the KiboNet portal.
+            timeout: Per-request timeout in seconds (default 30).
+            max_retries: Number of automatic retries on transient errors (default 3).
+            logger: Optional custom :class:`logging.Logger`.
+        """
+        if not api_key or not isinstance(api_key, str):
+            raise KiboNetValidationError("api_key must be a non-empty string")
+        if not api_secret or not isinstance(api_secret, str):
+            raise KiboNetValidationError("api_secret must be a non-empty string")
+
+        self.logger = logger or logging.getLogger(__name__)
+        self._http = AsyncHTTPClient(
+            api_key=api_key,
+            api_secret=api_secret,
+            timeout=timeout,
+            max_retries=max_retries,
+            logger=self.logger,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def is_healthy(self) -> bool:
+        """
+        Asynchronously check whether the KiboNet API is reachable.
+
+        Never raises — always returns a boolean.
+
+        Returns:
+            ``True`` if the API responds with HTTP 200, ``False`` otherwise.
+        """
+        try:
+            response = await self._http.request(
+                "GET", _BALANCE_ENDPOINT, timeout=5.0
+            )
+            return response.status_code == 200
+        except Exception:
+            return False
+
+    async def send_sms(
+        self,
+        sender_id: str,
+        message: str,
+        contacts: Union[str, List[str]],
+        delivery_report_url: str = "",
+        message_type: str = "text",
+    ) -> Dict[str, Any]:
+        """
+        Asynchronously send a text SMS to one or more recipients.
+
+        Args:
+            sender_id: Sender name/ID displayed to recipients.
+            message: Text content of the SMS.
+            contacts: A single phone number, a list of phone numbers, or an
+                      already comma-separated string.
+            delivery_report_url: Optional callback URL for delivery status.
+            message_type: Message type — currently only ``"text"`` is supported.
+
+        Returns:
+            Parsed API response dict (same structure as the sync version).
+
+        Raises:
+            KiboNetValidationError: Invalid input.
+            KiboNetAuthenticationError: Invalid credentials.
+            KiboNetRateLimitError: Rate limit exceeded.
+            KiboNetServerError: KiboNet server error.
+            KiboNetAPIError: Any other API-level error.
+            KiboNetConnectionError: Network failure.
+        """
+        if not sender_id or not isinstance(sender_id, str):
+            raise KiboNetValidationError("sender_id must be a non-empty string")
+        if not message or not isinstance(message, str):
+            raise KiboNetValidationError("message must be a non-empty string")
+
+        contacts_csv = PhoneNumberValidator.to_csv(contacts)
+
+        payload: Dict[str, Any] = {
+            "senderId": sender_id,
+            "messageType": message_type,
+            "message": message,
+            "contacts": contacts_csv,
+        }
+        if delivery_report_url:
+            payload["deliveryReportUrl"] = delivery_report_url
+
+        response = await self._http.request("POST", _SEND_ENDPOINT, json=payload)
+        return self._handle_response(response)
+
+    async def get_delivery_report(self, shoot_id: str) -> Dict[str, Any]:
+        """
+        Asynchronously retrieve delivery reports for a sent message.
+
+        Args:
+            shoot_id: The ``shootId`` returned by :meth:`send_sms`.
+
+        Returns:
+            Parsed API response dict (same structure as the sync version).
+
+        Raises:
+            KiboNetValidationError: If ``shoot_id`` is empty.
+            KiboNetAPIError: Any other API-level error.
+            KiboNetConnectionError: Network failure.
+        """
+        if not shoot_id or not isinstance(shoot_id, str):
+            raise KiboNetValidationError("shoot_id must be a non-empty string")
+
+        endpoint = _DELIVER_ENDPOINT.format(shoot_id=shoot_id)
+        response = await self._http.request("GET", endpoint)
+        return self._handle_response(response)
+
+    async def get_balance(self) -> Dict[str, Any]:
+        """
+        Asynchronously check the current SMS credit balance.
+
+        Returns:
+            Parsed API response dict (same structure as the sync version).
+
+        Raises:
+            KiboNetAuthenticationError: Invalid credentials.
+            KiboNetAPIError: Any other API-level error.
+            KiboNetConnectionError: Network failure.
+        """
+        response = await self._http.request("GET", _BALANCE_ENDPOINT)
+        return self._handle_response(response)
+
+    # ------------------------------------------------------------------
+    # Resource management
+    # ------------------------------------------------------------------
+
+    async def aclose(self) -> None:
+        """Close underlying HTTP connections and free resources."""
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.aclose()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        """Map HTTP / API error codes to SDK exceptions."""
+        if response.status_code == 401:
+            raise KiboNetAuthenticationError(
+                "Authentication failed — check your api_key and api_secret"
+            )
+        if response.status_code == 429:
+            raise KiboNetRateLimitError("Rate limit exceeded", code=429)
+        if 500 <= response.status_code < 600:
+            raise KiboNetServerError(
+                f"KiboNet server error (HTTP {response.status_code})",
+                code=response.status_code,
+            )
+
+        try:
+            data = response.json()
+        except Exception:
+            raise KiboNetAPIError(
+                f"Unexpected non-JSON response (HTTP {response.status_code}): "
+                f"{response.text[:200]}"
+            )
+
+        if response.status_code != 200 or not data.get("success", False):
+            raise KiboNetAPIError(
+                data.get("message", f"API error (HTTP {response.status_code})"),
+                code=data.get("code"),
+                response_data=data,
+            )
+
+        return data

kibonet_sdk/client.py

@@ -0,0 +1,279 @@
+"""
+Synchronous KiboNet SMS client.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    KiboNetAPIError,
+    KiboNetAuthenticationError,
+    KiboNetConnectionError,
+    KiboNetRateLimitError,
+    KiboNetServerError,
+    KiboNetValidationError,
+)
+from .utils.http_client import HTTPClient
+from .utils.validators import PhoneNumberValidator
+
+
+_SEND_ENDPOINT = "api/v1/vendor/message/send"
+_DELIVER_ENDPOINT = "api/v1/vendor/message/deliver/{shoot_id}"
+_BALANCE_ENDPOINT = "api/v1/vendor/message/balance"
+
+
+class KiboNetClient:
+    """
+    Synchronous client for the KiboNet SMS API.
+
+    Supports:
+    - Sending SMS to one or multiple recipients
+    - Retrieving delivery reports by shoot ID
+    - Checking your SMS balance
+    - Health-check via the balance endpoint
+
+    Example::
+
+        from kibonet_sdk import KiboNetClient
+
+        with KiboNetClient(api_key="...", api_secret="...") as client:
+            if client.is_healthy():
+                resp = client.send_sms(
+                    sender_id="MyBrand",
+                    message="Hello from KiboNet!",
+                    contacts=["255712345678", "255798765432"],
+                    delivery_report_url="https://myserver.com/delivery",
+                )
+                print(resp["data"]["shootId"])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        logger: Optional[logging.Logger] = None,
+    ):
+        """
+        Initialise the KiboNet synchronous client.
+
+        Args:
+            api_key: API key from the KiboNet portal.
+            api_secret: API secret from the KiboNet portal.
+            timeout: Per-request timeout in seconds (default 30).
+            max_retries: Number of automatic retries on transient errors (default 3).
+            logger: Optional custom :class:`logging.Logger`.
+        """
+        if not api_key or not isinstance(api_key, str):
+            raise KiboNetValidationError("api_key must be a non-empty string")
+        if not api_secret or not isinstance(api_secret, str):
+            raise KiboNetValidationError("api_secret must be a non-empty string")
+
+        self.logger = logger or logging.getLogger(__name__)
+        self._http = HTTPClient(
+            api_key=api_key,
+            api_secret=api_secret,
+            timeout=timeout,
+            max_retries=max_retries,
+            logger=self.logger,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def is_healthy(self) -> bool:
+        """
+        Check whether the KiboNet API is reachable and credentials are valid.
+
+        Never raises — always returns a boolean.  Suitable for liveness /
+        readiness probes in containerised deployments.
+
+        Returns:
+            ``True`` if the API responds with HTTP 200, ``False`` otherwise.
+        """
+        try:
+            response = self._http.request("GET", _BALANCE_ENDPOINT, timeout=5.0)
+            return response.status_code == 200
+        except Exception:
+            return False
+
+    def send_sms(
+        self,
+        sender_id: str,
+        message: str,
+        contacts: Union[str, List[str]],
+        delivery_report_url: str = "",
+        message_type: str = "text",
+    ) -> Dict[str, Any]:
+        """
+        Send a text SMS to one or more recipients.
+
+        Args:
+            sender_id: Sender name/ID displayed to recipients.
+            message: Text content of the SMS.
+            contacts: A single phone number, a list of phone numbers, or an
+                      already comma-separated string.
+            delivery_report_url: Optional callback URL for delivery status updates.
+            message_type: Message type — currently only ``"text"`` is supported.
+
+        Returns:
+            Parsed API response dict, e.g.::
+
+                {
+                    "code": 200,
+                    "data": {
+                        "validContacts": 2,
+                        "invalidContacts": 0,
+                        "duplicatedContacts": 0,
+                        "messageSize": 20,
+                        "message": "Hello!",
+                        "shootId": "abcd1234-…"
+                    },
+                    "success": True,
+                    "message": "Message submit"
+                }
+
+        Raises:
+            KiboNetValidationError: Invalid input parameters.
+            KiboNetAuthenticationError: Invalid credentials.
+            KiboNetRateLimitError: Rate limit exceeded.
+            KiboNetServerError: KiboNet server error.
+            KiboNetAPIError: Any other API-level error.
+            KiboNetConnectionError: Network failure.
+        """
+        if not sender_id or not isinstance(sender_id, str):
+            raise KiboNetValidationError("sender_id must be a non-empty string")
+        if not message or not isinstance(message, str):
+            raise KiboNetValidationError("message must be a non-empty string")
+
+        contacts_csv = PhoneNumberValidator.to_csv(contacts)
+
+        payload: Dict[str, Any] = {
+            "senderId": sender_id,
+            "messageType": message_type,
+            "message": message,
+            "contacts": contacts_csv,
+        }
+        if delivery_report_url:
+            payload["deliveryReportUrl"] = delivery_report_url
+
+        response = self._http.request("POST", _SEND_ENDPOINT, json=payload)
+        return self._handle_response(response)
+
+    def get_delivery_report(self, shoot_id: str) -> Dict[str, Any]:
+        """
+        Retrieve delivery status reports for a previously sent message.
+
+        Args:
+            shoot_id: The ``shootId`` returned by :meth:`send_sms`.
+
+        Returns:
+            Parsed API response dict, e.g.::
+
+                {
+                    "code": 200,
+                    "data": [
+                        {
+                            "message": "Hello!",
+                            "mobile": "255712345678",
+                            "senderId": "MyBrand",
+                            "status": "Delivered",
+                            "statusCode": "000",
+                            "explanation": "N/A",
+                            "messageType": "text",
+                            "sentAt": "07-02-2024 07:35:08"
+                        }
+                    ],
+                    "success": True,
+                    "message": "Sent messages report"
+                }
+
+        Raises:
+            KiboNetValidationError: If ``shoot_id`` is empty.
+            KiboNetAuthenticationError: Invalid credentials.
+            KiboNetAPIError: Any other API-level error.
+            KiboNetConnectionError: Network failure.
+        """
+        if not shoot_id or not isinstance(shoot_id, str):
+            raise KiboNetValidationError("shoot_id must be a non-empty string")
+
+        endpoint = _DELIVER_ENDPOINT.format(shoot_id=shoot_id)
+        response = self._http.request("GET", endpoint)
+        return self._handle_response(response)
+
+    def get_balance(self) -> Dict[str, Any]:
+        """
+        Check the current SMS credit balance for your account.
+
+        Returns:
+            Parsed API response dict, e.g.::
+
+                {
+                    "code": 200,
+                    "data": {"totalSms": 30},
+                    "success": True,
+                    "message": "Balance"
+                }
+
+        Raises:
+            KiboNetAuthenticationError: Invalid credentials.
+            KiboNetAPIError: Any other API-level error.
+            KiboNetConnectionError: Network failure.
+        """
+        response = self._http.request("GET", _BALANCE_ENDPOINT)
+        return self._handle_response(response)
+
+    # ------------------------------------------------------------------
+    # Resource management
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close underlying HTTP connections and free resources."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        """Map HTTP / API error codes to SDK exceptions."""
+        if response.status_code == 401:
+            raise KiboNetAuthenticationError(
+                "Authentication failed — check your api_key and api_secret"
+            )
+        if response.status_code == 429:
+            raise KiboNetRateLimitError(
+                "Rate limit exceeded", code=429
+            )
+        if 500 <= response.status_code < 600:
+            raise KiboNetServerError(
+                f"KiboNet server error (HTTP {response.status_code})",
+                code=response.status_code,
+            )
+
+        try:
+            data = response.json()
+        except Exception:
+            raise KiboNetAPIError(
+                f"Unexpected non-JSON response (HTTP {response.status_code}): "
+                f"{response.text[:200]}"
+            )
+
+        if response.status_code != 200 or not data.get("success", False):
+            raise KiboNetAPIError(
+                data.get("message", f"API error (HTTP {response.status_code})"),
+                code=data.get("code"),
+                response_data=data,
+            )
+
+        return data

kibonet_sdk/exceptions.py

@@ -0,0 +1,47 @@
+"""
+Custom exception hierarchy for KiboNet SMS SDK.
+All exceptions inherit from KiboNetError for easy catching.
+"""
+
+
+class KiboNetError(Exception):
+    """Base exception for all KiboNet SDK errors"""
+    pass
+
+
+class KiboNetAuthenticationError(KiboNetError):
+    """Invalid API key or secret (HTTP 401)"""
+    pass
+
+
+class KiboNetValidationError(KiboNetError):
+    """Input validation failed (e.g., invalid phone number, empty message)"""
+    pass
+
+
+class KiboNetAPIError(KiboNetError):
+    """API returned an error response"""
+    def __init__(self, message: str, code: int = None, response_data: dict = None):
+        super().__init__(message)
+        self.code = code
+        self.response_data = response_data or {}
+
+
+class KiboNetRateLimitError(KiboNetAPIError):
+    """Rate limit exceeded (HTTP 429)"""
+    pass
+
+
+class KiboNetInsufficientBalanceError(KiboNetAPIError):
+    """Not enough SMS credits"""
+    pass
+
+
+class KiboNetConnectionError(KiboNetError):
+    """Network-level error (timeout, DNS failure, TLS error)"""
+    pass
+
+
+class KiboNetServerError(KiboNetAPIError):
+    """KiboNet server error (HTTP 5xx)"""
+    pass

kibonet_sdk/utils/async_http_client.py

@@ -0,0 +1,108 @@
+"""
+Asynchronous httpx client with connection pooling and retry logic.
+"""
+
+import logging
+from typing import Optional
+
+import httpx
+
+from ..exceptions import KiboNetConnectionError
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://sms.kibonet.co.tz"
+SDK_VERSION = "0.1.0"
+
+
+class AsyncHTTPClient:
+    """
+    Asynchronous httpx client with connection pooling and header-based auth.
+
+    Must be used as an async context manager or closed explicitly with
+    ``await client.aclose()``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        logger: Optional[logging.Logger] = None,
+    ):
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.logger = logger or logging.getLogger(__name__)
+
+        transport = httpx.AsyncHTTPTransport(retries=max_retries)
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self._build_headers(),
+            timeout=timeout,
+            transport=transport,
+        )
+        self.logger.debug(
+            "KiboNet async HTTP client initialised (base_url=%s, timeout=%s)",
+            self.base_url,
+            timeout,
+        )
+
+    def _build_headers(self) -> dict:
+        return {
+            "api_key": self.api_key,
+            "api_secret": self.api_secret,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"KiboNet-Python-SDK/{SDK_VERSION}",
+        }
+
+    async def request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
+        """
+        Make an asynchronous HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, …)
+            endpoint: Path relative to base_url
+            **kwargs: Extra arguments forwarded to httpx
+
+        Returns:
+            httpx.Response
+
+        Raises:
+            KiboNetConnectionError: On any network-level failure
+        """
+        url = f"/{endpoint.lstrip('/')}"
+        self.logger.debug("→ %s %s", method, url)
+        try:
+            response = await self._client.request(method, url, **kwargs)
+            self.logger.debug("← %s", response.status_code)
+            return response
+        except httpx.TimeoutException as exc:
+            self.logger.error("Request timed out: %s", exc)
+            raise KiboNetConnectionError(
+                f"Request timed out after {self.timeout}s"
+            ) from exc
+        except httpx.ConnectError as exc:
+            self.logger.error("Connection error: %s", exc)
+            raise KiboNetConnectionError(
+                f"Failed to connect to KiboNet API: {exc}"
+            ) from exc
+        except httpx.RequestError as exc:
+            self.logger.error("Request failed: %s", exc)
+            raise KiboNetConnectionError(f"Request failed: {exc}") from exc
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._client.aclose()
+        self.logger.debug("KiboNet async HTTP client closed")
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.aclose()

kibonet_sdk/utils/http_client.py

@@ -0,0 +1,108 @@
+"""
+Synchronous httpx client with connection pooling and retry logic.
+"""
+
+import logging
+from typing import Optional, Any
+
+import httpx
+
+from ..exceptions import KiboNetConnectionError
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://sms.kibonet.co.tz"
+SDK_VERSION = "0.1.0"
+
+
+class HTTPClient:
+    """
+    Synchronous httpx client with connection pooling, retries, and header-based auth.
+
+    Designed to be reused across multiple requests. Use as a context manager
+    or call close() explicitly when done.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        logger: Optional[logging.Logger] = None,
+    ):
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.logger = logger or logging.getLogger(__name__)
+
+        transport = httpx.HTTPTransport(retries=max_retries)
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=self._build_headers(),
+            timeout=timeout,
+            transport=transport,
+        )
+        self.logger.debug(
+            "KiboNet sync HTTP client initialised (base_url=%s, timeout=%s)",
+            self.base_url,
+            timeout,
+        )
+
+    def _build_headers(self) -> dict:
+        return {
+            "api_key": self.api_key,
+            "api_secret": self.api_secret,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"KiboNet-Python-SDK/{SDK_VERSION}",
+        }
+
+    def request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
+        """
+        Make an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, …)
+            endpoint: Path relative to base_url
+            **kwargs: Extra arguments forwarded to httpx
+
+        Returns:
+            httpx.Response
+
+        Raises:
+            KiboNetConnectionError: On any network-level failure
+        """
+        url = f"/{endpoint.lstrip('/')}"
+        self.logger.debug("→ %s %s", method, url)
+        try:
+            response = self._client.request(method, url, **kwargs)
+            self.logger.debug("← %s", response.status_code)
+            return response
+        except httpx.TimeoutException as exc:
+            self.logger.error("Request timed out: %s", exc)
+            raise KiboNetConnectionError(
+                f"Request timed out after {self.timeout}s"
+            ) from exc
+        except httpx.ConnectError as exc:
+            self.logger.error("Connection error: %s", exc)
+            raise KiboNetConnectionError(
+                f"Failed to connect to KiboNet API: {exc}"
+            ) from exc
+        except httpx.RequestError as exc:
+            self.logger.error("Request failed: %s", exc)
+            raise KiboNetConnectionError(f"Request failed: {exc}") from exc
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+        self.logger.debug("KiboNet sync HTTP client closed")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

kibonet_sdk/utils/validators.py

@@ -0,0 +1,92 @@
+"""
+Phone number validation utilities.
+
+KiboNet accepts numbers in international format (e.g. 255XXXXXXXXX for Tanzania).
+Local 0XXXXXXXXX format is automatically converted.
+"""
+
+import re
+from typing import List, Tuple, Union
+
+
+class PhoneNumberValidator:
+    """Validator for phone numbers used with KiboNet SMS API."""
+
+    # Tanzania country code — most KiboNet customers are TZ-based
+    DEFAULT_COUNTRY_CODE = "255"
+    TZ_VALID_LENGTH = 12  # 255 + 9 digits
+
+    @classmethod
+    def _strip(cls, phone: str) -> str:
+        """Remove all non-digit characters (spaces, dashes, +)."""
+        return re.sub(r"\D", "", phone)
+
+    @classmethod
+    def validate(cls, phone: str) -> bool:
+        """
+        Return True if *phone* looks like a valid international number.
+
+        Accepts:
+        - Tanzanian format  : 255XXXXXXXXX  / 0XXXXXXXXX / +255XXXXXXXXX
+        - Any E.164 number  : 1-15 digits with a non-zero leading digit
+        """
+        if not phone or not isinstance(phone, str):
+            return False
+        cleaned = cls._strip(phone)
+        if cleaned.startswith("0") and len(cleaned) == 10:
+            cleaned = cls.DEFAULT_COUNTRY_CODE + cleaned[1:]
+        # E.164: 7–15 digits, no leading zero after stripping
+        return bool(re.fullmatch(r"[1-9]\d{6,14}", cleaned))
+
+    @classmethod
+    def clean(cls, phone: str) -> str:
+        """
+        Clean and return phone in international format (no + prefix).
+
+        Raises:
+            ValueError: If the number is invalid.
+        """
+        if not phone:
+            raise ValueError("Phone number cannot be empty")
+        cleaned = cls._strip(phone)
+        if cleaned.startswith("0") and len(cleaned) == 10:
+            cleaned = cls.DEFAULT_COUNTRY_CODE + cleaned[1:]
+        if not cls.validate(cleaned):
+            raise ValueError(
+                f"Invalid phone number: '{phone}'. "
+                "Expected international format e.g. 255712345678"
+            )
+        return cleaned
+
+    @classmethod
+    def validate_batch(cls, phones: List[str]) -> List[Tuple[str, bool]]:
+        """Validate a list of numbers, returning (phone, is_valid) tuples."""
+        return [(p, cls.validate(p)) for p in phones]
+
+    @classmethod
+    def clean_batch(cls, phones: List[str]) -> List[str]:
+        """
+        Clean a list of phone numbers.
+
+        Raises:
+            ValueError: If any number is invalid.
+        """
+        return [cls.clean(p) for p in phones]
+
+    @classmethod
+    def to_csv(cls, phones: Union[str, List[str]]) -> str:
+        """
+        Convert a string or list of phone numbers to the comma-separated
+        format required by KiboNet's ``contacts`` field.
+
+        All numbers are validated and cleaned first.
+
+        Raises:
+            ValueError: If any number is invalid.
+        """
+        if isinstance(phones, str):
+            # May already be CSV — split, clean, rejoin
+            phones = [p.strip() for p in phones.split(",") if p.strip()]
+        if not phones:
+            raise ValueError("At least one recipient phone number is required")
+        return ",".join(cls.clean_batch(phones))