feat: initial version of MpesaClient (facade)

Author: RafaelJohn9

mpesa_sdk/bill_manager/__init__.py

@@ -14,6 +14,7 @@
     BillManagerPaymentNotificationResponse,
     BillManagerPaymentAcknowledgmentRequest,
     BillManagerPaymentAcknowledgmentResponse,
+    InvoiceItem,
 )
 
 from .bill_manager import BillManager
@@ -35,4 +36,5 @@
     "BillManagerPaymentAcknowledgmentRequest",
     "BillManagerPaymentAcknowledgmentResponse",
     "BillManager",
+    "InvoiceItem",
 ]

mpesa_sdk/client.py

@@ -0,0 +1,39 @@
+"""MpesaClient: A unified client for M-PESA services."""
+
+from mpesa_sdk.auth import TokenManager
+from mpesa_sdk.http_client import HttpClient
+from mpesa_sdk.services import (
+    B2BService,
+    B2CService,
+    BalanceService,
+    BillService,
+    C2BService,
+    DynamicQRCodeService,
+    StkPushService,
+    RatibaService,
+    ReversalService,
+    TaxService,
+    TransactionService,
+)
+
+
+class MpesaClient:
+    """Unified client for all M-PESA services."""
+
+    def __init__(self, http_client: HttpClient, token_manager: TokenManager):
+        """Initialize the MpesaClient with all service facades."""
+        self.config = {
+            "http_client": http_client,
+            "token_manager": token_manager,
+        }
+        self.express = StkPushService(**self.config)
+        self.b2c = B2CService(**self.config)
+        self.b2b = B2BService(**self.config)
+        self.transactions = TransactionService(**self.config)
+        self.tax = TaxService(**self.config)
+        self.balance = BalanceService(**self.config)
+        self.reversal = ReversalService(**self.config)
+        self.bill = BillService(**self.config)
+        self.dynamic_qr = DynamicQRCodeService(**self.config)
+        self.c2b = C2BService(**self.config)
+        self.ratiba = RatibaService(**self.config)

mpesa_sdk/services/__init__.py

@@ -0,0 +1,25 @@
+from .b2b import B2BService
+from .b2c import B2CService
+from .balance import BalanceService
+from .bill import BillService
+from .c2b import C2BService
+from .dynamic_qr import DynamicQRCodeService
+from .express import StkPushService
+from .ratiba import RatibaService
+from .reversal import ReversalService
+from .tax import TaxService
+from .transaction import TransactionService
+
+__all__ = [
+    "B2BService",
+    "B2CService",
+    "BalanceService",
+    "BillService",
+    "C2BService",
+    "DynamicQRCodeService",
+    "StkPushService",
+    "RatibaService",
+    "ReversalService",
+    "TaxService",
+    "TransactionService",
+]

mpesa_sdk/services/account_balance.py

@@ -1,7 +1,17 @@
 """Facade for M-Pesa B2B APIs (Express Checkout)."""
 
+from typing import Optional
 from mpesa_sdk.auth import TokenManager
 from mpesa_sdk.http_client import HttpClient
+from mpesa_sdk.business_buy_goods import (
+    BusinessBuyGoods,
+    BusinessBuyGoodsRequest,
+)
+from mpesa_sdk.business_paybill import (
+    BusinessPayBill,
+    BusinessPayBillRequest,
+    BusinessPayBillResponse,
+)
 from mpesa_sdk.B2B_express_checkout import (
     B2BExpressCheckout,
     B2BExpressCheckoutRequest,
@@ -19,6 +29,14 @@ def __init__(self, http_client: HttpClient, token_manager: TokenManager) -> None
         self._express_checkout = B2BExpressCheckout(
             http_client=self.http_client, token_manager=self.token_manager
         )
+        self._business_paybill = BusinessPayBill(
+            http_client=self.http_client,
+            token_manager=self.token_manager,
+        )
+        self._business_buygoods = BusinessBuyGoods(
+            http_client=self.http_client,
+            token_manager=self.token_manager,
+        )
 
     def express_checkout(
         self,
@@ -31,7 +49,7 @@ def express_checkout(
         request_ref_id: str,
         **kwargs,
     ) -> B2BExpressCheckoutResponse:
-        """Initiate a B2B Express Checkout USSD Push transaction.
+        """Initiate a B2B Express Checkout USSD Push transaction to another merchant.
 
         Args:
             primary_short_code: The primary short code for the transaction.
@@ -61,3 +79,109 @@ def express_checkout(
             },
         )
         return self._express_checkout.ussd_push(request)
+
+    def paybill(
+        self,
+        initiator: str,
+        security_credential: str,
+        amount: int,
+        party_a: int,
+        party_b: int,
+        account_reference: str,
+        requester: str,
+        remarks: str,
+        queue_timeout_url: str,
+        result_url: str,
+        **kwargs,
+    ) -> BusinessPayBillResponse:
+        """Initiate a Business PayBill transaction to another merchant.
+
+        Args:
+            initiator: API username.
+            security_credential: Encrypted credential.
+            amount: The amount to be transacted.
+            party_a: The sender short code.
+            party_b: The receiver short code.
+            account_reference: Reference for the account.
+            requester: Requester phone number.
+            remarks: Remarks for the transaction.
+            queue_timeout_url: URL for timeout callback.
+            result_url: URL for result callback.
+            kwargs: Additional fields for BusinessPayBillRequest.
+
+        Returns:
+            BusinessPayBillResponse: Response from M-Pesa API.
+        """
+        request = BusinessPayBillRequest(
+            Initiator=initiator,
+            SecurityCredential=security_credential,
+            Amount=amount,
+            PartyA=party_a,
+            PartyB=party_b,
+            AccountReference=account_reference,
+            Requester=requester,
+            Remarks=remarks,
+            QueueTimeOutURL=queue_timeout_url,
+            ResultURL=result_url,
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k in BusinessPayBillRequest.model_fields
+            },
+        )
+
+        return self._business_paybill.paybill(request)
+
+    def buygoods(
+        self,
+        initiator: str,
+        security_credential: str,
+        amount: int,
+        party_a: int,
+        party_b: int,
+        account_reference: str,
+        requester: str,
+        remarks: str,
+        queue_timeout_url: str,
+        result_url: str,
+        occassion: Optional[str] = None,
+        **kwargs,
+    ):
+        """Initiate a Business Buy Goods transaction to another merchant.
+
+        Args:
+            initiator: API username.
+            security_credential: Encrypted credential.
+            amount: The amount to be transacted.
+            party_a: The sender short code.
+            party_b: The receiver short code.
+            account_reference: Reference for the account.
+            requester: Requester phone number.
+            remarks: Remarks for the transaction.
+            queue_timeout_url: URL for timeout callback.
+            result_url: URL for result callback.
+            occassion: Optional transaction occasion.
+            kwargs: Additional fields for BusinessBuyGoodsRequest.
+
+        Returns:
+            BusinessBuyGoodsResponse: Response from M-Pesa API.
+        """
+        request = BusinessBuyGoodsRequest(
+            Initiator=initiator,
+            SecurityCredential=security_credential,
+            Amount=amount,
+            PartyA=party_a,
+            PartyB=party_b,
+            AccountReference=account_reference,
+            Requester=requester,
+            Remarks=remarks,
+            QueueTimeOutURL=queue_timeout_url,
+            ResultURL=result_url,
+            Occassion=occassion,
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k in BusinessBuyGoodsRequest.model_fields
+            },
+        )
+        return self._business_buygoods.buy_goods(request)

mpesa_sdk/services/auth.py

@@ -0,0 +1,68 @@
+"""Facade for M-Pesa Account Balance API interactions."""
+
+from typing import Optional
+from mpesa_sdk.auth import TokenManager
+from mpesa_sdk.http_client import HttpClient
+from mpesa_sdk.account_balance import (
+    AccountBalance,
+    AccountBalanceRequest,
+    AccountBalanceResponse,
+)
+
+
+class BalanceService:
+    """Facade for M-Pesa Account Balance operations."""
+
+    def __init__(self, http_client: HttpClient, token_manager: TokenManager) -> None:
+        """Initialize the Balance service."""
+        self.http_client = http_client
+        self.token_manager = token_manager
+        self.account_balance = AccountBalance(
+            http_client=self.http_client,
+            token_manager=self.token_manager,
+        )
+
+    def query(
+        self,
+        initiator: str,
+        security_credential: str,
+        command_id: str,
+        party_a: int,
+        identifier_type: int,
+        remarks: str,
+        result_url: str,
+        queue_timeout_url: str,
+        **kwargs,
+    ) -> AccountBalanceResponse:
+        """Query account balance.
+
+        Args:
+            initiator: Name of the initiator.
+            security_credential: Security credential for authentication.
+            command_id: Command ID for the transaction.
+            party_a: Shortcode of the account to query.
+            identifier_type: Type of identifier for PartyA.
+            remarks: Additional remarks.
+            result_url: URL for result notification.
+            queue_timeout_url: URL for timeout notification.
+            **kwargs: Additional fields for AccountBalanceRequest.
+
+        Returns:
+            AccountBalanceResponse: Response from the M-Pesa API.
+        """
+        request = AccountBalanceRequest(
+            Initiator=initiator,
+            SecurityCredential=security_credential,
+            CommandID=command_id,
+            PartyA=party_a,
+            IdentifierType=identifier_type,
+            Remarks=remarks,
+            ResultURL=result_url,
+            QueueTimeOutURL=queue_timeout_url,
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k in AccountBalanceRequest.model_fields
+            },
+        )
+        return self.account_balance.query(request)