feat: recurring scheduled events

#10447 djs

src/managers/GuildScheduledEventManager.js

@@ -6,6 +6,7 @@ const { TypeError, Error } = require('../errors');
 const { GuildScheduledEvent } = require('../structures/GuildScheduledEvent');
 const { PrivacyLevels, GuildScheduledEventEntityTypes, GuildScheduledEventStatuses } = require('../util/Constants');
 const DataResolver = require('../util/DataResolver');
+const Util = require('../util/Util');
 
 /**
  * Manages API methods for GuildScheduledEvents and stores their cache.
@@ -35,6 +36,21 @@ class GuildScheduledEventManager extends CachedManager {
    * @typedef {Snowflake|GuildScheduledEvent} GuildScheduledEventResolvable
    */
 
+  /**
+   * Options for setting a recurrence rule for a guild scheduled event.
+   * @typedef {Object} GuildScheduledEventRecurrenceRuleOptions
+   * @property {DateResolvable} startAt The time the recurrence rule interval starts at
+   * @property {?DateResolvable} endAt The time the recurrence rule interval ends at
+   * @property {GuildScheduledEventRecurrenceRuleFrequency} frequency How often the event occurs
+   * @property {number} interval The spacing between the events
+   * @property {?GuildScheduledEventRecurrenceRuleWeekday[]} byWeekday The days within a week to recur on
+   * @property {?GuildScheduledEventRecurrenceRuleNWeekday[]} byNWeekday The days within a week to recur on
+   * @property {?GuildScheduledEventRecurrenceRuleMonth[]} byMonth The months to recur on
+   * @property {?number[]} byMonthDay The days within a month to recur on
+   * @property {?number[]} byYearDay The days within a year to recur on
+   * @property {?number} count The total amount of times the event is allowed to recur before stopping
+   */
+
   /**
    * Options used to create a guild scheduled event.
    * @typedef {Object} GuildScheduledEventCreateOptions
@@ -52,6 +68,8 @@ class GuildScheduledEventManager extends CachedManager {
    * <warn>This is required if `entityType` is 'EXTERNAL'</warn>
    * @property {?(BufferResolvable|Base64Resolvable)} [image] The cover image of the guild scheduled event
    * @property {string} [reason] The reason for creating the guild scheduled event
+   * @property {GuildScheduledEventRecurrenceRuleOptions} [recurrenceRule]
+   * The recurrence rule of the guild scheduled event
    */
 
   /**
@@ -79,6 +97,7 @@ class GuildScheduledEventManager extends CachedManager {
       entityMetadata,
       reason,
       image,
+      recurrenceRule,
     } = options;
 
     if (typeof privacyLevel === 'string') privacyLevel = PrivacyLevels[privacyLevel];
@@ -105,6 +124,7 @@ class GuildScheduledEventManager extends CachedManager {
         image: image && (await DataResolver.resolveImage(image)),
         entity_type: entityType,
         entity_metadata,
+        recurrence_rule: recurrenceRule && Util.transformGuildScheduledEventRecurrenceRule(recurrenceRule),
       },
       reason,
     });
@@ -178,6 +198,8 @@ class GuildScheduledEventManager extends CachedManager {
    * <warn>This can be modified only if `entityType` of the `GuildScheduledEvent` to be edited is 'EXTERNAL'</warn>
    * @property {?(BufferResolvable|Base64Resolvable)} [image] The cover image of the guild scheduled event
    * @property {string} [reason] The reason for editing the guild scheduled event
+   * @property {?GuildScheduledEventRecurrenceRuleOptions} [recurrenceRule]
+   * The recurrence rule of the guild scheduled event
    */
 
   /**
@@ -203,6 +225,7 @@ class GuildScheduledEventManager extends CachedManager {
       entityMetadata,
       reason,
       image,
+      recurrenceRule,
     } = options;
 
     if (typeof privacyLevel === 'string') privacyLevel = PrivacyLevels[privacyLevel];
@@ -228,6 +251,7 @@ class GuildScheduledEventManager extends CachedManager {
         status,
         image: image && (await DataResolver.resolveImage(image)),
         entity_metadata,
+        recurrence_rule: recurrenceRule && Util.transformGuildScheduledEventRecurrenceRule(recurrenceRule),
       },
       reason,
     });

src/util/APITypes.js

@@ -1,3 +1,23 @@
+/**
+ * @external APIGuildScheduledEventRecurrenceRule
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/interface/APIGuildScheduledEventRecurrenceRule}
+ */
+
+/**
+ * @external GuildScheduledEventRecurrenceRuleFrequency
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/GuildScheduledEventRecurrenceRuleFrequency}
+ */
+
+/**
+ * @external GuildScheduledEventRecurrenceRuleMonth
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/GuildScheduledEventRecurrenceRuleMonth}
+ */
+
+/**
+ * @external GuildScheduledEventRecurrenceRuleWeekday
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/GuildScheduledEventRecurrenceRuleWeekday}
+ */
+
 /**
  * @external MessageActivityType
  * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/MessageActivityType}

src/util/Util.js

@@ -784,6 +784,28 @@ class Util extends null {
     };
   }
 
+  /**
+   * Transforms a guild scheduled event recurrence rule object to a snake-cased variant.
+   * @param {GuildScheduledEventRecurrenceRuleOptions} recurrenceRule The recurrence rule to transform
+   * @returns {APIGuildScheduledEventRecurrenceRule}
+   * @ignore
+   */
+  static transformGuildScheduledEventRecurrenceRule(recurrenceRule) {
+    return {
+      start: new Date(recurrenceRule.startAt).toISOString(),
+      // eslint-disable-next-line eqeqeq
+      end: recurrenceRule.endAt != null ? new Date(recurrenceRule.endAt).toISOString() : recurrenceRule.endAt,
+      frequency: recurrenceRule.frequency,
+      interval: recurrenceRule.interval,
+      by_weekday: recurrenceRule.byWeekday,
+      by_n_weekday: recurrenceRule.byNWeekday,
+      by_month: recurrenceRule.byMonth,
+      by_month_day: recurrenceRule.byMonthDay,
+      by_year_day: recurrenceRule.byYearDay,
+      count: recurrenceRule.count,
+    };
+  }
+
   /**
    * Gets an array of the channel types that can be moved in the channel group. For example, a GuildText channel would
    * return an array containing the types that can be ordered within the text channels (always at the top), and a voice

typings/index.d.ts

@@ -6736,14 +6736,29 @@ export interface GuildScheduledEventCreateOptions {
   entityMetadata?: GuildScheduledEventEntityMetadataOptions;
   image?: BufferResolvable | Base64Resolvable | null;
   reason?: string;
+  recurrenceRule?: GuildScheduledEventRecurrenceRuleOptions;
+}
+
+export interface GuildScheduledEventRecurrenceRuleOptions {
+  startAt: DateResolvable;
+  endAt: DateResolvable;
+  frequency: GuildScheduledEventRecurrenceRuleFrequency;
+  interval: number;
+  byWeekday: readonly GuildScheduledEventRecurrenceRuleWeekday[];
+  byNWeekday: readonly GuildScheduledEventRecurrenceRuleNWeekday[];
+  byMonth: readonly GuildScheduledEventRecurrenceRuleMonth[];
+  byMonthDay: readonly number[];
+  byYearDay: readonly number[];
+  count: number;
 }
 
 export interface GuildScheduledEventEditOptions<
   S extends GuildScheduledEventStatus,
   T extends GuildScheduledEventSetStatusArg<S>,
-> extends Omit<Partial<GuildScheduledEventCreateOptions>, 'channel'> {
+> extends Omit<Partial<GuildScheduledEventCreateOptions>, 'channel' | 'recurrenceRule'> {
   channel?: GuildVoiceChannelResolvable | null;
   status?: T | number;
+  recurrenceRule?: GuildScheduledEventRecurrenceRuleOptions | null;
 }
 
 export interface GuildScheduledEventEntityMetadata {