toptl 0.1.0

Official Rust SDK for the TOP.TL Telegram directory API — post stats, check votes, manage vote webhooks.
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
139

# toptl

[![Crates.io](https://img.shields.io/crates/v/toptl.svg?color=3775a9)](https://crates.io/crates/toptl)
[![docs.rs](https://img.shields.io/docsrs/toptl/latest?color=3776ab)](https://docs.rs/toptl)
[![Downloads](https://img.shields.io/crates/d/toptl.svg?color=blue)](https://crates.io/crates/toptl)
[![License](https://img.shields.io/crates/l/toptl.svg?color=green)](https://github.com/top-tl/rust/blob/main/LICENSE)
[![TOP.TL](https://img.shields.io/badge/top.tl-developers-2ec4b6)](https://top.tl/developers)

The official Rust SDK for **[TOP.TL](https://top.tl)** — post bot stats, check votes, and manage vote webhooks from your Telegram bot.

## Install

```toml
[dependencies]
toptl = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

Requires Rust 1.70+.

## Quick start

Get an API key at <https://top.tl/profile> → **API Keys**.

```rust
use toptl::{StatsPayload, TopTL};

#[tokio::main]
async fn main() -> Result<(), toptl::Error> {
    let client = TopTL::new("toptl_xxx");

    // Look up a listing.
    let listing = client.get_listing("durov").await?;
    println!("{} — {} votes", listing.title, listing.vote_count);

    // Post stats for a bot you own.
    client
        .post_stats(
            "mybot",
            &StatsPayload {
                member_count: Some(5_000),
                group_count: Some(1_200),
                channel_count: Some(300),
                bot_serves: None,
            },
        )
        .await?;

    // Reward users who voted.
    if client.has_voted("mybot", 123_456_789u64).await?.voted {
        // grant premium …
    }

    Ok(())
}
```

## Autoposter

Long-running bot? Register an autoposter that flushes stats on an interval:

```rust
use std::sync::Arc;
use std::time::Duration;
use toptl::{autoposter::Autoposter, StatsPayload, TopTL};

let client = TopTL::new("toptl_xxx");
let autoposter = Autoposter::new(client, "mybot")
    .interval(Duration::from_secs(30 * 60))
    .callback(Arc::new(|| StatsPayload {
        member_count: Some(current_user_count()),
        ..StatsPayload::default()
    }))
    .start();

// autoposter.stop().await; on shutdown
```

## Webhooks

```rust
use toptl::WebhookConfig;

client
    .set_webhook(
        "mybot",
        &WebhookConfig {
            url: "https://mybot.example.com/toptl-vote".into(),
            reward_title: Some("30-day premium".into()),
        },
    )
    .await?;

let result = client.test_webhook("mybot").await?;
assert!(result.success);
```

## Batch stats

Up to 25 listings per request:

```rust
use toptl::BatchStatsItem;

client
    .batch_post_stats(&[
        BatchStatsItem {
            username: "bot1".into(),
            member_count: Some(1_200),
            ..Default::default()
        },
        BatchStatsItem {
            username: "bot2".into(),
            member_count: Some(5_400),
            ..Default::default()
        },
    ])
    .await?;
```

## Error handling

All methods return `Result<T, toptl::Error>`:

```rust
use toptl::Error;

match client.post_stats("mybot", &stats).await {
    Ok(_) => {}
    Err(Error::Api { status: 401, .. }) => { /* bad key */ }
    Err(Error::Api { status: 404, .. }) => { /* no such listing */ }
    Err(Error::Api { status: 429, .. }) => { /* back off */ }
    Err(e) => eprintln!("transport: {e}"),
}
```

## License

MIT — see [`LICENSE`](LICENSE).