feature: add Add Guild Member endpoint (#1183)

* Add AddGuildMember Oauth endpoint support

* Concat RoleIds if already exists.

* Use local ids variable.

src/Discord.Net.Core/Entities/Guilds/IGuild.cs

@@ -536,6 +536,18 @@ namespace Discord
         Task<IRole> CreateRoleAsync(string name, GuildPermissions? permissions = null, Color? color = null, bool isHoisted = false, RequestOptions options = null);
 
         /// <summary>
+        ///     Adds a user to this guild.
+        /// </summary>
+        /// <remarks>
+        ///     This method requires you have an OAuth2 access token for the user, requested with the guilds.join scope, and that the bot have the MANAGE_INVITES permission in the guild.
+        /// </remarks>
+        /// <param name="id">The snowflake identifier of the user.</param>
+        /// <param name="accessToken">The OAuth2 access token for the user, requested with the guilds.join scope.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the user upon being added to the guild.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>A guild user associated with the specified <paramref name="id" />; <c>null</c> if the user is already in the guild.</returns>
+        Task<IGuildUser> AddGuildUserAsync(ulong userId, string accessToken, Action<AddGuildUserProperties> func = null, RequestOptions options = null);
+        /// <summary>
         ///     Gets a collection of all users in this guild.
         /// </summary>
         /// <remarks>

src/Discord.Net.Core/Entities/Users/AddGuildUserProperties.cs

@@ -0,0 +1,62 @@
+using System.Collections.Generic;
+
+namespace Discord
+{
+    /// <summary>
+    ///     Properties that are used to add a new <see cref="IGuildUser"/> to the guild with the following parameters.
+    /// </summary>
+    /// <seealso cref="IGuild.AddGuildUserAsync" />
+    public class AddGuildUserProperties
+    {
+        /// <summary>
+        ///     Gets or sets the user's nickname.
+        /// </summary>
+        /// <remarks>
+        ///     To clear the user's nickname, this value can be set to <c>null</c> or
+        ///     <see cref="string.Empty"/>.
+        /// </remarks>
+        public Optional<string> Nickname { get; set; }
+        /// <summary>
+        ///     Gets or sets whether the user should be muted in a voice channel.
+        /// </summary>
+        /// <remarks>
+        ///     If this value is set to <c>true</c>, no user will be able to hear this user speak in the guild.
+        /// </remarks>
+        public Optional<bool> Mute { get; set; }
+        /// <summary>
+        ///     Gets or sets whether the user should be deafened in a voice channel.
+        /// </summary>
+        /// <remarks>
+        ///     If this value is set to <c>true</c>, this user will not be able to hear anyone speak in the guild.
+        /// </remarks>
+        public Optional<bool> Deaf { get; set; }
+        /// <summary>
+        ///     Gets or sets the roles the user should have.
+        /// </summary>
+        /// <remarks>
+        ///     <para>
+        ///         To add a role to a user:
+        ///         <see cref="IGuildUser.AddRolesAsync(IEnumerable{IRole},RequestOptions)" />
+        ///     </para>
+        ///     <para>
+        ///         To remove a role from a user:
+        ///         <see cref="IGuildUser.RemoveRolesAsync(IEnumerable{IRole},RequestOptions)" />
+        ///     </para>
+        /// </remarks>
+        public Optional<IEnumerable<IRole>> Roles { get; set; }
+        /// <summary>
+        ///     Gets or sets the roles the user should have.
+        /// </summary>
+        /// <remarks>
+        ///     <para>
+        ///         To add a role to a user:
+        ///         <see cref="IGuildUser.AddRolesAsync(IEnumerable{IRole},RequestOptions)" />
+        ///     </para>
+        ///     <para>
+        ///         To remove a role from a user:
+        ///         <see cref="IGuildUser.RemoveRolesAsync(IEnumerable{IRole},RequestOptions)" />
+        ///     </para>
+        /// </remarks>
+        public Optional<IEnumerable<ulong>> RoleIds { get; set; }
+    }
+}

src/Discord.Net.Rest/API/Rest/AddGuildMemberParams.cs

@@ -0,0 +1,19 @@
+using Newtonsoft.Json;
+
+namespace Discord.API.Rest
+{
+    [JsonObject(MemberSerialization = MemberSerialization.OptIn)]
+    internal class AddGuildMemberParams
+    {
+        [JsonProperty("access_token")]
+        public string AccessToken { get; set; }
+        [JsonProperty("nick")]
+        public Optional<string> Nickname { get; set; }
+        [JsonProperty("roles")]
+        public Optional<ulong[]> RoleIds { get; set; }
+        [JsonProperty("mute")]
+        public Optional<bool> IsMuted { get; set; }
+        [JsonProperty("deaf")]
+        public Optional<bool> IsDeafened { get; set; }
+    }
+}

src/Discord.Net.Rest/DiscordRestApiClient.cs

@@ -994,6 +994,25 @@ namespace Discord.API
         }
 
         //Guild Members
+        public async Task<GuildMember> AddGuildMemberAsync(ulong guildId, ulong userId, AddGuildMemberParams args, RequestOptions options = null)
+        {
+            Preconditions.NotEqual(guildId, 0, nameof(guildId));
+            Preconditions.NotEqual(userId, 0, nameof(userId));
+            Preconditions.NotNull(args, nameof(args));
+            Preconditions.NotNullOrWhitespace(args.AccessToken, nameof(args.AccessToken));
+
+            if (args.RoleIds.IsSpecified)
+            {
+                foreach (var roleId in args.RoleIds.Value)
+                    Preconditions.NotEqual(roleId, 0, nameof(roleId));
+            }                
+
+            options = RequestOptions.CreateOrClone(options);
+
+            var ids = new BucketIds(guildId: guildId);
+
+            return await SendJsonAsync<GuildMember>("PUT", () => $"guilds/{guildId}/members/{userId}", args, ids, options: options);
+        }
         public async Task<GuildMember> GetGuildMemberAsync(ulong guildId, ulong userId, RequestOptions options = null)
         {
             Preconditions.NotEqual(guildId, 0, nameof(guildId));

src/Discord.Net.Rest/Entities/Guilds/GuildHelper.cs

@@ -257,6 +257,34 @@ namespace Discord.Rest
         }
 
         //Users
+        public static async Task<RestGuildUser> AddGuildUserAsync(IGuild guild, BaseDiscordClient client, ulong userId, string accessToken,
+            Action<AddGuildUserProperties> func, RequestOptions options)
+        {
+            var args = new AddGuildUserProperties();
+            func?.Invoke(args);
+
+            if (args.Roles.IsSpecified)
+            {
+                var ids = args.Roles.Value.Select(r => r.Id);
+
+                if (args.RoleIds.IsSpecified)
+                    args.RoleIds.Value.Concat(ids);
+                else
+                    args.RoleIds = Optional.Create(ids);
+            }
+            var apiArgs = new AddGuildMemberParams
+            {
+                AccessToken = accessToken,
+                Nickname = args.Nickname,
+                IsDeafened = args.Deaf,
+                IsMuted = args.Mute,
+                RoleIds = args.RoleIds.IsSpecified ? args.RoleIds.Value.Distinct().ToArray() : Optional.Create<ulong[]>()
+            };
+
+            var model = await client.ApiClient.AddGuildMemberAsync(guild.Id, userId, apiArgs, options);
+
+            return model is null ? null : RestGuildUser.Create(client, guild, model);
+        }
         public static async Task<RestGuildUser> GetUserAsync(IGuild guild, BaseDiscordClient client,
             ulong id, RequestOptions options)
         {

src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs

@@ -537,6 +537,10 @@ namespace Discord.Rest
         public IAsyncEnumerable<IReadOnlyCollection<RestGuildUser>> GetUsersAsync(RequestOptions options = null)
             => GuildHelper.GetUsersAsync(this, Discord, null, null, options);
 
+        /// <inheritdoc />
+        public Task<RestGuildUser> AddGuildUserAsync(ulong id, string accessToken, Action<AddGuildUserProperties> func = null, RequestOptions options = null)
+            => GuildHelper.AddGuildUserAsync(this, Discord, id, accessToken, func, options);
+
         /// <summary>
         ///     Gets a user from this guild.
         /// </summary>
@@ -801,6 +805,10 @@ namespace Discord.Rest
             => await CreateRoleAsync(name, permissions, color, isHoisted, options).ConfigureAwait(false);
 
         /// <inheritdoc />
+        async Task<IGuildUser> IGuild.AddGuildUserAsync(ulong userId, string accessToken, Action<AddGuildUserProperties> func, RequestOptions options)
+            => await AddGuildUserAsync(userId, accessToken, func, options);
+
+        /// <inheritdoc />
         async Task<IGuildUser> IGuild.GetUserAsync(ulong id, CacheMode mode, RequestOptions options)
         {
             if (mode == CacheMode.AllowDownload)

src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs

@@ -669,6 +669,10 @@ namespace Discord.WebSocket
         }
 
         //Users
+        /// <inheritdoc />
+        public Task<RestGuildUser> AddGuildUserAsync(ulong id, string accessToken, Action<AddGuildUserProperties> func = null, RequestOptions options = null)
+            => GuildHelper.AddGuildUserAsync(this, Discord, id, accessToken, func, options);
+
         /// <summary>
         ///     Gets a user from this guild.
         /// </summary>
@@ -1096,6 +1100,10 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         Task<IReadOnlyCollection<IGuildUser>> IGuild.GetUsersAsync(CacheMode mode, RequestOptions options)
             => Task.FromResult<IReadOnlyCollection<IGuildUser>>(Users);
+
+        /// <inheritdoc />
+        async Task<IGuildUser> IGuild.AddGuildUserAsync(ulong userId, string accessToken, Action<AddGuildUserProperties> func, RequestOptions options)
+            => await AddGuildUserAsync(userId, accessToken, func, options);
         /// <inheritdoc />
         Task<IGuildUser> IGuild.GetUserAsync(ulong id, CacheMode mode, RequestOptions options)
             => Task.FromResult<IGuildUser>(GetUser(id));