[Feature] Scheduled event recurrence rule (#3023)

* api modelsssssssss

* recurrence rulesssss

src/Discord.Net.Core/Entities/GuildScheduledEvents/GuildScheduledEventPrivacyLevel.cs

@@ -0,0 +1,20 @@
+using System;
+
+namespace Discord;
+
+/// <summary>
+///     Represents the privacy level of a guild scheduled event.
+/// </summary>
+public enum GuildScheduledEventPrivacyLevel
+{
+    /// <summary>
+    ///     The scheduled event is public and available in discovery.
+    /// </summary>
+    [Obsolete("This event type isn't supported yet! check back later.", true)]
+    Public = 1,
+
+    /// <summary>
+    ///     The scheduled event is only accessible to guild members.
+    /// </summary>
+    Private = 2,
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/GuildScheduledEventRecurrenceRule.cs

@@ -0,0 +1,76 @@
+using System;
+using System.Collections.Generic;
+
+namespace Discord;
+
+public readonly struct GuildScheduledEventRecurrenceRule
+{
+    /// <summary>
+    ///     Gets the starting time of the recurrence interval.
+    /// </summary>
+    public DateTimeOffset StartsAt { get; }
+
+    /// <summary>
+    ///     Gets the ending time of the recurrence interval.
+    /// </summary>
+    public DateTimeOffset? EndsAt { get; }
+
+    /// <summary>
+    ///     Gets how often the event occurs.
+    /// </summary>
+    public RecurrenceFrequency Frequency { get; }
+
+    /// <summary>
+    ///     Gets the spacing between the events, defined by <see cref="Frequency"/>. 
+    /// </summary>
+    public int Interval { get; }
+
+    /// <summary>
+    ///     Gets the set of specific days within a week for the event to recur on.
+    /// </summary>
+    public IReadOnlyCollection<RecurrenceRuleWeekday> ByWeekday { get; }
+
+    /// <summary>
+    ///     Gets the list of specific days within a specific week to recur on.
+    /// </summary>
+    public IReadOnlyCollection<RecurrenceRuleByNWeekday> ByNWeekday { get; }
+
+    /// <summary>
+    ///     Gets the set of specific months to recur on.
+    /// </summary>
+    public IReadOnlyCollection<RecurrenceRuleMonth> ByMonth { get; }
+
+    /// <summary>
+    ///     Gets the set of specific dates within a month to recur on.
+    /// </summary>
+    public IReadOnlyCollection<int> ByMonthDay { get; }
+
+    /// <summary>
+    ///     Gets the set of days within a year to recur on. (1-364)
+    /// </summary>
+    public IReadOnlyCollection<int> ByYearDay { get; }
+
+    /// <summary>
+    ///     Gets the total amount of times that the event is allowed to recur before stopping.
+    /// </summary>
+    /// <remarks>
+    ///     <see langword="null"/> if the event recurs endlessly.
+    /// </remarks>
+    public int? Count { get; }
+
+    internal GuildScheduledEventRecurrenceRule(DateTimeOffset startsAt, DateTimeOffset? endsAt, RecurrenceFrequency frequency,
+        int interval, IReadOnlyCollection<RecurrenceRuleWeekday> byWeekday, IReadOnlyCollection<RecurrenceRuleByNWeekday> byNWeekday,
+        IReadOnlyCollection<RecurrenceRuleMonth> byMonth, IReadOnlyCollection<int> byMonthDay, IReadOnlyCollection<int> byYearDay, int? count)
+    {
+        StartsAt = startsAt;
+        EndsAt = endsAt;
+        Frequency = frequency;
+        Interval = interval;
+        ByWeekday = byWeekday;
+        ByNWeekday = byNWeekday;
+        ByMonth = byMonth;
+        ByMonthDay = byMonthDay;
+        ByYearDay = byYearDay;
+        Count = count;
+    }
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/GuildScheduledEventRecurrenceRuleProperties.cs

@@ -0,0 +1,59 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Discord;
+
+public class GuildScheduledEventRecurrenceRuleProperties
+{
+    /// <summary>
+    ///     Gets or sets the starting time of the recurrence interval.
+    /// </summary>
+    public DateTimeOffset StartsAt { get; set; }
+
+    /// <summary>
+    ///     Gets or sets how often the event occurs.
+    /// </summary>
+    public RecurrenceFrequency Frequency { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the spacing between the events, defined by <see cref="Frequency"/>. 
+    /// </summary>
+    public int Interval { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the set of specific days within a week for the event to recur on.
+    /// </summary>
+    public HashSet<RecurrenceRuleWeekday> ByWeekday { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the list of specific days within a specific week to recur on.
+    /// </summary>
+    public List<RecurrenceRuleByNWeekday> ByNWeekday { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the set of specific months to recur on.
+    /// </summary>
+    public HashSet<RecurrenceRuleMonth> ByMonth { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the set of specific dates within a month to recur on.
+    /// </summary>
+    public HashSet<int> ByMonthDay { get; set; }
+
+
+    public GuildScheduledEventRecurrenceRuleProperties() {}
+
+    public GuildScheduledEventRecurrenceRuleProperties(DateTimeOffset startsAt, RecurrenceFrequency frequency,
+        int interval, HashSet<RecurrenceRuleWeekday> byWeekday, IEnumerable<RecurrenceRuleByNWeekday> byNWeekday,
+        HashSet<RecurrenceRuleMonth> byMonth, HashSet<int> byMonthDay)
+    {
+        StartsAt = startsAt;
+        Frequency = frequency;
+        Interval = interval;
+        ByWeekday = byWeekday;
+        ByNWeekday = byNWeekday?.ToList();
+        ByMonth = byMonth;
+        ByMonthDay = byMonthDay;
+    }
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/GuildScheduledEventsProperties.cs

@@ -1,8 +1,4 @@
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Discord
 {
@@ -59,5 +55,10 @@ namespace Discord
         ///     Gets or sets the banner image of the event.
         /// </summary>
         public Optional<Image?> CoverImage { get; set; }
+
+        /// <summary>
+        ///     Gets or sets the definition for how often this event should recur.
+        /// </summary>
+        public Optional<GuildScheduledEventRecurrenceRuleProperties> RecurrenceRule { get; set; }
     }
 }

src/Discord.Net.Core/Entities/GuildScheduledEvents/IGuildScheduledEvent.cs

@@ -1,7 +1,5 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 using System.Threading.Tasks;
 
 namespace Discord
@@ -90,6 +88,11 @@ namespace Discord
         /// </summary>
         int? UserCount { get; }
 
+        /// <summary>
+        ///     Gets the definition for how often this event should recur. <cref langword="null"/> if not set.
+        /// </summary>
+        GuildScheduledEventRecurrenceRule? RecurrenceRule { get; }
+
         /// <summary>
         ///     Gets this events banner image url.
         /// </summary>

src/Discord.Net.Core/Entities/GuildScheduledEvents/RecurrenceFrequency.cs

@@ -0,0 +1,12 @@
+namespace Discord;
+
+public enum RecurrenceFrequency
+{
+    Yearly = 0,
+
+    Monthly = 1,
+
+    Weekly = 2,
+
+    Daily = 3
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/RecurrenceRuleByNWeekday.cs

@@ -0,0 +1,20 @@
+namespace Discord;
+
+public readonly struct RecurrenceRuleByNWeekday
+{
+    /// <summary>
+    ///     Gets the week to reoccur on. (from 1 to 5)
+    /// </summary>
+    public int Week { get; }
+
+    /// <summary>
+    ///     Gets the day within a week to reoccur on.
+    /// </summary>
+    public RecurrenceRuleWeekday Day { get; }
+
+    internal RecurrenceRuleByNWeekday(int week, RecurrenceRuleWeekday day)
+    {
+        Week = week;
+        Day = day;
+    }
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/RecurrenceRuleByNWeekdayProperties.cs

@@ -0,0 +1,22 @@
+namespace Discord;
+
+public class RecurrenceRuleByNWeekdayProperties
+{
+    /// <summary>
+    ///     Gets or sets the week to reoccur on. (from 1 to 5)
+    /// </summary>
+    public int Week { get; set; }
+
+    /// <summary>
+    ///     Gets or sets the day within a week to reoccur on.
+    /// </summary>
+    public RecurrenceRuleWeekday Day { get; set; }
+
+    public RecurrenceRuleByNWeekdayProperties() {}
+
+    public RecurrenceRuleByNWeekdayProperties(int week, RecurrenceRuleWeekday day)
+    {
+        Week = week;
+        Day = day;
+    }
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/RecurrenceRuleMonth.cs

@@ -0,0 +1,28 @@
+namespace Discord;
+
+public enum RecurrenceRuleMonth
+{
+    January = 1,
+
+    February = 2,
+
+    March = 3,
+
+    April = 4,
+
+    May = 5,
+
+    June = 6,
+
+    July = 7,
+
+    August = 8,
+
+    September = 9,
+
+    October = 10,
+
+    November = 11,
+
+    December = 12
+}

src/Discord.Net.Core/Entities/GuildScheduledEvents/RecurrenceRuleWeekday.cs

@@ -0,0 +1,18 @@
+namespace Discord;
+
+public enum RecurrenceRuleWeekday
+{
+    Monday = 0,
+
+    Tuesday = 1,
+
+    Wednesday = 2,
+
+    Thursday = 3,
+
+    Friday = 4,
+
+    Saturday = 5,
+
+    Sunday = 6
+}

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

@@ -1,25 +0,0 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
-
-namespace Discord
-{
-    /// <summary>
-    ///     Represents the privacy level of a guild scheduled event.
-    /// </summary>
-    public enum GuildScheduledEventPrivacyLevel
-    {
-        /// <summary>
-        ///     The scheduled event is public and available in discovery.
-        /// </summary>
-        [Obsolete("This event type isn't supported yet! check back later.", true)]
-        Public = 1,
-
-        /// <summary>
-        ///     The scheduled event is only accessible to guild members.
-        /// </summary>
-        Private = 2,
-    }
-}

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

@@ -2,41 +2,57 @@ using Newtonsoft.Json;
 
 using System;
 
-namespace Discord.API
+namespace Discord.API;
+
+internal class GuildScheduledEvent
 {
-    internal class GuildScheduledEvent
+    [JsonProperty("id")]
-    {
+    public ulong Id { get; set; }
-        [JsonProperty("id")]
+
-        public ulong Id { get; set; }
+    [JsonProperty("guild_id")]
-        [JsonProperty("guild_id")]
+    public ulong GuildId { get; set; }
-        public ulong GuildId { get; set; }
+
-        [JsonProperty("channel_id")]
+    [JsonProperty("channel_id")]
-        public Optional<ulong?> ChannelId { get; set; }
+    public Optional<ulong?> ChannelId { get; set; }
-        [JsonProperty("creator_id")]
+
-        public Optional<ulong?> CreatorId { get; set; }
+    [JsonProperty("creator_id")]
-        [JsonProperty("name")]
+    public Optional<ulong?> CreatorId { get; set; }
-        public string Name { get; set; }
+
-        [JsonProperty("description")]
+    [JsonProperty("name")]
-        public Optional<string> Description { get; set; }
+    public string Name { get; set; }
-        [JsonProperty("scheduled_start_time")]
+
-        public DateTimeOffset ScheduledStartTime { get; set; }
+    [JsonProperty("description")]
-        [JsonProperty("scheduled_end_time")]
+    public Optional<string> Description { get; set; }
-        public DateTimeOffset? ScheduledEndTime { get; set; }
+
-        [JsonProperty("privacy_level")]
+    [JsonProperty("scheduled_start_time")]
-        public GuildScheduledEventPrivacyLevel PrivacyLevel { get; set; }
+    public DateTimeOffset ScheduledStartTime { get; set; }
-        [JsonProperty("status")]
+
-        public GuildScheduledEventStatus Status { get; set; }
+    [JsonProperty("scheduled_end_time")]
-        [JsonProperty("entity_type")]
+    public DateTimeOffset? ScheduledEndTime { get; set; }
-        public GuildScheduledEventType EntityType { get; set; }
+
-        [JsonProperty("entity_id")]
+    [JsonProperty("privacy_level")]
-        public ulong? EntityId { get; set; }
+    public GuildScheduledEventPrivacyLevel PrivacyLevel { get; set; }
-        [JsonProperty("entity_metadata")]
+
-        public GuildScheduledEventEntityMetadata EntityMetadata { get; set; }
+    [JsonProperty("status")]
-        [JsonProperty("creator")]
+    public GuildScheduledEventStatus Status { get; set; }
-        public Optional<User> Creator { get; set; }
+
-        [JsonProperty("user_count")]
+    [JsonProperty("entity_type")]
-        public Optional<int> UserCount { get; set; }
+    public GuildScheduledEventType EntityType { get; set; }
-        [JsonProperty("image")]
+
-        public string Image { get; set; }
+    [JsonProperty("entity_id")]
-    }
+    public ulong? EntityId { get; set; }
+    [JsonProperty("entity_metadata")]
+    public GuildScheduledEventEntityMetadata EntityMetadata { get; set; }
+
+    [JsonProperty("creator")]
+    public Optional<User> Creator { get; set; }
+
+    [JsonProperty("user_count")]
+    public Optional<int> UserCount { get; set; }
+
+    [JsonProperty("image")]
+    public string Image { get; set; }
+
+    [JsonProperty("recurrence_rule")]
+    public GuildScheduledEventRecurrenceRule RecurrenceRule { get; set; }
 }

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

@@ -0,0 +1,37 @@
+using Newtonsoft.Json;
+using System;
+
+namespace Discord.API;
+
+public class GuildScheduledEventRecurrenceRule
+{
+    [JsonProperty("start")]
+    public DateTimeOffset StartAt { get; set; }
+
+    [JsonProperty("end")]
+    public DateTimeOffset? EndAt { get; set; }
+
+    [JsonProperty("frequency")]
+    public RecurrenceFrequency Frequency { get; set; }
+
+    [JsonProperty("interval")]
+    public int Interval { get; set; }
+
+    [JsonProperty("by_weekday")]
+    public RecurrenceRuleWeekday[] ByWeekday { get; set; }
+
+    [JsonProperty("by_n_weekday")]
+    public GuildScheduledEventRecurrenceRuleByNWeekday[] ByNWeekday { get; set; }
+
+    [JsonProperty("by_month")]
+    public RecurrenceRuleMonth[] ByMonth { get; set; }
+
+    [JsonProperty("by_month_day")]
+    public int[] ByMonthDay { get; set; }
+
+    [JsonProperty("by_year_day")]
+    public int[] ByYearDay { get; set; }
+
+    [JsonProperty("count")]
+    public int? Count { get; set; }
+}

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

@@ -0,0 +1,12 @@
+using Newtonsoft.Json;
+
+namespace Discord.API;
+
+public class GuildScheduledEventRecurrenceRuleByNWeekday
+{
+    [JsonProperty("n")]
+    public int WeekNumber { get; set; }
+
+    [JsonProperty("day")]
+    public RecurrenceRuleWeekday Day { get; set; }
+}

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

@@ -1,31 +1,37 @@
 using Newtonsoft.Json;
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
-namespace Discord.API.Rest
+namespace Discord.API.Rest;
+
+internal class CreateGuildScheduledEventParams
 {
-    internal class CreateGuildScheduledEventParams
+    [JsonProperty("channel_id")]
-    {
+    public Optional<ulong> ChannelId { get; set; }
-        [JsonProperty("channel_id")]
+
-        public Optional<ulong> ChannelId { get; set; }
+    [JsonProperty("entity_metadata")]
-        [JsonProperty("entity_metadata")]
+    public Optional<GuildScheduledEventEntityMetadata> EntityMetadata { get; set; }
-        public Optional<GuildScheduledEventEntityMetadata> EntityMetadata { get; set; }
+
-        [JsonProperty("name")]
+    [JsonProperty("name")]
-        public string Name { get; set; }
+    public string Name { get; set; }
-        [JsonProperty("privacy_level")]
+
-        public GuildScheduledEventPrivacyLevel PrivacyLevel { get; set; }
+    [JsonProperty("privacy_level")]
-        [JsonProperty("scheduled_start_time")]
+    public GuildScheduledEventPrivacyLevel PrivacyLevel { get; set; }
-        public DateTimeOffset StartTime { get; set; }
+
-        [JsonProperty("scheduled_end_time")]
+    [JsonProperty("scheduled_start_time")]
-        public Optional<DateTimeOffset> EndTime { get; set; }
+    public DateTimeOffset StartTime { get; set; }
-        [JsonProperty("description")]
+
-        public Optional<string> Description { get; set; }
+    [JsonProperty("scheduled_end_time")]
-        [JsonProperty("entity_type")]
+    public Optional<DateTimeOffset> EndTime { get; set; }
-        public GuildScheduledEventType Type { get; set; }
+
-        [JsonProperty("image")]
+    [JsonProperty("description")]
-        public Optional<Image> Image { get; set; }
+    public Optional<string> Description { get; set; }
-    }
+
+    [JsonProperty("entity_type")]
+    public GuildScheduledEventType Type { get; set; }
+
+    [JsonProperty("image")]
+    public Optional<Image> Image { get; set; }
+
+    [JsonProperty("recurrence_rule")]
+    public Optional<GuildScheduledEventRecurrenceRule> RecurrenceRule { get; set; }
 }

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

@@ -1,33 +1,40 @@
 using Newtonsoft.Json;
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
-namespace Discord.API.Rest
+namespace Discord.API.Rest;
+
+internal class ModifyGuildScheduledEventParams
 {
-    internal class ModifyGuildScheduledEventParams
+    [JsonProperty("channel_id")]
-    {
+    public Optional<ulong?> ChannelId { get; set; }
-        [JsonProperty("channel_id")]
+
-        public Optional<ulong?> ChannelId { get; set; }
+    [JsonProperty("entity_metadata")]
-        [JsonProperty("entity_metadata")]
+    public Optional<GuildScheduledEventEntityMetadata> EntityMetadata { get; set; }
-        public Optional<GuildScheduledEventEntityMetadata> EntityMetadata { get; set; }
+
-        [JsonProperty("name")]
+    [JsonProperty("name")]
-        public Optional<string> Name { get; set; }
+    public Optional<string> Name { get; set; }
-        [JsonProperty("privacy_level")]
+
-        public Optional<GuildScheduledEventPrivacyLevel> PrivacyLevel { get; set; }
+    [JsonProperty("privacy_level")]
-        [JsonProperty("scheduled_start_time")]
+    public Optional<GuildScheduledEventPrivacyLevel> PrivacyLevel { get; set; }
-        public Optional<DateTimeOffset> StartTime { get; set; }
+
-        [JsonProperty("scheduled_end_time")]
+    [JsonProperty("scheduled_start_time")]
-        public Optional<DateTimeOffset> EndTime { get; set; }
+    public Optional<DateTimeOffset> StartTime { get; set; }
-        [JsonProperty("description")]
+
-        public Optional<string> Description { get; set; }
+    [JsonProperty("scheduled_end_time")]
-        [JsonProperty("entity_type")]
+    public Optional<DateTimeOffset> EndTime { get; set; }
-        public Optional<GuildScheduledEventType> Type { get; set; }
+
-        [JsonProperty("status")]
+    [JsonProperty("description")]
-        public Optional<GuildScheduledEventStatus> Status { get; set; }
+    public Optional<string> Description { get; set; }
-        [JsonProperty("image")]
+
-        public Optional<Image?> Image { get; set; }
+    [JsonProperty("entity_type")]
-    }
+    public Optional<GuildScheduledEventType> Type { get; set; }
+
+    [JsonProperty("status")]
+    public Optional<GuildScheduledEventStatus> Status { get; set; }
+
+    [JsonProperty("image")]
+    public Optional<Image?> Image { get; set; }
+
+    [JsonProperty("recurrence_rule")]
+    public Optional<GuildScheduledEventRecurrenceRule> RecurrenceRule { get; set; }
 }

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

@@ -1273,6 +1273,55 @@ namespace Discord.Rest
                 }
             }
 
+            if (args.RecurrenceRule is { IsSpecified: true, Value: not null })
+            {
+                var rule = args.RecurrenceRule.Value;
+
+                var hasByWeekDay = rule.ByWeekday?.Any() ?? false;
+                var hasByNWeekDay = rule.ByNWeekday?.Any() ?? false;
+                var hasByMonth = (rule.ByMonthDay?.Any() ?? false) || (rule.ByMonth?.Any() ?? false);
+
+                if (hasByWeekDay && hasByNWeekDay ||
+                    hasByWeekDay && hasByMonth ||
+                    hasByNWeekDay && hasByMonth)
+                {
+                    throw new ArgumentException($"A recurrence rule can have one of ('{nameof(rule.ByWeekday)}', '{nameof(rule.ByNWeekday)}', '{nameof(rule.ByMonth)}' + '{nameof(rule.ByMonthDay)}'), but not a combination of them.");
+                }
+
+                if (hasByWeekDay)
+                {
+                    if (rule.Frequency is not RecurrenceFrequency.Daily and not RecurrenceFrequency.Weekly)
+                        throw new ArgumentException($"A {nameof(rule.ByWeekday)} rule can only be used with {nameof(rule.Frequency)} of 'Daily' or 'Weekly'.");
+
+                    if (rule.Frequency is RecurrenceFrequency.Weekly)
+                    {
+                        if (rule.ByWeekday.Count != 1)
+                            throw new ArgumentException("A 'Weekly' recurrence rule must have a single weekday selected.");
+
+                        if (rule.Interval == 1)
+                            throw new ArgumentException($"{nameof(rule.Interval)} can only be set to a value other than '1' when {nameof(rule.Frequency)} is set to 'Weekly'");
+                    }
+                }
+
+                if (hasByNWeekDay)
+                {
+                    if (rule.Frequency is not RecurrenceFrequency.Monthly)
+                        throw new ArgumentException($"A {rule.ByNWeekday} rule must have {nameof(rule.Frequency)} set to 'Monthly'.");
+
+                    if (rule.ByNWeekday.Count != 1)
+                        throw new ArgumentException($"A {rule.ByNWeekday} must have exactly one day selected.");
+                }
+
+                if (hasByMonth)
+                {
+                    if (rule.Frequency is not RecurrenceFrequency.Yearly)
+                        throw new ArgumentException($"A {rule.ByMonth} rule must have {nameof(rule.Frequency)} set to 'Yearly'.");
+
+                    if (rule.ByMonth?.Count is not 1 || rule.ByMonthDay?.Count is not 1)
+                        throw new ArgumentException($"A {rule.ByMonth} rule must have exactly 1 day and 1 month selected.");
+                }
+            }
+
             var apiArgs = new ModifyGuildScheduledEventParams()
             {
                 ChannelId = args.ChannelId,
@@ -1284,10 +1333,11 @@ namespace Discord.Rest
                 Status = args.Status,
                 Type = args.Type,
                 Image = args.CoverImage.IsSpecified
-                    ? args.CoverImage.Value.HasValue
+                    ? args.CoverImage.Value?.ToModel()
-                        ? args.CoverImage.Value.Value.ToModel()
+                    : Optional<ImageModel?>.Unspecified,
-                        : null
+                RecurrenceRule = args.RecurrenceRule.IsSpecified
-                    : Optional<ImageModel?>.Unspecified
+                    ? args.RecurrenceRule.Value?.ToModel()
+                    : Optional<API.GuildScheduledEventRecurrenceRule>.Unspecified
             };
 
             if (args.Location.IsSpecified)
@@ -1328,7 +1378,8 @@ namespace Discord.Rest
             ulong? channelId = null,
             string location = null,
             Image? bannerImage = null,
-            RequestOptions options = null)
+            RequestOptions options = null,
+            GuildScheduledEventRecurrenceRuleProperties recurrenceRule = null)
         {
             if (location != null)
             {
@@ -1353,6 +1404,53 @@ namespace Discord.Rest
             if (endTime != null && endTime <= startTime)
                 throw new ArgumentOutOfRangeException(nameof(endTime), $"{nameof(endTime)} cannot be before the start time");
 
+            if (recurrenceRule is not null)
+            {
+                var hasByWeekDay = recurrenceRule.ByWeekday?.Any() ?? false;
+                var hasByNWeekDay = recurrenceRule.ByNWeekday?.Any() ?? false;
+                var hasByMonth = (recurrenceRule.ByMonthDay?.Any() ?? false) || (recurrenceRule.ByMonth?.Any() ?? false);
+
+                if (hasByWeekDay && hasByNWeekDay ||
+                    hasByWeekDay && hasByMonth ||
+                    hasByNWeekDay && hasByMonth)
+                {
+                    throw new ArgumentException($"A recurrence rule can have one of ('{nameof(recurrenceRule.ByWeekday)}', '{nameof(recurrenceRule.ByNWeekday)}', '{nameof(recurrenceRule.ByMonth)}' + '{nameof(recurrenceRule.ByMonthDay)}'), but not a combination of them.");
+                }
+
+                if (hasByWeekDay)
+                {
+                    if (recurrenceRule.Frequency is not RecurrenceFrequency.Daily and not RecurrenceFrequency.Weekly)
+                        throw new ArgumentException($"A {nameof(recurrenceRule.ByWeekday)} rule can only be used with {nameof(recurrenceRule.Frequency)} of 'Daily' or 'Weekly'.");
+
+                    if (recurrenceRule.Frequency is RecurrenceFrequency.Weekly)
+                    {
+                        if (recurrenceRule.ByWeekday.Count != 1)
+                            throw new ArgumentException("A 'Weekly' recurrence rule must have a single weekday selected.");
+
+                        if (recurrenceRule.Interval == 1)
+                            throw new ArgumentException($"{nameof(recurrenceRule.Interval)} can only be set to a value other than '1' when {nameof(recurrenceRule.Frequency)} is set to 'Weekly'");
+                    }
+                }
+
+                if (hasByNWeekDay)
+                {
+                    if (recurrenceRule.Frequency is not RecurrenceFrequency.Monthly)
+                        throw new ArgumentException($"A {recurrenceRule.ByNWeekday} rule must have {nameof(recurrenceRule.Frequency)} set to 'Monthly'.");
+
+                    if (recurrenceRule.ByNWeekday.Count != 1)
+                        throw new ArgumentException($"A {recurrenceRule.ByNWeekday} must have exactly one day selected.");
+                }
+
+                if (hasByMonth)
+                {
+                    if (recurrenceRule.Frequency is not RecurrenceFrequency.Yearly)
+                        throw new ArgumentException($"A {recurrenceRule.ByMonth} rule must have {nameof(recurrenceRule.Frequency)} set to 'Yearly'.");
+
+                    if (recurrenceRule.ByMonth?.Count is not 1 || recurrenceRule.ByMonthDay?.Count is not 1)
+                        throw new ArgumentException($"A {recurrenceRule.ByMonth} rule must have exactly 1 day and 1 month selected.");
+                }
+            }
+
 
             var apiArgs = new CreateGuildScheduledEventParams()
             {
@@ -1363,7 +1461,8 @@ namespace Discord.Rest
                 PrivacyLevel = privacyLevel,
                 StartTime = startTime,
                 Type = type,
-                Image = bannerImage.HasValue ? bannerImage.Value.ToModel() : Optional<ImageModel>.Unspecified
+                Image = bannerImage?.ToModel() ?? Optional<ImageModel>.Unspecified,
+                RecurrenceRule = recurrenceRule?.ToModel() ?? Optional<API.GuildScheduledEventRecurrenceRule>.Unspecified
             };
 
             if (location != null)

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

@@ -1277,6 +1277,7 @@ namespace Discord.Rest
         /// <param name="location">The location of the event; links are supported</param>
         /// <param name="coverImage">The optional banner image for the event.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="recurrenceRule">The definition for how often this event should recur.</param>
         /// <returns>
         ///     A task that represents the asynchronous create operation.
         /// </returns>
@@ -1290,8 +1291,9 @@ namespace Discord.Rest
             ulong? channelId = null,
             string location = null,
             Image? coverImage = null,
-            RequestOptions options = null)
+            RequestOptions options = null,
-            => GuildHelper.CreateGuildEventAsync(Discord, this, name, privacyLevel, startTime, type, description, endTime, channelId, location, coverImage, options);
+            GuildScheduledEventRecurrenceRuleProperties recurrenceRule = null)
+            => GuildHelper.CreateGuildEventAsync(Discord, this, name, privacyLevel, startTime, type, description, endTime, channelId, location, coverImage, options, recurrenceRule);
 
         #endregion
 

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

@@ -58,6 +58,9 @@ namespace Discord.Rest
         /// <inheritdoc/>
         public int? UserCount { get; private set; }
 
+        /// <inheritdoc/>
+        public GuildScheduledEventRecurrenceRule? RecurrenceRule { get; private set; }
+
         internal RestGuildEvent(BaseDiscordClient client, IGuild guild, ulong id)
             : base(client, id)
         {
@@ -106,6 +109,8 @@ namespace Discord.Rest
             UserCount = model.UserCount.ToNullable();
             CoverImageId = model.Image;
             GuildId = model.GuildId;
+
+            RecurrenceRule = model.RecurrenceRule?.ToEntity();
         }
 
         /// <inheritdoc/>

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

@@ -231,5 +231,34 @@ namespace Discord.Rest
                 Id = interaction.Id,
             };
         }
+
+        public static GuildScheduledEventRecurrenceRule ToEntity(this API.GuildScheduledEventRecurrenceRule rule)
+            => new(
+                rule.StartAt,
+                rule.EndAt,
+                rule.Frequency,
+                rule.Interval,
+                rule.ByWeekday?.ToReadOnlyCollection() ?? ImmutableArray<RecurrenceRuleWeekday>.Empty,
+                rule.ByNWeekday?.Select(x => new RecurrenceRuleByNWeekday(x.WeekNumber, x.Day)).ToImmutableArray() ?? ImmutableArray<RecurrenceRuleByNWeekday>.Empty,
+                rule.ByMonth?.ToReadOnlyCollection() ?? ImmutableArray<RecurrenceRuleMonth>.Empty,
+                rule.ByMonthDay?.ToReadOnlyCollection() ?? ImmutableArray<int>.Empty,
+                rule.ByYearDay?.ToReadOnlyCollection() ?? ImmutableArray<int>.Empty,
+                rule.Count);
+
+        public static API.GuildScheduledEventRecurrenceRule ToModel(this GuildScheduledEventRecurrenceRuleProperties rule)
+            => new()
+            {
+                Frequency = rule.Frequency,
+                ByMonthDay = rule.ByMonthDay?.ToArray(),
+                ByNWeekday = rule.ByNWeekday?.Select(x => new API.GuildScheduledEventRecurrenceRuleByNWeekday
+                {
+                    Day = x.Day,
+                    WeekNumber = x.Week
+                }).ToArray(),
+                ByWeekday = rule.ByWeekday?.ToArray(),
+                ByMonth = rule.ByMonth?.ToArray(),
+                Interval = rule.Interval,
+                StartAt = rule.StartsAt
+            };
     }
 }

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

@@ -1417,6 +1417,7 @@ namespace Discord.WebSocket
         /// <param name="location">The location of the event; links are supported</param>
         /// <param name="coverImage">The optional banner image for the event.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="recurrenceRule">The definition for how often this event should recur.</param>
         /// <returns>
         ///     A task that represents the asynchronous create operation.
         /// </returns>
@@ -1430,7 +1431,8 @@ namespace Discord.WebSocket
             ulong? channelId = null,
             string location = null,
             Image? coverImage = null,
-            RequestOptions options = null)
+            RequestOptions options = null,
+            GuildScheduledEventRecurrenceRuleProperties recurrenceRule = null)
         {
             // requirements taken from https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-permissions-requirements
             switch (type)
@@ -1446,7 +1448,7 @@ namespace Discord.WebSocket
                     break;
             }
 
-            return GuildHelper.CreateGuildEventAsync(Discord, this, name, privacyLevel, startTime, type, description, endTime, channelId, location, coverImage, options);
+            return GuildHelper.CreateGuildEventAsync(Discord, this, name, privacyLevel, startTime, type, description, endTime, channelId, location, coverImage, options, recurrenceRule);
         }
 
 

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

@@ -65,6 +65,9 @@ namespace Discord.WebSocket
         /// <inheritdoc/>
         public int? UserCount { get; private set; }
 
+        /// <inheritdoc/>
+        public GuildScheduledEventRecurrenceRule? RecurrenceRule { get; private set; }
+
         internal SocketGuildEvent(DiscordSocketClient client, SocketGuild guild, ulong id)
             : base(client, id)
         {
@@ -117,6 +120,8 @@ namespace Discord.WebSocket
             UserCount = model.UserCount.ToNullable();
             CoverImageId = model.Image;
             GuildId = model.GuildId;
+
+            RecurrenceRule = model.RecurrenceRule?.ToEntity();
         }
 
         /// <inheritdoc/>