Merge pull request #71 from morukele/feature/plans

feat(plan): added support for the plan endpoint.

Author: morukele

README.md

@@ -21,7 +21,7 @@ The client currently covers the following section of the API, and the sections t
 - [x] Dedicated Virtual Account
 - [x] Apple Pay
 - [x] Subaccounts
-- [ ] Plans
+- [x] Plans
 - [ ] Subscriptions
 - [ ] Transfer Recipients
 - [ ] Transfers

src/client.rs

@@ -3,8 +3,8 @@
 //! This file contains the Paystack API client, and it associated endpoints.
 use crate::{
     ApplePayEndpoints, CustomersEndpoints, DedicatedVirtualAccountEndpoints, HttpClient,
-    SubaccountEndpoints, TerminalEndpoints, TransactionEndpoints, TransactionSplitEndpoints,
-    VirtualTerminalEndpoints,
+    PlansEndpoints, SubaccountEndpoints, TerminalEndpoints, TransactionEndpoints,
+    TransactionSplitEndpoints, VirtualTerminalEndpoints,
 };
 use std::sync::Arc;
 
@@ -27,6 +27,8 @@ pub struct PaystackClient<T: HttpClient + Default> {
     pub dedicated_virtual_account: DedicatedVirtualAccountEndpoints<T>,
     /// Apple Pay API route
     pub apple_pay: ApplePayEndpoints<T>,
+    /// Plans API route
+    pub plans: PlansEndpoints<T>,
 }
 
 impl<T: HttpClient + Default> PaystackClient<T> {
@@ -45,6 +47,7 @@ impl<T: HttpClient + Default> PaystackClient<T> {
                 Arc::clone(&http),
             ),
             apple_pay: ApplePayEndpoints::new(Arc::clone(&key), Arc::clone(&http)),
+            plans: PlansEndpoints::new(Arc::clone(&key), Arc::clone(&http)),
         }
     }
 }

src/endpoints/mod.rs

@@ -1,6 +1,7 @@
 pub mod apple_pay;
 pub mod customers;
 pub mod dedicated_virtual_account;
+pub mod plans;
 pub mod subaccount;
 pub mod terminal;
 pub mod transaction;
@@ -11,6 +12,7 @@ pub mod virtual_terminal;
 pub use apple_pay::*;
 pub use customers::*;
 pub use dedicated_virtual_account::*;
+pub use plans::*;
 pub use subaccount::*;
 pub use terminal::*;
 pub use transaction::*;

src/endpoints/plans.rs

@@ -0,0 +1,167 @@
+use std::{marker::PhantomData, sync::Arc};
+
+use super::PAYSTACK_BASE_URL;
+use crate::{
+    HttpClient, Interval, PaystackAPIError, PaystackResult, PlanRequest, PlanResponseData,
+    PlanStatus, PlanUpdateRequest, Response,
+};
+
+pub struct PlansEndpoints<T: HttpClient + Default> {
+    /// Paystack API Key
+    key: String,
+    /// Base URL for the plans route
+    base_url: String,
+    /// Http client for the route
+    http: Arc<T>,
+}
+
+/// Create a new `PlansEndpoints<T>` instance
+///
+/// # Arguments
+/// - `key` - The Paystack API key
+/// - `http`: The HTTP client implementation to use for the API requests
+///
+/// # Returns
+/// A new PlansEndpoints instance
+impl<T: HttpClient + Default> PlansEndpoints<T> {
+    pub fn new(key: Arc<String>, http: Arc<T>) -> PlansEndpoints<T> {
+        let base_url = format!("{PAYSTACK_BASE_URL}/plan");
+        PlansEndpoints {
+            key: key.to_string(),
+            base_url,
+            http,
+        }
+    }
+
+    /// Create a plan on your integration
+    ///
+    /// # Arguments
+    /// * `plan_request` - The request data to create the plan.
+    ///   Should be created with a `PlanRequestBuilder` struct.
+    ///
+    /// # Returns
+    /// A Result containing the plan response data or an error  
+    pub async fn create_plan(&self, plan_request: PlanRequest) -> PaystackResult<PlanResponseData> {
+        let url = &self.base_url;
+        let body = serde_json::to_value(plan_request)
+            .map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        let response = self
+            .http
+            .post(url, &self.key, &body)
+            .await
+            .map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        let parsed_response: Response<PlanResponseData> =
+            serde_json::from_str(&response).map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        Ok(parsed_response)
+    }
+
+    /// Lists plans available in your integration
+    ///
+    /// # Arguments
+    /// * `per_page` - specify how many records you want to retrieve per page. Defaults to 50 if None
+    /// * `page` - specify exactly what page you want to retrieve. Defaults to 1 if None
+    /// * `status` - Optional parameter to filter list by plans with specified status
+    /// * `interval` - Optional parameter to filter list by plans with specified interval
+    /// * `amount`- Optional parameter to filter list by plans with specified amount using the supported currency
+    ///
+    /// # Returns
+    /// A Result containing a vector of plan response data or an error
+    pub async fn list_plans(
+        &self,
+        per_page: Option<u8>,
+        page: Option<u8>,
+        status: Option<PlanStatus>,
+        interval: Option<Interval>,
+        amount: Option<u32>,
+    ) -> PaystackResult<Vec<PlanResponseData>> {
+        let url = &self.base_url;
+
+        let per_page = per_page.unwrap_or(50).to_string();
+        let page = page.unwrap_or(1).to_string();
+
+        let mut query = vec![("perPage", per_page), ("page", page)];
+
+        // Process optional parameters
+        if let Some(s) = status {
+            query.push(("status", s.to_string()));
+        }
+
+        if let Some(i) = interval {
+            query.push(("interval", i.to_string()));
+        }
+
+        if let Some(a) = amount {
+            query.push(("amount", a.to_string()));
+        }
+
+        // convert all string to &str
+        // TODO: there has to be a cleaner way of doing this
+        let query: Vec<(&str, &str)> = query.iter().map(|(k, v)| (*k, v.as_str())).collect();
+
+        let response = self
+            .http
+            .get(url, &self.key, Some(&query))
+            .await
+            .map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        let parsed_response: Response<Vec<PlanResponseData>> =
+            serde_json::from_str(&response).map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        Ok(parsed_response)
+    }
+
+    /// Get details of a plan on your integration
+    ///
+    /// # Arguments
+    /// * `id_or_code` - the plan `ID` or `code` you want to fetch
+    ///
+    /// # Returns
+    /// A Result containing the plan response data or an error
+    pub async fn fetch_plan(&self, id_or_code: String) -> PaystackResult<PlanResponseData> {
+        let url = format!("{}/{}", &self.base_url, id_or_code);
+
+        let response = self
+            .http
+            .get(&url, &self.key, None)
+            .await
+            .map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        let parsed_response: Response<PlanResponseData> =
+            serde_json::from_str(&response).map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        Ok(parsed_response)
+    }
+
+    /// Update a plan details on your integration
+    ///
+    /// # Arguments
+    /// * `id_or_code` - the plan `ID` or `code` you want to update
+    /// * `plan_update_request` - The request data to update the plan with.
+    ///   Should be created with a `PlanUpdateRequestBuilder` struct.
+    ///
+    /// # Returns
+    /// A Result containing a success message if the plan has been updated
+    pub async fn update_plan(
+        &self,
+        id_or_code: String,
+        plan_update_request: PlanUpdateRequest,
+    ) -> PaystackResult<PhantomData<String>> {
+        let url = format!("{}/{}", self.base_url, id_or_code);
+        let body = serde_json::to_value(plan_update_request)
+            .map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        let response = self
+            .http
+            .put(&url, &self.key, &body)
+            .await
+            .map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        let parsed_response: Response<PhantomData<String>> =
+            serde_json::from_str(&response).map_err(|e| PaystackAPIError::Plan(e.to_string()))?;
+
+        Ok(parsed_response)
+    }
+}

src/endpoints/subaccount.rs

@@ -15,7 +15,7 @@ use std::sync::Arc;
 pub struct SubaccountEndpoints<T: HttpClient + Default> {
     /// Paystack API Key
     key: String,
-    /// Base URL for the transaction route
+    /// Base URL for the subaccount route
     base_url: String,
     /// Http client for the route
     http: Arc<T>,

src/endpoints/terminal.rs

@@ -16,7 +16,7 @@ use super::PAYSTACK_BASE_URL;
 pub struct TerminalEndpoints<T: HttpClient + Default> {
     /// Paystack API Key
     key: String,
-    /// Base URL for the transaction route
+    /// Base URL for the terminal route
     base_url: String,
     /// Http client for the route
     http: Arc<T>,

src/endpoints/transaction_split.rs

@@ -15,7 +15,7 @@ use std::sync::Arc;
 pub struct TransactionSplitEndpoints<T: HttpClient + Default> {
     /// Paystack API Key
     key: String,
-    /// Base URL for the transaction route
+    /// Base URL for the transaction split route
     base_url: String,
     /// Http client for the route
     http: Arc<T>,

src/endpoints/virtual_terminal.rs

@@ -15,7 +15,7 @@ use std::{marker::PhantomData, sync::Arc};
 pub struct VirtualTerminalEndpoints<T: HttpClient + Default> {
     /// Paystack API key
     key: String,
-    /// Base URL for the transaction route
+    /// Base URL for the virtual terminal route
     base_url: String,
     /// Http client for the route
     http: Arc<T>,

src/errors.rs

@@ -35,4 +35,6 @@ pub enum PaystackAPIError {
     DedicatedVirtualAccount(String),
     #[error("Apple Pay Error: {0}")]
     ApplePay(String),
+    #[error("Plan Error: {0}")]
+    Plan(String),
 }

src/models/currency_models.rs

@@ -18,6 +18,8 @@ use std::fmt;
 /// - `GHS`: Ghanaian Cedis.
 /// - `USD`: American Dollar.
 /// - `ZAR`: South African Rands.
+/// - `KES`: Kenya Shilling.
+/// - `XOF`: West African CFA Franc.
 /// - `EMPTY`: Used when the currency can be empty.
 ///
 /// # Examples
@@ -29,6 +31,8 @@ use std::fmt;
 /// let ghs = Currency::GHS;
 /// let usd = Currency::USD;
 /// let zar = Currency::ZAR;
+/// let kes = Currency::KES;
+/// let xof = Currency::XOF;
 /// let empty = Currency::EMPTY;
 ///
 /// println!("{:?}", ngn); // Prints: NGN
@@ -47,6 +51,10 @@ pub enum Currency {
     USD,
     /// South African Rands
     ZAR,
+    /// Kenya Shilling
+    KES,
+    /// West African CFA Franc
+    XOF,
     /// Used when currency can be empty.
     EMPTY,
 }
@@ -58,6 +66,8 @@ impl fmt::Display for Currency {
             Currency::GHS => "GHS",
             Currency::USD => "USD",
             Currency::ZAR => "ZAR",
+            Currency::KES => "KES",
+            Currency::XOF => "XOF",
             Currency::EMPTY => "",
         };
         write!(f, "{currency}")