pricing_kit 0.1.5

A flexible, lightweight Rust library for pricing strategies, including calculating and managing prices, markup, commissions, and multi-currency support.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

//! # 🧮 pricing_kit
//!
//! A flexible and extensible Rust library for calculating and managing product pricing, markups, commissions, and currency conversions.
//!
//! ## ✨ Features
//!
//! - Define a **base (buy) price** and calculate **sell prices** based on:
//!   - Flat amount markups
//!   - Percentage markups
//!   - Commissions in other currencies
//! - Support for **multi-currency** operations using exchange rates, ensuring **financial precision** with `Decimal` types.
//! - Support for **adjustments** such as:
//!   - **Tax** calculations with percentage-based rates
//!   - **Discounts** based on percentage
//!   - **Fixed fees** with customizable currencies
//! - Clean and extensible API design, ready for future enhancements.
//!
//! ---
//!
//! ## ⚡ Quick Start
//!
//! ```rust
//! use pricing_kit::{Currency, CurrencyConverter, PricingDetail, MarkupType, dec, ToPrimitive};
//!
//! // fn main() {
//!     let usd = Currency::new("USD", "American Dollar");
//!     let idr = Currency::new("IDR", "Indonesian Rupiah");
//!
//!     let mut converter = CurrencyConverter::new();
//!     converter.add_exchange_rate(&usd, dec!(1.0));
//!     converter.add_exchange_rate(&idr, dec!(16500.0));
//!
//!     let mut pricing = PricingDetail::new(dec!(100.0), usd.clone(), idr.clone());
//!
//!     pricing.markup = Some(MarkupType::Amount {
//!         value: dec!(3500),
//!         currency: idr.clone(),
//!     });
//!
//!     pricing.apply_markup(&converter).expect("Failed to apply markup");
//!
//!     println!("Pricing after markup:\n{:#?}", pricing);
//!
//!     // Manual calculation for comparative purpose:
//!     // 1. Buy price: 100.0 USD
//!     // 2. Markup: Amount 3500 IDR → converted to USD = 3500 / 16500 = ~0.21212121 USD
//!     // 3. Converted buy price: 100 + 0.21212121 = ~100.21212121 USD
//!     // 4. Exchange rate USD → IDR = 16500
//!     // 5. Final sell price: 100.21212121 * 16500 = 1_653_500.0 IDR
//!
//!     if let Some(total_f64) = pricing.sell_price.to_f64() {
//!         println!("Total sell price as f64: {}", total_f64);
//!     }
//! // }
//! ```
//!
//!
//! ---
//!
//! ## ⚡ Adjustment Feature Example
//!
//! ```rust
//! use pricing_kit::{Currency, CurrencyConverter, PricingDetail, MarkupType, dec, PriceAdjustment, ToPrimitive};
//!
//! // fn main() {
//!     let usd = Currency::new("USD", "American Dollar");
//!     let idr = Currency::new("IDR", "Indonesian Rupiah");
//!
//!     let mut converter = CurrencyConverter::new();
//!     converter.add_exchange_rate(&usd, dec!(1.0));
//!     converter.add_exchange_rate(&idr, dec!(16500.0));
//!
//!     let mut pricing = PricingDetail::new(dec!(100.0), usd.clone(), idr.clone());
//!     pricing.markup = Some(MarkupType::Percentage(dec!(20.0)));
//!     pricing.apply_markup(&converter).expect("Failed to apply markup");
//!
//!     let adjustments = vec![
//!         PriceAdjustment::Tax {
//!             name: "Tax 11%".into(),
//!             percentage: dec!(11.0),
//!         },
//!         PriceAdjustment::Discount {
//!             name: "Discount".into(),
//!             percentage: dec!(5.0),
//!         },
//!         PriceAdjustment::Fixed {
//!             name: "Promo New Year".to_string(),
//!             amount: dec!(10.0),
//!             currency: pricing.sell_currency.clone(),
//!         }
//!     ];
//!
//!     pricing.apply_adjustments(&adjustments, &converter).expect("Failed to apply adjustments");
//!
//!     println!("Adjustment Pricing:\n{:#?}", pricing);
//!
//!     // Manual calculation for comparative purpose:
//!     // 1. Buy price in USD: 100.0
//!     // 2. Markup 20% -> 100 * 0.2 = 20 USD
//!     // 3. Converted buy price: 100 + 20 = 120 USD
//!     // 4. Sell price in IDR: 120 * 16500 = 1_980_000 IDR
//!
//!     // Adjustments:
//!     // + Tax 11% of 1_980_000 = 217_800 -> 2_197_800
//!     // - Discount 5% of 2_197_800 = 109_890 -> 2_087_910
//!     // + Fixed amount 10 IDR -> final = 2_087_920.0 IDR
//!
//!     if let Some(total_f64) = pricing.sell_price.to_f64() {
//!         println!("Total sell price as f64: {}", total_f64);
//!     }
//! // }
//! ```
//!
//! ---
//!
//! ## 🎯 Crate Goals
//!
//! This crate is designed to be:
//!
//! - Easy to use for common e-commerce and fintech pricing scenarios.
//! - **Accurate**, currency-aware, and reliable in financial calculations through explicit `Decimal` usage.
//! - Ready for dynamic adjustments such as tax, discount, and fixed fees.
//! - Extensible for future features like tiered pricing, tax rules, and promotions.
//!
//! ---
//!
//! ## ♻️ Re-exports for Convenience
//!
//! For ease of use and to ensure robust financial calculations, `pricing_kit` **re-exports** the following types and macros from the `rust_decimal` ecosystem:
//!
//! -   `Decimal` (from the `rust_decimal` crate): Used for all currency amounts and exchange rates to ensure arbitrary precision arithmetic and avoid floating-point inaccuracies.
//! -   `dec!` macro (from the `rust_decimal_macros` crate): A convenient macro for creating `Decimal` literals in your code.
//!
//! This means you can use `pricing_kit::Decimal` and `pricing_kit::dec!` directly without needing to explicitly import them from their original crates, although you still need to declare `rust_decimal` and `rust_decimal_macros` in your `Cargo.toml`.
//!
//! ```toml
//! [dependencies]
//! rust_decimal = "1.37.2"
//! rust_decimal_macros = "1.37.1"
//! ```
//! ---
//!
//! ## 📖 License
//!
//! This project is licensed under the Apache-2.0 license. [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt)
//!
//! ---
//!
//! ## 🧑 Author
//! Jerry Maheswara <jerrymaheswara@gmail.com>
//!
//! ---
//!
//! ## ❤️ Built with Love in Rust
//!
//! This project is built with ❤️ using **Rust** — a systems programming language that is safe, fast, and concurrent. Rust is the perfect choice for building reliable and efficient applications.
//!
//! ---
//!
//! ## 👋 Contributing
//!
//! Pull requests, issues, and feedback are welcome!
//! If you find this crate useful, give it a ⭐ and share it with others in the Rust community.
//!
//! ---

/// Core data model definitions for pricing operations.
pub mod model;

#[doc(inline)]
pub use rust_decimal::Decimal;
#[doc(inline)]
pub use rust_decimal::prelude::ToPrimitive;
#[doc(inline)]
pub use rust_decimal_macros::dec;

pub use model::currency::*;
pub use model::pricing::*;
pub use model::markup::*;
pub use model::adjustment::*;
pub use model::error::*;