@kumix/email 0.1.0

package/dist/helpers.js

@@ -0,0 +1,447 @@
+import React from "react";
+import { render } from "react-email";
+//#region src/helpers.ts
+/**
+* @fileoverview Email Helper Utilities
+*
+* This module provides utility functions for email operations including:
+* - Template rendering and text conversion
+* - Email address validation and formatting
+* - Content processing and sanitization
+* - Attachment handling
+* - Email list management
+*
+* Import from '@kumix/email/helpers' to access these utilities.
+*
+* @example
+* ```typescript
+* import {
+*   renderEmailTemplate,
+*   htmlToText,
+*   isValidEmail,
+*   formatEmailAddress,
+*   sanitizeHtml,
+*   generateUnsubscribeLink
+* } from '@kumix/email/helpers';
+* ```
+*/
+/**
+* Render React component to HTML string
+*
+* Converts a React email template component to HTML string that can be sent via email.
+*
+* @param Template - React component to render
+* @param props - Props to pass to the component
+* @returns Promise resolving to HTML string
+* @example
+* ```typescript
+* const WelcomeEmail = ({ name }: { name: string }) => <h1>Welcome {name}!</h1>;
+*
+* const html = await renderEmailTemplate(WelcomeEmail, { name: 'John' });
+* console.log(html); // "<h1>Welcome John!</h1>"
+* ```
+*/
+async function renderEmailTemplate(Template, props) {
+	return render(React.createElement(Template, props));
+}
+/**
+* Generate plain text from HTML
+*
+* Converts HTML content to plain text by removing tags and normalizing whitespace.
+* Useful for creating text versions of HTML emails.
+*
+* @param html - HTML string to convert
+* @returns Plain text version of the HTML
+* @example
+* ```typescript
+* const html = '<h1>Hello</h1><p>Welcome to our <strong>platform</strong>!</p>';
+* const text = htmlToText(html);
+* console.log(text); // "Hello Welcome to our platform!"
+* ```
+*/
+function htmlToText(html) {
+	return html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n\n").replace(/<\/h[1-6]>/gi, "\n\n").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").replace(/\n\s+/g, "\n").trim();
+}
+/**
+* Validate email address format
+*
+* Checks if an email address has a valid format using RFC 5322 compliant regex.
+*
+* @param email - Email address to validate
+* @returns true if email format is valid, false otherwise
+* @example
+* ```typescript
+* console.log(isValidEmail('user@example.com')); // true
+* console.log(isValidEmail('invalid-email')); // false
+* console.log(isValidEmail('user+tag@example.co.uk')); // true
+* ```
+*/
+function isValidEmail(email) {
+	return /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/.test(email);
+}
+/**
+* Validate multiple email addresses
+*
+* Validates an array of email addresses or a single email address.
+*
+* @param emails - Single email or array of emails to validate
+* @returns true if all emails are valid, false if any are invalid
+* @example
+* ```typescript
+* console.log(validateEmails('user@example.com')); // true
+* console.log(validateEmails(['user1@example.com', 'user2@example.com'])); // true
+* console.log(validateEmails(['valid@example.com', 'invalid-email'])); // false
+* ```
+*/
+function validateEmails(emails) {
+	return (Array.isArray(emails) ? emails : [emails]).every((email) => isValidEmail(email.trim()));
+}
+/**
+* Filter valid emails from a list
+*
+* Returns only the valid email addresses from a list, filtering out invalid ones.
+*
+* @param emails - Array of email addresses to filter
+* @returns Array containing only valid email addresses
+* @example
+* ```typescript
+* const emails = ['valid@example.com', 'invalid-email', 'another@example.com'];
+* const validEmails = filterValidEmails(emails);
+* console.log(validEmails); // ['valid@example.com', 'another@example.com']
+* ```
+*/
+function filterValidEmails(emails) {
+	return emails.filter((email) => isValidEmail(email.trim()));
+}
+/**
+* Format email address with display name
+*
+* Combines a display name with an email address in the standard format.
+*
+* @param name - Display name for the email address
+* @param email - Email address
+* @returns Formatted email address string
+* @example
+* ```typescript
+* const formatted = formatEmailAddress('John Doe', 'john@example.com');
+* console.log(formatted); // "John Doe <john@example.com>"
+* ```
+*/
+function formatEmailAddress(name, email) {
+	return `${name} <${email}>`;
+}
+/**
+* Extract email address from formatted string
+*
+* Extracts the email address from a formatted "Name <email>" string.
+*
+* @param formattedAddress - Formatted email address string
+* @returns Just the email address part
+* @example
+* ```typescript
+* const email = extractEmail('John Doe <john@example.com>');
+* console.log(email); // "john@example.com"
+*
+* const email2 = extractEmail('simple@example.com');
+* console.log(email2); // "simple@example.com"
+* ```
+*/
+function extractEmail(formattedAddress) {
+	const match = formattedAddress.match(/<([^>]*)>/);
+	return match ? match[1] : formattedAddress.trim();
+}
+/**
+* Extract display name from formatted email address
+*
+* Extracts the display name from a formatted "Name <email>" string.
+*
+* @param formattedAddress - Formatted email address string
+* @returns Display name or empty string if none found
+* @example
+* ```typescript
+* const name = extractDisplayName('John Doe <john@example.com>');
+* console.log(name); // "John Doe"
+*
+* const name2 = extractDisplayName('simple@example.com');
+* console.log(name2); // ""
+* ```
+*/
+function extractDisplayName(formattedAddress) {
+	const match = formattedAddress.match(/^(.+?)\s*<[^>]*>$/);
+	return match ? match[1].trim().replace(/^["']|["']$/g, "") : "";
+}
+/**
+* Sanitize HTML content for email
+*
+* Removes potentially dangerous HTML elements and attributes while preserving
+* email-safe formatting.
+*
+* @param html - HTML content to sanitize
+* @returns Sanitized HTML safe for email
+* @example
+* ```typescript
+* const unsafeHtml = '<script>alert("xss")<\/script><p>Safe content</p>';
+* const safeHtml = sanitizeHtml(unsafeHtml);
+* console.log(safeHtml); // "<p>Safe content</p>"
+* ```
+*/
+function sanitizeHtml(html) {
+	let sanitized = html.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "");
+	sanitized = sanitized.replace(/\s*on\w+\s*=\s*["'][^"']*["']/gi, "");
+	sanitized = sanitized.replace(/\s*javascript\s*:/gi, "");
+	sanitized = sanitized.replace(/\s*style\s*=\s*["'][^"']*expression\([^"']*\)["']/gi, "");
+	return sanitized;
+}
+/**
+* Truncate text with ellipsis
+*
+* Truncates text to a specified length and adds ellipsis if needed.
+*
+* @param text - Text to truncate
+* @param maxLength - Maximum length before truncation
+* @param ellipsis - String to append when truncated (default: '...')
+* @returns Truncated text
+* @example
+* ```typescript
+* const text = 'This is a very long email subject line';
+* const truncated = truncateText(text, 20);
+* console.log(truncated); // "This is a very long..."
+* ```
+*/
+function truncateText(text, maxLength, ellipsis = "...") {
+	if (text.length <= maxLength) return text;
+	return text.slice(0, maxLength - ellipsis.length) + ellipsis;
+}
+/**
+* Generate email preview text
+*
+* Creates a preview text from HTML content, suitable for email preview panes.
+*
+* @param html - HTML content to generate preview from
+* @param maxLength - Maximum length of preview text (default: 150)
+* @returns Preview text
+* @example
+* ```typescript
+* const html = '<h1>Welcome!</h1><p>Thank you for joining our platform.</p>';
+* const preview = generatePreviewText(html);
+* console.log(preview); // "Welcome! Thank you for joining our platform."
+* ```
+*/
+function generatePreviewText(html, maxLength = 150) {
+	return truncateText(htmlToText(html), maxLength);
+}
+/**
+* Generate unsubscribe link
+*
+* Creates an unsubscribe URL with proper parameters.
+*
+* @param baseUrl - Base URL for unsubscribe endpoint
+* @param email - Email address to unsubscribe
+* @param token - Optional security token
+* @returns Complete unsubscribe URL
+* @example
+* ```typescript
+* const link = generateUnsubscribeLink(
+*   'https://example.com/unsubscribe',
+*   'user@example.com',
+*   'secure-token-123'
+* );
+* console.log(link); // "https://example.com/unsubscribe?email=user%40example.com&token=secure-token-123"
+* ```
+*/
+function generateUnsubscribeLink(baseUrl, email, token) {
+	const url = new URL(baseUrl);
+	url.searchParams.set("email", email);
+	if (token) url.searchParams.set("token", token);
+	return url.toString();
+}
+/**
+* Generate tracking pixel URL
+*
+* Creates a tracking pixel URL for email open tracking.
+*
+* @param baseUrl - Base URL for tracking endpoint
+* @param emailId - Unique identifier for the email
+* @param recipientId - Unique identifier for the recipient
+* @returns Tracking pixel URL
+* @example
+* ```typescript
+* const pixelUrl = generateTrackingPixel(
+*   'https://example.com/track',
+*   'email-123',
+*   'user-456'
+* );
+* // Use in email: <img src="${pixelUrl}" width="1" height="1" />
+* ```
+*/
+function generateTrackingPixel(baseUrl, emailId, recipientId) {
+	const url = new URL(baseUrl);
+	url.searchParams.set("email_id", emailId);
+	url.searchParams.set("recipient_id", recipientId);
+	url.searchParams.set("t", Date.now().toString());
+	return url.toString();
+}
+/**
+* Add UTM parameters to URL
+*
+* Adds UTM tracking parameters to a URL for campaign tracking.
+*
+* @param url - Original URL
+* @param utmParams - UTM parameters object
+* @returns URL with UTM parameters added
+* @example
+* ```typescript
+* const trackedUrl = addUtmParams('https://example.com/product', {
+*   source: 'email',
+*   medium: 'newsletter',
+*   campaign: 'summer_sale',
+*   content: 'header_button'
+* });
+* ```
+*/
+function addUtmParams(url, utmParams) {
+	const urlObj = new URL(url);
+	if (utmParams.source) urlObj.searchParams.set("utm_source", utmParams.source);
+	if (utmParams.medium) urlObj.searchParams.set("utm_medium", utmParams.medium);
+	if (utmParams.campaign) urlObj.searchParams.set("utm_campaign", utmParams.campaign);
+	if (utmParams.term) urlObj.searchParams.set("utm_term", utmParams.term);
+	if (utmParams.content) urlObj.searchParams.set("utm_content", utmParams.content);
+	return urlObj.toString();
+}
+/**
+* Parse email list from string
+*
+* Parses a comma or semicolon separated string of email addresses.
+*
+* @param emailString - String containing multiple email addresses
+* @returns Array of trimmed email addresses
+* @example
+* ```typescript
+* const emails = parseEmailList('user1@example.com, user2@example.com; user3@example.com');
+* console.log(emails); // ['user1@example.com', 'user2@example.com', 'user3@example.com']
+* ```
+*/
+function parseEmailList(emailString) {
+	return emailString.split(/[,;]/).map((email) => email.trim()).filter((email) => email.length > 0);
+}
+/**
+* Deduplicate email list
+*
+* Removes duplicate email addresses from a list (case-insensitive).
+*
+* @param emails - Array of email addresses
+* @returns Array with duplicates removed
+* @example
+* ```typescript
+* const emails = ['user@example.com', 'USER@EXAMPLE.COM', 'other@example.com'];
+* const unique = deduplicateEmails(emails);
+* console.log(unique); // ['user@example.com', 'other@example.com']
+* ```
+*/
+function deduplicateEmails(emails) {
+	const seen = /* @__PURE__ */ new Set();
+	return emails.filter((email) => {
+		const normalized = email.toLowerCase().trim();
+		if (seen.has(normalized)) return false;
+		seen.add(normalized);
+		return true;
+	});
+}
+/**
+* Chunk email list for batch sending
+*
+* Splits a large email list into smaller chunks for batch processing.
+*
+* @param emails - Array of email addresses
+* @param chunkSize - Size of each chunk (default: 100)
+* @returns Array of email chunks
+* @example
+* ```typescript
+* const emails = ['user1@example.com', 'user2@example.com', ...]; // 250 emails
+* const chunks = chunkEmails(emails, 100);
+* console.log(chunks.length); // 3 chunks
+* console.log(chunks[0].length); // 100
+* console.log(chunks[2].length); // 50
+* ```
+*/
+function chunkEmails(emails, chunkSize = 100) {
+	const chunks = [];
+	for (let i = 0; i < emails.length; i += chunkSize) chunks.push(emails.slice(i, i + chunkSize));
+	return chunks;
+}
+/**
+* Get MIME type from file extension
+*
+* Returns the appropriate MIME type for common file extensions.
+*
+* @param filename - Filename or extension
+* @returns MIME type string
+* @example
+* ```typescript
+* console.log(getMimeType('document.pdf')); // 'application/pdf'
+* console.log(getMimeType('image.jpg')); // 'image/jpeg'
+* console.log(getMimeType('.png')); // 'image/png'
+* ```
+*/
+function getMimeType(filename) {
+	return {
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		png: "image/png",
+		gif: "image/gif",
+		webp: "image/webp",
+		svg: "image/svg+xml",
+		pdf: "application/pdf",
+		doc: "application/msword",
+		docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		xls: "application/vnd.ms-excel",
+		xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		ppt: "application/vnd.ms-powerpoint",
+		pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+		txt: "text/plain",
+		csv: "text/csv",
+		html: "text/html",
+		css: "text/css",
+		js: "text/javascript",
+		json: "application/json",
+		xml: "application/xml",
+		zip: "application/zip",
+		rar: "application/x-rar-compressed",
+		"7z": "application/x-7z-compressed",
+		tar: "application/x-tar",
+		gz: "application/gzip"
+	}[filename.toLowerCase().split(".").pop() || ""] || "application/octet-stream";
+}
+/**
+* Format file size for display
+*
+* Converts file size in bytes to human-readable format.
+*
+* @param bytes - File size in bytes
+* @param decimals - Number of decimal places (default: 2)
+* @returns Formatted file size string
+* @example
+* ```typescript
+* console.log(formatFileSize(1024)); // "1.00 KB"
+* console.log(formatFileSize(1048576)); // "1.00 MB"
+* console.log(formatFileSize(1073741824, 1)); // "1.0 GB"
+* ```
+*/
+function formatFileSize(bytes, decimals = 2) {
+	if (bytes === 0) return "0 Bytes";
+	const k = 1024;
+	const dm = decimals < 0 ? 0 : decimals;
+	const sizes = [
+		"Bytes",
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	const i = Math.floor(Math.log(bytes) / Math.log(k));
+	return `${(bytes / k ** i).toFixed(dm)} ${sizes[i]}`;
+}
+//#endregion
+export { addUtmParams, chunkEmails, deduplicateEmails, extractDisplayName, extractEmail, filterValidEmails, formatEmailAddress, formatFileSize, generatePreviewText, generateTrackingPixel, generateUnsubscribeLink, getMimeType, htmlToText, isValidEmail, parseEmailList, renderEmailTemplate, sanitizeHtml, truncateText, validateEmails };
+
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","names":[],"sources":["../src/helpers.ts"],"sourcesContent":["/**\n * @fileoverview Email Helper Utilities\n *\n * This module provides utility functions for email operations including:\n * - Template rendering and text conversion\n * - Email address validation and formatting\n * - Content processing and sanitization\n * - Attachment handling\n * - Email list management\n *\n * Import from '@kumix/email/helpers' to access these utilities.\n *\n * @example\n * ```typescript\n * import {\n *   renderEmailTemplate,\n *   htmlToText,\n *   isValidEmail,\n *   formatEmailAddress,\n *   sanitizeHtml,\n *   generateUnsubscribeLink\n * } from '@kumix/email/helpers';\n * ```\n */\n\nimport React from \"react\";\nimport { render } from \"react-email\";\n\n// =============================================================================\n// TEMPLATE RENDERING\n// =============================================================================\n\n/**\n * Render React component to HTML string\n *\n * Converts a React email template component to HTML string that can be sent via email.\n *\n * @param Template - React component to render\n * @param props - Props to pass to the component\n * @returns Promise resolving to HTML string\n * @example\n * ```typescript\n * const WelcomeEmail = ({ name }: { name: string }) => <h1>Welcome {name}!</h1>;\n *\n * const html = await renderEmailTemplate(WelcomeEmail, { name: 'John' });\n * console.log(html); // \"<h1>Welcome John!</h1>\"\n * ```\n */\nexport async function renderEmailTemplate<T extends Record<string, unknown>>(\n  Template: React.ComponentType<T>,\n  props: T,\n): Promise<string> {\n  return render(React.createElement(Template, props));\n}\n\n/**\n * Generate plain text from HTML\n *\n * Converts HTML content to plain text by removing tags and normalizing whitespace.\n * Useful for creating text versions of HTML emails.\n *\n * @param html - HTML string to convert\n * @returns Plain text version of the HTML\n * @example\n * ```typescript\n * const html = '<h1>Hello</h1><p>Welcome to our <strong>platform</strong>!</p>';\n * const text = htmlToText(html);\n * console.log(text); // \"Hello Welcome to our platform!\"\n * ```\n */\nexport function htmlToText(html: string): string {\n  return html\n    .replace(/<br\\s*\\/?>/gi, \"\\n\") // Convert <br> to newlines\n    .replace(/<\\/p>/gi, \"\\n\\n\") // Convert </p> to double newlines\n    .replace(/<\\/h[1-6]>/gi, \"\\n\\n\") // Convert heading endings to double newlines\n    .replace(/<[^>]*>/g, \" \") // Remove all other HTML tags\n    .replace(/\\s+/g, \" \") // Normalize whitespace\n    .replace(/\\n\\s+/g, \"\\n\") // Remove spaces after newlines\n    .trim();\n}\n\n// =============================================================================\n// EMAIL VALIDATION\n// =============================================================================\n\n/**\n * Validate email address format\n *\n * Checks if an email address has a valid format using RFC 5322 compliant regex.\n *\n * @param email - Email address to validate\n * @returns true if email format is valid, false otherwise\n * @example\n * ```typescript\n * console.log(isValidEmail('user@example.com')); // true\n * console.log(isValidEmail('invalid-email')); // false\n * console.log(isValidEmail('user+tag@example.co.uk')); // true\n * ```\n */\nexport function isValidEmail(email: string): boolean {\n  const emailRegex =\n    /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/;\n  return emailRegex.test(email);\n}\n\n/**\n * Validate multiple email addresses\n *\n * Validates an array of email addresses or a single email address.\n *\n * @param emails - Single email or array of emails to validate\n * @returns true if all emails are valid, false if any are invalid\n * @example\n * ```typescript\n * console.log(validateEmails('user@example.com')); // true\n * console.log(validateEmails(['user1@example.com', 'user2@example.com'])); // true\n * console.log(validateEmails(['valid@example.com', 'invalid-email'])); // false\n * ```\n */\nexport function validateEmails(emails: string | string[]): boolean {\n  const emailArray = Array.isArray(emails) ? emails : [emails];\n  return emailArray.every((email) => isValidEmail(email.trim()));\n}\n\n/**\n * Filter valid emails from a list\n *\n * Returns only the valid email addresses from a list, filtering out invalid ones.\n *\n * @param emails - Array of email addresses to filter\n * @returns Array containing only valid email addresses\n * @example\n * ```typescript\n * const emails = ['valid@example.com', 'invalid-email', 'another@example.com'];\n * const validEmails = filterValidEmails(emails);\n * console.log(validEmails); // ['valid@example.com', 'another@example.com']\n * ```\n */\nexport function filterValidEmails(emails: string[]): string[] {\n  return emails.filter((email) => isValidEmail(email.trim()));\n}\n\n// =============================================================================\n// EMAIL FORMATTING\n// =============================================================================\n\n/**\n * Format email address with display name\n *\n * Combines a display name with an email address in the standard format.\n *\n * @param name - Display name for the email address\n * @param email - Email address\n * @returns Formatted email address string\n * @example\n * ```typescript\n * const formatted = formatEmailAddress('John Doe', 'john@example.com');\n * console.log(formatted); // \"John Doe <john@example.com>\"\n * ```\n */\nexport function formatEmailAddress(name: string, email: string): string {\n  // Don't escape quotes - keep them as is for standard email format\n  return `${name} <${email}>`;\n}\n\n/**\n * Extract email address from formatted string\n *\n * Extracts the email address from a formatted \"Name <email>\" string.\n *\n * @param formattedAddress - Formatted email address string\n * @returns Just the email address part\n * @example\n * ```typescript\n * const email = extractEmail('John Doe <john@example.com>');\n * console.log(email); // \"john@example.com\"\n *\n * const email2 = extractEmail('simple@example.com');\n * console.log(email2); // \"simple@example.com\"\n * ```\n */\nexport function extractEmail(formattedAddress: string): string {\n  const match = formattedAddress.match(/<([^>]*)>/);\n  return match ? match[1] : formattedAddress.trim();\n}\n\n/**\n * Extract display name from formatted email address\n *\n * Extracts the display name from a formatted \"Name <email>\" string.\n *\n * @param formattedAddress - Formatted email address string\n * @returns Display name or empty string if none found\n * @example\n * ```typescript\n * const name = extractDisplayName('John Doe <john@example.com>');\n * console.log(name); // \"John Doe\"\n *\n * const name2 = extractDisplayName('simple@example.com');\n * console.log(name2); // \"\"\n * ```\n */\nexport function extractDisplayName(formattedAddress: string): string {\n  const match = formattedAddress.match(/^(.+?)\\s*<[^>]*>$/);\n  return match ? match[1].trim().replace(/^[\"']|[\"']$/g, \"\") : \"\";\n}\n\n// =============================================================================\n// CONTENT PROCESSING\n// =============================================================================\n\n/**\n * Sanitize HTML content for email\n *\n * Removes potentially dangerous HTML elements and attributes while preserving\n * email-safe formatting.\n *\n * @param html - HTML content to sanitize\n * @returns Sanitized HTML safe for email\n * @example\n * ```typescript\n * const unsafeHtml = '<script>alert(\"xss\")</script><p>Safe content</p>';\n * const safeHtml = sanitizeHtml(unsafeHtml);\n * console.log(safeHtml); // \"<p>Safe content</p>\"\n * ```\n */\nexport function sanitizeHtml(html: string): string {\n  // Remove script tags and their content\n  let sanitized = html.replace(/<script\\b[^<]*(?:(?!<\\/script>)<[^<]*)*<\\/script>/gi, \"\");\n\n  // Remove dangerous attributes\n  sanitized = sanitized.replace(/\\s*on\\w+\\s*=\\s*[\"'][^\"']*[\"']/gi, \"\"); // onclick, onload, etc.\n  sanitized = sanitized.replace(/\\s*javascript\\s*:/gi, \"\"); // javascript: urls\n\n  // Remove style attributes that could be dangerous\n  sanitized = sanitized.replace(/\\s*style\\s*=\\s*[\"'][^\"']*expression\\([^\"']*\\)[\"']/gi, \"\");\n\n  return sanitized;\n}\n\n/**\n * Truncate text with ellipsis\n *\n * Truncates text to a specified length and adds ellipsis if needed.\n *\n * @param text - Text to truncate\n * @param maxLength - Maximum length before truncation\n * @param ellipsis - String to append when truncated (default: '...')\n * @returns Truncated text\n * @example\n * ```typescript\n * const text = 'This is a very long email subject line';\n * const truncated = truncateText(text, 20);\n * console.log(truncated); // \"This is a very long...\"\n * ```\n */\nexport function truncateText(text: string, maxLength: number, ellipsis: string = \"...\"): string {\n  if (text.length <= maxLength) return text;\n  return text.slice(0, maxLength - ellipsis.length) + ellipsis;\n}\n\n/**\n * Generate email preview text\n *\n * Creates a preview text from HTML content, suitable for email preview panes.\n *\n * @param html - HTML content to generate preview from\n * @param maxLength - Maximum length of preview text (default: 150)\n * @returns Preview text\n * @example\n * ```typescript\n * const html = '<h1>Welcome!</h1><p>Thank you for joining our platform.</p>';\n * const preview = generatePreviewText(html);\n * console.log(preview); // \"Welcome! Thank you for joining our platform.\"\n * ```\n */\nexport function generatePreviewText(html: string, maxLength: number = 150): string {\n  const text = htmlToText(html);\n  return truncateText(text, maxLength);\n}\n\n// =============================================================================\n// URL AND LINK UTILITIES\n// =============================================================================\n\n/**\n * Generate unsubscribe link\n *\n * Creates an unsubscribe URL with proper parameters.\n *\n * @param baseUrl - Base URL for unsubscribe endpoint\n * @param email - Email address to unsubscribe\n * @param token - Optional security token\n * @returns Complete unsubscribe URL\n * @example\n * ```typescript\n * const link = generateUnsubscribeLink(\n *   'https://example.com/unsubscribe',\n *   'user@example.com',\n *   'secure-token-123'\n * );\n * console.log(link); // \"https://example.com/unsubscribe?email=user%40example.com&token=secure-token-123\"\n * ```\n */\nexport function generateUnsubscribeLink(baseUrl: string, email: string, token?: string): string {\n  const url = new URL(baseUrl);\n  url.searchParams.set(\"email\", email);\n  if (token) {\n    url.searchParams.set(\"token\", token);\n  }\n  return url.toString();\n}\n\n/**\n * Generate tracking pixel URL\n *\n * Creates a tracking pixel URL for email open tracking.\n *\n * @param baseUrl - Base URL for tracking endpoint\n * @param emailId - Unique identifier for the email\n * @param recipientId - Unique identifier for the recipient\n * @returns Tracking pixel URL\n * @example\n * ```typescript\n * const pixelUrl = generateTrackingPixel(\n *   'https://example.com/track',\n *   'email-123',\n *   'user-456'\n * );\n * // Use in email: <img src=\"${pixelUrl}\" width=\"1\" height=\"1\" />\n * ```\n */\nexport function generateTrackingPixel(\n  baseUrl: string,\n  emailId: string,\n  recipientId: string,\n): string {\n  const url = new URL(baseUrl);\n  url.searchParams.set(\"email_id\", emailId);\n  url.searchParams.set(\"recipient_id\", recipientId);\n  url.searchParams.set(\"t\", Date.now().toString());\n  return url.toString();\n}\n\n/**\n * Add UTM parameters to URL\n *\n * Adds UTM tracking parameters to a URL for campaign tracking.\n *\n * @param url - Original URL\n * @param utmParams - UTM parameters object\n * @returns URL with UTM parameters added\n * @example\n * ```typescript\n * const trackedUrl = addUtmParams('https://example.com/product', {\n *   source: 'email',\n *   medium: 'newsletter',\n *   campaign: 'summer_sale',\n *   content: 'header_button'\n * });\n * ```\n */\nexport function addUtmParams(\n  url: string,\n  utmParams: {\n    source?: string;\n    medium?: string;\n    campaign?: string;\n    term?: string;\n    content?: string;\n  },\n): string {\n  const urlObj = new URL(url);\n\n  if (utmParams.source) urlObj.searchParams.set(\"utm_source\", utmParams.source);\n  if (utmParams.medium) urlObj.searchParams.set(\"utm_medium\", utmParams.medium);\n  if (utmParams.campaign) urlObj.searchParams.set(\"utm_campaign\", utmParams.campaign);\n  if (utmParams.term) urlObj.searchParams.set(\"utm_term\", utmParams.term);\n  if (utmParams.content) urlObj.searchParams.set(\"utm_content\", utmParams.content);\n\n  return urlObj.toString();\n}\n\n// =============================================================================\n// EMAIL LIST UTILITIES\n// =============================================================================\n\n/**\n * Parse email list from string\n *\n * Parses a comma or semicolon separated string of email addresses.\n *\n * @param emailString - String containing multiple email addresses\n * @returns Array of trimmed email addresses\n * @example\n * ```typescript\n * const emails = parseEmailList('user1@example.com, user2@example.com; user3@example.com');\n * console.log(emails); // ['user1@example.com', 'user2@example.com', 'user3@example.com']\n * ```\n */\nexport function parseEmailList(emailString: string): string[] {\n  return emailString\n    .split(/[,;]/)\n    .map((email) => email.trim())\n    .filter((email) => email.length > 0);\n}\n\n/**\n * Deduplicate email list\n *\n * Removes duplicate email addresses from a list (case-insensitive).\n *\n * @param emails - Array of email addresses\n * @returns Array with duplicates removed\n * @example\n * ```typescript\n * const emails = ['user@example.com', 'USER@EXAMPLE.COM', 'other@example.com'];\n * const unique = deduplicateEmails(emails);\n * console.log(unique); // ['user@example.com', 'other@example.com']\n * ```\n */\nexport function deduplicateEmails(emails: string[]): string[] {\n  const seen = new Set<string>();\n  return emails.filter((email) => {\n    const normalized = email.toLowerCase().trim();\n    if (seen.has(normalized)) {\n      return false;\n    }\n    seen.add(normalized);\n    return true;\n  });\n}\n\n/**\n * Chunk email list for batch sending\n *\n * Splits a large email list into smaller chunks for batch processing.\n *\n * @param emails - Array of email addresses\n * @param chunkSize - Size of each chunk (default: 100)\n * @returns Array of email chunks\n * @example\n * ```typescript\n * const emails = ['user1@example.com', 'user2@example.com', ...]; // 250 emails\n * const chunks = chunkEmails(emails, 100);\n * console.log(chunks.length); // 3 chunks\n * console.log(chunks[0].length); // 100\n * console.log(chunks[2].length); // 50\n * ```\n */\nexport function chunkEmails(emails: string[], chunkSize: number = 100): string[][] {\n  const chunks: string[][] = [];\n  for (let i = 0; i < emails.length; i += chunkSize) {\n    chunks.push(emails.slice(i, i + chunkSize));\n  }\n  return chunks;\n}\n\n// =============================================================================\n// ATTACHMENT UTILITIES\n// =============================================================================\n\n/**\n * Get MIME type from file extension\n *\n * Returns the appropriate MIME type for common file extensions.\n *\n * @param filename - Filename or extension\n * @returns MIME type string\n * @example\n * ```typescript\n * console.log(getMimeType('document.pdf')); // 'application/pdf'\n * console.log(getMimeType('image.jpg')); // 'image/jpeg'\n * console.log(getMimeType('.png')); // 'image/png'\n * ```\n */\nexport function getMimeType(filename: string): string {\n  const ext = filename.toLowerCase().split(\".\").pop() || \"\";\n\n  const mimeTypes: Record<string, string> = {\n    // Images\n    jpg: \"image/jpeg\",\n    jpeg: \"image/jpeg\",\n    png: \"image/png\",\n    gif: \"image/gif\",\n    webp: \"image/webp\",\n    svg: \"image/svg+xml\",\n\n    // Documents\n    pdf: \"application/pdf\",\n    doc: \"application/msword\",\n    docx: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    xls: \"application/vnd.ms-excel\",\n    xlsx: \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n    ppt: \"application/vnd.ms-powerpoint\",\n    pptx: \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n\n    // Text\n    txt: \"text/plain\",\n    csv: \"text/csv\",\n    html: \"text/html\",\n    css: \"text/css\",\n    js: \"text/javascript\",\n    json: \"application/json\",\n    xml: \"application/xml\",\n\n    // Archives\n    zip: \"application/zip\",\n    rar: \"application/x-rar-compressed\",\n    \"7z\": \"application/x-7z-compressed\",\n    tar: \"application/x-tar\",\n    gz: \"application/gzip\",\n  };\n\n  return mimeTypes[ext] || \"application/octet-stream\";\n}\n\n/**\n * Format file size for display\n *\n * Converts file size in bytes to human-readable format.\n *\n * @param bytes - File size in bytes\n * @param decimals - Number of decimal places (default: 2)\n * @returns Formatted file size string\n * @example\n * ```typescript\n * console.log(formatFileSize(1024)); // \"1.00 KB\"\n * console.log(formatFileSize(1048576)); // \"1.00 MB\"\n * console.log(formatFileSize(1073741824, 1)); // \"1.0 GB\"\n * ```\n */\nexport function formatFileSize(bytes: number, decimals: number = 2): string {\n  if (bytes === 0) return \"0 Bytes\";\n\n  const k = 1024;\n  const dm = decimals < 0 ? 0 : decimals;\n  const sizes = [\"Bytes\", \"KB\", \"MB\", \"GB\", \"TB\"];\n\n  const i = Math.floor(Math.log(bytes) / Math.log(k));\n\n  return `${(bytes / k ** i).toFixed(dm)} ${sizes[i]}`;\n}\n"],"mappings":"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"}