feat(MessageAttachment): description (alt text) support (#6871)

Co-authored-by: D Trombett <maxtromb.dt@gmail.com>

src/rest/APIRequest.js

@@ -50,8 +50,8 @@ class APIRequest {
     let body;
     if (this.options.files?.length) {
       body = new FormData();
-      for (const file of this.options.files) {
+      for (const [index, file] of this.options.files.entries()) {
-        if (file?.file) body.append(file.key ?? file.name, file.file, file.name);
+        if (file?.file) body.append(file.key ?? `files[${index}]`, file.file, file.name);
       }
       if (typeof this.options.data !== 'undefined') {
         if (this.options.dontUsePayloadJSON) {

src/structures/MessageAttachment.js

@@ -21,6 +21,16 @@ class MessageAttachment {
     if (data) this._patch(data);
   }
 
+  /**
+   * Sets the description of this attachment.
+   * @param {string} description The description of the file
+   * @returns {MessageAttachment} This attachment
+   */
+  setDescription(description) {
+    this.description = description;
+    return this;
+  }
+
   /**
    * Sets the file of this attachment.
    * @param {BufferResolvable|Stream} attachment The file
@@ -122,6 +132,16 @@ class MessageAttachment {
       this.contentType ??= null;
     }
 
+    if ('description' in data) {
+      /**
+       * The description (alt text) of this attachment
+       * @type {?string}
+       */
+      this.description = data.description;
+    } else {
+      this.description ??= null;
+    }
+
     /**
      * Whether this attachment is ephemeral
      * @type {boolean}

src/structures/MessagePayload.js

@@ -177,6 +177,16 @@ class MessagePayload {
       }
     }
 
+    const attachments = this.options.files?.map((file, index) => ({
+      id: index.toString(),
+      description: file.description,
+    }));
+    if (Array.isArray(this.options.attachments)) {
+      this.options.attachments.push(...attachments);
+    } else {
+      this.options.attachments = attachments;
+    }
+
     this.data = {
       content,
       tts,

src/structures/interfaces/TextBasedChannel.js

@@ -96,6 +96,7 @@ class TextBasedChannel {
    * @typedef {Object} FileOptions
    * @property {BufferResolvable} attachment File to attach
    * @property {string} [name='file.jpg'] Filename of the attachment
+   * @property {string} description The description of the file
    */
 
   /**
@@ -128,6 +129,7 @@ class TextBasedChannel {
    *   files: [{
    *     attachment: 'entire/path/to/file.jpg',
    *     name: 'file.jpg'
+   *     description: 'A description of the file'
    *   }]
    * })
    *   .then(console.log)
@@ -146,6 +148,7 @@ class TextBasedChannel {
    *   files: [{
    *     attachment: 'entire/path/to/file.jpg',
    *     name: 'file.jpg'
+   *     description: 'A description of the file'
    *   }]
    * })
    *   .then(console.log)

typings/index.d.ts

@@ -1463,6 +1463,7 @@ export class MessageAttachment {
 
   public attachment: BufferResolvable | Stream;
   public contentType: string | null;
+  public description: string | null;
   public ephemeral: boolean;
   public height: number | null;
   public id: Snowflake;
@@ -1472,6 +1473,7 @@ export class MessageAttachment {
   public readonly spoiler: boolean;
   public url: string;
   public width: number | null;
+  public setDescription(description: string): this;
   public setFile(attachment: BufferResolvable | Stream, name?: string): this;
   public setName(name: string): this;
   public setSpoiler(spoiler?: boolean): this;
@@ -4118,6 +4120,7 @@ export interface FetchThreadsOptions {
 export interface FileOptions {
   attachment: BufferResolvable | Stream;
   name?: string;
+  description?: string;
 }
 
 export interface GuildApplicationCommandPermissionData {