discord-sb.js 1.0.0

package/src/structures/MessageReaction.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const GuildEmoji = require('./GuildEmoji');
+const ReactionEmoji = require('./ReactionEmoji');
+const ReactionUserManager = require('../managers/ReactionUserManager');
+const Util = require('../util/Util');
+
+/**
+ * Represents a reaction to a message.
+ */
+class MessageReaction {
+  constructor(client, data, message) {
+    /**
+     * The client that instantiated this message reaction
+     * @name MessageReaction#client
+     * @type {Client}
+     * @readonly
+     */
+    Object.defineProperty(this, 'client', { value: client });
+
+    /**
+     * The message that this reaction refers to
+     * @type {Message}
+     */
+    this.message = message;
+
+    /**
+     * Whether the client has given this reaction
+     * @type {boolean}
+     */
+    this.me = data.me;
+
+    /**
+     * Whether the client has super-reacted using this emoji
+     * @type {boolean}
+     */
+    this.meBurst = Boolean(data.me_burst);
+
+    /**
+     * A manager of the users that have given this reaction
+     * @type {ReactionUserManager}
+     */
+    this.users = new ReactionUserManager(this, this.me ? [client.user] : []);
+
+    this._emoji = new ReactionEmoji(this, data.emoji);
+
+    this.burstColors = null;
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if (data.burst_colors) {
+      /**
+       * Hexadecimal colors used for this super reaction
+       * @type {?string[]}
+       */
+      this.burstColors = data.burst_colors;
+    }
+
+    if ('count' in data) {
+      /**
+       * The number of people that have given the same reaction
+       * @type {?number}
+       */
+      this.count ??= data.count;
+    }
+
+    if ('count_details' in data) {
+      /**
+       * The reaction count details object contains information about super and normal reaction counts.
+       * @typedef {Object} ReactionCountDetailsData
+       * @property {number} burst Count of super reactions
+       * @property {number} normal Count of normal reactions
+       */
+
+      /**
+       * The reaction count details object contains information about super and normal reaction counts.
+       * @type {ReactionCountDetailsData}
+       */
+      this.countDetails = {
+        burst: data.count_details.burst,
+        normal: data.count_details.normal,
+      };
+    } else {
+      this.countDetails ??= { burst: 0, normal: 0 };
+    }
+  }
+
+  /**
+   * Removes all users from this reaction.
+   * @returns {Promise<MessageReaction>}
+   */
+  async remove() {
+    await this.client.api
+      .channels(this.message.channelId)
+      .messages(this.message.id)
+      .reactions(this._emoji.identifier)
+      .delete();
+    return this;
+  }
+
+  /**
+   * The emoji of this reaction. Either a {@link GuildEmoji} object for known custom emojis, or a {@link ReactionEmoji}
+   * object which has fewer properties. Whatever the prototype of the emoji, it will still have
+   * `name`, `id`, `identifier` and `toString()`
+   * @type {GuildEmoji|ReactionEmoji}
+   * @readonly
+   */
+  get emoji() {
+    if (this._emoji instanceof GuildEmoji) return this._emoji;
+    // Check to see if the emoji has become known to the client
+    if (this._emoji.id) {
+      const emojis = this.message.client.emojis.cache;
+      if (emojis.has(this._emoji.id)) {
+        const emoji = emojis.get(this._emoji.id);
+        this._emoji = emoji;
+        return emoji;
+      }
+    }
+    return this._emoji;
+  }
+
+  /**
+   * Whether or not this reaction is a partial
+   * @type {boolean}
+   * @readonly
+   */
+  get partial() {
+    return this.count === null;
+  }
+
+  /**
+   * Fetch this reaction.
+   * @returns {Promise<MessageReaction>}
+   */
+  async fetch() {
+    const message = await this.message.fetch();
+    const existing = message.reactions.cache.get(this.emoji.id ?? this.emoji.name);
+    // The reaction won't get set when it has been completely removed
+    this._patch(existing ?? { count: 0 });
+    return this;
+  }
+
+  toJSON() {
+    return Util.flatten(this, { emoji: 'emojiId', message: 'messageId' });
+  }
+
+  _add(user, burst) {
+    if (this.partial) return;
+    this.users.cache.set(user.id, user);
+    if (!this.me || user.id !== this.message.client.user.id || this.count === 0) {
+      this.count++;
+      if (burst) this.countDetails.burst++;
+      else this.countDetails.normal++;
+    }
+    if (user.id === this.message.client.user.id) {
+      if (burst) this.meBurst = true;
+      else this.me = true;
+    }
+  }
+
+  _remove(user, burst) {
+    if (this.partial) return;
+    this.users.cache.delete(user.id);
+    if (!this.me || user.id !== this.message.client.user.id) {
+      this.count--;
+      if (burst) this.countDetails.burst--;
+      else this.countDetails.normal--;
+    }
+    if (user.id === this.message.client.user.id) {
+      if (burst) this.meBurst = false;
+      else this.me = false;
+    }
+    if (this.count <= 0 && this.users.cache.size === 0) {
+      this.message.reactions.cache.delete(this.emoji.id ?? this.emoji.name);
+    }
+  }
+}
+
+module.exports = MessageReaction;

package/src/structures/MessageSelectMenu.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const BaseMessageComponent = require('./BaseMessageComponent');
+const { ChannelTypes, MessageComponentTypes } = require('../util/Constants');
+const Util = require('../util/Util');
+
+/**
+ * Represents a select menu message component
+ * @extends {BaseMessageComponent}
+ */
+class MessageSelectMenu extends BaseMessageComponent {
+  /**
+   * @typedef {BaseMessageComponentOptions} MessageSelectMenuOptions
+   * @property {string} [customId] A unique string to be sent in the interaction when clicked
+   * @property {string} [placeholder] Custom placeholder text to display when nothing is selected
+   * @property {number} [minValues] The minimum number of selections required
+   * @property {number} [maxValues] The maximum number of selections allowed
+   * @property {MessageSelectOption[]} [options] Options for the select menu
+   * @property {boolean} [disabled=false] Disables the select menu to prevent interactions
+   * @property {ChannelType[]} [channelTypes] List of channel types to include in the ChannelSelect component
+   */
+
+  /**
+   * @typedef {Object} MessageSelectOption
+   * @property {string} label The text to be displayed on this option
+   * @property {string} value The value to be sent for this option
+   * @property {?string} description Optional description to show for this option
+   * @property {?RawEmoji} emoji Emoji to display for this option
+   * @property {boolean} default Render this option as the default selection
+   */
+
+  /**
+   * @typedef {Object} MessageSelectOptionData
+   * @property {string} label The text to be displayed on this option
+   * @property {string} value The value to be sent for this option
+   * @property {string} [description] Optional description to show for this option
+   * @property {EmojiIdentifierResolvable} [emoji] Emoji to display for this option
+   * @property {boolean} [default] Render this option as the default selection
+   */
+
+  /**
+   * @param {MessageSelectMenu|MessageSelectMenuOptions} [data={}] MessageSelectMenu to clone or raw data
+   */
+  constructor(data = {}) {
+    super({ type: BaseMessageComponent.resolveType(data.type) ?? 'STRING_SELECT' });
+
+    this.setup(data);
+  }
+
+  setup(data) {
+    super.setup(data);
+    /**
+     * A unique string to be sent in the interaction when clicked
+     * @type {?string}
+     */
+    this.customId = data.custom_id ?? data.customId ?? null;
+
+    /**
+     * Custom placeholder text to display when nothing is selected
+     * @type {?string}
+     */
+    this.placeholder = data.placeholder ?? null;
+
+    /**
+     * The minimum number of selections required
+     * @type {?number}
+     */
+    this.minValues = data.min_values ?? data.minValues ?? null;
+
+    /**
+     * The maximum number of selections allowed
+     * @type {?number}
+     */
+    this.maxValues = data.max_values ?? data.maxValues ?? null;
+
+    /**
+     * Options for the STRING_SELECT menu
+     * @type {MessageSelectOption[]}
+     */
+    this.options = this.constructor.normalizeOptions(data.options ?? []);
+
+    /**
+     * Whether this select menu is currently disabled
+     * @type {boolean}
+     */
+    this.disabled = data.disabled ?? false;
+
+    /**
+     * Channels that are possible to select in CHANNEL_SELECT menu
+     * @type {ChannelType[]}
+     */
+    this.channelTypes =
+      data.channel_types?.map(channelType =>
+        typeof channelType === 'string' ? channelType : ChannelTypes[channelType],
+      ) ?? [];
+  }
+
+  /**
+   * Transforms the select menu into a plain object
+   * @returns {APIMessageSelectMenu} The raw data of this select menu
+   */
+  toJSON() {
+    return {
+      channel_types: this.channelTypes.map(type => (typeof type === 'string' ? ChannelTypes[type] : type)),
+      custom_id: this.customId,
+      disabled: this.disabled,
+      placeholder: this.placeholder,
+      min_values: this.minValues,
+      max_values: this.maxValues ?? (this.minValues ? this.options.length : undefined),
+      options: this.options,
+      type: typeof this.type === 'string' ? MessageComponentTypes[this.type] : this.type,
+    };
+  }
+
+  /**
+   * Normalizes option input and resolves strings and emojis.
+   * @param {MessageSelectOptionData} option The select menu option to normalize
+   * @returns {MessageSelectOption}
+   */
+  static normalizeOption(option) {
+    let { label, value, description, emoji } = option;
+
+    label = Util.verifyString(label, RangeError, 'SELECT_OPTION_LABEL');
+    value = Util.verifyString(value, RangeError, 'SELECT_OPTION_VALUE');
+    emoji = emoji ? Util.resolvePartialEmoji(emoji) : null;
+    description = description ? Util.verifyString(description, RangeError, 'SELECT_OPTION_DESCRIPTION', true) : null;
+
+    return { label, value, description, emoji, default: option.default ?? false };
+  }
+
+  /**
+   * Normalizes option input and resolves strings and emojis.
+   * @param {...MessageSelectOptionData|MessageSelectOptionData[]} options The select menu options to normalize
+   * @returns {MessageSelectOption[]}
+   */
+  static normalizeOptions(...options) {
+    return options.flat(Infinity).map(option => this.normalizeOption(option));
+  }
+}
+
+module.exports = MessageSelectMenu;

package/src/structures/Modal.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const BaseMessageComponent = require('./BaseMessageComponent');
+const { InteractionTypes } = require('../util/Constants');
+const SnowflakeUtil = require('../util/SnowflakeUtil');
+const Util = require('../util/Util');
+
+/**
+ * Represents a modal (form) to be shown in response to an interaction
+ */
+class Modal {
+  /**
+   * @param {Object} data Modal to clone or raw data
+   * @param {Client} client The client constructing this Modal, if provided
+   */
+  constructor(data = {}, client = null) {
+    /**
+     * A list of MessageActionRows in the modal
+     * @type {MessageActionRow[]}
+     */
+    this.components = data.components?.map(c => BaseMessageComponent.create(c, client)) ?? [];
+
+    /**
+     * A unique string to be sent in the interaction when submitted
+     * @type {?string}
+     */
+    this.customId = data.custom_id;
+
+    /**
+     * The title to be displayed on this modal
+     * @type {?string}
+     */
+    this.title = data.title;
+
+    /**
+     * Timestamp (Discord epoch) of when this modal was created
+     * @type {Snowflake}
+     */
+    this.nonce = data.nonce;
+
+    /**
+     * ID slash / button / menu when modal is displayed
+     * @type {Snowflake}
+     */
+    this.id = data.id;
+
+    /**
+     * Application sending the modal
+     * @type {Snowflake}
+     */
+    this.applicationId = data.application.id;
+
+    /**
+     * The id of the channel the message was sent in
+     * @type {Snowflake}
+     */
+    this.channelId = data.channel_id;
+
+    /**
+     * Whether this interaction has already been replied to
+     * @type {boolean}
+     */
+    this.replied = false;
+
+    Object.defineProperty(this, 'client', {
+      value: client,
+      writable: false,
+    });
+  }
+
+  /**
+   * The id of the guild the message was sent in, if any
+   * @type {?Snowflake}
+   * @readonly
+   */
+  get guildId() {
+    return this.client.channels.cache.get(this.channelId)?.guildId || null;
+  }
+
+  /**
+   * The channel that the message was sent in
+   * @type {TextBasedChannels}
+   * @readonly
+   */
+  get channel() {
+    return this.client.channels.resolve(this.channelId);
+  }
+
+  /**
+   * The guild the message was sent in (if in a guild channel)
+   * @type {?Guild}
+   * @readonly
+   */
+  get guild() {
+    return this.client.guilds.resolve(this.guildId) ?? this.channel?.guild ?? null;
+  }
+
+  toJSON() {
+    return {
+      components: this.components.map(c => c.toJSON()),
+      custom_id: this.customId,
+      title: this.title,
+      id: this.id,
+    };
+  }
+
+  /**
+   * Reply to this modal with data. (Event only)
+   * @returns {Promise<Message|Modal>}
+   * @example
+   * client.on('interactionModalCreate', modal => {
+   *    // Modal > ActionRow > TextInput
+   *    modal.components[0].components[0].setValue('1+1');
+   *    modal.components[1].components[0].setValue('hello');
+   *    modal.reply();
+   * })
+   */
+  reply() {
+    if (!this.applicationId || !this.client || !this.channelId || this.replied) throw new Error('Modal cannot reply');
+    // Get Object
+    const dataFinal = this.toJSON();
+    dataFinal.components = dataFinal.components
+      .map(c => {
+        c.components[0] = {
+          type: c.components[0].type,
+          value: c.components[0].value,
+          custom_id: c.components[0].custom_id,
+        };
+        return c;
+      })
+      .filter(c => typeof c.components[0].value == 'string');
+    delete dataFinal.title;
+    const nonce = SnowflakeUtil.generate();
+    const postData = {
+      type: InteractionTypes.MODAL_SUBMIT, // Modal
+      application_id: this.applicationId,
+      guild_id: this.guildId,
+      channel_id: this.channelId,
+      data: dataFinal,
+      nonce,
+      session_id: this.client.sessionId,
+    };
+    this.client.api.interactions.post({
+      data: postData,
+    });
+    this.replied = true;
+    return Util.createPromiseInteraction(this.client, nonce, 5_000, true, this);
+  }
+
+  // TypeScript
+  /**
+   * Check data
+   * @type {boolean}
+   * @readonly
+   */
+  get isMessage() {
+    return false;
+  }
+}
+
+module.exports = Modal;

package/src/structures/ModalSubmitFieldsResolver.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const { TypeError } = require('../errors');
+const { MessageComponentTypes } = require('../util/Constants');
+
+/**
+ * A resolver for modal submit interaction text inputs.
+ */
+class ModalSubmitFieldsResolver {
+  constructor(components) {
+    /**
+     * The components within the modal
+     * @type {PartialModalActionRow[]} The components in the modal
+     */
+    this.components = components;
+  }
+
+  /**
+   * The extracted fields from the modal
+   * @type {PartialInputTextData[]} The fields in the modal
+   * @private
+   */
+  get _fields() {
+    return this.components.reduce((previous, next) => previous.concat(next.components), []);
+  }
+
+  /**
+   * Gets a field given a custom id from a component
+   * @param {string} customId The custom id of the component
+   * @returns {?PartialInputTextData}
+   */
+  getField(customId) {
+    const field = this._fields.find(f => f.customId === customId);
+    if (!field) throw new TypeError('MODAL_SUBMIT_INTERACTION_FIELD_NOT_FOUND', customId);
+    return field;
+  }
+
+  /**
+   * Gets the value of a text input component given a custom id
+   * @param {string} customId The custom id of the text input component
+   * @returns {?string}
+   */
+  getTextInputValue(customId) {
+    const field = this.getField(customId);
+    const expectedType = MessageComponentTypes[MessageComponentTypes.TEXT_INPUT];
+    if (field.type !== expectedType) {
+      throw new TypeError('MODAL_SUBMIT_INTERACTION_FIELD_TYPE', customId, field.type, expectedType);
+    }
+    return field.value;
+  }
+}
+
+module.exports = ModalSubmitFieldsResolver;

package/src/structures/ModalSubmitInteraction.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const Interaction = require('./Interaction');
+const InteractionWebhook = require('./InteractionWebhook');
+const ModalSubmitFieldsResolver = require('./ModalSubmitFieldsResolver');
+const InteractionResponses = require('./interfaces/InteractionResponses');
+const { MessageComponentTypes } = require('../util/Constants');
+
+/**
+ * Represents a modal submit interaction.
+ * @extends {Interaction}
+ * @implements {InteractionResponses}
+ */
+class ModalSubmitInteraction extends Interaction {
+  constructor(client, data) {
+    super(client, data);
+
+    /**
+     * The custom id of the modal.
+     * @type {string}
+     */
+    this.customId = data.data.custom_id;
+
+    /**
+     * @typedef {Object} PartialTextInputData
+     * @property {string} [customId] A unique string to be sent in the interaction when submitted
+     * @property {MessageComponentType} [type] The type of this component
+     * @property {string} [value] Value of this text input component
+     */
+
+    /**
+     * @typedef {Object} PartialModalActionRow
+     * @property {MessageComponentType} [type] The type of this component
+     * @property {PartialTextInputData[]} [components] Partial text input components
+     */
+
+    /**
+     * The inputs within the modal
+     * @type {PartialModalActionRow[]}
+     */
+    this.components =
+      data.data.components?.map(c => ({
+        type: MessageComponentTypes[c.type],
+        components: ModalSubmitInteraction.transformComponent(c),
+      })) ?? [];
+
+    /**
+     * The message associated with this interaction
+     * @type {Message|APIMessage|null}
+     */
+    this.message = data.message ? this.channel?.messages._add(data.message) ?? data.message : null;
+
+    /**
+     * The fields within the modal
+     * @type {ModalSubmitFieldsResolver}
+     */
+    this.fields = new ModalSubmitFieldsResolver(this.components);
+
+    /**
+     * Whether the reply to this interaction has been deferred
+     * @type {boolean}
+     */
+    this.deferred = false;
+
+    /**
+     * Whether the reply to this interaction is ephemeral
+     * @type {?boolean}
+     */
+    this.ephemeral = null;
+
+    /**
+     * Whether this interaction has already been replied to
+     * @type {boolean}
+     */
+    this.replied = false;
+
+    /**
+     * An associated interaction webhook, can be used to further interact with this interaction
+     * @type {InteractionWebhook}
+     */
+    this.webhook = new InteractionWebhook(this.client, this.applicationId, this.token);
+  }
+
+  /**
+   * Transforms component data to discord.js-compatible data
+   * @param {*} rawComponent The data to transform
+   * @returns {PartialTextInputData[]}
+   */
+  static transformComponent(rawComponent) {
+    return rawComponent.components.map(c => ({
+      value: c.value,
+      type: MessageComponentTypes[c.type],
+      customId: c.custom_id,
+    }));
+  }
+
+  /**
+   * Whether this is from a {@link MessageComponentInteraction}.
+   * @returns {boolean}
+   */
+  isFromMessage() {
+    return Boolean(this.message);
+  }
+
+  // These are here only for documentation purposes - they are implemented by InteractionResponses
+  /* eslint-disable no-empty-function */
+  deferReply() {}
+  reply() {}
+  fetchReply() {}
+  editReply() {}
+  deleteReply() {}
+  followUp() {}
+  update() {}
+  deferUpdate() {}
+}
+
+InteractionResponses.applyToClass(ModalSubmitInteraction, ['showModal', 'awaitModalSubmit']);
+
+module.exports = ModalSubmitInteraction;

package/src/structures/NewsChannel.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const BaseGuildTextChannel = require('./BaseGuildTextChannel');
+const { Error } = require('../errors');
+
+/**
+ * Represents a guild news channel on Discord.
+ * @extends {BaseGuildTextChannel}
+ */
+class NewsChannel extends BaseGuildTextChannel {
+  /**
+   * Adds the target to this channel's followers.
+   * <info>If you need the created webhook id, use {@link GuildChannelManager#addFollower}.</info>
+   * @param {TextChannelResolvable} channel The channel where the webhook should be created
+   * @param {string} [reason] Reason for creating the webhook
+   * @returns {Promise<NewsChannel>}
+   * @example
+   * if (channel.type === 'GUILD_NEWS') {
+   *   channel.addFollower('222197033908436994', 'Important announcements')
+   *     .then(() => console.log('Added follower'))
+   *     .catch(console.error);
+   * }
+   */
+  async addFollower(channel, reason) {
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new Error('GUILD_CHANNEL_RESOLVE');
+    await this.client.api.channels(this.id).followers.post({ data: { webhook_channel_id: channelId }, reason });
+    return this;
+  }
+}
+
+module.exports = NewsChannel;