feat: add email and phoneNumber formatters (#11050)

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

Author: almeidx

packages/formatters/__tests__/formatters.test.ts

@@ -30,6 +30,8 @@ import {
 	underline,
 	unorderedList,
 	userMention,
+	email,
+	phoneNumber,
 } from '../src/index.js';
 
 describe('Message formatters', () => {
@@ -348,6 +350,33 @@ describe('Message formatters', () => {
 		});
 	});
 
+	describe('email', () => {
+		test('GIVEN an email THEN returns "<[email]>"', () => {
+			expect<'<[email protected]>'>(email('[email protected]')).toEqual('<[email protected]>');
+		});
+
+		test('GIVEN an email AND headers THEN returns "<[email]?[headers]>"', () => {
+			expect<`<[email protected]?${string}>`>(email('[email protected]', { subject: 'Hello', body: 'World' })).toEqual(
+				'<[email protected]?subject=Hello&body=World>',
+			);
+		});
+	});
+
+	describe('phoneNumber', () => {
+		test('GIVEN a phone number with + THEN returns "<[phoneNumber]>"', () => {
+			expect<'<+1234567890>'>(phoneNumber('+1234567890')).toEqual('<+1234567890>');
+		});
+
+		test('GIVEN a phone number without + THEN throws', () => {
+			expect(() =>
+				phoneNumber(
+					// @ts-expect-error - Invalid input
+					'1234567890',
+				),
+			).toThrowError();
+		});
+	});
+
 	describe('Faces', () => {
 		test('GIVEN Faces.Shrug THEN returns "¯\\_(ツ)_/¯"', () => {
 			expect<'¯\\_(ツ)_/¯'>(Faces.Shrug).toEqual('¯\\_(ツ)_/¯');

packages/formatters/src/formatters.ts

@@ -658,6 +658,60 @@ export function applicationDirectory<ApplicationId extends Snowflake, SKUId exte
 	return skuId ? `${url}/${skuId}` : url;
 }
 
+/**
+ * Formats an email address into an email mention.
+ *
+ * @typeParam Email - This is inferred by the supplied email address
+ * @param email - The email address to format
+ */
+export function email<Email extends string>(email: Email): `<${Email}>`;
+
+/**
+ * Formats an email address and headers into an email mention.
+ *
+ * @typeParam Email - This is inferred by the supplied email address
+ * @param email - The email address to format
+ * @param headers - Optional headers to include in the email mention
+ */
+export function email<Email extends string>(
+	email: Email,
+	headers: Record<string, string | readonly string[]> | undefined,
+): `<${Email}?${string}>`;
+
+/**
+ * Formats an email address into an email mention.
+ *
+ * @typeParam Email - This is inferred by the supplied email address
+ * @param email - The email address to format
+ * @param headers - Optional headers to include in the email mention
+ */
+export function email<Email extends string>(email: Email, headers?: Record<string, string | readonly string[]>) {
+	if (headers) {
+		// eslint-disable-next-line n/prefer-global/url-search-params
+		const searchParams = new URLSearchParams(
+			Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value])),
+		);
+
+		return `<${email}?${searchParams.toString()}>` as const;
+	}
+
+	return `<${email}>` as const;
+}
+
+/**
+ * Formats a phone number into a phone number mention.
+ *
+ * @typeParam PhoneNumber - This is inferred by the supplied phone number
+ * @param phoneNumber - The phone number to format. Must start with a `+` sign.
+ */
+export function phoneNumber<PhoneNumber extends `+${string}`>(phoneNumber: PhoneNumber) {
+	if (!phoneNumber.startsWith('+')) {
+		throw new Error('Phone number must start with a "+" sign.');
+	}
+
+	return `<${phoneNumber}>` as const;
+}
+
 /**
  * The {@link https://discord.com/developers/docs/reference#message-formatting-timestamp-styles | message formatting timestamp styles}
  * supported by Discord.