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
140

use serde::{Deserialize, Serialize};

/// A TOP.TL listing (channel, group, or bot). Field names mirror the
/// JSON the API returns; anything unknown is tolerated via `#[serde(default)]`
/// so the crate keeps compiling when the server adds new keys.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Listing {
    pub id: String,
    pub username: String,
    #[serde(default)]
    pub title: String,
    #[serde(default)]
    pub description: Option<String>,
    /// `"CHANNEL" | "GROUP" | "BOT"`.
    pub r#type: String,
    #[serde(default)]
    pub member_count: u64,
    #[serde(default)]
    pub vote_count: u64,
    #[serde(default)]
    pub languages: Vec<String>,
    #[serde(default)]
    pub verified: bool,
    #[serde(default)]
    pub featured: bool,
    #[serde(default)]
    pub photo_url: Option<String>,
    /// Additional tags associated with the listing.
    #[serde(default)]
    pub tags: Vec<String>,
}

/// One voter record returned by `get_votes`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Voter {
    #[serde(default)]
    pub user_id: Option<String>,
    #[serde(default)]
    pub first_name: Option<String>,
    #[serde(default)]
    pub username: Option<String>,
    #[serde(default, alias = "createdAt")]
    pub voted_at: Option<String>,
}

/// Response for `has_voted`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct VoteCheck {
    #[serde(default, alias = "hasVoted")]
    pub voted: bool,
    #[serde(default)]
    pub voted_at: Option<String>,
}

/// Payload for `post_stats`. All fields are optional — the server only
/// updates the ones you send, so you can push a member-count-only
/// update without zeroing out group/channel counts.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StatsPayload {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub member_count: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub group_count: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub channel_count: Option<u64>,
    /// For bots that operate inside specific groups/channels, a list of
    /// their usernames.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub bot_serves: Option<Vec<String>>,
}

/// Response for `post_stats` / `batch_post_stats` items.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StatsResult {
    #[serde(default = "default_true")]
    pub success: bool,
    #[serde(default)]
    pub username: Option<String>,
    #[serde(default)]
    pub error: Option<String>,
}

fn default_true() -> bool {
    true
}

/// One entry in a `batch_post_stats` request.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct BatchStatsItem {
    pub username: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub member_count: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub group_count: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub channel_count: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub bot_serves: Option<Vec<String>>,
}

/// Body for `set_webhook`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct WebhookConfig {
    pub url: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reward_title: Option<String>,
}

/// Response from `test_webhook`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct WebhookTestResult {
    #[serde(default)]
    pub success: bool,
    #[serde(default, alias = "status")]
    pub status_code: Option<u16>,
    #[serde(default, alias = "error")]
    pub message: Option<String>,
}

/// Site-wide totals from `get_global_stats`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GlobalStats {
    #[serde(default)]
    pub total: u64,
    #[serde(default)]
    pub channels: u64,
    #[serde(default)]
    pub groups: u64,
    #[serde(default)]
    pub bots: u64,
}