serenity/builder/
add_member.rs

1#[cfg(feature = "http")]
2use super::Builder;
3#[cfg(feature = "http")]
4use crate::http::CacheHttp;
5#[cfg(feature = "http")]
6use crate::internal::prelude::*;
7use crate::model::prelude::*;
8
9/// A builder to add parameters when using [`GuildId::add_member`].
10///
11/// [Discord docs](https://discord.com/developers/docs/resources/guild#add-guild-member).
12#[derive(Clone, Debug, Serialize)]
13#[must_use]
14pub struct AddMember {
15    access_token: String,
16    #[serde(skip_serializing_if = "Option::is_none")]
17    nick: Option<String>,
18    #[serde(skip_serializing_if = "Vec::is_empty")]
19    roles: Vec<RoleId>,
20    #[serde(skip_serializing_if = "Option::is_none")]
21    mute: Option<bool>,
22    #[serde(skip_serializing_if = "Option::is_none")]
23    deaf: Option<bool>,
24}
25
26impl AddMember {
27    /// Constructs a new builder with the given access token, leaving all other fields empty.
28    pub fn new(access_token: String) -> Self {
29        Self {
30            access_token,
31            nick: None,
32            roles: Vec::new(),
33            mute: None,
34            deaf: None,
35        }
36    }
37
38    /// Sets the OAuth2 access token for this request, replacing the current one.
39    ///
40    /// Requires the access token to have the `guilds.join` scope granted.
41    pub fn access_token(mut self, access_token: impl Into<String>) -> Self {
42        self.access_token = access_token.into();
43        self
44    }
45
46    /// Sets the member's nickname.
47    ///
48    /// Requires the [Manage Nicknames] permission.
49    ///
50    /// [Manage Nicknames]: crate::model::permissions::Permissions::MANAGE_NICKNAMES
51    pub fn nickname(mut self, nickname: impl Into<String>) -> Self {
52        self.nick = Some(nickname.into());
53        self
54    }
55
56    /// Sets the list of roles that the member should have.
57    ///
58    /// Requires the [Manage Roles] permission.
59    ///
60    /// [Manage Roles]: crate::model::permissions::Permissions::MANAGE_ROLES
61    pub fn roles(mut self, roles: impl IntoIterator<Item = impl Into<RoleId>>) -> Self {
62        self.roles = roles.into_iter().map(Into::into).collect();
63        self
64    }
65
66    /// Whether to mute the member.
67    ///
68    /// Requires the [Mute Members] permission.
69    ///
70    /// [Mute Members]: crate::model::permissions::Permissions::MUTE_MEMBERS
71    pub fn mute(mut self, mute: bool) -> Self {
72        self.mute = Some(mute);
73        self
74    }
75
76    /// Whether to deafen the member.
77    ///
78    /// Requires the [Deafen Members] permission.
79    ///
80    /// [Deafen Members]: crate::model::permissions::Permissions::DEAFEN_MEMBERS
81    pub fn deafen(mut self, deafen: bool) -> Self {
82        self.deaf = Some(deafen);
83        self
84    }
85}
86
87#[cfg(feature = "http")]
88#[async_trait::async_trait]
89impl Builder for AddMember {
90    type Context<'ctx> = (GuildId, UserId);
91    type Built = Option<Member>;
92
93    /// Adds a [`User`] to this guild with a valid OAuth2 access token.
94    ///
95    /// Returns the created [`Member`] object, or nothing if the user is already a member of the
96    /// guild.
97    ///
98    /// # Errors
99    ///
100    /// Returns [`Error::Http`] if the current user lacks permission, or if invalid data is given.
101    async fn execute(
102        self,
103        cache_http: impl CacheHttp,
104        ctx: Self::Context<'_>,
105    ) -> Result<Self::Built> {
106        cache_http.http().add_guild_member(ctx.0, ctx.1, &self).await
107    }
108}
serenity/builder/add_member.rs

serenity/builder/
add_member.rs
