pincho 1.0.0-alpha.1

Official Rust Client Library for Pincho - Send push notifications with async/await support
Documentation

Pincho Rust Client Library

crates.io License: MIT

Official Rust client for Pincho push notifications.

Installation

[dependencies]
pincho = ">=1.0.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use pincho::Client;

#[tokio::main]
async fn main() -> Result<(), pincho::Error> {
    // Auto-load token from PINCHO_TOKEN env var
    let client = Client::from_env()?;
    client.send("Deploy Complete", "Version 1.2.3 deployed").await?;

    // Or provide token explicitly
    let client = Client::new("YOUR_TOKEN")?;
    client.send("Alert", "Server CPU at 95%").await?;
    Ok(())
}

Features

use pincho::{Client, Notification};

#[tokio::main]
async fn main() -> Result<(), pincho::Error> {
    let client = Client::from_env()?;

    // Full parameters
    let notification = Notification::builder()
        .title("Deploy Complete")
        .message("Version 1.2.3 deployed")
        .notification_type("deployment")
        .tags(vec!["production".to_string(), "backend".to_string()])
        .image_url("https://example.com/success.png")
        .action_url("https://example.com/deploy/123")
        .build()?;

    client.send_notification(notification).await?;

    // AI-powered notifications (NotifAI)
    let response = client.notifai("deployment finished, v2.1.3 is live", None).await?;
    println!("Title: {}", response.notification.title);   // AI-generated
    println!("Message: {}", response.notification.message);

    // Encrypted messages
    let notification = Notification::builder()
        .title("Security Alert")
        .message("Sensitive data")
        .notification_type("security")
        .encryption_password("your_password")
        .build()?;
    client.send_notification(notification).await?;

    Ok(())
}

Configuration

// Environment variables (recommended)
// PINCHO_TOKEN - API token (required if not passed to constructor)
// PINCHO_TIMEOUT - Request timeout in seconds (default: 30)
// PINCHO_MAX_RETRIES - Retry attempts (default: 3)

// Or explicit configuration
let client = Client::with_config("YOUR_TOKEN", 60, 5)?;

Error Handling

use pincho::{Client, Error};

#[tokio::main]
async fn main() {
    let client = Client::from_env().unwrap();

    match client.send("Title", "Message").await {
        Ok(response) => println!("Success: {}", response.message),
        Err(Error::Authentication { message, .. }) => {
            eprintln!("Invalid token: {}", message);
        }
        Err(Error::Validation { message, .. }) => {
            eprintln!("Invalid parameters: {}", message);
        }
        Err(Error::RateLimit { message, .. }) => {
            eprintln!("Rate limited: {}", message);
        }
        Err(e) => {
            if e.is_retryable() {
                eprintln!("Retryable error: {}", e);
            }
        }
    }
}

Automatic retry with exponential backoff for network errors, 5xx, and 429 (rate limit).

Smart Rate Limiting

let client = Client::from_env()?;
client.send("Alert", "Message").await?;

// Check rate limit status after any request
if let Some(rate_limit) = client.get_last_rate_limit() {
    println!("Remaining: {}/{}", rate_limit.remaining, rate_limit.limit);
    println!("Resets at: {}", rate_limit.reset);
}

Links

License

MIT