discord-sb.js 1.0.0

package/src/structures/interfaces/Collector.js

@@ -0,0 +1,300 @@
+'use strict';
+
+const EventEmitter = require('node:events');
+const { setTimeout } = require('node:timers');
+const { Collection } = require('@discordjs/collection');
+const { TypeError } = require('../../errors');
+const Util = require('../../util/Util');
+
+/**
+ * Filter to be applied to the collector.
+ * @typedef {Function} CollectorFilter
+ * @param {...*} args Any arguments received by the listener
+ * @param {Collection} collection The items collected by this collector
+ * @returns {boolean|Promise<boolean>}
+ */
+
+/**
+ * Options to be applied to the collector.
+ * @typedef {Object} CollectorOptions
+ * @property {CollectorFilter} [filter] The filter applied to this collector
+ * @property {number} [time] How long to run the collector for in milliseconds
+ * @property {number} [idle] How long to stop the collector after inactivity in milliseconds
+ * @property {boolean} [dispose=false] Whether to dispose data when it's deleted
+ */
+
+/**
+ * Abstract class for defining a new Collector.
+ * @extends {EventEmitter}
+ * @abstract
+ */
+class Collector extends EventEmitter {
+  constructor(client, options = {}) {
+    super();
+
+    /**
+     * The client that instantiated this Collector
+     * @name Collector#client
+     * @type {Client}
+     * @readonly
+     */
+    Object.defineProperty(this, 'client', { value: client });
+
+    /**
+     * The filter applied to this collector
+     * @type {CollectorFilter}
+     * @returns {boolean|Promise<boolean>}
+     */
+    this.filter = options.filter ?? (() => true);
+
+    /**
+     * The options of this collector
+     * @type {CollectorOptions}
+     */
+    this.options = options;
+
+    /**
+     * The items collected by this collector
+     * @type {Collection}
+     */
+    this.collected = new Collection();
+
+    /**
+     * Whether this collector has finished collecting
+     * @type {boolean}
+     */
+    this.ended = false;
+
+    /**
+     * Timeout for cleanup
+     * @type {?Timeout}
+     * @private
+     */
+    this._timeout = null;
+
+    /**
+     * Timeout for cleanup due to inactivity
+     * @type {?Timeout}
+     * @private
+     */
+    this._idletimeout = null;
+
+    if (typeof this.filter !== 'function') {
+      throw new TypeError('INVALID_TYPE', 'options.filter', 'function');
+    }
+
+    this.handleCollect = this.handleCollect.bind(this);
+    this.handleDispose = this.handleDispose.bind(this);
+
+    if (options.time) this._timeout = setTimeout(() => this.stop('time'), options.time).unref();
+    if (options.idle) this._idletimeout = setTimeout(() => this.stop('idle'), options.idle).unref();
+  }
+
+  /**
+   * Call this to handle an event as a collectable element. Accepts any event data as parameters.
+   * @param {...*} args The arguments emitted by the listener
+   * @returns {Promise<void>}
+   * @emits Collector#collect
+   */
+  async handleCollect(...args) {
+    const collect = await this.collect(...args);
+
+    if (collect && (await this.filter(...args, this.collected))) {
+      this.collected.set(collect, args[0]);
+
+      /**
+       * Emitted whenever an element is collected.
+       * @event Collector#collect
+       * @param {...*} args The arguments emitted by the listener
+       */
+      this.emit('collect', ...args);
+
+      if (this._idletimeout) {
+        clearTimeout(this._idletimeout);
+        this._idletimeout = setTimeout(() => this.stop('idle'), this.options.idle).unref();
+      }
+    }
+    this.checkEnd();
+  }
+
+  /**
+   * Call this to remove an element from the collection. Accepts any event data as parameters.
+   * @param {...*} args The arguments emitted by the listener
+   * @returns {Promise<void>}
+   * @emits Collector#dispose
+   */
+  async handleDispose(...args) {
+    if (!this.options.dispose) return;
+
+    const dispose = this.dispose(...args);
+    if (!dispose || !(await this.filter(...args)) || !this.collected.has(dispose)) return;
+    this.collected.delete(dispose);
+
+    /**
+     * Emitted whenever an element is disposed of.
+     * @event Collector#dispose
+     * @param {...*} args The arguments emitted by the listener
+     */
+    this.emit('dispose', ...args);
+    this.checkEnd();
+  }
+
+  /**
+   * Returns a promise that resolves with the next collected element;
+   * rejects with collected elements if the collector finishes without receiving a next element
+   * @type {Promise}
+   * @readonly
+   */
+  get next() {
+    return new Promise((resolve, reject) => {
+      if (this.ended) {
+        reject(this.collected);
+        return;
+      }
+
+      const cleanup = () => {
+        this.removeListener('collect', onCollect);
+        this.removeListener('end', onEnd);
+      };
+
+      const onCollect = item => {
+        cleanup();
+        resolve(item);
+      };
+
+      const onEnd = () => {
+        cleanup();
+        reject(this.collected); // eslint-disable-line prefer-promise-reject-errors
+      };
+
+      this.on('collect', onCollect);
+      this.on('end', onEnd);
+    });
+  }
+
+  /**
+   * Stops this collector and emits the `end` event.
+   * @param {string} [reason='user'] The reason this collector is ending
+   * @emits Collector#end
+   */
+  stop(reason = 'user') {
+    if (this.ended) return;
+
+    if (this._timeout) {
+      clearTimeout(this._timeout);
+      this._timeout = null;
+    }
+    if (this._idletimeout) {
+      clearTimeout(this._idletimeout);
+      this._idletimeout = null;
+    }
+    this.ended = true;
+
+    /**
+     * Emitted when the collector is finished collecting.
+     * @event Collector#end
+     * @param {Collection} collected The elements collected by the collector
+     * @param {string} reason The reason the collector ended
+     */
+    this.emit('end', this.collected, reason);
+  }
+
+  /**
+   * Options used to reset the timeout and idle timer of a {@link Collector}.
+   * @typedef {Object} CollectorResetTimerOptions
+   * @property {number} [time] How long to run the collector for (in milliseconds)
+   * @property {number} [idle] How long to wait to stop the collector after inactivity (in milliseconds)
+   */
+
+  /**
+   * Resets the collector's timeout and idle timer.
+   * @param {CollectorResetTimerOptions} [options] Options for resetting
+   */
+  resetTimer({ time, idle } = {}) {
+    if (this._timeout) {
+      clearTimeout(this._timeout);
+      this._timeout = setTimeout(() => this.stop('time'), time ?? this.options.time).unref();
+    }
+    if (this._idletimeout) {
+      clearTimeout(this._idletimeout);
+      this._idletimeout = setTimeout(() => this.stop('idle'), idle ?? this.options.idle).unref();
+    }
+  }
+
+  /**
+   * Checks whether the collector should end, and if so, ends it.
+   * @returns {boolean} Whether the collector ended or not
+   */
+  checkEnd() {
+    const reason = this.endReason;
+    if (reason) this.stop(reason);
+    return Boolean(reason);
+  }
+
+  /**
+   * Allows collectors to be consumed with for-await-of loops
+   * @see {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/for-await...of}
+   */
+  async *[Symbol.asyncIterator]() {
+    const queue = [];
+    const onCollect = item => queue.push(item);
+    this.on('collect', onCollect);
+
+    try {
+      while (queue.length || !this.ended) {
+        if (queue.length) {
+          yield queue.shift();
+        } else {
+          // eslint-disable-next-line no-await-in-loop
+          await new Promise(resolve => {
+            const tick = () => {
+              this.removeListener('collect', tick);
+              this.removeListener('end', tick);
+              return resolve();
+            };
+            this.on('collect', tick);
+            this.on('end', tick);
+          });
+        }
+      }
+    } finally {
+      this.removeListener('collect', onCollect);
+    }
+  }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
+
+  /* eslint-disable no-empty-function */
+  /**
+   * The reason this collector has ended with, or null if it hasn't ended yet
+   * @type {?string}
+   * @readonly
+   * @abstract
+   */
+  get endReason() {}
+
+  /**
+   * Handles incoming events from the `handleCollect` function. Returns null if the event should not
+   * be collected, or returns an object describing the data that should be stored.
+   * @see Collector#handleCollect
+   * @param {...*} args Any args the event listener emits
+   * @returns {?(*|Promise<?*>)} Data to insert into collection, if any
+   * @abstract
+   */
+  collect() {}
+
+  /**
+   * Handles incoming events from the `handleDispose`. Returns null if the event should not
+   * be disposed, or returns the key that should be removed.
+   * @see Collector#handleDispose
+   * @param {...*} args Any args the event listener emits
+   * @returns {?*} Key to remove from the collection, if any
+   * @abstract
+   */
+  dispose() {}
+  /* eslint-enable no-empty-function */
+}
+
+module.exports = Collector;

package/src/structures/interfaces/InteractionResponses.js

@@ -0,0 +1,313 @@
+'use strict';
+
+const { Error } = require('../../errors');
+const { InteractionResponseTypes, InteractionTypes } = require('../../util/Constants');
+const MessageFlags = require('../../util/MessageFlags');
+const InteractionCollector = require('../InteractionCollector');
+const MessagePayload = require('../MessagePayload');
+const Modal = require('../Modal');
+
+/**
+ * Interface for classes that support shared interaction response types.
+ * @interface
+ */
+class InteractionResponses {
+  /**
+   * Options for deferring the reply to an {@link Interaction}.
+   * @typedef {Object} InteractionDeferReplyOptions
+   * @property {boolean} [ephemeral] Whether the reply should be ephemeral
+   * @property {boolean} [fetchReply] Whether to fetch the reply
+   */
+
+  /**
+   * Options for deferring and updating the reply to a {@link MessageComponentInteraction}.
+   * @typedef {Object} InteractionDeferUpdateOptions
+   * @property {boolean} [fetchReply] Whether to fetch the reply
+   */
+
+  /**
+   * Options for a reply to an {@link Interaction}.
+   * @typedef {BaseMessageOptionsWithPoll} InteractionReplyOptions
+   * @property {boolean} [ephemeral] Whether the reply should be ephemeral
+   * @property {boolean} [fetchReply] Whether to fetch the reply
+   * @property {MessageFlags} [flags] Which flags to set for the message.
+   * Only `SUPPRESS_EMBEDS` and `EPHEMERAL` can be set.
+   */
+
+  /**
+   * Options for updating the message received from a {@link MessageComponentInteraction}.
+   * @typedef {MessageEditOptions} InteractionUpdateOptions
+   * @property {boolean} [fetchReply] Whether to fetch the reply
+   */
+
+  /**
+   * Defers the reply to this interaction.
+   * @param {InteractionDeferReplyOptions} [options] Options for deferring the reply to this interaction
+   * @returns {Promise<Message|APIMessage|void>}
+   * @example
+   * // Defer the reply to this interaction
+   * interaction.deferReply()
+   *   .then(console.log)
+   *   .catch(console.error)
+   * @example
+   * // Defer to send an ephemeral reply later
+   * interaction.deferReply({ ephemeral: true })
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async deferReply(options = {}) {
+    if (this.deferred || this.replied) throw new Error('INTERACTION_ALREADY_REPLIED');
+    this.ephemeral = options.ephemeral ?? false;
+    await this.client.api.interactions(this.id, this.token).callback.post({
+      data: {
+        type: InteractionResponseTypes.DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE,
+        data: {
+          flags: options.ephemeral ? MessageFlags.FLAGS.EPHEMERAL : undefined,
+        },
+      },
+      auth: false,
+    });
+    this.deferred = true;
+
+    return options.fetchReply ? this.fetchReply() : undefined;
+  }
+
+  /**
+   * Creates a reply to this interaction.
+   * <info>Use the `fetchReply` option to get the bot's reply message.</info>
+   * @param {string|MessagePayload|InteractionReplyOptions} options The options for the reply
+   * @returns {Promise<Message|APIMessage|void>}
+   * @example
+   * // Reply to the interaction and fetch the response
+   * interaction.reply({ content: 'Pong!', fetchReply: true })
+   *   .then((message) => console.log(`Reply sent with content ${message.content}`))
+   *   .catch(console.error);
+   * @example
+   * // Create an ephemeral reply with an embed
+   * const embed = new MessageEmbed().setDescription('Pong!');
+   *
+   * interaction.reply({ embeds: [embed], ephemeral: true })
+   *   .then(() => console.log('Reply sent.'))
+   *   .catch(console.error);
+   */
+  async reply(options) {
+    if (this.deferred || this.replied) throw new Error('INTERACTION_ALREADY_REPLIED');
+    this.ephemeral = options.ephemeral ?? false;
+
+    let messagePayload;
+    if (options instanceof MessagePayload) messagePayload = options;
+    else messagePayload = MessagePayload.create(this, options);
+
+    const { data, files } = await messagePayload.resolveData().resolveFiles();
+
+    await this.client.api.interactions(this.id, this.token).callback.post({
+      data: {
+        type: InteractionResponseTypes.CHANNEL_MESSAGE_WITH_SOURCE,
+        data,
+      },
+      files,
+      auth: false,
+    });
+    this.replied = true;
+
+    return options.fetchReply ? this.fetchReply() : undefined;
+  }
+
+  /**
+   * Fetches a reply to this interaction.
+   * @see Webhook#fetchMessage
+   * @param {MessageResolvable|'@original'} [message='@original'] The response to fetch
+   * @returns {Promise<Message|APIMessage>}
+   * @example
+   * // Fetch the initial reply to this interaction
+   * interaction.fetchReply()
+   *   .then(reply => console.log(`Replied with ${reply.content}`))
+   *   .catch(console.error);
+   */
+  fetchReply(message = '@original') {
+    return this.webhook.fetchMessage(message);
+  }
+
+  /**
+   * Options that can be passed into {@link InteractionResponses#editReply}.
+   * @typedef {WebhookEditMessageOptions} InteractionEditReplyOptions
+   * @property {MessageResolvable|'@original'} [message='@original'] The response to edit
+   */
+
+  /**
+   * Edits a reply to this interaction.
+   * @see Webhook#editMessage
+   * @param {string|MessagePayload|InteractionEditReplyOptions} options The new options for the message
+   * @returns {Promise<Message|APIMessage>}
+   * @example
+   * // Edit the initial reply to this interaction
+   * interaction.editReply('New content')
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async editReply(options) {
+    if (!this.deferred && !this.replied) throw new Error('INTERACTION_NOT_REPLIED');
+    const message = await this.webhook.editMessage(options.message ?? '@original', options);
+    this.replied = true;
+    return message;
+  }
+
+  /**
+   * Deletes a reply to this interaction.
+   * @see Webhook#deleteMessage
+   * @param {MessageResolvable|'@original'} [message='@original'] The response to delete
+   * @returns {Promise<void>}
+   * @example
+   * // Delete the initial reply to this interaction
+   * interaction.deleteReply()
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async deleteReply(message = '@original') {
+    await this.webhook.deleteMessage(message);
+  }
+
+  /**
+   * Send a follow-up message to this interaction.
+   * @param {string|MessagePayload|InteractionReplyOptions} options The options for the reply
+   * @returns {Promise<Message|APIMessage>}
+   */
+  async followUp(options) {
+    if (!this.deferred && !this.replied) throw new Error('INTERACTION_NOT_REPLIED');
+    return this.webhook.send(options);
+  }
+
+  /**
+   * Defers an update to the message to which the component was attached.
+   * @param {InteractionDeferUpdateOptions} [options] Options for deferring the update to this interaction
+   * @returns {Promise<Message|APIMessage|void>}
+   * @example
+   * // Defer updating and reset the component's loading state
+   * interaction.deferUpdate()
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async deferUpdate(options = {}) {
+    if (this.deferred || this.replied) throw new Error('INTERACTION_ALREADY_REPLIED');
+    await this.client.api.interactions(this.id, this.token).callback.post({
+      data: {
+        type: InteractionResponseTypes.DEFERRED_MESSAGE_UPDATE,
+      },
+      auth: false,
+    });
+    this.deferred = true;
+
+    return options.fetchReply ? this.fetchReply() : undefined;
+  }
+
+  /**
+   * Updates the original message of the component on which the interaction was received on.
+   * @param {string|MessagePayload|InteractionUpdateOptions} options The options for the updated message
+   * @returns {Promise<Message|APIMessage|void>}
+   * @example
+   * // Remove the components from the message
+   * interaction.update({
+   *   content: "A component interaction was received",
+   *   components: []
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async update(options) {
+    if (this.deferred || this.replied) throw new Error('INTERACTION_ALREADY_REPLIED');
+
+    let messagePayload;
+    if (options instanceof MessagePayload) messagePayload = options;
+    else messagePayload = MessagePayload.create(this, options);
+
+    const { data, files } = await messagePayload.resolveData().resolveFiles();
+
+    await this.client.api.interactions(this.id, this.token).callback.post({
+      data: {
+        type: InteractionResponseTypes.UPDATE_MESSAGE,
+        data,
+      },
+      files,
+      auth: false,
+    });
+    this.replied = true;
+
+    return options.fetchReply ? this.fetchReply() : undefined;
+  }
+
+  /**
+   * Shows a modal component
+   * @param {Modal|ModalOptions} modal The modal to show
+   * @returns {Promise<void>}
+   */
+  async showModal(modal) {
+    if (this.deferred || this.replied) throw new Error('INTERACTION_ALREADY_REPLIED');
+
+    const _modal = modal instanceof Modal ? modal : new Modal(modal);
+    await this.client.api.interactions(this.id, this.token).callback.post({
+      data: {
+        type: InteractionResponseTypes.MODAL,
+        data: _modal.toJSON(),
+      },
+    });
+    this.replied = true;
+  }
+
+  /**
+   * An object containing the same properties as CollectorOptions, but a few more:
+   * @typedef {Object} AwaitModalSubmitOptions
+   * @property {CollectorFilter} [filter] The filter applied to this collector
+   * @property {number} time Time in milliseconds to wait for an interaction before rejecting
+   */
+
+  /**
+   * Collects a single modal submit interaction that passes the filter.
+   * The Promise will reject if the time expires.
+   * @param {AwaitModalSubmitOptions} options Options to pass to the internal collector
+   * @returns {Promise<ModalSubmitInteraction>}
+   * @example
+   * // Collect a modal submit interaction
+   * const filter = (interaction) => interaction.customId === 'modal';
+   * interaction.awaitModalSubmit({ filter, time: 15_000 })
+   *   .then(interaction => console.log(`${interaction.customId} was submitted!`))
+   *   .catch(console.error);
+   */
+  awaitModalSubmit(options) {
+    if (typeof options.time !== 'number') throw new Error('INVALID_TYPE', 'time', 'number');
+    const _options = { ...options, max: 1, interactionType: InteractionTypes.MODAL_SUBMIT };
+    return new Promise((resolve, reject) => {
+      const collector = new InteractionCollector(this.client, _options);
+      collector.once('end', (interactions, reason) => {
+        const interaction = interactions.first();
+        if (interaction) resolve(interaction);
+        else reject(new Error('INTERACTION_COLLECTOR_ERROR', reason));
+      });
+    });
+  }
+
+  static applyToClass(structure, ignore = []) {
+    const props = [
+      'deferReply',
+      'reply',
+      'fetchReply',
+      'editReply',
+      'deleteReply',
+      'followUp',
+      'deferUpdate',
+      'update',
+      'showModal',
+      'awaitModalSubmit',
+    ];
+
+    for (const prop of props) {
+      if (ignore.includes(prop)) continue;
+      Object.defineProperty(
+        structure.prototype,
+        prop,
+        Object.getOwnPropertyDescriptor(InteractionResponses.prototype, prop),
+      );
+    }
+  }
+}
+
+module.exports = InteractionResponses;