arn-rawmime 0.0.1

package/README.md

@@ -0,0 +1,3 @@
+# 📧 arn-rawmime
+
+A lightweight, robust, and fully typed library for generating raw MIME emails. Built for modern Node.js environments with built-in **DKIM signing**, **HTML minification**, and **Attachment handling**.

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "arn-rawmime",
+	"version": "0.0.1",
+	"description": "A lightweight, dependency-free raw MIME email builder with DKIM support.",
+	"author": "ARNDESK",
+	"type": "module",
+	"main": "src/index.js",
+	"types": "src/index.d.ts",
+	"directories": {
+		"test": "test"
+	},
+	"dependencies": {
+		"deepmerge": "^4.3.1",
+		"dom-serializer": "^2.0.0",
+		"domelementtype": "^2.3.0",
+		"domhandler": "^5.0.3",
+		"domutils": "^3.2.2",
+		"entities": "^4.5.0",
+		"he": "^1.2.0",
+		"html-to-text": "^9.0.5",
+		"htmlparser2": "^8.0.2",
+		"leac": "^0.6.0",
+		"marked": "^17.0.1",
+		"mime-types": "^3.0.2",
+		"parseley": "^0.12.1",
+		"peberminta": "^0.9.0",
+		"selderee": "^0.11.0",
+		"turndown": "^7.2.2"
+	},
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"keywords": [
+		"mime",
+		"email"
+	],
+	"license": "ISC"
+}

package/src/dkim-signer.d.ts

@@ -0,0 +1,13 @@
+// src/dkim-signer.d.ts
+
+export interface DKIMOptions {
+    headerFieldNames?: string;
+    privateKey: string;
+    domainName: string;
+    keySelector: string;
+}
+
+/**
+ * Signs a raw email string with DKIM.
+ */
+export function DKIMSign(email: string, options: DKIMOptions): string;

package/src/dkim-signer.js

@@ -0,0 +1,269 @@
+import crypto from "crypto";
+
+/**
+ * Folds a string into multiple lines that don't exceed the given length
+ * @param {String} str String to be folded
+ * @param {Number} [lineLength=76] Maximum length of a line
+ * @param {Boolean} [afterSpace=false] If true, break after spaces
+ * @return {String} Folded string
+ */
+function foldLines(str, lineLength = 76, afterSpace = false) {
+	str = (str || "").toString();
+	let pos = 0;
+	let len = str.length;
+	let result = "";
+
+	while (pos < len) {
+		let line = str.substring(pos, pos + lineLength);
+
+		if (line.length < lineLength) {
+			result += line;
+			break;
+		}
+
+		// Check for existing line breaks
+		let lineBreakMatch = line.match(/^[^\n\r]*(\r?\n|\r)/);
+		if (lineBreakMatch) {
+			line = lineBreakMatch[0];
+			result += line;
+			pos += line.length;
+			continue;
+		}
+
+		// Find appropriate breaking point
+		let wsMatch = line.match(/(\s+)[^\s]*$/);
+		if (wsMatch && wsMatch[0].length - (afterSpace ? (wsMatch[1] || "").length : 0) < line.length) {
+			line = line.substring(0, line.length - (wsMatch[0].length - (afterSpace ? (wsMatch[1] || "").length : 0)));
+		} else {
+			let nextMatch = str.substring(pos + line.length).match(/^[^\s]+(\s*)/);
+			if (nextMatch) {
+				line = line + nextMatch[0].substring(0, nextMatch[0].length - (!afterSpace ? (nextMatch[1] || "").length : 0));
+			}
+		}
+
+		result += line;
+		pos += line.length;
+
+		if (pos < len) {
+			result += "\r\n";
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Sign an email with provided DKIM key, uses RSA-SHA256.
+ *
+ * @param {String} email Full e-mail source complete with headers and body to sign
+ * @param {Object} options DKIM options
+ * @param {String} [options.headerFieldNames='from:to:cc:subject'] Header fields to sign
+ * @param {String} options.privateKey DKIM private key
+ * @param {String} options.domainName Domain name to use for signing (e.g., 'domain.com')
+ * @param {String} options.keySelector Selector for the DKIM public key (e.g., 'dkim' if you have set up a TXT record for 'dkim._domainkey.domain.com')
+ *
+ * @return {String} Signed DKIM-Signature header field for prepending
+ */
+function DKIMSign(email, options) {
+	options = options || {};
+	email = (email || "").toString("utf-8");
+
+	var match = email.match(/^\r?\n|(?:\r?\n){2}/),
+		headers = (match && email.substring(0, match.index)) || "",
+		body = (match && email.substring(match.index + match[0].length)) || email;
+
+	// All listed fields from RFC4871 #5.5
+	var defaultFieldNames =
+		"From:Sender:Reply-To:Subject:To:" +
+		"Cc:MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID:" +
+		"Content-Description:Resent-Date:Resent-From:Resent-Sender:" +
+		"Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References:" +
+		"List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post:" +
+		"List-Owner:List-Archive:" +
+		"List-Unsubscribe-Post:Date:Message-ID:Feedback-ID:DKIM-Signature:";
+
+	var dkim = generateDKIMHeader(
+		options.domainName,
+		options.keySelector,
+		options.headerFieldNames || defaultFieldNames,
+		headers,
+		body
+	),
+		canonicalizedHeaderData = DKIMCanonicalizer.relaxedHeaders(headers, options.headerFieldNames || defaultFieldNames),
+		canonicalizedDKIMHeader = DKIMCanonicalizer.relaxedHeaderLine(dkim),
+		signer,
+		signature;
+
+	// Add the DKIM-Signature header to the canonicalized headers
+	canonicalizedHeaderData.headers += canonicalizedDKIMHeader.key.toLowerCase() + ":" + canonicalizedDKIMHeader.value;
+
+	signer = crypto.createSign("RSA-SHA256");
+	signer.update(canonicalizedHeaderData.headers);
+	signature = signer.sign(options.privateKey, "base64");
+
+	return dkim + signature.replace(/(^.{73}|.{75}(?!\r?\n|\r))/g, "$&\r\n ").trim();
+}
+
+/**
+ * Generates a DKIM-Signature header field without the signature part ('b=' is empty)
+ *
+ * @private
+ * @param {String} domainName Domain name to use for signing
+ * @param {String} keySelector Selector for the DKIM public key
+ * @param {String} headerFieldNames Header fields to sign
+ * @param {String} headers E-mail headers
+ * @param {String} body E-mail body
+ *
+ * @return {String} Mime folded DKIM-Signature string
+ */
+function generateDKIMHeader(domainName, keySelector, headerFieldNames, headers, body) {
+	var canonicalizedBody = DKIMCanonicalizer.relaxedBody(body),
+		canonicalizedBodyHash = sha256(canonicalizedBody, "base64"),
+		canonicalizedHeaderData = DKIMCanonicalizer.relaxedHeaders(headers, headerFieldNames),
+		dkim;
+
+	if (hasUTFChars(domainName)) {
+		try {
+			const url = new URL(`http://${domainName}`);
+			domainName = url.hostname;
+		} catch (err) {
+			console.warn("Failed to convert domain to ASCII:", err);
+		}
+	}
+
+	dkim = [
+		"v=1",
+		"a=rsa-sha256",
+		"c=relaxed/relaxed",
+		"d=" + domainName,
+		"q=dns/txt",
+		"s=" + keySelector,
+		"bh=" + canonicalizedBodyHash,
+		"h=" + canonicalizedHeaderData.fieldNames,
+	].join("; ");
+
+	return foldLines("DKIM-Signature: " + dkim, 76) + ";\r\n b=";
+}
+
+/**
+ * DKIM canonicalization functions
+ */
+const DKIMCanonicalizer = {
+	/**
+	 * Applies "relaxed" canonicalization to message body
+	 * @param {String} body Message body
+	 * @return {String} Canonicalized body
+	 */
+	relaxedBody: function (body) {
+		return (body || "")
+			.toString()
+			.replace(/\r?\n|\r/g, "\n") // Normalize line endings to \n
+			.split("\n")
+			.map(function (line) {
+				return line
+					.replace(/\s*$/, "") // Remove trailing whitespace
+					.replace(/\s+/g, " "); // Collapse multiple whitespace to single space
+			})
+			.join("\n")
+			.replace(/\n*$/, "\n") // Ensure exactly one trailing newline
+			.replace(/\n/g, "\r\n"); // Convert line endings to CRLF
+	},
+
+	/**
+	 * Applies "relaxed" canonicalization to headers
+	 * @param {String} headers Header string
+	 * @param {String} fieldNames List of headers to include
+	 * @return {Object} Canonicalized headers and field names
+	 */
+	relaxedHeaders: function (headers, fieldNames) {
+		var includedFields = (fieldNames || "").split(":").map(function (field) {
+			return field.trim();
+		}),
+			includedFieldsLower = includedFields.map(function (field) {
+				return field.toLowerCase();
+			}),
+			headerFields = {},
+			headerLines = headers.split(/\r?\n|\r/),
+			line,
+			i;
+
+		// Join continuation lines
+		for (i = headerLines.length - 1; i >= 0; i--) {
+			if (i && headerLines[i].match(/^\s/)) {
+				headerLines[i - 1] += "\r\n" + headerLines.splice(i, 1);
+			}
+		}
+
+		// Process header lines
+		for (i = 0; i < headerLines.length; i++) {
+			line = DKIMCanonicalizer.relaxedHeaderLine(headerLines[i]);
+			var keyLower = line.key.toLowerCase();
+
+			if (includedFieldsLower.indexOf(keyLower) >= 0 && !(keyLower in headerFields)) {
+				headerFields[keyLower] = {
+					key: line.key,
+					value: line.value,
+				};
+			}
+		}
+
+		var headers = [];
+		var usedFields = [];
+		for (i = includedFields.length - 1; i >= 0; i--) {
+			var keyLower = includedFields[i].toLowerCase();
+			if (!headerFields[keyLower]) {
+				includedFields.splice(i, 1);
+			} else {
+				headers.unshift(headerFields[keyLower].key.toLowerCase() + ":" + headerFields[keyLower].value);
+				usedFields.unshift(headerFields[keyLower].key);
+			}
+		}
+
+		return {
+			headers: headers.join("\r\n") + "\r\n",
+			fieldNames: usedFields.join(":"),
+		};
+	},
+
+	/**
+	 * Applies "relaxed" canonicalization to a single header line
+	 * @param {String} line Header line
+	 * @return {Object} Parsed header line with key and value
+	 */
+	relaxedHeaderLine: function (line) {
+		var parts = line.split(":"),
+			key = (parts.shift() || "").trim(),
+			value = parts.join(":").replace(/\s+/g, " ").trim();
+
+		return {
+			key: key,
+			value: value,
+		};
+	},
+};
+
+/**
+ * Generates a SHA-256 hash
+ *
+ * @param {String} str String to be hashed
+ * @param {String} [encoding='hex'] Output encoding
+ * @return {String} SHA-256 hash in the selected output encoding
+ */
+function sha256(str, encoding) {
+	var shasum = crypto.createHash("sha256");
+	shasum.update(str);
+	return shasum.digest(encoding || "hex");
+}
+
+/**
+ * Detects if a string includes Unicode symbols
+ *
+ * @param {String} str String to be checked
+ * @return {Boolean} true if the string contains non-ASCII symbols
+ */
+function hasUTFChars(str) {
+	var rforeign = /[^\u0000-\u007f]/;
+	return !!rforeign.test(str);
+}
+
+export { DKIMSign };

package/src/index.d.ts

@@ -0,0 +1,6 @@
+// src/index.d.ts
+// Re-exports all types from individual module files
+
+export * from "./dkim-signer";
+export * from "./processMarkDown";
+export * from "./rawmimeBuilder";

package/src/index.js

@@ -0,0 +1,6 @@
+import { DKIMSign } from "./dkim-signer.js";
+import { processMarkDown } from "./processMarkDown.js";
+import { MimeMessage } from "./rawmimeBuilder.js";
+
+// 2. Add this line at the very bottom of the file
+export { processMarkDown, MimeMessage, DKIMSign };

package/src/processMarkDown.d.ts

@@ -0,0 +1,32 @@
+// src/processMarkDown.d.ts
+
+export interface MarkdownOptions {
+    /** The raw input string (HTML or Markdown) */
+    inputData: string;
+    /** Tag used to identify Markdown input. Default: "[m_d]" */
+    mdTag?: string;
+    /** Legacy tag for backward compatibility. Default: "[mark_down]" */
+    legacyMdTag?: string;
+    /** Convert URLs to visible text links? Default: false */
+    showLinks?: boolean;
+    /** Convert image tags to markdown image syntax? Default: false */
+    showImages?: boolean;
+    /** Max words for the reply/summary. Default: 100 */
+    maxWords?: number;
+}
+
+export interface MarkdownResult {
+    fullMarkdown: string;
+    fullHtml: string;
+    fullText: string;
+    replyMarkdown: string;
+    replyHtml: string;
+    replyText: string;
+    error: string | null;
+}
+
+/**
+ * Processes text/html/markdown input and returns structured data
+ * (Full HTML, Reply HTML, Text versions, etc.)
+ */
+export function processMarkDown(options: MarkdownOptions): Promise<MarkdownResult>;

package/src/processMarkDown.js

@@ -0,0 +1,283 @@
+import TurndownService from "turndown";
+import { marked } from "marked";
+import he from "he";
+
+// ==========================================
+// 1. GLOBAL CONSTANTS
+// ==========================================
+
+const CUTOFF_MARKERS = [
+	// --- Starts With ---
+	{ type: "startsWith", value: "* * *" },
+	{ type: "startsWith", value: ">" },
+	{ type: "startsWith", value: "On " },
+	{ type: "startsWith", value: "Sent from" },
+	{ type: "startsWith", value: "-----Original Message-----" },
+	{ type: "startsWith", value: "this reply" },
+
+	// --- Includes/Contains ---
+	{ type: "includes", value: "Yahoo Mail:" },
+	{ type: "includes", value: "Forwarded Message" },
+	{ type: "includes", value: "Original message" },
+	{ type: "includes", value: "> On " },
+	{ type: "includes", value: "Sent:" },
+	{ type: "includes", value: "From:" },
+	{ type: "includes", value: "To:" },
+	{ type: "includes", value: "Subject:" },
+	{ type: "includes", value: " wrote:" },
+	{ type: "includes", value: "Re:" },
+
+	// --- dbr / Platform Specific ---
+	{ type: "includes", value: "Someone sent you a message" },
+	{ type: "includes", value: "If you would like to block" },
+	{ type: "includes", value: "If this message is spam" },
+	{ type: "includes", value: "If the message contains" },
+];
+
+// ==========================================
+// 2. FACTORIES
+// ==========================================
+
+const createTurndownService = (showLinks, showImages) => {
+	const service = new TurndownService({
+		headingStyle: "atx",
+		bulletListMarker: "-",
+		codeBlockStyle: "fenced",
+	});
+
+	service.remove(["script", "style", "iframe", "object"]);
+
+	service.addRule("keepExplicitBr", {
+		filter: "br",
+		replacement: () => "<br />",
+	});
+
+	service.addRule("processImages", {
+		filter: "img",
+		replacement: (content, node) => {
+			const alt = node.getAttribute("alt") || "";
+			const src = node.getAttribute("src") || "";
+			if (showImages && src) {
+				return `![${alt}](${src})`;
+			} else {
+				return `![${alt}](#)`;
+			}
+		},
+	});
+
+	service.addRule("processLinks", {
+		filter: "a",
+		replacement: (content, node) => {
+			const href = node.getAttribute("href");
+			const text = content.trim();
+
+			if (showLinks && href) {
+				return `[${text}](${href})`;
+			} else {
+				return `[${text}](#)`;
+			}
+		},
+	});
+
+	return service;
+};
+
+/**
+ * Custom Renderer for HTML Output
+ * Forces paragraphs to be <div> instead of <p>
+ */
+const createHtmlRenderer = () => {
+	const renderer = new marked.Renderer();
+
+	// OVERRIDE: Use <div> instead of <p>
+	renderer.paragraph = ({ text }) => {
+		return `<div>${text}</div>\n`;
+	};
+
+	return renderer;
+};
+
+const createTextRenderer = (showLinks, showImages) => {
+	const renderer = new marked.Renderer();
+
+	renderer.paragraph = ({ text }) => text + "\n\n";
+	renderer.heading = ({ text }) => text + "\n\n";
+	renderer.list = ({ body }) => body + "\n";
+	renderer.listitem = ({ text }) => "- " + text + "\n";
+	renderer.code = ({ text }) => text + "\n\n";
+	renderer.blockquote = ({ text }) => "> " + text + "\n";
+
+	renderer.strong = ({ text }) => text;
+	renderer.em = ({ text }) => text;
+	renderer.codespan = ({ text }) => text;
+	renderer.del = ({ text }) => text;
+
+	renderer.link = ({ href, text }) => {
+		if (showLinks && href) return `${text} (${href})`;
+		return text;
+	};
+
+	renderer.image = ({ href, text }) => {
+		if (showImages && href) return `[Image: ${text || "image"} - ${href}]`;
+		return text ? `[Image: ${text}]` : "[Image]";
+	};
+
+	renderer.html = ({ text }) => {
+		if (text && text.includes("<br")) return "\n";
+		return "";
+	};
+	renderer.br = () => "\n";
+
+	return renderer;
+};
+
+// ==========================================
+// 3. HELPER FUNCTIONS
+// ==========================================
+
+const isHtml = (text) => {
+	if (!text) return false;
+	if (/^\s*<!DOCTYPE/i.test(text) || /^\s*<html/i.test(text)) return true;
+	return /<(\/?(br|div|p|span|a|b|i|strong|ul|ol|li|blockquote|table|img)|!DOCTYPE|html|body)[^>]*>/i.test(text);
+};
+
+const getLatestReplyMarkdown = (fullMarkdown) => {
+	const lines = fullMarkdown.split("\n");
+	let cutoffIndex = lines.length;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].toLowerCase().trim();
+		if (!line) continue;
+
+		const isMatch = CUTOFF_MARKERS.some((marker) => {
+			if (marker.type === "startsWith") return line.startsWith(marker.value.toLowerCase());
+			if (marker.type === "includes") return line.includes(marker.value.toLowerCase());
+			return false;
+		});
+
+		if (isMatch) {
+			cutoffIndex = i;
+			break;
+		}
+	}
+	return lines.slice(0, cutoffIndex).join("\n").trim();
+};
+
+const cleanTextOutput = (text) => {
+	if (!text) return "";
+	let cleaned = text.replace(/<br\s*\/?>/gi, "\n");
+	cleaned = cleaned.replace(/<\/?[^>]+(>|$)/g, "");
+
+	return he.decode(cleaned).trim();
+};
+
+const decodeSafeHtml = (html) => {
+	if (!html) return "";
+
+	return html.replace(/&[^;]+;/g, (match) => {
+		if (match === "&lt;" || match === "&gt;") {
+			return match;
+		}
+		return he.decode(match);
+	});
+};
+
+const truncateWords = (text, maxWords) => {
+	if (!text || !maxWords || maxWords <= 0) return text;
+	const words = text.trim().split(/\s+/);
+	if (words.length <= maxWords) return text;
+	return words.slice(0, maxWords).join(" ") + " ...";
+};
+
+const getDefaultEmpty = () => ({
+	fullMarkdown: "",
+	fullHtml: "",
+	fullText: "",
+	replyMarkdown: "",
+	replyHtml: "",
+	replyText: "",
+	error: "Invalid Input",
+});
+
+// ==========================================
+// 4. MAIN EXPORT FUNCTION
+// ==========================================
+
+export async function processMarkDown({
+	inputData,
+	mdTag = "[m_d]",
+	legacyMdTag = "[mark_down]",
+	showLinks = false,
+	showImages = false,
+	maxWords = 100, // Default 0 = Unlimited
+} = {}) {
+	if (!inputData || typeof inputData !== "string") return getDefaultEmpty();
+
+	try {
+		const turndownService = createTurndownService(showLinks, showImages);
+		const textRenderer = createTextRenderer(showLinks, showImages);
+		const htmlRenderer = createHtmlRenderer(); // <--- Initialize the new renderer
+
+		let masterMarkdown = "";
+		let intermediateHtml = "";
+		const cleanedInput = inputData.trim();
+
+		if (cleanedInput.startsWith(mdTag)) {
+			const rawMd = cleanedInput.replace(mdTag, "").trimStart();
+			intermediateHtml = marked.parse(rawMd);
+		} else if (cleanedInput.startsWith(legacyMdTag)) {
+			const rawMd = cleanedInput.replace(legacyMdTag, "").trimStart();
+			intermediateHtml = marked.parse(rawMd);
+		} else if (isHtml(cleanedInput)) {
+			intermediateHtml = cleanedInput;
+		} else {
+			intermediateHtml = marked.parse(cleanedInput);
+		}
+
+		masterMarkdown = turndownService.turndown(intermediateHtml);
+		masterMarkdown = masterMarkdown.replace(/(<br\s*\/?>)\n+/gi, "$1\n");
+
+		let replyMarkdownRaw = getLatestReplyMarkdown(masterMarkdown);
+
+		if (maxWords > 0) {
+			replyMarkdownRaw = truncateWords(replyMarkdownRaw, maxWords);
+		}
+
+		// --- Generate Versions ---
+
+		// 1. HTML: Use the custom htmlRenderer (uses <div> instead of <p>)
+		const rawFullHtml = marked.parse(masterMarkdown, { renderer: htmlRenderer, gfm: true, breaks: true });
+
+		// 2. TEXT: Use the custom textRenderer (strips tags)
+		const rawFullText = marked.parse(masterMarkdown, { renderer: textRenderer, breaks: true });
+
+		// 3. HTML Reply: Use custom htmlRenderer
+		const rawReplyHtml = marked.parse(replyMarkdownRaw, { renderer: htmlRenderer, gfm: true, breaks: true });
+
+		// 4. TEXT Reply: Use custom textRenderer
+		const rawReplyText = marked.parse(replyMarkdownRaw, { renderer: textRenderer, breaks: true });
+
+		// --- Clean & Decode ---
+
+		const fullHtml = decodeSafeHtml(rawFullHtml.trim());
+		const replyHtml = decodeSafeHtml(rawReplyHtml.trim());
+
+		const fullText = cleanTextOutput(rawFullText);
+		const replyText = cleanTextOutput(rawReplyText);
+
+		return {
+			fullMarkdown: `${mdTag}\n${masterMarkdown}`,
+			fullHtml: fullHtml,
+			fullText: fullText,
+
+			replyMarkdown: `${mdTag}\n${replyMarkdownRaw}`,
+			replyHtml: replyHtml,
+			replyText: replyText,
+
+			error: null,
+		};
+	} catch (err) {
+		console.error("Error processing content:", err);
+		return { ...getDefaultEmpty(), error: err.message };
+	}
+}

package/src/rawmimeBuilder.d.ts

@@ -0,0 +1,91 @@
+// src/rawmimeBuilder.d.ts
+
+import type { DKIMOptions } from "./dkim-signer";
+
+export interface Mailbox {
+    name?: string;
+    email: string;
+}
+
+export type MailboxInput = string | Mailbox | (string | Mailbox)[];
+
+export class MimeMessage {
+    constructor();
+
+    /**
+     * Removes specific headers from the message.
+     * @param headerNames Single header name or array of names.
+     */
+    removeHeaders(headerNames: string | string[]): void;
+
+    /**
+     * Overwrites an existing header or adds it if it doesn't exist.
+     */
+    updateHeader(name: string, value: string): void;
+
+    /**
+     * Adds a header. Handles singleton headers (From, Date, etc) by overwriting.
+     */
+    addCustomHeader(name: string, value: string): void;
+
+    setFrom(sender: MailboxInput): void;
+    setTo(recipients: MailboxInput): void;
+    setCc(recipients: MailboxInput): void;
+    setBcc(recipients: MailboxInput): void;
+    setReplyTo(replyTo: MailboxInput): void;
+    setSubject(subject: string): void;
+
+    /**
+     * Sets the Date header using a specific Time Zone or a random US Time Zone.
+     * @param options Configuration object.
+     * @param options.timeZone The IANA time zone identifier (e.g., "America/New_York", "UTC"). Defaults to "UTC".
+     * @param options.randomUSA If true, selects a random major US time zone (ignoring the `timeZone` parameter). Defaults to false.
+     */
+    setDate(options?: { timeZone?: string; randomUSA?: boolean }): void;
+
+    /**
+     * Generates or sets the Message-ID.
+     */
+    messageId(options?: { id?: string; domain?: string }): void;
+
+    /**
+     * Adds the plain text version of the email.
+     */
+    addText(options: { data: string; encoding?: "quoted-printable" | "base64" }): void;
+
+    /**
+     * Adds the HTML version of the email.
+     */
+    addHtml(options: {
+        data: string;
+        encoding?: "quoted-printable" | "base64";
+        autoTextPart?: boolean;
+        autoMinify?: boolean;
+        /** * If true, the `data` is treated as input for the markdown processor.
+         * It will be converted to HTML, sanitized, and used to generate the body.
+         */
+        markdownToHtml?: boolean;
+    }): void;
+
+    /**
+     * Adds an attachment from a file path.
+     */
+    addAttachment(options: { path: string; name?: string; cid?: string }): void;
+
+    /**
+     * Generates the raw MIME string (headers + body).
+     * @returns Promise resolving to the full email string.
+     */
+    asRaw(): Promise<string>;
+
+    /**
+     * Generates the Base64URL encoded string (suitable for Gmail API).
+     * @returns Promise resolving to the encoded string.
+     */
+    asEncoded(): Promise<string>;
+
+    /**
+     * Signs the email using DKIM.
+     */
+    addDKIM(options: DKIMOptions | DKIMOptions[], dkimOptions?: { chain: boolean }): Promise<string>;
+}

package/src/rawmimeBuilder.js

@@ -0,0 +1,622 @@
+import mime from "mime-types";
+import { promises as fs } from "fs";
+import path from "path";
+import { randomBytes } from "crypto";
+import { convert } from "html-to-text";
+import { DKIMSign } from "./dkim-signer.js";
+import { processMarkDown } from "./processMarkDown.js"; // <--- IMPORT ADDED
+
+const desiredOrder = [
+	"List-Unsubscribe-Post",
+	"List-Unsubscribe",
+	"Feedback-ID",
+	"MIME-Version",
+	"References",
+	"In-Reply-To",
+	"Reply-To",
+	"From",
+	"Date",
+	"Message-ID",
+	"Subject",
+	"To",
+];
+
+class MimeMessage {
+	constructor() {
+		this.headers = [];
+		this.bodyParts = [];
+		this.attachments = [];
+		this.attachmentPromises = [];
+		this.processingPromises = []; // <--- NEW: Track async ops
+		this.removedHeaders = new Set();
+	}
+
+	// ─── HELPER: HTML to Text Converter ─────────────────────────────
+	_htmlToText(html) {
+		if (!html) return "";
+		return convert(html, {
+			wordwrap: 130,
+			selectors: [
+				{ selector: "img", format: "skip" },
+				{ selector: "a", options: { hideLinkHrefIfSameAsText: true } },
+			],
+		});
+	}
+
+	// ─── HELPER: Safe HTML Minifier (FIXED) ─────────────────────────
+	_minifyHtml(html) {
+		if (!html) return "";
+		let minified = html;
+
+		// 1. Collapse all whitespace (newlines, tabs, spaces) into a single space
+		minified = minified.replace(/\s+/g, " ");
+
+		// 2. Remove space between tags (e.g. "</div> <div" -> "</div><div")
+		minified = minified.replace(/>\s+</g, "><");
+
+		return minified.trim();
+	}
+
+	// ─── HELPER: Smart Quoted-Printable Encoder (Word-Wrap) ─────────
+	_encodeQuotedPrintable(str) {
+		if (!str) return "";
+
+		// 1. Split into paragraphs first to preserve user's hard returns
+		const paragraphs = str.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+
+		return paragraphs
+			.map((line) => {
+				const buffer = Buffer.from(line, "utf8");
+
+				// 2. Pre-encode characters
+				let tempStr = "";
+				for (let i = 0; i < buffer.length; i++) {
+					const byte = buffer[i];
+					const isSafe = byte >= 33 && byte <= 126 && byte !== 61;
+					const isSpaceOrTab = byte === 32 || byte === 9;
+
+					if (isSafe) {
+						tempStr += String.fromCharCode(byte);
+					} else if (isSpaceOrTab) {
+						tempStr += String.fromCharCode(byte);
+					} else {
+						tempStr += "=" + byte.toString(16).toUpperCase().padStart(2, "0");
+					}
+				}
+
+				// 3. Apply Soft-Wrapping (76 chars max)
+				let result = "";
+				let currentLineLength = 0;
+				const tokens = tempStr.match(/([ \t]+)|([^ \t]+)/g) || [];
+
+				tokens.forEach((token) => {
+					if (currentLineLength + token.length > 75) {
+						if (currentLineLength > 0) {
+							result += "=\r\n";
+							currentLineLength = 0;
+						}
+						if (token.length > 75) {
+							// Hard split for giant tokens
+							const chunks = token.match(/.{1,73}/g);
+							chunks.forEach((chunk, idx) => {
+								if (idx < chunks.length - 1) {
+									result += chunk + "=\r\n";
+								} else {
+									result += chunk;
+									currentLineLength = chunk.length;
+								}
+							});
+						} else {
+							result += token;
+							currentLineLength = token.length;
+						}
+					} else {
+						result += token;
+						currentLineLength += token.length;
+					}
+				});
+
+				return result;
+			})
+			.join("\r\n");
+	}
+
+	// ─── HELPER: Header Folding (RFC 5322) ──────────────────────────
+	_foldHeader(name, value) {
+		const line = `${name}: ${value}`;
+		if (line.length <= 76) return line;
+
+		const headerKey = `${name}: `;
+		let remaining = value;
+		let result = headerKey;
+		let available = 76 - headerKey.length;
+
+		if (remaining.length < available) return result + remaining;
+
+		result += remaining.substring(0, available) + "\r\n ";
+		remaining = remaining.substring(available);
+
+		while (remaining.length > 75) {
+			result += remaining.substring(0, 75) + "\r\n ";
+			remaining = remaining.substring(75);
+		}
+		result += remaining;
+		return result;
+	}
+
+	removeHeaders(headerNames) {
+		if (!Array.isArray(headerNames)) headerNames = [headerNames];
+		headerNames.forEach((name) => this.removedHeaders.add(name.toLowerCase()));
+		this.headers = this.headers.filter((h) => !this.removedHeaders.has(h.name.toLowerCase()));
+	}
+
+	updateHeader(name, value) {
+		this.headers = this.headers.filter((h) => h.name.toLowerCase() !== name.toLowerCase());
+		this.headers.push({ name, value });
+	}
+
+	addCustomHeader(name, value) {
+		const singletonHeaders = [
+			"date",
+			"from",
+			"sender",
+			"reply-to",
+			"to",
+			"cc",
+			"bcc",
+			"message-id",
+			"in-reply-to",
+			"references",
+			"subject",
+			"mime-version",
+		];
+		if (singletonHeaders.includes(name.toLowerCase())) {
+			const exists = this.headers.some((h) => h.name.toLowerCase() === name.toLowerCase());
+			if (exists) {
+				console.warn(`[MimeMessage] Warning: Overwriting singleton header "${name}".`);
+			}
+			this.updateHeader(name, value);
+		} else {
+			this.headers.push({ name, value });
+		}
+	}
+
+	formatMailboxes(mailboxes) {
+		if (!mailboxes) return "";
+		const mbs = Array.isArray(mailboxes) ? mailboxes : [mailboxes];
+		return mbs.map((mb) => (mb.name ? `"${mb.name}" <${mb.email}>` : mb.email)).join(", ");
+	}
+
+	setFrom(sender) {
+		this.updateHeader("From", this.formatMailboxes(sender));
+	}
+	setTo(recipients) {
+		this.updateHeader("To", this.formatMailboxes(recipients));
+	}
+	setCc(recipients) {
+		this.updateHeader("Cc", this.formatMailboxes(recipients));
+	}
+	setBcc(recipients) {
+		this.updateHeader("Bcc", this.formatMailboxes(recipients));
+	}
+	setSubject(subject) {
+		this.updateHeader("Subject", subject);
+	}
+	setReplyTo(replyTo) {
+		this.updateHeader("Reply-To", this.formatMailboxes(replyTo));
+	}
+
+	setDate({ timeZone = "UTC", randomUSA = false } = {}) {
+		let selectedZone = timeZone;
+
+		if (randomUSA) {
+			const usaZones = [
+				"America/New_York", // Eastern
+				"America/Chicago", // Central
+				"America/Denver", // Mountain
+				"America/Phoenix", // Mountain (No DST)
+				"America/Los_Angeles", // Pacific
+				"America/Anchorage", // Alaska
+				"Pacific/Honolulu", // Hawaii
+			];
+			selectedZone = usaZones[Math.floor(Math.random() * usaZones.length)];
+		}
+
+		const date = new Date();
+
+		// 1. Use Intl to format the date for the specific Time Zone
+		const formatter = new Intl.DateTimeFormat("en-US", {
+			timeZone: selectedZone,
+			weekday: "short",
+			day: "numeric",
+			month: "short",
+			year: "numeric",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			hour12: false,
+			timeZoneName: "longOffset", // e.g., "GMT-05:00" or just "GMT"
+		});
+
+		// 2. Extract the parts
+		const parts = formatter.formatToParts(date);
+		const getPart = (type) => parts.find((p) => p.type === type)?.value;
+
+		const weekday = getPart("weekday");
+		const day = getPart("day");
+		const month = getPart("month");
+		const year = getPart("year");
+
+		// Handle midnight "24" edge case
+		let hour = getPart("hour");
+		if (hour === "24") hour = "00";
+
+		const minute = getPart("minute");
+		const second = getPart("second");
+
+		// 3. Fix the Timezone format
+		const tzRaw = getPart("timeZoneName") || "";
+
+		// Remove "GMT" and the colon (":")
+		// Example: "GMT-05:00" -> "-0500"
+		// Example: "GMT" -> ""
+		let tzClean = tzRaw.replace("GMT", "").replace(":", "").trim();
+
+		// If the result is empty (common for UTC), force +0000
+		if (!tzClean) {
+			tzClean = "+0000";
+		}
+
+		// 4. Construct valid RFC 5322 Date Header
+		const dateStr = `${weekday}, ${day} ${month} ${year} ${hour}:${minute}:${second} ${tzClean}`;
+
+		this.updateHeader("Date", dateStr);
+	}
+
+	messageId(options = {}) {
+		const { id, domain } = options;
+		let localPart = id ? id : "CA" + this._generateRandomString(49);
+		let msgDomain = domain;
+		if (!msgDomain) {
+			const fromHeader = this.headers.find((h) => h.name.toLowerCase() === "from");
+			if (fromHeader) {
+				const match = fromHeader.value.match(/<([^>]+)>/);
+				let emailAddress = match ? match[1] : fromHeader.value;
+				const atIndex = emailAddress.lastIndexOf("@");
+				msgDomain = atIndex !== -1 ? emailAddress.slice(atIndex + 1) : "mail.gmail.com";
+			} else {
+				msgDomain = "mail.gmail.com";
+			}
+		}
+		const fullMessageId = `<${localPart.trim()}@${msgDomain.trim()}>`;
+		this.updateHeader("Message-ID", fullMessageId);
+	}
+
+	_generateRandomString(length) {
+		const allowed = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789=";
+		const bytes = randomBytes(length);
+		let result = "";
+		for (let i = 0; i < length; i++) result += allowed[bytes[i] % allowed.length];
+		return result;
+	}
+
+	_validateEncoding(encoding) {
+		const allowed = ["quoted-printable", "base64"];
+		if (!allowed.includes(encoding)) {
+			throw new Error(`Invalid encoding: ${encoding}. Allowed options: ${allowed.join(", ")}`);
+		}
+	}
+
+	_addBodyPart(data, contentType, encoding) {
+		this._validateEncoding(encoding);
+		if (typeof data !== "string") data = "";
+
+		let encodedData;
+		if (encoding === "quoted-printable") {
+			encodedData = this._encodeQuotedPrintable(data);
+		} else {
+			encodedData =
+				Buffer.from(data, "utf8")
+					.toString("base64")
+					.match(/.{1,76}/g)
+					?.join("\r\n") || "";
+		}
+
+		this.bodyParts.push({
+			data: encodedData,
+			contentType,
+			charset: '"UTF-8"', // Added quotes for compliance
+			encoding,
+		});
+	}
+
+	// Default encoding is now 'quoted-printable'
+	addText({ data, encoding = "quoted-printable" }) {
+		this._addBodyPart(data, "text/plain", encoding);
+	}
+
+	/**
+	 * @param {Object} opts
+	 * @param {string} opts.data - The HTML string
+	 * @param {string} opts.encoding - Default "quoted-printable"
+	 * @param {boolean} opts.autoTextPart - Auto-generates text/plain
+	 * @param {boolean} opts.autoMinify - Minifies HTML before encoding
+	 * @param {boolean} opts.markdownToHtml - Process markdown before adding
+	 */
+	addHtml({
+		data,
+		encoding = "quoted-printable",
+		autoTextPart = false,
+		autoMinify = true,
+		markdownToHtml = false, // <--- NEW OPTION
+	}) {
+		if (markdownToHtml) {
+			// Push the async operation to the queue
+			const promise = processMarkDown({
+				inputData: data,
+				showLinks: true,
+				showImages: true,
+			})
+				.then((body_data) => {
+					// Call addHtml again, but with processed HTML and flag set to false
+					this.addHtml({
+						data: body_data.fullHtml,
+						encoding,
+						autoTextPart,
+						autoMinify,
+						markdownToHtml: false,
+					});
+				})
+				.catch((err) => {
+					console.error("[MimeMessage] Markdown processing failed:", err);
+					// Fallback to original data if processing fails
+					this.addHtml({
+						data: data,
+						encoding,
+						autoTextPart,
+						autoMinify,
+						markdownToHtml: false,
+					});
+				});
+
+			this.processingPromises.push(promise);
+			return;
+		}
+
+		let finalHtml = data;
+
+		if (autoMinify) {
+			finalHtml = this._minifyHtml(finalHtml);
+		}
+
+		this._addBodyPart(finalHtml, "text/html", encoding);
+
+		if (autoTextPart) {
+			// Use ORIGINAL data for text conversion to ensure readability
+			const plainText = this._htmlToText(data);
+			this.addText({ data: plainText, encoding: encoding });
+		}
+	}
+
+	_generateRandomNumericString(length) {
+		const bytes = randomBytes(length);
+		let result = "";
+		for (let i = 0; i < length; i++) result += (bytes[i] % 10).toString();
+		return result;
+	}
+
+	addAttachment({ path: filePath, name: customName, cid: customCid }) {
+		const promise = fs
+			.readFile(filePath)
+			.then((fileData) => {
+				const originalExt = path.extname(filePath);
+				let fileName;
+				if (customName) {
+					const customExt = path.extname(customName);
+					fileName = customExt ? customName : customName + originalExt;
+				} else {
+					fileName = this._generateRandomNumericString(12) + originalExt;
+				}
+
+				const contentType = mime.lookup(filePath) || "application/octet-stream";
+				const encodedData = fileData
+					.toString("base64")
+					.match(/.{1,76}/g)
+					.join("\r\n");
+				const cleanCid = customCid ? customCid.replace(/[<>]/g, "") : `f_${randomBytes(4).toString("hex")}`;
+
+				this.attachments.push({
+					data: encodedData,
+					contentType,
+					encoding: "base64",
+					fileName,
+					headers: {
+						"Content-Disposition": customCid ? `inline; filename="${fileName}"` : `attachment; filename="${fileName}"`,
+						"X-Attachment-Id": cleanCid,
+						"Content-ID": `<${cleanCid}>`,
+					},
+				});
+			})
+			.catch((error) => {
+				console.error("Attachment Error:", error);
+				throw error;
+			});
+		this.attachmentPromises.push(promise);
+	}
+
+	generateBoundary(oldBoundary) {
+		if (oldBoundary) {
+			const prefix = oldBoundary.slice(0, 17);
+			let newPart;
+			do {
+				newPart = randomBytes(6).toString("hex").slice(0, 11);
+			} while (prefix + newPart === oldBoundary);
+			return prefix + newPart;
+		}
+		return "000000000000" + randomBytes(8).toString("hex");
+	}
+
+	// ─── BUILDING THE RAW EMAIL ───────────────────────────────────────
+
+	async asRaw() {
+		// Wait for Attachments AND Markdown Processing
+		await Promise.all([...this.attachmentPromises, ...this.processingPromises]);
+
+		if (!this.headers.some((h) => h.name.toLowerCase() === "mime-version"))
+			this.headers.unshift({ name: "MIME-Version", value: "1.0" });
+		if (!this.headers.some((h) => h.name.toLowerCase() === "date")) this.setDate();
+		if (!this.headers.some((h) => h.name.toLowerCase() === "message-id")) this.messageId();
+		if (!this.headers.some((h) => h.name.toLowerCase() === "subject")) this.setSubject("");
+
+		// Sort Body: Text MUST be first
+		this.bodyParts.sort((a, b) => {
+			if (a.contentType === "text/plain") return -1;
+			if (b.contentType === "text/plain") return 1;
+			return 0;
+		});
+
+		let body = "";
+		const numAttachments = this.attachments.length;
+		const numBodyParts = this.bodyParts.length;
+
+		// NOTE: Double \r\n\r\n added after content parts for visual separation
+
+		// CASE 1: No Attachments (Multipart/Alternative)
+		if (numAttachments === 0) {
+			if (numBodyParts > 1) {
+				const boundary = this.generateBoundary();
+				this.updateHeader("Content-Type", `multipart/alternative; boundary="${boundary}"`);
+				body += "\r\n\r\n";
+				for (let part of this.bodyParts) {
+					body += `--${boundary}\r\n`;
+					body += `Content-Type: ${part.contentType}; charset=${part.charset}\r\n`;
+					body += `Content-Transfer-Encoding: ${part.encoding}\r\n\r\n`;
+					body += part.data + "\r\n\r\n"; // Visual Gap
+				}
+				body += `--${boundary}--`;
+			} else if (numBodyParts === 1) {
+				const part = this.bodyParts[0];
+				this.updateHeader("Content-Type", `${part.contentType}; charset=${part.charset}`);
+				body += `\r\nContent-Transfer-Encoding: ${part.encoding}\r\n\r\n${part.data}`;
+			} else {
+				// throw new Error("No body content found.");
+				// Removed throw to prevent crashing on empty bodies (optional)
+			}
+		}
+		// CASE 2: With Attachments (Multipart/Mixed)
+		else {
+			const mixedBoundary = this.generateBoundary();
+			this.updateHeader("Content-Type", `multipart/mixed; boundary="${mixedBoundary}"`);
+			body += "\r\n\r\n";
+
+			// A. Inner Body (Alternative)
+			if (numBodyParts > 0) {
+				if (numBodyParts > 1) {
+					const altBoundary = this.generateBoundary(mixedBoundary);
+					body += `--${mixedBoundary}\r\n`;
+					body += `Content-Type: multipart/alternative; boundary="${altBoundary}"\r\n\r\n`;
+					for (let part of this.bodyParts) {
+						body += `--${altBoundary}\r\n`;
+						body += `Content-Type: ${part.contentType}; charset=${part.charset}\r\n`;
+						body += `Content-Transfer-Encoding: ${part.encoding}\r\n\r\n`;
+						body += part.data + "\r\n\r\n"; // Visual Gap
+					}
+					body += `--${altBoundary}--\r\n\r\n`; // Gap after inner close
+				} else {
+					const part = this.bodyParts[0];
+					body += `--${mixedBoundary}\r\n`;
+					body += `Content-Type: ${part.contentType}; charset=${part.charset}\r\n`;
+					body += `Content-Transfer-Encoding: ${part.encoding}\r\n\r\n`;
+					body += part.data + "\r\n\r\n"; // Visual Gap
+				}
+			}
+
+			// B. Attachments
+			for (let att of this.attachments) {
+				body += `--${mixedBoundary}\r\n`;
+				body += `Content-Type: ${att.contentType}; name="${att.fileName}"\r\n`;
+				body += `Content-Disposition: ${att.headers["Content-Disposition"]}\r\n`;
+				body += `Content-Transfer-Encoding: ${att.encoding}\r\n`;
+				body += `Content-ID: ${att.headers["Content-ID"]}\r\n`;
+				body += `X-Attachment-Id: ${att.headers["X-Attachment-Id"]}\r\n\r\n`;
+				body += att.data + "\r\n\r\n"; // Visual Gap
+			}
+			body += `--${mixedBoundary}--`;
+		}
+
+		// ─── HEADER SORTING & FOLDING ───
+		let contentTypeHeader = null;
+		const recognized = [];
+		const unrecognized = [];
+
+		this.headers.forEach((h) => {
+			if (this.removedHeaders.has(h.name.toLowerCase())) return;
+			if (h.name.toLowerCase() === "content-type") {
+				contentTypeHeader = h;
+			} else if (desiredOrder.some((key) => key.toLowerCase() === h.name.toLowerCase())) {
+				recognized.push(h);
+			} else {
+				unrecognized.push(h);
+			}
+		});
+
+		recognized.sort((a, b) => {
+			const idxA = desiredOrder.findIndex((k) => k.toLowerCase() === a.name.toLowerCase());
+			const idxB = desiredOrder.findIndex((k) => k.toLowerCase() === b.name.toLowerCase());
+			return idxA - idxB;
+		});
+
+		const finalHeaders = [...unrecognized, ...recognized];
+		if (contentTypeHeader) finalHeaders.push(contentTypeHeader);
+
+		const headerStr = finalHeaders
+			.map((h) => {
+				const lowerName = h.name.toLowerCase();
+
+				// UPDATE THIS ARRAY BELOW
+				// Add "list-unsubscribe" and "list-unsubscribe-post" to this list
+				const doNotFold = [
+					"message-id",
+					"references",
+					"in-reply-to",
+					"content-id",
+					"list-unsubscribe", // <--- Added
+					"list-unsubscribe-post", // <--- Added
+				];
+
+				if (doNotFold.includes(lowerName)) {
+					return `${h.name}: ${h.value}`;
+				}
+				return this._foldHeader(h.name, h.value);
+			})
+			.join("\r\n");
+
+		return headerStr + body;
+	}
+
+	async asEncoded() {
+		const raw = await this.asRaw();
+		let encoded = Buffer.from(raw).toString("base64");
+		return encoded.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+	}
+
+	async addDKIM(options, dkimOptions = { chain: true }) {
+		const rawEmail = await this.asRaw();
+		if (Array.isArray(options)) {
+			if (dkimOptions.chain) {
+				let emailToSign = rawEmail;
+				for (const opt of options) {
+					emailToSign = DKIMSign(emailToSign, opt) + "\r\n" + emailToSign;
+				}
+				return emailToSign;
+			} else {
+				return options.map((opt) => DKIMSign(rawEmail, opt) + "\r\n").join("") + rawEmail;
+			}
+		} else {
+			return DKIMSign(rawEmail, options) + "\r\n" + rawEmail;
+		}
+	}
+}
+
+// 2. Add this line at the very bottom of the file
+export { MimeMessage };