@velliajs/discord 1.0.0

package/src/structures/Embed.js

@@ -0,0 +1,220 @@
+'use strict';
+
+const { embedLength } = require('@discordjs/builders');
+const isEqual = require('fast-deep-equal');
+
+/**
+ * Represents an embed.
+ */
+class Embed {
+  constructor(data) {
+    /**
+     * The API embed data.
+     * @type {APIEmbed}
+     * @readonly
+     */
+    this.data = { ...data };
+  }
+
+  /**
+   * An array of fields of this embed.
+   * @type {Array<APIEmbedField>}
+   * @readonly
+   */
+  get fields() {
+    return this.data.fields ?? [];
+  }
+
+  /**
+   * The title of this embed.
+   * @type {?string}
+   * @readonly
+   */
+  get title() {
+    return this.data.title ?? null;
+  }
+
+  /**
+   * The description of this embed.
+   * @type {?string}
+   * @readonly
+   */
+  get description() {
+    return this.data.description ?? null;
+  }
+
+  /**
+   * The URL of this embed.
+   * @type {?string}
+   * @readonly
+   */
+  get url() {
+    return this.data.url ?? null;
+  }
+
+  /**
+   * The color of this embed.
+   * @type {?number}
+   * @readonly
+   */
+  get color() {
+    return this.data.color ?? null;
+  }
+
+  /**
+   * The timestamp of this embed. This is in an ISO 8601 format.
+   * @type {?string}
+   * @readonly
+   */
+  get timestamp() {
+    return this.data.timestamp ?? null;
+  }
+
+  /**
+   * @typedef {Object} EmbedAssetData
+   * @property {?string} url The URL of the image
+   * @property {?string} proxyURL The proxy URL of the image
+   * @property {?number} height The height of the image
+   * @property {?number} width The width of the image
+   */
+
+  /**
+   * The thumbnail of this embed.
+   * @type {?EmbedAssetData}
+   * @readonly
+   */
+  get thumbnail() {
+    if (!this.data.thumbnail) return null;
+    return {
+      url: this.data.thumbnail.url,
+      proxyURL: this.data.thumbnail.proxy_url,
+      height: this.data.thumbnail.height,
+      width: this.data.thumbnail.width,
+    };
+  }
+
+  /**
+   * The image of this embed.
+   * @type {?EmbedAssetData}
+   * @readonly
+   */
+  get image() {
+    if (!this.data.image) return null;
+    return {
+      url: this.data.image.url,
+      proxyURL: this.data.image.proxy_url,
+      height: this.data.image.height,
+      width: this.data.image.width,
+    };
+  }
+
+  /**
+   * The video of this embed.
+   * @type {?EmbedAssetData}
+   * @readonly
+   */
+  get video() {
+    if (!this.data.video) return null;
+    return {
+      url: this.data.video.url,
+      proxyURL: this.data.video.proxy_url,
+      height: this.data.video.height,
+      width: this.data.video.width,
+    };
+  }
+
+  /**
+   * @typedef {Object} EmbedAuthorData
+   * @property {string} name The name of the author
+   * @property {?string} url The URL of the author
+   * @property {?string} iconURL The icon URL of the author
+   * @property {?string} proxyIconURL The proxy icon URL of the author
+   */
+
+  /**
+   * The author of this embed.
+   * @type {?EmbedAuthorData}
+   * @readonly
+   */
+  get author() {
+    if (!this.data.author) return null;
+    return {
+      name: this.data.author.name,
+      url: this.data.author.url,
+      iconURL: this.data.author.icon_url,
+      proxyIconURL: this.data.author.proxy_icon_url,
+    };
+  }
+
+  /**
+   * The provider of this embed.
+   * @type {?APIEmbedProvider}
+   * @readonly
+   */
+  get provider() {
+    return this.data.provider ?? null;
+  }
+
+  /**
+   * @typedef {Object} EmbedFooterData
+   * @property {string} text The text of the footer
+   * @property {?string} iconURL The URL of the icon
+   * @property {?string} proxyIconURL The proxy URL of the icon
+   */
+
+  /**
+   * The footer of this embed.
+   * @type {?EmbedFooterData}
+   * @readonly
+   */
+  get footer() {
+    if (!this.data.footer) return null;
+    return {
+      text: this.data.footer.text,
+      iconURL: this.data.footer.icon_url,
+      proxyIconURL: this.data.footer.proxy_icon_url,
+    };
+  }
+
+  /**
+   * The accumulated length for the embed title, description, fields, footer text, and author name.
+   * @type {number}
+   * @readonly
+   */
+  get length() {
+    return embedLength(this.data);
+  }
+
+  /**
+   * The hex color of this embed.
+   * @type {?string}
+   * @readonly
+   */
+  get hexColor() {
+    return typeof this.data.color === 'number'
+      ? `#${this.data.color.toString(16).padStart(6, '0')}`
+      : this.data.color ?? null;
+  }
+
+  /**
+   * Returns the API-compatible JSON for this embed.
+   * @returns {APIEmbed}
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+
+  /**
+   * Whether the given embeds are equal.
+   * @param {Embed|APIEmbed} other The embed to compare against
+   * @returns {boolean}
+   */
+  equals(other) {
+    if (other instanceof Embed) {
+      return isEqual(other.data, this.data);
+    }
+    return isEqual(other, this.data);
+  }
+}
+
+module.exports = Embed;

package/src/structures/EmbedBuilder.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const { EmbedBuilder: BuildersEmbed } = require('@discordjs/builders');
+const { isJSONEncodable } = require('@discordjs/util');
+const { toSnakeCase } = require('../util/Transformers');
+const { resolveColor } = require('../util/Util');
+
+/**
+ * Represents an embed builder.
+ * @extends {BuildersEmbed}
+ */
+class EmbedBuilder extends BuildersEmbed {
+  constructor(data) {
+    super(toSnakeCase(data));
+  }
+
+  /**
+   * Sets the color of this embed
+   * @param {?ColorResolvable} color The color of the embed
+   * @returns {EmbedBuilder}
+   */
+  setColor(color) {
+    return super.setColor(color && resolveColor(color));
+  }
+
+  /**
+   * Creates a new embed builder from JSON data
+   * @param {EmbedBuilder|Embed|APIEmbed} other The other data
+   * @returns {EmbedBuilder}
+   */
+  static from(other) {
+    return new this(isJSONEncodable(other) ? other.toJSON() : other);
+  }
+}
+
+module.exports = EmbedBuilder;
+
+/**
+ * @external BuildersEmbed
+ * @see {@link https://discord.js.org/docs/packages/builders/stable/EmbedBuilder:Class}
+ */

package/src/structures/Emoji.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const { DiscordSnowflake } = require('@sapphire/snowflake');
+const Base = require('./Base');
+
+/**
+ * Represents raw emoji data from the API
+ * @typedef {APIEmoji} RawEmoji
+ * @property {?Snowflake} id The emoji's id
+ * @property {?string} name The emoji's name
+ * @property {?boolean} animated Whether the emoji is animated
+ */
+
+/**
+ * Represents an emoji, see {@link GuildEmoji} and {@link ReactionEmoji}.
+ * @extends {Base}
+ */
+class Emoji extends Base {
+  constructor(client, emoji) {
+    super(client);
+    /**
+     * Whether or not the emoji is animated
+     * @type {?boolean}
+     */
+    this.animated = emoji.animated ?? null;
+
+    /**
+     * The emoji's name
+     * @type {?string}
+     */
+    this.name = emoji.name ?? null;
+
+    /**
+     * The emoji's id
+     * @type {?Snowflake}
+     */
+    this.id = emoji.id;
+  }
+
+  /**
+   * The identifier of this emoji, used for message reactions
+   * @type {string}
+   * @readonly
+   */
+  get identifier() {
+    if (this.id) return `${this.animated ? 'a:' : ''}${this.name}:${this.id}`;
+    return encodeURIComponent(this.name);
+  }
+
+  /**
+   * The URL to the emoji file if it's a custom emoji
+   * @type {?string}
+   * @readonly
+   */
+  get url() {
+    return this.id && this.client.rest.cdn.emoji(this.id, this.animated ? 'gif' : 'png');
+  }
+
+  /**
+   * The timestamp the emoji was created at, or null if unicode
+   * @type {?number}
+   * @readonly
+   */
+  get createdTimestamp() {
+    return this.id && DiscordSnowflake.timestampFrom(this.id);
+  }
+
+  /**
+   * The time the emoji was created at, or null if unicode
+   * @type {?Date}
+   * @readonly
+   */
+  get createdAt() {
+    return this.id && new Date(this.createdTimestamp);
+  }
+
+  /**
+   * When concatenated with a string, this automatically returns the text required to form a graphical emoji on Discord
+   * instead of the Emoji object.
+   * @returns {string}
+   * @example
+   * // Send a custom emoji from a guild:
+   * const emoji = guild.emojis.cache.first();
+   * msg.channel.send(`Hello! ${emoji}`);
+   * @example
+   * // Send the emoji used in a reaction to the channel the reaction is part of
+   * reaction.message.channel.send(`The emoji used was: ${reaction.emoji}`);
+   */
+  toString() {
+    return this.id ? `<${this.animated ? 'a' : ''}:${this.name}:${this.id}>` : this.name;
+  }
+
+  toJSON() {
+    return super.toJSON({
+      guild: 'guildId',
+      createdTimestamp: true,
+      url: true,
+      identifier: true,
+    });
+  }
+}
+
+exports.Emoji = Emoji;
+
+/**
+ * @external APIEmoji
+ * @see {@link https://discord.com/developers/docs/resources/emoji#emoji-object}
+ */

package/src/structures/ForumChannel.js

@@ -0,0 +1,264 @@
+'use strict';
+
+const GuildChannel = require('./GuildChannel');
+const TextBasedChannel = require('./interfaces/TextBasedChannel');
+const GuildForumThreadManager = require('../managers/GuildForumThreadManager');
+const { transformAPIGuildForumTag, transformAPIGuildDefaultReaction } = require('../util/Channels');
+
+/**
+ * @typedef {Object} GuildForumTagEmoji
+ * @property {?Snowflake} id The id of a guild's custom emoji
+ * @property {?string} name The unicode character of the emoji
+ */
+
+/**
+ * @typedef {Object} GuildForumTag
+ * @property {Snowflake} id The id of the tag
+ * @property {string} name The name of the tag
+ * @property {boolean} moderated Whether this tag can only be added to or removed from threads
+ * by a member with the `ManageThreads` permission
+ * @property {?GuildForumTagEmoji} emoji The emoji of this tag
+ */
+
+/**
+ * @typedef {Object} GuildForumTagData
+ * @property {Snowflake} [id] The id of the tag
+ * @property {string} name The name of the tag
+ * @property {boolean} [moderated] Whether this tag can only be added to or removed from threads
+ * by a member with the `ManageThreads` permission
+ * @property {?GuildForumTagEmoji} [emoji] The emoji of this tag
+ */
+
+/**
+ * @typedef {Object} DefaultReactionEmoji
+ * @property {?Snowflake} id The id of a guild's custom emoji
+ * @property {?string} name The unicode character of the emoji
+ */
+
+/**
+ * Represents a channel that only contains threads
+ * @extends {GuildChannel}
+ * @implements {TextBasedChannel}
+ */
+class ForumChannel extends GuildChannel {
+  constructor(guild, data, client) {
+    super(guild, data, client, false);
+
+    /**
+     * A manager of the threads belonging to this channel
+     * @type {GuildForumThreadManager}
+     */
+    this.threads = new GuildForumThreadManager(this);
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    super._patch(data);
+    if ('available_tags' in data) {
+      /**
+       * The set of tags that can be used in this channel.
+       * @type {GuildForumTag[]}
+       */
+      this.availableTags = data.available_tags.map(tag => transformAPIGuildForumTag(tag));
+    } else {
+      this.availableTags ??= [];
+    }
+
+    if ('default_reaction_emoji' in data) {
+      /**
+       * The emoji to show in the add reaction button on a thread in a guild forum channel
+       * @type {?DefaultReactionEmoji}
+       */
+      this.defaultReactionEmoji = data.default_reaction_emoji
+        ? transformAPIGuildDefaultReaction(data.default_reaction_emoji)
+        : null;
+    } else {
+      this.defaultReactionEmoji ??= null;
+    }
+
+    if ('default_thread_rate_limit_per_user' in data) {
+      /**
+       * The initial rate limit per user (slowmode) to set on newly created threads in a channel.
+       * @type {?number}
+       */
+      this.defaultThreadRateLimitPerUser = data.default_thread_rate_limit_per_user;
+    } else {
+      this.defaultThreadRateLimitPerUser ??= null;
+    }
+
+    if ('rate_limit_per_user' in data) {
+      /**
+       * The rate limit per user (slowmode) for this channel.
+       * @type {?number}
+       */
+      this.rateLimitPerUser = data.rate_limit_per_user;
+    } else {
+      this.rateLimitPerUser ??= null;
+    }
+
+    if ('default_auto_archive_duration' in data) {
+      /**
+       * The default auto archive duration for newly created threads in this channel.
+       * @type {?ThreadAutoArchiveDuration}
+       */
+      this.defaultAutoArchiveDuration = data.default_auto_archive_duration;
+    } else {
+      this.defaultAutoArchiveDuration ??= null;
+    }
+
+    if ('nsfw' in data) {
+      /**
+       * If this channel is considered NSFW.
+       * @type {boolean}
+       */
+      this.nsfw = data.nsfw;
+    } else {
+      this.nsfw ??= false;
+    }
+
+    if ('topic' in data) {
+      /**
+       * The topic of this channel.
+       * @type {?string}
+       */
+      this.topic = data.topic;
+    }
+
+    if ('default_sort_order' in data) {
+      /**
+       * The default sort order mode used to order posts
+       * @type {?SortOrderType}
+       */
+      this.defaultSortOrder = data.default_sort_order;
+    } else {
+      this.defaultSortOrder ??= null;
+    }
+
+    /**
+     * The default layout type used to display posts
+     * @type {ForumLayoutType}
+     */
+    this.defaultForumLayout = data.default_forum_layout;
+  }
+
+  /**
+   * Sets the available tags for this forum channel
+   * @param {GuildForumTagData[]} availableTags The tags to set as available in this channel
+   * @param {string} [reason] Reason for changing the available tags
+   * @returns {Promise<ForumChannel>}
+   */
+  setAvailableTags(availableTags, reason) {
+    return this.edit({ availableTags, reason });
+  }
+
+  /**
+   * Sets the default reaction emoji for this channel
+   * @param {?DefaultReactionEmoji} defaultReactionEmoji The emoji to set as the default reaction emoji
+   * @param {string} [reason] Reason for changing the default reaction emoji
+   * @returns {Promise<ForumChannel>}
+   */
+  setDefaultReactionEmoji(defaultReactionEmoji, reason) {
+    return this.edit({ defaultReactionEmoji, reason });
+  }
+
+  /**
+   * Sets the default rate limit per user (slowmode) for new threads in this channel
+   * @param {number} defaultThreadRateLimitPerUser The rate limit to set on newly created threads in this channel
+   * @param {string} [reason] Reason for changing the default rate limit
+   * @returns {Promise<ForumChannel>}
+   */
+  setDefaultThreadRateLimitPerUser(defaultThreadRateLimitPerUser, reason) {
+    return this.edit({ defaultThreadRateLimitPerUser, reason });
+  }
+
+  /**
+   * Creates an invite to this guild channel.
+   * @param {InviteCreateOptions} [options={}] The options for creating the invite
+   * @returns {Promise<Invite>}
+   * @example
+   * // Create an invite to a channel
+   * channel.createInvite()
+   *   .then(invite => console.log(`Created an invite with a code of ${invite.code}`))
+   *   .catch(console.error);
+   */
+  createInvite(options) {
+    return this.guild.invites.create(this.id, options);
+  }
+
+  /**
+   * Fetches a collection of invites to this guild channel.
+   * Resolves with a collection mapping invites by their codes.
+   * @param {boolean} [cache=true] Whether to cache the fetched invites
+   * @returns {Promise<Collection<string, Invite>>}
+   */
+  fetchInvites(cache) {
+    return this.guild.invites.fetch({ channelId: this.id, cache });
+  }
+
+  /**
+   * Sets the default auto archive duration for all newly created threads in this channel.
+   * @param {ThreadAutoArchiveDuration} defaultAutoArchiveDuration The new default auto archive duration
+   * @param {string} [reason] Reason for changing the channel's default auto archive duration
+   * @returns {Promise<ForumChannel>}
+   */
+  setDefaultAutoArchiveDuration(defaultAutoArchiveDuration, reason) {
+    return this.edit({ defaultAutoArchiveDuration, reason });
+  }
+
+  /**
+   * Sets a new topic for the guild channel.
+   * @param {?string} topic The new topic for the guild channel
+   * @param {string} [reason] Reason for changing the guild channel's topic
+   * @returns {Promise<ForumChannel>}
+   * @example
+   * // Set a new channel topic
+   * channel.setTopic('needs more rate limiting')
+   *   .then(newChannel => console.log(`Channel's new topic is ${newChannel.topic}`))
+   *   .catch(console.error);
+   */
+  setTopic(topic, reason) {
+    return this.edit({ topic, reason });
+  }
+
+  /**
+   * Sets the default sort order mode used to order posts
+   * @param {?SortOrderType} defaultSortOrder The default sort order mode to set on this channel
+   * @param {string} [reason] Reason for changing the default sort order
+   * @returns {Promise<ForumChannel>}
+   */
+  setDefaultSortOrder(defaultSortOrder, reason) {
+    return this.edit({ defaultSortOrder, reason });
+  }
+
+  /**
+   * Sets the default forum layout type used to display posts
+   * @param {ForumLayoutType} defaultForumLayout The default forum layout type to set on this channel
+   * @param {string} [reason] Reason for changing the default forum layout
+   * @returns {Promise<ForumChannel>}
+   */
+  setDefaultForumLayout(defaultForumLayout, reason) {
+    return this.edit({ defaultForumLayout, reason });
+  }
+
+  // These are here only for documentation purposes - they are implemented by TextBasedChannel
+  /* eslint-disable no-empty-function */
+  createWebhook() {}
+  fetchWebhooks() {}
+  setNSFW() {}
+  setRateLimitPerUser() {}
+}
+
+TextBasedChannel.applyToClass(ForumChannel, true, [
+  'send',
+  'lastMessage',
+  'lastPinAt',
+  'bulkDelete',
+  'sendTyping',
+  'createMessageCollector',
+  'awaitMessages',
+  'createMessageComponentCollector',
+  'awaitMessageComponent',
+]);
+
+module.exports = ForumChannel;