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

elusion/zenopay/models/order.py

@@ -1,19 +1,18 @@
 """Order-related models for the ZenoPay SDK."""
 
-from datetime import datetime
-from typing import Any, Dict, Optional, Union
-
+from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class OrderBase(BaseModel):
     """Base order model with common fields."""
 
+    order_id: str = Field(..., description="Unique order id")
     buyer_email: str = Field(..., description="Buyer's email address")
     buyer_name: str = Field(..., description="Buyer's full name")
     buyer_phone: str = Field(..., description="Buyer's phone number")
     amount: int = Field(..., gt=0, description="Order amount in smallest currency unit")
-    webhook_url: Optional[str] = Field(None, description="URL to receive webhook notifications")
+    webhook_url: Optional[str] = Field(default=None, description="URL to receive webhook notifications")
 
     @field_validator("buyer_email")
     def validate_email(cls, v: str) -> str:
@@ -25,7 +24,6 @@ class OrderBase(BaseModel):
     @field_validator("buyer_phone")
     def validate_phone(cls, v: str) -> str:
         """Validate phone number format."""
-        # Remove any non-digit characters except +
         cleaned = "".join(c for c in v if c.isdigit() or c == "+")
         if len(cleaned) < 10:
             raise ValueError("Phone number must be at least 10 digits")
@@ -44,7 +42,7 @@ class OrderBase(BaseModel):
 class NewOrder(OrderBase):
     """Model for creating a new order."""
 
-    metadata: Optional[Dict[str, Any]] = Field(None, description="Additional order metadata")
+    metadata: Optional[Dict[str, Any]] = Field(default=None, description="Additional order metadata")
 
     @field_validator("metadata")
     def validate_metadata(cls, v: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
@@ -95,11 +93,6 @@ class Order(BaseModel):
     webhook_url: Optional[str] = Field(None, description="Webhook URL")
     metadata: Optional[Dict[str, Any]] = Field(None, description="Order metadata")
 
-    # Timestamps
-    created_at: Optional[datetime] = Field(None, description="Order creation time")
-    updated_at: Optional[datetime] = Field(None, description="Last update time")
-    completed_at: Optional[datetime] = Field(None, description="Payment completion time")
-
     @field_validator("payment_status")
     def validate_payment_status(cls, v: str) -> str:
         """Validate payment status."""
@@ -155,9 +148,6 @@ class Order(BaseModel):
                     "size": "L",
                     "custom_notes": "Please gift-wrap this item.",
                 },
-                "created_at": "2025-06-15T10:00:00Z",
-                "updated_at": "2025-06-15T10:05:00Z",
-                "completed_at": "2025-06-15T10:05:00Z",
             }
         }
     )
@@ -166,86 +156,37 @@ class Order(BaseModel):
 class OrderResponse(BaseModel):
     """Response model for order operations."""
 
-    status: str = Field("success", description="Status of the operation (success or error)")
-    message: str = Field(
-        "Order created successfully",
-        description="Message describing the operation result",
-    )
-    order_id: str = Field(..., description="ID of the created or updated order")
+    status: str
+    message: str
+    resultcode: int
+    order_id: str
 
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
+                "order_id": "2cd93967-0d48-46c7-a9ab-f0a0a21a11cd",
+                "resultcode": "000",
                 "status": "success",
                 "message": "Order created successfully",
-                "order_id": "66c4bb9c9abb1",
             }
         }
     )
 
 
-class OrderStatusResponse(BaseModel):
-    status: str = Field("success", description="Status of the operation (success or error)")
-    order_id: str = Field(..., description="ID of the order")
-    message: str = Field(
-        "Order status retrieved successfully",
-        description="Message describing the operation result",
-    )
-    payment_status: str = Field("PENDING", description="Current payment status of the order")
-
-
-class OrderListParams(BaseModel):
-    """Parameters for listing orders."""
-
-    status: Optional[str] = Field(None, description="Filter by payment status")
-    buyer_email: Optional[str] = Field(None, description="Filter by buyer email")
-    date_from: Optional[Union[datetime, str]] = Field(None, description="Filter orders from this date")
-    date_to: Optional[Union[datetime, str]] = Field(None, description="Filter orders to this date")
-    limit: Optional[int] = Field(50, ge=1, le=100, description="Number of orders to return")
-
-    @field_validator("status")
-    def validate_status(cls, v: Optional[str]) -> Optional[str]:
-        """Validate status filter."""
-        if v is not None:
-            valid_statuses = ["PENDING", "COMPLETED", "FAILED", "CANCELLED"]
-            if v not in valid_statuses:
-                raise ValueError(f"Invalid status. Must be one of: {', '.join(valid_statuses)}")
-        return v
-
-    @field_validator("date_from", mode="before")
-    def parse_date_from(cls, v: Union[str, datetime, None]) -> Union[datetime, None]:
-        """Parse string dates to datetime objects for date_from."""
-        if isinstance(v, str):
-            try:
-                return datetime.fromisoformat(v.replace("Z", "+00:00"))
-            except ValueError:
-                try:
-                    return datetime.strptime(v, "%Y-%m-%d")
-                except ValueError:
-                    raise ValueError(f"Invalid date format: {v}")
-        return v
+class OrderData(BaseModel):
+    order_id: str
+    creation_date: str
+    amount: str
+    payment_status: str
+    transid: Optional[str] = None
+    channel: Optional[str] = None
+    reference: Optional[str] = None
+    msisdn: Optional[str] = None
 
-    @field_validator("date_to", mode="before")
-    def parse_date_to(cls, v: Union[str, datetime, None]) -> Union[datetime, None]:
-        """Parse string dates to datetime objects for date_to."""
-        if isinstance(v, str):
-            try:
-                return datetime.fromisoformat(v.replace("Z", "+00:00"))
-            except ValueError:
-                try:
-                    return datetime.strptime(v, "%Y-%m-%d")
-                except ValueError:
-                    raise ValueError(f"Invalid date format: {v}")
-        return v
 
-    model_config = ConfigDict(
-        json_schema_extra={
-            "example": {
-                "status": "COMPLETED",
-                "buyer_email": "jackson@gmail.com",
-                "date_from": "2025-06-01",
-                "date_to": "2025-06-15",
-                "limit": 50,
-            }
-        }
-    )
+class OrderStatusResponse(BaseModel):
+    reference: str
+    resultcode: str
+    result: str
+    message: str
+    data: List[OrderData]

elusion/zenopay/services/__init__.py

@@ -1,7 +1,5 @@
 from elusion.zenopay.services.orders import OrderService
 from elusion.zenopay.services.webhooks import WebhookService
+from elusion.zenopay.services.disbursements import DisbursementService
 
-__all__ = [
-    "OrderService",
-    "WebhookService",
-]
+__all__ = ["OrderService", "WebhookService", "DisbursementService"]

elusion/zenopay/services/base.py

@@ -1,6 +1,6 @@
 """Base service class for all ZenoPay SDK services."""
 
-from typing import Any, Dict, Type, TypeVar, Union
+from typing import Any, Dict, Type, TypeVar, Union, Optional
 
 from pydantic import BaseModel, ValidationError
 
@@ -53,16 +53,29 @@ class BaseService:
         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 _prepare_query_params(self, params: Optional[Union[BaseModel, Dict[str, Any]]] = None) -> Dict[str, Any]:
+        """Prepare and validate query parameters for GET requests.
+
+        Args:
+            params: Parameters to prepare for the request.
+
+        Returns:
+            Prepared query parameters dictionary.
+
+        Raises:
+            ZenoPayValidationError: If validation fails.
+        """
+        if params is None:
+            query_params = {}
+        elif isinstance(params, BaseModel):
+            query_params = params.model_dump(exclude_unset=True, by_alias=True)
+        else:
+            query_params = params.copy()
+
+        return query_params
+
     def _parse_response(
         self,
         response_data: Dict[str, Any],
@@ -81,27 +94,14 @@ class BaseService:
             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
+            parsed_data = model_class.model_validate(response_data)
+            success = True
+            message = response_data.get("message", None)
+            error = None
 
             return APIResponse[model_class](
                 success=success,
-                data=parsed_data,
+                results=parsed_data,
                 message=message,
                 error=error,
             )
@@ -131,16 +131,16 @@ class BaseService:
         url = self._build_url(endpoint)
         prepared_data = self._prepare_request_data(data)
 
-        response_data = await self.http_client.post(url, data=prepared_data)
+        response_data = await self.http_client.post(url, json=prepared_data)
         return self._parse_response(response_data, model_class)
 
-    async def _post(
+    def post_sync(
         self,
         endpoint: str,
         data: Union[BaseModel, Dict[str, Any]],
         model_class: Type[T],
     ) -> APIResponse[T]:
-        """Make a POST request (legacy method name).
+        """Make a sync POST request.
 
         Args:
             endpoint: API endpoint name.
@@ -150,26 +150,52 @@ class BaseService:
         Returns:
             Parsed API response.
         """
-        return await self.post_async(endpoint, data, model_class)
+        url = self._build_url(endpoint)
+        prepared_data = self._prepare_request_data(data)
 
-    def post_sync(
+        response_data = self.http_client.post_sync(url, json=prepared_data)
+        return self._parse_response(response_data, model_class)
+
+    async def get_async(
         self,
         endpoint: str,
-        data: Union[BaseModel, Dict[str, Any]],
         model_class: Type[T],
+        params: Optional[Union[BaseModel, Dict[str, Any]]] = None,
     ) -> APIResponse[T]:
-        """Make a sync POST request.
+        """Make an async GET request.
 
         Args:
             endpoint: API endpoint name.
-            data: Data to send in the request.
             model_class: Model class to parse response into.
+            params: Optional query parameters to send with the request.
 
         Returns:
             Parsed API response.
         """
         url = self._build_url(endpoint)
-        prepared_data = self._prepare_request_data(data)
+        query_params = self._prepare_query_params(params)
+
+        response_data = await self.http_client.get(url, params=query_params)
+        return self._parse_response(response_data, model_class)
+
+    def get_sync(
+        self,
+        endpoint: str,
+        model_class: Type[T],
+        params: Optional[Union[BaseModel, Dict[str, Any]]] = None,
+    ) -> APIResponse[T]:
+        """Make a sync GET request.
+
+        Args:
+            endpoint: API endpoint name.
+            model_class: Model class to parse response into.
+            params: Optional query parameters to send with the request.
+
+        Returns:
+            Parsed API response.
+        """
+        url = self._build_url(endpoint)
+        query_params = self._prepare_query_params(params)
 
-        response_data = self.http_client.post_sync(url, data=prepared_data)
+        response_data = self.http_client.get_sync(url, params=query_params)
         return self._parse_response(response_data, model_class)

elusion/zenopay/services/disbursements.py

@@ -0,0 +1,45 @@
+"""Disbursement service for the ZenoPay SDK"""
+
+from elusion.zenopay.config import ZenoPayConfig
+from elusion.zenopay.http import HTTPClient
+from elusion.zenopay.models.common import APIResponse
+from elusion.zenopay.models.disbursement import (
+    NewDisbursement,
+    DisbursementSuccessResponse,
+)
+from elusion.zenopay.services.base import BaseService
+
+
+class DisbursementSyncMethods(BaseService):
+    """Sync methods for DisbursementService - inherits from BaseService for direct access."""
+
+    def disburse(self, disbursement_data: NewDisbursement) -> APIResponse[DisbursementSuccessResponse]:
+        """Send money to mobile wallet (sync).
+
+        Args:
+            disbursement_data: Disbursement data with recipient details.
+
+        Returns:
+            Disbursement response with transaction details and fees.
+        """
+        return self.post_sync("disbursement", disbursement_data, DisbursementSuccessResponse)
+
+
+class DisbursementService(BaseService):
+    """Service for sending money to mobile wallets."""
+
+    def __init__(self, http_client: HTTPClient, config: ZenoPayConfig):
+        """Initialize DisbursementService with sync namespace."""
+        super().__init__(http_client, config)
+        self.sync = DisbursementSyncMethods(http_client, config)
+
+    async def disburse(self, disbursement_data: NewDisbursement) -> APIResponse[DisbursementSuccessResponse]:
+        """Send money to mobile wallet (async).
+
+        Args:
+            disbursement_data: Disbursement data with recipient details.
+
+        Returns:
+            Disbursement response with transaction details and fees.
+        """
+        return await self.post_async("disbursement", disbursement_data, DisbursementSuccessResponse)

elusion/zenopay/services/orders.py

@@ -1,10 +1,10 @@
 """Order service for the ZenoPay SDK"""
 
-from typing import Dict, Union
+from typing import Any, 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.common import APIResponse
 from elusion.zenopay.models.order import (
     NewOrder,
     OrderResponse,
@@ -16,7 +16,7 @@ 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]:
+    def create(self, order_data: NewOrder) -> APIResponse[OrderResponse]:
         """Create a new order and initiate USSD payment (sync).
 
         Args:
@@ -30,11 +30,10 @@ class OrderSyncMethods(BaseService):
             ...     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).
+    def check_status(self, order_id: str) -> APIResponse[OrderStatusResponse]:
+        """Check the status of an existing order using GET request (sync).
 
         Args:
             order_id: The order ID to check status for.
@@ -42,21 +41,16 @@ class OrderSyncMethods(BaseService):
         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)
+        params: Dict[str, Any] = {
+            "order_id": order_id,
+        }
+        return self.get_sync("order_status", OrderStatusResponse, params=params)
 
     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"
+            status_response = self.check_status(order_id)
+            return status_response.results.data[0].payment_status == "COMPLETED"
         except Exception:
             return False
 
@@ -67,12 +61,12 @@ class OrderSyncMethods(BaseService):
         start_time = time.time()
 
         while True:
-            status_response = self.get_status(order_id)
+            status_response = self.check_status(order_id)
 
-            if status_response.data.payment_status == "COMPLETED":
+            if status_response.results.data[0].payment_status == "COMPLETED":
                 return status_response
 
-            if status_response.data.payment_status == "FAILED":
+            if status_response.results.data[0].payment_status == "FAILED":
                 raise Exception(f"Payment failed for order {order_id}")
 
             elapsed = time.time() - start_time
@@ -91,41 +85,51 @@ class OrderService(BaseService):
         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)
+        """Create a new order and initiate USSD payment (async).
+
+        Args:
+            order_data: Order creation data.
+
+        Returns:
+            Created order response with order_id and status.
+        """
+        return await self.post_async("create_order", order_data, OrderResponse)
+
+    async def check_status(self, order_id: str) -> APIResponse[OrderStatusResponse]:
+        """Check the status of an existing order using GET request (async).
+
+        Args:
+            order_id: The order ID to check status for.
+
+        Returns:
+            Order status response with payment details.
+        """
+        params: Dict[str, Any] = {
+            "order_id": order_id,
+        }
+        return await self.get_async("order_status", OrderStatusResponse, params=params)
 
     async def check_payment(self, order_id: str) -> bool:
-        """Check if an order has been paid."""
+        """Check if an order has been paid (async)."""
         try:
-            status_response = await self.get_status(order_id)
-            return status_response.data.payment_status == "COMPLETED"
+            status_response = await self.check_status(order_id)
+            return status_response.results.data[0].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."""
+        """Wait for an order to be paid (async)."""
         import asyncio
 
         start_time = asyncio.get_event_loop().time()
 
         while True:
-            status_response = await self.get_status(order_id)
+            status_response = await self.check_status(order_id)
 
-            if status_response.data.payment_status == "COMPLETED":
+            if status_response.results.data[0].payment_status == "COMPLETED":
                 return status_response
 
-            if status_response.data.payment_status == "FAILED":
+            if status_response.results.data[0].payment_status == "FAILED":
                 raise Exception(f"Payment failed for order {order_id}")
 
             elapsed = asyncio.get_event_loop().time() - start_time

elusion/zenopay/utils/__init__.py

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

elusion/zenopay/utils/helpers.py

@@ -1,3 +1,7 @@
+import uuid
+from typing import Optional
+
+
 def format_amount(amount: int, currency: str = "TZS") -> str:
     """Format payment amount for display.
 
@@ -33,3 +37,55 @@ def parse_amount(amount_str: str, currency: str = "TZS") -> int:
             return int(amount_float * 100)
     except (ValueError, TypeError):
         raise ValueError(f"Invalid amount format: {amount_str}")
+
+
+def generate_order_id(prefix: Optional[str] = None) -> str:
+    """Generate a unique order ID using UUID.
+
+    Args:
+        prefix: Optional prefix to add to the order ID.
+
+    Returns:
+        Unique order ID string.
+
+    Examples:
+        >>> generate_order_id()
+        'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+
+        >>> generate_order_id(prefix="ORDER")
+        'ORDER_f47ac10b-58cc-4372-a567-0e02b2c3d479'
+
+        >>> generate_order_id(prefix="SHOP")
+        'SHOP_f47ac10b-58cc-4372-a567-0e02b2c3d479'
+    """
+    unique_id = str(uuid.uuid4())
+
+    if prefix:
+        return f"{prefix}_{unique_id}"
+
+    return unique_id
+
+
+def generate_short_order_id(prefix: Optional[str] = None, length: int = 8) -> str:
+    """Generate a shorter unique order ID using UUID.
+
+    Args:
+        prefix: Optional prefix to add to the order ID.
+        length: Length of the UUID portion (default: 8 characters).
+
+    Returns:
+        Shorter unique order ID string.
+
+    Examples:
+        >>> generate_short_order_id()
+        'f47ac10b'
+
+        >>> generate_short_order_id(prefix="ORD", length=12)
+        'ORD_f47ac10b58cc'
+    """
+    unique_id = str(uuid.uuid4()).replace("-", "")[:length]
+
+    if prefix:
+        return f"{prefix}_{unique_id}"
+
+    return unique_id