feat: Document attachment editing and is_spoiler param (#5235)

packages/types/src/discord/message.ts

@@ -485,7 +485,7 @@ export interface DiscordAttachment {
   width?: number | null;
   /** whether this attachment is ephemeral. Ephemeral attachments will automatically be removed after a set period of time. Ephemeral attachments on messages are guaranteed to be available as long as the message itself exists. */
   ephemeral?: boolean;
-  /** The duration of the audio file for a voice message */
+  /** The duration of the audio or video file */
   duration_secs?: number;
   /** A base64 encoded bytearray representing a sampled waveform for a voice message */
   waveform?: string;

packages/types/src/discordeno/channel.ts

@@ -2,10 +2,10 @@
 
 import type { ChannelFlags, ChannelTypes, ForumLayout, OverwriteTypes, SortOrderTypes, VideoQualityModes } from '../discord/channel.js';
 import type { TargetTypes } from '../discord/invite.js';
-import type { DiscordAttachment, DiscordEmbed, MessageFlags } from '../discord/message.js';
+import type { DiscordEmbed, MessageFlags } from '../discord/message.js';
 import type { BigString, Camelize } from '../shared.js';
 import type { MessageComponents } from './components.js';
-import type { AllowedMentions } from './message.js';
+import type { AllowedMentions, AttachmentRequest } from './message.js';
 import type { FileContent } from './reference.js';
 
 /** https://docs.discord.com/developers/resources/channel#overwrite-object-overwrite-structure */
@@ -372,8 +372,8 @@ export interface ForumAndMediaThreadMessage {
   components?: MessageComponents;
   /** IDs of up to 3 stickers in the server to send in the message */
   stickerIds?: BigString[];
-  /** Attachment objects with `filename` and `description` */
-  attachments?: Pick<DiscordAttachment, 'filename' | 'description' | 'id'>[];
+  /** Metadata for the attachments */
+  attachments?: Partial<AttachmentRequest>[];
   /**
    * Message flags combined as a bitfield, only SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS and IS_COMPONENTS_V2 can be set
    *

packages/types/src/discordeno/message.ts

@@ -1,13 +1,6 @@
 /** Types for: https://docs.discord.com/developers/resources/message */
 
-import type {
-  AllowedMentionsTypes,
-  DiscordAttachment,
-  DiscordEmbed,
-  DiscordMessageReferenceType,
-  DiscordReactionType,
-  MessageFlags,
-} from '../discord/message.js';
+import type { AllowedMentionsTypes, DiscordEmbed, DiscordMessageReferenceType, DiscordReactionType, MessageFlags } from '../discord/message.js';
 import type { BigString, Camelize } from '../shared.js';
 import type { MessageComponents } from './components.js';
 import type { CreatePoll } from './poll.js';
@@ -31,6 +24,41 @@ export interface DiscordenoMessageReference {
   failIfNotExists?: boolean;
 }
 
+/** https://docs.discord.com/developers/resources/message#attachment-object-attachment-request-structure */
+export interface AttachmentRequest {
+  /** Attachment id, for new attachments this must match the `n` in `files[n]` */
+  id: BigString | number;
+  /** Name of file attached */
+  filename?: string;
+  /** The title of the file */
+  title?: string;
+  /**
+   * Description (alt text) for the file
+   *
+   * @remarks
+   * max 1024 characters
+   */
+  description?: string;
+  /**
+   * The duration of the audio or video file
+   *
+   * @remarks
+   * Required for voice messages
+   */
+  durationSecs?: number;
+  /**
+   * Base64 encoded bytearray representing a sampled waveform
+   *
+   * @remarks
+   * Required for voice messages
+   */
+  waweform?: string;
+  /**
+   * Whether the attachment should be marked as a spoiler and blurred until clicked, this sets the `IS_SPOILER` attachment flag
+   */
+  isSpoiler: boolean;
+}
+
 /** https://docs.discord.com/developers/resources/message#allowed-mentions-object-default-settings-for-allowed-mentions */
 export interface AllowedMentions {
   /** An array of allowed mention types to parse from the content. */
@@ -70,7 +98,7 @@ export interface GetMessagesAfter extends GetMessagesLimit {
 /** https://docs.discord.com/developers/resources/channel#get-channel-messages-query-string-params */
 export type GetMessagesOptions = GetMessagesAfter | GetMessagesBefore | GetMessagesAround | GetMessagesLimit;
 
-/** https://docs.discord.com/developers/resources/message#create-message-jsonform-params */
+/** https://docs.discord.com/developers/resources/message#create-message-json/form-params */
 export interface CreateMessageOptions {
   /** The message contents (up to 2000 characters) */
   content?: string;
@@ -90,8 +118,8 @@ export interface CreateMessageOptions {
   stickerIds?: BigString[];
   /** The contents of the files being sent */
   files?: FileContent[];
-  /** Attachment objects with filename and description */
-  attachments?: Pick<DiscordAttachment, 'filename' | 'description' | 'id'>[];
+  /** Attached files to keep and their metadata */
+  attachments?: Partial<AttachmentRequest>[];
   /**
    * Message flags combined as a bitfield
    *
@@ -117,7 +145,7 @@ export interface GetReactions {
   limit?: number;
 }
 
-/** https://docs.discord.com/developers/resources/channel#edit-message-json-params */
+/** https://docs.discord.com/developers/resources/channel#edit-message-json/form-params */
 export interface EditMessage {
   /** The new message contents (up to 2000 characters) */
   content?: string | null;
@@ -138,8 +166,8 @@ export interface EditMessage {
   components?: MessageComponents;
   /** The contents of the files being sent/edited */
   files?: FileContent[];
-  /** When specified (adding new attachments), attachments which are not provided in this list will be removed. */
-  attachments?: Pick<DiscordAttachment, 'filename' | 'description' | 'id'>[];
+  /** Attached files to keep and their metadata. */
+  attachments?: Partial<AttachmentRequest>[];
 }
 
 /** https://docs.discord.com/developers/resources/message#get-channel-pins-query-string-params */

packages/types/src/discordeno/webhook.ts

@@ -1,9 +1,9 @@
 /** Types for: https://docs.discord.com/developers/resources/webhook */
 
-import type { DiscordAttachment, DiscordEmbed } from '../discord/message.js';
+import type { DiscordEmbed } from '../discord/message.js';
 import type { BigString, Camelize } from '../shared.js';
 import type { MessageComponents } from './components.js';
-import type { AllowedMentions } from './message.js';
+import type { AllowedMentions, AttachmentRequest } from './message.js';
 import type { CreatePoll } from './poll.js';
 import type { FileContent } from './reference.js';
 
@@ -25,7 +25,7 @@ export interface ModifyWebhook {
   channelId?: BigString;
 }
 
-/** https://docs.discord.com/developers/resources/webhook#execute-webhook */
+/** https://docs.discord.com/developers/resources/webhook#execute-webhook-json/form-params */
 export interface ExecuteWebhook {
   // Query Parameters
 
@@ -65,8 +65,8 @@ export interface ExecuteWebhook {
   components?: MessageComponents;
   /** The contents of the files being sent */
   files?: FileContent[];
-  /** Attachment objects with filename and description */
-  attachments?: Pick<DiscordAttachment, 'filename' | 'description' | 'id'>[];
+  /** Metadata for the attachments */
+  attachments?: Partial<AttachmentRequest>[];
   /**
    * Message flags combined in a bitfield
    *
@@ -87,7 +87,7 @@ export interface GetWebhookMessageOptions {
   threadId: BigString;
 }
 
-/** https://docs.discord.com/developers/resources/webhook#edit-webhook-message */
+/** https://docs.discord.com/developers/resources/webhook#edit-webhook-message-json/form-params */
 export interface EditWebhookMessageOptions {
   // Query parameters
   /** Id of the thread the message is in */
@@ -124,8 +124,8 @@ export interface EditWebhookMessageOptions {
   components?: MessageComponents;
   /** The contents of the files being sent */
   files?: FileContent[];
-  /** Attached files to keep and possible descriptions for new files */
-  attachments?: Pick<DiscordAttachment, 'filename' | 'description' | 'id'>[];
+  /** Attached files to keep and their metadata */
+  attachments?: Partial<AttachmentRequest>[];
   /**
    * A poll!
    *