pincho 1.0.0-alpha.1

Official Rust Client Library for Pincho - Send push notifications with async/await support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

# Pincho Rust Client Library

[![crates.io](https://img.shields.io/crates/v/pincho.svg)](https://crates.io/crates/pincho)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Rust client for [Pincho](https://pincho.app) push notifications.

## Installation

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

## Quick Start

```rust
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

```rust
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

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

```rust
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

```rust
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

- **Get Token**: App → Settings → Help → copy token
- **Documentation**: https://pincho.app/help
- **Repository**: https://gitlab.com/pincho/pincho-rust
- **Crates.io**: https://crates.io/crates/pincho

## License

MIT