discord-sb.js 1.0.0

package/src/structures/MessageActionRow.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const BaseMessageComponent = require('./BaseMessageComponent');
+const { MessageComponentTypes } = require('../util/Constants');
+
+/**
+ * Represents an action row containing message components.
+ * @extends {BaseMessageComponent}
+ */
+class MessageActionRow extends BaseMessageComponent {
+  /**
+   * Components that can be placed in an action row
+   * * MessageButton
+   * * MessageSelectMenu
+   * * TextInputComponent
+   * @typedef {MessageButton|MessageSelectMenu|TextInputComponent} MessageActionRowComponent
+   */
+
+  /**
+   * Options for components that can be placed in an action row
+   * * MessageButtonOptions
+   * * MessageSelectMenuOptions
+   * * TextInputComponentOptions
+   * @typedef {MessageButtonOptions|MessageSelectMenuOptions|TextInputComponentOptions} MessageActionRowComponentOptions
+   */
+
+  /**
+   * Data that can be resolved into components that can be placed in an action row
+   * * MessageActionRowComponent
+   * * MessageActionRowComponentOptions
+   * @typedef {MessageActionRowComponent|MessageActionRowComponentOptions} MessageActionRowComponentResolvable
+   */
+
+  /**
+   * @typedef {BaseMessageComponentOptions} MessageActionRowOptions
+   * @property {MessageActionRowComponentResolvable[]} [components]
+   * The components to place in this action row
+   */
+
+  /**
+   * @param {MessageActionRow|MessageActionRowOptions} [data={}] MessageActionRow to clone or raw data
+   * @param {Client} [client] The client constructing this MessageActionRow, if provided
+   */
+  constructor(data = {}, client = null) {
+    super({ type: 'ACTION_ROW' });
+
+    /**
+     * The components in this action row
+     * @type {MessageActionRowComponent[]}
+     */
+    this.components = data.components?.map(c => BaseMessageComponent.create(c, client)) ?? [];
+
+    super.setup(data);
+  }
+
+  /**
+   * Adds components to the action row.
+   * @param {...MessageActionRowComponentResolvable[]} components The components to add
+   * @returns {MessageActionRow}
+   */
+  addComponents(...components) {
+    this.components.push(...components.flat(Infinity).map(c => BaseMessageComponent.create(c)));
+    return this;
+  }
+
+  /**
+   * Sets the components of the action row.
+   * @param {...MessageActionRowComponentResolvable[]} components The components to set
+   * @returns {MessageActionRow}
+   */
+  setComponents(...components) {
+    this.spliceComponents(0, this.components.length, components);
+    return this;
+  }
+
+  /**
+   * Removes, replaces, and inserts components in the action row.
+   * @param {number} index The index to start at
+   * @param {number} deleteCount The number of components to remove
+   * @param {...MessageActionRowComponentResolvable[]} [components] The replacing components
+   * @returns {MessageActionRow}
+   */
+  spliceComponents(index, deleteCount, ...components) {
+    this.components.splice(index, deleteCount, ...components.flat(Infinity).map(c => BaseMessageComponent.create(c)));
+    return this;
+  }
+
+  /**
+   * Transforms the action row to a plain object.
+   * @returns {APIMessageComponent} The raw data of this action row
+   */
+  toJSON() {
+    return {
+      components: this.components.map(c => c.toJSON()),
+      type: MessageComponentTypes[this.type],
+    };
+  }
+}
+
+module.exports = MessageActionRow;
+
+/**
+ * @external APIMessageComponent
+ * @see {@link https://discord.com/developers/docs/interactions/message-components#component-object}
+ */

package/src/structures/MessageAttachment.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const AttachmentFlags = require('../util/AttachmentFlags');
+const Util = require('../util/Util');
+
+/**
+ * Represents an attachment in a message.
+ */
+class MessageAttachment {
+  /**
+   * @param {BufferResolvable|Stream} attachment The file
+   * @param {string} [name=null] The name of the file, if any
+   * @param {APIAttachment} [data] Extra data
+   */
+  constructor(attachment, name = null, data) {
+    this.attachment = attachment;
+    /**
+     * The name of this attachment
+     * @type {?string}
+     */
+    this.name = name;
+    if (data) this._patch(data);
+  }
+
+  /**
+   * Sets the description of this attachment.
+   * @param {string} description The description of the file
+   * @returns {MessageAttachment} This attachment
+   */
+  setDescription(description) {
+    this.description = description;
+    return this;
+  }
+
+  /**
+   * Sets the file of this attachment.
+   * @param {BufferResolvable|Stream} attachment The file
+   * @param {string} [name=null] The name of the file, if any
+   * @returns {MessageAttachment} This attachment
+   */
+  setFile(attachment, name = null) {
+    this.attachment = attachment;
+    this.name = name;
+    return this;
+  }
+
+  /**
+   * Sets the name of this attachment.
+   * @param {string} name The name of the file
+   * @returns {MessageAttachment} This attachment
+   */
+  setName(name) {
+    this.name = name;
+    return this;
+  }
+
+  /**
+   * Sets whether this attachment is a spoiler
+   * @param {boolean} [spoiler=true] Whether the attachment should be marked as a spoiler
+   * @returns {MessageAttachment} This attachment
+   */
+  setSpoiler(spoiler = true) {
+    if (spoiler === this.spoiler) return this;
+
+    if (!spoiler) {
+      while (this.spoiler) {
+        this.name = this.name.slice('SPOILER_'.length);
+      }
+      return this;
+    }
+    this.name = `SPOILER_${this.name}`;
+    return this;
+  }
+
+  _patch(data) {
+    /**
+     * The attachment's id
+     * @type {Snowflake}
+     */
+    this.id = data.id;
+
+    if ('size' in data) {
+      /**
+       * The size of this attachment in bytes
+       * @type {number}
+       */
+      this.size = data.size;
+    }
+
+    if ('url' in data) {
+      /**
+       * The URL to this attachment
+       * @type {string}
+       */
+      this.url = data.url;
+    }
+
+    if ('proxy_url' in data) {
+      /**
+       * The Proxy URL to this attachment
+       * @type {string}
+       */
+      this.proxyURL = data.proxy_url;
+    }
+
+    if ('height' in data) {
+      /**
+       * The height of this attachment (if an image or video)
+       * @type {?number}
+       */
+      this.height = data.height;
+    } else {
+      this.height ??= null;
+    }
+
+    if ('width' in data) {
+      /**
+       * The width of this attachment (if an image or video)
+       * @type {?number}
+       */
+      this.width = data.width;
+    } else {
+      this.width ??= null;
+    }
+
+    if ('content_type' in data) {
+      /**
+       * The media (MIME) type of this attachment
+       * @type {?string}
+       * @see {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types}
+       */
+      this.contentType = data.content_type;
+    } else {
+      this.contentType ??= null;
+    }
+
+    if ('description' in data) {
+      /**
+       * The description (alt text) of this attachment
+       * @type {?string}
+       */
+      this.description = data.description;
+    } else {
+      this.description ??= null;
+    }
+
+    /**
+     * Whether this attachment is ephemeral
+     * @type {boolean}
+     */
+    this.ephemeral = data.ephemeral ?? false;
+
+    if ('duration_secs' in data) {
+      /**
+       * The duration of this attachment in seconds
+       * <info>This will only be available if the attachment is an audio file.</info>
+       * @type {?number}
+       */
+      this.duration = data.duration_secs;
+    } else {
+      this.duration ??= null;
+    }
+
+    if ('waveform' in data) {
+      /**
+       * The base64 encoded byte array representing a sampled waveform
+       * <info>This will only be available if the attachment is an audio file.</info>
+       * @type {?string}
+       */
+      this.waveform = data.waveform;
+    } else {
+      this.waveform ??= null;
+    }
+
+    if ('flags' in data) {
+      /**
+       * The flags of this attachment
+       * @type {Readonly<AttachmentFlags>}
+       */
+      this.flags = new AttachmentFlags(data.flags).freeze();
+    } else {
+      this.flags ??= new AttachmentFlags().freeze();
+    }
+
+    if ('title' in data) {
+      /**
+       * The title of this attachment
+       * <info>This will only be available if the attachment name contains special characters.</info>
+       * @type {?string}
+       */
+      this.title = data.title;
+    } else {
+      this.title ??= null;
+    }
+  }
+
+  /**
+   * Whether or not this attachment has been marked as a spoiler
+   * @type {boolean}
+   * @readonly
+   */
+  get spoiler() {
+    return Util.basename(this.url ?? this.name).startsWith('SPOILER_');
+  }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
+}
+
+module.exports = MessageAttachment;
+
+/**
+ * @external APIAttachment
+ * @see {@link https://discord.com/developers/docs/resources/channel#attachment-object}
+ */

package/src/structures/MessageButton.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const BaseMessageComponent = require('./BaseMessageComponent');
+const { RangeError } = require('../errors');
+const { MessageButtonStyles, MessageComponentTypes } = require('../util/Constants');
+const Util = require('../util/Util');
+
+/**
+ * Represents a button message component.
+ * @extends {BaseMessageComponent}
+ */
+class MessageButton extends BaseMessageComponent {
+  /**
+   * @typedef {BaseMessageComponentOptions} MessageButtonOptions
+   * @property {string} [label] The text to be displayed on this button
+   * @property {string} [customId] A unique string to be sent in the interaction when clicked
+   * @property {MessageButtonStyleResolvable} [style] The style of this button
+   * @property {EmojiIdentifierResolvable} [emoji] The emoji to be displayed to the left of the text
+   * @property {string} [url] Optional URL for link-style buttons
+   * @property {boolean} [disabled=false] Disables the button to prevent interactions
+   */
+
+  /**
+   * @param {MessageButton|MessageButtonOptions} [data={}] MessageButton to clone or raw data
+   */
+  constructor(data = {}) {
+    super({ type: 'BUTTON' });
+
+    this.setup(data);
+  }
+
+  setup(data) {
+    super.setup(data);
+    /**
+     * The text to be displayed on this button
+     * @type {?string}
+     */
+    this.label = data.label ?? null;
+
+    /**
+     * A unique string to be sent in the interaction when clicked
+     * @type {?string}
+     */
+    this.customId = data.custom_id ?? data.customId ?? null;
+
+    /**
+     * The style of this button
+     * @type {?MessageButtonStyle}
+     */
+    this.style = data.style ? MessageButton.resolveStyle(data.style) : null;
+
+    /**
+     * Emoji for this button
+     * @type {?RawEmoji}
+     */
+    this.emoji = data.emoji ? Util.resolvePartialEmoji(data.emoji) : null;
+
+    /**
+     * The URL this button links to, if it is a Link style button
+     * @type {?string}
+     */
+    this.url = data.url ?? null;
+
+    /**
+     * Whether this button is currently disabled
+     * @type {boolean}
+     */
+    this.disabled = data.disabled ?? false;
+  }
+
+  /**
+   * Sets the custom id for this button
+   * @param {string} customId A unique string to be sent in the interaction when clicked
+   * @returns {MessageButton}
+   */
+  setCustomId(customId) {
+    this.customId = Util.verifyString(customId, RangeError, 'BUTTON_CUSTOM_ID');
+    return this;
+  }
+
+  /**
+   * Sets the interactive status of the button
+   * @param {boolean} [disabled=true] Whether this button should be disabled
+   * @returns {MessageButton}
+   */
+  setDisabled(disabled = true) {
+    this.disabled = disabled;
+    return this;
+  }
+
+  /**
+   * Set the emoji of this button
+   * @param {EmojiIdentifierResolvable} emoji The emoji to be displayed on this button
+   * @returns {MessageButton}
+   */
+  setEmoji(emoji) {
+    this.emoji = Util.resolvePartialEmoji(emoji);
+    return this;
+  }
+
+  /**
+   * Sets the label of this button
+   * @param {string} label The text to be displayed on this button
+   * @returns {MessageButton}
+   */
+  setLabel(label) {
+    this.label = Util.verifyString(label, RangeError, 'BUTTON_LABEL');
+    return this;
+  }
+
+  /**
+   * Sets the style of this button
+   * @param {MessageButtonStyleResolvable} style The style of this button
+   * @returns {MessageButton}
+   */
+  setStyle(style) {
+    this.style = MessageButton.resolveStyle(style);
+    return this;
+  }
+
+  /**
+   * Sets the URL of this button.
+   * <info>MessageButton#style must be LINK when setting a URL</info>
+   * @param {string} url The URL of this button
+   * @returns {MessageButton}
+   */
+  setURL(url) {
+    this.url = Util.verifyString(url, RangeError, 'BUTTON_URL');
+    return this;
+  }
+
+  /**
+   * Transforms the button to a plain object.
+   * @returns {APIMessageButton} The raw data of this button
+   */
+  toJSON() {
+    return {
+      custom_id: this.customId,
+      disabled: this.disabled,
+      emoji: this.emoji,
+      label: this.label,
+      style: MessageButtonStyles[this.style],
+      type: MessageComponentTypes[this.type],
+      url: this.url,
+    };
+  }
+
+  /**
+   * Data that can be resolved to a MessageButtonStyle. This can be
+   * * MessageButtonStyle
+   * * number
+   * @typedef {number|MessageButtonStyle} MessageButtonStyleResolvable
+   */
+
+  /**
+   * Resolves the style of a button
+   * @param {MessageButtonStyleResolvable} style The style to resolve
+   * @returns {MessageButtonStyle}
+   * @private
+   */
+  static resolveStyle(style) {
+    return typeof style === 'string' ? style : MessageButtonStyles[style];
+  }
+}
+
+module.exports = MessageButton;

package/src/structures/MessageCollector.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const Collector = require('./interfaces/Collector');
+const { Events } = require('../util/Constants');
+
+/**
+ * @typedef {CollectorOptions} MessageCollectorOptions
+ * @property {number} max The maximum amount of messages to collect
+ * @property {number} maxProcessed The maximum amount of messages to process
+ */
+
+/**
+ * Collects messages on a channel.
+ * Will automatically stop if the channel ({@link Client#event:channelDelete channelDelete}),
+ * thread ({@link Client#event:threadDelete threadDelete}), or
+ * guild ({@link Client#event:guildDelete guildDelete}) is deleted.
+ * @extends {Collector}
+ */
+class MessageCollector extends Collector {
+  /**
+   * @param {TextBasedChannels} channel The channel
+   * @param {MessageCollectorOptions} options The options to be applied to this collector
+   * @emits MessageCollector#message
+   */
+  constructor(channel, options = {}) {
+    super(channel.client, options);
+
+    /**
+     * The channel
+     * @type {TextBasedChannels}
+     */
+    this.channel = channel;
+
+    /**
+     * Total number of messages that were received in the channel during message collection
+     * @type {number}
+     */
+    this.received = 0;
+
+    const bulkDeleteListener = messages => {
+      for (const message of messages.values()) this.handleDispose(message);
+    };
+
+    this._handleChannelDeletion = this._handleChannelDeletion.bind(this);
+    this._handleThreadDeletion = this._handleThreadDeletion.bind(this);
+    this._handleGuildDeletion = this._handleGuildDeletion.bind(this);
+
+    this.client.incrementMaxListeners();
+    this.client.on(Events.MESSAGE_CREATE, this.handleCollect);
+    this.client.on(Events.MESSAGE_DELETE, this.handleDispose);
+    this.client.on(Events.MESSAGE_BULK_DELETE, bulkDeleteListener);
+    this.client.on(Events.CHANNEL_DELETE, this._handleChannelDeletion);
+    this.client.on(Events.THREAD_DELETE, this._handleThreadDeletion);
+    this.client.on(Events.GUILD_DELETE, this._handleGuildDeletion);
+
+    this.once('end', () => {
+      this.client.removeListener(Events.MESSAGE_CREATE, this.handleCollect);
+      this.client.removeListener(Events.MESSAGE_DELETE, this.handleDispose);
+      this.client.removeListener(Events.MESSAGE_BULK_DELETE, bulkDeleteListener);
+      this.client.removeListener(Events.CHANNEL_DELETE, this._handleChannelDeletion);
+      this.client.removeListener(Events.THREAD_DELETE, this._handleThreadDeletion);
+      this.client.removeListener(Events.GUILD_DELETE, this._handleGuildDeletion);
+      this.client.decrementMaxListeners();
+    });
+  }
+
+  /**
+   * Handles a message for possible collection.
+   * @param {Message} message The message that could be collected
+   * @returns {?Snowflake}
+   * @private
+   */
+  collect(message) {
+    /**
+     * Emitted whenever a message is collected.
+     * @event MessageCollector#collect
+     * @param {Message} message The message that was collected
+     */
+    if (message.channelId !== this.channel.id) return null;
+    this.received++;
+    return message.id;
+  }
+
+  /**
+   * Handles a message for possible disposal.
+   * @param {Message} message The message that could be disposed of
+   * @returns {?Snowflake}
+   */
+  dispose(message) {
+    /**
+     * Emitted whenever a message is disposed of.
+     * @event MessageCollector#dispose
+     * @param {Message} message The message that was disposed of
+     */
+    return message.channelId === this.channel.id ? message.id : null;
+  }
+
+  /**
+   * The reason this collector has ended with, or null if it hasn't ended yet
+   * @type {?string}
+   * @readonly
+   */
+  get endReason() {
+    if (this.options.max && this.collected.size >= this.options.max) return 'limit';
+    if (this.options.maxProcessed && this.received === this.options.maxProcessed) return 'processedLimit';
+    return null;
+  }
+
+  /**
+   * Handles checking if the channel has been deleted, and if so, stops the collector with the reason 'channelDelete'.
+   * @private
+   * @param {GuildChannel} channel The channel that was deleted
+   * @returns {void}
+   */
+  _handleChannelDeletion(channel) {
+    if (channel.id === this.channel.id || channel.id === this.channel.parentId) {
+      this.stop('channelDelete');
+    }
+  }
+
+  /**
+   * Handles checking if the thread has been deleted, and if so, stops the collector with the reason 'threadDelete'.
+   * @private
+   * @param {ThreadChannel} thread The thread that was deleted
+   * @returns {void}
+   */
+  _handleThreadDeletion(thread) {
+    if (thread.id === this.channel.id) {
+      this.stop('threadDelete');
+    }
+  }
+
+  /**
+   * Handles checking if the guild has been deleted, and if so, stops the collector with the reason 'guildDelete'.
+   * @private
+   * @param {Guild} guild The guild that was deleted
+   * @returns {void}
+   */
+  _handleGuildDeletion(guild) {
+    if (guild.id === this.channel.guild?.id) {
+      this.stop('guildDelete');
+    }
+  }
+}
+
+module.exports = MessageCollector;