feat(Guild): add fetchVanityData (#4103)

* chore: deprecate Guild.fetchVanityCode()

* feat: add Guild.fetchVanityData()

* chore: update typings

* fix: remove redundant .then()

Co-Authored-By: Antonio Román <kyradiscord@gmail.com>

* chore: fix lint

* chore: util.deprecate fetchVanityCode

* feat: add VanityData typedef and populate vanityURLUses

* chore: update typings

* chore: properly deprecate fetchVanityCode

* chore: fix jsdoc description for fetchVanityData

* feat: make fetchVanityData an async function

* chore: update Vanity typedef

* docs: update jsdoc

* feat: throw vanity url error instead of returning rejected promise

Co-Authored-By: Vlad Frangu <kingdgrizzle@gmail.com>

* docs: disable max-len rule and add info about receiving parameter

* fix: throw Error instead of rejecting Promise

* revert: revert "fix: throw Error instead of rejecting Promise"

This reverts commit 7ffd53eba4.

* fix: require DJSError to fix throwing VANITY_URL error

* nitpick: re-add TypeError to the import

Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

Co-authored-by: Antonio Román <kyradiscord@gmail.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

src/structures/Guild.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { deprecate } = require('util');
 const Base = require('./Base');
 const GuildAuditLogs = require('./GuildAuditLogs');
 const GuildPreview = require('./GuildPreview');
@@ -7,6 +8,7 @@ const Integration = require('./Integration');
 const Invite = require('./Invite');
 const VoiceRegion = require('./VoiceRegion');
 const Webhook = require('./Webhook');
+const { Error, TypeError } = require('../errors');
 const GuildChannelManager = require('../managers/GuildChannelManager');
 const GuildEmojiManager = require('../managers/GuildEmojiManager');
 const GuildMemberManager = require('../managers/GuildMemberManager');
@@ -331,6 +333,15 @@ class Guild extends Base {
      */
     this.vanityURLCode = data.vanity_url_code;
 
+    /* eslint-disable max-len */
+    /**
+     * The use count of the vanity URL code of the guild, if any
+     * <info>You will need to fetch the guild using {@link Guild#fetchVanityCode} if you want to receive this parameter</info>
+     * @type {?number}
+     */
+    this.vanityURLUses = null;
+    /* eslint-enable max-len */
+
     /**
      * The description of the guild, if any
      * @type {?string}
@@ -750,6 +761,7 @@ class Guild extends Base {
    * Fetches the vanity url invite code to this guild.
    * Resolves with a string matching the vanity url invite code, not the full url.
    * @returns {Promise<string>}
+   * @deprecated
    * @example
    * // Fetch invites
    * guild.fetchVanityCode()
@@ -768,6 +780,35 @@ class Guild extends Base {
       .then(res => res.code);
   }
 
+  /**
+   * An object containing information about a guild's vanity invite.
+   * @typedef {Object} Vanity
+   * @property {?string} code Vanity invite code
+   * @property {?number} uses How many times this invite has been used
+   */
+
+  /**
+   * Fetches the vanity url invite object to this guild.
+   * Resolves with an object containing the vanity url invite code and the use count
+   * @returns {Promise<Vanity>}
+   * @example
+   * // Fetch invite data
+   * guild.fetchVanityData()
+   *   .then(res => {
+   *     console.log(`Vanity URL: https://discord.gg/${res.code} with ${res.uses} uses`);
+   *   })
+   *   .catch(console.error);
+   */
+  async fetchVanityData() {
+    if (!this.features.includes('VANITY_URL')) {
+      throw new Error('VANITY_URL');
+    }
+    const data = await this.client.api.guilds(this.id, 'vanity-url').get();
+    this.vanityURLUses = data.uses;
+
+    return data;
+  }
+
   /**
    * Fetches all webhooks for the guild.
    * @returns {Promise<Collection<Snowflake, Webhook>>}
@@ -1369,4 +1410,9 @@ class Guild extends Base {
   }
 }
 
+Guild.prototype.fetchVanityCode = deprecate(
+  Guild.prototype.fetchVanityCode,
+  'Guild#fetchVanityCode: Use fetchVanityData() instead',
+);
+
 module.exports = Guild;

typings/index.d.ts

@@ -638,6 +638,7 @@ declare module 'discord.js' {
     public systemChannelFlags: Readonly<SystemChannelFlags>;
     public systemChannelID: Snowflake | null;
     public vanityURLCode: string | null;
+    public vanityURLUses: number | null;
     public verificationLevel: VerificationLevel;
     public readonly verified: boolean;
     public readonly voice: VoiceState | null;
@@ -660,6 +661,7 @@ declare module 'discord.js' {
     public fetchInvites(): Promise<Collection<string, Invite>>;
     public fetchPreview(): Promise<GuildPreview>;
     public fetchVanityCode(): Promise<string>;
+    public fetchVanityData(): Promise<{ code: string; uses: number }>;
     public fetchVoiceRegions(): Promise<Collection<string, VoiceRegion>>;
     public fetchWebhooks(): Promise<Collection<Snowflake, Webhook>>;
     public iconURL(options?: ImageURLOptions & { dynamic?: boolean }): string | null;