kibonet-python-sdk 0.1.0__tar.gz

kibonet_python_sdk-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,232 @@
+# 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/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kibonet-python-sdk"
+version = "0.1.0"
+description = "Simple, secure Python SDK for the KiboNet SMS Gateway"
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "Jackson Linus", email = "jacksonlinus95@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Telephony",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+]
+keywords = ["kibonet", "sms", "tanzania", "africa", "messaging", "httpx", "async"]
+dependencies = [
+    "httpx>=0.24.0",
+]
+requires-python = ">=3.8"
+
+[project.urls]
+Homepage = "https://github.com/JAXPARROW/kibonet-python-sdk"
+Repository = "https://github.com/JAXPARROW/kibonet-python-sdk.git"
+Issues = "https://github.com/JAXPARROW/kibonet-python-sdk/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "respx>=0.20.0",
+    "mypy>=1.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "build>=1.0.0",
+    "twine>=4.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["kibonet_sdk*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.8"
+strict = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"

kibonet_python_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+