Onboarding updates (#2729)

src/Discord.Net.Core/DiscordErrorCode.cs

@@ -231,7 +231,7 @@ namespace Discord
         StickerAnimationDurationTooLong = 170007,
         #endregion
 
-        #region Guild Scheduled Events
+        #region Guild Scheduled Events (180XXX)
         CannotUpdateFinishedEvent = 180000,
         FailedStageCreation = 180002,
         #endregion
@@ -245,5 +245,10 @@ namespace Discord
         WebhookServicesCannotBeUsedInForumChannels = 220004,
         MessageBlockedByHarmfulLinksFilter = 240000,
         #endregion
+
+        #region Onboarding (350XXX)
+        CannotEnableOnboardingUnmetRequirements = 350000,
+        CannotUpdateOnboardingBelowRequirements = 350001
+        #endregion
     }
 }

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

@@ -1317,5 +1317,13 @@ namespace Discord
         ///     A task that represents the asynchronous creation operation. The task result contains the created <see cref="IGuildOnboarding"/>.
         /// </returns>
         Task<IGuildOnboarding> GetOnboardingAsync(RequestOptions options = null);
+
+        /// <summary>
+        ///     Modifies the onboarding object configured for the guild.
+        /// </summary>
+        /// <returns>
+        ///     A task that represents the asynchronous creation operation. The task result contains the modified <see cref="IGuildOnboarding"/>.
+        /// </returns>
+        Task<IGuildOnboarding> ModifyOnboardingAsync(Action<GuildOnboardingProperties> props, RequestOptions options = null);
     }
 }

src/Discord.Net.Core/Entities/Guilds/Onboarding/GuildOnboardingMode.cs

@@ -0,0 +1,17 @@
+namespace Discord;
+
+/// <summary>
+///     Defines the criteria used to satisfy Onboarding constraints that are required for enabling.
+/// </summary>
+public enum GuildOnboardingMode
+{
+    /// <summary>
+    ///     Counts only Default Channels towards constraints.
+    /// </summary>
+    Default = 0,
+
+    /// <summary>
+    ///     Counts Default Channels and Questions towards constraints.
+    /// </summary>
+    Advanced = 1,
+}

src/Discord.Net.Core/Entities/Guilds/Onboarding/GuildOnboardingPromptOptionProperties.cs

@@ -0,0 +1,40 @@
+using System.Collections.Generic;
+
+namespace Discord;
+
+/// <summary>
+///     Represents properties used to create or modify guild onboarding prompt option.
+/// </summary>
+public class GuildOnboardingPromptOptionProperties
+{
+    /// <summary>
+    ///     Gets or sets the Id of the prompt option. If the value is <see langword="null" /> a new prompt will be created.
+    ///     The existing one will be updated otherwise.
+    /// </summary>
+    public ulong? Id { get; set; }
+
+    /// <summary>
+    ///     Gets or set IDs for channels a member is added to when the option is selected.
+    /// </summary>
+    public ulong[] ChannelIds { get; set; }
+
+    /// <summary>
+    ///     Gets or sets IDs for roles assigned to a member when the option is selected.
+    /// </summary>
+    public ulong[] RoleIds { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the emoji of the option.
+    /// </summary>
+    public Optional<IEmote> Emoji { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the title of the option.
+    /// </summary>
+    public string Title { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the description of the option.
+    /// </summary>
+    public string Description { get; set; }
+}

src/Discord.Net.Core/Entities/Guilds/Onboarding/GuildOnboardingPromptProperties.cs

@@ -0,0 +1,45 @@
+using System.Collections.Generic;
+
+namespace Discord;
+
+/// <summary>
+///     Represents properties used to create or modify guild onboarding prompt.
+/// </summary>
+public class GuildOnboardingPromptProperties
+{
+    /// <summary>
+    ///     Gets or sets the Id of the prompt. If the value is <see langword="null" /> a new prompt will be created.
+    ///     The existing one will be updated otherwise.
+    /// </summary>
+    public ulong? Id { get; set; }
+
+    /// <summary>
+    ///     Gets or sets options available within the prompt.
+    /// </summary>
+    public GuildOnboardingPromptOptionProperties[] Options { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the title of the prompt.
+    /// </summary>
+    public string Title { get; set; }
+
+    /// <summary>
+    ///     Gets or sets whether users are limited to selecting one option for the prompt.
+    /// </summary>
+    public bool IsSingleSelect { get; set; }
+
+    /// <summary>
+    ///     Gets or sets whether the prompt is required before a user completes the onboarding flow.
+    /// </summary>
+    public bool IsRequired { get; set; }
+
+    /// <summary>
+    ///     Gets or sets whether the prompt is present in the onboarding flow. 
+    /// </summary>
+    public bool IsInOnboarding { get; set; }
+
+    /// <summary>
+    ///     Gets or set the type of the prompt.
+    /// </summary>
+    public GuildOnboardingPromptType Type { get; set; }
+}

src/Discord.Net.Core/Entities/Guilds/Onboarding/GuildOnboardingProperties.cs

@@ -0,0 +1,29 @@
+using System.Collections.Generic;
+
+namespace Discord;
+
+/// <summary>
+///     Represents properties used to create or modify guild onboarding.
+/// </summary>
+public class GuildOnboardingProperties
+{
+    /// <summary>
+    ///     Gets or sets prompts shown during onboarding and in customize community.
+    /// </summary>
+    public Optional<GuildOnboardingPromptProperties[]> Prompts { get; set; }
+
+    /// <summary>
+    ///     Gets or sets channel IDs that members get opted into automatically.
+    /// </summary>
+    public Optional<ulong[]> ChannelIds { get; set; }
+
+    /// <summary>
+    ///     Gets or sets whether onboarding is enabled in the guild.
+    /// </summary>
+    public Optional<bool> IsEnabled { get; set; }
+
+    /// <summary>
+    ///     Gets or sets current mode of onboarding.
+    /// </summary>
+    public Optional<GuildOnboardingMode> Mode { get; set;}
+}

src/Discord.Net.Core/Entities/Guilds/Onboarding/IGuildOnboarding.cs

@@ -1,4 +1,6 @@
+using System;
 using System.Collections.Generic;
+using System.Threading.Tasks;
 
 namespace Discord;
 
@@ -31,4 +33,19 @@ public interface IGuildOnboarding
     ///     Gets whether onboarding is enabled in the guild.
     /// </summary>
     bool IsEnabled { get; }
+
+    /// <summary>
+    ///     Gets the current mode of onboarding.
+    /// </summary>
+    GuildOnboardingMode Mode { get; }
+
+    /// <summary>
+    ///     Gets whether the server does not meet requirements to enable guild onboarding.
+    /// </summary>
+    bool IsBelowRequirements { get; }
+
+    /// <summary>
+    ///     Modifies the onboarding object.
+    /// </summary>
+    Task ModifyAsync(Action<GuildOnboardingProperties> props, RequestOptions options = null);
 }

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

@@ -0,0 +1,39 @@
+using System.Linq;
+
+namespace Discord;
+
+public static class GuildOnboardingExtensions
+{
+    public static GuildOnboardingProperties ToProperties(this IGuildOnboarding onboarding)
+        => new ()
+        {
+            ChannelIds = onboarding.DefaultChannelIds.ToArray(),
+            IsEnabled = onboarding.IsEnabled,
+            Mode = onboarding.Mode,
+            Prompts = onboarding.Prompts.Select(x => x.ToProperties()).ToArray(),
+        };
+
+    public static GuildOnboardingPromptProperties ToProperties(this IGuildOnboardingPrompt prompt)
+        => new()
+        {
+            Id = prompt.Id,
+            Type = prompt.Type,
+            IsInOnboarding = prompt.IsInOnboarding,
+            IsRequired = prompt.IsRequired,
+            IsSingleSelect = prompt.IsSingleSelect,
+            Title = prompt.Title,
+            Options = prompt.Options.Select(x => x.ToProperties()).ToArray()
+        };
+
+    public static GuildOnboardingPromptOptionProperties ToProperties(this IGuildOnboardingPromptOption option)
+        => new()
+        {
+            Title = option.Title,
+            ChannelIds = option.ChannelIds.ToArray(),
+            Description = option.Description,
+            Emoji = Optional.Create(option.Emoji),
+            Id = option.Id,
+            RoleIds = option.RoleIds.ToArray(),
+        };
+
+}

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

@@ -15,4 +15,10 @@ internal class GuildOnboarding
 
     [JsonProperty("enabled")]
     public bool Enabled { get; set; }
+
+    [JsonProperty("mode")]
+    public GuildOnboardingMode Mode { get; set; }
+
+    [JsonProperty("below_requirements")]
+    public bool IsBelowRequirements { get; set; }
 }

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

@@ -20,5 +20,5 @@ internal class GuildOnboardingPromptOption
     public string Title { get; set; }
 
     [JsonProperty("description")]
-    public Optional<string> Description { get; set; }
+    public string Description { get; set; }
 }

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

@@ -0,0 +1,71 @@
+using Newtonsoft.Json;
+
+namespace Discord.API.Rest;
+
+internal class ModifyGuildOnboardingParams
+{
+    [JsonProperty("prompts")]
+    public Optional<GuildOnboardingPromptParams[]> Prompts { get; set; }
+
+    [JsonProperty("default_channel_ids")]
+    public Optional<ulong[]> DefaultChannelIds { get; set; }
+
+    [JsonProperty("enabled")]
+    public Optional<bool> Enabled { get; set; }
+
+    [JsonProperty("mode")]
+    public Optional<GuildOnboardingMode> Mode { get; set; }
+}
+
+
+internal class GuildOnboardingPromptParams
+{
+    [JsonProperty("id")]
+    public ulong Id { get; set; }
+
+    [JsonProperty("options")]
+    public GuildOnboardingPromptOptionParams[] Options { get; set; }
+
+    [JsonProperty("title")]
+    public string Title { get; set; }
+
+    [JsonProperty("single_select")]
+    public bool IsSingleSelect { get; set; }
+
+    [JsonProperty("required")]
+    public bool IsRequired { get; set; }
+
+    [JsonProperty("in_onboarding")]
+    public bool IsInOnboarding { get; set; }
+
+    [JsonProperty("type")]
+    public GuildOnboardingPromptType Type { get; set; }
+}
+
+
+internal class GuildOnboardingPromptOptionParams
+{
+    [JsonProperty("id")]
+    public Optional<ulong> Id { get; set; }
+
+    [JsonProperty("channel_ids")]
+    public ulong[] ChannelIds { get; set; }
+
+    [JsonProperty("role_ids")]
+    public ulong[] RoleIds { get; set; }
+
+    [JsonProperty("emoji_name")]
+    public string EmojiName { get; set; }
+
+    [JsonProperty("emoji_id")]
+    public ulong? EmojiId { get; set; }
+
+    [JsonProperty("emoji_animated")]
+    public bool? EmojiAnimated { get; set; }
+
+    [JsonProperty("title")]
+    public string Title { get; set; }
+
+    [JsonProperty("description")]
+    public string Description { get; set; }
+}

src/Discord.Net.Rest/DiscordRestApiClient.cs

@@ -2252,6 +2252,15 @@ namespace Discord.API
             return await SendAsync<GuildOnboarding>("GET", () => $"guilds/{guildId}/onboarding", new BucketIds(guildId: guildId), options: options);
         }
 
+        public async Task<GuildOnboarding> ModifyGuildOnboardingAsync(ulong guildId, ModifyGuildOnboardingParams args,  RequestOptions options)
+        {
+            Preconditions.NotEqual(guildId, 0, nameof(guildId));
+
+            options = RequestOptions.CreateOrClone(options);
+
+            return await SendJsonAsync<GuildOnboarding>("PUT", () => $"guilds/{guildId}/onboarding", args, new BucketIds(guildId: guildId), options: options);
+        }
+
         #endregion
 
         #region Users

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

@@ -1,11 +1,13 @@
 using Discord.API;
 using Discord.API.Rest;
+
 using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.IO;
 using System.Linq;
 using System.Threading.Tasks;
+
 using ImageModel = Discord.API.Image;
 using Model = Discord.API.Guild;
 using RoleModel = Discord.API.Role;
@@ -1125,7 +1127,7 @@ namespace Discord.Rest
             }
 
             if (args.TriggerType.Value is AutoModTriggerType.Keyword)
-                Preconditions.AtLeast(args.KeywordFilter.GetValueOrDefault(Array.Empty<string>()).Length + args.RegexPatterns.GetValueOrDefault(Array.Empty<string>()).Length, 1, "KeywordFilter & RegexPatterns","Auto moderation rule must have at least 1 keyword or regex pattern");
+                Preconditions.AtLeast(args.KeywordFilter.GetValueOrDefault(Array.Empty<string>()).Length + args.RegexPatterns.GetValueOrDefault(Array.Empty<string>()).Length, 1, "KeywordFilter & RegexPatterns", "Auto moderation rule must have at least 1 keyword or regex pattern");
 
             if (args.AllowList.IsSpecified)
             {
@@ -1264,6 +1266,46 @@ namespace Discord.Rest
         public static async Task<GuildOnboarding> GetGuildOnboardingAsync(IGuild guild, BaseDiscordClient client, RequestOptions options)
             => await client.ApiClient.GetGuildOnboardingAsync(guild.Id, options);
 
+        public static async Task<GuildOnboarding> ModifyGuildOnboardingAsync(IGuild guild, Action<GuildOnboardingProperties> func, BaseDiscordClient client, RequestOptions options)
+        {
+            var props = new GuildOnboardingProperties();
+            func(props);
+
+            var args = new ModifyGuildOnboardingParams
+            {
+                DefaultChannelIds = props.ChannelIds.IsSpecified
+                    ? props.ChannelIds.Value.ToArray()
+                    : Optional<ulong[]>.Unspecified,
+                Enabled = props.IsEnabled,
+                Mode = props.Mode,
+                Prompts = props.Prompts.IsSpecified ? props.Prompts.Value?
+                    .Select(prompt => new GuildOnboardingPromptParams
+                    {
+                        Id = prompt.Id ?? 0,
+                        Type = prompt.Type,
+                        IsInOnboarding = prompt.IsInOnboarding,
+                        IsRequired = prompt.IsRequired,
+                        IsSingleSelect = prompt.IsSingleSelect,
+                        Title = prompt.Title,
+                        Options = prompt.Options?
+                            .Select(option => new GuildOnboardingPromptOptionParams
+                            {
+                                Title = option.Title,
+                                ChannelIds = option.ChannelIds?.ToArray(),
+                                RoleIds = option.RoleIds?.ToArray(),
+                                Description = option.Description,
+                                EmojiName = option.Emoji.GetValueOrDefault(null)?.Name,
+                                EmojiId = option.Emoji.GetValueOrDefault(null) is Emote emote ? emote.Id : null,
+                                EmojiAnimated = option.Emoji.GetValueOrDefault(null) is Emote emt ? emt.Animated : null,
+                                Id = option.Id ?? Optional<ulong>.Unspecified,
+                            }).ToArray(),
+                    }).ToArray()
+                : Optional<GuildOnboardingPromptParams[]>.Unspecified,
+            };
+
+            return await client.ApiClient.ModifyGuildOnboardingAsync(guild.Id, args, options);
+        }
+
         #endregion
     }
 }

src/Discord.Net.Rest/Entities/Guilds/Onboarding/RestGuildOnboarding.cs

@@ -2,6 +2,7 @@ using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Linq;
+using System.Threading.Tasks;
 using Model = Discord.API.GuildOnboarding;
 
 namespace Discord.Rest;
@@ -9,6 +10,8 @@ namespace Discord.Rest;
 /// <inheritdoc />
 public class RestGuildOnboarding : IGuildOnboarding
 {
+    internal BaseDiscordClient Discord;
+
     /// <inheritdoc />
     public ulong GuildId { get; private set; }
 
@@ -21,17 +24,38 @@ public class RestGuildOnboarding : IGuildOnboarding
     /// <inheritdoc />
     public bool IsEnabled { get; private set; }
 
+    /// <inheritdoc />
+    public GuildOnboardingMode Mode { get; private set; }
+
+    /// <inheritdoc />
+    public bool IsBelowRequirements { get; private set; }
+
     /// <inheritdoc cref="IGuildOnboarding.Prompts"/>
     public IReadOnlyCollection<RestGuildOnboardingPrompt> Prompts { get; private set; }
 
     internal RestGuildOnboarding(BaseDiscordClient discord, Model model, RestGuild guild = null)
+    {
+        Discord = discord;
+        Guild = guild;
+        Update(model);
+    }
+
+    internal void Update(Model model)
     {
         GuildId = model.GuildId;
         DefaultChannelIds = model.DefaultChannelIds.ToImmutableArray();
         IsEnabled = model.Enabled;
+        Mode = model.Mode;
+        IsBelowRequirements = model.IsBelowRequirements;
+        Prompts = model.Prompts.Select(prompt => new RestGuildOnboardingPrompt(Discord, prompt.Id, prompt)).ToImmutableArray();
+    }
 
-        Guild = guild;
+    ///<inheritdoc/>
-        Prompts = model.Prompts.Select(prompt => new RestGuildOnboardingPrompt(discord, prompt.Id, prompt)).ToImmutableArray();
+    public async Task ModifyAsync(Action<GuildOnboardingProperties> props, RequestOptions options = null)
+    {
+        var model = await GuildHelper.ModifyGuildOnboardingAsync(Guild, props, Discord, options);
+
+        Update(model);
     }
 
     #region IGuildOnboarding

src/Discord.Net.Rest/Entities/Guilds/Onboarding/RestGuildOnboardingPromptOption.cs

@@ -32,7 +32,7 @@ public class RestGuildOnboardingPromptOption : RestEntity<ulong>, IGuildOnboardi
         ChannelIds = model.ChannelIds.ToImmutableArray();
         RoleIds = model.RoleIds.ToImmutableArray();
         Title = model.Title;
-        Description = model.Description.IsSpecified ? model.Description.Value : null;
+        Description = model.Description;
         
         if (model.Emoji.Id.HasValue)
         {

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

@@ -1246,6 +1246,14 @@ namespace Discord.Rest
             return new RestGuildOnboarding(Discord, model, this);
         }
 
+        /// <inheritdoc cref="IGuild.ModifyOnboardingAsync"/>
+        public async Task<RestGuildOnboarding> ModifyOnboardingAsync(Action<GuildOnboardingProperties> props, RequestOptions options = null)
+        {
+            var model = await GuildHelper.ModifyGuildOnboardingAsync(this, props, Discord, options);
+
+            return new RestGuildOnboarding(Discord, model, this);
+        }
+
         #endregion
 
         #region IGuild
@@ -1609,6 +1617,10 @@ namespace Discord.Rest
         async Task<IGuildOnboarding> IGuild.GetOnboardingAsync(RequestOptions options)
             => await GetOnboardingAsync(options);
 
+        /// <inheritdoc/>
+        async Task<IGuildOnboarding> IGuild.ModifyOnboardingAsync(Action<GuildOnboardingProperties> props, RequestOptions options)
+            => await ModifyOnboardingAsync(props, options);
+
         #endregion
     }
 }

src/Discord.Net.WebSocket/Entities/Guilds/Onboarding/SocketGuildOnboarding.cs

@@ -1,6 +1,9 @@
+using Discord.Rest;
+using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Linq;
+using System.Threading.Tasks;
 using Model = Discord.API.GuildOnboarding;
 
 namespace Discord.WebSocket;
@@ -8,6 +11,8 @@ namespace Discord.WebSocket;
 /// <inheritdoc />
 public class SocketGuildOnboarding : IGuildOnboarding
 {
+    internal DiscordSocketClient Discord;
+
     /// <inheritdoc />
     public ulong GuildId { get; private set; }
 
@@ -28,17 +33,38 @@ public class SocketGuildOnboarding : IGuildOnboarding
     /// <inheritdoc />
     public bool IsEnabled { get; private set; }
 
+    /// <inheritdoc />
+    public bool IsBelowRequirements { get; private set; }
+
+    /// <inheritdoc />
+    public GuildOnboardingMode Mode { get; private set; }
+
     internal SocketGuildOnboarding(DiscordSocketClient discord, Model model, SocketGuild guild)
     {
-        GuildId = model.GuildId;
+        Discord = discord;
         Guild = guild;
+        Update(model);
+    }
+
+    internal void Update(Model model)
+    {
+        GuildId = model.GuildId;
         IsEnabled = model.Enabled;
+        Mode = model.Mode;
+        IsBelowRequirements = model.IsBelowRequirements;
 
         DefaultChannelIds = model.DefaultChannelIds;
+        DefaultChannels = model.DefaultChannelIds.Select(Guild.GetChannel).ToImmutableArray();
 
-        DefaultChannels = model.DefaultChannelIds.Select(guild.GetChannel).ToImmutableArray();
+        Prompts = model.Prompts.Select(x => new SocketGuildOnboardingPrompt(Discord, x.Id, x, Guild)).ToImmutableArray();
-        Prompts = model.Prompts.Select(x => new SocketGuildOnboardingPrompt(discord, x.Id, x, guild)).ToImmutableArray();
+    }
 
+    ///<inheritdoc/>
+    public async Task ModifyAsync(Action<GuildOnboardingProperties> props, RequestOptions options = null)
+    {
+        var model = await GuildHelper.ModifyGuildOnboardingAsync(Guild, props, Discord, options);
+
+        Update(model);
     }
 
     #region IGuildOnboarding

src/Discord.Net.WebSocket/Entities/Guilds/Onboarding/SocketGuildOnboardingPromptOption.cs

@@ -43,7 +43,7 @@ public class SocketGuildOnboardingPromptOption : SocketEntity<ulong>, IGuildOnbo
         ChannelIds = model.ChannelIds.ToImmutableArray();
         RoleIds = model.RoleIds.ToImmutableArray();
         Title = model.Title;
-        Description = model.Description.IsSpecified ? model.Description.Value : null;
+        Description = model.Description;
 
         if (model.Emoji.Id.HasValue)
         {

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

@@ -1950,6 +1950,14 @@ namespace Discord.WebSocket
             return new SocketGuildOnboarding(Discord, model, this);
         }
 
+        /// <inheritdoc cref="IGuild.ModifyOnboardingAsync"/>
+        public async Task<SocketGuildOnboarding> ModifyOnboardingAsync(Action<GuildOnboardingProperties> props, RequestOptions options = null)
+        {
+            var model = await GuildHelper.ModifyGuildOnboardingAsync(this, props, Discord, options);
+
+            return new SocketGuildOnboarding(Discord, model, this);
+        }
+
         #endregion
 
         #region  IGuild
@@ -2214,6 +2222,10 @@ namespace Discord.WebSocket
         async Task<IGuildOnboarding> IGuild.GetOnboardingAsync(RequestOptions options)
             => await GetOnboardingAsync(options);
 
+        /// <inheritdoc/>
+        async Task<IGuildOnboarding> IGuild.ModifyOnboardingAsync(Action<GuildOnboardingProperties> props, RequestOptions options)
+            => await ModifyOnboardingAsync(props, options);
+
         #endregion
     }
 }