tgbot/types/chat/boost/
mod.rs

1use serde::{Deserialize, Deserializer, Serialize, Serializer};
2
3use crate::{
4    api::{Method, Payload},
5    types::{Chat, ChatId, Integer, User},
6};
7
8#[cfg(test)]
9mod tests;
10
11/// Contains information about a chat boost.
12#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
13pub struct ChatBoost {
14    /// Point in time (Unix timestamp) when the chat was boosted.
15    pub add_date: Integer,
16    /// Unique identifier of the boost.
17    pub boost_id: String,
18    /// Point in time (Unix timestamp) when the boost will automatically expire,
19    /// unless the booster's Telegram Premium subscription is prolonged.
20    pub expiration_date: Integer,
21    /// Source of the added boost.
22    pub source: ChatBoostSource,
23}
24
25impl ChatBoost {
26    /// Creates a new `ChatBoost`.
27    ///
28    /// # Arguments
29    ///
30    /// * `add_date` - Point in time (Unix timestamp) when the chat was boosted.
31    /// * `boost_id` - Unique identifier of the boost.
32    /// * `expiration_date` - Point in time (Unix timestamp) when the boost will automatically expire,
33    ///   unless the booster's Telegram Premium subscription is prolonged.
34    /// * `source` - Source of the added boost.
35    pub fn new<T>(add_date: Integer, boost_id: T, expiration_date: Integer, source: ChatBoostSource) -> Self
36    where
37        T: Into<String>,
38    {
39        Self {
40            add_date,
41            boost_id: boost_id.into(),
42            expiration_date,
43            source,
44        }
45    }
46}
47
48/// Represents a boost removed from a chat.
49#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
50pub struct ChatBoostRemoved {
51    /// Unique identifier of the boost.
52    pub boost_id: String,
53    /// Chat which was boosted.
54    pub chat: Chat,
55    /// Point in time (Unix timestamp) when the boost was removed.
56    pub remove_date: Integer,
57    /// Source of the removed boost.
58    pub source: ChatBoostSource,
59}
60
61impl ChatBoostRemoved {
62    /// Creates a new `ChatBoostRemoved`.
63    ///
64    /// # Arguments
65    ///
66    /// * `boost_id` - Unique identifier of the boost.
67    /// * `chat` - Chat which was boosted.
68    /// * `remove_date` - Point in time (Unix timestamp) when the boost was removed.
69    /// * `source` - Source of the removed boost.
70    pub fn new<A, B>(boost_id: A, chat: B, remove_date: Integer, source: ChatBoostSource) -> Self
71    where
72        A: Into<String>,
73        B: Into<Chat>,
74    {
75        Self {
76            boost_id: boost_id.into(),
77            chat: chat.into(),
78            remove_date,
79            source,
80        }
81    }
82}
83
84/// Describes the source of a chat boost.
85#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
86#[serde(rename_all = "snake_case", tag = "source")]
87pub enum ChatBoostSource {
88    /// The boost was obtained by the creation of Telegram Premium gift codes to boost a chat.
89    ///
90    /// Each such code boosts the chat 4 times for the duration of the corresponding Telegram Premium subscription.
91    /// Contains a user for which the gift code was created.
92    #[serde(
93        deserialize_with = "ChatBoostSourceUser::deserialize_value",
94        serialize_with = "ChatBoostSourceUser::serialize_value"
95    )]
96    GiftCode(User),
97    /// The boost was obtained by the creation of a Telegram Premium giveaway.
98    Giveaway(ChatBoostSourceGiveaway),
99    /// The boost was obtained by subscribing to Telegram Premium
100    /// or by gifting a Telegram Premium subscription to another user.
101    ///
102    /// Contains a user that boosted the chat
103    #[serde(
104        deserialize_with = "ChatBoostSourceUser::deserialize_value",
105        serialize_with = "ChatBoostSourceUser::serialize_value"
106    )]
107    Premium(User),
108}
109
110#[derive(Deserialize, Serialize)]
111struct ChatBoostSourceUser {
112    user: User,
113}
114
115impl ChatBoostSourceUser {
116    pub(super) fn deserialize_value<'de, D>(deserializer: D) -> Result<User, D::Error>
117    where
118        D: Deserializer<'de>,
119    {
120        Self::deserialize(deserializer).map(|x| x.user)
121    }
122
123    pub(super) fn serialize_value<S>(value: &User, serializer: S) -> Result<S::Ok, S::Error>
124    where
125        S: Serializer,
126    {
127        Self { user: value.clone() }.serialize(serializer)
128    }
129}
130
131/// The boost was obtained by the creation of a Telegram Premium giveaway.
132///
133/// This boosts the chat 4 times for the duration of the corresponding Telegram Premium subscription.
134#[serde_with::skip_serializing_none]
135#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
136pub struct ChatBoostSourceGiveaway {
137    /// Identifier of a message in the chat with the giveaway;
138    /// the message could have been deleted already.
139    /// May be 0 if the message isn't sent yet.
140    pub giveaway_message_id: Integer,
141    /// Whether the giveaway was completed, but there was no user to win the prize.
142    pub is_unclaimed: Option<bool>,
143    /// The number of Telegram Stars to be split between giveaway winners;
144    /// for Telegram Star giveaways only.
145    pub prize_star_count: Option<Integer>,
146    /// User that won the prize in the giveaway if any.
147    pub user: Option<User>,
148}
149
150impl ChatBoostSourceGiveaway {
151    /// Creates a new `ChatBoostSourceGiveaway`.
152    ///
153    /// # Arguments
154    ///
155    /// * `giveaway_message_id` - Identifier of a message in the chat with the giveaway.
156    pub fn new(giveaway_message_id: Integer) -> Self {
157        Self {
158            giveaway_message_id,
159            is_unclaimed: None,
160            prize_star_count: None,
161            user: None,
162        }
163    }
164
165    /// Sets a new value for the `is_unclaimed` flag.
166    ///
167    /// # Arguments
168    ///
169    /// * `value` - Whether the giveaway was completed, but there was no user to win the prize.
170    pub fn with_is_unclaimed(mut self, value: bool) -> Self {
171        self.is_unclaimed = Some(value);
172        self
173    }
174
175    /// Sets a new prize star count.
176    ///
177    /// # Arguments
178    ///
179    /// * `value` - The number of Telegram Stars to be split between giveaway winners;
180    ///   for Telegram Star giveaways only.
181    pub fn with_prize_star_count(mut self, value: Integer) -> Self {
182        self.prize_star_count = Some(value);
183        self
184    }
185
186    /// Sets a new user
187    ///
188    /// # Arguments
189    ///
190    /// * `value` - User that won the prize in the giveaway.
191    pub fn with_user(mut self, value: User) -> Self {
192        self.user = Some(value);
193        self
194    }
195}
196
197/// Represents a boost added to a chat or changed.
198#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
199pub struct ChatBoostUpdated {
200    /// Infomation about the chat boost.
201    pub boost: ChatBoost,
202    /// Chat which was boosted.
203    pub chat: Chat,
204}
205
206impl ChatBoostUpdated {
207    /// Creates a new `ChatBoostUpdated`.
208    ///
209    /// # Arguments
210    ///
211    /// * `boost` - Infomation about the chat boost.
212    /// * `chat` - Chat which was boosted.
213    pub fn new<T>(boost: ChatBoost, chat: T) -> Self
214    where
215        T: Into<Chat>,
216    {
217        Self {
218            boost,
219            chat: chat.into(),
220        }
221    }
222}
223
224/// Represents a list of boosts added to a chat by a user.
225#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
226pub struct UserChatBoosts {
227    /// The list of boosts added to the chat by the user.
228    pub boosts: Vec<ChatBoost>,
229}
230
231impl<T> From<T> for UserChatBoosts
232where
233    T: IntoIterator<Item = ChatBoost>,
234{
235    fn from(value: T) -> Self {
236        Self {
237            boosts: value.into_iter().collect(),
238        }
239    }
240}
241
242/// Returns the list of boosts added to a chat by a user.
243///
244/// Requires administrator rights in the chat.
245#[derive(Clone, Debug, Serialize)]
246pub struct GetUserChatBoosts {
247    chat_id: ChatId,
248    user_id: Integer,
249}
250
251impl GetUserChatBoosts {
252    /// Creates a new `GetUserChatBoosts`.
253    ///
254    /// # Arguments
255    ///
256    /// * `chat_id` - Unique identifier for the chat.
257    /// * `user_id` - Unique identifier of the target user.
258    pub fn new<T>(chat_id: T, user_id: Integer) -> Self
259    where
260        T: Into<ChatId>,
261    {
262        Self {
263            chat_id: chat_id.into(),
264            user_id,
265        }
266    }
267}
268
269impl Method for GetUserChatBoosts {
270    type Response = UserChatBoosts;
271
272    fn into_payload(self) -> Payload {
273        Payload::json("getUserChatBoosts", self)
274    }
275}
tgbot/types/chat/boost/mod.rs

tgbot/types/chat/boost/
mod.rs
