feature: Add missing properties to Guild and deprecate GuildEmbed (#1573

)

* Add missing properties to Guild, related methods, and deprecate GuildEmbed endpoints

- Add missing guild properties: `discovery_splash`, `widget_enabled`, `widget_channel_id`, `rules_channel_id`, `max_presences`, `max_presences`, `max_members`, `public_updates_channel_id`, `max_video_channel_users`, `approximate_member_count`, `approximate_presence_count`
- Update guild properties: `embed_enabled`, `embed_channel_id`
- Add `GetGuildDiscoverySplashUrl` to `CDN`
- Add classes related to the guild widget
- Add `withCounts` parameter to `GetGuild(s)Async`
- Make GuildEmbed related methods obsolete with a message redirecting to widget ones

* Change xml docs and PremiumSubscriptionCount type

* Changed some xml docs

src/Discord.Net.Core/CDN.cs

@@ -73,11 +73,21 @@ public static string GetGuildIconUrl(ulong guildId, string iconId)
         /// <param name="guildId">The guild snowflake identifier.</param>
         /// <param name="splashId">The splash icon identifier.</param>
         /// <returns>
-        ///     A URL pointing to the guild's icon.
+        ///     A URL pointing to the guild's splash.
         /// </returns>
         public static string GetGuildSplashUrl(ulong guildId, string splashId)
             => splashId != null ? $"{DiscordConfig.CDNUrl}splashes/{guildId}/{splashId}.jpg" : null;
         /// <summary>
+        ///     Returns a guild discovery splash URL.
+        /// </summary>
+        /// <param name="guildId">The guild snowflake identifier.</param>
+        /// <param name="discoverySplashId">The discovery splash icon identifier.</param>
+        /// <returns>
+        ///     A URL pointing to the guild's discovery splash.
+        /// </returns>
+        public static string GetGuildDiscoverySplashUrl(ulong guildId, string discoverySplashId)
+            => discoverySplashId != null ? $"{DiscordConfig.CDNUrl}discovery-splashes/{guildId}/{discoverySplashId}.jpg" : null;
+        /// <summary>
         ///     Returns a channel icon URL.
         /// </summary>
         /// <param name="channelId">The channel snowflake identifier.</param>

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

@@ -0,0 +1,21 @@
+namespace Discord
+{
+    /// <summary>
+    ///     Provides properties that are used to modify the widget of an <see cref="IGuild" /> with the specified changes.
+    /// </summary>
+    public class GuildWidgetProperties
+    {
+        /// <summary>
+        ///     Sets whether the widget should be enabled.
+        /// </summary>
+        public Optional<bool> Enabled { get; set; }
+        /// <summary>
+        ///     Sets the channel that the invite should place its users in, if not <see langword="null" />.
+        /// </summary>
+        public Optional<IChannel> Channel { get; set; }
+        /// <summary>
+        ///     Sets the channel that the invite should place its users in, if not <see langword="null" />.
+        /// </summary>
+        public Optional<ulong?> ChannelId { get; set; }
+    }
+}

src/Discord.Net.Core/Entities/IUpdateable.cs

@@ -10,6 +10,7 @@ public interface IUpdateable
         /// <summary>
         ///     Updates this object's properties with its current state.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
         Task UpdateAsync(RequestOptions options = null);
     }
 }

src/Discord.Net.Rest/API/Common/Guild.cs

@@ -13,6 +13,8 @@ internal class Guild
         public string Icon { get; set; }
         [JsonProperty("splash")]
         public string Splash { get; set; }
+        [JsonProperty("discovery_splash")]
+        public string DiscoverySplash { get; set; }
         [JsonProperty("owner_id")]
         public ulong OwnerId { get; set; }
         [JsonProperty("region")]
@@ -22,9 +24,9 @@ internal class Guild
         [JsonProperty("afk_timeout")]
         public int AFKTimeout { get; set; }
         [JsonProperty("embed_enabled")]
-        public bool EmbedEnabled { get; set; }
+        public Optional<bool> EmbedEnabled { get; set; }
         [JsonProperty("embed_channel_id")]
-        public ulong? EmbedChannelId { get; set; }
+        public Optional<ulong?> EmbedChannelId { get; set; }
         [JsonProperty("verification_level")]
         public VerificationLevel VerificationLevel { get; set; }
         [JsonProperty("default_message_notifications")]
@@ -43,6 +45,10 @@ internal class Guild
         public MfaLevel MfaLevel { get; set; }
         [JsonProperty("application_id")]
         public ulong? ApplicationId { get; set; }
+        [JsonProperty("widget_enabled")]
+        public Optional<bool> WidgetEnabled { get; set; }
+        [JsonProperty("widget_channel_id")]
+        public Optional<ulong?> WidgetChannelId { get; set; }
         [JsonProperty("system_channel_id")]
         public ulong? SystemChannelId { get; set; }
         [JsonProperty("premium_tier")]
@@ -56,9 +62,23 @@ internal class Guild
         // this value is inverted, flags set will turn OFF features
         [JsonProperty("system_channel_flags")]
         public SystemChannelMessageDeny SystemChannelFlags { get; set; }
+        [JsonProperty("rules_channel_id")]
+        public ulong? RulesChannelId { get; set; }
+        [JsonProperty("max_presences")]
+        public Optional<int?> MaxPresences { get; set; }
+        [JsonProperty("max_members")]
+        public Optional<int> MaxMembers { get; set; }
         [JsonProperty("premium_subscription_count")]
-        public int? PremiumSubscriptionCount { get; set; }
+        public Optional<int> PremiumSubscriptionCount { get; set; }
         [JsonProperty("preferred_locale")]
         public string PreferredLocale { get; set; }
+        [JsonProperty("public_updates_channel_id")]
+        public ulong? PublicUpdatesChannelId { get; set; }
+        [JsonProperty("max_video_channel_users")]
+        public Optional<int> MaxVideoChannelUsers { get; set; }
+        [JsonProperty("approximate_member_count")]
+        public Optional<int> ApproximateMemberCount { get; set; }
+        [JsonProperty("approximate_presence_count")]
+        public Optional<int> ApproximatePresenceCount { get; set; }
     }
 }

src/Discord.Net.Rest/API/Common/GuildWidget.cs

@@ -0,0 +1,13 @@
+#pragma warning disable CS1591
+using Newtonsoft.Json;
+
+namespace Discord.API
+{
+    internal class GuildWidget
+    {
+        [JsonProperty("enabled")]
+        public bool Enabled { get; set; }
+        [JsonProperty("channel_id")]
+        public ulong? ChannelId { get; set; }
+    }
+}

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

@@ -0,0 +1,14 @@
+#pragma warning disable CS1591
+using Newtonsoft.Json;
+
+namespace Discord.API.Rest
+{
+    [JsonObject(MemberSerialization = MemberSerialization.OptIn)]
+    internal class ModifyGuildWidgetParams
+    {        
+        [JsonProperty("enabled")]
+        public Optional<bool> Enabled { get; set; }
+        [JsonProperty("channel")]
+        public Optional<ulong?> ChannelId { get; set; }
+    }
+}

src/Discord.Net.Rest/ClientHelper.cs

@@ -62,9 +62,9 @@ public static async Task<RestInviteMetadata> GetInviteAsync(BaseDiscordClient cl
         }
 
         public static async Task<RestGuild> GetGuildAsync(BaseDiscordClient client,
-            ulong id, RequestOptions options)
+            ulong id, bool withCounts, RequestOptions options)
         {
-            var model = await client.ApiClient.GetGuildAsync(id, options).ConfigureAwait(false);
+            var model = await client.ApiClient.GetGuildAsync(id, withCounts, options).ConfigureAwait(false);
             if (model != null)
                 return RestGuild.Create(client, model);
             return null;
@@ -77,6 +77,14 @@ public static async Task<RestGuild> GetGuildAsync(BaseDiscordClient client,
                 return RestGuildEmbed.Create(model);
             return null;
         }
+        public static async Task<RestGuildWidget?> GetGuildWidgetAsync(BaseDiscordClient client,
+            ulong id, RequestOptions options)
+        {
+            var model = await client.ApiClient.GetGuildWidgetAsync(id, options).ConfigureAwait(false);
+            if (model != null)
+                return RestGuildWidget.Create(model);
+            return null;
+        }
         public static IAsyncEnumerable<IReadOnlyCollection<RestUserGuild>> GetGuildSummariesAsync(BaseDiscordClient client, 
             ulong? fromGuildId, int? limit, RequestOptions options)
         {
@@ -106,13 +114,13 @@ public static IAsyncEnumerable<IReadOnlyCollection<RestUserGuild>> GetGuildSumma
                 count: limit
             );
         }
-        public static async Task<IReadOnlyCollection<RestGuild>> GetGuildsAsync(BaseDiscordClient client, RequestOptions options)
+        public static async Task<IReadOnlyCollection<RestGuild>> GetGuildsAsync(BaseDiscordClient client, bool withCounts, RequestOptions options)
         {
             var summaryModels = await GetGuildSummariesAsync(client, null, null, options).FlattenAsync().ConfigureAwait(false);
             var guilds = ImmutableArray.CreateBuilder<RestGuild>();
             foreach (var summaryModel in summaryModels)
             {
-                var guildModel = await client.ApiClient.GetGuildAsync(summaryModel.Id).ConfigureAwait(false);
+                var guildModel = await client.ApiClient.GetGuildAsync(summaryModel.Id, withCounts).ConfigureAwait(false);
                 if (guildModel != null)
                     guilds.Add(RestGuild.Create(client, guildModel));
             }
@@ -140,7 +148,7 @@ public static async Task<RestUser> GetUserAsync(BaseDiscordClient client,
         public static async Task<RestGuildUser> GetGuildUserAsync(BaseDiscordClient client,
             ulong guildId, ulong id, RequestOptions options)
         {
-            var guild = await GetGuildAsync(client, guildId, options).ConfigureAwait(false);
+            var guild = await GetGuildAsync(client, guildId, false, options).ConfigureAwait(false);
             if (guild == null)
                 return null;
 

src/Discord.Net.Rest/DiscordRestApiClient.cs

@@ -787,15 +787,15 @@ public async Task RemoveGroupRecipientAsync(ulong channelId, ulong userId, Reque
         }
 
         //Guilds
-        public async Task<Guild> GetGuildAsync(ulong guildId, RequestOptions options = null)
+        public async Task<Guild> GetGuildAsync(ulong guildId, bool withCounts, RequestOptions options = null)
         {
             Preconditions.NotEqual(guildId, 0, nameof(guildId));
             options = RequestOptions.CreateOrClone(options);
 
             try
             {
                 var ids = new BucketIds(guildId: guildId);
-                return await SendAsync<Guild>("GET", () => $"guilds/{guildId}", ids, options: options).ConfigureAwait(false);
+                return await SendAsync<Guild>("GET", () => $"guilds/{guildId}?with_counts={(withCounts ? "true" : "false")}", ids, options: options).ConfigureAwait(false);
             }
             catch (HttpException ex) when (ex.HttpCode == HttpStatusCode.NotFound) { return null; }
         }
@@ -938,6 +938,32 @@ public async Task<GuildEmbed> ModifyGuildEmbedAsync(ulong guildId, Rest.ModifyGu
             return await SendJsonAsync<GuildEmbed>("PATCH", () => $"guilds/{guildId}/embed", args, ids, options: options).ConfigureAwait(false);
         }
 
+        //Guild Widget
+        /// <exception cref="ArgumentException"><paramref name="guildId"/> must not be equal to zero.</exception>
+        public async Task<GuildWidget> GetGuildWidgetAsync(ulong guildId, RequestOptions options = null)
+        {
+            Preconditions.NotEqual(guildId, 0, nameof(guildId));
+            options = RequestOptions.CreateOrClone(options);
+
+            try
+            {
+                var ids = new BucketIds(guildId: guildId);
+                return await SendAsync<GuildWidget>("GET", () => $"guilds/{guildId}/widget", ids, options: options).ConfigureAwait(false);
+            }
+            catch (HttpException ex) when (ex.HttpCode == HttpStatusCode.NotFound) { return null; }
+        }
+        /// <exception cref="ArgumentException"><paramref name="guildId"/> must not be equal to zero.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="args"/> must not be <see langword="null"/>.</exception>
+        public async Task<GuildWidget> ModifyGuildWidgetAsync(ulong guildId, Rest.ModifyGuildWidgetParams args, RequestOptions options = null)
+        {
+            Preconditions.NotNull(args, nameof(args));
+            Preconditions.NotEqual(guildId, 0, nameof(guildId));
+            options = RequestOptions.CreateOrClone(options);
+
+            var ids = new BucketIds(guildId: guildId);
+            return await SendJsonAsync<GuildWidget>("PATCH", () => $"guilds/{guildId}/widget", args, ids, options: options).ConfigureAwait(false);
+        }
+
         //Guild Integrations
         /// <exception cref="ArgumentException"><paramref name="guildId"/> must not be equal to zero.</exception>
         public async Task<IReadOnlyCollection<Integration>> GetGuildIntegrationsAsync(ulong guildId, RequestOptions options = null)

src/Discord.Net.Rest/DiscordRestClient.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.IO;
@@ -76,15 +77,22 @@ public Task<RestInviteMetadata> GetInviteAsync(string inviteId, RequestOptions o
             => ClientHelper.GetInviteAsync(this, inviteId, options);
 
         public Task<RestGuild> GetGuildAsync(ulong id, RequestOptions options = null)
-            => ClientHelper.GetGuildAsync(this, id, options);
+            => ClientHelper.GetGuildAsync(this, id, false, options);
+        public Task<RestGuild> GetGuildAsync(ulong id, bool withCounts, RequestOptions options = null)
+            => ClientHelper.GetGuildAsync(this, id, withCounts, options);
+        [Obsolete("This endpoint is deprecated, use GetGuildWidgetAsync instead.")]
         public Task<RestGuildEmbed?> GetGuildEmbedAsync(ulong id, RequestOptions options = null)
             => ClientHelper.GetGuildEmbedAsync(this, id, options);
+        public Task<RestGuildWidget?> GetGuildWidgetAsync(ulong id, RequestOptions options = null)
+            => ClientHelper.GetGuildWidgetAsync(this, id, options);
         public IAsyncEnumerable<IReadOnlyCollection<RestUserGuild>> GetGuildSummariesAsync(RequestOptions options = null)
             => ClientHelper.GetGuildSummariesAsync(this, null, null, options);
         public IAsyncEnumerable<IReadOnlyCollection<RestUserGuild>> GetGuildSummariesAsync(ulong fromGuildId, int limit, RequestOptions options = null)
             => ClientHelper.GetGuildSummariesAsync(this, fromGuildId, limit, options);
         public Task<IReadOnlyCollection<RestGuild>> GetGuildsAsync(RequestOptions options = null)
-            => ClientHelper.GetGuildsAsync(this, options);
+            => ClientHelper.GetGuildsAsync(this, false, options);
+        public Task<IReadOnlyCollection<RestGuild>> GetGuildsAsync(bool withCounts, RequestOptions options = null)
+            => ClientHelper.GetGuildsAsync(this, withCounts, options);
         public Task<RestGuild> CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon = null, RequestOptions options = null)
             => ClientHelper.CreateGuildAsync(this, name, region, jpegIcon, options);
 

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

@@ -5,6 +5,7 @@
 using System.Linq;
 using System.Threading.Tasks;
 using EmbedModel = Discord.API.GuildEmbed;
+using WidgetModel = Discord.API.GuildWidget;
 using Model = Discord.API.Guild;
 using RoleModel = Discord.API.Role;
 using ImageModel = Discord.API.Image;
@@ -99,6 +100,27 @@ public static async Task<EmbedModel> ModifyEmbedAsync(IGuild guild, BaseDiscordC
 
             return await client.ApiClient.ModifyGuildEmbedAsync(guild.Id, apiArgs, options).ConfigureAwait(false);
         }
+        /// <exception cref="ArgumentNullException"><paramref name="func"/> is <c>null</c>.</exception>
+        public static async Task<WidgetModel> ModifyWidgetAsync(IGuild guild, BaseDiscordClient client,
+            Action<GuildWidgetProperties> func, RequestOptions options)
+        {
+            if (func == null)
+                throw new ArgumentNullException(nameof(func));
+
+            var args = new GuildWidgetProperties();
+            func(args);
+            var apiArgs = new API.Rest.ModifyGuildWidgetParams
+            {
+                Enabled = args.Enabled
+            };
+
+            if (args.Channel.IsSpecified)
+                apiArgs.ChannelId = args.Channel.Value?.Id;
+            else if (args.ChannelId.IsSpecified)
+                apiArgs.ChannelId = args.ChannelId.Value;
+
+            return await client.ApiClient.ModifyGuildWidgetAsync(guild.Id, apiArgs, options).ConfigureAwait(false);
+        }
         public static async Task ReorderChannelsAsync(IGuild guild, BaseDiscordClient client,
             IEnumerable<ReorderChannelProperties> args, RequestOptions options)
         {