Skip to content

Commit

Permalink
Add documentation and fix minor details
Browse files Browse the repository at this point in the history
  • Loading branch information
kevin-pease authored and tluijken committed May 30, 2024
1 parent 7dee9c4 commit aafc8ec
Show file tree
Hide file tree
Showing 4 changed files with 96 additions and 11 deletions.
49 changes: 46 additions & 3 deletions stellar_rust_sdk/src/horizon_client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1432,15 +1432,58 @@ impl HorizonClient {
self.get::<TransactionResponse>(request).await
}

// TODO: Documentation

/// Retrieves a list of all transactions from the Horizon server.
///
/// This asynchronous method fetches a list of all transactions from the Horizon server.
/// It requires an [`AllTransactionsRequest`] to specify the optional query parameters.
///
/// # Arguments
/// * `request` - A reference to an [`AllTransactionsRequest`] instance, containing the
/// parameters for the transactions request.
///
/// # Returns
///
/// On successful execution, returns a `Result` containing an [`AllTransactionsResponse`], which includes
/// the list of all transactions obtained from the Horizon server. If the request fails, it returns an error within `Result`.
///
/// # Usage
/// To use this method, create an instance of [`AllTransactionsRequest`] and set any desired
/// filters or parameters.
///
/// ```
/// # use stellar_rs::transactions::prelude::*;
/// # use stellar_rs::models::Request;
/// # use stellar_rs::horizon_client::HorizonClient;
/// # use stellar_rust_sdk_derive::Pagination;
/// # use stellar_rs::Paginatable;
/// #
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let base_url = "https://horizon-testnet.stellar.org".to_string();
/// # let horizon_client = HorizonClient::new(base_url)
/// # .expect("Failed to create Horizon Client");
/// let request = AllTransactionsRequest::new()
/// .set_include_failed(true).unwrap();
///
/// let response = horizon_client.get_all_transactions(&request).await;
///
/// // Access the transactions
/// if let Ok(transactions_response) = response {
/// for transaction in transactions_response.embedded().records() {
/// println!("Transaction ID: {}", transaction.id());
/// // Further processing...
/// }
/// }
/// # Ok({})
/// # }
/// ```
///
pub async fn get_all_transactions(
&self,
request: &AllTransactionsRequest,
) -> Result<AllTransactionsResponse, String> {
self.get::<AllTransactionsResponse>(request).await
}


}

/// Handles the response received from an HTTP request made to the Horizon server.
Expand Down
36 changes: 33 additions & 3 deletions stellar_rust_sdk/src/transactions/all_transactions_request.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,35 @@ use crate::{models::*, BuildQueryParametersExt};
use stellar_rust_sdk_derive::Pagination;
use crate::Paginatable;

// TODO: Documentation
/// Represents a request to list all transactions from the Stellar Horizon API.
///
/// This structure is used to construct a query to retrieve a comprehensive list of transactions, which
/// can be filtered by setting `include_failed`. It adheres to the structure and parameters required
/// by the Horizon API for retrieving a
/// <a href="https://developers.stellar.org/network/horizon/api-reference/resources/list-all-transactions">list of all transactions</a>.
///
/// # Usage
///
/// Create an instance of this struct and set the desired query parameters to filter the list of transactions.
/// Pass this request object to the [`HorizonClient::get_all_transactions`](crate::horizon_client::HorizonClient::get_all_transactions)
/// method to fetch the corresponding data from the Horizon API.
///
/// # Example
/// ```
/// use stellar_rs::transactions::all_transactions_request::AllTransactionsRequest;
/// use stellar_rs::models::{Order};
/// use stellar_rust_sdk_derive::Pagination;
/// use stellar_rs::Paginatable;
///
/// let request = AllTransactionsRequest::new()
/// .set_include_failed(true).unwrap() // Optional flag to include failed transactions
/// .set_cursor(123).unwrap() // Optional cursor for pagination
/// .set_limit(100).unwrap() // Optional limit for response records
/// .set_order(Order::Desc); // Optional order of records
///
/// // Use with HorizonClient::get_all_transactions
/// ```
///
#[derive(Default, Pagination)]
pub struct AllTransactionsRequest {
// Indicates whether or not to include failed operations in the response.
Expand All @@ -29,7 +57,6 @@ impl Request for AllTransactionsRequest {
.build_query_parameters()
}

// TODO: Documentation
fn build_url(&self, base_url: &str) -> String {
format!(
"{}/{}{}",
Expand All @@ -46,7 +73,10 @@ impl AllTransactionsRequest {
AllTransactionsRequest::default()
}

// TODO: Documentation
/// Specifies whether to include failed operations in the response.
///
/// # Arguments
/// * `include_failed` (bool) - when set to `true`, failed operations will be included.
pub fn set_include_failed(self, include_failed: bool) -> Result<AllTransactionsRequest, String> {
Ok(AllTransactionsRequest {
include_failed: Some(include_failed),
Expand Down
16 changes: 12 additions & 4 deletions stellar_rust_sdk/src/transactions/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,14 @@
///
pub mod single_transaction_request;

/// TODO: Documentation
/// Provides the `AllTransactionsRequest`.
///
/// # Usage
/// This module provides the `AllTransactionsRequest` struct, specifically designed for
/// constructing requests to query information about all transactions from the Horizon
/// server. It is tailored for use with the [`HorizonClient::get_all_transactions`](crate::horizon_client::HorizonClient::get_all_transactions)
/// method.
///
pub mod all_transactions_request;

/// Provides the responses.
Expand All @@ -26,7 +33,7 @@ pub mod response;
///
/// # Usage
/// This variable is intended to be used internally by the request-building logic
/// to ensure consistent and accurate path construction for offer-related API calls.
/// to ensure consistent and accurate path construction for transaction-related API calls.
static TRANSACTIONS_PATH: &str = "transactions";

/// The `prelude` module of the `transactions` module.
Expand Down Expand Up @@ -67,7 +74,7 @@ pub mod prelude {
#[cfg(test)]
pub mod test {
use super::prelude::*;
use crate::{horizon_client::HorizonClient, models::Request};
use crate::horizon_client::HorizonClient;

#[tokio::test]
async fn test_get_single_transaction() {
Expand Down Expand Up @@ -179,7 +186,8 @@ pub mod test {
.to_string())
.unwrap();

let all_transactions_request = AllTransactionsRequest::new().set_include_failed(true).unwrap();
let all_transactions_request = AllTransactionsRequest::new()
.set_include_failed(true).unwrap();

let all_transactions_response = horizon_client
.get_all_transactions(&all_transactions_request)
Expand Down
6 changes: 5 additions & 1 deletion stellar_rust_sdk/src/transactions/response.rs
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,11 @@ pub struct LedgerBounds {
max_ledger: Option<String>,
}

// TODO: Documentation
/// Represents the response for the 'all transactions' query in the Horizon API.
///
/// This struct defines the overall structure of the response for an 'all transactions' query.
/// It includes navigational links and embedded results.
///
#[derive(Debug, Clone, Serialize, Deserialize, Getters)]
#[serde(rename_all = "camelCase")]
pub struct AllTransactionsResponse {
Expand Down

0 comments on commit aafc8ec

Please sign in to comment.