Implement bill manager api (#66)

* Add bill manager onboarding api

* Add bill manager onboard modify API

* Add single invoicing API

* Add single invoicing API tests

* Clean up bill manager onboard modules and tests

* Rename bill manager single invoice payload to just Payload<>

* Remove unnecessary type annotations

* Make 'due_date' for invoice type owned

* Add bill manager bulk invoicing API

* Add bill manager reconciliation API

* Add cancel invoice API

* Clean up bulk invoicing module to throw if invoices is None

* Keep bill manager features under one 'bill_manager' feature flag

* Update bill manager urls on our docs

* Apply suggestions from code review

Apply suggestions

Co-authored-by: Collins Muriuki <[email protected]>

* Rename res_msg and res_code; tie chrono dependency under bill_manager

* Add function to add single invoices to bulk invoice builder

* Update README.md

* Add  function to CancelInvoiceBuilder

---------

Co-authored-by: Collins Muriuki <[email protected]>

Author: crispinkoech

.cargo/config.toml

@@ -1,5 +1,5 @@
 [build]
-rustdoc = "rustdoc" 
+rustdoc = "rustdoc"
 
 [alias]
-t = ["test", "--all-features", "--no-fail-fast"]
+t = ["test", "--all-features", "--no-fail-fast"]

Cargo.toml

@@ -10,7 +10,7 @@ readme = "./README.md"
 license = "MIT"
 
 [dependencies]
-chrono = {version = "0.4", optional = true, default-features = false, features = ["clock"] }
+chrono = {version = "0.4", optional = true, default-features = false, features = ["clock", "serde"] }
 openssl = {version = "0.10", optional = true}
 reqwest = {version = "0.11", features = ["json"]}
 serde = {version="1.0", features= ["derive"]}
@@ -29,6 +29,7 @@ default = [
 	"account_balance",
 	"b2b",
 	"b2c",
+	"bill_manager",
 	"c2b_register",
 	"c2b_simulate",
 	"express_request",
@@ -38,6 +39,7 @@ default = [
 account_balance = ["dep:openssl"]
 b2b = ["dep:openssl"]
 b2c = ["dep:openssl"]
+bill_manager = ["dep:chrono"]
 c2b_register = []
 c2b_simulate = []
 express_request = ["dep:chrono"]

README.md

@@ -266,6 +266,110 @@ let response = client
 assert!(response.is_ok())
 ```
 
+- Bill Manager Onboard
+
+```rust,ignore
+let response = client
+    .onboard()
+    .callback_url("https://testdomain.com/true")
+    .email("[email protected]")
+    .logo("https://file.domain/file.png")
+    .official_contact("0712345678")
+    .send_reminders(SendRemindersTypes::Enable)
+    .short_code("600496")
+    .send()
+    .await;
+assert!(response.is_ok())
+```
+
+- Bill Manager Onboard Modify
+
+```rust,ignore
+let response = client
+    .onboard_modify()
+    .callback_url("https://testdomain.com/true")
+    .email("[email protected]")
+    .short_code("600496")
+    .send()
+    .await;
+assert!(response.is_ok())
+```
+
+- Bill Manager Bulk Invoice
+
+```rust,ignore
+let response = client
+    .bulk_invoice()
+    .invoices(vec![
+        Invoice {
+            amount: 1000.0,
+            account_reference: "John Doe",
+            billed_full_name: "John Doe",
+            billed_period: "August 2021",
+            billed_phone_number: "0712345678",
+            due_date: Utc::now(),
+            external_reference: "INV2345",
+            invoice_items: Some(
+                vec![InvoiceItem {amount: 1000.0, item_name: "An item"}]
+            ),
+            invoice_name: "Invoice 001"
+        }
+    ])
+    .send()
+    .await;
+assert!(response.is_ok())
+```
+
+- Bill Manager Single Invoice
+
+```rust,ignore
+let response = client
+    .single_invoice()
+    .amount(1000.0)
+    .account_reference("John Doe")
+    .billed_full_name("John Doe")
+    .billed_period("August 2021")
+    .billed_phone_number("0712345678")
+    .due_date(Utc::now())
+    .external_reference("INV2345")
+    .invoice_items(vec![
+        InvoiceItem {amount: 1000.0, item_name: "An item"}
+    ])
+    .invoice_name("Invoice 001")
+    .send()
+    .await;
+assert!(response.is_ok())
+```
+
+- Bill Manager Reconciliation
+
+```rust,ignore
+let response = client
+    .reconciliation()
+    .account_reference("John Doe")
+    .external_reference("INV2345")
+    .full_name("John Doe")
+    .invoice_name("Invoice 001")
+    .paid_amount(1000.0)
+    .payment_date(Utc::now())
+    .phone_number("0712345678")
+    .transaction_id("TRANSACTION_ID")
+    .send()
+    .await;
+assert!(response.is_ok())
+```
+
+- Bill Manager Cancel Invoice
+
+```rust,ignore
+let response = client
+    .cancel_invoice()
+    .external_references(vec!["9KLSS011"])
+    .send()
+    .await;
+assert!(response.is_ok())
+```
+
 More will be added progressively, pull requests welcome
 
 ## Author

src/client.rs

@@ -1,7 +1,9 @@
 use crate::environment::ApiEnvironment;
 use crate::services::{
-    AccountBalanceBuilder, B2bBuilder, B2cBuilder, C2bRegisterBuilder, C2bSimulateBuilder,
-    MpesaExpressRequestBuilder, TransactionReversalBuilder, TransactionStatusBuilder,
+    AccountBalanceBuilder, B2bBuilder, B2cBuilder, BulkInvoiceBuilder, C2bRegisterBuilder,
+    C2bSimulateBuilder, CancelInvoiceBuilder, MpesaExpressRequestBuilder, OnboardBuilder,
+    OnboardModifyBuilder, ReconciliationBuilder, SingleInvoiceBuilder, TransactionReversalBuilder,
+    TransactionStatusBuilder,
 };
 use crate::{ApiError, MpesaError};
 use openssl::base64;
@@ -184,6 +186,185 @@ impl<'mpesa, Env: ApiEnvironment> Mpesa<Env> {
         B2bBuilder::new(self, initiator_name)
     }
 
+    /// **Bill Manager Onboard Builder**
+    ///
+    /// Creates a `OnboardBuilder` which allows you to opt in as a biller to the bill manager features.
+    ///
+    /// See more from the Safaricom API docs [here](https://developer.safaricom.co.ke/APIs/BillManager)
+    ///
+    /// # Example
+    /// ```ignore
+    /// let response = client
+    ///     .onboard()
+    ///     .callback_url("https://testdomain.com/true")
+    ///     .email("[email protected]")
+    ///     .logo("https://file.domain/file.png")
+    ///     .official_contact("0712345678")
+    ///     .send_reminders(SendRemindersTypes::Enable)
+    ///     .short_code("600496")
+    ///     .send()
+    ///     .await;
+    /// ```
+    #[cfg(feature = "bill_manager")]
+    pub fn onboard(&'mpesa self) -> OnboardBuilder<'mpesa, Env> {
+        OnboardBuilder::new(self)
+    }
+
+    /// **Bill Manager Onboard Modify Builder**
+    ///
+    /// Creates a `OnboardModifyBuilder` which allows you to opt in as a biller to the bill manager features.
+    ///
+    /// See more from the Safaricom API docs [here](https://developer.safaricom.co.ke/APIs/BillManager)
+    ///
+    /// # Example
+    /// ```ignore
+    /// let response = client
+    ///     .onboard_modify()
+    ///     .callback_url("https://testdomain.com/true")
+    ///     .email("[email protected]")
+    ///     .logo("https://file.domain/file.png")
+    ///     .official_contact("0712345678")
+    ///     .send_reminders(SendRemindersTypes::Enable)
+    ///     .short_code("600496")
+    ///     .send()
+    ///     .await;
+    /// ```
+    #[cfg(feature = "bill_manager")]
+    pub fn onboard_modify(&'mpesa self) -> OnboardModifyBuilder<'mpesa, Env> {
+        OnboardModifyBuilder::new(self)
+    }
+
+    /// **Bill Manager Bulk Invoice Builder**
+    ///
+    /// Creates a `BulkInvoiceBuilder` which allows you to send invoices to your customers in bulk.
+    /// See more from the Safaricom API docs [here](https://developer.safaricom.co.ke/APIs/BillManager)
+    ///
+    /// # Example
+    /// ```ignore
+    /// use chrone::prelude::Utc;
+    ///
+    /// let response = client
+    ///     .bulk_invoice()
+    ///
+    ///     // Add multiple invoices at once
+    ///     .invoices(vec![
+    ///         Invoice {
+    ///             amount: 1000.0,
+    ///             account_reference: "John Doe",
+    ///             billed_full_name: "John Doe",
+    ///             billed_period: "August 2021",
+    ///             billed_phone_number: "0712345678",
+    ///             due_date: Utc::now(),
+    ///             external_reference: "INV2345",
+    ///             invoice_items: Some(
+    ///                 vec![InvoiceItem {amount: 1000.0, item_name: "An item"}]
+    ///             ),
+    ///             invoice_name: "Invoice 001"
+    ///         }
+    ///     ])
+    ///
+    ///     // Add a single invoice
+    ///     .invoice(
+    ///         Invoice {
+    ///             amount: 1000.0,
+    ///             account_reference: "John Doe",
+    ///             billed_full_name: "John Doe",
+    ///             billed_period: "August 2021",
+    ///             billed_phone_number: "0712345678",
+    ///             due_date: Utc::now(),
+    ///             external_reference: "INV2345",
+    ///             invoice_items: Some(vec![InvoiceItem {
+    ///                 amount: 1000.0,
+    ///                 item_name: "An item",
+    ///             }]),
+    ///             invoice_name: "Invoice 001",
+    ///         }
+    ///     )
+    ///     .send()
+    ///     .await;
+    /// ```
+    #[cfg(feature = "bill_manager")]
+    pub fn bulk_invoice(&'mpesa self) -> BulkInvoiceBuilder<'mpesa, Env> {
+        BulkInvoiceBuilder::new(self)
+    }
+
+    /// **Bill Manager Single Invoice Builder**
+    ///
+    /// Creates a `SingleInvoiceBuilder` which allows you to create and send invoices to your customers.
+    /// See more from the Safaricom API docs [here](https://developer.safaricom.co.ke/APIs/BillManager)
+    ///
+    /// # Example
+    /// ```ignore
+    /// use chrono::prelude::Utc;
+    ///
+    /// let response = client
+    ///     .single_invoice()
+    ///     .amount(1000.0)
+    ///     .account_reference("John Doe")
+    ///     .billed_full_name("John Doe")
+    ///     .billed_period("August 2021")
+    ///     .billed_phone_number("0712345678")
+    ///     .due_date(Utc::now())
+    ///     .external_reference("INV2345")
+    ///     .invoice_items(vec![
+    ///         InvoiceItem {amount: 1000.0, item_name: "An item"}
+    ///     ])
+    ///     .invoice_name("Invoice 001")
+    ///     .send()
+    ///     .await;
+    /// ```
+    #[cfg(feature = "bill_manager")]
+    pub fn single_invoice(&'mpesa self) -> SingleInvoiceBuilder<'mpesa, Env> {
+        SingleInvoiceBuilder::new(self)
+    }
+
+    /// **Bill Manager Reconciliation Builder**
+    ///
+    /// Creates a `ReconciliationBuilder` which enables your customers to receive e-receipts for payments made to your paybill account.
+    /// See more from the Safaricom API docs [here](https://developer.safaricom.co.ke/APIs/BillManager)
+    ///
+    /// # Example
+    /// ```ignore
+    /// use chrono::prelude::Utc;
+    ///
+    /// let response = client
+    ///     .reconciliation()
+    ///     .account_reference("John Doe")
+    ///     .external_reference("INV2345")
+    ///     .full_name("John Doe")
+    ///     .invoice_name("Invoice 001")
+    ///     .paid_amount(1000.0)
+    ///     .payment_date(Utc::now())
+    ///     .phone_number("0712345678")
+    ///     .transaction_id("TRANSACTION_ID")
+    ///     .send()
+    ///     .await;
+    /// ```
+    #[cfg(feature = "bill_manager")]
+    pub fn reconciliation(&'mpesa self) -> ReconciliationBuilder<'mpesa, Env> {
+        ReconciliationBuilder::new(self)
+    }
+
+    /// **Bill Manager Cancel Invoice Builder**
+    ///
+    /// Creates a `CancelInvoiceBuilder` which allows you to recall a sent invoice.
+    /// See more from the Safaricom API docs [here](https://developer.safaricom.co.ke/APIs/BillManager)
+    ///
+    /// # Example
+    /// ```ignore
+    /// use chrono::prelude::Utc;
+    ///
+    /// let response = client
+    ///     .cancel_invoice()
+    ///     .external_references(vec!["9KLSS011"])
+    ///     .send()
+    ///     .await;
+    /// ```
+    #[cfg(feature = "bill_manager")]
+    pub fn cancel_invoice(&'mpesa self) -> CancelInvoiceBuilder<'mpesa, Env> {
+        CancelInvoiceBuilder::new(self)
+    }
+
     /// **C2B Register builder**
     ///
     /// Creates a `C2bRegisterBuilder` for registering URLs to the 3rd party shortcode.