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

clickpesa/client.py

@@ -0,0 +1,302 @@
+"""
+Synchronous ClickPesa HTTP client.
+
+Handles authentication, checksum injection, retries, and error mapping for
+all blocking (sync) API calls.  For async usage see :mod:`clickpesa.async_client`.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import threading
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    ClickPesaError,
+    ConflictError,
+    ForbiddenError,
+    InsufficientFundsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .security import SecurityManager
+
+logger = logging.getLogger(__name__)
+
+_SANDBOX_URL = "https://api-sandbox.clickpesa.com"
+_PRODUCTION_URL = "https://api.clickpesa.com"
+_AUTH_PATH = "/third-parties/generate-token"
+# Tokens are valid for 1 hour; refresh 5 minutes before expiry.
+_TOKEN_TTL = 3300  # seconds
+_DEFAULT_TIMEOUT = 30.0
+_MAX_RETRIES = 3
+_RETRY_STATUSES = {500, 502, 503, 504}
+_INSUFFICIENT_FUNDS_PHRASE = "Insufficient balance"
+
+
+class ClickPesaClient:
+    """
+    Production-grade synchronous HTTP client for the ClickPesa API.
+
+    Features
+    --------
+    - Automatic JWT token acquisition and thread-safe caching (55-minute window).
+    - Optional HMAC-SHA256 checksum injection on every mutating request.
+    - Exponential-backoff retries on transient 5xx errors.
+    - Structured exception hierarchy — never raises a bare ``Exception``.
+    - Context-manager support (``with`` statement).
+
+    Parameters
+    ----------
+    client_id:
+        Your ClickPesa application Client ID.
+    api_key:
+        Your ClickPesa application API key.
+    checksum_key:
+        Optional checksum secret.  When provided every POST/PUT/PATCH request
+        automatically receives a ``checksum`` field.
+    sandbox:
+        Set ``True`` to target the sandbox environment.
+    timeout:
+        Request timeout in seconds (default: 30).
+    max_retries:
+        Maximum number of retry attempts on transient server errors (default: 3).
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        api_key: str,
+        checksum_key: str | None = None,
+        sandbox: bool = False,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _MAX_RETRIES,
+    ) -> None:
+        self.client_id = client_id
+        self.api_key = api_key
+        self.checksum_key = checksum_key
+        self.base_url = _SANDBOX_URL if sandbox else _PRODUCTION_URL
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        # Thread-safe token cache
+        self._token: str | None = None
+        self._token_expires_at: float = 0.0
+        self._lock = threading.Lock()
+
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Content-Type": "application/json"},
+            timeout=self.timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    def _authenticate(self) -> str:
+        """Return a valid Bearer token, refreshing if necessary."""
+        with self._lock:
+            now = time.monotonic()
+            if self._token and now < self._token_expires_at:
+                return self._token
+
+            logger.debug("Refreshing ClickPesa access token …")
+            try:
+                response = self._http.post(
+                    _AUTH_PATH,
+                    headers={
+                        "client-id": self.client_id,
+                        "api-key": self.api_key,
+                    },
+                )
+            except httpx.TransportError as exc:
+                raise ClickPesaError(f"Network error during authentication: {exc}") from exc
+
+            if response.status_code == 401:
+                raise AuthenticationError(
+                    "Invalid client-id or api-key", status_code=401
+                )
+            if response.status_code == 403:
+                data = _safe_json(response)
+                raise ForbiddenError(
+                    data.get("message", "Forbidden"),
+                    status_code=403,
+                    response=data,
+                )
+            if not response.is_success:
+                raise ClickPesaError(
+                    f"Authentication failed ({response.status_code}): {response.text}",
+                    status_code=response.status_code,
+                )
+
+            data = _safe_json(response)
+            token = data.get("token")
+            if not token:
+                raise ClickPesaError("Authentication response missing 'token' field")
+
+            self._token = token
+            self._token_expires_at = now + _TOKEN_TTL
+            logger.debug("Access token cached for %d seconds.", _TOKEN_TTL)
+            return self._token
+
+    # ------------------------------------------------------------------
+    # Core request dispatcher
+    # ------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """
+        Execute an authenticated API request with automatic retry on 5xx errors.
+
+        Parameters
+        ----------
+        method:   HTTP verb (``"GET"``, ``"POST"``, ``"PATCH"``, etc.).
+        endpoint: API path relative to the base URL (leading slash optional).
+        json:     Request body — will NOT be mutated; a shallow copy is made.
+        params:   Query-string parameters.
+
+        Returns
+        -------
+        Parsed JSON response body.
+
+        Raises
+        ------
+        :class:`~clickpesa.exceptions.ClickPesaError` or one of its subclasses.
+        """
+        token = self._authenticate()
+        path = endpoint if endpoint.startswith("/") else f"/{endpoint}"
+
+        # Build payload copy so the caller's dict is never mutated.
+        payload: dict[str, Any] | None = None
+        if json is not None:
+            payload = dict(json)
+            if self.checksum_key and method.upper() in {"POST", "PUT", "PATCH"}:
+                if "checksum" not in payload:
+                    payload["checksum"] = SecurityManager.create_checksum(
+                        self.checksum_key, payload
+                    )
+
+        last_exc: Exception | None = None
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                response = self._http.request(
+                    method=method,
+                    url=path,
+                    json=payload,
+                    params=params,
+                    headers={"Authorization": token},
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    _backoff(attempt)
+                    continue
+                raise ClickPesaError(f"Network error: {exc}") from exc
+
+            if response.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                logger.warning(
+                    "Received %d on attempt %d/%d — retrying …",
+                    response.status_code,
+                    attempt,
+                    self.max_retries,
+                )
+                _backoff(attempt)
+                continue
+
+            return self._handle_response(response)
+
+        raise ClickPesaError(
+            f"Request failed after {self.max_retries} attempts"
+        ) from last_exc
+
+    # ------------------------------------------------------------------
+    # Response handling
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _handle_response(response: httpx.Response) -> Any:
+        """Map HTTP status codes to structured exceptions."""
+        data = _safe_json(response)
+
+        if response.is_success:
+            return data
+
+        msg = data.get("message", "Unknown API error") if isinstance(data, dict) else str(data)
+        status = response.status_code
+
+        if status == 400:
+            if _INSUFFICIENT_FUNDS_PHRASE in msg:
+                raise InsufficientFundsError(msg, status_code=status, response=data)
+            raise ValidationError(msg, status_code=status, response=data)
+        if status == 401:
+            raise AuthenticationError(msg, status_code=status, response=data)
+        if status == 403:
+            raise ForbiddenError(msg, status_code=status, response=data)
+        if status == 404:
+            raise NotFoundError(msg, status_code=status, response=data)
+        if status == 409:
+            raise ConflictError(msg, status_code=status, response=data)
+        if status == 429:
+            raise RateLimitError(msg, status_code=status, response=data)
+        if status >= 500:
+            raise ServerError(msg, status_code=status, response=data)
+
+        raise ClickPesaError(msg, status_code=status, response=data)
+
+    # ------------------------------------------------------------------
+    # Utilities
+    # ------------------------------------------------------------------
+
+    def is_healthy(self) -> bool:
+        """
+        Perform a lightweight connectivity and credential check.
+
+        Returns ``True`` if the API is reachable and credentials are valid.
+        """
+        try:
+            self.request("GET", "/third-parties/account/balance")
+            return True
+        except Exception:
+            return False
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    # Context-manager protocol
+    def __enter__(self) -> "ClickPesaClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+# ------------------------------------------------------------------
+# Private helpers
+# ------------------------------------------------------------------
+
+def _safe_json(response: httpx.Response) -> Any:
+    """Parse JSON without raising; fall back to a message dict."""
+    try:
+        return response.json()
+    except Exception:
+        return {"message": response.text}
+
+
+def _backoff(attempt: int) -> None:
+    """Exponential backoff: 1 s, 2 s, 4 s …"""
+    delay = 2 ** (attempt - 1)
+    logger.debug("Retrying in %d second(s) …", delay)
+    time.sleep(delay)

clickpesa/exceptions.py

@@ -0,0 +1,100 @@
+"""
+ClickPesa SDK exception hierarchy.
+
+All exceptions inherit from ``ClickPesaError`` so callers can catch the
+base class when they don't need to distinguish between error types.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ClickPesaError(Exception):
+    """Base exception for all ClickPesa SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={str(self)!r}, "
+            f"status_code={self.status_code!r})"
+        )
+
+
+class AuthenticationError(ClickPesaError):
+    """
+    Raised on HTTP 401.
+    Credentials (client-id / api-key) are invalid or the JWT token has expired.
+    """
+
+
+class ForbiddenError(ClickPesaError):
+    """
+    Raised on HTTP 403.
+    The API key is valid but does not have access to the requested feature.
+    """
+
+
+class ValidationError(ClickPesaError):
+    """
+    Raised on HTTP 400.
+    The request payload failed server-side validation.
+    """
+
+
+class InsufficientFundsError(ValidationError):
+    """
+    Raised on HTTP 400 when the error message indicates insufficient balance.
+    Subclass of ValidationError so it is caught by the same broad handler.
+    """
+
+
+class NotFoundError(ClickPesaError):
+    """
+    Raised on HTTP 404.
+    The requested resource (payment, payout, BillPay number, etc.) does not exist.
+    """
+
+
+class ConflictError(ClickPesaError):
+    """
+    Raised on HTTP 409.
+    Typically means the ``orderReference`` or ``billReference`` has already been used.
+    """
+
+
+class RateLimitError(ClickPesaError):
+    """
+    Raised on HTTP 429.
+    A payout request is already in progress; retry after the indicated delay.
+    """
+
+
+class ServerError(ClickPesaError):
+    """
+    Raised on HTTP 5xx.
+    An unexpected error occurred on the ClickPesa server side.
+    """
+
+
+__all__ = [
+    "ClickPesaError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "ValidationError",
+    "InsufficientFundsError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+]

clickpesa/security.py

@@ -0,0 +1,74 @@
+"""
+ClickPesa HMAC-SHA256 security utilities.
+
+Used for generating request checksums and verifying incoming webhook signatures.
+"""
+
+from __future__ import annotations
+
+import hmac
+import hashlib
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityManager:
+    @staticmethod
+    def create_checksum(checksum_key: str, payload: dict) -> str:
+        """
+        Generate a ClickPesa-compatible HMAC-SHA256 checksum for a request payload.
+
+        Algorithm:
+        1. Sort payload keys alphabetically.
+        2. Concatenate the string representation of all top-level scalar values
+           (nested dicts and lists are excluded, matching ClickPesa's specification).
+        3. Return the hex digest of HMAC-SHA256(key, concatenated_string).
+
+        Args:
+            checksum_key: Your application's checksum secret key.
+            payload:      The request body dict (before the checksum field is added).
+
+        Returns:
+            Hex-encoded HMAC-SHA256 string, or ``""`` if ``checksum_key`` is falsy.
+        """
+        if not checksum_key:
+            return ""
+
+        sorted_keys = sorted(payload.keys())
+        payload_string = "".join(
+            str(payload[k])
+            for k in sorted_keys
+            if not isinstance(payload[k], (dict, list))
+        )
+
+        return hmac.new(
+            checksum_key.encode("utf-8"),
+            payload_string.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+    @staticmethod
+    def verify_webhook(checksum_key: str, payload: dict, signature: str) -> bool:
+        """
+        Verify an incoming ClickPesa webhook signature.
+
+        Uses ``hmac.compare_digest`` for constant-time comparison to prevent
+        timing-based side-channel attacks.
+
+        Args:
+            checksum_key: Your application's checksum secret key.
+            payload:      The parsed webhook body dict.
+            signature:    The ``X-ClickPesa-Signature`` header value.
+
+        Returns:
+            ``True`` if the signature is valid, ``False`` otherwise.
+        """
+        if not signature:
+            return False
+
+        computed = SecurityManager.create_checksum(checksum_key, payload)
+        return hmac.compare_digest(computed, signature)
+
+
+__all__ = ["SecurityManager"]

clickpesa/services/__init__.py

@@ -0,0 +1,21 @@
+from .payments import PaymentService, AsyncPaymentService
+from .payouts import PayoutService, AsyncPayoutService
+from .billpay import BillPayService, AsyncBillPayService
+from .account import AccountService, AsyncAccountService
+from .exchange import ExchangeService, AsyncExchangeService
+from .links import LinkService, AsyncLinkService
+
+__all__ = [
+    "PaymentService",
+    "AsyncPaymentService",
+    "PayoutService",
+    "AsyncPayoutService",
+    "BillPayService",
+    "AsyncBillPayService",
+    "AccountService",
+    "AsyncAccountService",
+    "ExchangeService",
+    "AsyncExchangeService",
+    "LinkService",
+    "AsyncLinkService",
+]

clickpesa/services/account.py

@@ -0,0 +1,87 @@
+"""
+Account services — balance and statement.
+
+Sync:  ``AccountService``      — attach to :class:`~clickpesa.client.ClickPesaClient`.
+Async: ``AsyncAccountService`` — attach to :class:`~clickpesa.async_client.AsyncClickPesaClient`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..client import ClickPesaClient
+    from ..async_client import AsyncClickPesaClient
+
+_BASE = "/third-parties/account"
+
+
+# ---------------------------------------------------------------------------
+# Sync
+# ---------------------------------------------------------------------------
+
+class AccountService:
+    """Synchronous account information methods."""
+
+    def __init__(self, client: "ClickPesaClient") -> None:
+        self._c = client
+
+    def get_balance(self) -> list[dict[str, Any]]:
+        """
+        Retrieve account balances for all active currencies.
+
+        Returns:
+            List of ``{"currency": "TZS", "balance": 12345.00}`` dicts.
+        """
+        return self._c.request("GET", f"{_BASE}/balance")
+
+    def get_statement(
+        self,
+        currency: str = "TZS",
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Fetch a transaction statement for a given currency.
+
+        Args:
+            currency:   ``"TZS"`` (default) or ``"USD"``.  Required by the API.
+            start_date: Optional filter — ``YYYY-MM-DD`` or ``DD-MM-YYYY``.
+            end_date:   Optional filter — ``YYYY-MM-DD`` or ``DD-MM-YYYY``.
+
+        Returns:
+            Dict with ``accountDetails`` and ``transactions`` list.
+        """
+        params: dict[str, Any] = {"currency": currency}
+        if start_date is not None:
+            params["startDate"] = start_date
+        if end_date is not None:
+            params["endDate"] = end_date
+        return self._c.request("GET", f"{_BASE}/statement", params=params)
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+class AsyncAccountService:
+    """Asynchronous account information methods (mirrors :class:`AccountService`)."""
+
+    def __init__(self, client: "AsyncClickPesaClient") -> None:
+        self._c = client
+
+    async def get_balance(self) -> list[dict[str, Any]]:
+        return await self._c.request("GET", f"{_BASE}/balance")
+
+    async def get_statement(
+        self,
+        currency: str = "TZS",
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"currency": currency}
+        if start_date is not None:
+            params["startDate"] = start_date
+        if end_date is not None:
+            params["endDate"] = end_date
+        return await self._c.request("GET", f"{_BASE}/statement", params=params)