From 07a094e7e430899a62c2f9252a094b2a9c45183b Mon Sep 17 00:00:00 2001
From: Fleny <Fleny113@outlook.com>
Date: Mon, 7 Jul 2025 09:36:31 +0200
Subject: [PATCH] feat: role gradient colors (#4239)

* sort GuildFeatures

* feat: role gradient colors

* Use deprecated jsdoc tag

---------

Co-authored-by: Awesome Stickz <awesome@stickz.dev>
---
 packages/bot/src/desiredProperties.ts         |  9 +++
 packages/bot/src/transformers.ts              |  7 ++
 packages/bot/src/transformers/role.ts         | 17 ++++-
 .../bot/src/transformers/toggles/guild.ts     | 11 +++-
 packages/bot/src/transformers/types.ts        | 16 ++++-
 packages/types/src/discord/guild.ts           | 66 ++++++++++---------
 packages/types/src/discord/permissions.ts     | 17 ++++-
 packages/types/src/discordeno.ts              | 25 ++++++-
 8 files changed, 129 insertions(+), 39 deletions(-)

diff --git a/packages/bot/src/desiredProperties.ts b/packages/bot/src/desiredProperties.ts
index 2f26624ee..cc7df07fe 100644
--- a/packages/bot/src/desiredProperties.ts
+++ b/packages/bot/src/desiredProperties.ts
@@ -41,6 +41,7 @@ import type {
   PollMedia,
   PollResult,
   Role,
+  RoleColors,
   ScheduledEvent,
   ScheduledEventRecurrenceRule,
   Sku,
@@ -99,6 +100,7 @@ export interface TransformersObjects {
   pollMedia: PollMedia
   pollResult: PollResult
   role: Role
+  roleColors: RoleColors
   scheduledEvent: ScheduledEvent
   scheduledEventRecurrenceRule: ScheduledEventRecurrenceRule
   sku: Sku
@@ -571,6 +573,7 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       guildId: defaultValue,
       position: defaultValue,
       color: defaultValue,
+      colors: defaultValue,
       id: defaultValue,
       permissions: defaultValue,
       icon: defaultValue,
@@ -580,6 +583,12 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
       toggles: defaultValue,
       ...desiredProperties.role,
     },
+    roleColors: {
+      primaryColor: defaultValue,
+      secondaryColor: defaultValue,
+      tertiaryColor: defaultValue,
+      ...desiredProperties.roleColors,
+    },
     scheduledEvent: {
       id: defaultValue,
       guildId: defaultValue,
diff --git a/packages/bot/src/transformers.ts b/packages/bot/src/transformers.ts
index c6634398b..3c6a83eac 100644
--- a/packages/bot/src/transformers.ts
+++ b/packages/bot/src/transformers.ts
@@ -56,6 +56,7 @@ import type {
   DiscordPollMedia,
   DiscordPresenceUpdate,
   DiscordRole,
+  DiscordRoleColors,
   DiscordScheduledEvent,
   DiscordScheduledEventRecurrenceRule,
   DiscordSku,
@@ -136,6 +137,7 @@ import {
   type PollMedia,
   type PresenceUpdate,
   type Role,
+  type RoleColors,
   type ScheduledEvent,
   type ScheduledEventRecurrenceRule,
   type Sku,
@@ -211,6 +213,7 @@ import {
   transformPollMedia,
   transformPresence,
   transformRole,
+  transformRoleColors,
   transformScheduledEvent,
   transformScheduledEventRecurrenceRule,
   transformSku,
@@ -373,6 +376,7 @@ export type Transformers<TProps extends TransformersDesiredProperties, TBehavior
     pollMedia: (bot: Bot<TProps, TBehavior>, payload: DiscordPollMedia, pollMedia: SetupDesiredProps<PollMedia, TProps, TBehavior>) => any
     presence: (bot: Bot<TProps, TBehavior>, payload: DiscordPresenceUpdate, presence: PresenceUpdate) => any
     role: (bot: Bot<TProps, TBehavior>, payload: DiscordRole, role: SetupDesiredProps<Role, TProps, TBehavior>) => any
+    roleColors: (bot: Bot<TProps, TBehavior>, payload: DiscordRoleColors, roleColors: SetupDesiredProps<RoleColors, TProps, TBehavior>) => any
     scheduledEvent: (
       bot: Bot<TProps, TBehavior>,
       payload: DiscordScheduledEvent,
@@ -523,6 +527,7 @@ export type Transformers<TProps extends TransformersDesiredProperties, TBehavior
   pollMedia: (bot: Bot<TProps, TBehavior>, payload: DiscordPollMedia) => SetupDesiredProps<PollMedia, TProps, TBehavior>
   presence: (bot: Bot<TProps, TBehavior>, payload: DiscordPresenceUpdate) => PresenceUpdate
   role: (bot: Bot<TProps, TBehavior>, payload: { role: DiscordRole; guildId: BigString }) => SetupDesiredProps<Role, TProps, TBehavior>
+  roleColors: (bot: Bot<TProps, TBehavior>, payload: DiscordRoleColors) => SetupDesiredProps<RoleColors, TProps, TBehavior>
   scheduledEvent: (bot: Bot<TProps, TBehavior>, payload: DiscordScheduledEvent) => SetupDesiredProps<ScheduledEvent, TProps, TBehavior>
   scheduledEventRecurrenceRule: (
     bot: Bot<TProps, TBehavior>,
@@ -608,6 +613,7 @@ export function createTransformers<TProps extends TransformersDesiredProperties,
       pollMedia: options.customizers?.pollMedia ?? defaultCustomizer,
       presence: options.customizers?.presence ?? defaultCustomizer,
       role: options.customizers?.role ?? defaultCustomizer,
+      roleColors: options.customizers?.roleColors ?? defaultCustomizer,
       scheduledEvent: options.customizers?.scheduledEvent ?? defaultCustomizer,
       scheduledEventRecurrenceRule: options.customizers?.scheduledEventRecurrenceRule ?? defaultCustomizer,
       sku: options.customizers?.sku ?? defaultCustomizer,
@@ -698,6 +704,7 @@ export function createTransformers<TProps extends TransformersDesiredProperties,
     pollMedia: options.pollMedia ?? transformPollMedia,
     presence: options.presence ?? transformPresence,
     role: options.role ?? transformRole,
+    roleColors: options.roleColors ?? transformRoleColors,
     scheduledEvent: options.scheduledEvent ?? transformScheduledEvent,
     scheduledEventRecurrenceRule: options.scheduledEventRecurrenceRule ?? transformScheduledEventRecurrenceRule,
     sku: options.sku ?? transformSku,
diff --git a/packages/bot/src/transformers/role.ts b/packages/bot/src/transformers/role.ts
index c85baed75..e42fdf462 100644
--- a/packages/bot/src/transformers/role.ts
+++ b/packages/bot/src/transformers/role.ts
@@ -1,5 +1,5 @@
-import type { BigString, DiscordRole } from '@discordeno/types'
-import { type InternalBot, type Role, iconHashToBigInt } from '../index.js'
+import type { BigString, DiscordRole, DiscordRoleColors } from '@discordeno/types'
+import { type InternalBot, type Role, type RoleColors, iconHashToBigInt } from '../index.js'
 import { Permissions } from './toggles/Permissions.js'
 import { RoleToggles } from './toggles/role.js'
 
@@ -69,3 +69,16 @@ export function transformRole(bot: InternalBot, payload: { role: DiscordRole; gu
 
   return bot.transformers.customizers.role(bot, payload.role, role)
 }
+
+export function transformRoleColors(bot: InternalBot, payload: DiscordRoleColors): RoleColors {
+  const roleColors = {} as RoleColors
+  const props = bot.transformers.desiredProperties.roleColors
+
+  if (props.primaryColor && payload.primary_color !== undefined) roleColors.primaryColor = payload.primary_color
+  if (props.secondaryColor && payload.secondary_color !== undefined && payload.secondary_color !== null)
+    roleColors.secondaryColor = payload.secondary_color
+  if (props.tertiaryColor && payload.tertiary_color !== undefined && payload.tertiary_color !== null)
+    roleColors.tertiaryColor = payload.tertiary_color
+
+  return bot.transformers.customizers.roleColors(bot, payload, roleColors)
+}
diff --git a/packages/bot/src/transformers/toggles/guild.ts b/packages/bot/src/transformers/toggles/guild.ts
index 8e3d5a14e..1f865791e 100644
--- a/packages/bot/src/transformers/toggles/guild.ts
+++ b/packages/bot/src/transformers/toggles/guild.ts
@@ -30,6 +30,7 @@ const featureNames = [
   'verified',
   'vipRegions',
   'welcomeScreenEnabled',
+  'enhancedRoleColors',
 ] as const
 
 export const GuildToggle = {
@@ -45,7 +46,7 @@ export const GuildToggle = {
   premiumProgressBarEnabled: 1n << 4n,
 
   // GUILD FEATURES ARE BELOW THIS
-  // MISSING VALUES IN THE BITFIELD: 26, 35+
+  // MISSING VALUES IN THE BITFIELD: 36+
 
   /** Whether the guild has access to set an animated guild banner image */
   animatedBanner: 1n << 11n,
@@ -105,6 +106,8 @@ export const GuildToggle = {
   vipRegions: 1n << 6n,
   /** Whether the guild has enabled the welcome screen */
   welcomeScreenEnabled: 1n << 18n,
+  /** Whether the guild is able to set gradient colors to roles */
+  enhancedRoleColors: 1n << 35n,
 }
 
 export class GuildToggles extends ToggleBitfieldBigint {
@@ -152,6 +155,7 @@ export class GuildToggles extends ToggleBitfieldBigint {
       if (guild.features.includes(GuildFeatures.Verified)) this.add(GuildToggle.verified)
       if (guild.features.includes(GuildFeatures.VipRegions)) this.add(GuildToggle.vipRegions)
       if (guild.features.includes(GuildFeatures.WelcomeScreenEnabled)) this.add(GuildToggle.welcomeScreenEnabled)
+      if (guild.features.includes(GuildFeatures.EnhancedRoleColors)) this.add(GuildToggle.enhancedRoleColors)
     }
   }
 
@@ -337,6 +341,11 @@ export class GuildToggles extends ToggleBitfieldBigint {
     return this.has('soundboard')
   }
 
+  /** Whether the guild is able to set gradient colors to roles */
+  get enhancedRoleColors(): boolean {
+    return this.has('enhancedRoleColors')
+  }
+
   /** Checks whether or not the permissions exist in this */
   has(permissions: GuildToggleKeys | GuildToggleKeys[]): boolean {
     if (!Array.isArray(permissions)) return super.contains(GuildToggle[permissions])
diff --git a/packages/bot/src/transformers/types.ts b/packages/bot/src/transformers/types.ts
index 7e2ebdda3..2e44d49c7 100644
--- a/packages/bot/src/transformers/types.ts
+++ b/packages/bot/src/transformers/types.ts
@@ -1502,8 +1502,13 @@ export interface Role {
   icon?: bigint
   /** Role name */
   name: string
-  /** Integer representation of hexadecimal color code */
+  /**
+   * Integer representation of hexadecimal color code
+   * @deprecated the {@link colors} field is recommended for use instead of this field
+   */
   color: number
+  /** The role's color */
+  colors: RoleColors
   /** Position of this role */
   position: number
   /** role unicode emoji */
@@ -1547,6 +1552,15 @@ export interface RoleTags {
   premiumSubscriber?: boolean
 }
 
+export interface RoleColors {
+  /** The primary color for the role */
+  primaryColor: number
+  /** The secondary color for the role, this will make the role a gradient between the other provided colors */
+  secondaryColor?: number
+  /** The tertiary color for the role, this will turn the gradient into a holographic style */
+  tertiaryColor?: number
+}
+
 export interface ScheduledEvent {
   /** the id of the scheduled event */
   id: bigint
diff --git a/packages/types/src/discord/guild.ts b/packages/types/src/discord/guild.ts
index 5cadd2168..d016c7488 100644
--- a/packages/types/src/discord/guild.ts
+++ b/packages/types/src/discord/guild.ts
@@ -202,16 +202,16 @@ export enum SystemChannelFlags {
 
 /** https://discord.com/developers/docs/resources/guild#guild-object-guild-features */
 export enum GuildFeatures {
-  /** Guild has access to set an invite splash background */
-  InviteSplash = 'INVITE_SPLASH',
-  /** Guild has access to set 384 kbps bitrate in voice (previously VIP voice servers) */
-  VipRegions = 'VIP_REGIONS',
-  /** Guild has access to set a vanity URL */
-  VanityUrl = 'VANITY_URL',
-  /** Guild is verified */
-  Verified = 'VERIFIED',
-  /** Guild is partnered */
-  Partnered = 'PARTNERED',
+  /** Guild has access to set an animated guild banner image */
+  AnimatedBanner = 'ANIMATED_BANNER',
+  /** Guild has access to set an animated guild icon */
+  AnimatedIcon = 'ANIMATED_ICON',
+  /** Guild is using the old permissions configuration behavior */
+  ApplicationCommandPermissionsV2 = 'APPLICATION_COMMAND_PERMISSIONS_V2',
+  /** Guild has set up auto moderation rules */
+  AutoModeration = 'AUTO_MODERATION',
+  /** Guild has access to set a guild banner image */
+  Banner = 'BANNER',
   /** Guild can enable welcome screen, Membership Screening, stage channels and discovery, and receives community updates */
   Community = 'COMMUNITY',
   /** Guild has enabled monetization. */
@@ -220,28 +220,28 @@ export enum GuildFeatures {
   CreatorStorePage = 'CREATOR_STORE_PAGE',
   /** Guild has been set as a support server on the App Directory */
   DeveloperSupportServer = 'DEVELOPER_SUPPORT_SERVER',
-  /** Guild has access to create news channels */
-  News = 'NEWS',
   /** Guild is able to be discovered in the directory */
   Discoverable = 'DISCOVERABLE',
   /** Guild is able to be featured in the directory */
   Featurable = 'FEATURABLE',
-  /** Guild has access to set an animated guild icon */
-  AnimatedIcon = 'ANIMATED_ICON',
-  /** Guild has access to set a guild banner image */
-  Banner = 'BANNER',
-  /** Guild has enabled the welcome screen */
-  WelcomeScreenEnabled = 'WELCOME_SCREEN_ENABLED',
+  /** Guild has paused invites, preventing new users from joining */
+  InvitesDisabled = 'INVITES_DISABLED',
+  /** Guild has access to set an invite splash background */
+  InviteSplash = 'INVITE_SPLASH',
   /** Guild has enabled [Membership Screening](https://discord.com/developers/docs/resources/guild#membership-screening-object) */
   MemberVerificationGateEnabled = 'MEMBER_VERIFICATION_GATE_ENABLED',
   /** Guild has increased custom soundboard sound slots. */
   MoreSoundboard = 'MORE_SOUNDBOARD',
-  /** Guild can be previewed before joining via Membership Screening or the directory */
-  PreviewEnabled = 'PREVIEW_ENABLED',
-  /** Guild has enabled ticketed events */
-  TicketedEventsEnabled = 'TICKETED_EVENTS_ENABLED',
   /** Guild has increased custom sticker slots */
   MoreStickers = 'MORE_STICKERS',
+  /** Guild has access to create news channels */
+  News = 'NEWS',
+  /** Guild is partnered */
+  Partnered = 'PARTNERED',
+  /** Guild can be previewed before joining via Membership Screening or the directory */
+  PreviewEnabled = 'PREVIEW_ENABLED',
+  /** Guild has disabled alerts for join raids in the configured safety alerts channel */
+  RaidAlertsDisabled = 'RAID_ALERTS_DISABLED',
   /** Guild is able to set role icons */
   RoleIcons = 'ROLE_ICONS',
   /** Guild has role subscriptions that can be purchased. */
@@ -250,16 +250,18 @@ export enum GuildFeatures {
   RoleSubscriptionsEnabled = 'ROLE_SUBSCRIPTIONS_ENABLED',
   /** Guild has created soundboard sounds. */
   Soundboard = 'SOUNDBOARD',
-  /** Guild has set up auto moderation rules */
-  AutoModeration = 'AUTO_MODERATION',
-  /** Guild has paused invites, preventing new users from joining */
-  InvitesDisabled = 'INVITES_DISABLED',
-  /** Guild has access to set an animated guild banner image */
-  AnimatedBanner = 'ANIMATED_BANNER',
-  /** Guild has disabled alerts for join raids in the configured safety alerts channel */
-  RaidAlertsDisabled = 'RAID_ALERTS_DISABLED',
-  /** Guild is using the old permissions configuration behavior */
-  ApplicationCommandPermissionsV2 = 'APPLICATION_COMMAND_PERMISSIONS_V2',
+  /** Guild has enabled ticketed events */
+  TicketedEventsEnabled = 'TICKETED_EVENTS_ENABLED',
+  /** Guild has access to set a vanity URL */
+  VanityUrl = 'VANITY_URL',
+  /** Guild is verified */
+  Verified = 'VERIFIED',
+  /** Guild has access to set 384 kbps bitrate in voice (previously VIP voice servers) */
+  VipRegions = 'VIP_REGIONS',
+  /** Guild has enabled the welcome screen */
+  WelcomeScreenEnabled = 'WELCOME_SCREEN_ENABLED',
+  /** Guild is able to set gradient colors to roles */
+  EnhancedRoleColors = 'ENHANCED_ROLE_COLORS',
 }
 
 /** https://discord.com/developers/docs/resources/guild#unavailable-guild-object */
diff --git a/packages/types/src/discord/permissions.ts b/packages/types/src/discord/permissions.ts
index c5f645ea6..908495fba 100644
--- a/packages/types/src/discord/permissions.ts
+++ b/packages/types/src/discord/permissions.ts
@@ -123,8 +123,13 @@ export interface DiscordRole {
   icon?: string
   /** Role name */
   name: string
-  /** Integer representation of hexadecimal color code */
+  /**
+   * RGB color value, default: 0
+   * @deprecated the {@link colors} field is recommended for use instead of this field
+   */
   color: number
+  /** The role's color */
+  colors: DiscordRoleColors
   /** Position of this role (roles with the same position are sorted by id) */
   position: number
   /** role unicode emoji */
@@ -149,6 +154,16 @@ export interface DiscordRoleTags {
   guild_connections?: null
 }
 
+/** https://discord.com/developers/docs/topics/permissions#role-object-role-colors-object */
+export interface DiscordRoleColors {
+  /** The primary color for the role */
+  primary_color: number
+  /** The secondary color for the role, this will make the role a gradient between the other provided colors */
+  secondary_color: number | null
+  /** The tertiary color for the role, this will turn the gradient into a holographic style */
+  tertiary_color: number | null
+}
+
 /** https://discord.com/developers/docs/topics/permissions#role-object-role-flags */
 export enum RoleFlags {
   None,
diff --git a/packages/types/src/discordeno.ts b/packages/types/src/discordeno.ts
index f7d49f751..365726f51 100644
--- a/packages/types/src/discordeno.ts
+++ b/packages/types/src/discordeno.ts
@@ -1426,13 +1426,19 @@ export interface CreateGuild {
   systemChannelFlags?: SystemChannelFlags
 }
 
+/** https://discord.com/developers/docs/resources/guild#create-guild-role-json-params */
 export interface CreateGuildRole {
   /** Name of the role, max 100 characters, default: "new role" */
   name?: string
   /** Bitwise value of the enabled/disabled permissions, default: everyone permissions in guild */
   permissions?: PermissionStrings[]
-  /** RGB color value, default: 0 */
+  /**
+   * RGB color value, default: 0
+   * @deprecated the {@link colors} field is recommended for use instead of this field
+   */
   color?: number
+  /** The role's color */
+  colors?: GuildRoleColors
   /** Whether the role should be displayed separately in the sidebar, default: false */
   hoist?: boolean
   /** Whether the role should be mentionable, default: false */
@@ -1443,13 +1449,28 @@ export interface CreateGuildRole {
   icon?: string
 }
 
+/** https://discord.com/developers/docs/topics/permissions#role-object-role-colors-object */
+export interface GuildRoleColors {
+  /** The primary color for the role */
+  primaryColor: number
+  /** The secondary color for the role, this will make the role a gradient between the other provided colors */
+  secondaryColor?: number
+  /** The tertiary color for the role, this will turn the gradient into a holographic style */
+  tertiaryColor?: number
+}
+
 export interface EditGuildRole {
   /** Name of the role, max 100 characters, default: "new role" */
   name?: string
   /** Bitwise value of the enabled/disabled permissions, default: everyone permissions in guild */
   permissions?: PermissionStrings[]
-  /** RGB color value, default: 0 */
+  /**
+   * RGB color value, default: 0
+   * @deprecated the {@link colors} field is recommended for use instead of this field
+   */
   color?: number
+  /** The role's color */
+  colors?: GuildRoleColors
   /** Whether the role should be displayed separately in the sidebar, default: false */
   hoist?: boolean
   /** Whether the role should be mentionable, default: false */