upi_rs/
lib.rs

1//! # upi-rs: Type-Safe UPI Payment Integration Library
2//!
3//! A production-ready, type-safe, asynchronous, and provider-agnostic Rust crate
4//! for integrating UPI payment processing into your applications.
5//!
6//! ## Philosophy
7//!
8//! **"Parse, don't validate."** This crate enforces type safety at compile time,
9//! ensuring that illegal states (like negative amounts or invalid VPAs) are
10//! unrepresentable in the type system.
11//!
12//! ## Features
13//!
14//! - **Type-Safe Domain Models**: Invalid payment data cannot be constructed
15//! - **Provider Agnostic**: Swap payment providers without changing your code
16//! - **Async-First**: Built on `tokio` for modern async Rust
17//! - **Cryptographic Verification**: Constant-time HMAC-SHA256 signature verification
18//! - **Zero-Cost Abstractions**: Efficient implementations with minimal overhead
19//!
20//! ## Getting Started
21//!
22//! ### 1. Create Domain Objects
23//!
24//! ```ignore
25//! use upi_rs::types::{Vpa, Amount};
26//!
27//! // UPI address - validated at construction time
28//! let vpa = Vpa::new("customer@upi")?;
29//!
30//! // Monetary amount - stored in Paise (1 INR = 100 Paise)
31//! let amount = Amount::from_inr(100.50)?;
32//! ```
33//!
34//! ### 2. Initialize a Provider
35//!
36//! ```ignore
37//! use upi_rs::providers::RazorpayProvider;
38//!
39//! let provider = RazorpayProvider::new(
40//!     "your_key_id",
41//!     "your_key_secret"
42//! );
43//! ```
44//!
45//! ### 3. Process Payments
46//!
47//! ```ignore
48//! use upi_rs::traits::PaymentRequest;
49//!
50//! let request = PaymentRequest::new(vpa, amount, "TXN001".to_string());
51//!
52//! match provider.create_payment(request).await {
53//!     Ok(response) => println!("Payment ID: {}", response.id),
54//!     Err(e) => eprintln!("Payment failed: {}", e),
55//! }
56//! ```
57//!
58//! ### 4. Verify Webhooks
59//!
60//! ```ignore
61//! if provider.verify_webhook(payload, signature) {
62//!     println!("Webhook is authentic!");
63//! }
64//! ```
65//!
66//! ## Modules
67//!
68//! - [`error`]: Unified error type for the entire crate
69//! - [`types`]: Domain types with strict validation (`Vpa`, `Amount`)
70//! - [`security`]: Cryptographic verification utilities
71//! - [`traits`]: Provider abstraction layer
72//! - [`providers`]: Concrete payment gateway implementations
73
74pub mod error;
75pub mod providers;
76pub mod security;
77pub mod traits;
78pub mod types;
79
80// Re-export commonly used types at the crate root
81pub use error::UpiError;
82pub use providers::RazorpayProvider;
83pub use traits::{PaymentRequest, PaymentResponse, PaymentStatus, UpiProvider};
84pub use types::{Amount, Vpa};
85
86/// The version of this crate.
87pub const VERSION: &str = env!("CARGO_PKG_VERSION");
88
89#[cfg(test)]
90mod tests {
91    use super::*;
92
93    #[test]
94    fn test_version() {
95        assert!(!VERSION.is_empty());
96    }
97
98    #[test]
99    fn test_public_api_exports() {
100        // Verify key types are exported at crate root
101        let _ = UpiError::ValidationError("test".to_string());
102        let _ = Amount::from_inr(100.0);
103        let _ = Vpa::new("test@upi");
104    }
105}
upi_rs/lib.rs

upi_rs/
lib.rs
