fix: message builders (#10802)

* fix: message builders

- Added `clearParse`, `clearRoles`, and `clearUsers` methods to the `AllowedMentionsBuilder`, since passing an empty array and omitting the these fields behave differently
- Strictened assertions
- Removed `AttachmentBuilder#clearId`, as it is a required field
- Added missing `MessageBuilder#setEmbeds`
- Added missing `MessageReferenceBuilder#setFailIfNotExists`
- Improve/fix documentation
- Consistency™️

* fix: updater functions return type

---------

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

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

@@ -1,6 +1,6 @@
 import { AllowedMentionsTypes, MessageFlags } from 'discord-api-types/v10';
 import { describe, test, expect } from 'vitest';
-import { EmbedBuilder, MessageBuilder } from '../../src/index.js';
+import { AllowedMentionsBuilder, EmbedBuilder, MessageBuilder } from '../../src/index.js';
 
 const base = {
 	allowed_mentions: undefined,
@@ -24,13 +24,41 @@ describe('Message', () => {
 		expect(() => message.toJSON()).toThrow();
 	});
 
+	test('GIVEN parse: [users] and empty users THEN return valid toJSON data', () => {
+		const allowedMentions = new AllowedMentionsBuilder();
+		allowedMentions.setUsers();
+		allowedMentions.setParse(AllowedMentionsTypes.User);
+		expect(allowedMentions.toJSON()).toStrictEqual({ parse: [AllowedMentionsTypes.User], users: [] });
+	});
+
+	test('GIVEN parse: [roles] and empty roles THEN return valid toJSON data', () => {
+		const allowedMentions = new AllowedMentionsBuilder();
+		allowedMentions.setRoles();
+		allowedMentions.setParse(AllowedMentionsTypes.Role);
+		expect(allowedMentions.toJSON()).toStrictEqual({ parse: [AllowedMentionsTypes.Role], roles: [] });
+	});
+
+	test('GIVEN specific users and parse: [users] THEN it throws', () => {
+		const allowedMentions = new AllowedMentionsBuilder();
+		allowedMentions.setUsers('123');
+		allowedMentions.setParse(AllowedMentionsTypes.User);
+		expect(() => allowedMentions.toJSON()).toThrow();
+	});
+
+	test('GIVEN specific roles and parse: [roles] THEN it throws', () => {
+		const allowedMentions = new AllowedMentionsBuilder();
+		allowedMentions.setRoles('123');
+		allowedMentions.setParse(AllowedMentionsTypes.Role);
+		expect(() => allowedMentions.toJSON()).toThrow();
+	});
+
 	test('GIVEN tons of data THEN return valid toJSON data', () => {
 		const message = new MessageBuilder()
 			.setContent('foo')
 			.setNonce(123)
 			.setTTS()
 			.addEmbeds(new EmbedBuilder().setTitle('foo').setDescription('bar'))
-			.setAllowedMentions({ parse: [AllowedMentionsTypes.Role], roles: ['123'] })
+			.setAllowedMentions({ parse: [AllowedMentionsTypes.Role] })
 			.setMessageReference({ channel_id: '123', message_id: '123' })
 			.addActionRowComponents((row) =>
 				row.addPrimaryButtonComponents((button) => button.setCustomId('abc').setLabel('def')),
@@ -46,7 +74,7 @@ describe('Message', () => {
 			nonce: 123,
 			tts: true,
 			embeds: [{ title: 'foo', description: 'bar', author: undefined, fields: [], footer: undefined }],
-			allowed_mentions: { parse: ['roles'], roles: ['123'] },
+			allowed_mentions: { parse: ['roles'] },
 			message_reference: { channel_id: '123', message_id: '123' },
 			components: [
 				{