discord.js 14.21.0 → 14.22.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "discord.js",
-  "version": "14.21.0",
+  "version": "14.22.0",
   "description": "A powerful library for interacting with the Discord API",
   "main": "./src/index.js",
   "types": "./typings/index.d.ts",
@@ -58,13 +58,13 @@
     "@discordjs/formatters": "^0.6.1",
     "@discordjs/ws": "^1.2.3",
     "@sapphire/snowflake": "3.5.3",
-    "discord-api-types": "^0.38.1",
+    "discord-api-types": "^0.38.16",
     "fast-deep-equal": "3.1.3",
     "lodash.snakecase": "4.1.1",
     "magic-bytes.js": "^1.10.0",
     "tslib": "^2.6.3",
     "undici": "6.21.3",
-    "@discordjs/rest": "^2.5.1",
+    "@discordjs/rest": "^2.6.0",
     "@discordjs/util": "^1.1.1"
   },
   "devDependencies": {

package/src/client/Client.js

@@ -522,7 +522,7 @@ class Client extends BaseClient {
   }
 
   /**
-   * Calls {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval} on a script
+   * Calls {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/eval} on a script
    * with the client as `this`.
    * @param {string} script Script to eval
    * @returns {*}
@@ -604,7 +604,7 @@ module.exports = Client;
  */
 
 /**
- * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake},
+ * A {@link https://docs.x.com/resources/fundamentals/x-ids Twitter snowflake},
  * except the epoch is 2015-01-01T00:00:00.000Z.
  *
  * If we have a snowflake '266241948824764416' we can represent it as binary:
@@ -638,6 +638,11 @@ module.exports = Client;
  * @see {@link https://discord.js.org/docs/packages/rest/stable/ImageURLOptions:Interface}
  */
 
+/**
+ * @external EmojiURLOptions
+ * @see {@link https://discord.js.org/docs/packages/rest/stable/EmojiURLOptions:TypeAlias}
+ */
+
 /**
  * @external BaseImageURLOptions
  * @see {@link https://discord.js.org/docs/packages/rest/stable/BaseImageURLOptions:Interface}

package/src/client/websocket/WebSocketManager.js

@@ -19,6 +19,7 @@ const Status = require('../../util/Status');
 const WebSocketShardEvents = require('../../util/WebSocketShardEvents');
 
 let zlib;
+let deprecationEmitted = false;
 
 try {
   zlib = require('zlib-sync');
@@ -379,6 +380,22 @@ class WebSocketManager extends EventEmitter {
     /**
      * Emitted when the client becomes ready to start working.
      * @event Client#ready
+     * @deprecated Use {@link Client#event:clientReady} instead.
+     * @param {Client} client The client
+     */
+    if (this.client.emit('ready', this.client) && !deprecationEmitted) {
+      deprecationEmitted = true;
+
+      process.emitWarning(
+        // eslint-disable-next-line max-len
+        'The ready event has been renamed to clientReady to distinguish it from the gateway READY event and will only emit under that name in v15. Please use clientReady instead.',
+        'DeprecationWarning',
+      );
+    }
+
+    /**
+     * Emitted when the client becomes ready to start working.
+     * @event Client#clientReady
      * @param {Client} client The client
      */
     this.client.emit(Events.ClientReady, this.client);

package/src/index.js

@@ -126,6 +126,7 @@ exports.CommandInteractionOptionResolver = require('./structures/CommandInteract
 exports.Component = require('./structures/Component');
 exports.ContainerComponent = require('./structures/ContainerComponent');
 exports.ContextMenuCommandInteraction = require('./structures/ContextMenuCommandInteraction');
+exports.DirectoryChannel = require('./structures/DirectoryChannel');
 exports.DMChannel = require('./structures/DMChannel');
 exports.Embed = require('./structures/Embed');
 exports.EmbedBuilder = require('./structures/EmbedBuilder');

package/src/managers/GuildChannelManager.js

@@ -230,13 +230,13 @@ class GuildChannelManager extends CachedManager {
   async createWebhook({ channel, name, avatar, reason }) {
     const id = this.resolveId(channel);
     if (!id) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'channel', 'GuildChannelResolvable');
-    if (typeof avatar === 'string' && !avatar.startsWith('data:')) {
-      avatar = await resolveImage(avatar);
-    }
+
+    const resolvedImage = await resolveImage(avatar);
+
     const data = await this.client.rest.post(Routes.channelWebhooks(id), {
       body: {
         name,
-        avatar,
+        avatar: resolvedImage,
       },
       reason,
     });

package/src/managers/GuildMemberRoleManager.js

@@ -65,7 +65,7 @@ class GuildMemberRoleManager extends DataManager {
    * @readonly
    */
   get color() {
-    const coloredRoles = this.cache.filter(role => role.color);
+    const coloredRoles = this.cache.filter(role => role.colors.primaryColor);
     if (!coloredRoles.size) return null;
     return coloredRoles.reduce((prev, role) => (role.comparePositionTo(prev) > 0 ? role : prev));
   }

package/src/managers/MessageManager.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const process = require('node:process');
 const { Collection } = require('@discordjs/collection');
 const { makeURLSearchParams } = require('@discordjs/rest');
 const { Routes } = require('discord-api-types/v10');
@@ -10,6 +11,8 @@ const MessagePayload = require('../structures/MessagePayload');
 const { MakeCacheOverrideSymbol } = require('../util/Symbols');
 const { resolvePartialEmoji } = require('../util/Util');
 
+let deprecationEmittedForFetchPinned = false;
+
 /**
  * Manages API methods for Messages and holds their cache.
  * @extends {CachedManager}
@@ -116,19 +119,83 @@ class MessageManager extends CachedManager {
     return data.reduce((_data, message) => _data.set(message.id, this._add(message, options.cache)), new Collection());
   }
 
+  /**
+   * Options used to fetch pinned messages.
+   *
+   * @typedef {Object} FetchPinnedMessagesOptions
+   * @property {DateResolvable} [before] Consider only pinned messages before this time
+   * @property {number} [limit] The maximum number of pinned messages to return
+   * @property {boolean} [cache] Whether to cache the pinned messages
+   */
+
+  /**
+   * Data returned from fetching pinned messages.
+   *
+   * @typedef {Object} FetchPinnedMessagesResponse
+   * @property {MessagePin[]} items The pinned messages
+   * @property {boolean} hasMore Whether there are additional pinned messages that require a subsequent call
+   */
+
+  /**
+   * Pinned message data returned from fetching pinned messages.
+   *
+   * @typedef {Object} MessagePin
+   * @property {Date} pinnedAt The time the message was pinned at
+   * @property {number} pinnedTimestamp The timestamp the message was pinned at
+   * @property {Message} message The pinned message
+   */
+
   /**
    * Fetches the pinned messages of this channel and returns a collection of them.
    * <info>The returned Collection does not contain any reaction data of the messages.
    * Those need to be fetched separately.</info>
-   * @param {boolean} [cache=true] Whether to cache the message(s)
-   * @returns {Promise<Collection<Snowflake, Message>>}
+   *
+   * @param {FetchPinnedMessagesOptions} [options={}] Options for fetching pinned messages
+   * @returns {Promise<FetchPinnedMessagesResponse>}
    * @example
    * // Get pinned messages
-   * channel.messages.fetchPinned()
-   *   .then(messages => console.log(`Received ${messages.size} messages`))
+   * channel.messages.fetchPins()
+   *   .then(messages => console.log(`Received ${messages.items.length} messages`))
    *   .catch(console.error);
    */
+  async fetchPins(options = {}) {
+    const data = await this.client.rest.get(Routes.channelMessagesPins(this.channel.id), {
+      query: makeURLSearchParams({
+        ...options,
+        before: options.before && new Date(options.before).toISOString(),
+      }),
+    });
+
+    return {
+      items: data.items.map(item => ({
+        pinnedTimestamp: Date.parse(item.pinned_at),
+        get pinnedAt() {
+          return new Date(this.pinnedTimestamp);
+        },
+        message: this._add(item.message, options.cache),
+      })),
+      hasMore: data.has_more,
+    };
+  }
+
+  /**
+   * Fetches the pinned messages of this channel and returns a collection of them.
+   * <info>The returned Collection does not contain any reaction data of the messages.
+   * Those need to be fetched separately.</info>
+   * @param {boolean} [cache=true] Whether to cache the message(s)
+   * @deprecated Use {@link MessageManager#fetchPins} instead.
+   * @returns {Promise<Collection<Snowflake, Message>>}
+   */
   async fetchPinned(cache = true) {
+    if (!deprecationEmittedForFetchPinned) {
+      process.emitWarning(
+        'The MessageManager#fetchPinned() method is deprecated. Use MessageManager#fetchPins() instead.',
+        'DeprecationWarning',
+      );
+
+      deprecationEmittedForFetchPinned = true;
+    }
+
     const data = await this.client.rest.get(Routes.channelPins(this.channel.id));
     const messages = new Collection();
     for (const message of data) messages.set(message.id, this._add(message, cache));
@@ -219,7 +286,7 @@ class MessageManager extends CachedManager {
     message = this.resolveId(message);
     if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
 
-    await this.client.rest.put(Routes.channelPin(this.channel.id, message), { reason });
+    await this.client.rest.put(Routes.channelMessagesPin(this.channel.id, message), { reason });
   }
 
   /**
@@ -232,7 +299,7 @@ class MessageManager extends CachedManager {
     message = this.resolveId(message);
     if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
 
-    await this.client.rest.delete(Routes.channelPin(this.channel.id, message), { reason });
+    await this.client.rest.delete(Routes.channelMessagesPin(this.channel.id, message), { reason });
   }
 
   /**

package/src/managers/RoleManager.js

@@ -12,6 +12,8 @@ const PermissionsBitField = require('../util/PermissionsBitField');
 const { setPosition, resolveColor } = require('../util/Util');
 
 let cacheWarningEmitted = false;
+let deprecationEmittedForCreate = false;
+let deprecationEmittedForEdit = false;
 
 /**
  * Manages API methods for roles and stores their cache.
@@ -58,7 +60,7 @@ class RoleManager extends CachedManager {
    * @example
    * // Fetch a single role
    * message.guild.roles.fetch('222078108977594368')
-   *   .then(role => console.log(`The role color is: ${role.color}`))
+   *   .then(role => console.log(`The role color is: ${role.colors.primaryColor}`))
    *   .catch(console.error);
    */
   async fetch(id, { cache = true, force = false } = {}) {
@@ -112,11 +114,24 @@ class RoleManager extends CachedManager {
    * @returns {?Snowflake}
    */
 
+  /**
+   * @typedef {Object} RoleColorsResolvable
+   * @property {ColorResolvable} primaryColor The primary color of the role
+   * @property {ColorResolvable} [secondaryColor] The secondary color of the role.
+   * This will make the role a gradient between the other provided colors
+   * @property {ColorResolvable} [tertiaryColor] The tertiary color of the role.
+   * When sending `tertiaryColor` the API enforces the role color to be a holographic style
+   * with values of `primaryColor = 11127295`, `secondaryColor = 16759788`, and `tertiaryColor = 16761760`.
+   * These values are available as a constant: `Constants.HolographicStyle`
+   */
+
   /**
    * Options used to create a new role.
    * @typedef {Object} RoleCreateOptions
    * @property {string} [name] The name of the new role
    * @property {ColorResolvable} [color] The data to create the role with
+   * <warn>This property is deprecated. Use `colors` instead.</warn>
+   * @property {RoleColorsResolvable} [colors] The colors to create the role with
    * @property {boolean} [hoist] Whether or not the new role should be hoisted
    * @property {PermissionResolvable} [permissions] The permissions for the new role
    * @property {number} [position] The position of the new role
@@ -142,15 +157,30 @@ class RoleManager extends CachedManager {
    * // Create a new role with data and a reason
    * guild.roles.create({
    *   name: 'Super Cool Blue People',
-   *   color: Colors.Blue,
    *   reason: 'we needed a role for Super Cool People',
+   *   colors: {
+   *     primaryColor: Colors.Blue,
+   *   },
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Create a role with holographic colors
+   * guild.roles.create({
+   *   name: 'Holographic Role',
+   *   reason: 'Creating a role with holographic effect',
+   *   colors: {
+   *     primaryColor: Constants.HolographicStyle.Primary,
+   *     secondaryColor: Constants.HolographicStyle.Secondary,
+   *     tertiaryColor: Constants.HolographicStyle.Tertiary,
+   *   },
    * })
    *   .then(console.log)
    *   .catch(console.error);
    */
   async create(options = {}) {
-    let { name, color, hoist, permissions, position, mentionable, reason, icon, unicodeEmoji } = options;
-    color &&= resolveColor(color);
+    let { permissions, icon } = options;
+    const { name, color, hoist, position, mentionable, reason, unicodeEmoji } = options;
     if (permissions !== undefined) permissions = new PermissionsBitField(permissions);
     if (icon) {
       const guildEmojiURL = this.guild.emojis.resolve(icon)?.imageURL();
@@ -158,10 +188,30 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
+    let colors = options.colors && {
+      primary_color: resolveColor(options.colors.primaryColor),
+      secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
+      tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
+    };
+
+    if (color !== undefined) {
+      if (!deprecationEmittedForCreate) {
+        process.emitWarning(`Passing "color" to RoleManager#create() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForCreate = true;
+
+      colors = {
+        primary_color: resolveColor(color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
     const data = await this.client.rest.post(Routes.guildRoles(this.guild.id), {
       body: {
         name,
-        color,
+        colors,
         hoist,
         permissions,
         mentionable,
@@ -210,9 +260,29 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
+    let colors = options.colors && {
+      primary_color: resolveColor(options.colors.primaryColor),
+      secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
+      tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
+    };
+
+    if (options.color !== undefined) {
+      if (!deprecationEmittedForEdit) {
+        process.emitWarning(`Passing "color" to RoleManager#edit() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForEdit = true;
+
+      colors = {
+        primary_color: resolveColor(options.color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
     const body = {
       name: options.name,
-      color: options.color === undefined ? undefined : resolveColor(options.color),
+      colors,
       hoist: options.hoist,
       permissions: options.permissions === undefined ? undefined : new PermissionsBitField(options.permissions),
       mentionable: options.mentionable,

package/src/structures/ApplicationCommand.js

@@ -312,7 +312,7 @@ class ApplicationCommand extends Base {
    * @returns {Promise<ApplicationCommand>}
    * @example
    * // Edit the name localizations of this command
-   * command.setLocalizedNames({
+   * command.setNameLocalizations({
    *   'en-GB': 'test',
    *   'pt-BR': 'teste',
    * })

package/src/structures/ApplicationEmoji.js

@@ -16,37 +16,42 @@ class ApplicationEmoji extends Emoji {
      */
     this.application = application;
 
-    /**
-     * The user who created this emoji
-     * @type {?User}
-     */
-    this.author = null;
-
-    this.managed = null;
-    this.requiresColons = null;
-
     this._patch(data);
   }
 
   _patch(data) {
     if ('name' in data) this.name = data.name;
-    if (data.user) this.author = this.client.users._add(data.user);
+    if (data.user) {
+      /**
+       * The user who created this emoji
+       * @type {User}
+       */
+      this.author = this.client.users._add(data.user);
+    }
 
     if ('managed' in data) {
       /**
-       * Whether this emoji is managed by an external service
-       * @type {?boolean}
+       * Whether this emoji is managed by an external service. Always `false` for application emojis
+       * @type {false}
        */
       this.managed = data.managed;
     }
 
     if ('require_colons' in data) {
       /**
-       * Whether or not this emoji requires colons surrounding it
-       * @type {?boolean}
+       * Whether this emoji requires colons surrounding it. Always `true` for application emojis
+       * @type {true}
        */
       this.requiresColons = data.require_colons;
     }
+
+    if ('available' in data) {
+      /**
+       * Whether this emoji is available. Always `true` for application emojis
+       * @type {true}
+       */
+      this.available = data.available;
+    }
   }
 
   /**
@@ -107,7 +112,8 @@ class ApplicationEmoji extends Emoji {
         other.id === this.id &&
         other.name === this.name &&
         other.managed === this.managed &&
-        other.requiresColons === this.requiresColons
+        other.requiresColons === this.requiresColons &&
+        other.available === this.available
       );
     }
 
@@ -115,4 +121,49 @@ class ApplicationEmoji extends Emoji {
   }
 }
 
+/**
+ * The emoji's name
+ * @name name
+ * @memberof ApplicationEmoji
+ * @instance
+ * @type {string}
+ * @readonly
+ */
+
+/**
+ * Whether the emoji is animated
+ * @name animated
+ * @memberof ApplicationEmoji
+ * @instance
+ * @type {boolean}
+ * @readonly
+ */
+
+/**
+ * Returns a URL for the emoji.
+ * @method imageURL
+ * @memberof ApplicationEmoji
+ * @instance
+ * @param {EmojiURLOptions} [options] Options for the image URL
+ * @returns {string}
+ */
+
+/**
+ * The time the emoji was created at
+ * @name createdAt
+ * @memberof ApplicationEmoji
+ * @instance
+ * @type {Date}
+ * @readonly
+ */
+
+/**
+ * The timestamp the emoji was created at
+ * @name createdTimestamp
+ * @memberof ApplicationEmoji
+ * @instance
+ * @type {number}
+ * @readonly
+ */
+
 module.exports = ApplicationEmoji;

package/src/structures/BaseGuildEmoji.js

@@ -58,7 +58,7 @@ class BaseGuildEmoji extends Emoji {
  * @method imageURL
  * @memberof BaseGuildEmoji
  * @instance
- * @param {BaseImageURLOptions} [options] Options for the image URL
+ * @param {EmojiURLOptions} [options] Options for the emoji URL
  * @returns {string}
  */
 
@@ -72,4 +72,40 @@ class BaseGuildEmoji extends Emoji {
  * @deprecated Use {@link BaseGuildEmoji#imageURL} instead.
  */
 
+/**
+ * The emoji's name
+ * @name name
+ * @memberof BaseGuildEmoji
+ * @instance
+ * @type {string}
+ * @readonly
+ */
+
+/**
+ * Whether or not the emoji is animated
+ * @name animated
+ * @memberof BaseGuildEmoji
+ * @instance
+ * @type {boolean}
+ * @readonly
+ */
+
+/**
+ * The time the emoji was created at.
+ * @name createdAt
+ * @memberof BaseGuildEmoji
+ * @instance
+ * @type {Date}
+ * @readonly
+ */
+
+/**
+ * The timestamp the emoji was created at.
+ * @name createdTimestamp
+ * @memberof BaseGuildEmoji
+ * @instance
+ * @type {number}
+ * @readonly
+ */
+
 module.exports = BaseGuildEmoji;

package/src/structures/Emoji.js

@@ -45,7 +45,7 @@ class Emoji extends Base {
 
   /**
    * Returns a URL for the emoji or `null` if this is not a custom emoji.
-   * @param {BaseImageURLOptions} [options] Options for the image URL
+   * @param {EmojiURLOptions} [options] Options for the emoji URL
    * @returns {?string}
    */
   imageURL(options) {

package/src/structures/GuildMember.js

@@ -270,7 +270,7 @@ class GuildMember extends Base {
    * @readonly
    */
   get displayColor() {
-    return this.roles.color?.color ?? 0;
+    return this.roles.color?.colors.primaryColor ?? 0;
   }
 
   /**

package/src/structures/Message.js

@@ -812,6 +812,7 @@ class Message extends Base {
     return Boolean(
       channel?.type === ChannelType.GuildAnnouncement &&
         !this.flags.has(MessageFlags.Crossposted) &&
+        this.reference?.type !== MessageReferenceType.Forward &&
         this.type === MessageType.Default &&
         !this.poll &&
         channel.viewable &&