feat: interactions

docs/examples/commands.md

@@ -0,0 +1,52 @@
+# Slash Commands
+
+In this example, you'll get to know how to create commands and listen to incoming interactions.
+
+## Creating a Command
+
+First off, we need to create a command so that users can use it. We will create an `echo` command which simply returns what the user inputted. Note that global commands can take up to an hour to appear in the client, so if you want to test a new command, you should create it for one guild first.
+
+```js
+// The data for our command
+const commandData = {
+  name: 'echo',
+  description: 'Replies with your input!',
+  options: [{
+    name: 'input',
+    type: 'STRING',
+    description: 'The input which should be echoed back',
+    required: true,
+  }],
+};
+
+client.once('ready', () => {
+  // Creating a global command
+  client.application.commands.create(commandData);
+
+  // Creating a guild-specific command
+  client.guilds.cache.get('id').commands.create(commandData);
+});
+```
+
+And that's it! As soon as your client gets ready, it will register the `echo` command.
+
+## Handling Commands
+
+Now let's implement a simple handler for it:
+
+```js
+client.on('interaction', interaction => {
+  // If the interaction isn't a slash command, return
+  if (!interaction.isCommand()) return;
+
+  // Check if it is the correct command
+  if (interaction.commandName === 'echo') {
+    // Get the input of the user
+    const input = interaction.options[0].value;
+    // Reply to the command
+    interaction.reply(input);
+  }
+});
+```
+
+The `interaction` event will get emitted every time the client receives an interaction. Only our own slash commands trigger this event, so there is no need to implement a check for commands that belong to other bots.

docs/index.yml

@@ -28,3 +28,5 @@
       path: moderation.md
     - name: Webhook
       path: webhook.js
+    - name: Slash Commands
+      path: commands.md

esm/discord.mjs

@@ -29,8 +29,10 @@ export const {
   UserFlags,
   Util,
   version,
+  ApplicationCommandManager,
   BaseGuildEmojiManager,
   ChannelManager,
+  GuildApplicationCommandManager,
   GuildChannelManager,
   GuildEmojiManager,
   GuildEmojiRoleManager,
@@ -50,6 +52,7 @@ export const {
   resolveString,
   splitMessage,
   Application,
+  ApplicationCommand,
   Base,
   Activity,
   APIMessage,
@@ -59,6 +62,7 @@ export const {
   ClientApplication,
   ClientUser,
   Collector,
+  CommandInteraction,
   DMChannel,
   Emoji,
   Guild,
@@ -69,6 +73,7 @@ export const {
   GuildPreview,
   GuildTemplate,
   Integration,
+  Interaction,
   Invite,
   Message,
   MessageAttachment,

src/client/websocket/handlers/INTERACTION_CREATE.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const CommandInteraction = require('../../../structures/CommandInteraction');
+const { Events, InteractionTypes } = require('../../../util/Constants');
+
+module.exports = (client, { d: data }) => {
+  if (data.type === InteractionTypes.APPLICATION_COMMAND) {
+    const interaction = new CommandInteraction(client, data);
+
+    /**
+     * Emitted when an interaction is created.
+     * @event Client#interaction
+     * @param {Interaction} interaction The interaction which was created
+     */
+    return client.emit(Events.INTERACTION_CREATE, interaction);
+  }
+
+  return client.emit('debug', `[INTERACTION] Received interaction with unknown type: ${data.type}`);
+};

src/index.js

@@ -34,8 +34,10 @@ module.exports = {
   version: require('../package.json').version,
 
   // Managers
+  ApplicationCommandManager: require('./managers/ApplicationCommandManager'),
   BaseGuildEmojiManager: require('./managers/BaseGuildEmojiManager'),
   ChannelManager: require('./managers/ChannelManager'),
+  GuildApplicationCommandManager: require('./managers/GuildApplicationCommandManager'),
   GuildChannelManager: require('./managers/GuildChannelManager'),
   GuildEmojiManager: require('./managers/GuildEmojiManager'),
   GuildEmojiRoleManager: require('./managers/GuildEmojiRoleManager'),
@@ -59,6 +61,7 @@ module.exports = {
 
   // Structures
   Application: require('./structures/interfaces/Application'),
+  ApplicationCommand: require('./structures/ApplicationCommand'),
   Base: require('./structures/Base'),
   Activity: require('./structures/Presence').Activity,
   APIMessage: require('./structures/APIMessage'),
@@ -71,6 +74,7 @@ module.exports = {
     return require('./structures/ClientUser');
   },
   Collector: require('./structures/interfaces/Collector'),
+  CommandInteraction: require('./structures/CommandInteraction'),
   DMChannel: require('./structures/DMChannel'),
   Emoji: require('./structures/Emoji'),
   Guild: require('./structures/Guild'),
@@ -81,6 +85,7 @@ module.exports = {
   GuildPreview: require('./structures/GuildPreview'),
   GuildTemplate: require('./structures/GuildTemplate'),
   Integration: require('./structures/Integration'),
+  Interaction: require('./structures/Interaction'),
   Invite: require('./structures/Invite'),
   Message: require('./structures/Message'),
   MessageAttachment: require('./structures/MessageAttachment'),

src/managers/ApplicationCommandManager.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const BaseManager = require('./BaseManager');
+const { TypeError } = require('../errors');
+const ApplicationCommand = require('../structures/ApplicationCommand');
+const Collection = require('../util/Collection');
+
+/**
+ * Manages API methods for application commands and stores their cache.
+ * @extends {BaseManager}
+ */
+class ApplicationCommandManager extends BaseManager {
+  constructor(client, iterable) {
+    super(client, iterable, ApplicationCommand);
+  }
+
+  /**
+   * The cache of this manager
+   * @type {Collection<Snowflake, ApplicationCommand>}
+   * @name ApplicationCommandManager#cache
+   */
+
+  add(data, cache) {
+    return super.add(data, cache, { extras: [this.guild] });
+  }
+
+  /**
+   * The APIRouter path to the commands
+   * @type {Object}
+   * @readonly
+   * @private
+   */
+  get commandPath() {
+    let path = this.client.api.applications(this.client.application.id);
+    if (this.guild) path = path.guilds(this.guild.id);
+    return path.commands;
+  }
+
+  /**
+   * Data that resolves to give an ApplicationCommand object. This can be:
+   * * An ApplicationCommand object
+   * * A Snowflake
+   * @typedef {ApplicationCommand|Snowflake} ApplicationCommandResolvable
+   */
+
+  /**
+   * Obtains one or multiple application commands from Discord, or the cache if it's already available.
+   * @param {Snowflake} [id] ID of the application command
+   * @param {boolean} [cache=true] Whether to cache the new application commands if they weren't already
+   * @param {boolean} [force=false] Whether to skip the cache check and request the API
+   * @returns {Promise<ApplicationCommand|Collection<Snowflake, ApplicationCommand>>}
+   */
+  async fetch(id, cache = true, force = false) {
+    if (id) {
+      if (!force) {
+        const existing = this.cache.get(id);
+        if (existing) return existing;
+      }
+      const command = await this.commandPath(id).get();
+      return this.add(command, cache);
+    }
+
+    const data = await this.commandPath.get();
+    return data.reduce((coll, command) => coll.set(command.id, this.add(command, cache)), new Collection());
+  }
+
+  /**
+   * Creates an application command.
+   * @param {ApplicationCommandData} command The command
+   * @returns {Promise<ApplicationCommand>}
+   */
+  async create(command) {
+    const data = await this.commandPath.post({
+      data: ApplicationCommandManager.transformCommand(command),
+    });
+    return this.add(data);
+  }
+
+  /**
+   * Sets all the commands for this application or guild.
+   * @param {ApplicationCommandData[]} commands The commands
+   * @returns {Promise<Collection<Snowflake, ApplicationCommand>>}
+   */
+  async set(commands) {
+    const data = await this.commandPath.put({
+      data: commands.map(ApplicationCommandManager.transformCommand),
+    });
+    return data.reduce((coll, command) => coll.set(command.id, this.add(command)), new Collection());
+  }
+
+  /**
+   * Edits an application command.
+   * @param {ApplicationCommandResolvable} command The command to edit
+   * @param {ApplicationCommandData} data The data to update the command with
+   * @returns {ApplicationCommand}
+   */
+  async edit(command, data) {
+    const id = this.resolveID(command);
+    if (!id) throw new TypeError('INVALID_TYPE', 'command', 'ApplicationCommandResolvable');
+
+    const raw = {};
+    if (data.name) raw.name = data.name;
+    if (data.description) raw.description = data.description;
+    if (data.options) raw.options = data.options.map(ApplicationCommand.transformOption);
+
+    const patched = await this.commandPath(id).patch({ data: raw });
+    return this.add(patched);
+  }
+
+  /**
+   * Deletes an application command.
+   * @param {ApplicationCommandResolvable} command The command to delete
+   */
+  async delete(command) {
+    const id = this.resolveID(command);
+    if (!id) throw new TypeError('INVALID_TYPE', 'command', 'ApplicationCommandResolvable');
+
+    await this.commandPath(id).delete();
+    this.cache.delete(id);
+  }
+
+  /**
+   * Transforms an {@link ApplicationCommandData} object into something that can be used with the API.
+   * @param {ApplicationCommandData} command The command to transform
+   * @returns {Object}
+   * @private
+   */
+  static transformCommand(command) {
+    return {
+      ...command,
+      options: command.options?.map(ApplicationCommand.transformOption),
+    };
+  }
+}
+
+module.exports = ApplicationCommandManager;

src/managers/GuildApplicationCommandManager.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const ApplicationCommandManager = require('./ApplicationCommandManager');
+
+/**
+ * An extension for guild-specific application commands.
+ * @extends {ApplicationCommandManager}
+ */
+class GuildApplicationCommandManager extends ApplicationCommandManager {
+  constructor(guild, iterable) {
+    super(guild.client, iterable);
+
+    /**
+     * The guild that this manager belongs to
+     * @type {Guild}
+     */
+    this.guild = guild;
+  }
+}
+
+module.exports = GuildApplicationCommandManager;

src/structures/APIMessage.js

@@ -73,6 +73,16 @@ class APIMessage {
     return this.target instanceof Message;
   }
 
+  /**
+   * Whether or not the target is an interaction
+   * @type {boolean}
+   * @readonly
+   */
+  get isInteraction() {
+    const Interaction = require('./Interaction');
+    return this.target instanceof Interaction;
+  }
+
   /**
    * Makes the content of this message.
    * @returns {?(string|string[])}
@@ -149,6 +159,8 @@ class APIMessage {
     if (this.isMessage) {
       // eslint-disable-next-line eqeqeq
       flags = this.options.flags != null ? new MessageFlags(this.options.flags).bitfield : this.target.flags.bitfield;
+    } else if (this.isInteraction && this.options.ephemeral) {
+      flags = MessageFlags.FLAGS.EPHEMERAL;
     }
 
     let allowedMentions =