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

* feat(GuildPreview): method — fetchGuildPreview * feat(GuildPreview): structure — GuildPreview * feat(GuildPreview): update typings * fix(GuildPreview): remove typedef for Features — already exists * refactor(GuildPreview): update JSDocs & method * feat(GuildPreview): implement DiscoverySplash function * fix(GuildPreview): description & error handling for id * fix(GuildPreview): misleading description, assign emojis correctly * feat(GuildPreview): func DisplaySplash & GuildPreviewEmoji interface * fix(Typings): satisfy TSLint * fix(GuildPreview): toJSON - returns a value now * feat(GuildPreview): add fetchPreview method on instance of Guild * feat(GuildPreview): update typings * fix: missing client constructor * fix: typo in typings * feat(BaseEmoji): implement BaseEmoji — parent for emoji instances * feat(BaseEmoji): refactor - GuildEmoji extends BaseEmoji now * feat(BaseEmoji): refactor - adjust emojis prop to BaseEmoji instance * feat(BaseEmoji): not documented fully - GuildPreviewEmoji * feat(BaseEmoji): update typings * fix: remove duplicate typing properties - inherited * fix: remove redundant methods & properties - inherited / already set * fix: let -> const * fix: typings - put BaseEmoji after BaseClient * fix: remove _clone method - redundant * refactor(GuildPreview): emojis should be a collection * refactor: rename base class, move relevant props there and expose roles * fix(GuildPreview): update emojis in _patch * fix(Typings): remove empty line, add Client#fetchGuildPreview * feat: export GuildPreview * fix(Typings): add GuildPreview#discoverSplash, icon, and splash Co-authored-by: LxveFades <twitchisadeck@gmail.com> Co-authored-by: Crawl <icrawltogo@gmail.com> Co-authored-by: SpaceEEC <spaceeec@yahoo.com>
2026-03-11 09:03:29 +01:00 · 2020-03-27 20:57:28 +01:00
parent fee9a218e8
commit 88133d0d77
9 changed files with 328 additions and 57 deletions
--- a/src/structures/GuildPreview.js
+++ b/src/structures/GuildPreview.js
@@ -0,0 +1,157 @@
+'use strict';
+
+const Base = require('./Base');
+const GuildPreviewEmoji = require('./GuildPreviewEmoji');
+const Collection = require('../util/Collection');
+
+/**
+ * Represents the data about the guild any bot can preview, connected to the specified public guild.
+ * @extends {Base}
+ */
+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) {
+      /**
+       * Collection of emojis belonging to this public guild
+       * @type {Collection<Snowflake, GuildPreviewEmoji>}
+       */
+      this.emojis = new Collection();
+    } else {
+      this.emojis.clear();
+    }
+    for (const emoji of data.emojis) {
+      this.emojis.set(emoji.id, new GuildPreviewEmoji(this.client, emoji, this));
+    }
+  }
+
+  /**
+   * 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.DiscoverySplash(this.id, this.discoverySplash, format, size);
+  }
+
+  /**
+   * 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();
+    return json;
+  }
+}
+
+module.exports = GuildPreview;