From c4f2fc2b0131691f1dbd9f89c50fbff1d62b0ca7 Mon Sep 17 00:00:00 2001
From: Fleny <Fleny113@outlook.com>
Date: Sat, 14 Jun 2025 10:08:58 +0200
Subject: [PATCH] feat(types,bot): add user collectibles (#4225)

---
 packages/bot/src/desiredProperties.ts  | 24 ++++++++++++++++++++----
 packages/bot/src/transformers.ts       | 12 ++++++++++++
 packages/bot/src/transformers/types.ts | 18 ++++++++++++++++++
 packages/bot/src/transformers/user.ts  | 26 ++++++++++++++++++++++++--
 packages/types/src/discord/user.ts     | 20 ++++++++++++++++++++
 5 files changed, 94 insertions(+), 6 deletions(-)

diff --git a/packages/bot/src/desiredProperties.ts b/packages/bot/src/desiredProperties.ts
index 4fc23e6c4..2f26624ee 100644
--- a/packages/bot/src/desiredProperties.ts
+++ b/packages/bot/src/desiredProperties.ts
@@ -7,6 +7,7 @@ import type {
   Attachment,
   AvatarDecorationData,
   Channel,
+  Collectibles,
   Component,
   DefaultReactionEmoji,
   Emoji,
@@ -33,6 +34,7 @@ import type {
   MessageInteractionMetadata,
   MessageReference,
   MessageSnapshot,
+  Nameplate,
   Poll,
   PollAnswer,
   PollAnswerCount,
@@ -63,6 +65,7 @@ export interface TransformersObjects {
   attachment: Attachment
   avatarDecorationData: AvatarDecorationData
   channel: Channel
+  collectibles: Collectibles
   component: Component
   defaultReactionEmoji: DefaultReactionEmoji
   emoji: Emoji
@@ -79,6 +82,8 @@ export interface TransformersObjects {
   interactionResource: InteractionResource
   invite: Invite
   inviteStageInstance: InviteStageInstance
+  lobby: Lobby
+  lobbyMember: LobbyMember
   mediaGalleryItem: MediaGalleryItem
   member: Member
   message: Message
@@ -87,6 +92,7 @@ export interface TransformersObjects {
   messageInteractionMetadata: MessageInteractionMetadata
   messageReference: MessageReference
   messageSnapshot: MessageSnapshot
+  nameplate: Nameplate
   poll: Poll
   pollAnswer: PollAnswer
   pollAnswerCount: PollAnswerCount
@@ -96,16 +102,14 @@ export interface TransformersObjects {
   scheduledEvent: ScheduledEvent
   scheduledEventRecurrenceRule: ScheduledEventRecurrenceRule
   sku: Sku
+  soundboardSound: SoundboardSound
   stageInstance: StageInstance
   sticker: Sticker
+  subscription: Subscription
   unfurledMediaItem: UnfurledMediaItem
   user: User
   voiceState: VoiceState
   webhook: Webhook
-  subscription: Subscription
-  soundboardSound: SoundboardSound
-  lobby: Lobby
-  lobbyMember: LobbyMember
 }
 
 // NOTE: the top-level objects need both the dependencies and alwaysPresents even if empty when the key is specified, this is due the extends & nullability on DesiredPropertiesMetadata
@@ -286,6 +290,10 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       threadMetadata: defaultValue,
       ...desiredProperties.channel,
     },
+    collectibles: {
+      nameplate: defaultValue,
+      ...desiredProperties.collectibles,
+    },
     component: {
       type: defaultValue,
       customId: defaultValue,
@@ -551,6 +559,13 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       endedTimestamp: defaultValue,
       ...desiredProperties.messageCall,
     },
+    nameplate: {
+      skuId: defaultValue,
+      asset: defaultValue,
+      label: defaultValue,
+      palette: defaultValue,
+      ...desiredProperties.nameplate,
+    },
     role: {
       name: defaultValue,
       guildId: defaultValue,
@@ -657,6 +672,7 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       banner: defaultValue,
       avatarDecorationData: defaultValue,
       toggles: defaultValue,
+      collectibles: defaultValue,
       ...desiredProperties.user,
     },
     avatarDecorationData: {
diff --git a/packages/bot/src/transformers.ts b/packages/bot/src/transformers.ts
index 56eabe43b..67a181b3d 100644
--- a/packages/bot/src/transformers.ts
+++ b/packages/bot/src/transformers.ts
@@ -16,6 +16,7 @@ import type {
   DiscordAutoModerationRule,
   DiscordAvatarDecorationData,
   DiscordChannel,
+  DiscordCollectibles,
   DiscordCreateApplicationCommand,
   DiscordDefaultReactionEmoji,
   DiscordEmbed,
@@ -50,6 +51,7 @@ import type {
   DiscordMessageComponent,
   DiscordMessageInteractionMetadata,
   DiscordMessageSnapshot,
+  DiscordNameplate,
   DiscordPoll,
   DiscordPollMedia,
   DiscordPresenceUpdate,
@@ -96,6 +98,7 @@ import {
   type AutoModerationRule,
   type AvatarDecorationData,
   type Channel,
+  type Collectibles,
   type Component,
   type DefaultReactionEmoji,
   type Embed,
@@ -128,6 +131,7 @@ import {
   type MessageCall,
   type MessageInteractionMetadata,
   type MessageSnapshot,
+  type Nameplate,
   type Poll,
   type PollMedia,
   type PresenceUpdate,
@@ -170,6 +174,7 @@ import {
   transformAutoModerationRule,
   transformAvatarDecorationData,
   transformChannel,
+  transformCollectibles,
   transformComponent,
   transformComponentToDiscordComponent,
   transformDefaultReactionEmoji,
@@ -201,6 +206,7 @@ import {
   transformMessageCall,
   transformMessageInteractionMetadata,
   transformMessageSnapshot,
+  transformNameplate,
   transformPoll,
   transformPollMedia,
   transformPresence,
@@ -280,6 +286,7 @@ export type Transformers<TProps extends TransformersDesiredProperties, TBehavior
       avatarDecorationData: SetupDesiredProps<AvatarDecorationData, TProps, TBehavior>,
     ) => any
     channel: (bot: Bot<TProps, TBehavior>, payload: DiscordChannel, channel: SetupDesiredProps<Channel, TProps, TBehavior>) => any
+    collectibles: (bot: Bot<TProps, TBehavior>, payload: DiscordCollectibles, collectibles: SetupDesiredProps<Collectibles, TProps, TBehavior>) => any
     component: (bot: Bot<TProps, TBehavior>, payload: DiscordMessageComponent, component: Component) => any
     defaultReactionEmoji: (
       bot: Bot<TProps, TBehavior>,
@@ -361,6 +368,7 @@ export type Transformers<TProps extends TransformersDesiredProperties, TBehavior
       payload: DiscordMessageSnapshot,
       messageSnapshot: SetupDesiredProps<MessageSnapshot, TProps, TBehavior>,
     ) => any
+    nameplate: (bot: Bot<TProps, TBehavior>, payload: DiscordNameplate, nameplate: SetupDesiredProps<Nameplate, TProps, TBehavior>) => any
     poll: (bot: Bot<TProps, TBehavior>, payload: DiscordPoll, poll: SetupDesiredProps<Poll, TProps, TBehavior>) => any
     pollMedia: (bot: Bot<TProps, TBehavior>, payload: DiscordPollMedia, pollMedia: SetupDesiredProps<PollMedia, TProps, TBehavior>) => any
     presence: (bot: Bot<TProps, TBehavior>, payload: DiscordPresenceUpdate, presence: PresenceUpdate) => any
@@ -445,6 +453,7 @@ export type Transformers<TProps extends TransformersDesiredProperties, TBehavior
     payload: DiscordAvatarDecorationData,
   ) => SetupDesiredProps<AvatarDecorationData, TProps, TBehavior>
   channel: (bot: Bot<TProps, TBehavior>, payload: { channel: DiscordChannel; guildId?: BigString }) => SetupDesiredProps<Channel, TProps, TBehavior>
+  collectibles: (bot: Bot<TProps, TBehavior>, payload: DiscordCollectibles) => SetupDesiredProps<Collectibles, TProps, TBehavior>
   component: (bot: Bot<TProps, TBehavior>, payload: DiscordMessageComponent) => Component
   defaultReactionEmoji: (
     bot: Bot<TProps, TBehavior>,
@@ -509,6 +518,7 @@ export type Transformers<TProps extends TransformersDesiredProperties, TBehavior
     bot: Bot<TProps, TBehavior>,
     payload: { messageSnapshot: DiscordMessageSnapshot; shardId: number },
   ) => SetupDesiredProps<MessageSnapshot, TProps, TBehavior>
+  nameplate: (bot: Bot<TProps, TBehavior>, payload: DiscordNameplate) => SetupDesiredProps<Nameplate, TProps, TBehavior>
   poll: (bot: Bot<TProps, TBehavior>, payload: DiscordPoll) => SetupDesiredProps<Poll, TProps, TBehavior>
   pollMedia: (bot: Bot<TProps, TBehavior>, payload: DiscordPollMedia) => SetupDesiredProps<PollMedia, TProps, TBehavior>
   presence: (bot: Bot<TProps, TBehavior>, payload: DiscordPresenceUpdate) => PresenceUpdate
@@ -651,6 +661,7 @@ export function createTransformers<TProps extends TransformersDesiredProperties,
     automodRule: options.automodRule ?? transformAutoModerationRule,
     avatarDecorationData: options.avatarDecorationData ?? transformAvatarDecorationData,
     channel: options.channel ?? transformChannel,
+    collectibles: options.collectibles ?? transformCollectibles,
     component: options.component ?? transformComponent,
     defaultReactionEmoji: options.defaultReactionEmoji ?? transformDefaultReactionEmoji,
     embed: options.embed ?? transformEmbed,
@@ -680,6 +691,7 @@ export function createTransformers<TProps extends TransformersDesiredProperties,
     messageCall: options.messageCall ?? transformMessageCall,
     messageInteractionMetadata: options.messageInteractionMetadata ?? transformMessageInteractionMetadata,
     messageSnapshot: options.messageSnapshot ?? transformMessageSnapshot,
+    nameplate: options.nameplate ?? transformNameplate,
     poll: options.poll ?? transformPoll,
     pollMedia: options.pollMedia ?? transformPollMedia,
     presence: options.presence ?? transformPresence,
diff --git a/packages/bot/src/transformers/types.ts b/packages/bot/src/transformers/types.ts
index 43d60bd98..7e2ebdda3 100644
--- a/packages/bot/src/transformers/types.ts
+++ b/packages/bot/src/transformers/types.ts
@@ -1766,6 +1766,24 @@ export interface User {
   mfaEnabled: boolean
   /** Whether the email on this account has been verified */
   verified: boolean
+  /** data for the user's collectibles */
+  collectibles?: Collectibles
+}
+
+export interface Collectibles {
+  /** object mapping of nameplate data */
+  nameplate?: Nameplate
+}
+
+export interface Nameplate {
+  /** the nameplate's id */
+  skuId: bigint
+  /** path to the nameplate asset */
+  asset: string
+  /** the label of this nameplate. Currently unused */
+  label: string
+  /** background color of the nameplate, one of: `crimson`, `berry`, `sky`, `teal`, `forest`, `bubble_gum`, `violet`, `cobalt`, `clover`, `lemon`, `white` */
+  palette: string
 }
 
 export interface VoiceRegion {
diff --git a/packages/bot/src/transformers/user.ts b/packages/bot/src/transformers/user.ts
index 5538de412..bf712db15 100644
--- a/packages/bot/src/transformers/user.ts
+++ b/packages/bot/src/transformers/user.ts
@@ -1,6 +1,6 @@
-import type { DiscordUser } from '@discordeno/types'
+import type { DiscordCollectibles, DiscordNameplate, DiscordUser } from '@discordeno/types'
 import { iconHashToBigInt } from '@discordeno/utils'
-import { type InternalBot, ToggleBitfield, type User, UserToggles } from '../index.js'
+import { type Collectibles, type InternalBot, type Nameplate, ToggleBitfield, type User, UserToggles } from '../index.js'
 
 export const baseUser: InternalBot['transformers']['$inferredTypes']['user'] = {
   // This allows typescript to still check for type errors on functions below
@@ -42,6 +42,28 @@ export function transformUser(bot: InternalBot, payload: DiscordUser): typeof bo
   if (props.accentColor && payload.accent_color) user.accentColor = payload.accent_color
   if (props.avatarDecorationData && payload.avatar_decoration_data)
     user.avatarDecorationData = bot.transformers.avatarDecorationData(bot, payload.avatar_decoration_data)
+  if (props.collectibles && payload.collectibles) user.collectibles = bot.transformers.collectibles(bot, payload.collectibles)
 
   return bot.transformers.customizers.user(bot, payload, user)
 }
+
+export function transformCollectibles(bot: InternalBot, payload: DiscordCollectibles): Collectibles {
+  const collectibles = {} as Collectibles
+  const props = bot.transformers.desiredProperties.collectibles
+
+  if (props.nameplate && payload.nameplate) collectibles.nameplate = bot.transformers.nameplate(bot, payload.nameplate)
+
+  return bot.transformers.customizers.collectibles(bot, payload, collectibles)
+}
+
+export function transformNameplate(bot: InternalBot, payload: DiscordNameplate): Nameplate {
+  const nameplate = {} as Nameplate
+  const props = bot.transformers.desiredProperties.nameplate
+
+  if (props.skuId && payload.sku_id) nameplate.skuId = bot.transformers.snowflake(payload.sku_id)
+  if (props.asset && payload.asset) nameplate.asset = payload.asset
+  if (props.label && payload.label) nameplate.label = payload.label
+  if (props.palette && payload.palette) nameplate.palette = payload.palette
+
+  return bot.transformers.customizers.nameplate(bot, payload, nameplate)
+}
diff --git a/packages/types/src/discord/user.ts b/packages/types/src/discord/user.ts
index 8d000c93d..c571dea11 100644
--- a/packages/types/src/discord/user.ts
+++ b/packages/types/src/discord/user.ts
@@ -38,6 +38,8 @@ export interface DiscordUser {
   banner?: string
   /** data for the user's avatar decoration */
   avatar_decoration_data?: DiscordAvatarDecorationData
+  /** data for the user's collectibles */
+  collectibles?: DiscordCollectibles
 }
 
 /** https://discord.com/developers/docs/resources/user#user-object-user-flags */
@@ -75,6 +77,24 @@ export interface DiscordAvatarDecorationData {
   sku_id: string
 }
 
+/** https://discord.com/developers/docs/resources/user#collectibles-collectible-structure */
+export interface DiscordCollectibles {
+  /** object mapping of nameplate data */
+  nameplate?: DiscordNameplate
+}
+
+/** https://discord.com/developers/docs/resources/user#nameplate-nameplate-structure */
+export interface DiscordNameplate {
+  /** the nameplate's id */
+  sku_id: string
+  /** path to the nameplate asset */
+  asset: string
+  /** the label of this nameplate. Currently unused */
+  label: string
+  /** background color of the nameplate, one of: `crimson`, `berry`, `sky`, `teal`, `forest`, `bubble_gum`, `violet`, `cobalt`, `clover`, `lemon`, `white` */
+  palette: string
+}
+
 /** https://discord.com/developers/docs/resources/user#connection-object-connection-structure */
 export interface DiscordConnection {
   /** id of the connection account */