feat: deprecate GuildEmbed methods and properties in favour of GuildWidget (#4121)

src/structures/Guild.js

@@ -206,6 +206,7 @@ class Guild extends Base {
     /**
      * Whether embedded images are enabled on this guild
      * @type {boolean}
+     * @deprecated
      */
     this.embedEnabled = data.embed_enabled;
 
@@ -251,6 +252,7 @@ class Guild extends Base {
      * The embed channel ID, if enabled
      * @type {?string}
      * @name Guild#embedChannelID
+     * @deprecated
      */
     if (typeof data.embed_channel_id !== 'undefined') this.embedChannelID = data.embed_channel_id;
 
@@ -557,6 +559,7 @@ class Guild extends Base {
    * Embed channel for this guild
    * @type {?TextChannel}
    * @readonly
+   * @deprecated
    */
   get embedChannel() {
     return this.client.channels.cache.get(this.embedChannelID) || null;
@@ -839,15 +842,23 @@ class Guild extends Base {
   }
 
   /**
-   * The Guild Embed object
+   * Data for the Guild Widget object
-   * @typedef {Object} GuildEmbedData
+   * @typedef {Object} GuildWidget
-   * @property {boolean} enabled Whether the embed is enabled
+   * @property {boolean} enabled Whether the widget is enabled
-   * @property {?GuildChannel} channel The embed channel
+   * @property {?GuildChannel} channel The widget channel
+   */
+
+  /**
+   * The Guild Widget object
+   * @typedef {Object} GuildWidgetData
+   * @property {boolean} enabled Whether the widget is enabled
+   * @property {?GuildChannelResolvable} channel The widget channel
    */
 
   /**
    * Fetches the guild embed.
-   * @returns {Promise<GuildEmbedData>}
+   * @returns {Promise<GuildWidget>}
+   * @deprecated
    * @example
    * // Fetches the guild embed
    * guild.fetchEmbed()
@@ -864,6 +875,25 @@ class Guild extends Base {
       }));
   }
 
+  /**
+   * Fetches the guild widget.
+   * @returns {Promise<GuildWidget>}
+   * @example
+   * // Fetches the guild widget
+   * guild.fetchWidget()
+   *   .then(widget => console.log(`The widget is ${widget.enabled ? 'enabled' : 'disabled'}`))
+   *   .catch(console.error);
+   */
+  fetchWidget() {
+    return this.client.api
+      .guilds(this.id)
+      .widget.get()
+      .then(data => ({
+        enabled: data.enabled,
+        channel: data.channel_id ? this.channels.cache.get(data.channel_id) : null,
+      }));
+  }
+
   /**
    * Fetches audit logs for this guild.
    * @param {Object} [options={}] Options for fetching audit logs
@@ -1262,9 +1292,10 @@ class Guild extends Base {
 
   /**
    * Edits the guild's embed.
-   * @param {GuildEmbedData} embed The embed for the guild
+   * @param {GuildWidgetData} embed The embed for the guild
    * @param {string} [reason] Reason for changing the guild's embed
    * @returns {Promise<Guild>}
+   * @deprecated
    */
   setEmbed(embed, reason) {
     return this.client.api
@@ -1279,6 +1310,25 @@ class Guild extends Base {
       .then(() => this);
   }
 
+  /**
+   * Edits the guild's widget.
+   * @param {GuildWidgetData} widget The widget for the guild
+   * @param {string} [reason] Reason for changing the guild's widget
+   * @returns {Promise<Guild>}
+   */
+  setWidget(widget, reason) {
+    return this.client.api
+      .guilds(this.id)
+      .widget.patch({
+        data: {
+          enabled: widget.enabled,
+          channel_id: this.channels.resolveID(widget.channel),
+        },
+        reason,
+      })
+      .then(() => this);
+  }
+
   /**
    * Leaves the guild.
    * @returns {Promise<Guild>}
@@ -1404,6 +1454,10 @@ class Guild extends Base {
   }
 }
 
+Guild.prototype.setEmbed = deprecate(Guild.prototype.setEmbed, 'Guild#setEmbed: Use setWidget instead');
+
+Guild.prototype.fetchEmbed = deprecate(Guild.prototype.fetchEmbed, 'Guild#fetchEmbed: Use fetchWidget instead');
+
 Guild.prototype.fetchVanityCode = deprecate(
   Guild.prototype.fetchVanityCode,
   'Guild#fetchVanityCode: Use fetchVanityData() instead',

typings/index.d.ts

@@ -674,7 +674,7 @@ declare module 'discord.js' {
     public fetchAuditLogs(options?: GuildAuditLogsFetchOptions): Promise<GuildAuditLogs>;
     public fetchBan(user: UserResolvable): Promise<{ user: User; reason: string }>;
     public fetchBans(): Promise<Collection<Snowflake, { user: User; reason: string }>>;
-    public fetchEmbed(): Promise<GuildEmbedData>;
+    public fetchEmbed(): Promise<GuildWidget>;
     public fetchIntegrations(): Promise<Collection<string, Integration>>;
     public fetchInvites(): Promise<Collection<string, Invite>>;
     public fetchPreview(): Promise<GuildPreview>;
@@ -682,6 +682,7 @@ declare module 'discord.js' {
     public fetchVanityData(): Promise<{ code: string; uses: number }>;
     public fetchVoiceRegions(): Promise<Collection<string, VoiceRegion>>;
     public fetchWebhooks(): Promise<Collection<Snowflake, Webhook>>;
+    public fetchWidget(): Promise<GuildWidget>;
     public iconURL(options?: ImageURLOptions & { dynamic?: boolean }): string | null;
     public leave(): Promise<Guild>;
     public member(user: UserResolvable): GuildMember | null;
@@ -693,7 +694,7 @@ declare module 'discord.js' {
       defaultMessageNotifications: DefaultMessageNotifications | number,
       reason?: string,
     ): Promise<Guild>;
-    public setEmbed(embed: GuildEmbedData, reason?: string): Promise<Guild>;
+    public setEmbed(embed: GuildWidgetData, reason?: string): Promise<Guild>;
     public setExplicitContentFilter(explicitContentFilter: ExplicitContentFilterLevel, reason?: string): Promise<Guild>;
     public setIcon(icon: Base64Resolvable | null, reason?: string): Promise<Guild>;
     public setName(name: string, reason?: string): Promise<Guild>;
@@ -704,6 +705,7 @@ declare module 'discord.js' {
     public setSystemChannel(systemChannel: ChannelResolvable | null, reason?: string): Promise<Guild>;
     public setSystemChannelFlags(systemChannelFlags: SystemChannelFlagsResolvable, reason?: string): Promise<Guild>;
     public setVerificationLevel(verificationLevel: VerificationLevel, reason?: string): Promise<Guild>;
+    public setWidget(widget: GuildWidgetData, reason?: string): Promise<Guild>;
     public splashURL(options?: ImageURLOptions): string | null;
     public toJSON(): object;
     public toString(): string;
@@ -2519,6 +2521,11 @@ declare module 'discord.js' {
     name?: string;
   }
 
+  interface GuildWidget {
+    enabled: boolean;
+    channel: GuildChannel | null;
+  }
+
   interface GuildEditData {
     name?: string;
     region?: string;
@@ -2535,11 +2542,6 @@ declare module 'discord.js' {
     banner?: Base64Resolvable;
   }
 
-  interface GuildEmbedData {
-    enabled: boolean;
-    channel: GuildChannelResolvable | null;
-  }
-
   interface GuildEmojiCreateOptions {
     roles?: Collection<Snowflake, Role> | RoleResolvable[];
     reason?: string;
@@ -2585,6 +2587,11 @@ declare module 'discord.js' {
     reason?: string;
   }
 
+  interface GuildWidgetData {
+    enabled: boolean;
+    channel: GuildChannelResolvable | null;
+  }
+
   interface HTTPOptions {
     api?: string;
     version?: number;