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,7 +754,8 @@ 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
@@ -778,7 +763,7 @@ class Message extends Base {
 
   /**
    * 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
+     * The payload of this message.
-     * @type {MessageOptions|WebhookMessageOptions}
+     * @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 {string|MessagePayloadOption} options Options or content to use
-   * @param {MessageOptions|WebhookMessageOptions} [extra={}] Extra options to add onto specified options
+   * @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
+   * @typedef {BaseMessageOptions} 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}
    * @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|null} [content=''] The content for the message. This can only be `null` when editing a message.
-   * @property {string} [nonce=''] The nonce for the message
-   * @property {string} [content=''] The content for the 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.
+   * Options for sending a message with a reply.
-   * @typedef {BaseMessageOptions} MessageOptions
+   * @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 {StickerResolvable[]} [stickers=[]] The stickers to send in the message
-   * @property {MessageFlags} [flags] Which flags to set for the message. Only `MessageFlags.SuppressEmbeds` can be set.
+   * @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

packages/discord.js/typings/index.d.ts

@@ -1718,7 +1718,7 @@ export class Message<InGuild extends boolean = boolean> extends Base {
   public pin(reason?: string): Promise<Message<InGuild>>;
   public react(emoji: EmojiIdentifierResolvable): Promise<MessageReaction>;
   public removeAttachments(): Promise<Message<InGuild>>;
-  public reply(options: string | MessagePayload | ReplyMessageOptions): Promise<Message<InGuild>>;
+  public reply(options: string | MessagePayload | MessageReplyOptions): Promise<Message<InGuild>>;
   public resolveComponent(customId: string): MessageActionRowComponent | null;
   public startThread(options: StartThreadOptions): Promise<AnyThreadChannel>;
   public suppressEmbeds(suppress?: boolean): Promise<Message<InGuild>>;
@@ -1875,8 +1875,16 @@ export class MessageMentions {
   public static UsersPattern: typeof FormattingPatterns.User;
 }
 
+export type MessagePayloadOption =
+  | MessageCreateOptions
+  | MessageEditOptions
+  | WebhookCreateMessageOptions
+  | WebhookEditMessageOptions
+  | InteractionReplyOptions
+  | InteractionUpdateOptions;
+
 export class MessagePayload {
-  public constructor(target: MessageTarget, options: MessageOptions | WebhookMessageOptions);
+  public constructor(target: MessageTarget, options: MessagePayloadOption);
   public body: RawMessagePayloadData | null;
   public get isUser(): boolean;
   public get isWebhook(): boolean;
@@ -1884,13 +1892,13 @@ export class MessagePayload {
   public get isMessageManager(): boolean;
   public get isInteraction(): boolean;
   public files: RawFile[] | null;
-  public options: MessageOptions | WebhookMessageOptions;
+  public options: MessagePayloadOption;
   public target: MessageTarget;
 
   public static create(
     target: MessageTarget,
-    options: string | MessageOptions | WebhookMessageOptions,
+    options: string | MessagePayloadOption,
-    extra?: MessageOptions | WebhookMessageOptions,
+    extra?: MessagePayloadOption,
   ): MessagePayload;
   public static resolveFile(
     fileLike: BufferResolvable | Stream | AttachmentPayload | JSONEncodable<AttachmentPayload>,
@@ -2831,7 +2839,7 @@ export class Webhook extends WebhookMixin() {
     options: string | MessagePayload | WebhookEditMessageOptions,
   ): Promise<Message>;
   public fetchMessage(message: Snowflake, options?: WebhookFetchMessageOptions): Promise<Message>;
-  public send(options: string | MessagePayload | Omit<WebhookMessageOptions, 'flags'>): Promise<Message>;
+  public send(options: string | MessagePayload | WebhookCreateMessageOptions): Promise<Message>;
 }
 
 export class WebhookClient extends WebhookMixin(BaseClient) {
@@ -2844,7 +2852,7 @@ export class WebhookClient extends WebhookMixin(BaseClient) {
     options: string | MessagePayload | WebhookEditMessageOptions,
   ): Promise<APIMessage>;
   public fetchMessage(message: Snowflake, options?: WebhookFetchMessageOptions): Promise<APIMessage>;
-  public send(options: string | MessagePayload | WebhookMessageOptions): Promise<APIMessage>;
+  public send(options: string | MessagePayload | WebhookCreateMessageOptions): Promise<APIMessage>;
 }
 
 export class WebSocketManager extends EventEmitter {
@@ -3627,7 +3635,7 @@ export class UserManager extends CachedManager<Snowflake, User, UserResolvable>
   public deleteDM(user: UserResolvable): Promise<DMChannel>;
   public fetch(user: UserResolvable, options?: BaseFetchOptions): Promise<User>;
   public fetchFlags(user: UserResolvable, options?: BaseFetchOptions): Promise<UserFlagsBitField>;
-  public send(user: UserResolvable, options: string | MessagePayload | MessageOptions): Promise<Message>;
+  public send(user: UserResolvable, options: string | MessagePayload | MessageCreateOptions): Promise<Message>;
 }
 
 export class VoiceStateManager extends CachedManager<Snowflake, VoiceState, typeof VoiceState> {
@@ -3659,7 +3667,7 @@ export function TextBasedChannelMixin<
 ): Constructable<T & Omit<TextBasedChannelFields<InGuild>, I>>;
 
 export interface PartialTextBasedChannelFields<InGuild extends boolean = boolean> {
-  send(options: string | MessagePayload | MessageOptions): Promise<Message<InGuild>>;
+  send(options: string | MessagePayload | MessageCreateOptions): Promise<Message<InGuild>>;
 }
 
 export interface TextBasedChannelFields<InGuild extends boolean = boolean>
@@ -3700,7 +3708,9 @@ export interface PartialWebhookFields {
     options: string | MessagePayload | WebhookEditMessageOptions,
   ): Promise<APIMessage | Message>;
   fetchMessage(message: Snowflake | '@original', options?: WebhookFetchMessageOptions): Promise<APIMessage | Message>;
-  send(options: string | MessagePayload | Omit<WebhookMessageOptions, 'flags'>): Promise<APIMessage | Message>;
+  send(
+    options: string | MessagePayload | InteractionReplyOptions | WebhookCreateMessageOptions,
+  ): Promise<APIMessage | Message>;
 }
 
 export interface WebhookFields extends PartialWebhookFields {
@@ -5023,10 +5033,14 @@ export interface InteractionDeferReplyOptions {
 
 export type InteractionDeferUpdateOptions = Omit<InteractionDeferReplyOptions, 'ephemeral'>;
 
-export interface InteractionReplyOptions extends Omit<WebhookMessageOptions, 'username' | 'avatarURL' | 'flags'> {
+export interface InteractionReplyOptions extends BaseMessageOptions {
+  tts?: boolean;
   ephemeral?: boolean;
   fetchReply?: boolean;
-  flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds' | 'Ephemeral'>, number>;
+  flags?: BitFieldResolvable<
+    Extract<MessageFlagsString, 'Ephemeral' | 'SuppressEmbeds'>,
+    MessageFlags.Ephemeral | MessageFlags.SuppressEmbeds
+  >;
 }
 
 export interface InteractionUpdateOptions extends MessageEditOptions {
@@ -5121,28 +5135,6 @@ export type MessageChannelComponentCollectorOptions<T extends CollectedMessageIn
   'channel' | 'guild' | 'interactionType'
 >;
 
-export interface MessageEditOptions {
-  attachments?: JSONEncodable<AttachmentPayload>[];
-  content?: string | null;
-  embeds?: (JSONEncodable<APIEmbed> | APIEmbed)[] | null;
-  files?: (
-    | BufferResolvable
-    | Stream
-    | JSONEncodable<APIAttachment>
-    | Attachment
-    | AttachmentBuilder
-    | AttachmentPayload
-  )[];
-  flags?: BitFieldResolvable<MessageFlagsString, number>;
-  allowedMentions?: MessageMentionOptions;
-  components?: (
-    | JSONEncodable<APIActionRowComponent<APIMessageActionRowComponent>>
-    | ActionRow<MessageActionRowComponent>
-    | ActionRowData<MessageActionRowComponentData | MessageActionRowComponentBuilder>
-    | APIActionRowComponent<APIMessageActionRowComponent>
-  )[];
-}
-
 export interface MessageEvent {
   data: WebSocket.Data;
   type: string;
@@ -5172,16 +5164,9 @@ export interface MessageMentionOptions {
 
 export type MessageMentionTypes = 'roles' | 'users' | 'everyone';
 
-export interface MessageOptions {
+export interface BaseMessageOptions {
-  tts?: boolean;
+  content?: string;
-  nonce?: string | number;
-  content?: string | null;
   embeds?: (JSONEncodable<APIEmbed> | APIEmbed)[];
-  components?: (
-    | JSONEncodable<APIActionRowComponent<APIMessageActionRowComponent>>
-    | ActionRowData<MessageActionRowComponentData | MessageActionRowComponentBuilder>
-    | APIActionRowComponent<APIMessageActionRowComponent>
-  )[];
   allowedMentions?: MessageMentionOptions;
   files?: (
     | BufferResolvable
@@ -5191,10 +5176,25 @@ export interface MessageOptions {
     | AttachmentBuilder
     | AttachmentPayload
   )[];
+  components?: (
+    | JSONEncodable<APIActionRowComponent<APIMessageActionRowComponent>>
+    | ActionRowData<MessageActionRowComponentData | MessageActionRowComponentBuilder>
+    | APIActionRowComponent<APIMessageActionRowComponent>
+  )[];
+}
+
+export interface MessageCreateOptions extends BaseMessageOptions {
+  tts?: boolean;
+  nonce?: string | number;
   reply?: ReplyOptions;
   stickers?: StickerResolvable[];
+  flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds'>, MessageFlags.SuppressEmbeds>;
+}
+
+export interface MessageEditOptions extends Omit<BaseMessageOptions, 'content'> {
+  content?: string | null;
   attachments?: JSONEncodable<AttachmentPayload>[];
-  flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds'>, number>;
+  flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds'>, MessageFlags.SuppressEmbeds>;
 }
 
 export type MessageReactionResolvable =
@@ -5387,7 +5387,7 @@ export interface ReplyOptions {
   failIfNotExists?: boolean;
 }
 
-export interface ReplyMessageOptions extends Omit<MessageOptions, 'reply'> {
+export interface MessageReplyOptions extends Omit<MessageCreateOptions, 'reply'> {
   failIfNotExists?: boolean;
 }
 
@@ -5608,16 +5608,15 @@ export interface WebhookEditData {
   reason?: string;
 }
 
-export type WebhookEditMessageOptions = Pick<
+export interface WebhookEditMessageOptions extends Omit<MessageEditOptions, 'flags'> {
-  WebhookMessageOptions,
+  threadId?: Snowflake;
-  'content' | 'embeds' | 'files' | 'allowedMentions' | 'components' | 'attachments' | 'threadId'
+}
->;
 
 export interface WebhookFetchMessageOptions {
   threadId?: Snowflake;
 }
 
-export interface WebhookMessageOptions extends Omit<MessageOptions, 'reply' | 'stickers'> {
+export interface WebhookCreateMessageOptions extends Omit<MessageCreateOptions, 'nonce' | 'reply' | 'stickers'> {
   username?: string;
   avatarURL?: string;
   threadId?: Snowflake;