tgbot/types/giveaway/
mod.rs

1use serde::{Deserialize, Serialize};
2
3use crate::types::{Chat, Integer, Message, User};
4
5#[cfg(test)]
6mod tests;
7
8/// Represents a message about a scheduled giveaway.
9#[serde_with::skip_serializing_none]
10#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
11pub struct Giveaway {
12    /// The list of chats which the user must join to participate in the giveaway.
13    pub chats: Vec<Chat>,
14    /// Point in time (Unix timestamp) when winners of the giveaway will be selected.
15    pub winners_selection_date: Integer,
16    /// The number of users which are supposed to be selected as winners of the giveaway.
17    pub winner_count: Integer,
18    /// A list of two-letter ISO 3166-1 alpha-2 country codes indicating the countries
19    /// from which eligible users for the giveaway must come.
20    ///
21    /// If empty, then all users can participate in the giveaway.
22    /// Users with a phone number that was bought on Fragment can always participate in giveaways.
23    pub country_codes: Option<Vec<String>>,
24    /// Whether the list of giveaway winners will be visible to everyone.
25    pub has_public_winners: Option<bool>,
26    /// Whether only users who join the chats after the giveaway started should be eligible to win.
27    pub only_new_members: Option<bool>,
28    /// The number of months the Telegram Premium subscription won from the giveaway will be active for.
29    pub premium_subscription_month_count: Option<Integer>,
30    /// Description of additional giveaway prize.
31    pub prize_description: Option<String>,
32    /// The number of Telegram Stars to be split between giveaway winners;
33    /// for Telegram Star giveaways only.
34    pub prize_star_count: Option<Integer>,
35}
36
37impl Giveaway {
38    /// Creates a new `Giveaway`.
39    ///
40    /// # Arguments
41    ///
42    /// * `chats` - The list of chats which the user must join to participate in the giveaway.
43    /// * `winners_selection_date` - Point in time (Unix timestamp) when winners of the giveaway will be selected.
44    /// * `winner_count` - The number of users which are supposed to be selected as winners of the giveaway.
45    pub fn new<A, B>(chats: A, winners_selection_date: Integer, winner_count: Integer) -> Self
46    where
47        A: IntoIterator<Item = B>,
48        B: Into<Chat>,
49    {
50        Self {
51            chats: chats.into_iter().map(Into::into).collect(),
52            winners_selection_date,
53            winner_count,
54            country_codes: None,
55            has_public_winners: None,
56            only_new_members: None,
57            premium_subscription_month_count: None,
58            prize_description: None,
59            prize_star_count: None,
60        }
61    }
62
63    /// Sets a new list of country codes.
64    ///
65    /// # Arguments
66    ///
67    /// * `value` - A list of two-letter ISO 3166-1 alpha-2 country codes.
68    pub fn with_country_codes<A, B>(mut self, value: A) -> Self
69    where
70        A: IntoIterator<Item = B>,
71        B: Into<String>,
72    {
73        self.country_codes = Some(value.into_iter().map(Into::into).collect());
74        self
75    }
76
77    /// Sets a new value for the `has_public_winners` flag.
78    ///
79    /// # Arguments
80    ///
81    /// * `value` - Whether the list of giveaway winners will be visible to everyone.
82    pub fn with_has_public_winners(mut self, value: bool) -> Self {
83        self.has_public_winners = Some(value);
84        self
85    }
86
87    /// Sets a new value for the `only_new_members` flag.
88    ///
89    /// # Arguments
90    ///
91    /// * `value` - Whether only users who join the chats after the giveaway started should be eligible to win.
92    pub fn with_only_new_members(mut self, value: bool) -> Self {
93        self.only_new_members = Some(value);
94        self
95    }
96
97    /// Sets a new number of premium subscription months.
98    ///
99    /// # Arguments
100    ///
101    /// * `value` - The number of months the Telegram Premium subscription won from the giveaway will be active for.
102    pub fn with_premium_subscription_month_count(mut self, value: Integer) -> Self {
103        self.premium_subscription_month_count = Some(value);
104        self
105    }
106
107    /// Sets a new description of additional prizes.
108    ///
109    /// # Arguments
110    ///
111    /// * `value` - Description of additional giveaway prize.
112    pub fn with_prize_description<T>(mut self, value: T) -> Self
113    where
114        T: Into<String>,
115    {
116        self.prize_description = Some(value.into());
117        self
118    }
119
120    /// Sets a new prize star count.
121    ///
122    /// # Arguments
123    ///
124    /// * `value` - The number of Telegram Stars to be split between giveaway winners;
125    ///   for Telegram Star giveaways only.
126    pub fn with_prize_star_count(mut self, value: Integer) -> Self {
127        self.prize_star_count = Some(value);
128        self
129    }
130}
131
132/// Represents a service message about the creation of a scheduled giveaway.
133#[serde_with::skip_serializing_none]
134#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
135pub struct GiveawayCreated {
136    /// The number of Telegram Stars to be split between giveaway winners;
137    /// for Telegram Star giveaways only.
138    pub prize_star_count: Option<Integer>,
139}
140
141impl GiveawayCreated {
142    /// Sets a new prize star count.
143    ///
144    /// # Arguments
145    ///
146    /// * `value` - The number of Telegram Stars to be split between giveaway winners;
147    ///   for Telegram Star giveaways only.
148    pub fn with_prize_star_count(mut self, value: Integer) -> Self {
149        self.prize_star_count = Some(value);
150        self
151    }
152}
153
154/// Represents a service message about the completion of a giveaway without public winners.
155#[serde_with::skip_serializing_none]
156#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
157pub struct GiveawayCompleted {
158    /// Number of winners in the giveaway.
159    pub winner_count: Integer,
160    /// Message with the giveaway that was completed, if it wasn't deleted.
161    pub giveaway_message: Option<Box<Message>>,
162    /// Whether the giveaway is a Telegram Star giveaway.
163    ///
164    /// Otherwise, currently, the giveaway is a Telegram Premium giveaway.
165    pub is_star_giveaway: Option<bool>,
166    /// Number of undistributed prizes.
167    pub unclaimed_prize_count: Option<Integer>,
168}
169
170impl GiveawayCompleted {
171    /// Creates a new `GiveawayCompleted`.
172    ///
173    /// # Arguments
174    ///
175    /// * `winner_count` - Number of winners in the giveaway.
176    pub fn new(winner_count: Integer) -> Self {
177        Self {
178            winner_count,
179            giveaway_message: None,
180            is_star_giveaway: None,
181            unclaimed_prize_count: None,
182        }
183    }
184
185    /// Sets a new giveaway message.
186    ///
187    /// # Arguments
188    ///
189    /// * `value` - Message with the giveaway that was completed.
190    pub fn with_giveaway_message(mut self, value: Message) -> Self {
191        self.giveaway_message = Some(Box::new(value));
192        self
193    }
194
195    /// Sets a new value for the `is_star_giveaway` flag.
196    ///
197    /// # Arguments
198    ///
199    /// * `value` - Whether the giveaway is a Telegram Star giveaway.
200    ///   Otherwise, currently, the giveaway is a Telegram Premium giveaway.
201    pub fn with_is_star_giveaway(mut self, value: bool) -> Self {
202        self.is_star_giveaway = Some(value);
203        self
204    }
205
206    /// Sets a new unclaimed prize count.
207    ///
208    /// # Arguments
209    ///
210    /// * `value` - Number of undistributed prizes.
211    pub fn with_unclaimed_prize_count(mut self, value: Integer) -> Self {
212        self.unclaimed_prize_count = Some(value);
213        self
214    }
215}
216
217/// Represents a message about the completion of a giveaway with public winners.
218#[serde_with::skip_serializing_none]
219#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
220pub struct GiveawayWinners {
221    /// The chat that created the giveaway.
222    pub chat: Chat,
223    /// Identifier of the messsage with the giveaway in the chat.
224    pub giveaway_message_id: Integer,
225    /// Total number of winners in the giveaway.
226    pub winner_count: Integer,
227    /// List of up to 100 winners of the giveaway.
228    pub winners: Vec<User>,
229    /// Point in time (Unix timestamp) when winners of the giveaway were selected.
230    pub winners_selection_date: Integer,
231    /// The number of other chats the user had to join in order to be eligible for the giveaway.
232    pub additional_chat_count: Option<Integer>,
233    /// Whether only users who had joined the chats after the giveaway started were eligible to win.
234    pub only_new_members: Option<bool>,
235    /// The number of months the Telegram Premium subscription won from the giveaway will be active for.
236    pub premium_subscription_month_count: Option<Integer>,
237    /// Description of additional giveaway prize.
238    pub prize_description: Option<String>,
239    /// The number of Telegram Stars that were split between giveaway winners;
240    /// for Telegram Star giveaways only.
241    pub prize_star_count: Option<Integer>,
242    /// Number of undistributed prizes.
243    pub unclaimed_prize_count: Option<Integer>,
244    /// Whether the giveaway was canceled because the payment for it was refunded.
245    pub was_refunded: Option<bool>,
246}
247
248impl GiveawayWinners {
249    /// Creates a new `GiveawayWinners`.
250    ///
251    ///
252    /// # Arguments
253    ///
254    /// * `chat` - The chat that created the giveaway.
255    /// * `giveaway_message_id` - Identifier of the messsage with the giveaway in the chat.
256    /// * `winner_count` - Total number of winners in the giveaway.
257    /// * `winners` - List of up to 100 winners of the giveaway.
258    /// * `winners_selection_date` - Point in time (Unix timestamp) when winners of the giveaway were selected.
259    pub fn new<A, B>(
260        chat: A,
261        giveaway_message_id: Integer,
262        winner_count: Integer,
263        winners: B,
264        winners_selection_date: Integer,
265    ) -> Self
266    where
267        A: Into<Chat>,
268        B: IntoIterator<Item = User>,
269    {
270        Self {
271            chat: chat.into(),
272            giveaway_message_id,
273            winner_count,
274            winners: winners.into_iter().collect(),
275            winners_selection_date,
276            additional_chat_count: None,
277            only_new_members: None,
278            premium_subscription_month_count: None,
279            prize_description: None,
280            prize_star_count: None,
281            unclaimed_prize_count: None,
282            was_refunded: None,
283        }
284    }
285
286    /// Sets a new number of additional chats.
287    ///
288    /// # Arguments
289    ///
290    /// * `value` - The number of other chats the user had to join in order to be eligible for the giveaway.
291    pub fn with_additional_chat_count(mut self, value: Integer) -> Self {
292        self.additional_chat_count = Some(value);
293        self
294    }
295
296    /// Sets a new value for the `only_new_members` flag.
297    ///
298    /// # Arguments
299    ///
300    /// * `value` - Whether only users who had joined the chats after the giveaway started were eligible to win.
301    pub fn with_only_new_members(mut self, value: bool) -> Self {
302        self.only_new_members = Some(value);
303        self
304    }
305
306    /// Sets a new number of premium subscription months.
307    ///
308    /// # Arguments
309    ///
310    /// * `value` - The number of months the Telegram Premium subscription won from the giveaway will be active for.
311    pub fn with_premium_subscription_month_count(mut self, value: Integer) -> Self {
312        self.premium_subscription_month_count = Some(value);
313        self
314    }
315
316    /// Sets a new prize description.
317    ///
318    /// # Arguments
319    ///
320    /// * `value` - Description of additional giveaway prize.
321    pub fn with_prize_description<T>(mut self, value: T) -> Self
322    where
323        T: Into<String>,
324    {
325        self.prize_description = Some(value.into());
326        self
327    }
328
329    /// Sets a new prize star count.
330    ///
331    /// # Arguments
332    ///
333    /// * `value` - The number of Telegram Stars to be split between giveaway winners;
334    ///   for Telegram Star giveaways only.
335    pub fn with_prize_star_count(mut self, value: Integer) -> Self {
336        self.prize_star_count = Some(value);
337        self
338    }
339
340    /// Sets a new number of unclaimed prizes.
341    ///
342    /// # Arguments
343    ///
344    /// * `value` - Number of undistributed prizes.
345    pub fn with_unclaimed_prize_count(mut self, value: Integer) -> Self {
346        self.unclaimed_prize_count = Some(value);
347        self
348    }
349
350    /// Sets a new value for the `was_refunded` flag.
351    ///
352    /// # Arguments
353    ///
354    /// * `value` - Whether the giveaway was canceled because the payment for it was refunded.
355    pub fn with_was_refunded(mut self, value: bool) -> Self {
356        self.was_refunded = Some(value);
357        self
358    }
359}
tgbot/types/giveaway/mod.rs

tgbot/types/giveaway/
mod.rs
