feature: Include allowed mentions payload on message creation (discor…

…d-net#1455)

* Feature: Allowed mentions object on msg create (interface breaking)

This change implements the AllowedMentions object for the payload of message creation. By default, the mentions behavior remains unchanged, the message content is parsed for all mentionable entities and they are all notified. If this payload is not null, it will use the content of the allowed_mentions field to determine if a role is notified, or just displayed.

This change is interface breaking. This follows the conventions of keeping RequestOptions as the last argument, but could break some users who specify each of these arguments without using named arguments.

* lint: remove commented-out code

This change removes the commented-out code which was added during testing from the previous commit.

* fix interface break: reorder allowedMentions arg so that it's after options

This change modifies the order of the AllowedMentions argument of SendMessageAsync so that this addition shouldn't be interface breaking. The downside to this change is that it breaks the convention followed by other methods, where the RequestOptions argument is normally last.

* docs: fix typo in allowedMentions arg doc

* fix interface break arg from IRestMessageChannel

* docs: update xmldoc for allowedMentions args

* fix interface breaking arg order for ISocketMessageChannel

* fix mocked classes that weren't updated

* fix: RestDMChannel#SendMessageAsync bug, allowed mentions always null

This change fixes a bug that was introduced while testing changes to the interface of the SendMessageAsync method to try and retain interface compatibility

* docs: update xmldoc for AllowedMentions type

* docs: reword xmldoc of AllowedMentionTypes type

* docs: fix typo

* fix: validate that User/Role flags and UserIds/RoleIds lists are mutually exclusive

This change adds validation to SendMessageAsync which checks that the User flag is mutually exclusive with the list of UserIds, and that the Role flag is also mutually exclusive with the list of RoleIds

* docs: reword summaries for AllowedMentions type

* Add util properties for specifying all or no mentions

Adds read only properties which specify that all mentions or no mentions will notify users. These settings might be more common than others, so this would make them easier to use.

* docs: Resolve PR comments for documentation issues/typos

src/Discord.Net.Commands/ModuleBase.cs

@@ -31,9 +31,13 @@ public abstract class ModuleBase<T> : IModuleBase
         /// </param>
         /// <param name="isTTS">Specifies if Discord should read this <paramref name="message"/> aloud using text-to-speech.</param>
         /// <param name="embed">An embed to be displayed alongside the <paramref name="message"/>.</param>
-        protected virtual async Task<IUserMessage> ReplyAsync(string message = null, bool isTTS = false, Embed embed = null, RequestOptions options = null)
+        /// <param name="allowedMentions">
+        ///     Specifies if notifications are sent for mentioned users and roles in the <paramref name="message"/>.
+        ///     If <c>null</c>, all mentioned roles and users will be notified.
+        /// </param>
+        protected virtual async Task<IUserMessage> ReplyAsync(string message = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null)
         {
-            return await Context.Channel.SendMessageAsync(message, isTTS, embed, options).ConfigureAwait(false);
+            return await Context.Channel.SendMessageAsync(message, isTTS, embed, options, allowedMentions).ConfigureAwait(false);
         }
         /// <summary>
         ///     The method to execute before executing the command.

src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs

@@ -23,11 +23,15 @@ public interface IMessageChannel : IChannel
         /// <param name="isTTS">Determines whether the message should be read aloud by Discord or not.</param>
         /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="allowedMentions">
+        ///     Specifies if notifications are sent for mentioned users and roles in the message <paramref name="text"/>.
+        ///     If <c>null</c>, all mentioned roles and users will be notified.
+        /// </param>
         /// <returns>
         ///     A task that represents an asynchronous send operation for delivering the message. The task result
         ///     contains the sent message.
         /// </returns>
-        Task<IUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
+        Task<IUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null);
         /// <summary>
         ///     Sends a file to this message channel with an optional caption.
         /// </summary>

src/Discord.Net.Core/Entities/Messages/AllowedMentionTypes.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace Discord
+{
+    /// <summary>
+    ///     Specifies the type of mentions that will be notified from the message content.
+    /// </summary>
+    [Flags]
+    public enum AllowedMentionTypes
+    {
+        /// <summary>
+        ///     Controls role mentions.
+        /// </summary>
+        Roles,
+        /// <summary>
+        ///     Controls user mentions.
+        /// </summary>
+        Users,
+        /// <summary>
+        ///     Controls <code>@everyone</code> and <code>@here</code> mentions.
+        /// </summary>
+        Everyone,
+    }
+}

src/Discord.Net.Core/Entities/Messages/AllowedMentions.cs

@@ -0,0 +1,64 @@
+using System;
+using System.Collections.Generic;
+
+namespace Discord
+{
+    /// <summary>
+    ///     Defines which mentions and types of mentions that will notify users from the message content.
+    /// </summary>
+    public class AllowedMentions
+    {
+        private static readonly Lazy<AllowedMentions> none = new Lazy<AllowedMentions>(() => new AllowedMentions());
+        private static readonly Lazy<AllowedMentions> all = new Lazy<AllowedMentions>(() =>
+            new AllowedMentions(AllowedMentionTypes.Everyone | AllowedMentionTypes.Users | AllowedMentionTypes.Roles));
+
+        /// <summary>
+        ///     Gets a value which indicates that no mentions in the message content should notify users.
+        /// </summary>
+        public static AllowedMentions None => none.Value;
+
+        /// <summary>
+        ///     Gets a value which indicates that all mentions in the message content should notify users.
+        /// </summary>
+        public static AllowedMentions All => all.Value;
+
+        /// <summary>
+        ///     Gets or sets the type of mentions that will be parsed from the message content.
+        /// </summary>
+        /// <remarks>
+        ///     The <see cref="AllowedMentionTypes.Users"/> flag is mutually exclusive with the <see cref="UserIds"/>
+        ///     property, and the <see cref="AllowedMentionTypes.Roles"/> flag is mutually exclusive with the
+        ///     <see cref="RoleIds"/> property.
+        ///     If <c>null</c>, only the ids specified in <see cref="UserIds"/> and <see cref="RoleIds"/> will be mentioned.
+        /// </remarks>
+        public AllowedMentionTypes? AllowedTypes { get; set; }
+
+        /// <summary>
+        ///     Gets or sets the list of all role ids that will be mentioned.
+        ///     This property is mutually exclusive with the <see cref="AllowedMentionTypes.Roles"/>
+        ///     flag of the <see cref="AllowedTypes"/> property. If the flag is set, the value of this property
+        ///     must be <c>null</c> or empty.
+        /// </summary>
+        public List<ulong> RoleIds { get; set; }
+
+        /// <summary>
+        ///     Gets or sets the list of all user ids that will be mentioned.
+        ///     This property is mutually exclusive with the <see cref="AllowedMentionTypes.Users"/>
+        ///     flag of the <see cref="AllowedTypes"/> property. If the flag is set, the value of this property
+        ///     must be <c>null</c> or empty.
+        /// </summary>
+        public List<ulong> UserIds { get; set; }
+
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="AllowedMentions"/> class.
+        /// </summary>
+        /// <param name="allowedTypes">
+        ///     The types of mentions to parse from the message content.
+        ///     If <c>null</c>, only the ids specified in <see cref="UserIds"/> and <see cref="RoleIds"/> will be mentioned.
+        /// </param>
+        public AllowedMentions(AllowedMentionTypes? allowedTypes = null)
+        {
+            AllowedTypes = allowedTypes;
+        }
+    }
+}

src/Discord.Net.Core/Extensions/UserExtensions.cs

@@ -28,16 +28,21 @@ public static class UserExtensions
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
         /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="allowedMentions">
+        ///     Specifies if notifications are sent for mentioned users and roles in the message <paramref name="text"/>.
+        ///     If <c>null</c>, all mentioned roles and users will be notified.
+        /// </param>
         /// <returns>
         ///     A task that represents the asynchronous send operation. The task result contains the sent message.
         /// </returns>
         public static async Task<IUserMessage> SendMessageAsync(this IUser user,
             string text = null,
             bool isTTS = false,
             Embed embed = null,
-            RequestOptions options = null)
+            RequestOptions options = null,
+            AllowedMentions allowedMentions = null)
         {
-            return await (await user.GetOrCreateDMChannelAsync().ConfigureAwait(false)).SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false);
+            return await (await user.GetOrCreateDMChannelAsync().ConfigureAwait(false)).SendMessageAsync(text, isTTS, embed, options, allowedMentions).ConfigureAwait(false);
         }
 
         /// <summary>

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

@@ -54,5 +54,7 @@ internal class Message
         public Optional<MessageReference> Reference { get; set; }
         [JsonProperty("flags")]
         public Optional<MessageFlags> Flags { get; set; }
+        [JsonProperty("allowed_mentions")]
+        public Optional<AllowedMentions> AllowedMentions { get; set; }
     }
 }

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

@@ -1,4 +1,4 @@
-#pragma warning disable CS1591
+#pragma warning disable CS1591
 using Newtonsoft.Json;
 
 namespace Discord.API.Rest
@@ -15,6 +15,8 @@ internal class CreateMessageParams
         public Optional<bool> IsTTS { get; set; }
         [JsonProperty("embed")]
         public Optional<Embed> Embed { get; set; }
+        [JsonProperty("allowed_mentions")]
+        public Optional<AllowedMentions> AllowedMentions { get; set; }
 
         public CreateMessageParams(string content)
         {

src/Discord.Net.Rest/Entities/Channels/ChannelHelper.cs

@@ -167,9 +167,28 @@ public static async Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsyn
 
         /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
         public static async Task<RestUserMessage> SendMessageAsync(IMessageChannel channel, BaseDiscordClient client,
-            string text, bool isTTS, Embed embed, RequestOptions options)
+            string text, bool isTTS, Embed embed, AllowedMentions allowedMentions, RequestOptions options)
         {
-            var args = new CreateMessageParams(text) { IsTTS = isTTS, Embed = embed?.ToModel() };
+            Preconditions.AtMost(allowedMentions?.RoleIds?.Count ?? 0, 100, nameof(allowedMentions.RoleIds), "A max of 100 role Ids are allowed.");
+            Preconditions.AtMost(allowedMentions?.UserIds?.Count ?? 0, 100, nameof(allowedMentions.UserIds), "A max of 100 user Ids are allowed.");
+
+            // check that user flag and user Id list are exclusive, same with role flag and role Id list
+            if (allowedMentions != null && allowedMentions.AllowedTypes.HasValue)
+            {
+                if (allowedMentions.AllowedTypes.Value.HasFlag(AllowedMentionTypes.Users) &&
+                    allowedMentions.UserIds != null && allowedMentions.UserIds.Count > 0)
+                {
+                    throw new ArgumentException("The Users flag is mutually exclusive with the list of User Ids.", nameof(allowedMentions));
+                }
+
+                if (allowedMentions.AllowedTypes.Value.HasFlag(AllowedMentionTypes.Roles) &&
+                    allowedMentions.RoleIds != null && allowedMentions.RoleIds.Count > 0)
+                {
+                    throw new ArgumentException("The Roles flag is mutually exclusive with the list of Role Ids.", nameof(allowedMentions));
+                }
+            }
+
+            var args = new CreateMessageParams(text) { IsTTS = isTTS, Embed = embed?.ToModel(), AllowedMentions = allowedMentions?.ToModel() };
             var model = await client.ApiClient.CreateMessageAsync(channel.Id, args, options).ConfigureAwait(false);
             return RestUserMessage.Create(client, channel, client.CurrentUser, model);
         }

src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs

@@ -20,11 +20,15 @@ public interface IRestMessageChannel : IMessageChannel
         /// <param name="isTTS">Determines whether the message should be read aloud by Discord or not.</param>
         /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="allowedMentions">
+        ///     Specifies if notifications are sent for mentioned users and roles in the message <paramref name="text"/>.
+        ///     If <c>null</c>, all mentioned roles and users will be notified.
+        /// </param>
         /// <returns>
         ///     A task that represents an asynchronous send operation for delivering the message. The task result
         ///     contains the sent message.
         /// </returns>
-        new Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
+        new Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null);
         /// <summary>
         ///     Sends a file to this message channel with an optional caption.
         /// </summary>

src/Discord.Net.Rest/Entities/Channels/RestDMChannel.cs

@@ -93,8 +93,8 @@ public Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOpti
 
         /// <inheritdoc />
         /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
-        public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null)
-            => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, options);
+        public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null)
+            => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, allowedMentions, options);
 
         /// <inheritdoc />
         /// <exception cref="ArgumentException">
@@ -206,8 +206,8 @@ async Task<IUserMessage> IMessageChannel.SendFileAsync(string filePath, string t
         async Task<IUserMessage> IMessageChannel.SendFileAsync(Stream stream, string filename, string text, bool isTTS, Embed embed, RequestOptions options, bool isSpoiler)
             => await SendFileAsync(stream, filename, text, isTTS, embed, options, isSpoiler).ConfigureAwait(false);
         /// <inheritdoc />
-        async Task<IUserMessage> IMessageChannel.SendMessageAsync(string text, bool isTTS, Embed embed, RequestOptions options)
-            => await SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false);
+        async Task<IUserMessage> IMessageChannel.SendMessageAsync(string text, bool isTTS, Embed embed, RequestOptions options, AllowedMentions allowedMentions)
+            => await SendMessageAsync(text, isTTS, embed, options, allowedMentions).ConfigureAwait(false);
 
         //IChannel
         /// <inheritdoc />

src/Discord.Net.Rest/Entities/Channels/RestGroupChannel.cs

@@ -95,8 +95,8 @@ public Task DeleteMessageAsync(IMessage message, RequestOptions options = null)
 
         /// <inheritdoc />
         /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
-        public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null)
-            => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, options);
+        public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null)
+            => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, allowedMentions, options);
 
         /// <inheritdoc />
         /// <exception cref="ArgumentException">
@@ -183,8 +183,9 @@ async Task<IUserMessage> IMessageChannel.SendFileAsync(string filePath, string t
 
         async Task<IUserMessage> IMessageChannel.SendFileAsync(Stream stream, string filename, string text, bool isTTS, Embed embed, RequestOptions options, bool isSpoiler)
             => await SendFileAsync(stream, filename, text, isTTS, embed, options, isSpoiler).ConfigureAwait(false);
-        async Task<IUserMessage> IMessageChannel.SendMessageAsync(string text, bool isTTS, Embed embed, RequestOptions options)
-            => await SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false);
+
+        async Task<IUserMessage> IMessageChannel.SendMessageAsync(string text, bool isTTS, Embed embed, RequestOptions options, AllowedMentions allowedMentions)
+            => await SendMessageAsync(text, isTTS, embed, options, allowedMentions).ConfigureAwait(false);
 
         //IAudioChannel
         /// <inheritdoc />

src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs

@@ -101,8 +101,8 @@ public Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOpti
 
         /// <inheritdoc />
         /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
-        public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null)
-            => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, options);
+        public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null)
+            => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, allowedMentions, options);
 
         /// <inheritdoc />
         /// <exception cref="ArgumentException">
@@ -273,8 +273,8 @@ async Task<IUserMessage> IMessageChannel.SendFileAsync(string filePath, string t
         async Task<IUserMessage> IMessageChannel.SendFileAsync(Stream stream, string filename, string text, bool isTTS, Embed embed, RequestOptions options, bool isSpoiler)
             => await SendFileAsync(stream, filename, text, isTTS, embed, options, isSpoiler).ConfigureAwait(false);
         /// <inheritdoc />
-        async Task<IUserMessage> IMessageChannel.SendMessageAsync(string text, bool isTTS, Embed embed, RequestOptions options)
-            => await SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false);
+        async Task<IUserMessage> IMessageChannel.SendMessageAsync(string text, bool isTTS, Embed embed, RequestOptions options, AllowedMentions allowedMentions)
+            => await SendMessageAsync(text, isTTS, embed, options, allowedMentions).ConfigureAwait(false);
 
         //IGuildChannel
         /// <inheritdoc />

src/Discord.Net.Rest/Entities/Messages/AllowedMentions.cs

@@ -0,0 +1,15 @@
+using Newtonsoft.Json;
+
+namespace Discord.API
+{
+    public class AllowedMentions
+    {
+        [JsonProperty("parse")]
+        public Optional<string[]> Parse { get; set; }
+        // Roles and Users have a max size of 100
+        [JsonProperty("roles")]
+        public Optional<ulong[]> Roles { get; set; }
+        [JsonProperty("users")]
+        public Optional<ulong[]> Users { get; set; }
+    }
+}

src/Discord.Net.Rest/Extensions/EntityExtensions.cs

@@ -1,3 +1,4 @@
+using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Linq;
 
@@ -60,6 +61,24 @@ public static API.Embed ToModel(this Embed entity)
                 model.Video = entity.Video.Value.ToModel();
             return model;
         }
+        public static API.AllowedMentions ToModel(this AllowedMentions entity)
+        {
+            return new API.AllowedMentions()
+            {
+                Parse = entity.AllowedTypes?.EnumerateMentionTypes().ToArray(),
+                Roles = entity.RoleIds?.ToArray(),
+                Users = entity.UserIds?.ToArray(),
+            };
+        }
+        public static IEnumerable<string> EnumerateMentionTypes(this AllowedMentionTypes mentionTypes)
+        {
+            if (mentionTypes.HasFlag(AllowedMentionTypes.Everyone))
+                yield return "everyone";
+            if (mentionTypes.HasFlag(AllowedMentionTypes.Roles))
+                yield return "roles";
+            if (mentionTypes.HasFlag(AllowedMentionTypes.Users))
+                yield return "users";
+        }
         public static EmbedAuthor ToEntity(this API.EmbedAuthor model)
         {
             return new EmbedAuthor(model.Name, model.Url, model.IconUrl, model.ProxyIconUrl);