refactor!: remove AttachmentBuilder and support new file body encodables

packages/builders/src/messages/Attachment.ts

@@ -28,6 +28,11 @@ export class AttachmentBuilder implements JSONEncodable<RESTAPIAttachment> {
 	 * Creates a new attachment builder.
 	 *
 	 * @param data - The API data to create this attachment with
+	 * @example
+	 * ```ts
+	 * const attachment = new AttachmentBuilder().setId(1).setFileData(':)').setFilename('smiley.txt')
+	 * ```
+	 * @remarks Please note that the `id` field is required, it's rather easy to miss!
 	 */
 	public constructor(data: Partial<RESTAPIAttachment> = {}) {
 		this.data = structuredClone(data);

packages/discord.js/src/index.js

@@ -111,7 +111,6 @@ exports.ApplicationEmoji = require('./structures/ApplicationEmoji.js').Applicati
 exports.ApplicationRoleConnectionMetadata =
   require('./structures/ApplicationRoleConnectionMetadata.js').ApplicationRoleConnectionMetadata;
 exports.Attachment = require('./structures/Attachment.js').Attachment;
-exports.AttachmentBuilder = require('./structures/AttachmentBuilder.js').AttachmentBuilder;
 exports.AutocompleteInteraction = require('./structures/AutocompleteInteraction.js').AutocompleteInteraction;
 exports.AutoModerationActionExecution =
   require('./structures/AutoModerationActionExecution.js').AutoModerationActionExecution;

packages/discord.js/src/managers/ChannelManager.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const process = require('node:process');
-const { lazy } = require('@discordjs/util');
+const { lazy, isFileBodyEncodable, isJSONEncodable } = require('@discordjs/util');
 const { Routes } = require('discord-api-types/v10');
 const { BaseChannel } = require('../structures/BaseChannel.js');
 const { MessagePayload } = require('../structures/MessagePayload.js');
@@ -147,7 +147,7 @@ class ChannelManager extends CachedManager {
    * Creates a message in a channel.
    *
    * @param {TextChannelResolvable} channel The channel to send the message to
-   * @param {string|MessagePayload|MessageCreateOptions} options The options to provide
+   * @param {string|MessagePayload|MessageCreateOptions|JSONEncodable<RESTPostAPIChannelMessageJSONBody>|FileBodyEncodable<RESTPostAPIChannelMessageJSONBody>} options The options to provide
    * @returns {Promise<Message>}
    * @example
    * // Send a basic message
@@ -174,18 +174,21 @@ class ChannelManager extends CachedManager {
    *   .catch(console.error);
    */
   async createMessage(channel, options) {
-    let messagePayload;
+    let payload;
 
     if (options instanceof MessagePayload) {
-      messagePayload = options.resolveBody();
+      payload = await options.resolveBody().resolveFiles();
+    } else if (isFileBodyEncodable(options)) {
+      payload = options.toFileBody();
+    } else if (isJSONEncodable(options)) {
+      payload = { body: options.toJSON() };
     } else {
-      messagePayload = MessagePayload.create(this, options).resolveBody();
+      payload = await MessagePayload.create(this, options).resolveBody().resolveFiles();
     }
 
     const resolvedChannelId = this.resolveId(channel);
     const resolvedChannel = this.resolve(channel);
-    const { body, files } = await messagePayload.resolveFiles();
-    const data = await this.client.rest.post(Routes.channelMessages(resolvedChannelId), { body, files });
+    const data = await this.client.rest.post(Routes.channelMessages(resolvedChannelId), payload);
 
     return resolvedChannel?.messages._add(data) ?? new (getMessage())(this.client, data);
   }

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

@@ -2,6 +2,7 @@
 
 const { Collection } = require('@discordjs/collection');
 const { makeURLSearchParams } = require('@discordjs/rest');
+const { isFileBodyEncodable, isJSONEncodable } = require('@discordjs/util');
 const { Routes } = require('discord-api-types/v10');
 const { DiscordjsTypeError, ErrorCodes } = require('../errors/index.js');
 const { Message } = require('../structures/Message.js');
@@ -223,21 +224,27 @@ class MessageManager extends CachedManager {
    * Edits a message, even if it's not cached.
    *
    * @param {MessageResolvable} message The message to edit
-   * @param {string|MessageEditOptions|MessagePayload} options The options to edit the message
+   * @param {string|MessageEditOptions|MessagePayload|FileBodyEncodable<RESTPatchAPIChannelMessageJSONBody>|JSONEncodable<RESTPatchAPIChannelMessageJSONBody>} options The options to edit the message
    * @returns {Promise<Message>}
    */
   async edit(message, options) {
     const messageId = this.resolveId(message);
     if (!messageId) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
 
-    const { body, files } = await (
-      options instanceof MessagePayload
-        ? options
-        : MessagePayload.create(message instanceof Message ? message : this, options)
-    )
-      .resolveBody()
-      .resolveFiles();
-    const data = await this.client.rest.patch(Routes.channelMessage(this.channel.id, messageId), { body, files });
+    let payload;
+    if (options instanceof MessagePayload) {
+      payload = await options.resolveBody().resolveFiles();
+    } else if (isFileBodyEncodable(options)) {
+      payload = options.toFileBody();
+    } else if (isJSONEncodable(options)) {
+      payload = { body: options.toJSON() };
+    } else {
+      payload = await MessagePayload.create(message instanceof Message ? message : this, options)
+        .resolveBody()
+        .resolveFiles();
+    }
+
+    const data = await this.client.rest.patch(Routes.channelMessage(this.channel.id, messageId), payload);
 
     const existing = this.cache.get(messageId);
     if (existing) {

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

@@ -849,7 +849,7 @@ class Message extends Base {
   /**
    * Edits the content of the message.
    *
-   * @param {string|MessagePayload|MessageEditOptions} options The options to provide
+   * @param {string|MessageEditOptions|MessagePayload|FileBodyEncodable<RESTPatchAPIChannelMessageJSONBody>|JSONEncodable<RESTPatchAPIChannelMessageJSONBody>} options The options to provide
    * @returns {Promise<Message>}
    * @example
    * // Update the content of a message

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

@@ -197,8 +197,13 @@ class MessagePayload {
       waveform: file.waveform,
       duration_secs: file.duration,
     }));
+
+    // Only passable during edits
     if (Array.isArray(this.options.attachments)) {
-      this.options.attachments.push(...(attachments ?? []));
+      this.options.attachments = this.options.attachments
+        // Note how we don't check for file body encodable, since we aren't expecting file data here
+        .map(attachment => (isJSONEncodable(attachment) ? attachment.toJSON() : attachment))
+        .concat(attachments ?? []);
     } else {
       this.options.attachments = attachments;
     }

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

@@ -88,7 +88,7 @@ class TextBasedChannel {
    * @property {Array<(EmbedBuilder|Embed|APIEmbed)>} [embeds] The embeds for the message
    * @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
    * (see {@link https://discord.com/developers/docs/resources/message#allowed-mentions-object here} for more details)
-   * @property {Array<(AttachmentBuilder|Attachment|AttachmentPayload|BufferResolvable)>} [files]
+   * @property {Array<(Attachment|AttachmentPayload|BufferResolvable|FileBodyEncodable<APIAttachment>|Stream)>} [files]
    * The files to send with the message.
    * @property {Array<(ActionRowBuilder|MessageTopLevelComponent|APIMessageTopLevelComponent)>} [components]
    * Action rows containing interactive components for the message (buttons, select menus) and other
@@ -156,7 +156,7 @@ class TextBasedChannel {
   /**
    * Sends a message to this channel.
    *
-   * @param {string|MessagePayload|MessageCreateOptions} options The options to provide
+   * @param {string|MessagePayload|MessageCreateOptions|JSONEncodable<RESTPostAPIChannelMessageJSONBody>|FileBodyEncodable<RESTPostAPIChannelMessageJSONBody>} options The options to provide
    * @returns {Promise<Message>}
    * @example
    * // Send a basic message

packages/discord.js/src/util/APITypes.js

@@ -683,3 +683,13 @@
  * @external WebhookType
  * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/WebhookType}
  */
+
+/**
+ * @external RESTPostAPIChannelMessageJSONBody
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/interface/RESTPostAPIChannelMessageJSONBody}
+ */
+
+/**
+ * @external RESTPatchAPIChannelMessageJSONBody
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/interface/RESTPatchAPIChannelMessageJSONBody}
+ */