zenopay-sdk 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

elusion/zenopay/http/client.py

@@ -1,7 +1,7 @@
 """HTTP client for the ZenoPay SDK."""
 
 import logging
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 import httpx
 
@@ -74,11 +74,50 @@ class HTTPClient:
             self._sync_client.close()
             self._sync_client = None
 
+    def _clean_params(self, params: Optional[Dict[str, Any]]) -> Optional[Dict[str, str]]:
+        """Clean query parameters by removing None values and converting to strings.
+
+        Args:
+            params: Query parameters to clean.
+
+        Returns:
+            Cleaned parameters dictionary or None.
+        """
+        if not params:
+            return None
+
+        cleaned_params: Dict[str, str] = {}
+        for key, value in params.items():
+            if value is not None:
+                cleaned_params[str(key)] = str(value)
+
+        return cleaned_params if cleaned_params else None
+
+    def _clean_data(self, data: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        """Clean form data by removing None values and converting to strings.
+
+        Args:
+            data: Form data to clean.
+
+        Returns:
+            Cleaned data dictionary or None.
+        """
+        if not data:
+            return None
+
+        cleaned_data: Dict[str, Any] = {}
+        for key, value in data.items():
+            if value is not None:
+                cleaned_data[key] = str(value)
+
+        return cleaned_data if cleaned_data else None
+
     async def request(
         self,
         method: str,
         url: str,
         data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
         **kwargs: Any,
     ) -> Dict[str, Any]:
@@ -87,7 +126,8 @@ class HTTPClient:
         Args:
             method: HTTP method (GET, POST, PUT, DELETE, etc.).
             url: Request URL.
-            data: Form data to send.
+            data: Form data to send (for POST/PUT requests).
+            params: Query parameters to send (for GET requests).
             headers: Additional headers.
             **kwargs: Additional arguments for httpx.
 
@@ -105,15 +145,10 @@ class HTTPClient:
         if headers:
             request_headers.update(headers)
 
-        if data:
-            cleaned_data = {}
-            for key, value in data.items():
-                if value is not None:
-                    cleaned_data[key] = str(value)
-            data = cleaned_data
+        cleaned_data = self._clean_data(data)
+        cleaned_params = self._clean_params(params)
 
         try:
-            logger.debug(f"Making {method} request to {url}")
 
             if self._client is None:
                 raise ZenoPayNetworkError("Async HTTP client is not initialized.", None)
@@ -121,7 +156,8 @@ class HTTPClient:
             response = await self._client.request(
                 method=method,
                 url=url,
-                data=data,
+                data=cleaned_data,
+                params=cleaned_params,
                 headers=request_headers,
                 **kwargs,
             )
@@ -129,16 +165,13 @@ class HTTPClient:
             return await self._handle_response(response)
 
         except httpx.TimeoutException as e:
-            logger.error(f"Request timeout: {e}")
             raise ZenoPayTimeoutError(
                 f"Request timeout after {self.config.timeout} seconds",
                 self.config.timeout,
             ) from e
         except httpx.NetworkError as e:
-            logger.error(f"Network error: {e}")
             raise ZenoPayNetworkError(f"Network error: {str(e)}", e) from e
         except Exception as e:
-            logger.error(f"Unexpected error: {e}")
             raise ZenoPayNetworkError(f"Unexpected error: {str(e)}", e) from e
 
     def request_sync(
@@ -146,6 +179,7 @@ class HTTPClient:
         method: str,
         url: str,
         data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
         **kwargs: Any,
     ) -> Dict[str, Any]:
@@ -154,7 +188,8 @@ class HTTPClient:
         Args:
             method: HTTP method (GET, POST, PUT, DELETE, etc.).
             url: Request URL.
-            data: Form data to send.
+            data: Form data to send (for POST/PUT requests).
+            params: Query parameters to send (for GET requests).
             headers: Additional headers.
             **kwargs: Additional arguments for httpx.
 
@@ -172,15 +207,10 @@ class HTTPClient:
         if headers:
             request_headers.update(headers)
 
-        if data:
-            cleaned_data = {}
-            for key, value in data.items():
-                if value is not None:
-                    cleaned_data[key] = str(value)
-            data = cleaned_data
+        cleaned_data = self._clean_data(data)
+        cleaned_params = self._clean_params(params)
 
         try:
-            logger.debug(f"Making {method} request to {url}")
 
             if self._sync_client is None:
                 raise ZenoPayNetworkError("Sync HTTP client is not initialized.", None)
@@ -188,24 +218,24 @@ class HTTPClient:
             response = self._sync_client.request(
                 method=method,
                 url=url,
-                data=data,
+                data=cleaned_data,
+                params=cleaned_params,
                 headers=request_headers,
                 **kwargs,
             )
 
+            # Log response details for debugging
+
             return self._handle_response_sync(response)
 
         except httpx.TimeoutException as e:
-            logger.error(f"Request timeout: {e}")
             raise ZenoPayTimeoutError(
                 f"Request timeout after {self.config.timeout} seconds",
                 self.config.timeout,
             ) from e
         except httpx.NetworkError as e:
-            logger.error(f"Network error: {e}")
             raise ZenoPayNetworkError(f"Network error: {str(e)}", e) from e
         except Exception as e:
-            logger.error(f"Unexpected error: {e}")
             raise ZenoPayNetworkError(f"Unexpected error: {str(e)}", e) from e
 
     async def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
@@ -220,17 +250,14 @@ class HTTPClient:
         Raises:
             ZenoPayAPIError: For API errors.
         """
-        logger.debug(f"Response status: {response.status_code}")
+
+        response_data: Dict[str, Any] = {}
 
         try:
-            # Try to parse as JSON first
             response_data = response.json()
         except Exception:
-            # If JSON parsing fails, treat as text response
             response_text = response.text
-            logger.debug(f"Non-JSON response: {response_text}")
 
-            # For successful responses that aren't JSON, create a basic structure
             if response.is_success:
                 return {
                     "success": True,
@@ -238,20 +265,18 @@ class HTTPClient:
                     "message": "Request successful",
                 }
             else:
-                response_data: Dict[str, Any] = {
+                response_data = {
                     "success": False,
                     "error": response_text or f"HTTP {response.status_code}",
                     "message": f"Request failed with status {response.status_code}",
+                    "status_code": response.status_code,
                 }
 
         if response.is_success:
             return response_data
 
-        # Handle API errors
-        error_message = response_data.get("error", f"HTTP {response.status_code}")
-        error_code = response_data.get("code")
-
-        logger.error(f"API error: {response.status_code} - {error_message}")
+        error_message = self._extract_error_message(response_data, response)
+        error_code = response_data.get("code") or response_data.get("error_code")
 
         raise create_api_error(
             status_code=response.status_code,
@@ -272,17 +297,14 @@ class HTTPClient:
         Raises:
             ZenoPayAPIError: For API errors.
         """
-        logger.debug(f"Response status: {response.status_code}")
+
+        response_data: Dict[str, Any] = {}
 
         try:
-            # Try to parse as JSON first
             response_data = response.json()
         except Exception:
-            # If JSON parsing fails, treat as text response
             response_text = response.text
-            logger.debug(f"Non-JSON response: {response_text}")
 
-            # For successful responses that aren't JSON, create a basic structure
             if response.is_success:
                 return {
                     "success": True,
@@ -290,19 +312,18 @@ class HTTPClient:
                     "message": "Request successful",
                 }
             else:
-                response_data: Dict[str, Any] = {
+                response_data = {
                     "success": False,
                     "error": response_text or f"HTTP {response.status_code}",
                     "message": f"Request failed with status {response.status_code}",
+                    "status_code": response.status_code,
                 }
 
         if response.is_success:
             return response_data
 
-        error_message = response_data.get("error", f"HTTP {response.status_code}")
-        error_code = response_data.get("code")
-
-        logger.error(f"API error: {response.status_code} - {error_message}")
+        error_message = self._extract_error_message(response_data, response)
+        error_code = response_data.get("code") or response_data.get("error_code")
 
         raise create_api_error(
             status_code=response.status_code,
@@ -311,10 +332,103 @@ class HTTPClient:
             error_code=error_code,
         )
 
+    def _extract_error_message(self, response_data: Dict[str, Any], response: httpx.Response) -> str:
+        """Extract detailed error message from response data.
+
+        Args:
+            response_data: Parsed response data
+            response: HTTP response object
+
+        Returns:
+            Detailed error message
+        """
+
+        error_fields = ["error_description", "error", "message", "detail", "details", "error_message", "msg", "description", "reason"]
+
+        for field in error_fields:
+            if field in response_data and response_data[field]:
+                error_msg: str = response_data[field]
+                if isinstance(error_msg, dict):
+                    return str(error_msg)
+                return str(error_msg)
+
+        if "errors" in response_data:
+            errors: Dict[str, Any] = response_data["errors"]
+            error_parts: List[str] = []
+            for field, field_errors in errors.items():
+                field_name: str = field
+                if isinstance(field_errors, list):
+                    error_strs = [str(e) for e in field_errors]  # type: ignore
+                    error_parts.append(f"{field_name}: {', '.join(error_strs)}")
+                else:
+                    error_parts.append(f"{field_name}: {str(field_errors)}")
+            formatted_errors = "; ".join(error_parts)
+            return formatted_errors
+
+        if "success" in response_data and response_data["success"] is False:
+            print("DEBUG: Response indicates failure, checking for error details")
+
+        if "error" in response_data and isinstance(response_data["error"], dict):
+            nested_error: Dict[str, Any] = response_data["error"]  # type: ignore
+            for field in error_fields:
+                if field in nested_error:
+                    return str(nested_error[field])
+
+        response_text = response.text
+        if response_text and len(response_text) < 1000:
+            return f"HTTP {response.status_code}: {response_text}"
+
+        fallback = f"HTTP {response.status_code} - {response.reason_phrase or 'Unknown error'}"
+        return fallback
+
     async def post(self, url: str, data: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
-        """Make a POST request."""
+        """Make an async POST request.
+
+        Args:
+            url: Request URL.
+            data: Form data to send.
+            **kwargs: Additional arguments for httpx.
+
+        Returns:
+            Parsed response data.
+        """
         return await self.request("POST", url, data=data, **kwargs)
 
     def post_sync(self, url: str, data: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
-        """Make a sync POST request."""
+        """Make a sync POST request.
+
+        Args:
+            url: Request URL.
+            data: Form data to send.
+            **kwargs: Additional arguments for httpx.
+
+        Returns:
+            Parsed response data.
+        """
         return self.request_sync("POST", url, data=data, **kwargs)
+
+    async def get(self, url: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Make an async GET request.
+
+        Args:
+            url: Request URL.
+            params: Query parameters to send.
+            **kwargs: Additional arguments for httpx.
+
+        Returns:
+            Parsed response data.
+        """
+        return await self.request("GET", url, params=params, **kwargs)
+
+    def get_sync(self, url: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Make a sync GET request.
+
+        Args:
+            url: Request URL.
+            params: Query parameters to send.
+            **kwargs: Additional arguments for httpx.
+
+        Returns:
+            Parsed response data.
+        """
+        return self.request_sync("GET", url, params=params, **kwargs)

elusion/zenopay/models/__init__.py

@@ -1,10 +1,6 @@
 """Models package for the ZenoPay SDK."""
 
-from elusion.zenopay.models.common import (
-    PAYMENT_STATUSES,
-    APIResponse,
-    StatusCheckRequest,
-)
+from elusion.zenopay.models.common import PAYMENT_STATUSES, APIResponse, StatusCheckRequest, UtilityCodes
 
 from elusion.zenopay.models.order import (
     OrderBase,
@@ -13,7 +9,6 @@ from elusion.zenopay.models.order import (
     Order,
     OrderResponse,
     OrderStatusResponse,
-    OrderListParams,
 )
 
 from elusion.zenopay.models.webhook import (
@@ -22,12 +17,18 @@ from elusion.zenopay.models.webhook import (
     WebhookResponse,
 )
 
+from elusion.zenopay.models.disbursement import (
+    NewDisbursement,
+    DisbursementSuccessResponse,
+)
+
 __all__ = [
     # Constants and utilities
     "PAYMENT_STATUSES",
     # Common models
     "APIResponse",
     "StatusCheckRequest",
+    "UtilityCodes",
     # Order models
     "OrderBase",
     "NewOrder",
@@ -35,9 +36,11 @@ __all__ = [
     "Order",
     "OrderResponse",
     "OrderStatusResponse",
-    "OrderListParams",
     # Webhook models
     "WebhookPayload",
     "WebhookEvent",
     "WebhookResponse",
+    # Disbursement
+    "NewDisbursement",
+    "DisbursementSuccessResponse",
 ]

elusion/zenopay/models/common.py

@@ -1,6 +1,7 @@
 """Common models and types used across the ZenoPay SDK."""
 
 from datetime import datetime
+from enum import Enum
 from typing import Generic, List, Optional, TypeVar
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -12,7 +13,7 @@ class APIResponse(BaseModel, Generic[T]):
     """Generic API response wrapper."""
 
     success: bool = Field(..., description="Whether the request was successful")
-    data: T = Field(..., description="Response data")
+    results: T = Field(..., description="Response data")
     message: Optional[str] = Field(None, description="Response message")
     error: Optional[str] = Field(None, description="Error message if applicable")
 
@@ -43,10 +44,6 @@ class ValidationError(BaseModel):
 class ZenoPayAPIRequest(BaseModel):
     """Base model for ZenoPay API requests."""
 
-    api_key: Optional[str] = Field(None, description="API key (usually null in requests)")
-    secret_key: Optional[str] = Field(None, description="Secret key (usually null in requests)")
-    account_id: str = Field(..., description="ZenoPay account ID")
-
     def to_form_data(self) -> dict[str, str]:
         """Convert to form data format as expected by ZenoPay API."""
         data = self.model_dump(exclude_unset=True, by_alias=True)
@@ -62,22 +59,27 @@ class ZenoPayAPIRequest(BaseModel):
 class StatusCheckRequest(ZenoPayAPIRequest):
     """Request model for checking order status."""
 
-    check_status: int = Field(1, description="Always 1 for status check requests")
     order_id: str = Field(..., description="Order ID to check")
 
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
-                "check_status": 1,
                 "order_id": "66c4bb9c9abb1",
-                "account_id": "zp87778",
-                "api_key": "null",
-                "secret_key": "null",
             }
         }
     )
 
 
+class UtilityCodes(str, Enum):
+    """Uility codes"""
+
+    CASHIN = "CASHIN"
+
+    def __str__(self) -> str:
+        """String representation of the utility codes."""
+        return self.value
+
+
 # Common status constants
 PAYMENT_STATUSES = {
     "PENDING": "PENDING",

elusion/zenopay/models/disbursement.py

@@ -0,0 +1,70 @@
+from typing import Any, Dict, List
+from pydantic import BaseModel, ConfigDict, Field
+from elusion.zenopay.models.common import UtilityCodes
+
+
+class NewDisbursement(BaseModel):
+    transid: str = Field(..., description="Unique transaction ID (e.g., UUID) to prevent duplication.")
+    utilitycode: str = Field(default=UtilityCodes.CASHIN, description='Set to "CASHIN" for disbursements.')
+    utilityref: str = Field(..., description="Mobile number to receive the funds (e.g., 0744963858).")
+    amount: int = Field(..., description="Amount to send in Tanzanian Shillings (TZS).")
+    pin: int = Field(..., description="4-digit wallet PIN to authorize the transaction.", ge=1000, le=9999)
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {"transid": "7pbBX-lnnASw-erwnn-nrrr09AZ", "utilitycode": "CASHIN", "utilityref": "07XXXXXXXX", "amount": 1000, "pin": 0000}
+        }
+    )
+
+
+class ZenoPayResponse(BaseModel):
+    reference: str
+    transid: str
+    resultcode: str
+    result: str
+    message: str
+    data: List[Dict[str, Any]]
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "reference": "0949694808",
+                "transid": "7pbBXlnnASwerdsadasdwnnnrrr09AZ",
+                "resultcode": "000",
+                "result": "SUCCESS",
+                "message": "\nMpesa\nTo JOHN DOE(2557XXXXXXXX)\nFrom ZENO\nAmount 1,000.00\n\nReference 0949694808\n26/06/2025 7:21:24 PM",
+                "data": [],
+            }
+        }
+    )
+
+
+class DisbursementSuccessResponse(BaseModel):
+    status: str
+    message: str
+    fee: int
+    amount_sent_to_customer: int
+    total_deducted: int
+    new_balance: str
+    zenopay_response: ZenoPayResponse
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "status": "success",
+                "message": "Wallet Cashin processed successfully.",
+                "fee": 1500,
+                "amount_sent_to_customer": 3000,
+                "total_deducted": 4500,
+                "new_balance": "62984034.00",
+                "zenopay_response": {
+                    "reference": "0949694808",
+                    "transid": "7pbBXlnnASwerdsadasdwnnnrrr09AZ",
+                    "resultcode": "000",
+                    "result": "SUCCESS",
+                    "message": "\nMpesa\nTo JOHN DOE(2557XXXXXXXX)\nFrom ZENO\nAmount 1,000.00\n\nReference 0949694808\n26/06/2025 7:21:24 PM",
+                    "data": [],
+                },
+            }
+        }
+    )