feat!: Migrate to derive builder

src/client.rs

@@ -12,13 +12,7 @@
 
 use crate::auth::AUTH;
 use crate::environment::ApiEnvironment;
-use crate::services::{
-    AccountBalanceBuilder, B2bBuilder, B2cBuilder, BulkInvoiceBuilder, C2bRegisterBuilder,
-    C2bSimulateBuilder, CancelInvoiceBuilder, DynamicQR, DynamicQRBuilder, MpesaExpress,
-    MpesaExpressBuilder, OnboardBuilder, OnboardModifyBuilder, ReconciliationBuilder,
-    SingleInvoiceBuilder, TransactionReversal, TransactionReversalBuilder,
-    TransactionStatusBuilder,
-};
+use crate::services::*;
 use crate::{auth, MpesaError, MpesaResult, ResponseError};
 
 /// Source: [test credentials](https://developer.safaricom.co.ke/test_credentials)
@@ -232,8 +226,8 @@
 
     #[cfg(feature = "account_balance")]
     #[doc = include_str!("../docs/client/account_balance.md")]
-    pub fn account_balance<'a>(&'a self, initiator_name: &'a str) -> AccountBalanceBuilder {
-        AccountBalanceBuilder::new(self, initiator_name)
+    pub fn account_balance(&self) -> AccountBalanceBuilder {
+        AccountBalance::builder(self)
     }
 
     #[cfg(feature = "express_request")]
@@ -257,9 +251,9 @@
     #[cfg(feature = "dynamic_qr")]
     #[doc = include_str!("../docs/client/dynamic_qr.md")]
     pub fn dynamic_qr(&self) -> DynamicQRBuilder {
         DynamicQR::builder(self)
     }
 
     /// Generates security credentials
     /// M-Pesa Core authenticates a transaction by decrypting the security credentials.
     /// Security credentials are generated by encrypting the base64 encoded initiator password with M-Pesa’s public key, a X509 certificate.
@@ -267,7 +261,7 @@
     ///
     /// # Errors
     /// Returns `EncryptionError` variant of `MpesaError`
-    pub(crate) fn gen_security_credentials(&self) -> MpesaResult<String> {
+    pub fn gen_security_credentials(&self) -> MpesaResult<String> {
         let pem = self.certificate.as_bytes();
         let cert = X509::from_pem(pem)?;
         // getting the public and rsa keys

src/constants.rs

@@ -33,7 +33,7 @@ impl Display for CommandId {
 /// Identifier types - both sender and receiver - identify an M-Pesa transaction’s sending and receiving party as
 /// either a shortcode, a till number or a MSISDN (phone number).
 /// There are three identifier types that can be used with M-Pesa APIs.
-#[derive(Debug, Serialize_repr, Deserialize_repr, Copy, Clone)]
+#[derive(Debug, Serialize_repr, Deserialize_repr, Copy, Clone, PartialEq, Eq)]
 #[repr(u16)]
 pub enum IdentifierTypes {
     MSISDN = 1,

src/services/account_balance.rs

@@ -1,5 +1,7 @@
 #![doc = include_str!("../../docs/client/account_balance.md")]
 
+use derive_builder::Builder;
+use reqwest::Url;
 use serde::{Deserialize, Serialize};
 
 use crate::constants::{CommandId, IdentifierTypes};
@@ -8,28 +10,23 @@
 const ACCOUNT_BALANCE_URL: &str = "mpesa/accountbalance/v1/query";
 
 #[derive(Debug, Serialize)]
-/// Account Balance payload
-struct AccountBalancePayload<'mpesa> {
-    #[serde(rename(serialize = "Initiator"))]
-    initiator: &'mpesa str,
-    #[serde(rename(serialize = "SecurityCredential"))]
-    security_credential: &'mpesa str,
+#[serde(rename_all = "PascalCase")]
+pub struct AccountBalanceRequest<'mpesa> {
+    pub initiator: &'mpesa str,
+    pub security_credential: String,
     #[serde(rename(serialize = "CommandID"))]
-    command_id: CommandId,
-    #[serde(rename(serialize = "PartyA"))]
-    party_a: &'mpesa str,
-    #[serde(rename(serialize = "IdentifierType"))]
-    identifier_type: &'mpesa str,
-    #[serde(rename(serialize = "Remarks"))]
-    remarks: &'mpesa str,
+    pub command_id: CommandId,
+    pub party_a: &'mpesa str,
+    pub identifier_type: IdentifierTypes,
+    pub remarks: &'mpesa str,
     #[serde(rename(serialize = "QueueTimeOutURL"))]
-    queue_time_out_url: &'mpesa str,
+    pub queue_time_out_url: Url,
     #[serde(rename(serialize = "ResultURL"))]
-    result_url: &'mpesa str,
+    pub result_url: Url,
 }
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct AccountBalanceResponse {
     #[serde(rename(deserialize = "ConversationID"))]
     pub conversation_id: String,
     #[serde(rename(deserialize = "OriginatorConversationID"))]
@@ -39,146 +36,98 @@
     #[serde(rename(deserialize = "ResponseDescription"))]
     pub response_description: String,
 }
-#[derive(Debug)]
-pub struct AccountBalanceBuilder<'mpesa> {
-    initiator_name: &'mpesa str,
-    client: &'mpesa Mpesa,
-    command_id: Option<CommandId>,
-    party_a: Option<&'mpesa str>,
-    identifier_type: Option<IdentifierTypes>,
-    remarks: Option<&'mpesa str>,
-    queue_timeout_url: Option<&'mpesa str>,
-    result_url: Option<&'mpesa str>,
-}
-
-impl<'mpesa> AccountBalanceBuilder<'mpesa> {
-    /// Creates a new `AccountBalanceBuilder`.
-    /// Requires an `initiator_name`, the credential/ username used to authenticate the transaction request
-    pub fn new(
-        client: &'mpesa Mpesa,
-        initiator_name: &'mpesa str,
-    ) -> AccountBalanceBuilder<'mpesa> {
-        AccountBalanceBuilder {
-            initiator_name,
-            client,
-            command_id: None,
-            party_a: None,
-            identifier_type: None,
-            remarks: None,
-            queue_timeout_url: None,
-            result_url: None,
-        }
-    }
 
+#[derive(Builder, Debug, Clone)]
+#[builder(build_fn(error = "MpesaError"))]
+pub struct AccountBalance<'mpesa> {
+    #[builder(pattern = "immutable", private)]
+    client: &'mpesa Mpesa,
+    #[builder(setter(into))]
+    /// The credential/ username used to authenticate the transaction request
+    initiator_name: &'mpesa str,
     /// Adds a `CommandId`, the unique command passed to the MPESA system.
     /// Defaults to `CommandId::AccountBalance` if not passed explicitly.
     ///
     /// # Errors
     /// If `CommandId` is invalid
-    pub fn command_id(mut self, command_id: CommandId) -> AccountBalanceBuilder<'mpesa> {
-        self.command_id = Some(command_id);
-        self
-    }
-
+    #[builder(default = "crate::CommandId::AccountBalance")]
+    command_id: CommandId,
     /// Adds `PartyA`, the shortcode of the organization receiving the transaction.
     /// This is a required field.
     ///
     /// # Errors
     /// If `Party A` is not provided or invalid
-    pub fn party_a(mut self, party_a: &'mpesa str) -> AccountBalanceBuilder<'mpesa> {
-        self.party_a = Some(party_a);
-        self
-    }
-
-    /// Adds the `ReceiverIdentifierType`, the type of organization receiving the transaction.
+    party_a: &'mpesa str,
+    // Adds the `ReceiverIdentifierType`, the type of organization receiving the transaction.
     /// Defaults to `IdentifierTypes::ShortCode` if not passed explicitly
     ///
     /// # Errors
     /// If invalid `ReceiverIdentifierType` is provided
-    pub fn identifier_type(
-        mut self,
-        identifier_type: IdentifierTypes,
-    ) -> AccountBalanceBuilder<'mpesa> {
-        self.identifier_type = Some(identifier_type);
-        self
-    }
-
+    #[builder(default = "crate::IdentifierTypes::ShortCode")]
+    identifier_type: IdentifierTypes,
     /// Adds `Remarks`, a comment sent along transaction.
     /// Optional field that defaults to `"None"` if no value is provided
-    pub fn remarks(mut self, remarks: &'mpesa str) -> AccountBalanceBuilder<'mpesa> {
-        self.remarks = Some(remarks);
-        self
-    }
-
+    #[builder(setter(into, strip_option), default = "Some(\"None\")")]
+    remarks: Option<&'mpesa str>,
     // Adds `QueueTimeoutUrl` This is a required field
     ///
     /// # Error
     /// If `QueueTimeoutUrl` is invalid or not provided
-    pub fn timeout_url(mut self, timeout_url: &'mpesa str) -> AccountBalanceBuilder<'mpesa> {
-        self.queue_timeout_url = Some(timeout_url);
-        self
-    }
-
+    #[builder(try_setter, setter(into))]
+    queue_timeout_url: Url,
     // Adds `ResultUrl` This is a required field
     ///
     /// # Error
     /// If `ResultUrl` is invalid or not provided
-    pub fn result_url(mut self, result_url: &'mpesa str) -> AccountBalanceBuilder<'mpesa> {
-        self.result_url = Some(result_url);
-        self
-    }
+    #[builder(try_setter, setter(into))]
+    result_url: Url,
+}
 
-    /// Adds `QueueTimeoutUrl` and `ResultUrl`. This is a required field
-    ///
-    /// # Error
-    /// If either `QueueTimeoutUrl` and `ResultUrl` is invalid or not provided
-    #[deprecated]
-    pub fn urls(
-        mut self,
-        timeout_url: &'mpesa str,
-        result_url: &'mpesa str,
-    ) -> AccountBalanceBuilder<'mpesa> {
-        self.queue_timeout_url = Some(timeout_url);
-        self.result_url = Some(result_url);
-        self
+impl<'mpesa> TryFrom<AccountBalance<'mpesa>> for AccountBalanceRequest<'mpesa> {
+    type Error = MpesaError;
+
+    fn try_from(value: AccountBalance<'mpesa>) -> MpesaResult<AccountBalanceRequest> {
+        Ok(AccountBalanceRequest {
+            command_id: value.command_id,
+            identifier_type: value.identifier_type,
+            initiator: value.initiator_name,
+            party_a: value.party_a,
+            queue_time_out_url: value.queue_timeout_url,
+            remarks: value.remarks.unwrap_or_default(),
+            result_url: value.result_url,
+            security_credential: value.client.gen_security_credentials()?,
+        })
     }
+}
 
-    /// # AccountBalance API
-    ///
-    /// Enquire the balance on an M-Pesa BuyGoods (Till Number).
-    /// A successful request returns a `C2bRegisterResponse` type.
-    /// See more [here](https://developer.safaricom.co.ke/docs#account-balance-api)
-    ///
-    /// # Errors
-    /// Returns a `MpesaError` on failure
-    pub async fn send(self) -> MpesaResult<AccountBalanceResponse> {
-        let credentials = self.client.gen_security_credentials()?;
+impl<'mpesa> AccountBalance<'mpesa> {
+    /// Creates a new `AccountBalanceBuilder`
+    pub(crate) fn builder(client: &'mpesa Mpesa) -> AccountBalanceBuilder<'mpesa> {
+        AccountBalanceBuilder::default().client(client)
+    }
 
-        let payload = AccountBalancePayload {
-            command_id: self.command_id.unwrap_or(CommandId::AccountBalance),
-            party_a: self
-                .party_a
-                .ok_or(MpesaError::Message("party_a is required"))?,
-            identifier_type: &self
-                .identifier_type
-                .unwrap_or(IdentifierTypes::ShortCode)
-                .to_string(),
-            remarks: self.remarks.unwrap_or_else(|| stringify!(None)),
-            initiator: self.initiator_name,
-            queue_time_out_url: self
-                .queue_timeout_url
-                .ok_or(MpesaError::Message("queue_timeout_url is required"))?,
-            result_url: self
-                .result_url
-                .ok_or(MpesaError::Message("result_url is required"))?,
-            security_credential: &credentials,
-        };
+    pub fn from_request(
+        client: &'mpesa Mpesa,
+        request: AccountBalanceRequest<'mpesa>,
+    ) -> AccountBalance<'mpesa> {
+        AccountBalance {
+            client,
+            command_id: request.command_id,
+            identifier_type: request.identifier_type,
+            initiator_name: request.initiator,
+            party_a: request.party_a,
+            queue_timeout_url: request.queue_time_out_url,
+            remarks: Some(request.remarks),
+            result_url: request.result_url,
+        }
+    }
 
+    pub async fn send(self) -> MpesaResult<AccountBalanceResponse> {
         self.client
-            .send(crate::client::Request {
+            .send::<AccountBalanceRequest, _>(crate::client::Request {
                 method: reqwest::Method::POST,
                 path: ACCOUNT_BALANCE_URL,
-                body: payload,
+                body: self.try_into()?,
             })
             .await
     }

src/services/mod.rs

@@ -29,7 +29,9 @@ mod transaction_reversal;
 mod transaction_status;
 
 #[cfg(feature = "account_balance")]
-pub use account_balance::{AccountBalanceBuilder, AccountBalanceResponse};
+pub use account_balance::{
+    AccountBalance, AccountBalanceBuilder, AccountBalanceRequest, AccountBalanceResponse,
+};
 #[cfg(feature = "b2b")]
 pub use b2b::{B2bBuilder, B2bResponse};
 #[cfg(feature = "b2c")]