feat: support user guilds

packages/discord.js/src/structures/User.js

@@ -138,18 +138,42 @@ class User extends Base {
      * @property {Snowflake} skuId The id of the avatar decoration's SKU
      */
 
-    if (data.avatar_decoration_data) {
+    if ('avatar_decoration_data' in data) {
       /**
        * The user avatar decoration's data
        *
        * @type {?AvatarDecorationData}
        */
       this.avatarDecorationData = {
-        asset: data.avatar_decoration_data.asset,
-        skuId: data.avatar_decoration_data.sku_id,
+        asset: data.avatar_decoration_data?.asset,
+        skuId: data.avatar_decoration_data?.sku_id,
       };
     } else {
-      this.avatarDecorationData = null;
+      this.avatarDecorationData ??= null;
+    }
+
+    /**
+     * @typedef {Object} UserPrimaryGuild
+     * @property {?Snowflake} identityGuildId - The id of the user's primary guild
+     * @property {?boolean} identityEnabled - Whether the user is displaying the primary guild's tag
+     * @property {?string} tag - The user's guild tag. Limited to 4 characters
+     * @property {?string} badge - The guild tag badge hash
+     */
+
+    if ('primary_guild' in data) {
+      /**
+       * The primary guild of the user
+       *
+       * @type {?UserPrimaryGuild}
+       */
+      this.primaryGuild = {
+        identityGuildId: data.primary_guild?.identity_guild_id,
+        identityEnabled: data.primary_guild?.identity_enabled,
+        tag: data.primary_guild?.tag,
+        badge: data.primary_guild?.badge,
+      };
+    } else {
+      this.primaryGuild ??= null;
     }
   }
 
@@ -246,6 +270,18 @@ class User extends Base {
     return this.banner && this.client.rest.cdn.banner(this.id, this.banner, options);
   }
 
+  /**
+   * A link to the user's guild tag badge.
+   *
+   * @param {ImageURLOptions} [options={}] Options for the image URL
+   * @returns {?string}
+   */
+  guildTagBadgeURL(options = {}) {
+    return this.primaryGuild?.badge
+      ? this.client.rest.cdn.guildTagBadge(this.primaryGuild.identityGuildId, this.primaryGuild.badge, options)
+      : null;
+  }
+
   /**
    * The tag of this user
    * <info>This user's username, or their legacy tag (e.g. `hydrabolt#0001`)
@@ -338,7 +374,11 @@ class User extends Base {
       this.banner === user.banner &&
       this.accentColor === user.accentColor &&
       this.avatarDecorationData?.asset === user.avatarDecorationData?.asset &&
-      this.avatarDecorationData?.skuId === user.avatarDecorationData?.skuId
+      this.avatarDecorationData?.skuId === user.avatarDecorationData?.skuId &&
+      this.primaryGuild?.identityGuildId === user.primaryGuild?.identityGuildId &&
+      this.primaryGuild?.identityEnabled === user.primaryGuild?.identityEnabled &&
+      this.primaryGuild?.tag === user.primaryGuild?.tag &&
+      this.primaryGuild?.badge === user.primaryGuild?.badge
     );
   }
 
@@ -363,6 +403,12 @@ class User extends Base {
       ('avatar_decoration_data' in user
         ? this.avatarDecorationData?.asset === user.avatar_decoration_data?.asset &&
           this.avatarDecorationData?.skuId === user.avatar_decoration_data?.sku_id
+        : true) &&
+      ('primary_guild' in user
+        ? this.primaryGuild?.identityGuildId === user.primary_guild?.identity_guild_id &&
+          this.primaryGuild?.identityEnabled === user.primary_guild?.identity_enabled &&
+          this.primaryGuild?.tag === user.primary_guild?.tag &&
+          this.primaryGuild?.badge === user.primary_guild?.badge
         : true)
     );
   }
@@ -402,6 +448,7 @@ class User extends Base {
     json.avatarURL = this.avatarURL();
     json.displayAvatarURL = this.displayAvatarURL();
     json.bannerURL = this.banner ? this.bannerURL() : this.banner;
+    json.guildTagBadgeURL = this.guildTagBadgeURL();
     return json;
   }
 }

packages/discord.js/typings/index.d.ts

@@ -31,10 +31,7 @@ import {
   APIComponentInModalActionRow,
   APIContainerComponent,
   APIEmbed,
-  APIEmbedAuthor,
   APIEmbedField,
-  APIEmbedFooter,
-  APIEmbedImage,
   APIEmbedProvider,
   APIEmoji,
   APIEntitlement,
@@ -3497,6 +3494,13 @@ export interface AvatarDecorationData {
   skuId: Snowflake;
 }
 
+export interface UserPrimaryGuild {
+  badge: string | null;
+  identityEnabled: boolean | null;
+  identityGuildId: Snowflake | null;
+  tag: string | null;
+}
+
 export interface UnfurledMediaItemData {
   url: string;
 }
@@ -3528,12 +3532,14 @@ export class User extends Base {
   public get hexAccentColor(): HexColorString | null | undefined;
   public id: Snowflake;
   public get partial(): false;
+  public primaryGuild: UserPrimaryGuild | null;
   public system: boolean;
   public get tag(): string;
   public username: string;
   public avatarURL(options?: ImageURLOptions): string | null;
   public avatarDecorationURL(): string | null;
   public bannerURL(options?: ImageURLOptions): string | null | undefined;
+  public guildTagBadgeURL(options?: ImageURLOptions): string | null;
   public createDM(force?: boolean): Promise<DMChannel>;
   public deleteDM(): Promise<DMChannel>;
   public displayAvatarURL(options?: ImageURLOptions): string;

packages/rest/__tests__/CDN.test.ts

@@ -134,8 +134,11 @@ test('soundboardSound', () => {
 	expect(cdn.soundboardSound(id)).toEqual(`${baseCDN}/soundboard-sounds/${id}`);
 });
 
+test('guildTagBadge', () => {
+	expect(cdn.guildTagBadge(id, hash)).toEqual(`${baseCDN}/guild-tag-badges/${id}/${hash}.webp`);
+});
+
 test('makeURL throws on invalid size', () => {
-	// @ts-expect-error: Invalid size
 	expect(() => cdn.avatar(id, animatedHash, { size: 5 })).toThrow(RangeError);
 });
 

packages/rest/src/lib/CDN.ts

@@ -318,6 +318,17 @@ export class CDN {
 		return `${this.cdn}${CDNRoutes.soundboardSound(soundId)}`;
 	}
 
+	/**
+	 * Generates a URL for a guild tag badge.
+	 *
+	 * @param guildId - The guild id
+	 * @param badgeHash - The hash of the badge
+	 * @param options - Optional options for the badge
+	 */
+	public guildTagBadge(guildId: string, badgeHash: string, options?: Readonly<BaseImageURLOptions>): string {
+		return this.makeURL(`/guild-tag-badges/${guildId}/${badgeHash}`, options);
+	}
+
 	/**
 	 * Constructs the URL for the resource, checking whether or not `hash` starts with `a_` if `dynamic` is set to `true`.
 	 *