Rain SDK

A modern, type-safe Rust SDK for the Rain Cards API.

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:

[dependencies]
rain-sdk = { version = "0.1.0", features = ["async"] }

For blocking/sync operations:

[dependencies]
rain-sdk = { version = "0.1.0", features = ["sync"] }

Quick Start

Async Example

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

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:

let auth = AuthConfig::with_api_key("your-api-key".to_string());

Examples

See the examples directory for usage examples:

• Basic Client - Initialize a client and make simple API calls
• Initiate User Application - Initiate a user application
• Consumer Signup - Complete consumer signup workflow
• Corporate Signup - Complete corporate signup workflow
• Manage Corporate Users - Manage users in corporate programs (add, deactivate, delete)

Run an example:

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:

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

// 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

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 - Complete guide for signing up customers (Consumer and Corporate programs)
• Managing Users Guide - Guide for managing users in corporate programs (add, deactivate, delete)
• Managing Cards Guide - Guide for issuing and managing cards (virtual, physical, bulk shipping, encrypted details)

License

Licensed under the MIT license (LICENSE).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.