feat(WelcomeScreen): welcome screens (#5490)

Co-authored-by: Jan <66554238+vaporox@users.noreply.github.com>
Co-authored-by: izexi <43889168+izexi@users.noreply.github.com>
Co-authored-by: SpaceEEC <spaceeec@yahoo.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

src/structures/AnonymousGuild.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const BaseGuild = require('./BaseGuild');
+const { VerificationLevels, NSFWLevels } = require('../util/Constants');
+
+/**
+ * Bundles common attributes and methods between {@link Guild} and {@link InviteGuild}
+ * @abstract
+ */
+class AnonymousGuild extends BaseGuild {
+  constructor(client, data) {
+    super(client, data);
+    this._patch(data);
+  }
+
+  _patch(data) {
+    this.features = data.features;
+    /**
+     * The hash of the guild invite splash image
+     * @type {?string}
+     */
+    this.splash = data.splash;
+
+    /**
+     * The hash of the guild banner
+     * @type {?string}
+     */
+    this.banner = data.banner;
+
+    /**
+     * The description of the guild, if any
+     * @type {?string}
+     */
+    this.description = data.description;
+
+    /**
+     * The verification level of the guild
+     * @type {VerificationLevel}
+     */
+    this.verificationLevel = VerificationLevels[data.verification_level];
+
+    /**
+     * The vanity invite code of the guild, if any
+     * @type {?string}
+     */
+    this.vanityURLCode = data.vanity_url_code;
+
+    if ('nsfw_level' in data) {
+      /**
+       * The NSFW level of this guild
+       * @type {NSFWLevel}
+       */
+      this.nsfwLevel = NSFWLevels[data.nsfw_level];
+    }
+  }
+
+  /**
+   * The URL to this guild's banner.
+   * @param {ImageURLOptions} [options={}] Options for the Image URL
+   * @returns {?string}
+   */
+  bannerURL({ format, size } = {}) {
+    if (!this.banner) return null;
+    return this.client.rest.cdn.Banner(this.id, this.banner, format, size);
+  }
+
+  /**
+   * The URL to this guild's invite splash image.
+   * @param {ImageURLOptions} [options={}] Options for the Image URL
+   * @returns {?string}
+   */
+  splashURL({ format, size } = {}) {
+    if (!this.splash) return null;
+    return this.client.rest.cdn.Splash(this.id, this.splash, format, size);
+  }
+}
+
+module.exports = AnonymousGuild;

src/structures/BaseGuild.js

@@ -4,8 +4,9 @@ const Base = require('./Base');
 const SnowflakeUtil = require('../util/SnowflakeUtil');
 
 /**
- * The base class for {@link Guild} and {@link OAuth2Guild}.
+ * The base class for {@link Guild}, {@link OAuth2Guild} and {@link InviteGuild}.
  * @extends {Base}
+ * @abstract
  */
 class BaseGuild extends Base {
   constructor(client, data) {

src/structures/Channel.js

@@ -153,7 +153,7 @@ class Channel extends Base {
             break;
           }
         }
-        if (channel) guild.channels.cache.set(channel.id, channel);
+        if (channel) guild.channels?.cache.set(channel.id, channel);
       }
     }
     return channel;

src/structures/Emoji.js

@@ -20,9 +20,9 @@ class Emoji extends Base {
     super(client);
     /**
      * Whether this emoji is animated
-     * @type {boolean}
+     * @type {?boolean}
      */
-    this.animated = emoji.animated;
+    this.animated = emoji.animated ?? null;
 
     /**
      * The name of this emoji

src/structures/Guild.js

@@ -1,12 +1,13 @@
 'use strict';
 
-const BaseGuild = require('./BaseGuild');
+const AnonymousGuild = require('./AnonymousGuild');
 const GuildAuditLogs = require('./GuildAuditLogs');
 const GuildPreview = require('./GuildPreview');
 const GuildTemplate = require('./GuildTemplate');
 const Integration = require('./Integration');
 const Invite = require('./Invite');
 const Webhook = require('./Webhook');
+const WelcomeScreen = require('./WelcomeScreen');
 const { Error, TypeError } = require('../errors');
 const GuildApplicationCommandManager = require('../managers/GuildApplicationCommandManager');
 const GuildBanManager = require('../managers/GuildBanManager');
@@ -24,7 +25,6 @@ const {
   PartialTypes,
   VerificationLevels,
   ExplicitContentFilterLevels,
-  NSFWLevels,
   Status,
   MFALevels,
   PremiumTiers,
@@ -37,9 +37,9 @@ const Util = require('../util/Util');
  * Represents a guild (or a server) on Discord.
  * <info>It's recommended to see if a guild is available before performing operations or reading data from it. You can
  * check this with `guild.available`.</info>
- * @extends {BaseGuild}
+ * @extends {AnonymousGuild}
  */
-class Guild extends BaseGuild {
+class Guild extends AnonymousGuild {
   constructor(client, data) {
     super(client, data);
 
@@ -131,18 +131,12 @@ class Guild extends BaseGuild {
    * @private
    */
   _patch(data) {
+    super._patch(data);
     this.id = data.id;
     this.name = data.name;
     this.icon = data.icon;
-    this.features = data.features;
     this.available = !data.unavailable;
 
-    /**
-     * The hash of the guild invite splash image
-     * @type {?string}
-     */
-    this.splash = data.splash;
-
     /**
      * The hash of the guild discovery splash image
      * @type {?string}
@@ -155,14 +149,6 @@ class Guild extends BaseGuild {
      */
     this.memberCount = data.member_count || this.memberCount;
 
-    if ('nsfw_level' in data) {
-      /**
-       * The NSFW level of this guild
-       * @type {NSFWLevel}
-       */
-      this.nsfwLevel = NSFWLevels[data.nsfw_level];
-    }
-
     /**
      * Whether the guild is "large" (has more than large_threshold members, 50 by default)
      * @type {boolean}
@@ -247,12 +233,6 @@ class Guild extends BaseGuild {
       this.widgetChannelID = data.widget_channel_id;
     }
 
-    /**
-     * The verification level of the guild
-     * @type {VerificationLevel}
-     */
-    this.verificationLevel = VerificationLevels[data.verification_level];
-
     /**
      * The explicit content filter level of the guild
      * @type {ExplicitContentFilterLevel}
@@ -326,12 +306,6 @@ class Guild extends BaseGuild {
       this.approximatePresenceCount = null;
     }
 
-    /**
-     * The vanity invite code of the guild, if any
-     * @type {?string}
-     */
-    this.vanityURLCode = data.vanity_url_code;
-
     /**
      * The use count of the vanity URL code of the guild, if any
      * <info>You will need to fetch this parameter using {@link Guild#fetchVanityData} if you want to receive it</info>
@@ -339,18 +313,6 @@ class Guild extends BaseGuild {
      */
     this.vanityURLUses = null;
 
-    /**
-     * The description of the guild, if any
-     * @type {?string}
-     */
-    this.description = data.description;
-
-    /**
-     * The hash of the guild banner
-     * @type {?string}
-     */
-    this.banner = data.banner;
-
     /**
      * The ID of the rules channel for the guild
      * @type {?Snowflake}
@@ -576,6 +538,15 @@ class Guild extends BaseGuild {
       );
   }
 
+  /**
+   * Fetches the welcome screen for this guild.
+   * @returns {Promise<WelcomeScreen>}
+   */
+  async fetchWelcomeScreen() {
+    const data = await this.client.api.guilds(this.id, 'welcome-screen').get();
+    return new WelcomeScreen(this, data);
+  }
+
   /**
    * The data for creating an integration.
    * @typedef {Object} IntegrationData
@@ -900,6 +871,60 @@ class Guild extends BaseGuild {
       .then(newData => this.client.actions.GuildUpdate.handle(newData).updated);
   }
 
+  /**
+   * Welcome channel data
+   * @typedef {Object} WelcomeChannelData
+   * @property {string} description The description to show for this welcome channel
+   * @property {GuildTextChannelResolvable} channel The channel to link for this welcome channel
+   * @property {EmojiIdentifierResolvable} [emoji] The emoji to display for this welcome channel
+   */
+
+  /**
+   * Welcome screen edit data
+   * @typedef {Object} WelcomeScreenEditData
+   * @property {boolean} [enabled] Whether the welcome screen is enabled
+   * @property {string} [description] The description for the welcome screen
+   * @property {WelcomeChannelData[]} [welcomeChannels] The welcome channel data for the welcome screen
+   */
+
+  /**
+   * Updates the guild's welcome screen
+   * @param {WelcomeScreenEditData} data Data to edit the welcome screen with
+   * @returns {Promise<WelcomeScreen>}
+   * @example
+   * guild.editWelcomeScreen({
+   *   description: 'Hello World',
+   *   enabled: true,
+   *   welcomeChannels: [
+   *     {
+   *       description: 'foobar',
+   *       channel: '222197033908436994',
+   *     }
+   *   ],
+   * })
+   */
+  async editWelcomeScreen(data) {
+    const { enabled, description, welcomeChannels } = data;
+    const welcome_channels = welcomeChannels?.map(welcomeChannelData => {
+      const emoji = this.emojis.resolve(welcomeChannelData.emoji);
+      return {
+        emoji_id: emoji?.id ?? null,
+        emoji_name: emoji?.name ?? welcomeChannelData.emoji,
+        channel_id: this.channels.resolveID(welcomeChannelData.channel),
+        description: welcomeChannelData.description,
+      };
+    });
+
+    const patchData = await this.client.api.guilds(this.id, 'welcome-screen').patch({
+      data: {
+        welcome_channels,
+        description,
+        enabled,
+      },
+    });
+    return new WelcomeScreen(this, patchData);
+  }
+
   /**
    * Edits the level of the explicit content filter.
    * @param {ExplicitContentFilterLevel|number} explicitContentFilter The new level of the explicit content filter

src/structures/Invite.js

@@ -19,11 +19,16 @@ class Invite extends Base {
   }
 
   _patch(data) {
+    const InviteGuild = require('./InviteGuild');
+    const Guild = require('./Guild');
     /**
-     * The guild the invite is for
-     * @type {?Guild}
+     * The guild the invite is for including welcome screen data if present
+     * @type {?(Guild|InviteGuild)}
      */
-    this.guild = data.guild ? this.client.guilds.add(data.guild, false) : null;
+    this.guild = null;
+    if (data.guild) {
+      this.guild = data.guild instanceof Guild ? data.guild : new InviteGuild(this.client, data.guild);
+    }
 
     /**
      * The code for this invite

src/structures/InviteGuild.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const AnonymousGuild = require('./AnonymousGuild');
+const WelcomeScreen = require('./WelcomeScreen');
+
+/**
+ * Represents a guild received from an invite, includes welcome screen data if available.
+ * @extends {AnonymousGuild}
+ */
+class InviteGuild extends AnonymousGuild {
+  constructor(client, data) {
+    super(client, data);
+
+    /**
+     * The welcome screen for this invite guild
+     * @type {?WelcomeScreen}
+     */
+    this.welcomeScreen =
+      typeof data.welcome_screen !== 'undefined' ? new WelcomeScreen(this, data.welcome_screen) : null;
+  }
+}
+
+module.exports = InviteGuild;

src/structures/WelcomeChannel.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const Base = require('./Base');
+const Emoji = require('./Emoji');
+
+/**
+ * Represents a channel link in a guild's welcome screen.
+ * @extends {Base}
+ */
+class WelcomeChannel extends Base {
+  constructor(guild, data) {
+    super(guild.client);
+
+    /**
+     * The guild for this welcome channel
+     * @type {Guild|WelcomeGuild}
+     */
+    this.guild = guild;
+
+    /**
+     * The description of this welcome channel
+     * @type {string}
+     */
+    this.description = data.description;
+
+    /**
+     * The raw emoji data
+     * @type {Object}
+     * @private
+     */
+    this._emoji = {
+      name: data.emoji_name,
+      id: data.emoji_id,
+    };
+
+    /**
+     * The id of this welcome channel
+     * @type {Snowflake}
+     */
+    this.channelID = data.channel_id;
+  }
+
+  /**
+   * The channel of this welcome channel
+   * @type {?TextChannel|NewsChannel}
+   */
+  get channel() {
+    return this.client.channels.resolve(this.channelID);
+  }
+
+  /**
+   * The emoji of this welcome channel
+   * @type {GuildEmoji|Emoji}
+   */
+  get emoji() {
+    return this.client.emojis.resolve(this._emoji.id) ?? new Emoji(this.client, this._emoji);
+  }
+}
+
+module.exports = WelcomeChannel;

src/structures/WelcomeScreen.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const Base = require('./Base');
+const WelcomeChannel = require('./WelcomeChannel');
+const Collection = require('../util/Collection');
+
+/**
+ * Represents a welcome screen.
+ * @extends {Base}
+ */
+class WelcomeScreen extends Base {
+  constructor(guild, data) {
+    super(guild.client);
+
+    /**
+     * The guild for this welcome screen
+     * @type {Guild}
+     */
+    this.guild = guild;
+
+    /**
+     * The description of this welcome screen
+     * @type {?string}
+     */
+    this.description = data.description ?? null;
+
+    /**
+     * Collection of welcome channels belonging to this welcome screen
+     * @type {Collection<Snowflake, WelcomeChannel>}
+     */
+    this.welcomeChannels = new Collection();
+
+    for (const channel of data.welcome_channels) {
+      const welcomeChannel = new WelcomeChannel(this.guild, channel);
+      this.welcomeChannels.set(welcomeChannel.channelID, welcomeChannel);
+    }
+  }
+
+  /**
+   * Whether the welcome screen is enabled on the guild or not
+   * @type {boolean}
+   */
+  get enabled() {
+    return this.guild.features.includes('WELCOME_SCREEN_ENABLED');
+  }
+}
+
+module.exports = WelcomeScreen;