feat!: Document more attachment flags and fields (#5234)

* feat: Document more attachment flags and fields

* Update packages/types/src/discord/message.ts

Co-authored-by: stickz <38146668+AwesomeStickz@users.noreply.github.com>

* fix!: Add missing optionals, remove EmbedThumbnail

packages/bot/src/desiredProperties.ts

@@ -283,6 +283,11 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       duration_secs: defaultValue,
       waveform: defaultValue,
       flags: defaultValue,
+      application: defaultValue,
+      clipCreatedAt: defaultValue,
+      clipParticipants: defaultValue,
+      placeholder: defaultValue,
+      placeholderVersion: defaultValue,
       ...desiredProperties.attachment,
     },
     channel: {
@@ -714,6 +719,9 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       width: defaultValue,
       contentType: defaultValue,
       attachmentId: defaultValue,
+      flags: defaultValue,
+      placeholder: defaultValue,
+      placeholderVersion: defaultValue,
       ...desiredProperties.unfurledMediaItem,
     },
     user: {

packages/bot/src/transformers/attachment.ts

@@ -16,11 +16,17 @@ export function transformAttachment(bot: Bot, payload: DiscordAttachment): typeo
   if (props.proxyUrl && payload.proxy_url) attachment.proxyUrl = payload.proxy_url;
   if (props.height && payload.height) attachment.height = payload.height;
   if (props.width && payload.width) attachment.width = payload.width;
+  if (props.placeholder && payload.placeholder) attachment.placeholder = payload.placeholder;
+  if (props.placeholderVersion && payload.placeholder_version) attachment.placeholderVersion = payload.placeholder_version;
   if (props.ephemeral && payload.ephemeral) attachment.ephemeral = payload.ephemeral;
   if (props.description && payload.description) attachment.description = payload.description;
   if (props.duration_secs && payload.duration_secs) attachment.duration_secs = payload.duration_secs;
   if (props.waveform && payload.waveform) attachment.waveform = payload.waveform;
   if (props.flags) attachment.flags = payload.flags;
+  if (props.clipParticipants && payload.clip_participants)
+    attachment.clipParticipants = payload.clip_participants.map((user) => bot.transformers.user(bot, user));
+  if (props.clipCreatedAt && payload.clip_created_at) attachment.clipCreatedAt = payload.clip_created_at;
+  if (props.application && payload.application) attachment.application = bot.transformers.application(bot, payload.application);
 
   return bot.transformers.customizers.attachment(bot, payload, attachment);
 }

packages/bot/src/transformers/component.ts

@@ -39,6 +39,7 @@ import {
 } from '@discordeno/types';
 import type { Bot } from '../bot.js';
 import type { DesiredPropertiesBehavior, SetupDesiredProps, TransformersDesiredProperties } from '../desiredProperties.js';
+import { ToggleBitfield } from './toggles/ToggleBitfield.js';
 import type { Component, MediaGalleryItem, UnfurledMediaItem } from './types.js';
 
 export function transformComponent(bot: Bot, payload: DiscordMessageComponent | DiscordMessageComponentFromModalInteractionResponse): Component {
@@ -119,7 +120,10 @@ export function transformUnfurledMediaItem(bot: Bot, payload: DiscordUnfurledMed
   if (props.proxyUrl && payload.proxy_url) mediaItem.proxyUrl = payload.proxy_url;
   if (props.height && payload.height) mediaItem.height = payload.height;
   if (props.width && payload.width) mediaItem.width = payload.width;
+  if (props.placeholder && payload.placeholder) mediaItem.placeholder = payload.placeholder;
+  if (props.placeholderVersion && payload.placeholder_version) mediaItem.placeholderVersion = payload.placeholder_version;
   if (props.contentType && payload.content_type) mediaItem.contentType = payload.content_type;
+  if (props.flags && payload.flags) mediaItem.flags = new ToggleBitfield(payload.flags);
   if (props.attachmentId && payload.attachment_id) mediaItem.attachmentId = bot.transformers.snowflake(payload.attachment_id);
 
   return bot.transformers.customizers.unfurledMediaItem(bot, payload, mediaItem);

packages/bot/src/transformers/embed.ts

@@ -1,5 +1,6 @@
 import type { DiscordEmbed } from '@discordeno/types';
 import type { Bot } from '../bot.js';
+import { ToggleBitfield } from './toggles/ToggleBitfield.js';
 import type { Embed } from './types.js';
 
 export function transformEmbed(bot: Bot, payload: DiscordEmbed): Embed {
@@ -23,6 +24,11 @@ export function transformEmbed(bot: Bot, payload: DiscordEmbed): Embed {
           proxyUrl: payload.image.proxy_url,
           height: payload.image.height,
           width: payload.image.width,
+          contentType: payload.image.content_type,
+          placeholder: payload.image.placeholder,
+          placeholderVersion: payload.image.placeholder_version,
+          description: payload.image.description,
+          flags: payload.image.flags ? new ToggleBitfield(payload.image.flags) : undefined,
         }
       : undefined,
     thumbnail: payload.thumbnail
@@ -31,6 +37,11 @@ export function transformEmbed(bot: Bot, payload: DiscordEmbed): Embed {
           proxyUrl: payload.thumbnail.proxy_url,
           height: payload.thumbnail.height,
           width: payload.thumbnail.width,
+          contentType: payload.thumbnail.content_type,
+          placeholder: payload.thumbnail.placeholder,
+          placeholderVersion: payload.thumbnail.placeholder_version,
+          description: payload.thumbnail.description,
+          flags: payload.thumbnail.flags ? new ToggleBitfield(payload.thumbnail.flags) : undefined,
         }
       : undefined,
     video: payload.video
@@ -39,6 +50,11 @@ export function transformEmbed(bot: Bot, payload: DiscordEmbed): Embed {
           proxyUrl: payload.video.proxy_url,
           height: payload.video.height,
           width: payload.video.width,
+          contentType: payload.video.content_type,
+          placeholder: payload.video.placeholder,
+          placeholderVersion: payload.video.placeholder_version,
+          description: payload.video.description,
+          flags: payload.video.flags ? new ToggleBitfield(payload.video.flags) : undefined,
         }
       : undefined,
     provider: payload.provider,
@@ -51,6 +67,7 @@ export function transformEmbed(bot: Bot, payload: DiscordEmbed): Embed {
         }
       : undefined,
     fields: payload.fields,
+    flags: payload.flags ? new ToggleBitfield(payload.flags) : undefined,
   } as Embed;
 
   return bot.transformers.customizers.embed(bot, payload, embed);

packages/bot/src/transformers/reverse/component.ts

@@ -91,7 +91,10 @@ export function transformUnfurledMediaItemToDiscordUnfurledMediaItem(bot: Bot, p
     proxy_url: payload.proxyUrl,
     height: payload.height,
     width: payload.width,
+    placeholder: payload.placeholder,
+    placeholder_version: payload.placeholderVersion,
     content_type: payload.contentType,
+    flags: payload.flags?.bitfield,
     attachment_id: payload.attachmentId ? bot.transformers.reverse.snowflake(payload.attachmentId) : undefined,
   };
 }

packages/bot/src/transformers/reverse/embed.ts

@@ -23,6 +23,11 @@ export function transformEmbedToDiscordEmbed(_bot: Bot, payload: Embed): Discord
           proxy_url: payload.image.proxyUrl,
           height: payload.image.height,
           width: payload.image.width,
+          content_type: payload.image.contentType,
+          placeholder: payload.image.placeholder,
+          placeholder_version: payload.image.placeholderVersion,
+          description: payload.image.description,
+          flags: payload.image.flags?.bitfield,
         }
       : undefined,
     thumbnail: payload.thumbnail
@@ -31,6 +36,11 @@ export function transformEmbedToDiscordEmbed(_bot: Bot, payload: Embed): Discord
           proxy_url: payload.thumbnail.proxyUrl,
           height: payload.thumbnail.height,
           width: payload.thumbnail.width,
+          content_type: payload.thumbnail.contentType,
+          placeholder: payload.thumbnail.placeholder,
+          placeholder_version: payload.thumbnail.placeholderVersion,
+          description: payload.thumbnail.description,
+          flags: payload.thumbnail.flags?.bitfield,
         }
       : undefined,
     video: payload.video
@@ -39,6 +49,11 @@ export function transformEmbedToDiscordEmbed(_bot: Bot, payload: Embed): Discord
           proxy_url: payload.video.proxyUrl,
           height: payload.video.height,
           width: payload.video.width,
+          content_type: payload.video.contentType,
+          placeholder: payload.video.placeholder,
+          placeholder_version: payload.video.placeholderVersion,
+          description: payload.video.description,
+          flags: payload.video.flags?.bitfield,
         }
       : undefined,
     provider: payload.provider,

packages/bot/src/transformers/types.ts

@@ -25,6 +25,8 @@ import type {
   DiscordAuditLogChange,
   DiscordAutoModerationRuleTriggerMetadataPresets,
   DiscordBaseTheme,
+  DiscordEmbedFlags,
+  DiscordEmbedMediaFlags,
   DiscordEntitlementType,
   DiscordGuildOnboardingMode,
   DiscordGuildOnboardingPromptType,
@@ -40,6 +42,7 @@ import type {
   DiscordSubscriptionStatus,
   DiscordTeamMemberRole,
   DiscordTemplateSerializedSourceGuild,
+  DiscordUnfurledMediaItemFlags,
   DiscordWebhookEventType,
   EmbedTypes,
   ExplicitContentFilterLevels,
@@ -316,10 +319,14 @@ export interface Attachment {
   id: bigint;
   /** description for the file (max 1024 characters) */
   description?: string;
-  /** Height of file (if image) */
+  /** Height of file (if image or video) */
   height?: number;
-  /** Width of file (if image) */
+  /** Width of file (if image or video) */
   width?: number;
+  /** Thumbhash placeholder (if image or video) */
+  placeholder?: string;
+  /** Version of the placeholder (if image or video) */
+  placeholderVersion?: number;
   /** 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 */
@@ -328,6 +335,12 @@ export interface Attachment {
   waveform?: string;
   /** Attachment flags combined as a bitfield */
   flags?: AttachmentFlags;
+  /** for Clips, array of users who were in the stream */
+  clipParticipants?: User[];
+  /** for Clips, when the clip was created. ISO8601 timestamp */
+  clipCreatedAt?: string;
+  /** for Clips, the application in the stream, if recognized */
+  application?: Application;
 }
 
 export interface AuditLogEntry {
@@ -687,8 +700,21 @@ export interface UnfurledMediaItem {
   height?: number | null;
   /** The width of the media item. This field is ignored and provided by the API as part of the response */
   width?: number | null;
+  /** Thumbhash placeholder if image or video. This field is ignored and provided by the API as part of the response */
+  placeholder?: string;
+  /** Version of the placeholder (if image or video). This field is ignored and provided by the API as part of the response */
+  placeholderVersion?: number;
   /** The media type of the content. This field is ignored and provided by the API as part of the response */
   contentType?: string;
+  /**
+   * Unfurled media item flags combined as a bitfield
+   *
+   * @remarks
+   * This field is ignored and provided by the API as part of the response
+   *
+   * @see {@link DiscordUnfurledMediaItemFlags}
+   */
+  flags?: ToggleBitfield;
   /** The id of the uploaded attachment. Only present if the media was uploaded as an attachment. This field is ignored and provided by the API as part of the response */
   attachmentId?: bigint;
 }
@@ -719,10 +745,12 @@ export interface Embed {
   timestamp?: number;
   color?: number;
   footer?: EmbedFooter;
-  thumbnail?: EmbedThumbnail;
+  thumbnail?: EmbedImage;
   provider?: EmbedProvider;
   author?: EmbedAuthor;
   fields?: EmbedField[];
+  /** @see {@link DiscordEmbedFlags} */
+  flags?: ToggleBitfield;
 }
 
 export interface EmbedImage {
@@ -730,6 +758,16 @@ export interface EmbedImage {
   height?: number;
   width?: number;
   url: string;
+  contentType?: string;
+  placeholder?: string;
+  placeholderVersion?: number;
+  description?: string;
+  /**
+   * Embed media flags combined as a bitfield
+   *
+   * @see {@link DiscordEmbedMediaFlags}
+   */
+  flags?: ToggleBitfield;
 }
 
 export interface EmbedVideo {
@@ -737,6 +775,16 @@ export interface EmbedVideo {
   proxyUrl?: string;
   height?: number;
   width?: number;
+  contentType?: string;
+  placeholder?: string;
+  placeholderVersion?: number;
+  description?: string;
+  /**
+   * Embed media flags combined as a bitfield
+   *
+   * @see {@link DiscordEmbedMediaFlags}
+   */
+  flags?: ToggleBitfield;
 }
 
 export interface EmbedFooter {
@@ -745,13 +793,6 @@ export interface EmbedFooter {
   text: string;
 }
 
-export interface EmbedThumbnail {
-  proxyUrl?: string;
-  height?: number;
-  width?: number;
-  url: string;
-}
-
 export interface EmbedProvider {
   name?: string;
   url?: string;