telecom-platform/sdk/rust/README.md

Telecom Platform Rust SDK

Async Rust SDK for the Telecom Platform with full type safety and modern async/await support.

Features

• Modular Architecture: Separate modules for authentication, HTTP client, and API services
• Async/Await Support: Full async/await support with tokio
• Type Safety: Strong typing with Rust structs and enums
• Error Handling: Comprehensive error handling with custom error types
• Retry Logic: Built-in retry mechanism with exponential backoff
• Context Support: Full context.Context support for cancellation

Installation

Add to your Cargo.toml:

[dependencies]
telecom-sdk = { path = "../sdk/rust" }

Or install from source:

cd sdk/rust
cargo build

Architecture

The SDK is organized into modular components:

• auth.rs - Authentication provider handling API keys and JWT tokens
• client.rs - HTTP client with retry logic and authentication
• error.rs - Error types for the SDK
• types.rs - Data structures and type definitions
• api/ - Directory containing API modules:
  • subscribers.rs - Subscriber management API
  • usage.rs - Usage tracking API
  • payments.rs - Payment processing API
  • rating_plans.rs - Rating plan management API
  • system.rs - System monitoring API
  • graphql.rs - GraphQL query execution
  • mod.rs - Module exports

Quick Start

use telecom_sdk::{TelecomClient, Config};
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config {
        api_url: "http://localhost:8000".to_string(),
        api_key: Some("your-api-key".to_string()),
        ..Default::default()
    };

    let client = TelecomClient::new(config).await?;
    
    // Get subscriber
    let subscriber = client.subscribers.get(1).await?;
    println!("Subscriber: {} {}", subscriber.first_name, subscriber.last_name);
    
    // List subscribers
    let list = client.subscribers.list(1, 50, None).await?;
    println!("Total subscribers: {}", list.total);
    
    Ok(())
}

API Reference

Configuration

let config = Config {
    api_url: "http://localhost:8000".to_string(),
    api_key: Some("your-api-key".to_string()),
    jwt_secret: Some("your-jwt-secret".to_string()),
    timeout: Some(Duration::from_secs(30)),
    max_retries: Some(3),
    retry_delay: Some(Duration::from_secs(1)),
};

Subscriber Management

// Get subscriber
let subscriber = client.subscribers.get(1).await?;

// List subscribers
let list = client.subscribers.list(1, 50, Some("active".to_string())).await?;

// Create subscriber
let request = CreateSubscriberRequest {
    imsi: "208930000000001".to_string(),
    msisdn: "+1234567890".to_string(),
    first_name: "John".to_string(),
    last_name: "Doe".to_string(),
    email: "[email protected]".to_string(),
    plan_id: 1,
};
let subscriber = client.subscribers.create(request).await?;

// Update subscriber
let update = UpdateSubscriberRequest {
    first_name: Some("Jane".to_string()),
    ..Default::default()
};
let subscriber = client.subscribers.update(1, update).await?;

// Delete subscriber
client.subscribers.delete(1).await?;

// Suspend subscriber
client.subscribers.suspend(1).await?;

// Activate subscriber
client.subscribers.activate(1).await?;

Usage Management

use std::time::{Duration, SystemTime};

// Get usage stats
let start_date = SystemTime::now() - Duration::from_secs(30 * 24 * 60 * 60);
let end_date = SystemTime::now();
let stats = client.usage.get_stats(1, start_date, end_date).await?;

// List usage events
let events = client.usage.list_events(1, Some("data".to_string()), 1, 50).await?;

// Get real-time usage
let realtime = client.usage.get_real_time(1).await?;

Payment Management

// Create payment transaction
let transaction = client.payments.create_transaction(CreatePaymentTransactionRequest {
    subscriber_id: "1".to_string(),
    amount: 25.00,
    currency: "USD".to_string(),
    gateway: "stripe".to_string(),
    metadata: None,
}).await?;

// Get transaction
let transaction = client.payments.get_transaction("txn-123".to_string()).await?;

// List transactions
let transactions = client.payments.list_transactions(1, Some("completed".to_string()), 1, 50).await?;

Rating Plans

// List rating plans
let plans = client.rating_plans.list().await?;

// Get specific plan
let plan = client.rating_plans.get("plan-123".to_string()).await?;

System Management

// Get system stats
let stats = client.system.get_stats().await?;

// Get health status
let health = client.system.get_health().await?;

GraphQL

// Execute GraphQL query
let query = r#"
    query GetSubscribers($first: Int) {
        subscribers(first: $first) {
            id
            firstName
            lastName
        }
    }
"#;

let variables = serde_json::json!({"first": 10});
let result = client.graphql.execute(query, Some(variables)).await?;

Error Handling

use telecom_sdk::TelecomError;

match client.subscribers.get(1).await {
    Ok(subscriber) => println!("Subscriber: {}", subscriber.first_name),
    Err(TelecomError::AuthenticationError) => println!("Authentication failed"),
    Err(TelecomError::APIError(msg)) => println!("API error: {}", msg),
    Err(TelecomError::NetworkError(msg)) => println!("Network error: {}", msg),
    Err(e) => println!("Error: {}", e),
}

Development

Running Tests

cargo test

Building

cargo build --release

Code Style

cargo fmt
cargo clippy

License

This SDK is licensed under the MIT License.