zenopay-sdk 0.0.1__py3-none-any.whl

elusion/zenopay/services/base.py

@@ -0,0 +1,175 @@
+"""Base service class for all ZenoPay SDK services."""
+
+from typing import Any, Dict, Type, TypeVar, Union
+
+from pydantic import BaseModel, ValidationError
+
+from elusion.zenopay.config import ZenoPayConfig
+from elusion.zenopay.exceptions import ZenoPayValidationError
+from elusion.zenopay.http import HTTPClient
+from elusion.zenopay.models.common import APIResponse
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class BaseService:
+    """Base class for all API services."""
+
+    def __init__(self, http_client: HTTPClient, config: ZenoPayConfig) -> None:
+        """Initialize the service.
+
+        Args:
+            http_client: HTTP client instance.
+            config: ZenoPay configuration.
+        """
+        self.http_client = http_client
+        self.config = config
+
+    def _build_url(self, endpoint: str) -> str:
+        """Build a full URL for an API endpoint.
+
+        Args:
+            endpoint: The endpoint name from config.ENDPOINTS.
+
+        Returns:
+            Full URL for the endpoint.
+        """
+        return self.config.get_endpoint_url(endpoint)
+
+    def _prepare_request_data(self, data: Union[BaseModel, Dict[str, Any]]) -> Dict[str, Any]:
+        """Prepare and validate data for API requests.
+
+        Args:
+            data: Data to prepare for the request.
+
+        Returns:
+            Prepared data dictionary for form submission.
+
+        Raises:
+            ZenoPayValidationError: If validation fails.
+        """
+        if isinstance(data, BaseModel):
+            request_data = data.model_dump(exclude_unset=True, by_alias=True)
+        else:
+            request_data = data.copy()
+
+        request_data.update(
+            {
+                "account_id": self.config.account_id,
+                "api_key": self.config.api_key or "null",
+                "secret_key": self.config.secret_key or "null",
+            }
+        )
+
+        return request_data
+
+    def _parse_response(
+        self,
+        response_data: Dict[str, Any],
+        model_class: Type[T],
+    ) -> APIResponse[T]:
+        """Parse API response into typed models.
+
+        Args:
+            response_data: Raw response data from API.
+            model_class: Pydantic model class to parse data into.
+
+        Returns:
+            Parsed response with typed data.
+
+        Raises:
+            ZenoPayValidationError: If response parsing fails.
+        """
+        try:
+            if "success" in response_data:
+                success = response_data.get("success", True)
+                data = response_data.get("data", response_data)
+                message = response_data.get("message")
+                error = response_data.get("error")
+
+                if success and data:
+                    parsed_data = model_class.model_validate(data)
+                else:
+                    # Error response
+                    raise ZenoPayValidationError(error or "Unknown API error")
+            else:
+                # Direct data response
+                parsed_data = model_class.model_validate(response_data)
+                success = True
+                message = None
+                error = None
+
+            return APIResponse[model_class](
+                success=success,
+                data=parsed_data,
+                message=message,
+                error=error,
+            )
+
+        except ValidationError as e:
+            raise ZenoPayValidationError(
+                f"Failed to parse response: {str(e)}",
+                validation_errors={"errors": e.errors()},
+            ) from e
+
+    async def post_async(
+        self,
+        endpoint: str,
+        data: Union[BaseModel, Dict[str, Any]],
+        model_class: Type[T],
+    ) -> APIResponse[T]:
+        """Make an async POST request.
+
+        Args:
+            endpoint: API endpoint name.
+            data: Data to send in the request.
+            model_class: Model class to parse response into.
+
+        Returns:
+            Parsed API response.
+        """
+        url = self._build_url(endpoint)
+        prepared_data = self._prepare_request_data(data)
+
+        response_data = await self.http_client.post(url, data=prepared_data)
+        return self._parse_response(response_data, model_class)
+
+    async def _post(
+        self,
+        endpoint: str,
+        data: Union[BaseModel, Dict[str, Any]],
+        model_class: Type[T],
+    ) -> APIResponse[T]:
+        """Make a POST request (legacy method name).
+
+        Args:
+            endpoint: API endpoint name.
+            data: Data to send in the request.
+            model_class: Model class to parse response into.
+
+        Returns:
+            Parsed API response.
+        """
+        return await self.post_async(endpoint, data, model_class)
+
+    def post_sync(
+        self,
+        endpoint: str,
+        data: Union[BaseModel, Dict[str, Any]],
+        model_class: Type[T],
+    ) -> APIResponse[T]:
+        """Make a sync POST request.
+
+        Args:
+            endpoint: API endpoint name.
+            data: Data to send in the request.
+            model_class: Model class to parse response into.
+
+        Returns:
+            Parsed API response.
+        """
+        url = self._build_url(endpoint)
+        prepared_data = self._prepare_request_data(data)
+
+        response_data = self.http_client.post_sync(url, data=prepared_data)
+        return self._parse_response(response_data, model_class)

elusion/zenopay/services/orders.py

@@ -0,0 +1,135 @@
+"""Order service for the ZenoPay SDK"""
+
+from typing import Dict, Union
+
+from elusion.zenopay.config import ZenoPayConfig
+from elusion.zenopay.http import HTTPClient
+from elusion.zenopay.models.common import APIResponse, StatusCheckRequest
+from elusion.zenopay.models.order import (
+    NewOrder,
+    OrderResponse,
+    OrderStatusResponse,
+)
+from elusion.zenopay.services.base import BaseService
+
+
+class OrderSyncMethods(BaseService):
+    """Sync methods for OrderService - inherits from BaseService for direct access."""
+
+    def create(self, order_data: Union[NewOrder, Dict[str, str]]) -> APIResponse[OrderResponse]:
+        """Create a new order and initiate USSD payment (sync).
+
+        Args:
+            order_data: Order creation data.
+
+        Returns:
+            Created order response with order_id and status.
+
+        Examples:
+            >>> with zenopay_client:
+            ...     response = zenopay_client.orders.sync.create(order_data)
+            ...     print(f"Order created: {response.data.order_id}")
+        """
+        # ✅ Direct access to post_sync - no parent needed
+        return self.post_sync("create_order", order_data, OrderResponse)
+
+    def get_status(self, order_id: str) -> APIResponse[OrderStatusResponse]:
+        """Check the status of an existing order (sync).
+
+        Args:
+            order_id: The order ID to check status for.
+
+        Returns:
+            Order status response with payment details.
+        """
+        status_request = StatusCheckRequest(
+            order_id=order_id,
+            api_key=self.config.api_key,
+            secret_key=self.config.secret_key,
+            account_id=self.config.account_id or "",
+            check_status=1,
+        )
+        # ✅ Direct access - clean and simple
+        return self.post_sync("order_status", status_request, OrderStatusResponse)
+
+    def check_payment(self, order_id: str) -> bool:
+        """Check if an order has been paid (sync)."""
+        try:
+            status_response = self.get_status(order_id)
+            return status_response.data.payment_status == "COMPLETED"
+        except Exception:
+            return False
+
+    def wait_for_payment(self, order_id: str, timeout: int = 300, poll_interval: int = 10) -> APIResponse[OrderStatusResponse]:
+        """Wait for an order to be paid (sync)."""
+        import time
+
+        start_time = time.time()
+
+        while True:
+            status_response = self.get_status(order_id)
+
+            if status_response.data.payment_status == "COMPLETED":
+                return status_response
+
+            if status_response.data.payment_status == "FAILED":
+                raise Exception(f"Payment failed for order {order_id}")
+
+            elapsed = time.time() - start_time
+            if elapsed >= timeout:
+                raise TimeoutError(f"Payment timeout after {timeout} seconds")
+
+            time.sleep(poll_interval)
+
+
+class OrderService(BaseService):
+    """Service for managing orders and payments."""
+
+    def __init__(self, http_client: HTTPClient, config: ZenoPayConfig):
+        """Initialize OrderService with sync namespace."""
+        super().__init__(http_client, config)
+        self.sync = OrderSyncMethods(http_client, config)
+
+    async def create(self, order_data: Union[NewOrder, Dict[str, str]]) -> APIResponse[OrderResponse]:
+        """Create a new order and initiate USSD payment."""
+        return await self._post("create_order", order_data, OrderResponse)
+
+    async def get_status(self, order_id: str) -> APIResponse[OrderStatusResponse]:
+        """Check the status of an existing order."""
+        status_request = StatusCheckRequest(
+            order_id=order_id,
+            api_key=self.config.api_key,
+            secret_key=self.config.secret_key,
+            account_id=self.config.account_id or "",
+            check_status=1,
+        )
+        return await self._post("order_status", status_request, OrderStatusResponse)
+
+    async def check_payment(self, order_id: str) -> bool:
+        """Check if an order has been paid."""
+        try:
+            status_response = await self.get_status(order_id)
+            return status_response.data.payment_status == "COMPLETED"
+        except Exception:
+            return False
+
+    async def wait_for_payment(self, order_id: str, timeout: int = 300, poll_interval: int = 10) -> APIResponse[OrderStatusResponse]:
+        """Wait for an order to be paid."""
+        import asyncio
+
+        start_time = asyncio.get_event_loop().time()
+
+        while True:
+            status_response = await self.get_status(order_id)
+
+            if status_response.data.payment_status == "COMPLETED":
+                return status_response
+
+            if status_response.data.payment_status == "FAILED":
+                raise Exception(f"Payment failed for order {order_id}")
+
+            elapsed = asyncio.get_event_loop().time() - start_time
+            if elapsed >= timeout:
+                raise TimeoutError(f"Payment timeout after {timeout} seconds")
+
+            await asyncio.sleep(poll_interval)

elusion/zenopay/services/webhooks.py

@@ -0,0 +1,188 @@
+"""Webhook service for the ZenoPay SDK."""
+
+import json
+import logging
+from datetime import datetime
+from typing import Any, Callable, Dict, Optional
+
+from elusion.zenopay.exceptions import ZenoPayWebhookError
+from elusion.zenopay.models.webhook import WebhookEvent, WebhookResponse
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookService:
+    """Service for handling ZenoPay webhooks."""
+
+    def __init__(self) -> None:
+        """Initialize the webhook service."""
+        self._handlers: Dict[str, Callable[[WebhookEvent], Any]] = {}
+
+    def parse_webhook(self, raw_data: str, signature: Optional[str] = None) -> WebhookEvent:
+        """Parse raw webhook data into a WebhookEvent.
+
+        Args:
+            raw_data: Raw JSON string from the webhook request.
+            signature: Optional webhook signature for verification.
+
+        Returns:
+            Parsed WebhookEvent.
+
+        Raises:
+            ZenoPayWebhookError: If the webhook data is invalid.
+
+        Examples:
+            >>> webhook_service = WebhookService()
+            >>> raw_data = '''{"order_id":"677e43274d7cb","payment_status":"COMPLETED","reference":"1003020496"}'''
+            >>> event = webhook_service.parse_webhook(raw_data)
+            >>> print(f"Order {event.payload.order_id} is {event.payload.payment_status}")
+        """
+        try:
+            event = WebhookEvent.from_raw_data(raw_data)
+            event.signature = signature
+            event.timestamp = datetime.now().isoformat()
+
+            logger.info(f"Parsed webhook for order {event.payload.order_id}: {event.payload.payment_status}")
+            return event
+
+        except Exception as e:
+            logger.error(f"Failed to parse webhook: {e}")
+            raise ZenoPayWebhookError(f"Invalid webhook data: {e}", {"raw_data": raw_data})
+
+    def register_handler(self, event_type: str, handler: Callable[[WebhookEvent], Any]) -> None:
+        """Register a handler for specific webhook events.
+
+        Args:
+            event_type: Type of event to handle (e.g., "COMPLETED", "FAILED").
+            handler: Function to call when this event type is received.
+
+        Examples:
+            >>> def payment_completed_handler(event: WebhookEvent):
+            ...     print(f"Payment completed for order {event.payload.order_id}")
+            ...     # Update database, send emails, etc.
+            >>>
+            >>> webhook_service.register_handler("COMPLETED", payment_completed_handler)
+        """
+        self._handlers[event_type] = handler
+
+    def handle_webhook(self, event: WebhookEvent) -> WebhookResponse:
+        """Handle a parsed webhook event.
+
+        Args:
+            event: Parsed webhook event.
+
+        Returns:
+            Webhook response to send back to ZenoPay.
+
+        Examples:
+            >>> event = webhook_service.parse_webhook(raw_data)
+            >>> response = webhook_service.handle_webhook(event)
+            >>> print(response.message)  # "Webhook received and processed"
+        """
+        try:
+            event_type = event.payload.payment_status
+
+            if event_type in self._handlers:
+                self._handlers[event_type](event)
+            else:
+                logger.warning(f"No handler registered for event type: {event_type}")
+
+            self._log_webhook_event(event)
+
+            return WebhookResponse(
+                status="success",
+                message=f"Webhook received and processed for order {event.payload.order_id}",
+            )
+
+        except Exception as e:
+            logger.error(f"Error handling webhook: {e}")
+            return WebhookResponse(status="error", message=f"Error processing webhook: {str(e)}")
+
+    def process_webhook_request(self, raw_data: str, signature: Optional[str] = None) -> WebhookResponse:
+        """Process a complete webhook request from raw data to response.
+
+        Args:
+            raw_data: Raw JSON string from the webhook request.
+            signature: Optional webhook signature.
+
+        Returns:
+            Webhook response to send back to ZenoPay.
+
+        Examples:
+            >>> # In your Flask/FastAPI endpoint:
+            >>> @app.route('/webhook', methods=['POST'])
+            >>> def handle_zenopay_webhook():
+            ...     raw_data = request.data.decode('utf-8')
+            ...     response = webhook_service.process_webhook_request(raw_data)
+            ...     return {"status": response.status, "message": response.message}
+        """
+        try:
+            event = self.parse_webhook(raw_data, signature)
+
+            response = self.handle_webhook(event)
+
+            logger.info(f"Successfully processed webhook for order {event.payload.order_id}")
+            return response
+
+        except ZenoPayWebhookError as e:
+            logger.error(f"Webhook error: {e}")
+            return WebhookResponse(status="error", message=str(e))
+        except Exception as e:
+            logger.error(f"Unexpected error processing webhook: {e}")
+            return WebhookResponse(status="error", message="Internal error processing webhook")
+
+    def _log_webhook_event(self, event: WebhookEvent) -> None:
+        """Log webhook event for debugging and audit purposes.
+
+        Args:
+            event: The webhook event to log.
+        """
+        log_data: Dict[str, Any] = {
+            "timestamp": event.timestamp,
+            "order_id": event.payload.order_id,
+            "payment_status": event.payload.payment_status,
+            "reference": event.payload.reference,
+        }
+
+        logger.info(f"Webhook event logged: {json.dumps(log_data)}")
+
+    def create_test_webhook(self, order_id: str, payment_status: str = "COMPLETED") -> WebhookEvent:
+        """Create a test webhook event for development/testing.
+
+        Args:
+            order_id: Order ID for the test webhook.
+            payment_status: Payment status for the test webhook.
+
+        Returns:
+            Test webhook event.
+
+        Examples:
+            >>> # For testing your webhook handlers
+            >>> test_event = webhook_service.create_test_webhook("test-123", "COMPLETED")
+            >>> response = webhook_service.handle_webhook(test_event)
+        """
+        test_payload: Dict[str, Any] = {
+            "order_id": order_id,
+            "payment_status": payment_status,
+            "reference": "TEST-" + str(int(datetime.now().timestamp())),
+            "metadata": {"test": True, "created_at": datetime.now().isoformat()},
+        }
+
+        raw_data = json.dumps(test_payload)
+        return self.parse_webhook(raw_data)
+
+    def on_payment_completed(self, handler: Callable[[WebhookEvent], Any]) -> None:
+        """Register handler for payment completed events."""
+        self.register_handler("COMPLETED", handler)
+
+    def on_payment_failed(self, handler: Callable[[WebhookEvent], Any]) -> None:
+        """Register handler for payment failed events."""
+        self.register_handler("FAILED", handler)
+
+    def on_payment_pending(self, handler: Callable[[WebhookEvent], Any]) -> None:
+        """Register handler for payment pending events."""
+        self.register_handler("PENDING", handler)
+
+    def on_payment_cancelled(self, handler: Callable[[WebhookEvent], Any]) -> None:
+        """Register handler for payment cancelled events."""
+        self.register_handler("CANCELLED", handler)

elusion/zenopay/utils/__init__.py

@@ -0,0 +1,9 @@
+from elusion.zenopay.utils.helpers import (
+    format_amount,
+    parse_amount,
+)
+
+__all__ = [
+    "format_amount",
+    "parse_amount",
+]

elusion/zenopay/utils/helpers.py

@@ -0,0 +1,35 @@
+def format_amount(amount: int, currency: str = "TZS") -> str:
+    """Format payment amount for display.
+
+    Args:
+        amount: Amount in smallest currency unit.
+        currency: Currency code.
+
+    Returns:
+        Formatted amount string.
+    """
+    if currency == "TZS":
+        return f"{amount:,} {currency}"
+    else:
+        amount_decimal = amount / 100
+        return f"{amount_decimal:.2f} {currency}"
+
+
+def parse_amount(amount_str: str, currency: str = "TZS") -> int:
+    """Parse amount string to integer in smallest currency unit.
+
+    Args:
+        amount_str: Amount string to parse.
+        currency: Currency code.
+
+    Returns:
+        Amount as integer in smallest currency unit.
+    """
+    try:
+        amount_float = float(amount_str.replace(",", ""))
+        if currency == "TZS":
+            return int(amount_float)
+        else:
+            return int(amount_float * 100)
+    except (ValueError, TypeError):
+        raise ValueError(f"Invalid amount format: {amount_str}")