zenopay-sdk 0.0.1__py3-none-any.whl

elusion/__init__.py

@@ -0,0 +1,3 @@
+"""Elusion SDK namespace package."""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

elusion/zenopay/__init__.py

@@ -0,0 +1,42 @@
+"""ZenoPay SDK for Python.
+
+A modern Python SDK for the ZenoPay payment API with support for USSD payments,
+order management, and webhook handling.
+"""
+
+__version__ = "0.0.1"
+__author__ = "Elution Hub"
+__email__ = "elusion.lab@gmail.com"
+
+from elusion.zenopay.client import ZenoPayClient as ZenoPay
+from elusion.zenopay.exceptions import (
+    ZenoPayError,
+    ZenoPayAPIError,
+    ZenoPayAuthenticationError,
+    ZenoPayValidationError,
+    ZenoPayNetworkError,
+)
+from elusion.zenopay.models import (
+    Order,
+    NewOrder,
+    OrderStatus,
+    WebhookEvent,
+    WebhookPayload,
+)
+
+__all__ = [
+    # Main client
+    "ZenoPay",
+    # Exceptions
+    "ZenoPayError",
+    "ZenoPayAPIError",
+    "ZenoPayAuthenticationError",
+    "ZenoPayValidationError",
+    "ZenoPayNetworkError",
+    # Models
+    "Order",
+    "NewOrder",
+    "OrderStatus",
+    "WebhookEvent",
+    "WebhookPayload",
+]

elusion/zenopay/client.py

@@ -0,0 +1,207 @@
+"""Main client for the ZenoPay SDK."""
+
+import logging
+from typing import Optional, Type
+from types import TracebackType
+
+from elusion.zenopay.config import ZenoPayConfig
+from elusion.zenopay.http import HTTPClient
+from elusion.zenopay.services import OrderService
+from elusion.zenopay.services import WebhookService
+
+logger = logging.getLogger(__name__)
+
+
+class ZenoPayClient:
+    """Main client for interacting with the ZenoPay API.
+
+    This client provides access to all ZenoPay services including order management,
+    payment processing, and webhook handling. It supports both async and sync operations.
+
+    Examples:
+        Basic usage:
+        >>> client = ZenoPayClient(account_id="zp87778")
+
+        Async usage:
+        >>> async with ZenoPayClient(account_id="zp87778") as client:
+        ...     order = await client.orders.create({
+        ...         "buyer_email": "jackson@gmail.com",
+        ...         "buyer_name": "Jackson Dastani",
+        ...         "buyer_phone": "0652449389",
+        ...         "amount": 1000,
+        ...         "webhook_url": "https://yourwebsite.com/webhook"
+        ...     })
+
+        Sync usage:
+        >>> with ZenoPayClient(account_id="zp87778") as client:
+        ...     order = client.orders.create_sync({
+        ...         "buyer_email": "jackson@gmail.com",
+        ...         "buyer_name": "Jackson Dastani",
+        ...         "buyer_phone": "0652449389",
+        ...         "amount": 1000
+        ...     })
+    """
+
+    def __init__(
+        self,
+        account_id: str,
+        api_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ):
+        """Initialize the ZenoPay client.
+
+        Args:
+            account_id: Your ZenoPay account ID (required).
+            api_key: API key (optional, can be set via environment variable).
+            secret_key: Secret key (optional, can be set via environment variable).
+            base_url: Base URL for the API (optional, defaults to production).
+            timeout: Request timeout in seconds (optional).
+            max_retries: Maximum number of retries for failed requests (optional).
+            **kwargs: Additional configuration options.
+
+        Examples:
+            >>> # Using environment variables for API keys
+            >>> client = ZenoPayClient(account_id="zp87778")
+
+            >>> # Explicit configuration
+            >>> client = ZenoPayClient(
+            ...     account_id="zp87778",
+            ...     api_key="your_api_key",
+            ...     secret_key="your_secret_key",
+            ...     timeout=30.0
+            ... )
+        """
+        self.config = ZenoPayConfig(
+            account_id=account_id,
+            api_key=api_key,
+            secret_key=secret_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.http_client = HTTPClient(self.config)
+
+        # Initialize services
+        self.orders = OrderService(self.http_client, self.config)
+        self.webhooks = WebhookService()
+
+        logger.info(f"ZenoPay client initialized for account: {account_id}")
+
+    async def __aenter__(self) -> "ZenoPayClient":
+        """Async context manager entry."""
+        await self.http_client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        """Async context manager exit."""
+        await self.http_client.__aexit__(exc_type, exc_val, exc_tb)
+        await self.http_client.__aexit__(exc_type, exc_val, exc_tb)
+
+    def __enter__(self) -> "ZenoPayClient":
+        """Sync context manager entry."""
+        self.http_client.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        """Sync context manager exit."""
+        self.http_client.__exit__(exc_type, exc_val, exc_tb)
+
+    async def close(self) -> None:
+        """Close the client and cleanup resources."""
+        await self.http_client.close()
+
+    def close_sync(self) -> None:
+        """Close the client and cleanup resources (sync version)."""
+        self.http_client.close_sync()
+
+    def test_connection(self) -> bool:
+        """Test the connection to ZenoPay API.
+
+        Returns:
+            True if connection is successful, False otherwise.
+
+        Examples:
+            >>> client = ZenoPayClient(account_id="zp87778")
+            >>> if client.test_connection():
+            ...     print("Connection successful!")
+            ... else:
+            ...     print("Connection failed!")
+        """
+        try:
+            self.orders.get_status_sync("test-connection-check")
+            return True
+        except Exception as e:
+            logger.debug(f"Connection test failed: {e}")
+            return False
+
+    async def test_connection_async(self) -> bool:
+        """Test the connection to ZenoPay API (async version).
+
+        Returns:
+            True if connection is successful, False otherwise.
+
+        Examples:
+            >>> async with ZenoPayClient(account_id="zp87778") as client:
+            ...     if await client.test_connection_async():
+            ...         print("Connection successful!")
+            ...     else:
+            ...         print("Connection failed!")
+        """
+        try:
+            await self.orders.get_status("test-connection-check")
+            return True
+        except Exception as e:
+            logger.debug(f"Connection test failed: {e}")
+            return False
+
+    @property
+    def account_id(self) -> str:
+        """Get the account ID."""
+        return self.config.account_id or ""
+
+    @property
+    def base_url(self) -> str:
+        """Get the base URL."""
+        return self.config.base_url
+
+    def get_config(self) -> ZenoPayConfig:
+        """Get the current configuration.
+
+        Returns:
+            Current ZenoPayConfig instance.
+        """
+        return self.config
+
+    def update_config(self, **kwargs: object) -> None:
+        """Update client configuration.
+
+        Args:
+            **kwargs: Configuration parameters to update.
+
+        Examples:
+            >>> client = ZenoPayClient(account_id="zp87778")
+            >>> client.update_config(timeout=60.0, max_retries=5)
+        """
+        for key, value in kwargs.items():
+            if hasattr(self.config, key):
+                setattr(self.config, key, value)
+            else:
+                logger.warning(f"Unknown configuration parameter: {key}")
+
+    def __repr__(self) -> str:
+        """String representation of the client."""
+        return f"ZenoPayClient(account_id='{self.account_id}', base_url='{self.base_url}')"

elusion/zenopay/config.py

@@ -0,0 +1,116 @@
+"""Configuration and constants for the ZenoPay SDK."""
+
+import os
+from typing import Dict, Optional
+from dotenv import load_dotenv
+
+# Load environment variables from .env file if it exists
+load_dotenv()
+
+# Default configuration
+DEFAULT_BASE_URL = "https://api.zeno.africa"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_DELAY = 1.0
+
+# Environment variable names
+ENV_API_KEY = "ZENOPAY_API_KEY"
+ENV_SECRET_KEY = "ZENOPAY_SECRET_KEY"
+ENV_ACCOUNT_ID = "ZENOPAY_ACCOUNT_ID"
+ENV_BASE_URL = "ZENOPAY_BASE_URL"
+ENV_TIMEOUT = "ZENOPAY_TIMEOUT"
+
+# HTTP headers
+DEFAULT_HEADERS = {
+    "User-Agent": "zenopay-python-sdk",
+    "Accept": "application/json",
+    "Content-Type": "application/x-www-form-urlencoded",
+}
+
+# API endpoints
+ENDPOINTS = {
+    "create_order": "",
+    "order_status": "/order-status",
+}
+
+# Payment statuses
+PAYMENT_STATUSES = {
+    "PENDING": "PENDING",
+    "COMPLETED": "COMPLETED",
+    "FAILED": "FAILED",
+    "CANCELLED": "CANCELLED",
+}
+
+
+class ZenoPayConfig:
+    """Configuration class for the ZenoPay SDK."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        account_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_delay: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """Initialize configuration.
+
+        Args:
+            api_key: ZenoPay API key. If not provided, will try to get from environment.
+            secret_key: ZenoPay secret key. If not provided, will try to get from environment.
+            account_id: ZenoPay account ID. If not provided, will try to get from environment.
+            base_url: Base URL for the ZenoPay API.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retries for failed requests.
+            retry_delay: Delay between retries in seconds.
+            headers: Additional headers to include in requests.
+        """
+        self.api_key = api_key or os.getenv(ENV_API_KEY)
+        self.secret_key = secret_key or os.getenv(ENV_SECRET_KEY)
+        self.account_id = account_id or os.getenv(ENV_ACCOUNT_ID)
+
+        if not self.account_id:
+            raise ValueError(f"Account ID is required. Set {ENV_ACCOUNT_ID} environment variable " "or pass account_id parameter.")
+
+        self.base_url = base_url or os.getenv(ENV_BASE_URL, DEFAULT_BASE_URL)
+
+        # Parse timeout from environment if provided
+        env_timeout = os.getenv(ENV_TIMEOUT)
+        if env_timeout:
+            try:
+                env_timeout_float = float(env_timeout)
+            except ValueError:
+                env_timeout_float = DEFAULT_TIMEOUT
+        else:
+            env_timeout_float = DEFAULT_TIMEOUT
+
+        self.timeout = timeout or env_timeout_float
+        self.max_retries = max_retries or DEFAULT_MAX_RETRIES
+        self.retry_delay = retry_delay or DEFAULT_RETRY_DELAY
+
+        # Merge default headers with custom headers
+        self.headers = DEFAULT_HEADERS.copy()
+        if headers:
+            self.headers.update(headers)
+
+    def get_endpoint_url(self, endpoint: str) -> str:
+        """Get the full URL for an endpoint.
+
+        Args:
+            endpoint: Endpoint key from ENDPOINTS dict.
+
+        Returns:
+            Full URL for the endpoint.
+        """
+        if endpoint not in ENDPOINTS:
+            raise ValueError(f"Unknown endpoint: {endpoint}")
+
+        endpoint_path = ENDPOINTS[endpoint]
+        if endpoint_path:
+            return f"{self.base_url.rstrip('/')}{endpoint_path}"
+        else:
+            # For create_order, the base URL is the endpoint
+            return self.base_url

elusion/zenopay/exceptions.py

@@ -0,0 +1,227 @@
+"""Custom exceptions for the ZenoPay SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class ZenoPayError(Exception):
+    """Base exception for all ZenoPay SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize ZenoPayError.
+
+        Args:
+            message: Error message.
+            status_code: HTTP status code if applicable.
+            response_data: Response data from the API if available.
+        """
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_data = response_data or {}
+
+
+class ZenoPayAPIError(ZenoPayError):
+    """Exception raised for API errors from the ZenoPay service."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        response_data: Optional[Dict[str, Any]] = None,
+        error_code: Optional[str] = None,
+    ) -> None:
+        """Initialize ZenoPayAPIError.
+
+        Args:
+            message: Error message from the API.
+            status_code: HTTP status code.
+            response_data: Full response data from the API.
+            error_code: Specific error code from the API.
+        """
+        super().__init__(message, status_code, response_data)
+        self.error_code = error_code
+
+
+class ZenoPayAuthenticationError(ZenoPayAPIError):
+    """Exception raised for authentication errors (401)."""
+
+    def __init__(
+        self,
+        message: str = "Invalid API key or secret key",
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, 401, response_data, "AUTHENTICATION_ERROR")
+
+
+class ZenoPayAuthorizationError(ZenoPayAPIError):
+    """Exception raised for authorization errors (403)."""
+
+    def __init__(
+        self,
+        message: str = "Insufficient permissions for this operation",
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, 403, response_data, "AUTHORIZATION_ERROR")
+
+
+class ZenoPayNotFoundError(ZenoPayAPIError):
+    """Exception raised when a resource is not found (404)."""
+
+    def __init__(
+        self,
+        message: str = "The requested resource was not found",
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, 404, response_data, "NOT_FOUND_ERROR")
+
+
+class ZenoPayValidationError(ZenoPayAPIError):
+    """Exception raised for validation errors (400, 422)."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 400,
+        response_data: Optional[Dict[str, Any]] = None,
+        validation_errors: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize ZenoPayValidationError.
+
+        Args:
+            message: Error message.
+            status_code: HTTP status code (400 or 422).
+            response_data: Response data from the API.
+            validation_errors: Detailed validation errors by field.
+        """
+        super().__init__(message, status_code, response_data, "VALIDATION_ERROR")
+        self.validation_errors = validation_errors or {}
+
+
+class ZenoPayRateLimitError(ZenoPayAPIError):
+    """Exception raised when rate limit is exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        response_data: Optional[Dict[str, Any]] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        """Initialize ZenoPayRateLimitError.
+
+        Args:
+            message: Error message.
+            response_data: Response data from the API.
+            retry_after: Number of seconds to wait before retrying.
+        """
+        super().__init__(message, 429, response_data, "RATE_LIMIT_ERROR")
+        self.retry_after = retry_after
+
+
+class ZenoPayServerError(ZenoPayAPIError):
+    """Exception raised for server errors (5xx)."""
+
+    def __init__(
+        self,
+        message: str = "Internal server error",
+        status_code: int = 500,
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, status_code, response_data, "SERVER_ERROR")
+
+
+class ZenoPayNetworkError(ZenoPayError):
+    """Exception raised for network-related errors."""
+
+    def __init__(
+        self,
+        message: str = "Network error occurred",
+        original_error: Optional[Exception] = None,
+    ) -> None:
+        """Initialize ZenoPayNetworkError.
+
+        Args:
+            message: Error message.
+            original_error: The original exception that caused this error.
+        """
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class ZenoPayTimeoutError(ZenoPayNetworkError):
+    """Exception raised when a request times out."""
+
+    def __init__(
+        self,
+        message: str = "Request timeout",
+        timeout_duration: Optional[float] = None,
+    ) -> None:
+        """Initialize ZenoPayTimeoutError.
+
+        Args:
+            message: Error message.
+            timeout_duration: The timeout duration that was exceeded.
+        """
+        super().__init__(message)
+        self.timeout_duration = timeout_duration
+
+
+class ZenoPayWebhookError(ZenoPayError):
+    """Exception raised for webhook-related errors."""
+
+    def __init__(
+        self,
+        message: str = "Webhook processing error",
+        webhook_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize ZenoPayWebhookError.
+
+        Args:
+            message: Error message.
+            webhook_data: The webhook data that caused the error.
+        """
+        super().__init__(message)
+        self.webhook_data = webhook_data or {}
+
+
+def create_api_error(
+    status_code: int,
+    message: str,
+    response_data: Optional[Dict[str, Any]] = None,
+    error_code: Optional[str] = None,
+) -> ZenoPayAPIError:
+    """Factory function to create appropriate API error based on status code.
+
+    Args:
+        status_code: HTTP status code.
+        message: Error message.
+        response_data: Response data from the API.
+        error_code: Specific error code from the API.
+
+    Returns:
+        Appropriate ZenoPayAPIError subclass instance.
+    """
+    if status_code == 401:
+        return ZenoPayAuthenticationError(message, response_data)
+    elif status_code == 403:
+        return ZenoPayAuthorizationError(message, response_data)
+    elif status_code == 404:
+        return ZenoPayNotFoundError(message, response_data)
+    elif status_code in (400, 422):
+        validation_errors = None
+        if response_data and "errors" in response_data:
+            validation_errors = response_data["errors"]
+        return ZenoPayValidationError(message, status_code, response_data, validation_errors)
+    elif status_code == 429:
+        retry_after = None
+        if response_data and "retry_after" in response_data:
+            retry_after = response_data["retry_after"]
+        return ZenoPayRateLimitError(message, response_data, retry_after)
+    elif status_code >= 500:
+        return ZenoPayServerError(message, status_code, response_data)
+    else:
+        return ZenoPayAPIError(message, status_code, response_data, error_code)

elusion/zenopay/http/__init__.py

@@ -0,0 +1,5 @@
+from elusion.zenopay.http.client import HTTPClient
+
+__all__ = [
+    "HTTPClient",
+]