# Rain SDK
[](https://docs.rs/rain-sdk)
[](https://crates.io/crates/rain-sdk)
[](LICENSE)
[](https://www.rust-lang.org)
[](https://docs.rs/rain-sdk)
[](https://github.com/yezz123/rain-rust-sdk/actions/workflows/ci.yaml)
[](https://deps.rs/repo/github/yezz123/rain-rust-sdk)
---
A modern, type-safe Rust SDK for the [Rain Cards API](https://raincards.xyz).
## Features
- ✅ **100% API Coverage**: All 71 non-deprecated endpoints fully implemented
- ✅ **OpenAPI Aligned**: Fully aligned with the official OpenAPI specification
- ✅ **Async and Sync Support**: Use async/await or blocking operations via feature flags
- ✅ **Type Safety**: Strongly typed models for all API endpoints with proper serialization
- ✅ **API Key Authentication**: Simple API key-based authentication
- ✅ **Comprehensive Error Handling**: Detailed error types with HTTP status codes and context
- ✅ **Production Ready**: Well-tested, documented, and validated
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
rain-sdk = { version = "0.1.0", features = ["async"] }
```
For blocking/sync operations:
```toml
[dependencies]
rain-sdk = { version = "0.1.0", features = ["sync"] }
```
## Quick Start
### Async Example
```rust
use rain_sdk::{RainClient, Config, Environment, AuthConfig};
use rain_sdk::models::applications::InitiateUserApplicationRequest;
use uuid::Uuid;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create configuration for dev environment
let config = Config::new(Environment::Dev);
// Create authentication config with API key
let auth = AuthConfig::with_api_key("your-api-key".to_string());
// Create the client
let client = RainClient::new(config, auth)?;
// Initiate a user application
let request = InitiateUserApplicationRequest {
first_name: "John".to_string(),
last_name: "Doe".to_string(),
email: "john@example.com".to_string(),
wallet_address: None,
};
let application = client.initiate_user_application(&request).await?;
println!("Application ID: {}", application.id);
Ok(())
}
```
### Sync Example
```rust
use rain_sdk::{RainClient, Config, Environment, AuthConfig};
use rain_sdk::models::applications::InitiateUserApplicationRequest;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = Config::new(Environment::Dev);
let auth = AuthConfig::with_api_key("your-api-key".to_string());
let client = RainClient::new(config, auth)?;
let request = InitiateUserApplicationRequest {
first_name: "John".to_string(),
last_name: "Doe".to_string(),
email: "john@example.com".to_string(),
wallet_address: None,
};
let application = client.initiate_user_application_blocking(&request)?;
println!("Application ID: {}", application.id);
Ok(())
}
```
## Authentication
The SDK supports API key authentication:
```rust
let auth = AuthConfig::with_api_key("your-api-key".to_string());
```
## Examples
See the [examples](examples/) directory for usage examples:
- **[Basic Client](./examples/basic_client.rs)** - Initialize a client and make simple API calls
- **[Initiate User Application](./examples/initiate_user_application.rs)** - Initiate a user application
- **[Consumer Signup](./examples/signup_consumer.rs)** - Complete consumer signup workflow
- **[Corporate Signup](./examples/signup_corporate.rs)** - Complete corporate signup workflow
- **[Manage Corporate Users](./examples/manage_corporate_users.rs)** - Manage users in corporate programs (add, deactivate, delete)
Run an example:
```bash
cargo run --example signup_consumer --features async
```
## API Coverage
The SDK provides **100% coverage** of the Rain Issuing API, with all 71 non-deprecated endpoints fully implemented and aligned with the OpenAPI specification.
## Error Handling
The SDK uses a comprehensive error type system with detailed HTTP status codes:
```rust
use rain_sdk::error::RainError;
match client.get_user_application(&user_id).await {
Ok(application) => println!("Success: {:?}", application),
Err(RainError::ApiError { status, response }) => {
println!("API error (status {}): {}", status, response);
// Common status codes:
// - 400: Invalid request
// - 401: Invalid authorization
// - 403: Forbidden
// - 404: Not found
// - 409: Conflict
// - 423: Locked
// - 500: Internal server error
},
Err(RainError::HttpError(err)) => println!("HTTP error: {}", err),
Err(RainError::AuthError(msg)) => println!("Auth error: {}", msg),
Err(e) => println!("Other error: {}", e),
}
```
## Configuration
### Environment Selection
```rust
// Dev (default)
let config = Config::new(Environment::Dev);
// Production
let config = Config::new(Environment::Production);
// Custom URL
let config = Config::new(Environment::Custom(
url::Url::parse("https://api.custom.com/v1")?
));
```
### Custom Configuration
```rust
let config = Config::new(Environment::Dev)
.with_timeout(60) // 60 second timeout
.with_user_agent("my-app/1.0".to_string())
.with_logging(true);
```
## Features
- `default`: Enables async support with rustls-tls
- `async`: Async/await support (requires tokio)
- `sync`: Blocking/synchronous operations
- `rustls-tls`: Use rustls for TLS (default)
- `native-tls`: Use native TLS implementation
- `gzip`: Enable gzip compression
- `json`: JSON serialization support (enabled by default)
## Documentation
- **[Signup Guide](./docs/signup.md)** - Complete guide for signing up customers (Consumer and Corporate programs)
- **[Managing Users Guide](./docs/managing_users.md)** - Guide for managing users in corporate programs (add, deactivate, delete)
- **[Managing Cards Guide](./docs/managing_cards.md)** - Guide for issuing and managing cards (virtual, physical, bulk shipping, encrypted details)
## License
Licensed under the MIT license ([LICENSE](LICENSE)).
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.