cinetpay-python 0.1.0__py3-none-any.whl

cinetpay/http/async_http_client.py

@@ -0,0 +1,173 @@
+"""Asynchronous HTTP client wrapping :mod:`httpx`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from cinetpay.errors.api_error import ApiError
+from cinetpay.errors.network_errors import NetworkError, TimeoutError
+from cinetpay.logger import LoggerProtocol
+
+# Fields whose values must be masked in log output
+_SENSITIVE_KEYWORDS = frozenset({"password", "secret", "token", "api_key"})
+
+
+class AsyncHttpClient:
+    """Internal asynchronous HTTP client.
+
+    Wraps :class:`httpx.AsyncClient` with JSON defaults, timeout, Bearer auth,
+    sensitive field sanitization in logs, and error mapping to SDK exceptions.
+
+    .. note::
+        Internal — used by :class:`~cinetpay.async_client.AsyncCinetPayClient`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float,
+        logger: LoggerProtocol,
+    ) -> None:
+        self._base_url = base_url
+        self._timeout = timeout
+        self._logger = logger
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=httpx.Timeout(timeout),
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def post(self, path: str, body: Any, token: str | None = None) -> dict[str, Any]:
+        """Send a POST request and return the parsed JSON response.
+
+        Args:
+            path: API path (e.g. ``/v1/payment``).
+            body: Request body (will be JSON-encoded).
+            token: Optional JWT Bearer token.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            ApiError: If the API returns an error.
+            NetworkError: If the HTTP request fails.
+            TimeoutError: If the request exceeds the configured timeout.
+        """
+        return await self._request("POST", path, body=body, token=token)
+
+    async def get(self, path: str, token: str | None = None) -> dict[str, Any]:
+        """Send a GET request and return the parsed JSON response.
+
+        Args:
+            path: API path (e.g. ``/v1/balances``).
+            token: Optional JWT Bearer token.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            ApiError: If the API returns an error.
+            NetworkError: If the HTTP request fails.
+            TimeoutError: If the request exceeds the configured timeout.
+        """
+        return await self._request("GET", path, token=token)
+
+    async def close(self) -> None:
+        """Close the underlying :class:`httpx.AsyncClient`."""
+        await self._client.aclose()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        token: str | None = None,
+    ) -> dict[str, Any]:
+        headers: dict[str, str] = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+
+        if body is not None:
+            self._logger.debug(f"{method} {path}", {"body": _sanitize_body(body)})
+        else:
+            self._logger.debug(f"{method} {path}")
+
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                json=body,
+                headers=headers,
+            )
+            data: dict[str, Any] = response.json()
+
+            self._logger.debug(
+                f"{method} {path} -> {response.status_code}",
+                {"code": data.get("code"), "status": data.get("status")},
+            )
+
+            return self._handle_response(data, response.status_code, method, path)
+
+        except ApiError:
+            raise
+        except httpx.TimeoutException:
+            self._logger.error(f"{method} {path} -> timeout ({self._timeout}s)")
+            raise TimeoutError(self._timeout) from None
+        except httpx.HTTPError as exc:
+            self._logger.error(
+                f"{method} {path} -> network error",
+                {"message": str(exc)},
+            )
+            raise NetworkError(f"Request to {method} {path} failed", exc) from exc
+
+    def _handle_response(
+        self,
+        data: dict[str, Any],
+        http_status: int,
+        method: str,
+        path: str,
+    ) -> dict[str, Any]:
+        code = data.get("code")
+
+        if http_status >= 400 or (
+            code is not None
+            and code not in (200, 100, 2001, 2002)
+        ):
+            if data.get("description") or (code is not None and http_status >= 400):
+                error = ApiError.from_response(data)
+                self._logger.error(
+                    f"{method} {path} -> API error",
+                    {
+                        "api_code": error.api_code,
+                        "api_status": error.api_status,
+                        "description": error.description,
+                    },
+                )
+                raise error
+
+        return data
+
+
+def _sanitize_body(body: Any) -> Any:
+    """Mask sensitive fields (credentials, tokens) in log output."""
+    if not isinstance(body, dict):
+        return body
+    sanitized = dict(body)
+    for key in sanitized:
+        lower = key.lower()
+        if any(kw in lower for kw in _SENSITIVE_KEYWORDS):
+            sanitized[key] = "***"
+    return sanitized

cinetpay/http/http_client.py

@@ -0,0 +1,173 @@
+"""Synchronous HTTP client wrapping :mod:`httpx`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from cinetpay.errors.api_error import ApiError
+from cinetpay.errors.network_errors import NetworkError, TimeoutError
+from cinetpay.logger import LoggerProtocol
+
+# Fields whose values must be masked in log output
+_SENSITIVE_KEYWORDS = frozenset({"password", "secret", "token", "api_key"})
+
+
+class HttpClient:
+    """Internal synchronous HTTP client.
+
+    Wraps :class:`httpx.Client` with JSON defaults, timeout, Bearer auth,
+    sensitive field sanitization in logs, and error mapping to SDK exceptions.
+
+    .. note::
+        Internal — used by :class:`~cinetpay.client.CinetPayClient`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float,
+        logger: LoggerProtocol,
+    ) -> None:
+        self._base_url = base_url
+        self._timeout = timeout
+        self._logger = logger
+        self._client = httpx.Client(
+            base_url=base_url,
+            timeout=httpx.Timeout(timeout),
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def post(self, path: str, body: Any, token: str | None = None) -> dict[str, Any]:
+        """Send a POST request and return the parsed JSON response.
+
+        Args:
+            path: API path (e.g. ``/v1/payment``).
+            body: Request body (will be JSON-encoded).
+            token: Optional JWT Bearer token.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            ApiError: If the API returns an error.
+            NetworkError: If the HTTP request fails.
+            TimeoutError: If the request exceeds the configured timeout.
+        """
+        return self._request("POST", path, body=body, token=token)
+
+    def get(self, path: str, token: str | None = None) -> dict[str, Any]:
+        """Send a GET request and return the parsed JSON response.
+
+        Args:
+            path: API path (e.g. ``/v1/balances``).
+            token: Optional JWT Bearer token.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            ApiError: If the API returns an error.
+            NetworkError: If the HTTP request fails.
+            TimeoutError: If the request exceeds the configured timeout.
+        """
+        return self._request("GET", path, token=token)
+
+    def close(self) -> None:
+        """Close the underlying :class:`httpx.Client`."""
+        self._client.close()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        token: str | None = None,
+    ) -> dict[str, Any]:
+        headers: dict[str, str] = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+
+        if body is not None:
+            self._logger.debug(f"{method} {path}", {"body": _sanitize_body(body)})
+        else:
+            self._logger.debug(f"{method} {path}")
+
+        try:
+            response = self._client.request(
+                method,
+                path,
+                json=body,
+                headers=headers,
+            )
+            data: dict[str, Any] = response.json()
+
+            self._logger.debug(
+                f"{method} {path} -> {response.status_code}",
+                {"code": data.get("code"), "status": data.get("status")},
+            )
+
+            return self._handle_response(data, response.status_code, method, path)
+
+        except ApiError:
+            raise
+        except httpx.TimeoutException:
+            self._logger.error(f"{method} {path} -> timeout ({self._timeout}s)")
+            raise TimeoutError(self._timeout) from None
+        except httpx.HTTPError as exc:
+            self._logger.error(
+                f"{method} {path} -> network error",
+                {"message": str(exc)},
+            )
+            raise NetworkError(f"Request to {method} {path} failed", exc) from exc
+
+    def _handle_response(
+        self,
+        data: dict[str, Any],
+        http_status: int,
+        method: str,
+        path: str,
+    ) -> dict[str, Any]:
+        code = data.get("code")
+
+        if http_status >= 400 or (
+            code is not None
+            and code not in (200, 100, 2001, 2002)
+        ):
+            if data.get("description") or (code is not None and http_status >= 400):
+                error = ApiError.from_response(data)
+                self._logger.error(
+                    f"{method} {path} -> API error",
+                    {
+                        "api_code": error.api_code,
+                        "api_status": error.api_status,
+                        "description": error.description,
+                    },
+                )
+                raise error
+
+        return data
+
+
+def _sanitize_body(body: Any) -> Any:
+    """Mask sensitive fields (credentials, tokens) in log output."""
+    if not isinstance(body, dict):
+        return body
+    sanitized = dict(body)
+    for key in sanitized:
+        lower = key.lower()
+        if any(kw in lower for kw in _SENSITIVE_KEYWORDS):
+            sanitized[key] = "***"
+    return sanitized

cinetpay/logger.py

@@ -0,0 +1,70 @@
+"""Pluggable logging interface for the CinetPay SDK."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LoggerProtocol(Protocol):
+    """Interface for injectable loggers.
+
+    Implement this protocol to plug in your own logger (structlog, loguru, etc.)::
+
+        import structlog
+
+        log = structlog.get_logger()
+        client = CinetPayClient(
+            credentials={...},
+            logger=MyStructlogAdapter(log),
+        )
+    """
+
+    def debug(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log request/response details, cached tokens, etc."""
+        ...
+
+    def warn(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log token refresh retries, fallbacks."""
+        ...
+
+    def error(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log API errors, network errors, timeouts."""
+        ...
+
+
+class StandardLibLogger:
+    """Logger backed by the Python standard library :mod:`logging`.
+
+    Writes messages with a ``[cinetpay]`` prefix. Used when ``debug=True``
+    is passed without a custom logger.
+    """
+
+    def __init__(self, name: str = "cinetpay") -> None:
+        self._logger = logging.getLogger(name)
+
+    def debug(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log a debug-level message with optional structured data."""
+        self._logger.debug("[cinetpay] %s %s", message, data or "")
+
+    def warn(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log a warning-level message with optional structured data."""
+        self._logger.warning("[cinetpay] %s %s", message, data or "")
+
+    def error(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log an error-level message with optional structured data."""
+        self._logger.error("[cinetpay] %s %s", message, data or "")
+
+
+class NoopLogger:
+    """Silent logger — produces no output. Used by default."""
+
+    def debug(self, message: str = "", data: dict[str, Any] | None = None) -> None:
+        """Accept and discard a debug-level message (no-op)."""
+
+    def warn(self, message: str = "", data: dict[str, Any] | None = None) -> None:
+        """Accept and discard a warning-level message (no-op)."""
+
+    def error(self, message: str = "", data: dict[str, Any] | None = None) -> None:
+        """Accept and discard an error-level message (no-op)."""

cinetpay/types/__init__.py

@@ -0,0 +1,59 @@
+"""Public type re-exports for the CinetPay SDK."""
+
+from cinetpay.types.balance import Balance
+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,
+    TokenStoreProtocol,
+)
+from cinetpay.types.payment import (
+    PaymentDetails,
+    PaymentRequest,
+    PaymentResponse,
+    PaymentStatus,
+    PaymentStatusUser,
+)
+from cinetpay.types.transfer import (
+    TransferRequest,
+    TransferResponse,
+    TransferStatus,
+    TransferStatusUser,
+)
+from cinetpay.types.webhook import WebhookPayload, WebhookUser
+
+__all__ = [
+    # config
+    "API_KEY_PREFIX_LIVE",
+    "API_KEY_PREFIX_TEST",
+    "AsyncTokenStoreProtocol",
+    "ClientConfig",
+    "CountryCredentials",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_TOKEN_TTL",
+    "PRODUCTION_BASE_URL",
+    "TokenStoreProtocol",
+    # payment
+    "PaymentDetails",
+    "PaymentRequest",
+    "PaymentResponse",
+    "PaymentStatus",
+    "PaymentStatusUser",
+    # transfer
+    "TransferRequest",
+    "TransferResponse",
+    "TransferStatus",
+    "TransferStatusUser",
+    # balance
+    "Balance",
+    # webhook
+    "WebhookPayload",
+    "WebhookUser",
+]

cinetpay/types/balance.py

@@ -0,0 +1,35 @@
+"""Balance type and deserialization helper."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cinetpay.constants.currencies import Currency
+
+
+@dataclass(frozen=True, slots=True)
+class Balance:
+    """Merchant account balance returned by ``client.balance.get()``.
+
+    Attributes:
+        code: HTTP response code.
+        status: Textual response status.
+        available_balance: Available balance (used for transfers).
+        currency: Account currency.
+    """
+
+    code: int
+    status: str
+    available_balance: str
+    currency: Currency
+
+
+def to_balance(raw: dict[str, Any]) -> Balance:
+    """Transform a raw API response dict into a typed :class:`Balance`."""
+    return Balance(
+        code=int(raw.get("code", 0)),
+        status=str(raw.get("status", "")),
+        available_balance=str(raw.get("available_balance", "")),
+        currency=raw.get("currency", "XOF"),
+    )

cinetpay/types/config.py

@@ -0,0 +1,139 @@
+"""Configuration types for the CinetPay SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from cinetpay.logger import LoggerProtocol
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_BASE_URL: str = "https://api.cinetpay.net"
+"""Base URL for the CinetPay Sandbox API."""
+
+PRODUCTION_BASE_URL: str = "https://api.cinetpay.co"
+"""Base URL for the CinetPay Production API."""
+
+API_KEY_PREFIX_TEST: str = "sk_test_"
+"""Prefix for sandbox API keys."""
+
+API_KEY_PREFIX_LIVE: str = "sk_live_"
+"""Prefix for production API keys."""
+
+DEFAULT_TOKEN_TTL: int = 82_800
+"""Default JWT token cache TTL in seconds (23 h — safety margin under the 86 400 s API TTL)."""
+
+DEFAULT_TIMEOUT: float = 30.0
+"""Default HTTP request timeout in seconds."""
+
+# ---------------------------------------------------------------------------
+# Dataclasses & Protocols
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class CountryCredentials:
+    """API credentials for a single country.
+
+    Attributes:
+        api_key: API key provided by CinetPay (``sk_test_...`` or ``sk_live_...``).
+        api_password: API password provided by CinetPay.
+    """
+
+    api_key: str
+    api_password: str
+
+    def __repr__(self) -> str:
+        """Mask credentials in repr to prevent accidental leakage in logs."""
+        masked_key = self.api_key[:8] + "***" if len(self.api_key) > 8 else "***"
+        return f"CountryCredentials(api_key='{masked_key}', api_password='***')"
+
+
+@runtime_checkable
+class TokenStoreProtocol(Protocol):
+    """Interface for JWT token storage backends.
+
+    Implement this protocol to use Redis, a database, or any other shared store::
+
+        class RedisTokenStore:
+            def get(self, key: str) -> str | None:
+                return redis.get(key)
+
+            def set(self, key: str, value: str, ttl_seconds: int) -> None:
+                redis.setex(key, ttl_seconds, value)
+
+            def delete(self, key: str) -> None:
+                redis.delete(key)
+    """
+
+    def get(self, key: str) -> str | None:
+        """Retrieve a token from the cache. Return ``None`` if absent or expired."""
+        ...
+
+    def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Store a token with a TTL in seconds."""
+        ...
+
+    def delete(self, key: str) -> None:
+        """Remove a token from the cache."""
+        ...
+
+
+@runtime_checkable
+class AsyncTokenStoreProtocol(Protocol):
+    """Async interface for JWT token storage backends.
+
+    Implement this protocol for async stores (aioredis, etc.)::
+
+        class AsyncRedisTokenStore:
+            async def get(self, key: str) -> str | None: ...
+            async def set(self, key: str, value: str, ttl_seconds: int) -> None: ...
+            async def delete(self, key: str) -> None: ...
+    """
+
+    async def get(self, key: str) -> str | None:
+        """Retrieve a token from the cache. Return ``None`` if absent or expired."""
+        ...
+
+    async def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Store a token with a TTL in seconds."""
+        ...
+
+    async def delete(self, key: str) -> None:
+        """Remove a token from the cache."""
+        ...
+
+
+@dataclass(slots=True)
+class ClientConfig:
+    """Configuration for the CinetPay client.
+
+    Example::
+
+        config = ClientConfig(
+            credentials={
+                "CI": CountryCredentials(api_key="sk_test_...", api_password="..."),
+                "SN": CountryCredentials(api_key="sk_test_...", api_password="..."),
+            },
+        )
+
+    Attributes:
+        credentials: Credentials keyed by ISO 3166-1 alpha-2 country code.
+        base_url: API base URL. Auto-detected from key prefixes if omitted.
+        token_ttl: JWT token cache TTL in seconds (default: 82 800 = 23 h).
+        token_store: Custom sync token store (default: in-memory).
+        timeout: HTTP request timeout in seconds (default: 30).
+        debug: Enable logging with the standard library logger.
+        logger: Custom logger implementing :class:`~cinetpay.logger.LoggerProtocol`.
+    """
+
+    credentials: dict[str, CountryCredentials]
+    base_url: str | None = None
+    token_ttl: int = field(default=DEFAULT_TOKEN_TTL)
+    token_store: TokenStoreProtocol | None = None
+    timeout: float = field(default=DEFAULT_TIMEOUT)
+    debug: bool = False
+    logger: LoggerProtocol | None = None