smskit – Universal Multi‑Provider SMS Toolkit for Rust 🚀

Status: v0.2.0 (beta) – Complete framework-agnostic SMS abstraction with support for every major Rust web framework.

🎯 Why smskit?

Give your users the freedom to bring their own SMS provider while you code to a single, unified interface. Switch between Plivo, Twilio, AWS SNS, or any provider without changing your application code.

🔥 NEW in v0.2.0: Universal web framework support! Works with Axum, Warp, Actix-web, Rocket, Tide, Hyper, or ANY framework you can imagine.

📦 Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   Your App      │    │   sms-core       │    │  SMS Providers      │
│                 │────│  (traits & types)│────│  • Plivo           │
│ • Business Logic│    │                  │    │  • Twilio (soon)   │
│ • Web Routes    │    └──────────────────┘    │  • AWS SNS (soon)  │
└─────────────────┘             │              └─────────────────────┘
         │                      │
         ▼                      ▼
┌─────────────────┐    ┌──────────────────┐
│ Web Framework   │    │ sms-web-generic  │
│ Adapters        │────│ (core logic)     │
│ • Axum          │    │                  │
│ • Warp          │    │ Framework-       │
│ • Actix-web     │    │ agnostic         │
│ • Rocket        │    │ processing       │
│ • Tide          │    │                  │
│ • Hyper         │    │                  │
│ • + ANY other   │    │                  │
└─────────────────┘    └──────────────────┘

🚀 Quick Start

Option 1: Use Your Favorite Framework

[dependencies]
sms-core = "0.2"
sms-plivo = "0.2"
sms-web-axum = "0.2"
axum = "0.7"
tokio = { version = "1.0", features = ["full"] }

use std::sync::Arc;
use axum::{routing::post, Router};
use sms_core::InboundRegistry;
use sms_plivo::PlivoClient;
use sms_web_axum::{unified_webhook, AppState};

#[tokio::main]
async fn main() {
    let plivo = PlivoClient::new("your_auth_id", "your_auth_token");
    let registry = InboundRegistry::new().with(Arc::new(plivo));
    let state = AppState { registry };

    let app = Router::new()
        .route("/webhooks/:provider", post(unified_webhook))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Option 2: Framework-Agnostic Integration 🔥

Works with ANY web framework - just adapt the request/response types:

use sms_web_generic::WebhookProcessor;

// This works with ANY web framework!
async fn handle_sms_webhook(provider: String, headers: Vec<(String, String)>, body: &[u8]) -> YourFrameworkResponse {
    let processor = WebhookProcessor::new(your_registry);
    let response = processor.process_webhook(&provider, headers, body);

    // Convert to your framework's response type
    response.into()
}

📋 Supported Frameworks

🔌 SMS Providers

💡 Usage Examples

Sending SMS

use sms_core::{SendRequest, SmsClient};
use sms_plivo::PlivoClient;

let client = PlivoClient::new("auth_id", "auth_token");
let response = client.send(SendRequest {
    to: "+1234567890",
    from: "+0987654321",
    text: "Hello from smskit!"
}).await?;

println!("Message sent with ID: {}", response.id);

Receiving SMS (Webhooks)

All frameworks receive the same normalized InboundMessage:

{
  "id": "abc-123",
  "from": "+1234567890",
  "to": "+0987654321",
  "text": "Hello World",
  "timestamp": "2024-12-30T12:34:56Z",
  "provider": "plivo",
  "raw": { /* original provider payload */ }
}

Webhook URLs:

• POST http://yourserver.com/webhooks/plivo
• POST http://yourserver.com/webhooks/twilio
• POST http://yourserver.com/webhooks/{any_provider}

🏃‍♂️ Running Examples

# Test the generic integration (works everywhere!)
cargo run --example generic_integration

# Try with specific frameworks
cargo run --example warp_server --features warp
cargo run --example actix_server --features actix-web
cargo run --example hyper_server --features hyper

# Original Axum example
cargo run --example unified_webhook