feat(GuildPreview): implement support for "preview" endpoint

src/client/Client.js

@@ -11,6 +11,7 @@ const GuildManager = require('../managers/GuildManager');
 const UserManager = require('../managers/UserManager');
 const ShardClientUtil = require('../sharding/ShardClientUtil');
 const ClientApplication = require('../structures/ClientApplication');
+const GuildPreview = require('../structures/GuildPreview');
 const Invite = require('../structures/Invite');
 const VoiceRegion = require('../structures/VoiceRegion');
 const Webhook = require('../structures/Webhook');
@@ -338,6 +339,19 @@ class Client extends BaseClient {
       .then(app => new ClientApplication(this, app));
   }
 
+  /**
+   * Tries to fetch the specified guild, if available to the "preview" endpoint.
+   * @param {GuildResolvable} guild The GuildResolvable to resolve
+   * @returns {Promise<GuildPreview>}
+   */
+  fetchGuildPreview(guild) {
+    const id = this.guilds.resolveID(guild);
+    return this.api
+      .guilds(id, 'preview')
+      .get()
+      .then(data => new GuildPreview(this, data));
+  }
+
   /**
    * Generates a link that can be used to invite the bot to a guild.
    * @param {PermissionResolvable} [permissions] Permissions to request

src/structures/GuildPreview.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const Base = require('./Base');
+const GuildEmojiManager = require('../managers/GuildEmojiManager');
+
+/**
+ * Represents the data about the guild any bot can preivew, connected to the specified public guild
+ */
+class GuildPreview extends Base {
+  constructor(client, data) {
+    super(client);
+
+    if (!data) return;
+    this._patch(data);
+  }
+
+  /**
+   * Builds the public guild with the provided data
+   * @param {*} data The raw data of the public guild
+   * @private
+   */
+  _patch(data) {
+    /**
+     * The id of this public guild
+     * @type {string}
+     */
+    this.id = data.id;
+
+    /**
+     * The name of this public guild
+     * @type {string}
+     */
+    this.name = data.name;
+
+    /**
+     * The icon of this public guild
+     * @type {?string}
+     */
+    this.icon = data.icon;
+
+    /**
+     * The splash icon of this public guild
+     * @type {?string}
+     */
+    this.splash = data.splash;
+
+    /**
+     * The discovery splash icon of this public guild
+     * @type {?string}
+     */
+    this.discoverySplash = data.discovery_splash;
+
+    /**
+     * An array of enabled guild features
+     * @type {Features[]}
+     */
+    this.features = data.features;
+
+    /**
+     * The approximate count of members in this public guild
+     * @type {number}
+     */
+    this.approximateMemberCount = data.approximate_member_count;
+
+    /**
+     * The approximate count of online members in this public guild
+     * @type {number}
+     */
+    this.approximatePresenceCount = data.approximate_presence_count;
+
+    /**
+     * The description for this public guild
+     * @type {?string}
+     */
+    this.description = data.description;
+
+    if (!this.emojis) {
+      /**
+       * A manager of the emojis belonging to this public guild
+       * @type {GuildEmojiManager}
+       */
+      this.emojis = new GuildEmojiManager(this);
+      if (data.emojis) for (const emoji of data.emojis) this.emojis.add(emoji);
+    } else if (data.emojis) {
+      this.client.actions.GuildemojisUpdate.handle({
+        guild_id: this.id,
+        emojis: data.emojis,
+      });
+    }
+  }
+
+  /**
+   * The URL to this public guild's splash
+   * @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);
+  }
+
+  /**
+   * The URL to this public guild's discovery splash
+   * @param {ImageURLOptions} [options={}] Options for the Image URL
+   * @returns {?string}
+   */
+  discoverySplashURL({ format, size } = {}) {
+    if (!this.discoverySplash) return null;
+    return this.client.rest.cdn.Splash(this.id, this.discoverySplash, format, size, 'discovery');
+  }
+
+  /**
+   * The URL to this public guild's icon
+   * @param {ImageURLOptions} [options={}] Options for the Image URL
+   * @returns {?string}
+   */
+  iconURL({ format, size, dynamic } = {}) {
+    if (!this.icon) return null;
+    return this.client.rest.cdn.Icon(this.id, this.icon, format, size, dynamic);
+  }
+
+  /**
+   * Fetches this public guild.
+   * @returns {Promise<GuildPreview>}
+   */
+  fetch() {
+    return this.client.api
+      .guilds(this.id, 'preview')
+      .get()
+      .then(data => {
+        this._patch(data);
+        return this;
+      });
+  }
+
+  /**
+   * When concatenated with a string, this automatically returns the guild's name instead of the Guild object.
+   * @returns {string}
+   * @example
+   * // Logs: Hello from My Guild!
+   * console.log(`Hello from ${previewGuild}!`);
+   */
+  toString() {
+    return this.name;
+  }
+
+  toJSON() {
+    const json = super.toJSON();
+    json.iconURL = this.iconURL();
+    json.splashURL = this.splashURL();
+  }
+}
+
+module.exports = GuildPreview;

typings/index.d.ts

@@ -807,6 +807,24 @@ declare module 'discord.js' {
     public valueOf(): string;
   }
 
+  export class GuildPreview extends Base {
+    constructor(client: Client, data: object);
+    public approximateMemberCount: number;
+    public approximatePresenceCount: number;
+    public description?: string;
+    public emojis: GuildEmojiManager;
+    public features: GuildFeatures;
+    public id: string;
+    public name: string;
+
+    public discoverySplashURL(options?: ImageURLOptions): string | null;
+    public iconURL(options?: ImageURLOptions & { dynamic?: boolean }): string | null;
+    public splashURL(options?: ImageURLOptions): string | null;
+    public fetch(): Promise<GuildPreview>;
+    public toJSON(): object;
+    public toString(): string;
+    private _patch(data: object);
+  }
   export class HTTPError extends Error {
     constructor(message: string, name: string, code: number, method: string, path: string);
     public code: number;
@@ -2771,26 +2789,18 @@ declare module 'discord.js' {
     partial: true;
     fetch(): Promise<T>;
   } & {
-    [K in keyof Omit<T,
-      'client' |
-      'createdAt' |
-      'createdTimestamp' |
-      'id' |
-      'partial' |
-      'fetch' | O>
-      // tslint:disable-next-line:ban-types
-    ]: T[K] extends Function ? T[K] : T[K] | null;
+    [K in keyof Omit<
+      T,
+      'client' | 'createdAt' | 'createdTimestamp' | 'id' | 'partial' | 'fetch' | O
+    >]: // tslint:disable-next-line:ban-types
+    T[K] extends Function ? T[K] : T[K] | null;
   };
 
-  interface PartialDMChannel extends Partialize<DMChannel,
-    'lastMessage' |
-    'lastMessageID' |
-    'messages' |
-    'recipient' |
-    'type' |
-    'typing' |
-    'typingCount'
-  > {
+  interface PartialDMChannel
+    extends Partialize<
+      DMChannel,
+      'lastMessage' | 'lastMessageID' | 'messages' | 'recipient' | 'type' | 'typing' | 'typingCount'
+    > {
     lastMessage: null;
     lastMessageID: undefined;
     messages: MessageManager;
@@ -2814,16 +2824,11 @@ declare module 'discord.js' {
     }[];
   }
 
-  interface PartialGuildMember extends Partialize<GuildMember,
-    'bannable' |
-    'displayColor' |
-    'displayHexColor' |
-    'displayName' |
-    'guild' |
-    'kickable' |
-    'permissions' |
-    'roles'
-  > {
+  interface PartialGuildMember
+    extends Partialize<
+      GuildMember,
+      'bannable' | 'displayColor' | 'displayHexColor' | 'displayName' | 'guild' | 'kickable' | 'permissions' | 'roles'
+    > {
     readonly bannable: boolean;
     readonly displayColor: number;
     readonly displayHexColor: string;
@@ -2836,16 +2841,11 @@ declare module 'discord.js' {
     readonly roles: GuildMember['roles'];
   }
 
-  interface PartialMessage extends Partialize<Message,
-    'attachments' |
-    'channel' |
-    'deletable' |
-    'editable' |
-    'mentions' |
-    'pinnable' |
-    'system' |
-    'url'
-  > {
+  interface PartialMessage
+    extends Partialize<
+      Message,
+      'attachments' | 'channel' | 'deletable' | 'editable' | 'mentions' | 'pinnable' | 'system' | 'url'
+    > {
     attachments: Message['attachments'];
     channel: Message['channel'];
     readonly deletable: boolean;