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/src/messages/AllowedMentions.ts

@@ -11,9 +11,9 @@ export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions>
 	private readonly data: Partial<APIAllowedMentions>;
 
 	/**
-	 * Creates new allowed mention builder from API data.
+	 * Creates a new allowed mentions builder from API data.
 	 *
-	 * @param data - The API data to create this attachment with
+	 * @param data - The API data to create this allowed mentions builder with
 	 */
 	public constructor(data: Partial<APIAllowedMentions> = {}) {
 		this.data = structuredClone(data);
@@ -29,6 +29,14 @@ export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions>
 		return this;
 	}
 
+	/**
+	 * Clears the parse mention types.
+	 */
+	public clearParse(): this {
+		this.data.parse = undefined;
+		return this;
+	}
+
 	/**
 	 * Sets the roles to mention.
 	 *
@@ -65,7 +73,7 @@ export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions>
 	 * allowedMentions.spliceRoles(0, 1);
 	 * ```
 	 * @example
-	 * Remove the first n role:
+	 * Remove the first n roles:
 	 * ```ts
 	 * const n = 4;
 	 * allowedMentions.spliceRoles(0, n);
@@ -85,6 +93,14 @@ export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions>
 		return this;
 	}
 
+	/**
+	 * Clears the roles to mention.
+	 */
+	public clearRoles(): this {
+		this.data.roles = undefined;
+		return this;
+	}
+
 	/**
 	 * Sets the users to mention.
 	 *
@@ -120,7 +136,7 @@ export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions>
 	 * allowedMentions.spliceUsers(0, 1);
 	 * ```
 	 * @example
-	 * Remove the first n user:
+	 * Remove the first n users:
 	 * ```ts
 	 * const n = 4;
 	 * allowedMentions.spliceUsers(0, n);
@@ -141,7 +157,17 @@ export class AllowedMentionsBuilder implements JSONEncodable<APIAllowedMentions>
 	}
 
 	/**
-	 * For replies, sets whether to mention the author of the message being replied to
+	 * Clears the users to mention.
+	 */
+	public clearUsers(): this {
+		this.data.users = undefined;
+		return this;
+	}
+
+	/**
+	 * For replies, sets whether to mention the author of the message being replied to.
+	 *
+	 * @param repliedUser - Whether to mention the author of the message being replied to
 	 */
 	public setRepliedUser(repliedUser = true): this {
 		this.data.replied_user = repliedUser;