cinetpay-python 0.1.0__py3-none-any.whl

cinetpay/api/transfer.py

@@ -0,0 +1,118 @@
+"""Synchronous transfer API — create transfers and check status."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from cinetpay.auth.authenticator import Authenticator
+from cinetpay.errors.api_error import ApiError
+from cinetpay.http.http_client import HttpClient
+from cinetpay.types.transfer import (
+    TransferRequest,
+    TransferResponse,
+    TransferStatus,
+    serialize_transfer_request,
+    to_transfer_response,
+    to_transfer_status,
+)
+from cinetpay.validation import validate_transfer_request
+
+
+class TransferApi:
+    """CinetPay money transfer API.
+
+    Accessible via ``client.transfer``.
+
+    Example::
+
+        transfer = client.transfer.create(request, "CI")
+        status = client.transfer.get_status(transfer.transaction_id, "CI")
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClient,
+        authenticators: dict[str, Authenticator],
+    ) -> None:
+        self._http_client = http_client
+        self._authenticators = authenticators
+
+    def create(
+        self,
+        request: TransferRequest,
+        country: str,
+    ) -> TransferResponse:
+        """Create a money transfer to a mobile money number.
+
+        Args:
+            request: Transfer parameters (amount, currency, phone, operator, etc.).
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Response containing initial status and transaction identifiers.
+
+        Raises:
+            ApiError: If the API returns an error (e.g. INSUFFICIENT_BALANCE).
+            ValidationError: If a request field is invalid.
+            TypeError: If the country is not configured.
+        """
+        validate_transfer_request(request)
+        auth = self._resolve_authenticator(country)
+        body = serialize_transfer_request(request)
+
+        try:
+            token = auth.get_token()
+            raw: dict[str, Any] = self._http_client.post("/v1/transfer", body, token)
+            return to_transfer_response(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = auth.force_refresh()
+                raw = self._http_client.post("/v1/transfer", body, token)
+                return to_transfer_response(raw)
+            raise
+
+    def get_status(
+        self,
+        transaction_id: str,
+        country: str,
+    ) -> TransferStatus:
+        """Retrieve the current status of a transfer.
+
+        Args:
+            transaction_id: CinetPay transaction ID or ``merchant_transaction_id``.
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Transfer status with recipient information.
+
+        Raises:
+            ApiError: If the transaction is not found (NOT_FOUND).
+        """
+        auth = self._resolve_authenticator(country)
+        path = f"/v1/transfer/{quote(transaction_id, safe='')}"
+
+        try:
+            token = auth.get_token()
+            raw: dict[str, Any] = self._http_client.get(path, token)
+            return to_transfer_status(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = auth.force_refresh()
+                raw = self._http_client.get(path, token)
+                return to_transfer_status(raw)
+            raise
+
+    def _resolve_authenticator(self, country: str) -> Authenticator:
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            available = ", ".join(self._authenticators.keys())
+            raise TypeError(
+                f'No credentials configured for country "{key}". Available: {available}'
+            )
+        return auth
+
+
+def _is_token_expired(error: ApiError) -> bool:
+    return error.api_code == 1003 or error.api_status == "EXPIRED_TOKEN"

cinetpay/async_client.py

@@ -0,0 +1,290 @@
+"""Asynchronous CinetPay client — async entry point of the SDK."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from cinetpay.api.async_balance import AsyncBalanceApi
+from cinetpay.api.async_payment import AsyncPaymentApi
+from cinetpay.api.async_transfer import AsyncTransferApi
+from cinetpay.auth.async_authenticator import AsyncAuthenticator
+from cinetpay.auth.token_store import MemoryTokenStore
+from cinetpay.http.async_http_client import AsyncHttpClient
+from cinetpay.logger import LoggerProtocol, NoopLogger, StandardLibLogger
+from cinetpay.types.config import (
+    API_KEY_PREFIX_LIVE,
+    API_KEY_PREFIX_TEST,
+    AsyncTokenStoreProtocol,
+    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 _AsyncMemoryTokenStore:
+    """Async adapter around the sync :class:`MemoryTokenStore`."""
+
+    def __init__(self) -> None:
+        self._store = MemoryTokenStore()
+
+    async def get(self, key: str) -> str | None:
+        """Retrieve a token from the in-memory cache.
+
+        Args:
+            key: Cache key (e.g. ``cinetpay_token_ci``).
+
+        Returns:
+            The token string, or ``None`` if absent or expired.
+        """
+        return self._store.get(key)
+
+    async 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._store.set(key, value, ttl_seconds)
+
+    async def delete(self, key: str) -> None:
+        """Remove a token from the in-memory cache.
+
+        Args:
+            key: Cache key to delete.
+        """
+        self._store.delete(key)
+
+
+class AsyncCinetPayClient:
+    """Asynchronous CinetPay SDK client.
+
+    Equivalent of :class:`~cinetpay.client.CinetPayClient` for async contexts
+    (FastAPI, aiohttp, etc.).
+
+    Example::
+
+        from cinetpay import AsyncCinetPayClient, ClientConfig, CountryCredentials
+
+        async with AsyncCinetPayClient(ClientConfig(
+            credentials={
+                "CI": CountryCredentials(api_key="sk_test_...", api_password="..."),
+            },
+        )) as client:
+            balance = await client.balance.get("CI")
+
+    Attributes:
+        payment: Async web payment API (initialize, get_status).
+        transfer: Async money transfer API (create, get_status).
+        balance: Async merchant balance API (get).
+    """
+
+    payment: AsyncPaymentApi
+    """Async web payment API -- initialization and status check."""
+
+    transfer: AsyncTransferApi
+    """Async money transfer API -- send and check status."""
+
+    balance: AsyncBalanceApi
+    """Async 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
+
+        # For async, we need an async-compatible token store
+        async_token_store: AsyncTokenStoreProtocol
+        if config.token_store is not None and isinstance(config.token_store, AsyncTokenStoreProtocol):
+            async_token_store = config.token_store  # type: ignore[assignment]
+        else:
+            async_token_store = _AsyncMemoryTokenStore()
+
+        # Resolve logger
+        logger: LoggerProtocol
+        if config.logger is not None:
+            logger = config.logger
+        elif config.debug:
+            logger = StandardLibLogger()
+        else:
+            logger = NoopLogger()
+
+        # Detect environment
+        entries = list(credentials.items())
+        detected_env = _detect_environment(entries, logger)
+
+        # Resolve base URL
+        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 coherence
+        _validate_key_url_coherence(detected_env, base_url, logger)
+
+        # Enforce HTTPS
+        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
+        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."
+            )
+
+        if not parsed.scheme or not parsed.hostname:
+            raise TypeError(f'base_url "{base_url}" is not a valid URL.')
+
+        # Build async HTTP client and authenticators
+        http_client = AsyncHttpClient(base_url, timeout, logger)
+
+        self._authenticators: dict[str, AsyncAuthenticator] = {}
+        for country, creds in entries:
+            key = country.upper()
+            self._authenticators[key] = AsyncAuthenticator(
+                http_client, key, creds, token_ttl, async_token_store, logger,
+            )
+
+        self.payment = AsyncPaymentApi(http_client, self._authenticators)
+        self.transfer = AsyncTransferApi(http_client, self._authenticators)
+        self.balance = AsyncBalanceApi(http_client, self._authenticators)
+
+        self._http_client = http_client
+        self._logger = logger
+
+        logger.debug("AsyncCinetPayClient 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."""
+        return list(self._authenticators.keys())
+
+    async def revoke_token(self, country: str) -> None:
+        """Revoke the cached JWT token for a country.
+
+        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())}"
+            )
+        await auth.clear_cache()
+
+    async def revoke_all_tokens(self) -> None:
+        """Revoke all cached JWT tokens for all configured countries."""
+        for auth in self._authenticators.values():
+            await auth.clear_cache()
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client and release resources."""
+        await self._http_client.close()
+
+    async def __aenter__(self) -> AsyncCinetPayClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        """Prevent credential leakage via repr()."""
+        return f"AsyncCinetPayClient(countries={self.countries()!r})"
+
+
+# ---------------------------------------------------------------------------
+# Private helpers (shared logic with sync client)
+# ---------------------------------------------------------------------------
+
+
+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/auth/__init__.py

@@ -0,0 +1,11 @@
+"""Authentication module — token store, sync and async authenticators."""
+
+from cinetpay.auth.authenticator import Authenticator
+from cinetpay.auth.async_authenticator import AsyncAuthenticator
+from cinetpay.auth.token_store import MemoryTokenStore
+
+__all__ = [
+    "AsyncAuthenticator",
+    "Authenticator",
+    "MemoryTokenStore",
+]

cinetpay/auth/async_authenticator.py

@@ -0,0 +1,119 @@
+"""Asynchronous JWT authenticator with asyncio.Lock stampede guard."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from cinetpay.errors.auth_error import AuthenticationError
+from cinetpay.http.async_http_client import AsyncHttpClient
+from cinetpay.logger import LoggerProtocol
+from cinetpay.types.config import AsyncTokenStoreProtocol, CountryCredentials
+
+
+class AsyncAuthenticator:
+    """Async JWT authenticator for a single country.
+
+    Equivalent of :class:`~cinetpay.auth.authenticator.Authenticator` but uses
+    :class:`asyncio.Lock` for the stampede guard and ``await`` for all I/O.
+
+    .. note::
+        Internal — used by :class:`~cinetpay.async_client.AsyncCinetPayClient`.
+        Do not instantiate directly.
+    """
+
+    def __init__(
+        self,
+        http_client: AsyncHttpClient,
+        country: str,
+        credentials: CountryCredentials,
+        token_ttl: int,
+        token_store: AsyncTokenStoreProtocol,
+        logger: LoggerProtocol,
+    ) -> None:
+        self._http_client = http_client
+        self._country = country
+        self._token_ttl = token_ttl
+        self._token_store = token_store
+        self._logger = logger
+        self._cache_key = f"cinetpay_token_{country.lower()}"
+
+        # Name-mangled to prevent accidental leakage
+        self.__api_key = credentials.api_key
+        self.__api_password = credentials.api_password
+
+        # Stampede guard
+        self._lock = asyncio.Lock()
+
+    async def get_token(self) -> str:
+        """Return a valid JWT token (from cache or freshly obtained).
+
+        Uses an :class:`asyncio.Lock` to prevent token stampede.
+
+        Returns:
+            JWT Bearer token.
+
+        Raises:
+            AuthenticationError: If the API does not return a token.
+        """
+        cached = await self._token_store.get(self._cache_key)
+        if cached is not None:
+            self._logger.debug(f"Token cache hit for {self._country}")
+            return cached
+
+        self._logger.debug(f"Token cache miss for {self._country}, authenticating...")
+
+        async with self._lock:
+            # Double-check after acquiring the lock
+            cached = await self._token_store.get(self._cache_key)
+            if cached is not None:
+                self._logger.debug(f"Token cache hit for {self._country} (after lock)")
+                return cached
+            return await self._authenticate()
+
+    async def force_refresh(self) -> str:
+        """Force token renewal by clearing cache then re-authenticating.
+
+        Returns:
+            New JWT token.
+
+        Raises:
+            AuthenticationError: If the API does not return a token.
+        """
+        self._logger.warn(f"Force refreshing token for {self._country} (expired or invalid)")
+        await self._token_store.delete(self._cache_key)
+        return await self._authenticate()
+
+    async def clear_cache(self) -> None:
+        """Delete the cached token for this country."""
+        await self._token_store.delete(self._cache_key)
+
+    def __repr__(self) -> str:
+        """Prevent credential leakage in logs and stack traces."""
+        return f"AsyncAuthenticator(country={self._country!r}, cache_key={self._cache_key!r})"
+
+    async def _authenticate(self) -> str:
+        """Call ``POST /v1/oauth/login`` and cache the returned token."""
+        try:
+            data: dict[str, Any] = await self._http_client.post(
+                "/v1/oauth/login",
+                {
+                    "api_key": self.__api_key,
+                    "api_password": self.__api_password,
+                },
+            )
+        except Exception:
+            raise AuthenticationError(
+                f"Authentication failed for country {self._country}"
+            ) from None
+
+        access_token = data.get("access_token")
+        if not access_token:
+            raise AuthenticationError(
+                f"Authentication failed for country {self._country}: "
+                "no access_token in response"
+            )
+
+        await self._token_store.set(self._cache_key, access_token, self._token_ttl)
+        self._logger.debug(f"Token cached for {self._country} (TTL: {self._token_ttl}s)")
+        return access_token

cinetpay/auth/authenticator.py

@@ -0,0 +1,140 @@
+"""Synchronous JWT authenticator with stampede guard."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from cinetpay.errors.auth_error import AuthenticationError
+from cinetpay.http.http_client import HttpClient
+from cinetpay.logger import LoggerProtocol
+from cinetpay.types.config import CountryCredentials, TokenStoreProtocol
+
+
+class Authenticator:
+    """Manages JWT authentication for a single country.
+
+    Each CinetPay country has its own credentials (``api_key`` / ``api_password``).
+    The Authenticator obtains a JWT via ``POST /v1/oauth/login``, caches it in the
+    :class:`~cinetpay.types.config.TokenStoreProtocol`, and auto-renews on expiry.
+
+    Credentials are stored in name-mangled attributes and never exposed via
+    ``repr()``, ``str()``, or ``vars()``.
+
+    .. note::
+        Internal — used by :class:`~cinetpay.client.CinetPayClient`.
+        Do not instantiate directly.
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClient,
+        country: str,
+        credentials: CountryCredentials,
+        token_ttl: int,
+        token_store: TokenStoreProtocol,
+        logger: LoggerProtocol,
+    ) -> None:
+        self._http_client = http_client
+        self._country = country
+        self._token_ttl = token_ttl
+        self._token_store = token_store
+        self._logger = logger
+        self._cache_key = f"cinetpay_token_{country.lower()}"
+
+        # Name-mangled to prevent accidental leakage
+        self.__api_key = credentials.api_key
+        self.__api_password = credentials.api_password
+
+        # Stampede guard: only one thread authenticates at a time
+        self._lock = threading.Lock()
+
+    def get_token(self) -> str:
+        """Return a valid JWT token (from cache or freshly obtained).
+
+        Uses a :class:`threading.Lock` to prevent token stampede: if multiple
+        threads call this concurrently with an empty cache, only one HTTP call
+        is made.
+
+        Returns:
+            JWT Bearer token.
+
+        Raises:
+            AuthenticationError: If the API does not return a token.
+        """
+        cached = self._token_store.get(self._cache_key)
+        if cached is not None:
+            self._logger.debug(f"Token cache hit for {self._country}")
+            return cached
+
+        self._logger.debug(f"Token cache miss for {self._country}, authenticating...")
+
+        with self._lock:
+            # Double-check after acquiring the lock (another thread may have filled the cache)
+            cached = self._token_store.get(self._cache_key)
+            if cached is not None:
+                self._logger.debug(f"Token cache hit for {self._country} (after lock)")
+                return cached
+            return self._authenticate()
+
+    def force_refresh(self) -> str:
+        """Force token renewal by clearing the cache then re-authenticating.
+
+        Called automatically by API classes when the API returns
+        ``EXPIRED_TOKEN`` (code 1003).
+
+        Returns:
+            New JWT token.
+
+        Raises:
+            AuthenticationError: If the API does not return a token.
+        """
+        self._logger.warn(f"Force refreshing token for {self._country} (expired or invalid)")
+        self._token_store.delete(self._cache_key)
+        return self._authenticate()
+
+    def clear_cache(self) -> None:
+        """Delete the cached token for this country.
+
+        Useful to force re-authentication on the next API call.
+        """
+        self._token_store.delete(self._cache_key)
+
+    def __repr__(self) -> str:
+        """Prevent credential leakage in logs and stack traces."""
+        return f"Authenticator(country={self._country!r}, cache_key={self._cache_key!r})"
+
+    def _authenticate(self) -> str:
+        """Call ``POST /v1/oauth/login`` and cache the returned token.
+
+        Returns:
+            JWT token.
+
+        Raises:
+            AuthenticationError: If the response is missing ``access_token``
+                or the HTTP call fails.
+        """
+        try:
+            data: dict[str, Any] = self._http_client.post(
+                "/v1/oauth/login",
+                {
+                    "api_key": self.__api_key,
+                    "api_password": self.__api_password,
+                },
+            )
+        except Exception:
+            # Sanitize to prevent credential leakage in stack traces
+            raise AuthenticationError(
+                f"Authentication failed for country {self._country}"
+            ) from None
+
+        access_token = data.get("access_token")
+        if not access_token:
+            raise AuthenticationError(
+                f"Authentication failed for country {self._country}: "
+                "no access_token in response"
+            )
+
+        self._token_store.set(self._cache_key, access_token, self._token_ttl)
+        self._logger.debug(f"Token cached for {self._country} (TTL: {self._token_ttl}s)")
+        return access_token