inf_circle_sdk/

helper.rs

//! Shared helper functions and types used across the SDK
//!
//! This module provides common utilities, error types, HTTP client functionality,
//! and cryptographic helpers used throughout the Circle SDK.
//!
//! # Main Components
//!
//! - [`CircleError`]: Comprehensive error type for all SDK operations
//! - [`CircleResult`]: Type alias for `Result<T, CircleError>`
//! - [`HttpClient`]: Configured HTTP client for Circle API requests
//! - [`encrypt_entity_secret`]: RSA-OAEP encryption for entity secrets
//! - Serialization helpers for API compatibility
//!
//! # Error Handling
//!
//! All SDK operations return `CircleResult<T>` which provides detailed error information:
//!
//! ```rust
//! use inf_circle_sdk::helper::{CircleError, CircleResult};
//!
//! fn example_function() -> CircleResult<String> {
//!     // Environment variable errors
//!     // HTTP request errors  
//!     // JSON parsing errors
//!     // API errors with status codes
//!     // etc.
//!     Ok("Success".to_string())
//! }
//! ```

use chrono::{DateTime, Utc};
use reqwest::{Client, Method, RequestBuilder, Response};
use serde::{Deserialize, Serialize, Serializer};
use std::collections::HashMap;
use thiserror::Error;
use url::Url;

// Cryptography imports
use anyhow::{anyhow, Result as AnyhowResult};
use base64::{engine::general_purpose, Engine};
use rsa::{pkcs1::DecodeRsaPublicKey, pkcs8::DecodePublicKey, Oaep, RsaPublicKey};
use sha2::Sha256;

/// Result type alias for Circle SDK operations
pub type CircleResult<T> = Result<T, CircleError>;

/// Comprehensive error type for Circle SDK operations
///
/// This enum covers all possible errors that can occur when using the Circle SDK,
/// including environment configuration errors, HTTP request failures, JSON parsing issues,
/// and API-specific errors with status codes.
///
/// # Variants
///
/// - `EnvVar`: Missing or invalid environment variables
/// - `Http`: HTTP request failures (network errors, timeouts, etc.)
/// - `Json`: JSON serialization/deserialization errors
/// - `Url`: URL parsing errors
/// - `Api`: Circle API errors with HTTP status code and message
/// - `Config`: Invalid SDK configuration
/// - `Uuid`: UUID parsing or generation errors
#[derive(Error, Debug)]
pub enum CircleError {
    #[error("Environment variable error: {0}")]
    EnvVar(String),

    #[error("HTTP request error: {0}")]
    Http(#[from] reqwest::Error),

    #[error("JSON serialization/deserialization error: {0}")]
    Json(#[from] serde_json::Error),

    #[error("URL parsing error: {0}")]
    Url(#[from] url::ParseError),

    #[error("API error: {status} - {message}")]
    Api { status: u16, message: String },

    #[error("Invalid configuration: {0}")]
    Config(String),

    #[error("UUID error: {0}")]
    Uuid(#[from] uuid::Error),
}

/// Standard Circle API response wrapper
#[derive(Debug, Deserialize, Serialize)]
pub struct CircleResponse<T> {
    pub data: T,
}

/// Standard Circle API error response
#[derive(Debug, Deserialize, Serialize)]
pub struct CircleErrorResponse {
    pub code: Option<i32>,
    pub message: String,
}

/// Helper function to serialize u32 as string
pub fn serialize_u32_as_string<S>(value: &Option<u32>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    match value {
        Some(val) => serializer.serialize_str(&val.to_string()),
        None => serializer.serialize_none(),
    }
}

/// Helper function to serialize DateTime as string
pub fn serialize_datetime_as_string<S>(
    dt: &Option<DateTime<Utc>>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    match dt {
        Some(dt) => serializer.serialize_str(&dt.to_rfc3339()),
        None => serializer.serialize_none(),
    }
}

pub fn serialize_bool_as_string<S>(value: &Option<bool>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    match value {
        Some(val) => serializer.serialize_str(&val.to_string()),
        None => serializer.serialize_none(),
    }
}

/// Common query parameters for pagination
#[derive(Debug, Serialize, Default, Clone, Deserialize)]
pub struct PaginationParams {
    #[serde(rename = "pageAfter", skip_serializing_if = "Option::is_none")]
    pub page_after: Option<String>,

    #[serde(rename = "pageBefore", skip_serializing_if = "Option::is_none")]
    pub page_before: Option<String>,

    #[serde(
        rename = "pageSize",
        skip_serializing_if = "Option::is_none",
        serialize_with = "serialize_u32_as_string"
    )]
    pub page_size: Option<u32>,
}

/// HTTP client wrapper with common functionality
///
/// Handles HTTP requests to the Circle API with automatic header management,
/// authentication, and response parsing.
#[derive(Clone)]
pub struct HttpClient {
    client: Client,
    base_url: Url,
    api_key: Option<String>,
}

impl HttpClient {
    /// Create a new HTTP client with base URL
    pub fn new(base_url: &str) -> CircleResult<Self> {
        let client = Client::new();
        let base_url = Url::parse(base_url)?;

        Ok(Self {
            client,
            base_url,
            api_key: None,
        })
    }

    /// Create a new HTTP client with base URL and API key
    pub fn with_api_key(base_url: &str, api_key: String) -> CircleResult<Self> {
        let mut client = Self::new(base_url)?;
        client.api_key = Some(api_key);
        Ok(client)
    }

    /// Build a request with common headers
    pub fn request(&self, method: Method, path: &str) -> CircleResult<RequestBuilder> {
        let url = self.base_url.join(path)?;
        let mut request = self.client.request(method, url);

        // Add common headers
        request = request.header("Content-Type", "application/json");

        // Add authorization header if API key is available
        if let Some(ref api_key) = self.api_key {
            request = request.header("Authorization", format!("Bearer {}", api_key));
        }

        Ok(request)
    }

    /// Execute a request and handle the response
    pub async fn execute<T>(&self, request: RequestBuilder) -> CircleResult<T>
    where
        T: for<'de> Deserialize<'de>,
    {
        let response = request.send().await?;
        self.handle_response(response).await
    }

    /// Handle HTTP response and convert to typed result
    async fn handle_response<T>(&self, response: Response) -> CircleResult<T>
    where
        T: for<'de> Deserialize<'de>,
    {
        let status = response.status();
        let response_text = response.text().await?;

        if status.is_success() {
            let circle_response: CircleResponse<T> = serde_json::from_str(&response_text)?;
            Ok(circle_response.data)
        } else {
            // Try to parse error response
            let error_message = match serde_json::from_str::<CircleErrorResponse>(&response_text) {
                Ok(error_resp) => error_resp.message,
                Err(_) => response_text,
            };

            Err(CircleError::Api {
                status: status.as_u16(),
                message: error_message,
            })
        }
    }
}

/// Helper function to read environment variable
///
/// Reads an environment variable and returns its value, or an error if it's not set.
///
/// # Arguments
///
/// * `name` - The name of the environment variable to read
///
/// # Returns
///
/// Returns the environment variable value on success.
///
/// # Errors
///
/// Returns `CircleError::EnvVar` if the environment variable is not set.
///
/// # Example
///
/// ```rust,no_run
/// use inf_circle_sdk::helper::get_env_var;
///
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let api_key = get_env_var("CIRCLE_API_KEY")?;
/// println!("API Key: {}", api_key);
/// # Ok(())
/// # }
/// ```
pub fn get_env_var(name: &str) -> CircleResult<String> {
    std::env::var(name)
        .map_err(|_| CircleError::EnvVar(format!("Missing environment variable: {}", name)))
}

/// Helper function to build query string from parameters
///
/// Serializes a struct into a URL-encoded query string, filtering out empty values.
///
/// # Arguments
///
/// * `params` - A serializable struct containing query parameters
///
/// # Returns
///
/// Returns a URL-encoded query string (e.g., "key1=value1&key2=value2").
///
/// # Example
///
/// ```rust,no_run
/// use inf_circle_sdk::helper::build_query_params;
/// use serde::Serialize;
///
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// #[derive(Serialize)]
/// struct Params {
///     page_size: u32,
///     blockchain: String,
/// }
///
/// let params = Params {
///     page_size: 10,
///     blockchain: "ETH-SEPOLIA".to_string(),
/// };
///
/// let query = build_query_params(&params)?;
/// println!("Query string: {}", query); // "page_size=10&blockchain=ETH-SEPOLIA"
/// # Ok(())
/// # }
/// ```
pub fn build_query_params<T: Serialize>(params: &T) -> CircleResult<String> {
    let query_map: HashMap<String, String> = serde_json::from_value(serde_json::to_value(params)?)?;
    let query_pairs: Vec<String> = query_map
        .into_iter()
        .filter(|(_, v)| !v.is_empty())
        .map(|(k, v)| format!("{}={}", urlencoding::encode(&k), urlencoding::encode(&v)))
        .collect();

    Ok(query_pairs.join("&"))
}

/// Helper function to generate UUID v4
///
/// Generates a new UUID v4 (random UUID) and returns it as a string.
///
/// # Returns
///
/// Returns a UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
///
/// # Example
///
/// ```rust,no_run
/// use inf_circle_sdk::helper::generate_uuid;
///
/// # fn example() {
/// let idempotency_key = generate_uuid();
/// println!("Generated UUID: {}", idempotency_key);
/// // Example output: "550e8400-e29b-41d4-a716-446655440000"
/// # }
/// ```
pub fn generate_uuid() -> String {
    uuid::Uuid::new_v4().to_string()
}

/// Encrypts entity secret using RSA-OAEP with SHA-256
///
/// This function takes a hex-encoded entity secret and encrypts it using the provided
/// RSA public key in PEM format. The result is base64-encoded.
///
/// # Arguments
/// * `entity_secret_hex` - The entity secret as a hex string
/// * `public_key_pem` - The RSA public key in PEM format (PKCS#1 or PKCS#8)
///
/// # Returns
/// * `Result<String>` - Base64-encoded encrypted data on success
///
/// # Example
///
/// ```rust,no_run
/// use inf_circle_sdk::helper::encrypt_entity_secret;
///
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let entity_secret = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
/// let public_key = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----";
///
/// let encrypted = encrypt_entity_secret(entity_secret, public_key)?;
/// println!("Encrypted secret: {}", encrypted);
/// # Ok(())
/// # }
/// ```
pub fn encrypt_entity_secret(
    entity_secret_hex: &str,
    public_key_pem: &str,
) -> AnyhowResult<String> {
    // Convert hex string to bytes
    let entity_secret_bytes = hex::decode(entity_secret_hex)
        .map_err(|e| anyhow!("Failed to decode hex entity secret: {}", e))?;

    // Try PKCS#1 format first, then fall back to PKCS#8 format
    let public_key = match RsaPublicKey::from_pkcs1_pem(public_key_pem) {
        Ok(key) => key,
        Err(e1) => match RsaPublicKey::from_public_key_pem(public_key_pem) {
            Ok(key) => key,
            Err(e2) => {
                return Err(anyhow!(
                        "Failed to parse public key from PEM (tried both PKCS#1 and PKCS#8): PKCS#1 error: {}, PKCS#8 error: {}",
                        e1, e2
                    ));
            }
        },
    };

    // Encrypt using RSA-OAEP with SHA-256
    let mut rng = rand::thread_rng();
    let padding = Oaep::new::<Sha256>();
    let encrypted_data = public_key
        .encrypt(&mut rng, padding, &entity_secret_bytes)
        .map_err(|e| anyhow!("Failed to encrypt data: {}", e))?;

    // Encode to base64
    let base64_encoded = general_purpose::STANDARD.encode(&encrypted_data);

    Ok(base64_encoded)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_generate_uuid() {
        let uuid = generate_uuid();
        assert_eq!(uuid.len(), 36); // Standard UUID length
        assert!(uuid.contains('-'));
    }

    #[test]
    fn test_pagination_params_serialization() {
        let params = PaginationParams {
            page_size: Some(10),
            ..Default::default()
        };

        let serialized = serde_json::to_string(&params).unwrap();
        assert!(serialized.contains("pageSize"));
        assert!(!serialized.contains("pageAfter"));
    }

    #[test]
    fn test_encrypt_entity_secret_generates_different_values() {
        // Test that multiple encryptions of the same data produce different results
        // This is expected behavior due to RSA-OAEP padding with random values

        // Use a simple test key pair (in practice, this would come from environment)
        let entity_secret = "deadbeef"; // Simple hex string
        let test_public_key = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3VoPN9PKUjKFLMwOge9+\nG852nMEQAiMpm8FZ8VpJx5yXHdVXyMqTDwGJstidHy5htGKsyEArvIHxBzgWhMfL\nKLFZjvnxWx+rm/d5fk/5UjpjGFI7KABlxEBOAArBuLoi8TJb9BF3MjEqtlHOHUj6\nKG2n4sRRqeWpyFxTJU2v8fhJgHR1HhYkdHw8JdJ6J1lNNJGE7JfGtKDHI4mEo8ZN\nKF8TlW4wIJLQ4CJtEZJH2vKJJFNyFwJNJG2vKJJFNyFwJNJG2vKJJFNyFwJNJG2v\nKJJFNyFwJNJG2vKJJFNyFwJNJG2vKJJFNyFwJNJG2vKJJFNyFwJNJG2vKJJFNyFw\nQIDAQAB\n-----END PUBLIC KEY-----";

        // Note: This test would require a valid key pair to actually run
        // For now, we'll just test the function signature and error handling
        let result = encrypt_entity_secret(entity_secret, test_public_key);

        // We expect this to fail with an invalid key, but that's ok for testing the interface
        assert!(result.is_err());

        // The important thing is that the function exists and has the right signature
        // In real usage with valid keys, multiple calls would produce different encrypted values
    }
}