Merge branch 'main' into feat/url-formatter

package.json

@@ -41,8 +41,8 @@
 		"@commitlint/config-angular": "^17.0.3",
 		"@favware/cliff-jumper": "^1.8.5",
 		"@favware/npm-deprecate": "^1.0.4",
-		"@typescript-eslint/eslint-plugin": "^5.30.7",
-		"@typescript-eslint/parser": "^5.30.7",
+		"@typescript-eslint/eslint-plugin": "^5.31.0",
+		"@typescript-eslint/parser": "^5.31.0",
 		"conventional-changelog-cli": "^2.2.2",
 		"eslint": "^8.20.0",
 		"eslint-config-marine": "^9.4.1",

packages/actions/package.json

@@ -54,10 +54,10 @@
 		"eslint": "^8.20.0",
 		"prettier": "^2.7.1",
 		"rollup-plugin-typescript2": "0.32.1",
-		"tsup": "^6.1.3",
+		"tsup": "^6.2.0",
 		"typescript": "^4.7.4",
 		"unbuild": "^0.7.6",
-		"vitest": "^0.18.1"
+		"vitest": "^0.19.1"
 	},
 	"engines": {
 		"node": ">=16.9.0"

packages/builders/__tests__/messages/formatters.test.ts

@@ -26,11 +26,11 @@ import {
 describe('Message formatters', () => {
 	describe('codeBlock', () => {
 		test('GIVEN "discord.js" with no language THEN returns "```\\ndiscord.js```"', () => {
-			expect<'```\ndiscord.js```'>(codeBlock('discord.js')).toEqual('```\ndiscord.js```');
+			expect<'```\ndiscord.js\n```'>(codeBlock('discord.js')).toEqual('```\ndiscord.js\n```');
 		});
 
 		test('GIVEN "discord.js" with "js" as language THEN returns "```js\\ndiscord.js```"', () => {
-			expect<'```js\ndiscord.js```'>(codeBlock('js', 'discord.js')).toEqual('```js\ndiscord.js```');
+			expect<'```js\ndiscord.js\n```'>(codeBlock('js', 'discord.js')).toEqual('```js\ndiscord.js\n```');
 		});
 	});
 

packages/builders/package.json

@@ -70,10 +70,10 @@
 		"eslint": "^8.20.0",
 		"prettier": "^2.7.1",
 		"rollup-plugin-typescript2": "0.32.1",
-		"tsup": "^6.1.3",
+		"tsup": "^6.2.0",
 		"typescript": "^4.7.4",
 		"unbuild": "^0.7.6",
-		"vitest": "^0.18.1"
+		"vitest": "^0.19.1"
 	},
 	"engines": {
 		"node": ">=16.9.0"

packages/builders/src/messages/formatters.ts

@@ -6,17 +6,17 @@ import type { Snowflake } from 'discord-api-types/globals';
  *
  * @param content - The content to wrap
  */
-export function codeBlock<C extends string>(content: C): `\`\`\`\n${C}\`\`\``;
+export function codeBlock<C extends string>(content: C): `\`\`\`\n${C}\n\`\`\``;
 
 /**
  * Wraps the content inside a codeblock with the specified language
  *
  * @param language - The language for the codeblock
  * @param content - The content to wrap
  */
-export function codeBlock<L extends string, C extends string>(language: L, content: C): `\`\`\`${L}\n${C}\`\`\``;
+export function codeBlock<L extends string, C extends string>(language: L, content: C): `\`\`\`${L}\n${C}\n\`\`\``;
 export function codeBlock(language: string, content?: string): string {
-	return typeof content === 'undefined' ? `\`\`\`\n${language}\`\`\`` : `\`\`\`${language}\n${content}\`\`\``;
+	return typeof content === 'undefined' ? `\`\`\`\n${language}\n\`\`\`` : `\`\`\`${language}\n${content}\n\`\`\``;
 }
 
 /**

packages/collection/package.json

@@ -59,10 +59,10 @@
 		"eslint": "^8.20.0",
 		"prettier": "^2.7.1",
 		"rollup-plugin-typescript2": "0.32.1",
-		"tsup": "^6.1.3",
+		"tsup": "^6.2.0",
 		"typescript": "^4.7.4",
 		"unbuild": "^0.7.6",
-		"vitest": "^0.18.1"
+		"vitest": "^0.19.1"
 	},
 	"engines": {
 		"node": ">=16.9.0"

packages/discord.js/src/client/WebhookClient.js

@@ -12,11 +12,21 @@ const { parseWebhookURL } = require('../util/Util');
  */
 class WebhookClient extends BaseClient {
   /**
-   * The data for the webhook client containing either an id and token or just a URL
-   * @typedef {Object} WebhookClientData
-   * @property {Snowflake} [id] The id of the webhook
-   * @property {string} [token] The token of the webhook
-   * @property {string} [url] The full URL for the webhook client
+   * Represents the credentials used for a webhook in the form of its id and token.
+   * @typedef {Object} WebhookClientDataIdWithToken
+   * @property {Snowflake} id The webhook's id
+   * @property {string} token The webhook's token
+   */
+
+  /**
+   * Represents the credentials used for a webhook in the form of a URL.
+   * @typedef {Object} WebhookClientDataURL
+   * @property {string} url The full URL for the webhook
+   */
+
+  /**
+   * Represents the credentials used for a webhook.
+   * @typedef {WebhookClientDataIdWithToken|WebhookClientDataURL} WebhookClientData
    */
 
   /**

packages/discord.js/src/client/actions/InviteCreate.js

@@ -15,8 +15,8 @@ class InviteCreateAction extends Action {
 
     /**
      * Emitted when an invite is created.
-     * <info> This event only triggers if the client has {@link PermissionFlagsBits.ManageGuild} permissions
-     * for the guild, or {@link PermissionFlagsBits.ManageChannels} permissions for the channel.</info>
+     * <info>This event requires either the {@link PermissionFlagsBits.ManageGuild} permission or the
+     * {@link PermissionFlagsBits.ManageChannels} permission for the channel.</info>
      * @event Client#inviteCreate
      * @param {Invite} invite The invite that was created
      */

packages/discord.js/src/client/actions/InviteDelete.js

@@ -17,8 +17,8 @@ class InviteDeleteAction extends Action {
 
     /**
      * Emitted when an invite is deleted.
-     * <info> This event only triggers if the client has {@link PermissionFlagsBits.ManageGuild} permissions
-     * for the guild, or `{@link PermissionFlagsBits.ManageChannels}` permissions for the channel.</info>
+     * <info>This event requires either the {@link PermissionFlagsBits.ManageGuild} permission or the
+     * {@link PermissionFlagsBits.ManageChannels} permission for the channel.</info>
      * @event Client#inviteDelete
      * @param {Invite} invite The invite that was deleted
      */

packages/discord.js/src/client/actions/ThreadMembersUpdate.js

@@ -31,8 +31,8 @@ class ThreadMembersUpdateAction extends Action {
       }
 
       /**
-       * Emitted whenever members are added or removed from a thread. Requires
-       * {@link GatewayIntentBits.GuildMembers} privileged intent
+       * Emitted whenever members are added or removed from a thread.
+       * <info>This event requires the {@link GatewayIntentBits.GuildMembers} privileged gateway intent.</info>
        * @event Client#threadMembersUpdate
        * @param {Collection<Snowflake, ThreadMember>} addedMembers The members that were added
        * @param {Collection<Snowflake, ThreadMember>} removedMembers The members that were removed

packages/discord.js/src/managers/GuildMemberManager.js

@@ -74,20 +74,23 @@ class GuildMemberManager extends CachedManager {
   /**
    * Options used to add a user to a guild using OAuth2.
    * @typedef {Object} AddGuildMemberOptions
-   * @property {string} accessToken An OAuth2 access token for the user with the `guilds.join` scope granted to the
-   * bot's application
-   * @property {string} [nick] The nickname to give to the member (requires {@link PermissionFlagsBits.ManageNicknames})
+   * @property {string} accessToken An OAuth2 access token for the user with the {@link OAuth2Scopes.GuildsJoin}
+   * scope granted to the bot's application
+   * @property {string} [nick] The nickname to give to the member
+   * <info>This property requires the {@link PermissionFlagsBits.ManageNicknames} permission.</info>
    * @property {Collection<Snowflake, Role>|RoleResolvable[]} [roles] The roles to add to the member
-   * (requires {@link PermissionFlagsBits.ManageRoles})
-   * @property {boolean} [mute] Whether the member should be muted (requires {@link PermissionFlagsBits.MuteMembers})
+   * <info>This property requires the {@link PermissionFlagsBits.ManageRoles} permission.</info>
+   * @property {boolean} [mute] Whether the member should be muted
+   * <info>This property requires the {@link PermissionFlagsBits.MuteMembers} permission.</info>
    * @property {boolean} [deaf] Whether the member should be deafened
-   * (requires {@link PermissionFlagsBits.DeafenMembers})
-   * @property {boolean} [force] Whether to skip the cache check and call the API directly
+   * <info>This property requires the {@link PermissionFlagsBits.MuteMembers} permission.</info>
+   * @property {boolean} [force] Whether to skip the cache check and request the API directly
    * @property {boolean} [fetchWhenExisting=true] Whether to fetch the user if not cached and already a member
    */
 
   /**
-   * Adds a user to the guild using OAuth2. Requires the {@link PermissionFlagsBits.CreateInstantInvite} permission.
+   * Adds a user to the guild using OAuth2.
+   * <info>This method requires the {@link PermissionFlagsBits.CreateInstantInvite} permission.
    * @param {UserResolvable} user The user to add to the guild
    * @param {AddGuildMemberOptions} options Options for adding the user to the guild
    * @returns {Promise<GuildMember|null>}

packages/discord.js/src/managers/PermissionOverwriteManager.js

@@ -72,11 +72,11 @@ class PermissionOverwriteManager extends CachedManager {
   }
 
   /**
-   * Extra information about the overwrite
+   * Extra information about the overwrite.
    * @typedef {Object} GuildChannelOverwriteOptions
-   * @property {string} [reason] Reason for creating/editing this overwrite
-   * @property {number} [type] The type of overwrite, either `0` for a role or `1` for a member. Use this to bypass
-   * automatic resolution of type that results in an error for uncached structure
+   * @property {string} [reason] The reason for creating/editing this overwrite
+   * @property {OverwriteType} [type] The type of overwrite. Use this to bypass automatic resolution of `type`
+   * that results in an error for an uncached structure
    */
 
   /**

packages/discord.js/src/managers/ThreadManager.js

@@ -177,11 +177,12 @@ class ThreadManager extends CachedManager {
   /**
    * The options used to fetch archived threads.
    * @typedef {Object} FetchArchivedThreadOptions
-   * @property {string} [type='public'] The type of threads to fetch, either `public` or `private`
-   * @property {boolean} [fetchAll=false] Whether to fetch **all** archived threads when type is `private`.
-   * Requires {@link PermissionFlagsBits.ManageThreads} if true
+   * @property {string} [type='public'] The type of threads to fetch (`public` or `private`)
+   * @property {boolean} [fetchAll=false] Whether to fetch **all** archived threads when `type` is `private`
+   * <info>This property requires the {@link PermissionFlagsBits.ManageThreads} permission if `true`.</info>
    * @property {DateResolvable|ThreadChannelResolvable} [before] Only return threads that were created before this Date
-   * or Snowflake. <warn>Must be a {@link ThreadChannelResolvable} when type is `private` and fetchAll is `false`</warn>
+   * or Snowflake
+   * <warn>Must be a {@link ThreadChannelResolvable} when `type` is `private` and `fetchAll` is `false`.</warn>
    * @property {number} [limit] Maximum number of threads to return
    */
 
@@ -193,8 +194,9 @@ class ThreadManager extends CachedManager {
    */
 
   /**
-   * Obtains a set of archived threads from Discord, requires {@link PermissionFlagsBits.ReadMessageHistory}
-   * in the parent channel.
+   * Obtains a set of archived threads from Discord.
+   * <info>This method requires the {@link PermissionFlagsBits.ReadMessageHistory} permission
+   * in the parent channel.</info>
    * @param {FetchArchivedThreadOptions} [options] The options to fetch archived threads
    * @param {boolean} [cache=true] Whether to cache the new thread objects if they aren't already
    * @returns {Promise<FetchedThreads>}
@@ -232,8 +234,9 @@ class ThreadManager extends CachedManager {
   }
 
   /**
-   * Obtains the accessible active threads from Discord, requires {@link PermissionFlagsBits.ReadMessageHistory}
-   * in the parent channel.
+   * Obtains the accessible active threads from Discord.
+   * <info>This method requires the {@link PermissionFlagsBits.ReadMessageHistory} permission
+   * in the parent channel.</info>
    * @param {boolean} [cache=true] Whether to cache the new thread objects if they aren't already
    * @returns {Promise<FetchedThreads>}
    */

packages/discord.js/src/managers/ThreadMemberManager.js

@@ -122,7 +122,8 @@ class ThreadMemberManager extends CachedManager {
    */
 
   /**
-   * Fetches thread member(s) from Discord. Requires the {@link GatewayIntentBits.GuildMembers} gateway intent.
+   * Fetches thread member(s) from Discord.
+   * <info>This method requires the {@link GatewayIntentBits.GuildMembers} privileged gateway intent.</info>
    * @param {ThreadMemberResolvable|FetchThreadMemberOptions|FetchThreadMembersOptions} [options]
    * Options for fetching thread member(s)
    * @returns {Promise<ThreadMember|Collection<Snowflake, ThreadMember>>}

packages/discord.js/src/structures/GuildChannel.js

@@ -151,7 +151,7 @@ class GuildChannel extends BaseChannel {
   /**
    * Gets the overall set of permissions for a member or role in this channel, taking into account channel overwrites.
    * @param {GuildMemberResolvable|RoleResolvable} memberOrRole The member or role to obtain the overall permissions for
-   * @param {boolean} [checkAdmin=true] Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} [checkAdmin=true] Whether having the {@link PermissionFlagsBits.Administrator} permission
    * will return all permissions
    * @returns {?Readonly<PermissionsBitField>}
    */
@@ -191,7 +191,7 @@ class GuildChannel extends BaseChannel {
   /**
    * Gets the overall set of permissions for a member in this channel, taking into account channel overwrites.
    * @param {GuildMember} member The member to obtain the overall permissions for
-   * @param {boolean} checkAdmin=true Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} checkAdmin Whether having the {@link PermissionFlagsBits.Administrator} permission
    * will return all permissions
    * @returns {Readonly<PermissionsBitField>}
    * @private
@@ -223,7 +223,8 @@ class GuildChannel extends BaseChannel {
   /**
    * Gets the overall set of permissions for a role in this channel, taking into account channel overwrites.
    * @param {Role} role The role to obtain the overall permissions for
-   * @param {boolean} checkAdmin Whether having {@link PermissionFlagsBits.Administrator} will return all permissions
+   * @param {boolean} checkAdmin Whether having the {@link PermissionFlagsBits.Administrator} permission
+   * will return all permissions
    * @returns {Readonly<PermissionsBitField>}
    * @private
    */

packages/discord.js/src/structures/Message.js

@@ -82,7 +82,9 @@ class Message extends Base {
 
     if ('content' in data) {
       /**
-       * The content of the message
+       * The content of the message.
+       * <info>This property requires the {@link GatewayIntentBits.MessageContent} privileged intent
+       * in a guild for messages that do not mention the client.</info>
        * @type {?string}
        */
       this.content = data.content;
@@ -134,7 +136,9 @@ class Message extends Base {
 
     if ('embeds' in data) {
       /**
-       * A list of embeds in the message - e.g. YouTube Player
+       * An array of embeds in the message - e.g. YouTube Player.
+       * <info>This property requires the {@link GatewayIntentBits.MessageContent} privileged intent
+       * in a guild for messages that do not mention the client.</info>
        * @type {Embed[]}
        */
       this.embeds = data.embeds.map(e => new Embed(e));
@@ -144,7 +148,9 @@ class Message extends Base {
 
     if ('components' in data) {
       /**
-       * A list of MessageActionRows in the message
+       * An array of of action rows in the message.
+       * <info>This property requires the {@link GatewayIntentBits.MessageContent} privileged intent
+       * in a guild for messages that do not mention the client.</info>
        * @type {ActionRow[]}
        */
       this.components = data.components.map(c => createComponent(c));
@@ -154,7 +160,9 @@ class Message extends Base {
 
     if ('attachments' in data) {
       /**
-       * A collection of attachments in the message - e.g. Pictures - mapped by their ids
+       * A collection of attachments in the message - e.g. Pictures - mapped by their ids.
+       * <info>This property requires the {@link GatewayIntentBits.MessageContent} privileged intent
+       * in a guild for messages that do not mention the client.</info>
        * @type {Collection<Snowflake, Attachment>}
        */
       this.attachments = new Collection();
@@ -642,8 +650,8 @@ class Message extends Base {
    * @property {?string} [content] Content to be edited
    * @property {Embed[]|APIEmbed[]} [embeds] Embeds to be added/edited
    * @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
-   * @property {MessageFlags} [flags] Which flags to set for the message.
-   * Only {@link MessageFlags.SuppressEmbeds} can be edited.
+   * @property {MessageFlags} [flags] Which flags to set for the message
+   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
    * @property {Attachment[]} [attachments] An array of attachments to keep,
    * all attachments will be kept if omitted
    * @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]

packages/discord.js/src/structures/Presence.js

@@ -268,7 +268,7 @@ class Activity {
   }
 
   /**
-   * When concatenated with a string, this automatically returns the activities' name instead of the Activity object.
+   * When concatenated with a string, this automatically returns the activity's name instead of the Activity object.
    * @returns {string}
    */
   toString() {

packages/discord.js/src/structures/Role.js

@@ -223,7 +223,7 @@ class Role extends Base {
    * Returns `channel.permissionsFor(role)`. Returns permissions for a role in a guild channel,
    * taking into account permission overwrites.
    * @param {GuildChannel|Snowflake} channel The guild channel to use as context
-   * @param {boolean} [checkAdmin=true] Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} [checkAdmin=true] Whether having the {@link PermissionFlagsBits.Administrator} permission
    * will return all permissions
    * @returns {Readonly<PermissionsBitField>}
    */

packages/discord.js/src/structures/ThreadChannel.js

@@ -75,9 +75,9 @@ class ThreadChannel extends BaseChannel {
       this.locked = data.thread_metadata.locked ?? false;
 
       /**
-       * Whether members without {@link PermissionFlagsBits.ManageThreads} can invite other members without
-       * {@link PermissionFlagsBits.ManageThreads}
-       * <info>Always `null` in public threads</info>
+       * Whether members without the {@link PermissionFlagsBits.ManageThreads} permission
+       * can invite other members to this thread.
+       * <info>This property is always `null` in public threads.</info>
        * @type {?boolean}
        */
       this.invitable = this.type === ChannelType.GuildPrivateThread ? data.thread_metadata.invitable ?? false : null;
@@ -253,7 +253,7 @@ class ThreadChannel extends BaseChannel {
    * Gets the overall set of permissions for a member or role in this thread's parent channel, taking overwrites into
    * account.
    * @param {GuildMemberResolvable|RoleResolvable} memberOrRole The member or role to obtain the overall permissions for
-   * @param {boolean} [checkAdmin=true] Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} [checkAdmin=true] Whether having the {@link PermissionFlagsBits.Administrator} permission
    * will return all permissions
    * @returns {?Readonly<PermissionsBitField>}
    */
@@ -363,8 +363,8 @@ class ThreadChannel extends BaseChannel {
   }
 
   /**
-   * Sets whether members without the {@link PermissionFlagsBits.ManageThreads} permission can invite other members
-   * without the {@link PermissionFlagsBits.ManageThreads} permission to this thread.
+   * Sets whether members without the {@link PermissionFlagsBits.ManageThreads} permission
+   * can invite other members to this thread.
    * @param {boolean} [invitable=true] Whether non-moderators can invite non-moderators to this thread
    * @param {string} [reason] Reason for changing invite
    * @returns {Promise<ThreadChannel>}
@@ -377,8 +377,9 @@ class ThreadChannel extends BaseChannel {
   }
 
   /**
-   * Sets whether the thread can be **unarchived** by anyone with {@link PermissionFlagsBits.SendMessages} permission.
-   * When a thread is locked only members with {@link PermissionFlagsBits.ManageThreads} can unarchive it.
+   * Sets whether the thread can be **unarchived** by anyone with the
+   * {@link PermissionFlagsBits.SendMessages} permission. When a thread is locked, only members with the
+   * {@link PermissionFlagsBits.ManageThreads} permission can unarchive it.
    * @param {boolean} [locked=true] Whether the thread is locked
    * @param {string} [reason] Reason for locking or unlocking the thread
    * @returns {Promise<ThreadChannel>}