feat(Widget): wrapper for widget.json (#5619)

Co-authored-by: monbrey <rsm999@uowmail.edu.au>
Co-authored-by: BannerBomb <BannerBomb55@gmail.com>
Co-authored-by: SpaceEEC <spaceeec@yahoo.com>
Co-authored-by: Antonio Román <kyradiscord@gmail.com>
Co-authored-by: Noel <icrawltogo@gmail.com>

src/client/Client.js

@@ -15,6 +15,7 @@ const GuildTemplate = require('../structures/GuildTemplate');
 const Invite = require('../structures/Invite');
 const VoiceRegion = require('../structures/VoiceRegion');
 const Webhook = require('../structures/Webhook');
+const Widget = require('../structures/Widget');
 const Collection = require('../util/Collection');
 const { Events, DefaultOptions, InviteScopes } = require('../util/Constants');
 const DataResolver = require('../util/DataResolver');
@@ -365,6 +366,18 @@ class Client extends BaseClient {
       .then(data => new GuildPreview(this, data));
   }
 
+  /**
+   * Obtains the widget of a guild from Discord, available for guilds with the widget enabled.
+   * @param {GuildResolvable} guild The guild to fetch the widget for
+   * @returns {Promise<Widget>}
+   */
+  async fetchWidget(guild) {
+    const id = this.guilds.resolveID(guild);
+    if (!id) throw new TypeError('INVALID_TYPE', 'guild', 'GuildResolvable');
+    const data = await this.api.guilds(id, 'widget.json').get();
+    return new Widget(this, data);
+  }
+
   /**
    * Options for {@link Client#generateInvite}.
    * @typedef {Object} InviteGenerationOptions

src/index.js

@@ -124,6 +124,8 @@ module.exports = {
   VoiceRegion: require('./structures/VoiceRegion'),
   VoiceState: require('./structures/VoiceState'),
   Webhook: require('./structures/Webhook'),
+  Widget: require('./structures/Widget'),
+  WidgetMember: require('./structures/WidgetMember'),
 
   WebSocket: require('./WebSocket'),
 };

src/structures/Widget.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const Base = require('./Base');
+const WidgetMember = require('./WidgetMember');
+const Collection = require('../util/Collection');
+
+/**
+ * Represents a Widget.
+ */
+class Widget extends Base {
+  /**
+   * @param {Client} client The instantiating client
+   * @param {Object} data The raw data
+   */
+  constructor(client, data) {
+    super(client);
+    this._patch(data);
+  }
+
+  /**
+   * Builds the widget with the provided data.
+   * @param {*} data The raw data of the widget
+   * @private
+   */
+  _patch(data) {
+    /**
+     * The id of the guild.
+     * @type {Snowflake}
+     */
+    this.id = data.id;
+
+    /**
+     * The name of the guild.
+     * @type {string}
+     */
+    this.name = data.name;
+
+    /**
+     * The invite of the guild.
+     * @type {?string}
+     */
+    this.instantInvite = data.instant_invite;
+
+    /**
+     * The list of channels in the guild.
+     * @type {Collection<Snowflake, WidgetChannel>}
+     */
+    this.channels = new Collection();
+    for (const channel of data.channels) {
+      this.channels.set(channel.id, channel);
+    }
+
+    /**
+     * The list of members in the guild.
+     * These strings are just arbitrary numbers, they aren't Snowflakes.
+     * @type {Collection<string, WidgetMember>}
+     */
+    this.members = new Collection();
+    for (const member of data.members) {
+      this.members.set(member.id, new WidgetMember(this.client, member));
+    }
+
+    /**
+     * The number of the members online.
+     * @type {number}
+     */
+    this.presenceCount = data.presence_count;
+  }
+
+  /**
+   * Update the Widget.
+   * @returns {Promise<Widget>}
+   */
+  async fetch() {
+    const data = await this.client.api.guilds(this.id, 'widget.json').get();
+    this._patch(data);
+    return this;
+  }
+}
+
+module.exports = Widget;

src/structures/WidgetMember.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const Base = require('./Base');
+
+/**
+ * Represents a WidgetMember.
+ */
+class WidgetMember extends Base {
+  /**
+   * Activity sent in a {@link WidgetMember}.
+   * @typedef {Object} WidgetActivity
+   * @property {string} name The name of the activity
+   */
+
+  /**
+   * @param {Client} client The instantiating client
+   * @param {Object} data The raw data
+   */
+  constructor(client, data) {
+    super(client);
+
+    /**
+     * The id of the user. It's an arbitrary number.
+     * @type {string}
+     */
+    this.id = data.id;
+
+    /**
+     * The username of the member.
+     * @type {string}
+     */
+    this.username = data.username;
+
+    /**
+     * The discriminator of the member.
+     * @type {string}
+     */
+    this.discriminator = data.discriminator;
+
+    /**
+     * The avatar of the member.
+     * @type {?string}
+     */
+    this.avatar = data.avatar;
+
+    /**
+     * The status of the member.
+     * @type {PresenceStatus}
+     */
+    this.status = data.status;
+
+    /**
+     * IIf the member is server deafened
+     * @type {?boolean}
+     */
+    this.deaf = data.deaf;
+
+    /**
+     * If the member is server muted
+     * @type {?boolean}
+     */
+    this.mute = data.mute;
+
+    /**
+     * If the member is self deafened
+     * @type {?boolean}
+     */
+    this.selfDeaf = data.self_deaf;
+
+    /**
+     * If the member is self muted
+     * @type {?boolean}
+     */
+    this.selfMute = data.self_mute;
+
+    /**
+     * If the member is suppressed
+     * @type {?boolean}
+     */
+    this.suppress = data.suppress;
+
+    /**
+     * The id of the voice channel the member is in, if any
+     * @type {?Snowflake}
+     */
+    this.channelID = data.channel_id;
+
+    /**
+     * The avatar URL of the member.
+     * @type {string}
+     */
+    this.avatarURL = data.avatar_url;
+
+    /**
+     * The activity of the member.
+     * @type {?WidgetActivity}
+     */
+    this.activity = data.activity;
+  }
+}
+
+module.exports = WidgetMember;

typings/index.d.ts

@@ -350,6 +350,7 @@ declare module 'discord.js' {
     public fetchGuildTemplate(template: GuildTemplateResolvable): Promise<GuildTemplate>;
     public fetchVoiceRegions(): Promise<Collection<string, VoiceRegion>>;
     public fetchWebhook(id: Snowflake, token?: string): Promise<Webhook>;
+    public fetchWidget(id: Snowflake): Promise<Widget>;
     public generateInvite(options?: InviteGenerationOptions): string;
     public login(token?: string): Promise<string>;
     public sweepMessages(lifetime?: number): number;
@@ -2028,6 +2029,34 @@ declare module 'discord.js' {
     public once(event: string, listener: (...args: any[]) => Awaited<void>): this;
   }
 
+  export class Widget extends Base {
+    constructor(client: Client, data: object);
+    private _patch(data: object): void;
+    public fetch(): Promise<Widget>;
+    public id: Snowflake;
+    public instantInvite?: string;
+    public channels: Collection<Snowflake, WidgetChannel>;
+    public members: Collection<string, WidgetMember>;
+    public presenceCount: number;
+  }
+
+  export class WidgetMember extends Base {
+    constructor(client: Client, data: object);
+    public id: string;
+    public username: string;
+    public discriminator: string;
+    public avatar?: string;
+    public status: PresenceStatus;
+    public deaf?: boolean;
+    public mute?: boolean;
+    public selfDeaf?: boolean;
+    public selfMute?: boolean;
+    public suppress?: boolean;
+    public channelID?: Snowflake;
+    public avatarURL: string;
+    public activity?: WidgetActivity;
+  }
+
   //#endregion
 
   //#region Collections
@@ -3861,6 +3890,16 @@ declare module 'discord.js' {
     $device?: string;
   }
 
+  interface WidgetActivity {
+    name: string;
+  }
+
+  interface WidgetChannel {
+    id: Snowflake;
+    name: string;
+    position: number;
+  }
+
   type WSEventType =
     | 'READY'
     | 'RESUMED'