@upyo/core 0.1.0-dev.10

package/README.md

@@ -0,0 +1,19 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/core
+==========
+
+Shared types and interfaces for Upyo, a simple and cross-runtime library for
+sending email messages.
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add     @upyo/core
+pnpm add     @upyo/core
+yarn add     @upyo/core
+deno add jsr:@upyo/core
+bun  add     @upyo/core
+~~~~

package/dist/address.cjs

@@ -0,0 +1,134 @@
+
+//#region src/address.ts
+/**
+* Formats an address object into a string representation.  This function is
+* an inverse of the {@link parseAddress} function.
+*
+* @example Formatting an address with a name
+* ```ts
+* import { type Address, formatAddress } from "@upyo/core/address";
+* const address: Address = { name: "John Doe", address: "john@example.com" };
+* console.log(formatAddress(address)); // "John Doe <john@example.com>"
+* ```
+*
+* @example Formatting an address without a name
+* ```ts
+* import { type Address, formatAddress } from "@upyo/core/address";
+* const address: Address = { address: "jane@examle.com" };
+* console.log(formatAddress(address)); // "jane@example.com"
+* ```
+*
+* @param address The address object to format.
+* @return A string representation of the address.
+*/
+function formatAddress(address) {
+	return address.name == null ? address.address : `${address.name} <${address.address}>`;
+}
+/**
+* Parses a string representation of an email address into an {@link Address}
+* object.  This function is an inverse of the {@link formatAddress} function.
+*
+* @example Parsing an address with a name
+* ```ts
+* import { parseAddress } from "@upyo/core/address";
+* const address = parseAddress("John Doe <john@example.com>");
+* console.log(address); // { name: "John Doe", address: "john@example.com" }
+* ```
+*
+* @example Parsing an address without a name
+* ```ts
+* import { parseAddress } from "@upyo/core/address";
+* const address = parseAddress("jane@example.com");
+* console.log(address); // { address: "jane@example.com" }
+* ```
+*
+* @example Trying to parse an invalid address
+* ```ts
+* import { parseAddress } from "@upyo/core/address";
+* const address = parseAddress("invalid-email");
+* console.log(address); // undefined
+* ```
+*
+* @param address The string representation of the address to parse.
+* @returns An {@link Address} object if the parsing is successful,
+*          or `undefined` if the input is invalid.
+*/
+function parseAddress(address) {
+	if (!address || typeof address !== "string") return void 0;
+	const trimmed = address.trim();
+	if (!trimmed) return void 0;
+	const nameAngleBracketMatch = trimmed.match(/^(.+?)\s*<(.+?)>$/);
+	if (nameAngleBracketMatch) {
+		const name = nameAngleBracketMatch[1].trim();
+		const email = nameAngleBracketMatch[2].trim();
+		if (!isValidEmail(email)) return void 0;
+		const cleanName = name.replace(/^"(.+)"$/, "$1");
+		return {
+			name: cleanName,
+			address: email
+		};
+	}
+	const angleBracketMatch = trimmed.match(/^<(.+?)>$/);
+	if (angleBracketMatch) {
+		const email = angleBracketMatch[1].trim();
+		if (!isValidEmail(email)) return void 0;
+		return { address: email };
+	}
+	if (isValidEmail(trimmed)) return { address: trimmed };
+	return void 0;
+}
+function isValidEmail(email) {
+	if (!email || typeof email !== "string") return false;
+	let atIndex = -1;
+	let inQuotes = false;
+	for (let i = 0; i < email.length; i++) {
+		const char = email[i];
+		if (char === "\"" && (i === 0 || email[i - 1] !== "\\")) inQuotes = !inQuotes;
+		else if (char === "@" && !inQuotes) if (atIndex === -1) atIndex = i;
+		else return false;
+	}
+	if (atIndex === -1) return false;
+	const localPart = email.substring(0, atIndex);
+	const domainPart = email.substring(atIndex + 1);
+	return isValidLocalPart(localPart) && isValidDomainPart(domainPart);
+}
+function isValidLocalPart(localPart) {
+	if (!localPart || localPart.length === 0 || localPart.length > 64) return false;
+	if (localPart.startsWith("\"") && localPart.endsWith("\"")) {
+		const quotedContent = localPart.slice(1, -1);
+		let isValid = true;
+		for (let i = 0; i < quotedContent.length; i++) {
+			const char = quotedContent[i];
+			if (char === "\"" || char === "\r" || char === "\n") {
+				if (i === 0 || quotedContent[i - 1] !== "\\") {
+					isValid = false;
+					break;
+				}
+			}
+		}
+		return isValid;
+	}
+	if (localPart.startsWith(".") || localPart.endsWith(".") || localPart.includes("..")) return false;
+	const validLocalPartRegex = /^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+	return validLocalPartRegex.test(localPart);
+}
+function isValidDomainPart(domainPart) {
+	if (!domainPart || domainPart.length === 0 || domainPart.length > 253) return false;
+	if (domainPart.startsWith("[") && domainPart.endsWith("]")) {
+		const literal = domainPart.slice(1, -1);
+		try {
+			return URL.canParse(`http://${literal}/`);
+		} catch {
+			return false;
+		}
+	}
+	try {
+		return URL.canParse(`http://${domainPart}/`);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+exports.formatAddress = formatAddress;
+exports.parseAddress = parseAddress;

package/dist/address.d.cts

@@ -0,0 +1,68 @@
+//#region src/address.d.ts
+/**
+ * A pair of name (which is optional) and email address.
+ */
+interface Address {
+  /**
+   * The name of the person or entity associated with the email address.
+   */
+  readonly name?: string;
+  /**
+   * The email address itself.
+   */
+  readonly address: string;
+}
+/**
+ * Formats an address object into a string representation.  This function is
+ * an inverse of the {@link parseAddress} function.
+ *
+ * @example Formatting an address with a name
+ * ```ts
+ * import { type Address, formatAddress } from "@upyo/core/address";
+ * const address: Address = { name: "John Doe", address: "john@example.com" };
+ * console.log(formatAddress(address)); // "John Doe <john@example.com>"
+ * ```
+ *
+ * @example Formatting an address without a name
+ * ```ts
+ * import { type Address, formatAddress } from "@upyo/core/address";
+ * const address: Address = { address: "jane@examle.com" };
+ * console.log(formatAddress(address)); // "jane@example.com"
+ * ```
+ *
+ * @param address The address object to format.
+ * @return A string representation of the address.
+ */
+declare function formatAddress(address: Address): string;
+/**
+ * Parses a string representation of an email address into an {@link Address}
+ * object.  This function is an inverse of the {@link formatAddress} function.
+ *
+ * @example Parsing an address with a name
+ * ```ts
+ * import { parseAddress } from "@upyo/core/address";
+ * const address = parseAddress("John Doe <john@example.com>");
+ * console.log(address); // { name: "John Doe", address: "john@example.com" }
+ * ```
+ *
+ * @example Parsing an address without a name
+ * ```ts
+ * import { parseAddress } from "@upyo/core/address";
+ * const address = parseAddress("jane@example.com");
+ * console.log(address); // { address: "jane@example.com" }
+ * ```
+ *
+ * @example Trying to parse an invalid address
+ * ```ts
+ * import { parseAddress } from "@upyo/core/address";
+ * const address = parseAddress("invalid-email");
+ * console.log(address); // undefined
+ * ```
+ *
+ * @param address The string representation of the address to parse.
+ * @returns An {@link Address} object if the parsing is successful,
+ *          or `undefined` if the input is invalid.
+ */
+declare function parseAddress(address: string): Address | undefined;
+//#endregion
+export { Address, formatAddress, parseAddress };

package/dist/address.d.ts

@@ -0,0 +1,68 @@
+//#region src/address.d.ts
+/**
+ * A pair of name (which is optional) and email address.
+ */
+interface Address {
+  /**
+   * The name of the person or entity associated with the email address.
+   */
+  readonly name?: string;
+  /**
+   * The email address itself.
+   */
+  readonly address: string;
+}
+/**
+ * Formats an address object into a string representation.  This function is
+ * an inverse of the {@link parseAddress} function.
+ *
+ * @example Formatting an address with a name
+ * ```ts
+ * import { type Address, formatAddress } from "@upyo/core/address";
+ * const address: Address = { name: "John Doe", address: "john@example.com" };
+ * console.log(formatAddress(address)); // "John Doe <john@example.com>"
+ * ```
+ *
+ * @example Formatting an address without a name
+ * ```ts
+ * import { type Address, formatAddress } from "@upyo/core/address";
+ * const address: Address = { address: "jane@examle.com" };
+ * console.log(formatAddress(address)); // "jane@example.com"
+ * ```
+ *
+ * @param address The address object to format.
+ * @return A string representation of the address.
+ */
+declare function formatAddress(address: Address): string;
+/**
+ * Parses a string representation of an email address into an {@link Address}
+ * object.  This function is an inverse of the {@link formatAddress} function.
+ *
+ * @example Parsing an address with a name
+ * ```ts
+ * import { parseAddress } from "@upyo/core/address";
+ * const address = parseAddress("John Doe <john@example.com>");
+ * console.log(address); // { name: "John Doe", address: "john@example.com" }
+ * ```
+ *
+ * @example Parsing an address without a name
+ * ```ts
+ * import { parseAddress } from "@upyo/core/address";
+ * const address = parseAddress("jane@example.com");
+ * console.log(address); // { address: "jane@example.com" }
+ * ```
+ *
+ * @example Trying to parse an invalid address
+ * ```ts
+ * import { parseAddress } from "@upyo/core/address";
+ * const address = parseAddress("invalid-email");
+ * console.log(address); // undefined
+ * ```
+ *
+ * @param address The string representation of the address to parse.
+ * @returns An {@link Address} object if the parsing is successful,
+ *          or `undefined` if the input is invalid.
+ */
+declare function parseAddress(address: string): Address | undefined;
+//#endregion
+export { Address, formatAddress, parseAddress };

package/dist/address.js

@@ -0,0 +1,132 @@
+//#region src/address.ts
+/**
+* Formats an address object into a string representation.  This function is
+* an inverse of the {@link parseAddress} function.
+*
+* @example Formatting an address with a name
+* ```ts
+* import { type Address, formatAddress } from "@upyo/core/address";
+* const address: Address = { name: "John Doe", address: "john@example.com" };
+* console.log(formatAddress(address)); // "John Doe <john@example.com>"
+* ```
+*
+* @example Formatting an address without a name
+* ```ts
+* import { type Address, formatAddress } from "@upyo/core/address";
+* const address: Address = { address: "jane@examle.com" };
+* console.log(formatAddress(address)); // "jane@example.com"
+* ```
+*
+* @param address The address object to format.
+* @return A string representation of the address.
+*/
+function formatAddress(address) {
+	return address.name == null ? address.address : `${address.name} <${address.address}>`;
+}
+/**
+* Parses a string representation of an email address into an {@link Address}
+* object.  This function is an inverse of the {@link formatAddress} function.
+*
+* @example Parsing an address with a name
+* ```ts
+* import { parseAddress } from "@upyo/core/address";
+* const address = parseAddress("John Doe <john@example.com>");
+* console.log(address); // { name: "John Doe", address: "john@example.com" }
+* ```
+*
+* @example Parsing an address without a name
+* ```ts
+* import { parseAddress } from "@upyo/core/address";
+* const address = parseAddress("jane@example.com");
+* console.log(address); // { address: "jane@example.com" }
+* ```
+*
+* @example Trying to parse an invalid address
+* ```ts
+* import { parseAddress } from "@upyo/core/address";
+* const address = parseAddress("invalid-email");
+* console.log(address); // undefined
+* ```
+*
+* @param address The string representation of the address to parse.
+* @returns An {@link Address} object if the parsing is successful,
+*          or `undefined` if the input is invalid.
+*/
+function parseAddress(address) {
+	if (!address || typeof address !== "string") return void 0;
+	const trimmed = address.trim();
+	if (!trimmed) return void 0;
+	const nameAngleBracketMatch = trimmed.match(/^(.+?)\s*<(.+?)>$/);
+	if (nameAngleBracketMatch) {
+		const name = nameAngleBracketMatch[1].trim();
+		const email = nameAngleBracketMatch[2].trim();
+		if (!isValidEmail(email)) return void 0;
+		const cleanName = name.replace(/^"(.+)"$/, "$1");
+		return {
+			name: cleanName,
+			address: email
+		};
+	}
+	const angleBracketMatch = trimmed.match(/^<(.+?)>$/);
+	if (angleBracketMatch) {
+		const email = angleBracketMatch[1].trim();
+		if (!isValidEmail(email)) return void 0;
+		return { address: email };
+	}
+	if (isValidEmail(trimmed)) return { address: trimmed };
+	return void 0;
+}
+function isValidEmail(email) {
+	if (!email || typeof email !== "string") return false;
+	let atIndex = -1;
+	let inQuotes = false;
+	for (let i = 0; i < email.length; i++) {
+		const char = email[i];
+		if (char === "\"" && (i === 0 || email[i - 1] !== "\\")) inQuotes = !inQuotes;
+		else if (char === "@" && !inQuotes) if (atIndex === -1) atIndex = i;
+		else return false;
+	}
+	if (atIndex === -1) return false;
+	const localPart = email.substring(0, atIndex);
+	const domainPart = email.substring(atIndex + 1);
+	return isValidLocalPart(localPart) && isValidDomainPart(domainPart);
+}
+function isValidLocalPart(localPart) {
+	if (!localPart || localPart.length === 0 || localPart.length > 64) return false;
+	if (localPart.startsWith("\"") && localPart.endsWith("\"")) {
+		const quotedContent = localPart.slice(1, -1);
+		let isValid = true;
+		for (let i = 0; i < quotedContent.length; i++) {
+			const char = quotedContent[i];
+			if (char === "\"" || char === "\r" || char === "\n") {
+				if (i === 0 || quotedContent[i - 1] !== "\\") {
+					isValid = false;
+					break;
+				}
+			}
+		}
+		return isValid;
+	}
+	if (localPart.startsWith(".") || localPart.endsWith(".") || localPart.includes("..")) return false;
+	const validLocalPartRegex = /^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+	return validLocalPartRegex.test(localPart);
+}
+function isValidDomainPart(domainPart) {
+	if (!domainPart || domainPart.length === 0 || domainPart.length > 253) return false;
+	if (domainPart.startsWith("[") && domainPart.endsWith("]")) {
+		const literal = domainPart.slice(1, -1);
+		try {
+			return URL.canParse(`http://${literal}/`);
+		} catch {
+			return false;
+		}
+	}
+	try {
+		return URL.canParse(`http://${domainPart}/`);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { formatAddress, parseAddress };

package/dist/attachment.d.cts

@@ -0,0 +1,31 @@
+//#region src/attachment.d.ts
+/**
+ * Represents an attachment in an email message.
+ */
+interface Attachment {
+  /**
+   * Whether the attachment is intended to be used for inline images.
+   */
+  readonly inline: boolean;
+  /**
+   * The filename of the attachment, which is used for display purposes
+   * and may not be the actual name of the file on disk.
+   */
+  readonly filename: string;
+  /**
+   * The content of the attachment as a byte array.
+   */
+  readonly content: Uint8Array;
+  /**
+   * The media type of the attachment, which indicates the type of content
+   * and how it should be handled by email clients.
+   */
+  readonly contentType: `${string}/${string}`;
+  /**
+   * The content ID of the attachment, which is used to reference
+   * inline images in HTML emails.
+   */
+  readonly contentId: string;
+}
+//#endregion
+export { Attachment };

package/dist/attachment.d.ts

@@ -0,0 +1,31 @@
+//#region src/attachment.d.ts
+/**
+ * Represents an attachment in an email message.
+ */
+interface Attachment {
+  /**
+   * Whether the attachment is intended to be used for inline images.
+   */
+  readonly inline: boolean;
+  /**
+   * The filename of the attachment, which is used for display purposes
+   * and may not be the actual name of the file on disk.
+   */
+  readonly filename: string;
+  /**
+   * The content of the attachment as a byte array.
+   */
+  readonly content: Uint8Array;
+  /**
+   * The media type of the attachment, which indicates the type of content
+   * and how it should be handled by email clients.
+   */
+  readonly contentType: `${string}/${string}`;
+  /**
+   * The content ID of the attachment, which is used to reference
+   * inline images in HTML emails.
+   */
+  readonly contentId: string;
+}
+//#endregion
+export { Attachment };

package/dist/index.cjs

@@ -0,0 +1,6 @@
+const require_address = require('./address.cjs');
+const require_priority = require('./priority.cjs');
+
+exports.comparePriority = require_priority.comparePriority;
+exports.formatAddress = require_address.formatAddress;
+exports.parseAddress = require_address.parseAddress;

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+import { Address, formatAddress, parseAddress } from "./address.cjs";
+import { Attachment } from "./attachment.cjs";
+import { Priority, comparePriority } from "./priority.cjs";
+import { ImmutableHeaders, Message, MessageContent } from "./message.cjs";
+import { Receipt } from "./receipt.cjs";
+import { Transport, TransportOptions } from "./transport.cjs";
+export { Address, Attachment, ImmutableHeaders, Message, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, formatAddress, parseAddress };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { Address, formatAddress, parseAddress } from "./address.js";
+import { Attachment } from "./attachment.js";
+import { Priority, comparePriority } from "./priority.js";
+import { ImmutableHeaders, Message, MessageContent } from "./message.js";
+import { Receipt } from "./receipt.js";
+import { Transport, TransportOptions } from "./transport.js";
+export { Address, Attachment, ImmutableHeaders, Message, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, formatAddress, parseAddress };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { formatAddress, parseAddress } from "./address.js";
+import { comparePriority } from "./priority.js";
+
+export { comparePriority, formatAddress, parseAddress };

package/dist/message.d.cts

@@ -0,0 +1,111 @@
+import { Address } from "./address.cjs";
+import { Attachment } from "./attachment.cjs";
+import { Priority } from "./priority.cjs";
+
+//#region src/message.d.ts
+
+/**
+ * Represents an email message with various properties such as
+ * sender, recipients, subject, content, and attachments.
+ */
+interface Message {
+  /**
+   * The email address of the sender of the message.
+   */
+  readonly sender: Address;
+  /**
+   * The email addresses of the recipient of the message.
+   */
+  readonly recipients: Address[];
+  /**
+   * The email addresses of the carbon copy (CC) recipients of the message.
+   */
+  readonly ccRecipients: Address[];
+  /**
+   * The email addresses of the blind carbon copy (BCC) recipients of the message.
+   */
+  readonly bccRecipients: Address[];
+  /**
+   * The email addresses of the reply-to recipients of the message.
+   */
+  readonly replyRecipients: Address[];
+  /**
+   * The attachments included in the email message.  These are files that
+   * are sent along with the email, such as documents, images, or other
+   * media files.  Each attachment is represented by an {@link Attachment}
+   * object, which contains information about the attachment such as its
+   * filename, content type, and content ID.
+   */
+  readonly attachments: Attachment[];
+  /**
+   * The subject of the email message.  This is typically a brief summary
+   * of the content of the email, and is used to help the recipient identify
+   * the purpose of the message.
+   */
+  readonly subject: string;
+  /**
+   * The content of the email message, which can be either HTML or plain text.
+   * This property is represented by the {@link MessageContent} type, which
+   * includes both HTML and plain text content.  The HTML content is typically
+   * used for rich formatting and layout, while the plain text content is
+   * used for simple text emails or for compatibility with email clients
+   * that do not support HTML.
+   */
+  readonly content: MessageContent;
+  /**
+   * The priority of the email message, which indicates its importance
+   * relative to other messages.  The priority can be one of three
+   * levels: `"high"`, `"normal"`, or `"low"`.  This is represented by
+   * the {@link Priority} type, which is a string literal type that
+   * allows only these three values.
+   */
+  readonly priority: Priority;
+  /**
+   * The tags associated with the email message.
+   */
+  readonly tags: string[];
+  /**
+   * The headers of the email message.  This is represented by
+   * the {@link ImmutableHeaders} type, which is a supertype of
+   * the standard `Headers` class.  The `ImmutableHeaders` type
+   * includes only the methods for reading the headers, such as `get`, `keys`,
+   * `has`, and `entries`, but does not include methods for modifying
+   * the headers, such as `append`, `delete`, or `set`.
+   */
+  readonly headers: ImmutableHeaders;
+}
+/**
+ * Represents the content of an email message, which can be either HTML
+ * or plain text.  The `html` property is optional, and if it is
+ * provided, the `text` property may also be included for
+ * compatibility with email clients that do not support HTML.
+ */
+type MessageContent = {
+  /**
+   * The HTML content of the email message.  This is typically used
+   * for rich formatting and layout.
+   */
+  html: string;
+  /**
+   * The alternative plain text content of the email message.  This is
+   * optional and may be included for compatibility with email
+   * clients that do not support HTML.
+   */
+  text?: string;
+} | {
+  /**
+   * The plain text content of the email message.  This is typically
+   * used for simple text emails.
+   */
+  text: string;
+};
+/**
+ * Represents the headers of an email message.  This type is a supertype of
+ * the standard `Headers` class, which is used to manage HTTP headers.
+ * Note that this type does not include methods for modifying the headers,
+ * such as `append`, `delete`, or `set`.  It is intended to be used for
+ * read-only access to the headers of an email message.
+ */
+type ImmutableHeaders = Omit<Headers, "append" | "delete" | "set">;
+//#endregion
+export { ImmutableHeaders, Message, MessageContent };

package/dist/message.d.ts

@@ -0,0 +1,111 @@
+import { Address } from "./address.js";
+import { Attachment } from "./attachment.js";
+import { Priority } from "./priority.js";
+
+//#region src/message.d.ts
+
+/**
+ * Represents an email message with various properties such as
+ * sender, recipients, subject, content, and attachments.
+ */
+interface Message {
+  /**
+   * The email address of the sender of the message.
+   */
+  readonly sender: Address;
+  /**
+   * The email addresses of the recipient of the message.
+   */
+  readonly recipients: Address[];
+  /**
+   * The email addresses of the carbon copy (CC) recipients of the message.
+   */
+  readonly ccRecipients: Address[];
+  /**
+   * The email addresses of the blind carbon copy (BCC) recipients of the message.
+   */
+  readonly bccRecipients: Address[];
+  /**
+   * The email addresses of the reply-to recipients of the message.
+   */
+  readonly replyRecipients: Address[];
+  /**
+   * The attachments included in the email message.  These are files that
+   * are sent along with the email, such as documents, images, or other
+   * media files.  Each attachment is represented by an {@link Attachment}
+   * object, which contains information about the attachment such as its
+   * filename, content type, and content ID.
+   */
+  readonly attachments: Attachment[];
+  /**
+   * The subject of the email message.  This is typically a brief summary
+   * of the content of the email, and is used to help the recipient identify
+   * the purpose of the message.
+   */
+  readonly subject: string;
+  /**
+   * The content of the email message, which can be either HTML or plain text.
+   * This property is represented by the {@link MessageContent} type, which
+   * includes both HTML and plain text content.  The HTML content is typically
+   * used for rich formatting and layout, while the plain text content is
+   * used for simple text emails or for compatibility with email clients
+   * that do not support HTML.
+   */
+  readonly content: MessageContent;
+  /**
+   * The priority of the email message, which indicates its importance
+   * relative to other messages.  The priority can be one of three
+   * levels: `"high"`, `"normal"`, or `"low"`.  This is represented by
+   * the {@link Priority} type, which is a string literal type that
+   * allows only these three values.
+   */
+  readonly priority: Priority;
+  /**
+   * The tags associated with the email message.
+   */
+  readonly tags: string[];
+  /**
+   * The headers of the email message.  This is represented by
+   * the {@link ImmutableHeaders} type, which is a supertype of
+   * the standard `Headers` class.  The `ImmutableHeaders` type
+   * includes only the methods for reading the headers, such as `get`, `keys`,
+   * `has`, and `entries`, but does not include methods for modifying
+   * the headers, such as `append`, `delete`, or `set`.
+   */
+  readonly headers: ImmutableHeaders;
+}
+/**
+ * Represents the content of an email message, which can be either HTML
+ * or plain text.  The `html` property is optional, and if it is
+ * provided, the `text` property may also be included for
+ * compatibility with email clients that do not support HTML.
+ */
+type MessageContent = {
+  /**
+   * The HTML content of the email message.  This is typically used
+   * for rich formatting and layout.
+   */
+  html: string;
+  /**
+   * The alternative plain text content of the email message.  This is
+   * optional and may be included for compatibility with email
+   * clients that do not support HTML.
+   */
+  text?: string;
+} | {
+  /**
+   * The plain text content of the email message.  This is typically
+   * used for simple text emails.
+   */
+  text: string;
+};
+/**
+ * Represents the headers of an email message.  This type is a supertype of
+ * the standard `Headers` class, which is used to manage HTTP headers.
+ * Note that this type does not include methods for modifying the headers,
+ * such as `append`, `delete`, or `set`.  It is intended to be used for
+ * read-only access to the headers of an email message.
+ */
+type ImmutableHeaders = Omit<Headers, "append" | "delete" | "set">;
+//#endregion
+export { ImmutableHeaders, Message, MessageContent };

package/dist/priority.cjs

@@ -0,0 +1,25 @@
+
+//#region src/priority.ts
+/**
+* Compares two priority levels and returns a number indicating their
+* relative order.
+*
+* @example Sorting priorities
+* ```ts
+* import { comparePriority, type Priority } from "@upyo/core/priority";
+* const priorities: Priority[] = ["normal", "low", "high"];
+* priorities.sort(comparePriority);
+* console.log(priorities); // ["high", "normal", "low"]
+* ```
+*
+* @param a The first priority to compare.
+* @param b The second priority to compare.
+* @return A negative number if `a` is less than `b`, a positive number
+*         if `a` is greater than `b`, and zero if they are equal.
+*/
+function comparePriority(a, b) {
+	return a === b ? 0 : a === "high" ? -1 : b === "high" ? 1 : a === "low" ? 1 : -1;
+}
+
+//#endregion
+exports.comparePriority = comparePriority;

package/dist/priority.d.cts

@@ -0,0 +1,25 @@
+//#region src/priority.d.ts
+/**
+ * The priority levels for email messages.
+ */
+type Priority = "high" | "normal" | "low";
+/**
+ * Compares two priority levels and returns a number indicating their
+ * relative order.
+ *
+ * @example Sorting priorities
+ * ```ts
+ * import { comparePriority, type Priority } from "@upyo/core/priority";
+ * const priorities: Priority[] = ["normal", "low", "high"];
+ * priorities.sort(comparePriority);
+ * console.log(priorities); // ["high", "normal", "low"]
+ * ```
+ *
+ * @param a The first priority to compare.
+ * @param b The second priority to compare.
+ * @return A negative number if `a` is less than `b`, a positive number
+ *         if `a` is greater than `b`, and zero if they are equal.
+ */
+declare function comparePriority(a: Priority, b: Priority): number;
+//#endregion
+export { Priority, comparePriority };

package/dist/priority.d.ts

@@ -0,0 +1,25 @@
+//#region src/priority.d.ts
+/**
+ * The priority levels for email messages.
+ */
+type Priority = "high" | "normal" | "low";
+/**
+ * Compares two priority levels and returns a number indicating their
+ * relative order.
+ *
+ * @example Sorting priorities
+ * ```ts
+ * import { comparePriority, type Priority } from "@upyo/core/priority";
+ * const priorities: Priority[] = ["normal", "low", "high"];
+ * priorities.sort(comparePriority);
+ * console.log(priorities); // ["high", "normal", "low"]
+ * ```
+ *
+ * @param a The first priority to compare.
+ * @param b The second priority to compare.
+ * @return A negative number if `a` is less than `b`, a positive number
+ *         if `a` is greater than `b`, and zero if they are equal.
+ */
+declare function comparePriority(a: Priority, b: Priority): number;
+//#endregion
+export { Priority, comparePriority };

package/dist/priority.js

@@ -0,0 +1,24 @@
+//#region src/priority.ts
+/**
+* Compares two priority levels and returns a number indicating their
+* relative order.
+*
+* @example Sorting priorities
+* ```ts
+* import { comparePriority, type Priority } from "@upyo/core/priority";
+* const priorities: Priority[] = ["normal", "low", "high"];
+* priorities.sort(comparePriority);
+* console.log(priorities); // ["high", "normal", "low"]
+* ```
+*
+* @param a The first priority to compare.
+* @param b The second priority to compare.
+* @return A negative number if `a` is less than `b`, a positive number
+*         if `a` is greater than `b`, and zero if they are equal.
+*/
+function comparePriority(a, b) {
+	return a === b ? 0 : a === "high" ? -1 : b === "high" ? 1 : a === "low" ? 1 : -1;
+}
+
+//#endregion
+export { comparePriority };

package/dist/receipt.d.cts

@@ -0,0 +1,21 @@
+//#region src/receipt.d.ts
+/**
+ * The response from the email service after sending an email message.
+ */
+interface Receipt {
+  /**
+   * The unique identifier for the message that was sent.
+   */
+  readonly messageId: string;
+  /**
+   * An array of error messages that occurred during the sending process,
+   * if any. If the email was sent successfully, this array will be empty.
+   */
+  readonly errorMessages: string[];
+  /**
+   * Indicates whether the email was sent successfully.
+   */
+  readonly successful: boolean;
+}
+//#endregion
+export { Receipt };

package/dist/receipt.d.ts

@@ -0,0 +1,21 @@
+//#region src/receipt.d.ts
+/**
+ * The response from the email service after sending an email message.
+ */
+interface Receipt {
+  /**
+   * The unique identifier for the message that was sent.
+   */
+  readonly messageId: string;
+  /**
+   * An array of error messages that occurred during the sending process,
+   * if any. If the email was sent successfully, this array will be empty.
+   */
+  readonly errorMessages: string[];
+  /**
+   * Indicates whether the email was sent successfully.
+   */
+  readonly successful: boolean;
+}
+//#endregion
+export { Receipt };

package/dist/transport.d.cts

@@ -0,0 +1,43 @@
+import { Message } from "./message.cjs";
+import { Receipt } from "./receipt.cjs";
+
+//#region src/transport.d.ts
+
+/**
+ * A common interface for email sending services.
+ */
+interface Transport {
+  /**
+   * Sends a single message using the email service.
+   * @param message The message to send.
+   * @param options Optional parameters for sending the message.
+   * @returns A promise that resolves to a receipt containing the result of
+   *          the send operation.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple messages using the email service.
+   * @param messages An iterable of messages to send.
+   * @param options Optional parameters for sending the messages.
+   * @return An async iterable that yields receipts for each sent message.
+   */
+  sendMany(messages: Iterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Sends multiple messages using the email service.
+   * @param messages An async iterable of messages to send.
+   * @param options Optional parameters for sending the messages.
+   * @return An async iterable that yields receipts for each sent message.
+   */
+  sendMany(messages: AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+}
+/**
+ * Options for sending messages with the email service.
+ */
+interface TransportOptions {
+  /**
+   * The abort signal to cancel the send operation if needed.
+   */
+  signal?: AbortSignal;
+}
+//#endregion
+export { Transport, TransportOptions };

package/dist/transport.d.ts

@@ -0,0 +1,43 @@
+import { Message } from "./message.js";
+import { Receipt } from "./receipt.js";
+
+//#region src/transport.d.ts
+
+/**
+ * A common interface for email sending services.
+ */
+interface Transport {
+  /**
+   * Sends a single message using the email service.
+   * @param message The message to send.
+   * @param options Optional parameters for sending the message.
+   * @returns A promise that resolves to a receipt containing the result of
+   *          the send operation.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple messages using the email service.
+   * @param messages An iterable of messages to send.
+   * @param options Optional parameters for sending the messages.
+   * @return An async iterable that yields receipts for each sent message.
+   */
+  sendMany(messages: Iterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Sends multiple messages using the email service.
+   * @param messages An async iterable of messages to send.
+   * @param options Optional parameters for sending the messages.
+   * @return An async iterable that yields receipts for each sent message.
+   */
+  sendMany(messages: AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+}
+/**
+ * Options for sending messages with the email service.
+ */
+interface TransportOptions {
+  /**
+   * The abort signal to cancel the send operation if needed.
+   */
+  signal?: AbortSignal;
+}
+//#endregion
+export { Transport, TransportOptions };

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@upyo/core",
+  "version": "0.1.0-dev.10+c222d7c6",
+  "description": "Simple email sending library for Node.js, Deno, Bun, and edge functions",
+  "keywords": [
+    "email",
+    "mail",
+    "sendmail",
+    "smtp"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/core/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/upyo/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./address": {
+      "types": {
+        "import": "./dist/address.d.ts",
+        "require": "./dist/address.cts"
+      },
+      "import": "./dist/address.js",
+      "require": "./dist/address.cjs"
+    },
+    "./attachment": {
+      "types": {
+        "import": "./dist/attachment.d.ts",
+        "require": "./dist/attachment.cts"
+      },
+      "import": "./dist/attachment.js",
+      "require": "./dist/attachment.cjs"
+    },
+    "./message": {
+      "types": {
+        "import": "./dist/message.d.ts",
+        "require": "./dist/message.cts"
+      },
+      "import": "./dist/message.js",
+      "require": "./dist/message.cjs"
+    },
+    "./priority": {
+      "types": {
+        "import": "./dist/priority.d.ts",
+        "require": "./dist/priority.cts"
+      },
+      "import": "./dist/priority.js",
+      "require": "./dist/priority.cjs"
+    },
+    "./receipt": {
+      "types": {
+        "import": "./dist/receipt.d.ts",
+        "require": "./dist/receipt.cts"
+      },
+      "import": "./dist/receipt.js",
+      "require": "./dist/receipt.cjs"
+    },
+    "./transport": {
+      "types": {
+        "import": "./dist/transport.d.ts",
+        "require": "./dist/transport.cts"
+      },
+      "import": "./dist/transport.js",
+      "require": "./dist/transport.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}