mobiska 0.1.0__tar.gz

mobiska-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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.

mobiska-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: mobiska
+Version: 0.1.0
+Summary: Python SDK for the Mobiska REST API
+Author-email: Mobiska <dev@mobiska.com>
+License: MIT License
+        
+        Copyright (c) 2026 Your Name
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/mobiska/mobiska-py
+Project-URL: Documentation, https://github.com/mobiska/mobiska-py#readme
+Project-URL: Issues, https://github.com/mobiska/mobiska-py/issues
+Keywords: mobiska,sdk,api,client
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Mobiska Python SDK
+
+The official Python SDK for the Mobiska REST API — payments and SMS for businesses across Africa.
+
+## Installation
+
+```bash
+pip install mobiska
+```
+
+## Quick Start
+
+### Configuration
+
+Credentials can be provided via keyword arguments **or** environment variables:
+
+```bash
+MOBISKA_USER_NAME=your_client_key
+MOBISKA_PASSWORD=your_secret_key
+MOBISKA_SERVICE_ID=1
+MOBISKA_SMS_SENDER_ID=YourSender      # SMS only
+MOBISKA_API_URL=https://api.mobiska.com  # optional, this is the default
+```
+
+### SMS
+
+```python
+from mobiska import InitSMS
+
+# Uses env vars when no arguments are passed
+sms = InitSMS()
+
+# Or pass credentials explicitly
+sms = InitSMS(
+    username="your_client_key",
+    password="your_secret_key",
+    service_id=1,
+    sender_id="YourSender",
+)
+
+# Send a message
+response = sms.send_sms("0540000000", "Welcome to Mobiska!")
+print(response["response_code"])
+
+# Send to multiple recipients
+sms.send_sms(["0540000000", "0200000000"], "Batch message")
+
+# Check balance
+balance = sms.check_balance()
+print(balance["response_data"]["sms_balance"])
+```
+
+### Payments
+
+```python
+from mobiska import InitPayment
+
+payment = InitPayment(
+    username="your_client_key",
+    password="your_secret_key",
+    service_id=2,
+)
+
+# Make a payment
+result = payment.make_payment(
+    reference="Order #123",
+    nickname="MyShop",
+    transaction_id="txn_001",
+    trans_type="CTM",
+    customer_number="0541840988",
+    nw="MTN",
+    amount=100,
+    payment_option="MOM",
+    callback_url="https://example.com/webhook",
+    currency_code="GHS",
+)
+
+# Check transaction status
+status = payment.check_transaction_status("txn_001")
+print(status["response_data"]["status"])
+
+# Account lookup (single)
+info = payment.payment_account_lookup(pan="0541840988", nw="MTN")
+print(info["response_data"]["name"])
+
+# Account lookup (batch)
+accounts = payment.payment_account_lookup(accounts=[
+    {"pan": "0541840988", "nw": "MTN"},
+    {"pan": "0201234567", "nw": "VOD"},
+])
+```
+
+### Advanced options
+
+Both `InitSMS` and `InitPayment` accept `timeout`, `retry_count`, and `retry_delay`:
+
+```python
+sms = InitSMS(timeout=10, retry_count=3, retry_delay=0.5)
+```
+
+## Error Handling
+
+```python
+from mobiska import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    APIError,
+)
+
+try:
+    payment.make_payment(...)
+except ValidationError as e:
+    print(f"Invalid input: {e}")
+except AuthenticationError:
+    print("Check your credentials.")
+except RateLimitError:
+    print("Slow down — rate limit hit.")
+except APIError as e:
+    print(f"Server error ({e.status_code}): {e}")
+```
+
+## Development
+
+```bash
+# Create a virtual environment and install
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black mobiska tests
+
+# Lint
+ruff check mobiska tests
+```
+
+## License
+
+MIT
+
+# Mobiska Python SDK
+
+The official Python SDK for the Mobiska REST API.
+
+## Installation
+
+```bash
+pip install mobiska
+```
+
+## Quick Start
+
+```python
+from mobiska import MobiskaClient
+
+client = MobiskaClient(api_key="your-api-key")
+
+# GET request
+users = client.get("/users")
+
+# POST request
+new_user = client.post("/users", json={"name": "Alice"})
+
+# PATCH request
+client.patch(f"/users/{new_user['id']}", json={"name": "Alice Updated"})
+
+# DELETE request
+client.delete(f"/users/{new_user['id']}")
+```
+
+## Error Handling
+
+```python
+from mobiska import MobiskaClient, AuthenticationError, NotFoundError, RateLimitError
+
+try:
+    client.get("/users/999")
+except AuthenticationError:
+    print("Check your API key.")
+except NotFoundError:
+    print("Resource not found.")
+except RateLimitError:
+    print("Slow down — rate limit hit.")
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black mobiska tests
+
+# Lint
+ruff check mobiska tests
+```
+
+## License
+
+MIT

mobiska-0.1.0/README.md

@@ -0,0 +1,209 @@
+# Mobiska Python SDK
+
+The official Python SDK for the Mobiska REST API — payments and SMS for businesses across Africa.
+
+## Installation
+
+```bash
+pip install mobiska
+```
+
+## Quick Start
+
+### Configuration
+
+Credentials can be provided via keyword arguments **or** environment variables:
+
+```bash
+MOBISKA_USER_NAME=your_client_key
+MOBISKA_PASSWORD=your_secret_key
+MOBISKA_SERVICE_ID=1
+MOBISKA_SMS_SENDER_ID=YourSender      # SMS only
+MOBISKA_API_URL=https://api.mobiska.com  # optional, this is the default
+```
+
+### SMS
+
+```python
+from mobiska import InitSMS
+
+# Uses env vars when no arguments are passed
+sms = InitSMS()
+
+# Or pass credentials explicitly
+sms = InitSMS(
+    username="your_client_key",
+    password="your_secret_key",
+    service_id=1,
+    sender_id="YourSender",
+)
+
+# Send a message
+response = sms.send_sms("0540000000", "Welcome to Mobiska!")
+print(response["response_code"])
+
+# Send to multiple recipients
+sms.send_sms(["0540000000", "0200000000"], "Batch message")
+
+# Check balance
+balance = sms.check_balance()
+print(balance["response_data"]["sms_balance"])
+```
+
+### Payments
+
+```python
+from mobiska import InitPayment
+
+payment = InitPayment(
+    username="your_client_key",
+    password="your_secret_key",
+    service_id=2,
+)
+
+# Make a payment
+result = payment.make_payment(
+    reference="Order #123",
+    nickname="MyShop",
+    transaction_id="txn_001",
+    trans_type="CTM",
+    customer_number="0541840988",
+    nw="MTN",
+    amount=100,
+    payment_option="MOM",
+    callback_url="https://example.com/webhook",
+    currency_code="GHS",
+)
+
+# Check transaction status
+status = payment.check_transaction_status("txn_001")
+print(status["response_data"]["status"])
+
+# Account lookup (single)
+info = payment.payment_account_lookup(pan="0541840988", nw="MTN")
+print(info["response_data"]["name"])
+
+# Account lookup (batch)
+accounts = payment.payment_account_lookup(accounts=[
+    {"pan": "0541840988", "nw": "MTN"},
+    {"pan": "0201234567", "nw": "VOD"},
+])
+```
+
+### Advanced options
+
+Both `InitSMS` and `InitPayment` accept `timeout`, `retry_count`, and `retry_delay`:
+
+```python
+sms = InitSMS(timeout=10, retry_count=3, retry_delay=0.5)
+```
+
+## Error Handling
+
+```python
+from mobiska import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    APIError,
+)
+
+try:
+    payment.make_payment(...)
+except ValidationError as e:
+    print(f"Invalid input: {e}")
+except AuthenticationError:
+    print("Check your credentials.")
+except RateLimitError:
+    print("Slow down — rate limit hit.")
+except APIError as e:
+    print(f"Server error ({e.status_code}): {e}")
+```
+
+## Development
+
+```bash
+# Create a virtual environment and install
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black mobiska tests
+
+# Lint
+ruff check mobiska tests
+```
+
+## License
+
+MIT
+
+# Mobiska Python SDK
+
+The official Python SDK for the Mobiska REST API.
+
+## Installation
+
+```bash
+pip install mobiska
+```
+
+## Quick Start
+
+```python
+from mobiska import MobiskaClient
+
+client = MobiskaClient(api_key="your-api-key")
+
+# GET request
+users = client.get("/users")
+
+# POST request
+new_user = client.post("/users", json={"name": "Alice"})
+
+# PATCH request
+client.patch(f"/users/{new_user['id']}", json={"name": "Alice Updated"})
+
+# DELETE request
+client.delete(f"/users/{new_user['id']}")
+```
+
+## Error Handling
+
+```python
+from mobiska import MobiskaClient, AuthenticationError, NotFoundError, RateLimitError
+
+try:
+    client.get("/users/999")
+except AuthenticationError:
+    print("Check your API key.")
+except NotFoundError:
+    print("Resource not found.")
+except RateLimitError:
+    print("Slow down — rate limit hit.")
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black mobiska tests
+
+# Lint
+ruff check mobiska tests
+```
+
+## License
+
+MIT

mobiska-0.1.0/mobiska/__init__.py

@@ -0,0 +1,95 @@
+"""Mobiska Python SDK.
+
+Public API::
+
+    from mobiska import InitSMS, InitPayment
+
+    sms     = InitSMS(username=…, password=…, service_id=…, sender_id=…)
+    payment = InitPayment(username=…, password=…, service_id=…)
+
+Both factories also accept ``timeout``, ``retry_count`` and ``retry_delay``
+keyword arguments.  When called with no arguments they read credentials from
+environment variables (``MOBISKA_USER_NAME``, ``MOBISKA_PASSWORD``,
+``MOBISKA_SERVICE_ID``, ``MOBISKA_SMS_SENDER_ID``, ``MOBISKA_API_URL``).
+"""
+
+from typing import Optional
+
+from .client import BaseClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    MobiskaError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .resources import PaymentClient, SMSClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "InitSMS",
+    "InitPayment",
+    "SMSClient",
+    "PaymentClient",
+    "BaseClient",
+    "MobiskaError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "APIError",
+]
+
+
+def InitSMS(
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    service_id: Optional[int] = None,
+    sender_id: Optional[str] = None,
+    api_url: Optional[str] = None,
+    timeout: int = 30,
+    retry_count: int = 0,
+    retry_delay: float = 0.5,
+) -> SMSClient:
+    """Create and return an :class:`SMSClient`.
+
+    All arguments are optional — when omitted the values are read from
+    environment variables.
+    """
+    return SMSClient(
+        username=username,
+        password=password,
+        service_id=service_id,
+        sender_id=sender_id,
+        api_url=api_url,
+        timeout=timeout,
+        retry_count=retry_count,
+        retry_delay=retry_delay,
+    )
+
+
+def InitPayment(
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    service_id: Optional[int] = None,
+    api_url: Optional[str] = None,
+    timeout: int = 30,
+    retry_count: int = 0,
+    retry_delay: float = 0.5,
+) -> PaymentClient:
+    """Create and return a :class:`PaymentClient`.
+
+    All arguments are optional — when omitted the values are read from
+    environment variables.
+    """
+    return PaymentClient(
+        username=username,
+        password=password,
+        service_id=service_id,
+        api_url=api_url,
+        timeout=timeout,
+        retry_count=retry_count,
+        retry_delay=retry_delay,
+    )

mobiska-0.1.0/mobiska/auth.py

@@ -0,0 +1,32 @@
+"""Basic Authentication helper for the Mobiska API.
+
+Mobiska uses HTTP Basic Auth: the client_key (username) and secret_key
+(password) are combined as ``username:password``, base64-encoded, and sent
+in the ``Authorization`` header prefixed with ``Basic``.
+"""
+
+import base64
+from typing import Dict
+
+
+class BasicAuth:
+    """Generates the Basic-auth Authorization header for API requests."""
+
+    def __init__(self, username: str, password: str):
+        if not username or not password:
+            raise ValueError("username and password must not be empty.")
+        self.username = username
+        self.password = password
+
+    @property
+    def _encoded(self) -> str:
+        raw = f"{self.username}:{self.password}".encode("utf-8")
+        return base64.b64encode(raw).decode("ascii")
+
+    def get_headers(self) -> Dict[str, str]:
+        """Return the auth headers to attach to every request."""
+        return {
+            "Authorization": f"Basic {self._encoded}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }