twilight_http/request/channel/invite/
create_invite.rs

1use crate::{
2    client::Client,
3    error::Error,
4    request::{self, AuditLogReason, Request, TryIntoRequest},
5    response::{Response, ResponseFuture},
6    routing::Route,
7};
8use serde::Serialize;
9use std::future::IntoFuture;
10use twilight_model::{
11    guild::invite::{Invite, TargetType},
12    id::{
13        Id,
14        marker::{ApplicationMarker, ChannelMarker, UserMarker},
15    },
16};
17use twilight_validate::request::{
18    ValidationError, audit_reason as validate_audit_reason,
19    invite_max_age as validate_invite_max_age, invite_max_uses as validate_invite_max_uses,
20};
21
22#[derive(Serialize)]
23struct CreateInviteFields {
24    #[serde(skip_serializing_if = "Option::is_none")]
25    max_age: Option<u32>,
26    #[serde(skip_serializing_if = "Option::is_none")]
27    max_uses: Option<u16>,
28    #[serde(skip_serializing_if = "Option::is_none")]
29    temporary: Option<bool>,
30    #[serde(skip_serializing_if = "Option::is_none")]
31    target_application_id: Option<Id<ApplicationMarker>>,
32    #[serde(skip_serializing_if = "Option::is_none")]
33    target_user_id: Option<Id<UserMarker>>,
34    #[serde(skip_serializing_if = "Option::is_none")]
35    target_type: Option<TargetType>,
36    #[serde(skip_serializing_if = "Option::is_none")]
37    unique: Option<bool>,
38}
39
40/// Create an invite, with options.
41///
42/// Requires the [`CREATE_INVITE`] permission.
43///
44/// # Examples
45///
46/// ```no_run
47/// use twilight_http::Client;
48/// use twilight_model::id::Id;
49///
50/// # #[tokio::main]
51/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
52/// let client = Client::new("my token".to_owned());
53///
54/// let channel_id = Id::new(123);
55/// let invite = client.create_invite(channel_id).max_uses(3).await?;
56/// # Ok(()) }
57/// ```
58///
59/// [`CREATE_INVITE`]: twilight_model::guild::Permissions::CREATE_INVITE
60#[must_use = "requests must be configured and executed"]
61pub struct CreateInvite<'a> {
62    channel_id: Id<ChannelMarker>,
63    fields: Result<CreateInviteFields, ValidationError>,
64    http: &'a Client,
65    reason: Result<Option<&'a str>, ValidationError>,
66}
67
68impl<'a> CreateInvite<'a> {
69    pub(crate) const fn new(http: &'a Client, channel_id: Id<ChannelMarker>) -> Self {
70        Self {
71            channel_id,
72            fields: Ok(CreateInviteFields {
73                max_age: None,
74                max_uses: None,
75                temporary: None,
76                target_application_id: None,
77                target_user_id: None,
78                target_type: None,
79                unique: None,
80            }),
81            http,
82            reason: Ok(None),
83        }
84    }
85
86    /// Set the maximum age for an invite.
87    ///
88    /// If no age is specified, Discord sets the age to 86400 seconds, or 24 hours.
89    /// Set to 0 to never expire.
90    ///
91    /// # Examples
92    ///
93    /// Create an invite for a channel with a maximum of 1 use and an age of 1
94    /// hour:
95    ///
96    /// ```no_run
97    /// use std::env;
98    /// use twilight_http::Client;
99    /// use twilight_model::id::Id;
100    ///
101    /// # #[tokio::main]
102    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
103    /// let client = Client::new(env::var("DISCORD_TOKEN")?);
104    /// let invite = client
105    ///     .create_invite(Id::new(1))
106    ///     .max_age(60 * 60)
107    ///     .await?
108    ///     .model()
109    ///     .await?;
110    ///
111    /// println!("invite code: {}", invite.code);
112    /// # Ok(()) }
113    /// ```
114    ///
115    /// # Errors
116    ///
117    /// Returns an error of type [`InviteMaxAge`] if the age is invalid.
118    ///
119    /// [`InviteMaxAge`]: twilight_validate::request::ValidationErrorType::InviteMaxAge
120    pub fn max_age(mut self, max_age: u32) -> Self {
121        self.fields = self.fields.and_then(|mut fields| {
122            validate_invite_max_age(max_age)?;
123            fields.max_age = Some(max_age);
124
125            Ok(fields)
126        });
127
128        self
129    }
130
131    /// Set the maximum uses for an invite, or 0 for infinite.
132    ///
133    /// Discord defaults this to 0, or infinite.
134    ///
135    /// # Examples
136    ///
137    /// Create an invite for a channel with a maximum of 5 uses:
138    ///
139    /// ```no_run
140    /// use std::env;
141    /// use twilight_http::Client;
142    /// use twilight_model::id::Id;
143    ///
144    /// # #[tokio::main]
145    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
146    /// let client = Client::new(env::var("DISCORD_TOKEN")?);
147    /// let invite = client
148    ///     .create_invite(Id::new(1))
149    ///     .max_uses(5)
150    ///     .await?
151    ///     .model()
152    ///     .await?;
153    ///
154    /// println!("invite code: {}", invite.code);
155    /// # Ok(()) }
156    /// ```
157    ///
158    /// # Errors
159    ///
160    /// Returns an error of type [`InviteMaxUses`] if the uses is invalid.
161    ///
162    /// [`InviteMaxUses`]: twilight_validate::request::ValidationErrorType::InviteMaxUses
163    pub fn max_uses(mut self, max_uses: u16) -> Self {
164        self.fields = self.fields.and_then(|mut fields| {
165            validate_invite_max_uses(max_uses)?;
166            fields.max_uses = Some(max_uses);
167
168            Ok(fields)
169        });
170
171        self
172    }
173
174    /// Set the target application ID for this invite.
175    ///
176    /// This only works if [`target_type`] is set to [`TargetType::EmbeddedApplication`].
177    ///
178    /// [`target_type`]: Self::target_type
179    pub const fn target_application_id(
180        mut self,
181        target_application_id: Id<ApplicationMarker>,
182    ) -> Self {
183        if let Ok(fields) = self.fields.as_mut() {
184            fields.target_application_id = Some(target_application_id);
185        }
186
187        self
188    }
189
190    /// Set the target user id for this invite.
191    pub const fn target_user_id(mut self, target_user_id: Id<UserMarker>) -> Self {
192        if let Ok(fields) = self.fields.as_mut() {
193            fields.target_user_id = Some(target_user_id);
194        }
195
196        self
197    }
198
199    /// Set the target type for this invite.
200    pub const fn target_type(mut self, target_type: TargetType) -> Self {
201        if let Ok(fields) = self.fields.as_mut() {
202            fields.target_type = Some(target_type);
203        }
204
205        self
206    }
207
208    /// Specify true if the invite should grant temporary membership.
209    ///
210    /// Defaults to false.
211    pub const fn temporary(mut self, temporary: bool) -> Self {
212        if let Ok(fields) = self.fields.as_mut() {
213            fields.temporary = Some(temporary);
214        }
215
216        self
217    }
218
219    /// Specify true if the invite should be unique. Defaults to false.
220    ///
221    /// If true, don't try to reuse a similar invite (useful for creating many
222    /// unique one time use invites). See [Discord Docs/Create Channel Invite].
223    ///
224    /// [Discord Docs/Create Channel Invite]: https://discord.com/developers/docs/resources/channel#create-channel-invite
225    pub const fn unique(mut self, unique: bool) -> Self {
226        if let Ok(fields) = self.fields.as_mut() {
227            fields.unique = Some(unique);
228        }
229
230        self
231    }
232}
233
234impl<'a> AuditLogReason<'a> for CreateInvite<'a> {
235    fn reason(mut self, reason: &'a str) -> Self {
236        self.reason = validate_audit_reason(reason).and(Ok(Some(reason)));
237
238        self
239    }
240}
241
242impl IntoFuture for CreateInvite<'_> {
243    type Output = Result<Response<Invite>, Error>;
244
245    type IntoFuture = ResponseFuture<Invite>;
246
247    fn into_future(self) -> Self::IntoFuture {
248        let http = self.http;
249
250        match self.try_into_request() {
251            Ok(request) => http.request(request),
252            Err(source) => ResponseFuture::error(source),
253        }
254    }
255}
256
257impl TryIntoRequest for CreateInvite<'_> {
258    fn try_into_request(self) -> Result<Request, Error> {
259        let fields = self.fields.map_err(Error::validation)?;
260        let mut request = Request::builder(&Route::CreateInvite {
261            channel_id: self.channel_id.get(),
262        })
263        .json(&fields);
264
265        if let Some(reason) = self.reason.map_err(Error::validation)? {
266            request = request.headers(request::audit_header(reason)?);
267        }
268
269        request.build()
270    }
271}
272
273#[cfg(test)]
274mod tests {
275    use super::CreateInvite;
276    use crate::Client;
277    use std::error::Error;
278    use twilight_model::id::Id;
279
280    #[test]
281    fn max_age() -> Result<(), Box<dyn Error>> {
282        let client = Client::new("foo".to_owned());
283        let mut builder = CreateInvite::new(&client, Id::new(1)).max_age(0);
284        assert_eq!(Some(0), builder.fields.as_ref().unwrap().max_age);
285        builder = builder.max_age(604_800);
286        assert_eq!(Some(604_800), builder.fields.as_ref().unwrap().max_age);
287        builder = builder.max_age(604_801);
288        assert!(builder.fields.is_err());
289
290        Ok(())
291    }
292
293    #[test]
294    fn max_uses() -> Result<(), Box<dyn Error>> {
295        let client = Client::new("foo".to_owned());
296        let mut builder = CreateInvite::new(&client, Id::new(1)).max_uses(0);
297        assert_eq!(Some(0), builder.fields.as_ref().unwrap().max_uses);
298        builder = builder.max_uses(100);
299        assert_eq!(Some(100), builder.fields.as_ref().unwrap().max_uses);
300        builder = builder.max_uses(101);
301        assert!(builder.fields.is_err());
302
303        Ok(())
304    }
305}
twilight_http/request/channel/invite/create_invite.rs

twilight_http/request/channel/invite/
create_invite.rs
