(ifcbrk) Add SearchUsersAsync (#1556)

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

@@ -710,6 +710,22 @@ namespace Discord
         ///     be or has been removed from this guild.
         /// </returns>
         Task<int> PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null);
+        /// <summary>
+        ///     Gets a collection of users in this guild that the name or nickname starts with the
+        ///     provided <see cref="string"/> at <paramref name="query"/>.
+        /// </summary>
+        /// <remarks>
+        ///     The <paramref name="limit"/> can not be higher than <see cref="DiscordConfig.MaxUsersPerBatch"/>.
+        /// </remarks>
+        /// <param name="query">The partial name or nickname to search.</param>
+        /// <param name="limit">The maximum number of users to be gotten.</param>
+        /// <param name="mode">The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a collection of guild
+        ///     users that the name or nickname starts with the provided <see cref="string"/> at <paramref name="query"/>.
+        /// </returns>
+        Task<IReadOnlyCollection<IGuildUser>> SearchUsersAsync(string query, int limit = DiscordConfig.MaxUsersPerBatch, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
         /// <summary>
         ///     Gets the specified number of audit log entries for this guild.

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

@@ -0,0 +1,9 @@
+#pragma warning disable CS1591
+namespace Discord.API.Rest
+{
+    internal class SearchGuildMembersParams
+    {
+        public string Query { get; set; }
+        public Optional<int> Limit { get; set; }
+    }
+}

src/Discord.Net.Rest/DiscordRestApiClient.cs

@@ -1136,6 +1136,22 @@ namespace Discord.API
                 await SendJsonAsync("PATCH", () => $"guilds/{guildId}/members/{userId}", args, ids, options: options).ConfigureAwait(false);
             }
         }
+        public async Task<IReadOnlyCollection<GuildMember>> SearchGuildMembersAsync(ulong guildId, SearchGuildMembersParams args, RequestOptions options = null)
+        {
+            Preconditions.NotEqual(guildId, 0, nameof(guildId));
+            Preconditions.NotNull(args, nameof(args));
+            Preconditions.GreaterThan(args.Limit, 0, nameof(args.Limit));
+            Preconditions.AtMost(args.Limit, DiscordConfig.MaxUsersPerBatch, nameof(args.Limit));
+            Preconditions.NotNullOrEmpty(args.Query, nameof(args.Query));
+            options = RequestOptions.CreateOrClone(options);
+
+            int limit = args.Limit.GetValueOrDefault(DiscordConfig.MaxUsersPerBatch);
+            string query = args.Query;
+
+            var ids = new BucketIds(guildId: guildId);
+            Expression<Func<string>> endpoint = () => $"guilds/{guildId}/members/search?limit={limit}&query={query}";
+            return await SendAsync<IReadOnlyCollection<GuildMember>>("GET", endpoint, ids, options: options).ConfigureAwait(false);
+        }
 
         //Guild Roles
         public async Task<IReadOnlyCollection<Role>> GetGuildRolesAsync(ulong guildId, RequestOptions options = null)

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

@@ -387,6 +387,17 @@ namespace Discord.Rest
                 model = await client.ApiClient.BeginGuildPruneAsync(guild.Id, args, options).ConfigureAwait(false);
             return model.Pruned;
         }
+        public static async Task<IReadOnlyCollection<RestGuildUser>> SearchUsersAsync(IGuild guild, BaseDiscordClient client,
+            string query, int? limit, RequestOptions options)
+        {
+            var apiArgs = new SearchGuildMembersParams
+            {
+                Query = query,
+                Limit = limit ?? Optional.Create<int>()
+            };
+            var models = await client.ApiClient.SearchGuildMembersAsync(guild.Id, apiArgs, options).ConfigureAwait(false);
+            return models.Select(x => RestGuildUser.Create(client, guild, x)).ToImmutableArray();
+        }
 
         // Audit logs
         public static IAsyncEnumerable<IReadOnlyCollection<RestAuditLogEntry>> GetAuditLogsAsync(IGuild guild, BaseDiscordClient client,

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

@@ -634,6 +634,23 @@ namespace Discord.Rest
         public Task<int> PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null)
             => GuildHelper.PruneUsersAsync(this, Discord, days, simulate, options);
 
+        /// <summary>
+        ///     Gets a collection of users in this guild that the name or nickname starts with the
+        ///     provided <see cref="string"/> at <paramref name="query"/>.
+        /// </summary>
+        /// <remarks>
+        ///     The <paramref name="limit"/> can not be higher than <see cref="DiscordConfig.MaxUsersPerBatch"/>.
+        /// </remarks>
+        /// <param name="query">The partial name or nickname to search.</param>
+        /// <param name="limit">The maximum number of users to be gotten.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a collection of guild
+        ///     users that the name or nickname starts with the provided <see cref="string"/> at <paramref name="query"/>.
+        /// </returns>
+        public Task<IReadOnlyCollection<RestGuildUser>> SearchUsersAsync(string query, int limit = DiscordConfig.MaxUsersPerBatch, RequestOptions options = null)
+            => GuildHelper.SearchUsersAsync(this, Discord, query, limit, options);
+
         //Audit logs
         /// <summary>
         ///     Gets the specified number of audit log entries for this guild.
@@ -884,6 +901,14 @@ namespace Discord.Rest
         /// <exception cref="NotSupportedException">Downloading users is not supported for a REST-based guild.</exception>
         Task IGuild.DownloadUsersAsync() =>
             throw new NotSupportedException();
+        /// <inheritdoc />
+        async Task<IReadOnlyCollection<IGuildUser>> IGuild.SearchUsersAsync(string query, int limit, CacheMode mode, RequestOptions options)
+        {
+            if (mode == CacheMode.AllowDownload)
+                return await SearchUsersAsync(query, limit, options).ConfigureAwait(false);
+            else
+                return ImmutableArray.Create<IGuildUser>();
+        }
 
         async Task<IReadOnlyCollection<IAuditLogEntry>> IGuild.GetAuditLogsAsync(int limit, CacheMode cacheMode, RequestOptions options,
             ulong? beforeId, ulong? userId, ActionType? actionType)

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

@@ -850,6 +850,23 @@ namespace Discord.WebSocket
             _downloaderPromise.TrySetResultAsync(true);
         }
 
+        /// <summary>
+        ///     Gets a collection of users in this guild that the name or nickname starts with the
+        ///     provided <see cref="string"/> at <paramref name="query"/>.
+        /// </summary>
+        /// <remarks>
+        ///     The <paramref name="limit"/> can not be higher than <see cref="DiscordConfig.MaxUsersPerBatch"/>.
+        /// </remarks>
+        /// <param name="query">The partial name or nickname to search.</param>
+        /// <param name="limit">The maximum number of users to be gotten.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a collection of guild
+        ///     users that the name or nickname starts with the provided <see cref="string"/> at <paramref name="query"/>.
+        /// </returns>
+        public Task<IReadOnlyCollection<RestGuildUser>> SearchUsersAsync(string query, int limit = DiscordConfig.MaxUsersPerBatch, RequestOptions options = null)
+            => GuildHelper.SearchUsersAsync(this, Discord, query, limit, options);
+
         //Audit logs
         /// <summary>
         ///     Gets the specified number of audit log entries for this guild.
@@ -1224,6 +1241,14 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         Task<IGuildUser> IGuild.GetOwnerAsync(CacheMode mode, RequestOptions options)
             => Task.FromResult<IGuildUser>(Owner);
+        /// <inheritdoc />
+        async Task<IReadOnlyCollection<IGuildUser>> IGuild.SearchUsersAsync(string query, int limit, CacheMode mode, RequestOptions options)
+        {
+            if (mode == CacheMode.AllowDownload)
+                return await SearchUsersAsync(query, limit, options).ConfigureAwait(false);
+            else
+                return ImmutableArray.Create<IGuildUser>();
+        }
 
         /// <inheritdoc />
         async Task<IReadOnlyCollection<IAuditLogEntry>> IGuild.GetAuditLogsAsync(int limit, CacheMode cacheMode, RequestOptions options,