refactor: Split message send/edit types/documentation (#8590)

* refactor: split message send/edit types

* refactor: move `MessageEditOptions`

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

packages/discord.js/src/client/WebhookClient.js

@@ -32,7 +32,7 @@ class WebhookClient extends BaseClient {
   /**
    * Options for a webhook client.
    * @typedef {Object} WebhookClientOptions
-   * @property {MessageMentionOptions} [allowedMentions] Default value for {@link WebhookMessageOptions#allowedMentions}
+   * @property {MessageMentionOptions} [allowedMentions] Default value for {@link BaseMessageOptions#allowedMentions}
    * @property {RESTOptions} [rest] Options for the REST manager
    */
 
@@ -68,7 +68,7 @@ class WebhookClient extends BaseClient {
   /* eslint-disable no-empty-function, valid-jsdoc */
   /**
    * Sends a message with this webhook.
-   * @param {string|MessagePayload|WebhookMessageOptions} options The content for the reply
+   * @param {string|MessagePayload|WebhookCreateMessageOptions} options The content for the reply
    * @returns {Promise<APIMessage>}
    */
   send() {}

packages/discord.js/src/managers/MessageManager.js

@@ -147,6 +147,15 @@ class MessageManager extends CachedManager {
    * @returns {?Snowflake}
    */
 
+  /**
+   * Options that can be passed to edit a message.
+   * @typedef {BaseMessageOptions} MessageEditOptions
+   * @property {Array<JSONEncodable<AttachmentPayload>>} [attachments] An array of attachments to keep,
+   * all attachments will be kept if omitted
+   * @property {MessageFlags} [flags] Which flags to set for the message
+   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
+   */
+
   /**
    * Edits a message, even if it's not cached.
    * @param {MessageResolvable} message The message to edit

packages/discord.js/src/managers/UserManager.js

@@ -105,7 +105,7 @@ class UserManager extends CachedManager {
   /**
    * Sends a message to a user.
    * @param {UserResolvable} user The UserResolvable to identify
-   * @param {string|MessagePayload|MessageOptions} options The options to provide
+   * @param {string|MessagePayload|MessageCreateOptions} options The options to provide
    * @returns {Promise<Message>}
    */
   async send(user, options) {

packages/discord.js/src/structures/Message.js

@@ -644,22 +644,6 @@ class Message extends Base {
     );
   }
 
-  /**
-   * Options that can be passed into {@link Message#edit}.
-   * @typedef {Object} MessageEditOptions
-   * @property {?string} [content] Content to be edited
-   * @property {Embed[]|APIEmbed[]} [embeds] Embeds to be added/edited
-   * @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
-   * @property {MessageFlags} [flags] Which flags to set for the message
-   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
-   * @property {Attachment[]} [attachments] An array of attachments to keep,
-   * all attachments will be kept if omitted
-   * @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
-   * Files to add to the message
-   * @property {ActionRow[]|ActionRowOptions[]} [components]
-   * Action rows containing interactive components for the message (buttons, select menus)
-   */
-
   /**
    * Edits the content of the message.
    * @param {string|MessagePayload|MessageEditOptions} options The options to provide
@@ -770,15 +754,16 @@ class Message extends Base {
 
   /**
    * Options provided when sending a message as an inline reply.
-   * @typedef {BaseMessageOptions} ReplyMessageOptions
+   * @typedef {BaseMessageCreateOptions} MessageReplyOptions
+   * @property {StickerResolvable[]} [stickers=[]] The stickers to send in the message
    * @property {boolean} [failIfNotExists=this.client.options.failIfNotExists] Whether to error if the referenced
    * message does not exist (creates a standard message in this case when false)
    * @property {StickerResolvable[]} [stickers=[]] Stickers to send in the message
    */
 
   /**
    * Send an inline reply to this message.
-   * @param {string|MessagePayload|ReplyMessageOptions} options The options to provide
+   * @param {string|MessagePayload|MessageReplyOptions} options The options to provide
    * @returns {Promise<Message>}
    * @example
    * // Reply to a message

packages/discord.js/src/structures/MessagePayload.js

@@ -17,7 +17,7 @@ const getBaseInteraction = lazy(() => require('./BaseInteraction'));
 class MessagePayload {
   /**
    * @param {MessageTarget} target The target for this message to be sent to
-   * @param {MessageOptions|WebhookMessageOptions} options Options passed in from send
+   * @param {MessagePayloadOption} options The payload of this message
    */
   constructor(target, options) {
     /**
@@ -27,8 +27,8 @@ class MessagePayload {
     this.target = target;
 
     /**
-     * Options passed in from send
-     * @type {MessageOptions|WebhookMessageOptions}
+     * The payload of this message.
+     * @type {MessagePayloadOption}
      */
     this.options = options;
 
@@ -261,8 +261,8 @@ class MessagePayload {
   /**
    * Creates a {@link MessagePayload} from user-level arguments.
    * @param {MessageTarget} target Target to send to
-   * @param {string|MessageOptions|WebhookMessageOptions} options Options or content to use
-   * @param {MessageOptions|WebhookMessageOptions} [extra={}] Extra options to add onto specified options
+   * @param {string|MessagePayloadOption} options Options or content to use
+   * @param {MessagePayloadOption} [extra={}] Extra options to add onto specified options
    * @returns {MessagePayload}
    */
   static create(target, options, extra = {}) {
@@ -281,6 +281,12 @@ module.exports = MessagePayload;
  * Message|MessageManager} MessageTarget
  */
 
+/**
+ * A possible payload option.
+ * @typedef {MessageCreateOptions|MessageEditOptions|WebhookCreateMessageOptions|WebhookEditMessageOptions|
+ * InteractionReplyOptions|InteractionUpdateOptions} MessagePayloadOption
+ */
+
 /**
  * @external APIMessage
  * @see {@link https://discord.com/developers/docs/resources/channel#message-object}

packages/discord.js/src/structures/Webhook.js

@@ -122,33 +122,27 @@ class Webhook {
 
   /**
    * Options that can be passed into send.
-   * @typedef {BaseMessageOptions} WebhookMessageOptions
+   * @typedef {BaseMessageOptions} WebhookCreateMessageOptions
+   * @property {boolean} [tts=false] Whether the message should be spoken aloud
+   * @property {MessageFlags} [flags] Which flags to set for the message.
+   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be set.</info>
    * @property {string} [username=this.name] Username override for the message
    * @property {string} [avatarURL] Avatar URL override for the message
    * @property {Snowflake} [threadId] The id of the thread in the channel to send to.
    * <info>For interaction webhooks, this property is ignored</info>
-   * @property {MessageFlags} [flags] Which flags to set for the message.
-   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be set.</info>
    */
 
   /**
    * Options that can be passed into editMessage.
-   * @typedef {Object} WebhookEditMessageOptions
-   * @property {Embed[]|APIEmbed[]} [embeds] See {@link WebhookMessageOptions#embeds}
-   * @property {string} [content] See {@link BaseMessageOptions#content}
-   * @property {JSONEncodable<AttachmentPayload>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
-   * See {@link BaseMessageOptions#files}
-   * @property {MessageMentionOptions} [allowedMentions] See {@link BaseMessageOptions#allowedMentions}
+   * @typedef {BaseMessageOptions} WebhookEditMessageOptions
    * @property {Attachment[]} [attachments] Attachments to send with the message
-   * @property {ActionRow[]|ActionRowOptions[]} [components]
-   * Action rows containing interactive components for the message (buttons, select menus)
    * @property {Snowflake} [threadId] The id of the thread this message belongs to
    * <info>For interaction webhooks, this property is ignored</info>
    */
 
   /**
    * Sends a message with this webhook.
-   * @param {string|MessagePayload|WebhookMessageOptions} options The options to provide
+   * @param {string|MessagePayload|WebhookCreateMessageOptions} options The options to provide
    * @returns {Promise<Message>}
    * @example
    * // Send a basic message

packages/discord.js/src/structures/interfaces/InteractionResponses.js

@@ -33,12 +33,13 @@ class InteractionResponses {
    */
 
   /**
-   * Options for a reply to an {@link BaseInteraction}.
+   * Options for a reply to a {@link BaseInteraction}.
    * @typedef {BaseMessageOptions} InteractionReplyOptions
+   * @property {boolean} [tts=false] Whether the message should be spoken aloud
    * @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 `MessageFlags.SuppressEmbeds` and `MessageFlags.Ephemeral` can be set.
+   * <info>Only `MessageFlags.SuppressEmbeds` and `MessageFlags.Ephemeral` can be set.</info>
    */
 
   /**

packages/discord.js/src/structures/interfaces/TextBasedChannel.js

@@ -52,27 +52,35 @@ class TextBasedChannel {
   }
 
   /**
-   * Base options provided when sending.
+   * The base message options for messages.
    * @typedef {Object} BaseMessageOptions
-   * @property {boolean} [tts=false] Whether or not the message should be spoken aloud
-   * @property {string} [nonce=''] The nonce for the message
-   * @property {string} [content=''] The content for the message
+   * @property {string|null} [content=''] The content for the message. This can only be `null` when editing a message.
    * @property {Embed[]|APIEmbed[]} [embeds] The embeds for the message
-   * (see [here](https://discord.com/developers/docs/resources/channel#embed-object) for more details)
    * @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
    * (see [here](https://discord.com/developers/docs/resources/channel#allowed-mentions-object) for more details)
-   * @property {FileOptions[]|BufferResolvable[]|Attachment[]} [files] Files to send with the message
+   * @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
+   * The files to send with the message.
    * @property {ActionRow[]|ActionRowOptions[]} [components]
    * Action rows containing interactive components for the message (buttons, select menus)
-   * @property {Array<JSONEncodable<AttachmentPayload>>} [attachments] Attachments to send in the message
    */
 
   /**
-   * Options provided when sending or editing a message.
-   * @typedef {BaseMessageOptions} MessageOptions
+   * Options for sending a message with a reply.
+   * @typedef {Object} ReplyOptions
+   * @property {MessageResolvable} messageReference The message to reply to (must be in the same channel and not system)
+   * @property {boolean} [failIfNotExists=this.client.options.failIfNotExists] Whether to error if the referenced
+   * message does not exist (creates a standard message in this case when false)
+   */
+
+  /**
+   * The options for sending a message.
+   * @typedef {BaseMessageOptions} MessageCreateOptions
+   * @property {boolean} [tts=false] Whether the message should be spoken aloud
+   * @property {string} [nonce=''] The nonce for the message
    * @property {ReplyOptions} [reply] The options for replying to a message
-   * @property {StickerResolvable[]} [stickers=[]] Stickers to send in the message
-   * @property {MessageFlags} [flags] Which flags to set for the message. Only `MessageFlags.SuppressEmbeds` can be set.
+   * @property {StickerResolvable[]} [stickers=[]] The stickers to send in the message
+   * @property {MessageFlags} [flags] Which flags to set for the message.
+   * <info>Only `MessageFlags.SuppressEmbeds` can be set.</info>
    */
 
   /**
@@ -99,17 +107,9 @@ class TextBasedChannel {
    * @property {string} description The description of the file
    */
 
-  /**
-   * Options for sending a message with a reply.
-   * @typedef {Object} ReplyOptions
-   * @property {MessageResolvable} messageReference The message to reply to (must be in the same channel and not system)
-   * @property {boolean} [failIfNotExists=this.client.options.failIfNotExists] Whether to error if the referenced
-   * message does not exist (creates a standard message in this case when false)
-   */
-
   /**
    * Sends a message to this channel.
-   * @param {string|MessagePayload|MessageOptions} options The options to provide
+   * @param {string|MessagePayload|MessageCreateOptions} options The options to provide
    * @returns {Promise<Message>}
    * @example
    * // Send a basic message

packages/discord.js/src/util/Options.js

@@ -25,12 +25,12 @@ const { toSnakeCase } = require('./Transformers');
  * You can use your own function, or the {@link Options} class to customize the Collection used for the cache.
  * <warn>Overriding the cache used in `GuildManager`, `ChannelManager`, `GuildChannelManager`, `RoleManager`,
  * and `PermissionOverwriteManager` is unsupported and **will** break functionality</warn>
- * @property {MessageMentionOptions} [allowedMentions] Default value for {@link MessageOptions#allowedMentions}
+ * @property {MessageMentionOptions} [allowedMentions] The default value for {@link BaseMessageOptions#allowedMentions}
  * @property {Partials[]} [partials] Structures allowed to be partial. This means events can be emitted even when
  * they're missing all the data for a particular structure. See the "Partial Structures" topic on the
  * [guide](https://discordjs.guide/popular-topics/partials.html) for some
  * important usage information, as partials require you to put checks in place when handling data.
- * @property {boolean} [failIfNotExists=true] Default value for {@link ReplyMessageOptions#failIfNotExists}
+ * @property {boolean} [failIfNotExists=true] The default value for {@link MessageReplyOptions#failIfNotExists}
  * @property {PresenceData} [presence={}] Presence data to use upon login
  * @property {IntentsResolvable} intents Intents to enable for this connection
  * @property {number} [waitGuildTimeout=15_000] Time in milliseconds that clients with the