diff --git a/src/claimable_balances/all_claimable_balances_request.rs b/src/claimable_balances/all_claimable_balances_request.rs index 36ca991..b8f20ef 100644 --- a/src/claimable_balances/all_claimable_balances_request.rs +++ b/src/claimable_balances/all_claimable_balances_request.rs @@ -4,7 +4,9 @@ use crate::{models::*, BuildQueryParametersExt}; /// /// This structure is used to construct a query to retrieve a comprehensive list of claimable balances, which /// can be filtered by sponsor, asset, or claimant. Claimable balances are a feature of the Stellar network -/// that allows users to create a balance of assets that can be claimed by another account. +/// that allows users to create a balance of assets that can be claimed by another account. It adheres to the structure and parameters required +/// by the Horizon API for retrieving a +/// list of claimable balances. /// /// # Usage /// diff --git a/src/claimable_balances/mod.rs b/src/claimable_balances/mod.rs index c8317e0..ba379a3 100644 --- a/src/claimable_balances/mod.rs +++ b/src/claimable_balances/mod.rs @@ -80,15 +80,94 @@ pub mod all_claimable_balances_request; /// # } /// ``` /// -/// The `all_claimable_balances_response` module is an essential part of the SDK that allows developers -/// to work with claimable balances, supporting the building of applications that interact with -/// this Stellar network feature. pub mod all_claimable_balances_response; +/// Provides the `SingleClaimableBalanceRequest` struct. +/// +/// This module contains the `SingleClaimableBalanceRequest` struct, which is utilized to create +/// requests for retrieving information about a single claimable balance from the Stellar Horizon API. +/// It is specifically designed to query detailed data for a particular claimable balance identified by its ID. +/// +/// The struct is intended to be used with the [`HorizonClient`](crate::horizon_client::HorizonClient) +/// to perform API calls and fetch detailed information about a specific claimable balance. +/// +/// # Usage +/// +/// To use this module, instantiate a `SingleClaimableBalanceRequest` and set the claimable balance ID. +/// Then, pass this request to the [`HorizonClient::get_single_claimable_balance`](crate::horizon_client::HorizonClient::get_single_claimable_balance) method to execute the query. +/// The method returns a `SingleClaimableBalanceResponse` with the detailed information. +/// +/// # Example +/// ``` +/// # use stellar_rust_sdk::claimable_balances::single_claimable_balance_request::SingleClaimableBalanceRequest; +/// # use stellar_rust_sdk::horizon_client::HorizonClient; +/// # use stellar_rust_sdk::models::Request; +/// # +/// # async fn fetch_claimable_balance() -> Result<(), Box> { +/// # let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?; +/// let request = SingleClaimableBalanceRequest::new() +/// .set_claimable_balance_id("00000000".to_string()); // Example claimable balance ID +/// +/// let response = horizon_client.get_single_claimable_balance(&request).await?; +/// // Process the response +/// # Ok(()) +/// # } +/// ``` +/// pub mod single_claimable_balance_request; +/// Provides the `SingleClaimableBalanceResponse`. +/// +/// This module contains structures representing the response received from the Horizon API +/// when querying a single claimable balance. The main structure, `SingleClaimableBalanceResponse`, +/// is designed to convert the JSON response from the Horizon server into structured Rust objects. +/// This allows for easier handling and utilization of claimable balance data within client applications. +/// +/// For a detailed description of the response structure, refer to the +/// [Retrieve a Single Claimable Balance](https://developers.stellar.org/api/horizon/resources/retrieve-a-claimable-balance) +/// endpoint documentation on the Stellar Developer's site. +/// +/// The structures in this module include serialization and deserialization capabilities to handle +/// JSON data returned by the Horizon server. The `Getters` derive macro is used to provide +/// convenient getter methods for accessing fields of these structures. +/// +/// # Usage +/// +/// The response structures are primarily used internally by the `HorizonClient` when processing +/// responses from claimable balance-related API calls. The `SingleClaimableBalanceResponse` struct +/// is especially important as it is returned by the +/// [`HorizonClient::get_single_claimable_balance`](crate::horizon_client::HorizonClient::get_single_claimable_balance) +/// method, providing a user-friendly way to access data of a single claimable balance. +/// +/// # Example +/// +/// ``` +/// # use stellar_rust_sdk::claimable_balances::prelude::{SingleClaimableBalanceRequest, SingleClaimableBalanceResponse}; +/// # use stellar_rust_sdk::horizon_client::HorizonClient; +/// # use stellar_rust_sdk::models::Response; +/// # +/// # async fn example() -> Result<(), Box> { +/// # let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?; +/// let claimable_balance_id = "123456789abcdefg".to_string(); +/// let request = SingleClaimableBalanceRequest::new() +/// .set_claimable_balance_id(claimable_balance_id); +/// +/// let response = horizon_client +/// .get_single_claimable_balance(&request) +/// .await; +/// +/// // Access the details of the claimable balance +/// if let Ok(balance_response) = response { +/// println!("Balance Amount: {}", balance_response.amount()); +/// // Further processing... +/// } +/// # Ok(()) +/// # } +/// ``` +/// pub mod single_claimable_balance_response; + /// The base path for all claimable balance related endpoints in the Stellar Horizon API. /// /// This static variable holds the string slice that represents the common base path used in constructing diff --git a/src/claimable_balances/single_claimable_balance_request.rs b/src/claimable_balances/single_claimable_balance_request.rs index b69277a..1947dc2 100644 --- a/src/claimable_balances/single_claimable_balance_request.rs +++ b/src/claimable_balances/single_claimable_balance_request.rs @@ -1,22 +1,62 @@ use crate::models::*; +/// Represents the ID of a claimable balance. #[derive(Default, Clone)] pub struct ClaimableBalanceId(String); + +/// Represents the absence of a claimable balance ID. #[derive(Default, Clone)] pub struct NoClaimableBalanceId; -/// SingleClaimableBalanceRequest is the struct that implements the type for the /claimable_balances endpoint to get a single claimable balance -/// [More Details](https://developers.stellar.org/api/horizon/resources/retrieve-a-claimable-balance) "Single Claimable Balance") +/// Represents a request to retrieve information about a single claimable balance from the Stellar Horizon API. +/// +/// The `SingleClaimableBalanceRequest` struct is designed for querying detailed data for a specific +/// claimable balance, identified by its unique ID. It adheres to the structure and parameters required +/// by the Horizon API for retrieving a +/// single claimable balance. +/// +/// The struct is used in conjunction with the [`HorizonClient`](crate::horizon_client::HorizonClient) to +/// make API calls to the Horizon server and fetch the desired claimable balance information. +/// +/// # Usage +/// +/// To create a request, instantiate a `SingleClaimableBalanceRequest` and set the claimable balance ID +/// using `set_claimable_balance_id`. Then, pass the request object to the [`HorizonClient::get_single_claimable_balance`](crate::horizon_client::HorizonClient::get_single_claimable_balance) +/// method to execute the query. The method returns a `SingleClaimableBalanceResponse` containing the details of the claimable balance. +/// +/// # Example +/// ``` +/// # use stellar_rust_sdk::claimable_balances::single_claimable_balance_request::SingleClaimableBalanceRequest; +/// # use stellar_rust_sdk::horizon_client::HorizonClient; +/// # use stellar_rust_sdk::models::Request; +/// # +/// # async fn fetch_single_claimable_balance() -> Result<(), Box> { +/// # let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?; +/// let request = SingleClaimableBalanceRequest::new() +/// .set_claimable_balance_id("00000000".to_string()); // Example claimable balance ID +/// +/// let response = horizon_client.get_single_claimable_balance(&request).await?; +/// // Process the response +/// # Ok(()) +/// # } +/// ``` +/// #[derive(Default)] pub struct SingleClaimableBalanceRequest { claimable_balance_id: I, } impl SingleClaimableBalanceRequest { + /// Creates a new `SingleClaimableBalanceRequest` with default parameters. pub fn new() -> Self { SingleClaimableBalanceRequest::default() } + /// Sets the claimable balance ID for the request. + /// + /// # Arguments + /// * `claimable_balance_id` - A `String` representing the claimable balance ID. + /// pub fn set_claimable_balance_id( self, claimable_balance_id: String, diff --git a/src/claimable_balances/single_claimable_balance_response.rs b/src/claimable_balances/single_claimable_balance_response.rs index 05d9331..1118a7c 100644 --- a/src/claimable_balances/single_claimable_balance_response.rs +++ b/src/claimable_balances/single_claimable_balance_response.rs @@ -6,100 +6,162 @@ use serde::Serialize; use crate::models::Response; +/// Represents the response to a single claimable balance query in the Horizon API. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct SingleClaimableBalanceResponse { + /// Links to related resources in the Horizon API response. #[serde(rename = "_links")] pub links: Links, + + /// The unique identifier of the claimable balance. pub id: String, + + /// The asset type of the claimable balance. pub asset: String, + + /// The amount of the claimable balance. pub amount: String, + + /// The account ID of the sponsor of the claimable balance. pub sponsor: String, + + /// The ledger number in which the claimable balance was last modified. #[serde(rename = "last_modified_ledger")] pub last_modified_ledger: i64, + + /// The timestamp when the claimable balance was last modified. #[serde(rename = "last_modified_time")] pub last_modified_time: String, + + /// A list of claimants eligible to claim the balance. pub claimants: Vec, + + /// Flags indicating special conditions of the claimable balance. pub flags: Flags, + + /// A token used for paging through results. #[serde(rename = "paging_token")] pub paging_token: String, } +/// Contains navigational links related to the single claimable balance response. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Links { + /// The link to the current claimable balance resource. #[serde(rename = "self")] pub self_field: SelfField, + + /// Link to transactions related to the claimable balance. pub transactions: Transactions, + + /// Link to operations related to the claimable balance. pub operations: Operations, } +/// Represents a navigational link in the Horizon API response. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct SelfField { + /// The URL of the link. pub href: String, } +/// Represents a link to the transactions of a claimable balance. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Transactions { + /// The URL of the transactions link. pub href: String, + + /// Indicates if the link is templated. pub templated: bool, } +/// Represents a link to the operations of a claimable balance. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Operations { + /// The URL of the operations link. pub href: String, + + /// Indicates if the link is templated. pub templated: bool, } +/// Represents a claimant of a claimable balance. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Claimant { + /// The account ID of the claimant. pub destination: String, + + /// Conditions that need to be met for the claimant to claim the balance. pub predicate: Predicate, } +/// Represents conditions under which a claimable balance can be claimed. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Predicate { + /// Indicates if the claim is unconditional. pub unconditional: Option, + + /// Conditions combined using the logical 'or' operation. pub or: Option>, } +/// Represents an 'or' condition in a claimable balance's claim predicate. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Or { + /// Conditions combined using the logical 'and' operation. pub and: Option>, + + /// Specifies the absolute time before which the claim is valid. #[serde(rename = "abs_before")] pub abs_before: Option, + + /// The epoch time representation of `abs_before`. #[serde(rename = "abs_before_epoch")] pub abs_before_epoch: Option, } +/// Represents an 'and' condition in a claimable balance's claim predicate. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct And { + /// A negation of a condition. pub not: Option, + + /// Specifies the absolute time before which the claim is valid. #[serde(rename = "abs_before")] pub abs_before: Option, + + /// The epoch time representation of `abs_before`. #[serde(rename = "abs_before_epoch")] pub abs_before_epoch: Option, } +/// Represents a 'not' condition in a claimable balance's claim predicate. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Not { + /// Specifies the absolute time before which the claim is invalid. #[serde(rename = "abs_before")] pub abs_before: String, + + /// The epoch time representation of `abs_before`. #[serde(rename = "abs_before_epoch")] pub abs_before_epoch: String, } +/// Flags indicating special conditions of the claimable balance. #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct Flags { + /// Indicates if the clawback feature is enabled for the claimable balance. #[serde(rename = "clawback_enabled")] pub clawback_enabled: bool, }