cinetpay-python 0.1.0__py3-none-any.whl

cinetpay/auth/token_store.py

@@ -0,0 +1,72 @@
+"""In-memory token store (default implementation)."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class _CacheEntry:
+    """Internal cache entry with monotonic expiration timestamp."""
+
+    value: str
+    expires_at: float
+
+
+class MemoryTokenStore:
+    """In-memory JWT token store with lazy expiration.
+
+    Expired tokens are automatically evicted on read. Suitable for a single
+    process. For multi-instance production deployments, implement
+    :class:`~cinetpay.types.config.TokenStoreProtocol` with Redis or another
+    shared backend.
+
+    Example::
+
+        from cinetpay.auth.token_store import MemoryTokenStore
+        store = MemoryTokenStore()
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, _CacheEntry] = {}
+
+    def get(self, key: str) -> str | None:
+        """Retrieve a token from the cache.
+
+        If the token is expired, it is deleted and ``None`` is returned.
+
+        Args:
+            key: Cache key (e.g. ``cinetpay_token_ci``).
+
+        Returns:
+            The token string, or ``None`` if absent/expired.
+        """
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        if time.monotonic() >= entry.expires_at:
+            del self._cache[key]
+            return None
+        return entry.value
+
+    def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Store a token with a time-to-live.
+
+        Args:
+            key: Cache key.
+            value: JWT token string.
+            ttl_seconds: Time-to-live in seconds.
+        """
+        self._cache[key] = _CacheEntry(
+            value=value,
+            expires_at=time.monotonic() + ttl_seconds,
+        )
+
+    def delete(self, key: str) -> None:
+        """Remove a token from the cache.
+
+        Args:
+            key: Cache key to delete.
+        """
+        self._cache.pop(key, None)

cinetpay/client.py

@@ -0,0 +1,256 @@
+"""Synchronous CinetPay client — main entry point of the SDK."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from cinetpay.api.balance import BalanceApi
+from cinetpay.api.payment import PaymentApi
+from cinetpay.api.transfer import TransferApi
+from cinetpay.auth.authenticator import Authenticator
+from cinetpay.auth.token_store import MemoryTokenStore
+from cinetpay.http.http_client import HttpClient
+from cinetpay.logger import LoggerProtocol, NoopLogger, StandardLibLogger
+from cinetpay.types.config import (
+    API_KEY_PREFIX_LIVE,
+    API_KEY_PREFIX_TEST,
+    ClientConfig,
+    CountryCredentials,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_TOKEN_TTL,
+    PRODUCTION_BASE_URL,
+)
+
+# Hostnames allowed for the base URL (SSRF protection)
+_ALLOWED_HOSTS = frozenset({
+    "api.cinetpay.net",   # Sandbox
+    "api.cinetpay.co",    # Production
+    "localhost",
+    "127.0.0.1",
+})
+
+
+class CinetPayClient:
+    """Synchronous CinetPay SDK client.
+
+    Manages multi-country JWT authentication, token caching, and exposes
+    the payment, transfer, and balance APIs.
+
+    Example::
+
+        from cinetpay import CinetPayClient, ClientConfig, CountryCredentials
+
+        client = CinetPayClient(ClientConfig(
+            credentials={
+                "CI": CountryCredentials(api_key="sk_test_...", api_password="..."),
+                "SN": CountryCredentials(api_key="sk_test_...", api_password="..."),
+            },
+            debug=True,
+        ))
+
+    Attributes:
+        payment: Web payment API (initialize, get_status).
+        transfer: Money transfer API (create, get_status).
+        balance: Merchant balance API (get).
+    """
+
+    payment: PaymentApi
+    """Web payment API -- initialization and status check."""
+
+    transfer: TransferApi
+    """Money transfer API -- send and check status."""
+
+    balance: BalanceApi
+    """Merchant account balance API."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        credentials = config.credentials
+        if not credentials:
+            raise TypeError(
+                "At least one country credential must be provided in config.credentials"
+            )
+
+        token_ttl = config.token_ttl if config.token_ttl is not None else DEFAULT_TOKEN_TTL
+        timeout = config.timeout if config.timeout is not None else DEFAULT_TIMEOUT
+        token_store = config.token_store if config.token_store is not None else MemoryTokenStore()
+
+        # Resolve logger: explicit > debug flag > silent
+        logger: LoggerProtocol
+        if config.logger is not None:
+            logger = config.logger
+        elif config.debug:
+            logger = StandardLibLogger()
+        else:
+            logger = NoopLogger()
+
+        # Detect environment from API key prefixes
+        entries = list(credentials.items())
+        detected_env = _detect_environment(entries, logger)
+
+        # Resolve base URL: explicit > auto-detect > sandbox default
+        if config.base_url is not None:
+            base_url = config.base_url
+        elif detected_env == "live":
+            base_url = PRODUCTION_BASE_URL
+        else:
+            base_url = DEFAULT_BASE_URL
+
+        # Validate key/URL coherence
+        _validate_key_url_coherence(detected_env, base_url, logger)
+
+        # Enforce HTTPS (except localhost)
+        parsed = urlparse(base_url)
+        if parsed.scheme != "https" and parsed.hostname not in ("localhost", "127.0.0.1"):
+            raise TypeError(
+                "base_url must use HTTPS for security. "
+                "Use https:// or localhost for development."
+            )
+
+        # SSRF protection: warn on unknown hosts
+        if parsed.hostname and not any(
+            parsed.hostname == h or parsed.hostname.endswith(f".{h}")
+            for h in _ALLOWED_HOSTS
+        ):
+            logger.warn(
+                f'base_url hostname "{parsed.hostname}" is not a known CinetPay domain. '
+                f"Expected: {', '.join(sorted(_ALLOWED_HOSTS))}. Proceeding anyway."
+            )
+
+        # Validate URL
+        if not parsed.scheme or not parsed.hostname:
+            raise TypeError(f'base_url "{base_url}" is not a valid URL.')
+
+        # Build HTTP client and authenticators
+        http_client = HttpClient(base_url, timeout, logger)
+
+        self._authenticators: dict[str, Authenticator] = {}
+        for country, creds in entries:
+            key = country.upper()
+            self._authenticators[key] = Authenticator(
+                http_client, key, creds, token_ttl, token_store, logger,
+            )
+
+        self.payment = PaymentApi(http_client, self._authenticators)
+        self.transfer = TransferApi(http_client, self._authenticators)
+        self.balance = BalanceApi(http_client, self._authenticators)
+
+        self._http_client = http_client
+        self._logger = logger
+
+        logger.debug("CinetPayClient initialized", {
+            "countries": self.countries(),
+            "base_url": base_url,
+            "token_ttl": token_ttl,
+            "timeout": timeout,
+        })
+
+    def countries(self) -> list[str]:
+        """Return the list of configured country codes.
+
+        Example::
+
+            client.countries()  # ["CI", "SN"]
+        """
+        return list(self._authenticators.keys())
+
+    def revoke_token(self, country: str) -> None:
+        """Revoke the cached JWT token for a country.
+
+        The next API call will trigger a fresh authentication.
+
+        Args:
+            country: ISO country code (e.g. ``"CI"``).
+
+        Raises:
+            TypeError: If the country is not configured.
+        """
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            raise TypeError(
+                f'No credentials configured for country "{key}". '
+                f"Available: {', '.join(self.countries())}"
+            )
+        auth.clear_cache()
+
+    def revoke_all_tokens(self) -> None:
+        """Revoke all cached JWT tokens for all configured countries."""
+        for auth in self._authenticators.values():
+            auth.clear_cache()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._http_client.close()
+
+    def __enter__(self) -> CinetPayClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        """Prevent credential leakage via repr()."""
+        return f"CinetPayClient(countries={self.countries()!r})"
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _detect_environment(
+    entries: list[tuple[str, CountryCredentials]],
+    logger: LoggerProtocol,
+) -> str:
+    """Detect test/live/mixed/unknown from API key prefixes."""
+    envs: set[str] = set()
+    for country, creds in entries:
+        if creds.api_key.startswith(API_KEY_PREFIX_TEST):
+            envs.add("test")
+        elif creds.api_key.startswith(API_KEY_PREFIX_LIVE):
+            envs.add("live")
+        else:
+            logger.warn(
+                f'API key for country {country.upper()} does not start with '
+                f'"{API_KEY_PREFIX_TEST}" or "{API_KEY_PREFIX_LIVE}". '
+                f"Expected format: sk_test_... (sandbox) or sk_live_... (production)."
+            )
+            envs.add("unknown")
+
+    if "test" in envs and "live" in envs:
+        logger.error(
+            "MIXED ENVIRONMENTS: some credentials use sk_test_ (sandbox) and "
+            "others use sk_live_ (production). This will cause authentication "
+            "failures. Use the same environment for all countries."
+        )
+        return "mixed"
+
+    if "live" in envs:
+        return "live"
+    if "test" in envs:
+        return "test"
+    return "unknown"
+
+
+def _validate_key_url_coherence(
+    detected_env: str,
+    base_url: str,
+    logger: LoggerProtocol,
+) -> None:
+    """Warn if API key type and base URL are mismatched."""
+    is_sandbox_url = "cinetpay.net" in base_url
+    is_production_url = "cinetpay.co" in base_url
+
+    if detected_env == "live" and is_sandbox_url:
+        logger.error(
+            f"ENVIRONMENT MISMATCH: production keys (sk_live_) are used with "
+            f'sandbox URL ({base_url}). Use base_url="{PRODUCTION_BASE_URL}" '
+            f"for production, or remove base_url to auto-detect."
+        )
+    if detected_env == "test" and is_production_url:
+        logger.error(
+            f"ENVIRONMENT MISMATCH: sandbox keys (sk_test_) are used with "
+            f'production URL ({base_url}). Use base_url="{DEFAULT_BASE_URL}" '
+            f"for sandbox, or remove base_url to auto-detect."
+        )

cinetpay/constants/__init__.py

@@ -0,0 +1,15 @@
+from cinetpay.constants.currencies import CURRENCIES, Currency
+from cinetpay.constants.channels import CHANNELS, Channel
+from cinetpay.constants.payment_methods import PAYMENT_METHODS, PAYMENT_METHODS_BY_COUNTRY, PaymentMethod
+from cinetpay.constants.statuses import (
+    TRANSACTION_STATUSES, API_CODES, COUNTRY_CODES,
+    TransactionStatus, CountryCode, is_final_status,
+)
+
+__all__ = [
+    "CURRENCIES", "Currency",
+    "CHANNELS", "Channel",
+    "PAYMENT_METHODS", "PAYMENT_METHODS_BY_COUNTRY", "PaymentMethod",
+    "TRANSACTION_STATUSES", "API_CODES", "COUNTRY_CODES",
+    "TransactionStatus", "CountryCode", "is_final_status",
+]

cinetpay/constants/channels.py

@@ -0,0 +1,12 @@
+"""Payment channels supported by CinetPay (PUSH, OTP, QRCODE)."""
+
+from __future__ import annotations
+from typing import Literal
+
+Channel = Literal["PUSH", "OTP", "QRCODE"]
+
+CHANNELS: dict[str, Channel] = {
+    "PUSH": "PUSH",
+    "OTP": "OTP",
+    "QRCODE": "QRCODE",
+}

cinetpay/constants/currencies.py

@@ -0,0 +1,14 @@
+"""Supported currencies for CinetPay transactions (XOF, XAF, GNF, CDF, USD)."""
+
+from __future__ import annotations
+from typing import Literal
+
+Currency = Literal["XOF", "XAF", "GNF", "CDF", "USD"]
+
+CURRENCIES: dict[str, Currency] = {
+    "XOF": "XOF",
+    "XAF": "XAF",
+    "GNF": "GNF",
+    "CDF": "CDF",
+    "USD": "USD",
+}

cinetpay/constants/payment_methods.py

@@ -0,0 +1,43 @@
+"""Mobile money payment methods by operator and country (e.g. OM_CI, WAVE_SN)."""
+
+from __future__ import annotations
+from typing import Literal
+
+PaymentMethod = Literal[
+    "OM_CI", "MOOV_CI", "MTN_CI", "WAVE_CI",
+    "OM_BF", "MOOV_BF", "WAVE_BF",
+    "OM_ML", "MOOV_ML",
+    "OM_SN", "FREE_SN", "EXPRESSO_SN", "WAVE_SN",
+    "MOOV_TG", "TMONEY_TG",
+    "OM_GN", "MTN_GN",
+    "OM_CM", "MTN_CM",
+    "MOOV_BJ", "MTN_BJ",
+    "OM_CD", "AIRTEL_CD", "MPESA_CD", "AFRICELL_CD",
+    "AIRTEL_NE", "MOOV_NE", "ZAMANI_NE",
+]
+
+PAYMENT_METHODS: dict[str, PaymentMethod] = {
+    "OM_CI": "OM_CI", "MOOV_CI": "MOOV_CI", "MTN_CI": "MTN_CI", "WAVE_CI": "WAVE_CI",
+    "OM_BF": "OM_BF", "MOOV_BF": "MOOV_BF", "WAVE_BF": "WAVE_BF",
+    "OM_ML": "OM_ML", "MOOV_ML": "MOOV_ML",
+    "OM_SN": "OM_SN", "FREE_SN": "FREE_SN", "EXPRESSO_SN": "EXPRESSO_SN", "WAVE_SN": "WAVE_SN",
+    "MOOV_TG": "MOOV_TG", "TMONEY_TG": "TMONEY_TG",
+    "OM_GN": "OM_GN", "MTN_GN": "MTN_GN",
+    "OM_CM": "OM_CM", "MTN_CM": "MTN_CM",
+    "MOOV_BJ": "MOOV_BJ", "MTN_BJ": "MTN_BJ",
+    "OM_CD": "OM_CD", "AIRTEL_CD": "AIRTEL_CD", "MPESA_CD": "MPESA_CD", "AFRICELL_CD": "AFRICELL_CD",
+    "AIRTEL_NE": "AIRTEL_NE", "MOOV_NE": "MOOV_NE", "ZAMANI_NE": "ZAMANI_NE",
+}
+
+PAYMENT_METHODS_BY_COUNTRY: dict[str, tuple[PaymentMethod, ...]] = {
+    "CI": ("OM_CI", "MOOV_CI", "MTN_CI", "WAVE_CI"),
+    "BF": ("OM_BF", "MOOV_BF", "WAVE_BF"),
+    "ML": ("OM_ML", "MOOV_ML"),
+    "SN": ("OM_SN", "FREE_SN", "EXPRESSO_SN", "WAVE_SN"),
+    "TG": ("MOOV_TG", "TMONEY_TG"),
+    "GN": ("OM_GN", "MTN_GN"),
+    "CM": ("OM_CM", "MTN_CM"),
+    "BJ": ("MOOV_BJ", "MTN_BJ"),
+    "CD": ("OM_CD", "AIRTEL_CD", "MPESA_CD", "AFRICELL_CD"),
+    "NE": ("AIRTEL_NE", "MOOV_NE", "ZAMANI_NE"),
+}

cinetpay/constants/statuses.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from typing import Literal
+
+TransactionStatus = Literal[
+    "OK", "SUCCESS", "OPERATION_ERROR", "NOT_FOUND",
+    "INVALID_CREDENTIALS", "INVALID_PARAMS", "EXPIRED_TOKEN", "INVALID_TOKEN",
+    "TRANSACTION_EXIST", "INITIATED", "PENDING", "EXPIRED",
+    "OTP_ERROR", "OTP_EXPIRED", "INSUFFICIENT_BALANCE",
+    "USER_NOT_FOUND", "USER_IS_BLOCKED", "FAILED", "NOT_ALLOWED",
+]
+
+TRANSACTION_STATUSES: dict[str, TransactionStatus] = {
+    "OK": "OK", "SUCCESS": "SUCCESS", "OPERATION_ERROR": "OPERATION_ERROR",
+    "NOT_FOUND": "NOT_FOUND", "INVALID_CREDENTIALS": "INVALID_CREDENTIALS",
+    "INVALID_PARAMS": "INVALID_PARAMS", "EXPIRED_TOKEN": "EXPIRED_TOKEN",
+    "INVALID_TOKEN": "INVALID_TOKEN", "TRANSACTION_EXIST": "TRANSACTION_EXIST",
+    "INITIATED": "INITIATED", "PENDING": "PENDING", "EXPIRED": "EXPIRED",
+    "OTP_ERROR": "OTP_ERROR", "OTP_EXPIRED": "OTP_EXPIRED",
+    "INSUFFICIENT_BALANCE": "INSUFFICIENT_BALANCE",
+    "USER_NOT_FOUND": "USER_NOT_FOUND", "USER_IS_BLOCKED": "USER_IS_BLOCKED",
+    "FAILED": "FAILED", "NOT_ALLOWED": "NOT_ALLOWED",
+}
+
+_FINAL_STATUSES = frozenset({"SUCCESS", "FAILED", "TRANSACTION_EXIST", "INSUFFICIENT_BALANCE"})
+
+
+def is_final_status(status: str) -> bool:
+    """Returns True if the status is final (no more changes possible)."""
+    return status in _FINAL_STATUSES
+
+
+API_CODES: dict[int, TransactionStatus] = {
+    200: "OK", 100: "SUCCESS", -1: "OPERATION_ERROR", 404: "NOT_FOUND",
+    1005: "INVALID_CREDENTIALS", 1004: "INVALID_PARAMS",
+    1003: "EXPIRED_TOKEN", 1002: "INVALID_TOKEN", 1200: "TRANSACTION_EXIST",
+    2001: "INITIATED", 2002: "PENDING", 2003: "EXPIRED",
+    2004: "OTP_ERROR", 2008: "OTP_EXPIRED", 2005: "INSUFFICIENT_BALANCE",
+    2006: "USER_NOT_FOUND", 2007: "USER_IS_BLOCKED",
+    2010: "FAILED", 2011: "NOT_ALLOWED",
+}
+
+CountryCode = Literal["CI", "BF", "ML", "SN", "TG", "GN", "CM", "BJ", "CD", "NE"]
+
+COUNTRY_CODES: tuple[CountryCode, ...] = ("CI", "BF", "ML", "SN", "TG", "GN", "CM", "BJ", "CD", "NE")

cinetpay/errors/__init__.py

@@ -0,0 +1,14 @@
+"""CinetPay SDK error hierarchy."""
+
+from cinetpay.errors.api_error import ApiError
+from cinetpay.errors.auth_error import AuthenticationError
+from cinetpay.errors.base import CinetPayError
+from cinetpay.errors.network_errors import NetworkError, TimeoutError
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "CinetPayError",
+    "NetworkError",
+    "TimeoutError",
+]

cinetpay/errors/api_error.py

@@ -0,0 +1,45 @@
+"""API error returned by the CinetPay backend."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cinetpay.errors.base import CinetPayError
+
+
+class ApiError(CinetPayError):
+    """Error returned by the CinetPay API (code + status + description).
+
+    Example::
+
+        try:
+            client.payment.initialize(request, "CI")
+        except ApiError as exc:
+            print(exc.api_code)     # 1200
+            print(exc.api_status)   # "TRANSACTION_EXIST"
+            print(exc.description)  # "La transaction existe deja"
+    """
+
+    __slots__ = ("api_code", "api_status", "description")
+
+    def __init__(self, api_code: int, api_status: str, description: str) -> None:
+        super().__init__(f"[{api_code}] {api_status}: {description}")
+        self.api_code: int = api_code
+        self.api_status: str = api_status
+        self.description: str = description
+
+    @classmethod
+    def from_response(cls, data: dict[str, Any]) -> ApiError:
+        """Build an :class:`ApiError` from a raw API response dict.
+
+        Args:
+            data: Raw JSON-decoded response body.
+
+        Returns:
+            A new :class:`ApiError` instance.
+        """
+        return cls(
+            api_code=int(data.get("code", 0)),
+            api_status=str(data.get("status", "UNKNOWN")),
+            description=str(data.get("description") or data.get("message") or ""),
+        )

cinetpay/errors/auth_error.py

@@ -0,0 +1,12 @@
+"""Authentication error — invalid credentials or missing JWT token."""
+
+from __future__ import annotations
+
+from cinetpay.errors.base import CinetPayError
+
+
+class AuthenticationError(CinetPayError):
+    """Raised when API credentials are invalid or the API did not return a JWT token."""
+
+    def __init__(self, message: str = "Authentication failed") -> None:
+        super().__init__(message)

cinetpay/errors/base.py

@@ -0,0 +1,18 @@
+"""Base exception for the CinetPay SDK."""
+
+from __future__ import annotations
+
+
+class CinetPayError(Exception):
+    """Base class for all CinetPay SDK errors.
+
+    All SDK errors inherit from this class, allowing a simple catch-all::
+
+        try:
+            client.payment.initialize(request, "CI")
+        except CinetPayError as exc:
+            ...
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)

cinetpay/errors/network_errors.py

@@ -0,0 +1,29 @@
+"""Network and timeout errors."""
+
+from __future__ import annotations
+
+from cinetpay.errors.base import CinetPayError
+
+
+class NetworkError(CinetPayError):
+    """Raised when an HTTP request fails (DNS, connection refused, etc.).
+
+    Attributes:
+        cause: The original exception that triggered the network failure.
+    """
+
+    def __init__(self, message: str, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.cause: BaseException | None = cause
+
+
+class TimeoutError(CinetPayError):  # noqa: A001 — intentional shadow of builtins.TimeoutError
+    """Raised when an HTTP request exceeds the configured timeout.
+
+    Attributes:
+        timeout_seconds: The timeout value in seconds.
+    """
+
+    def __init__(self, timeout_seconds: float) -> None:
+        super().__init__(f"Request timed out after {timeout_seconds}s")
+        self.timeout_seconds: float = timeout_seconds

cinetpay/http/__init__.py

@@ -0,0 +1,9 @@
+"""HTTP client module — sync and async wrappers around httpx."""
+
+from cinetpay.http.async_http_client import AsyncHttpClient
+from cinetpay.http.http_client import HttpClient
+
+__all__ = [
+    "AsyncHttpClient",
+    "HttpClient",
+]