@growth-labs/mailer 0.1.3

package/src/utils/templates.ts

@@ -0,0 +1,459 @@
+import type { DigestItem, TemplateData, TemplateName } from '../types.js'
+
+// ─── Inline style map (~40 utility classes → CSS) ───
+
+const INLINE_STYLES: Record<string, string> = {
+	'text-center': 'text-align: center;',
+	'text-left': 'text-align: left;',
+	'text-right': 'text-align: right;',
+	'font-bold': 'font-weight: 700;',
+	'font-normal': 'font-weight: 400;',
+	'text-sm': 'font-size: 14px; line-height: 20px;',
+	'text-base': 'font-size: 16px; line-height: 24px;',
+	'text-lg': 'font-size: 18px; line-height: 28px;',
+	'text-xl': 'font-size: 20px; line-height: 28px;',
+	'text-2xl': 'font-size: 24px; line-height: 32px;',
+	'text-3xl': 'font-size: 30px; line-height: 36px;',
+	'p-2': 'padding: 8px;',
+	'p-3': 'padding: 12px;',
+	'p-4': 'padding: 16px;',
+	'p-6': 'padding: 24px;',
+	'p-8': 'padding: 32px;',
+	'px-2': 'padding-left: 8px; padding-right: 8px;',
+	'px-3': 'padding-left: 12px; padding-right: 12px;',
+	'px-4': 'padding-left: 16px; padding-right: 16px;',
+	'px-6': 'padding-left: 24px; padding-right: 24px;',
+	'px-8': 'padding-left: 32px; padding-right: 32px;',
+	'py-2': 'padding-top: 8px; padding-bottom: 8px;',
+	'py-3': 'padding-top: 12px; padding-bottom: 12px;',
+	'py-4': 'padding-top: 16px; padding-bottom: 16px;',
+	'py-6': 'padding-top: 24px; padding-bottom: 24px;',
+	'py-8': 'padding-top: 32px; padding-bottom: 32px;',
+	'm-0': 'margin: 0;',
+	'm-2': 'margin: 8px;',
+	'm-3': 'margin: 12px;',
+	'm-4': 'margin: 16px;',
+	'mx-auto': 'margin-left: auto; margin-right: auto;',
+	'my-2': 'margin-top: 8px; margin-bottom: 8px;',
+	'my-3': 'margin-top: 12px; margin-bottom: 12px;',
+	'my-4': 'margin-top: 16px; margin-bottom: 16px;',
+	'w-full': 'width: 100%;',
+	'max-w-xl': 'max-width: 576px;',
+	'max-w-2xl': 'max-width: 672px;',
+	rounded: 'border-radius: 4px;',
+	'rounded-lg': 'border-radius: 8px;',
+	border: 'border: 1px solid #e5e7eb;',
+	block: 'display: block;',
+	'inline-block': 'display: inline-block;',
+	hidden: 'display: none;',
+	'leading-relaxed': 'line-height: 1.625;',
+}
+
+// ─── Helpers ───
+
+function escapeHtml(str: string): string {
+	return str
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+}
+
+function resolveValue(data: Record<string, unknown>, path: string): unknown {
+	return path.split('.').reduce<unknown>((obj, key) => {
+		if (obj !== null && obj !== undefined && typeof obj === 'object') {
+			return (obj as Record<string, unknown>)[key]
+		}
+		return undefined
+	}, data)
+}
+
+// ─── Conditional block processing ───
+
+/**
+ * Process {{#key}}...{{/key}} conditional blocks.
+ * If the resolved value is truthy the inner content is kept;
+ * otherwise the entire block (including delimiters) is removed.
+ * Supports nested dot paths like {{#brand.logoUrl}}...{{/brand.logoUrl}}.
+ */
+export function processConditionals(template: string, data: Record<string, unknown>): string {
+	return template.replace(
+		/\{\{#([^}]+)\}\}([\s\S]*?)\{\{\/\1\}\}/g,
+		(_, key: string, content: string) => {
+			const value = resolveValue(data, key.trim())
+			return value ? content : ''
+		},
+	)
+}
+
+// ─── Template interpolation ───
+
+export function interpolate(template: string, data: Record<string, unknown>): string {
+	// Conditional blocks first
+	let result = processConditionals(template, data)
+
+	// Triple-brace: raw unescaped output
+	result = result.replace(/\{\{\{([^}]+)\}\}\}/g, (_, key: string) => {
+		const value = resolveValue(data, key.trim())
+		return value !== undefined && value !== null ? String(value) : ''
+	})
+
+	// Double-brace: HTML-escaped output
+	result = result.replace(/\{\{([^}]+)\}\}/g, (_, key: string) => {
+		const value = resolveValue(data, key.trim())
+		return value !== undefined && value !== null ? escapeHtml(String(value)) : ''
+	})
+
+	return result
+}
+
+// ─── Style inlining ───
+
+export function inlineStyles(
+	html: string,
+	brand?: { primaryColor: string; accentColor: string },
+): string {
+	return html.replace(/class="([^"]*)"/g, (_, classAttr: string) => {
+		const classes = classAttr.split(/\s+/).filter(Boolean)
+		const styles: string[] = []
+
+		for (const cls of classes) {
+			if (INLINE_STYLES[cls]) {
+				styles.push(INLINE_STYLES[cls])
+			} else if (brand) {
+				if (cls === 'text-primary') {
+					styles.push(`color: ${brand.primaryColor};`)
+				} else if (cls === 'text-accent') {
+					styles.push(`color: ${brand.accentColor};`)
+				} else if (cls === 'bg-primary') {
+					styles.push(`background-color: ${brand.primaryColor};`)
+				} else if (cls === 'bg-accent') {
+					styles.push(`background-color: ${brand.accentColor};`)
+				}
+				// Unrecognized classes without brand match are dropped silently
+			}
+			// Unrecognized classes are dropped silently
+		}
+
+		if (styles.length === 0) return ''
+		return `style="${styles.join(' ')}"`
+	})
+}
+
+// ─── Digest item renderer ───
+
+export function renderDigestItems(items: DigestItem[]): string {
+	return items
+		.map((item) => {
+			const thumbnail = item.imageUrl
+				? `<td style="width: 120px; padding-right: 16px; vertical-align: top;"><a href="${item.url}"><img src="${item.imageUrl}" alt="" width="120" style="display: block; border-radius: 4px; width: 120px;" /></a></td>`
+				: ''
+
+			const meta: string[] = []
+			if (item.author) meta.push(item.author)
+			if (item.publishedAt) meta.push(item.publishedAt)
+			const metaLine =
+				meta.length > 0
+					? `<p style="font-size: 12px; line-height: 16px; color: #6b7280; margin: 4px 0 0 0;">${escapeHtml(meta.join(' &middot; '))}</p>`
+					: ''
+
+			const description = item.description
+				? `<p style="font-size: 14px; line-height: 20px; color: #374151; margin: 4px 0 0 0;">${escapeHtml(item.description)}</p>`
+				: ''
+
+			return `<table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin-bottom: 24px;"><tr>${thumbnail}<td style="vertical-align: top;"><a href="${item.url}" style="font-size: 16px; line-height: 24px; color: #111827; font-weight: 700; text-decoration: none;">${escapeHtml(item.title)}</a>${description}${metaLine}</td></tr></table>`
+		})
+		.join('\n')
+}
+
+// ─── Built-in templates ───
+
+const BUILT_IN_TEMPLATES: Record<TemplateName, string> = {
+	confirmation: [
+		'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"',
+		' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+		'<html xmlns="http://www.w3.org/1999/xhtml">',
+		'<head>',
+		'<meta charset="utf-8" />',
+		'<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+		'<title>Confirm your {{senderName}} subscription</title>',
+		'</head>',
+		'<body style="margin: 0; padding: 0;">',
+		'<table width="100%" cellpadding="0" cellspacing="0" border="0"',
+		' class="w-full" style="background-color: #f4f4f5;">',
+		'<tr><td class="text-center p-4">',
+		'<table cellpadding="0" cellspacing="0" border="0"',
+		' class="mx-auto" style="max-width: 600px; width: 100%;">',
+		// Header
+		'<tr><td class="bg-primary p-6 text-center rounded-lg"' +
+			' style="border-radius: 8px 8px 0 0;">',
+		'{{#brand.logoUrl}}<img src="{{brand.logoUrl}}" alt="{{senderName}}"' +
+			' style="max-height: 48px; margin-bottom: 8px;" />{{/brand.logoUrl}}',
+		'<p class="text-xl font-bold"' + ' style="color: #ffffff; margin: 0;">{{senderName}}</p>',
+		'</td></tr>',
+		// Body
+		'<tr><td style="background-color: #ffffff; padding: 32px 24px;">',
+		'<h1 class="text-2xl font-bold"' + ' style="margin: 0 0 16px 0; color: #111827;">',
+		'Confirm your subscription</h1>',
+		'<p class="text-base leading-relaxed"' + ' style="margin: 0 0 24px 0; color: #374151;">',
+		'Thanks for subscribing! Please confirm your email address',
+		' by clicking the button below.</p>',
+		'<table cellpadding="0" cellspacing="0" border="0"><tr>',
+		'<td class="bg-primary rounded text-center"' + ' style="padding: 12px 24px;">',
+		'<a href="{{confirmUrl}}" style="color: #ffffff;' +
+			' text-decoration: none; font-weight: 700;' +
+			' font-size: 16px;">Confirm Subscription</a>',
+		'</td></tr></table>',
+		'<p class="text-sm"' + ' style="margin: 24px 0 0 0; color: #6b7280;">',
+		"If you didn't subscribe to {{senderName}},",
+		' you can safely ignore this email.</p>',
+		'</td></tr>',
+		// Footer
+		'<tr><td class="text-center p-4">',
+		'{{#brand.footerText}}<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{brand.footerText}}</p>{{/brand.footerText}}',
+		'<p class="text-sm" style="color: #9ca3af; margin: 0;">',
+		'{{senderName}}</p>',
+		'</td></tr>',
+		'</table>',
+		'</td></tr></table>',
+		'</body></html>',
+	].join('\n'),
+
+	welcome: [
+		'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"',
+		' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+		'<html xmlns="http://www.w3.org/1999/xhtml">',
+		'<head>',
+		'<meta charset="utf-8" />',
+		'<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+		'<title>Welcome to {{senderName}}</title>',
+		'</head>',
+		'<body style="margin: 0; padding: 0;">',
+		'<table width="100%" cellpadding="0" cellspacing="0" border="0"',
+		' class="w-full" style="background-color: #f4f4f5;">',
+		'<tr><td class="text-center p-4">',
+		'<table cellpadding="0" cellspacing="0" border="0"',
+		' class="mx-auto" style="max-width: 600px; width: 100%;">',
+		// Header
+		'<tr><td class="bg-primary p-6 text-center"' + ' style="border-radius: 8px 8px 0 0;">',
+		'{{#brand.logoUrl}}<img src="{{brand.logoUrl}}" alt="{{senderName}}"' +
+			' style="max-height: 48px; margin-bottom: 8px;" />{{/brand.logoUrl}}',
+		'<p class="text-xl font-bold"' + ' style="color: #ffffff; margin: 0;">{{senderName}}</p>',
+		'</td></tr>',
+		// Body
+		'<tr><td style="background-color: #ffffff; padding: 32px 24px;">',
+		'<h1 class="text-2xl font-bold"' + ' style="margin: 0 0 16px 0; color: #111827;">',
+		"You're confirmed!</h1>",
+		'<p class="text-base leading-relaxed"' + ' style="margin: 0 0 24px 0; color: #374151;">',
+		'{{{welcomeMessage}}}</p>',
+		'<table cellpadding="0" cellspacing="0" border="0"><tr>',
+		'<td class="bg-primary rounded text-center"' + ' style="padding: 12px 24px;">',
+		'<a href="{{siteUrl}}" style="color: #ffffff;' +
+			' text-decoration: none; font-weight: 700;' +
+			' font-size: 16px;">Visit {{senderName}}</a>',
+		'</td></tr></table>',
+		'</td></tr>',
+		// Footer
+		'<tr><td class="text-center p-4">',
+		'{{#brand.footerText}}<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{brand.footerText}}</p>{{/brand.footerText}}',
+		'<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{senderName}}</p>',
+		'{{#unsubscribeUrl}}<p class="text-sm" style="color: #9ca3af; margin: 0;">',
+		'<a href="{{unsubscribeUrl}}"' + ' style="color: #9ca3af;">Unsubscribe</a>',
+		' &middot; ',
+		'<a href="{{preferencesUrl}}"' + ' style="color: #9ca3af;">Preferences</a>',
+		'</p>{{/unsubscribeUrl}}',
+		'</td></tr>',
+		'</table>',
+		'</td></tr></table>',
+		'</body></html>',
+	].join('\n'),
+
+	campaign: [
+		'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"',
+		' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+		'<html xmlns="http://www.w3.org/1999/xhtml">',
+		'<head>',
+		'<meta charset="utf-8" />',
+		'<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+		'<title>{{subject}}</title>',
+		'</head>',
+		'<body style="margin: 0; padding: 0;">',
+		'<table width="100%" cellpadding="0" cellspacing="0" border="0"',
+		' class="w-full" style="background-color: #f4f4f5;">',
+		'<tr><td class="text-center p-4">',
+		'<table cellpadding="0" cellspacing="0" border="0"',
+		' class="mx-auto" style="max-width: 600px; width: 100%;">',
+		// Header
+		'<tr><td class="bg-primary p-6 text-center"' + ' style="border-radius: 8px 8px 0 0;">',
+		'{{#brand.logoUrl}}<img src="{{brand.logoUrl}}" alt="{{senderName}}"' +
+			' style="max-height: 48px; margin-bottom: 8px;" />{{/brand.logoUrl}}',
+		'<p class="text-xl font-bold"' + ' style="color: #ffffff; margin: 0;">{{senderName}}</p>',
+		'</td></tr>',
+		// Body
+		'<tr><td style="background-color: #ffffff; padding: 32px 24px;">',
+		'{{{content}}}',
+		'</td></tr>',
+		// Footer
+		'<tr><td class="text-center p-4">',
+		'{{#brand.footerText}}<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{brand.footerText}}</p>{{/brand.footerText}}',
+		'<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{senderName}}</p>',
+		'{{#unsubscribeUrl}}<p class="text-sm" style="color: #9ca3af; margin: 0;">',
+		'<a href="{{unsubscribeUrl}}"' + ' style="color: #9ca3af;">Unsubscribe</a>',
+		' &middot; ',
+		'<a href="{{preferencesUrl}}"' + ' style="color: #9ca3af;">Preferences</a>',
+		'</p>{{/unsubscribeUrl}}',
+		'</td></tr>',
+		'</table>',
+		'</td></tr></table>',
+		'{{#trackingPixelUrl}}<img src="{{trackingPixelUrl}}" width="1" height="1" alt=""' +
+			' style="display:block;width:1px;height:1px;border:0;" />{{/trackingPixelUrl}}',
+		'</body></html>',
+	].join('\n'),
+
+	digest: [
+		'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"',
+		' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+		'<html xmlns="http://www.w3.org/1999/xhtml">',
+		'<head>',
+		'<meta charset="utf-8" />',
+		'<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+		'<title>{{subject}}</title>',
+		'</head>',
+		'<body style="margin: 0; padding: 0;">',
+		'<table width="100%" cellpadding="0" cellspacing="0" border="0"',
+		' class="w-full" style="background-color: #f4f4f5;">',
+		'<tr><td class="text-center p-4">',
+		'<table cellpadding="0" cellspacing="0" border="0"',
+		' class="mx-auto" style="max-width: 600px; width: 100%;">',
+		// Header
+		'<tr><td class="bg-primary p-6 text-center"' + ' style="border-radius: 8px 8px 0 0;">',
+		'{{#brand.logoUrl}}<img src="{{brand.logoUrl}}" alt="{{senderName}}"' +
+			' style="max-height: 48px; margin-bottom: 8px;" />{{/brand.logoUrl}}',
+		'<p class="text-xl font-bold"' + ' style="color: #ffffff; margin: 0;">{{senderName}}</p>',
+		'</td></tr>',
+		// Body
+		'<tr><td style="background-color: #ffffff; padding: 32px 24px;">',
+		'{{#introText}}<p class="text-base leading-relaxed" style="margin: 0 0 24px 0; color: #374151;">',
+		'{{{introText}}}</p>{{/introText}}',
+		'{{{digestItems}}}',
+		'</td></tr>',
+		// Footer
+		'<tr><td class="text-center p-4">',
+		'{{#brand.footerText}}<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{brand.footerText}}</p>{{/brand.footerText}}',
+		'<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{senderName}}</p>',
+		'{{#unsubscribeUrl}}<p class="text-sm" style="color: #9ca3af; margin: 0;">',
+		'<a href="{{unsubscribeUrl}}"' + ' style="color: #9ca3af;">Unsubscribe</a>',
+		' &middot; ',
+		'<a href="{{preferencesUrl}}"' + ' style="color: #9ca3af;">Preferences</a>',
+		'</p>{{/unsubscribeUrl}}',
+		'</td></tr>',
+		'</table>',
+		'</td></tr></table>',
+		'{{#trackingPixelUrl}}<img src="{{trackingPixelUrl}}" width="1" height="1" alt=""' +
+			' style="display:block;width:1px;height:1px;border:0;" />{{/trackingPixelUrl}}',
+		'</body></html>',
+	].join('\n'),
+
+	transactional: [
+		'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"',
+		' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+		'<html xmlns="http://www.w3.org/1999/xhtml">',
+		'<head>',
+		'<meta charset="utf-8" />',
+		'<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+		'<title>{{subject}}</title>',
+		'</head>',
+		'<body style="margin: 0; padding: 0;">',
+		'<table width="100%" cellpadding="0" cellspacing="0" border="0"',
+		' class="w-full" style="background-color: #f4f4f5;">',
+		'<tr><td class="text-center p-4">',
+		'<table cellpadding="0" cellspacing="0" border="0"',
+		' class="mx-auto" style="max-width: 600px; width: 100%;">',
+		// Header — minimal, text only
+		'<tr><td class="p-4 text-center">',
+		'<p class="text-lg font-bold"' + ' style="color: #374151; margin: 0;">{{senderName}}</p>',
+		'</td></tr>',
+		// Body
+		'<tr><td style="background-color: #ffffff; padding: 32px 24px;">',
+		'{{{content}}}',
+		'</td></tr>',
+		// Footer — minimal, no unsubscribe
+		'<tr><td class="text-center p-4">',
+		'<p class="text-sm" style="color: #9ca3af; margin: 0;">',
+		'{{senderName}}</p>',
+		'</td></tr>',
+		'</table>',
+		'</td></tr></table>',
+		'</body></html>',
+	].join('\n'),
+
+	'unsubscribe-confirm': [
+		'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"',
+		' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+		'<html xmlns="http://www.w3.org/1999/xhtml">',
+		'<head>',
+		'<meta charset="utf-8" />',
+		'<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+		'<title>Unsubscribed from {{senderName}}</title>',
+		'</head>',
+		'<body style="margin: 0; padding: 0;">',
+		'<table width="100%" cellpadding="0" cellspacing="0" border="0"',
+		' class="w-full" style="background-color: #f4f4f5;">',
+		'<tr><td class="text-center p-4">',
+		'<table cellpadding="0" cellspacing="0" border="0"',
+		' class="mx-auto" style="max-width: 600px; width: 100%;">',
+		// Header
+		'<tr><td class="bg-primary p-6 text-center"' + ' style="border-radius: 8px 8px 0 0;">',
+		'{{#brand.logoUrl}}<img src="{{brand.logoUrl}}" alt="{{senderName}}"' +
+			' style="max-height: 48px; margin-bottom: 8px;" />{{/brand.logoUrl}}',
+		'<p class="text-xl font-bold"' + ' style="color: #ffffff; margin: 0;">{{senderName}}</p>',
+		'</td></tr>',
+		// Body
+		'<tr><td style="background-color: #ffffff; padding: 32px 24px;">',
+		'<h1 class="text-2xl font-bold"' + ' style="margin: 0 0 16px 0; color: #111827;">',
+		"You've been unsubscribed</h1>",
+		'<p class="text-base leading-relaxed"' + ' style="margin: 0 0 24px 0; color: #374151;">',
+		"You won't receive any more emails from {{senderName}}.</p>",
+		'<table cellpadding="0" cellspacing="0" border="0"><tr>',
+		'<td class="bg-primary rounded text-center"' + ' style="padding: 12px 24px;">',
+		'<a href="{{resubscribeUrl}}" style="color: #ffffff;' +
+			' text-decoration: none; font-weight: 700;' +
+			' font-size: 16px;">Re-subscribe</a>',
+		'</td></tr></table>',
+		'</td></tr>',
+		// Footer
+		'<tr><td class="text-center p-4">',
+		'{{#brand.footerText}}<p class="text-sm" style="color: #9ca3af; margin: 0 0 8px 0;">',
+		'{{brand.footerText}}</p>{{/brand.footerText}}',
+		'<p class="text-sm" style="color: #9ca3af; margin: 0;">',
+		'{{senderName}}</p>',
+		'</td></tr>',
+		'</table>',
+		'</td></tr></table>',
+		'</body></html>',
+	].join('\n'),
+}
+
+// ─── Main render function ───
+
+export function renderEmail(template: string | TemplateName, data: TemplateData): string {
+	const templateStr =
+		template in BUILT_IN_TEMPLATES ? BUILT_IN_TEMPLATES[template as TemplateName] : template
+
+	// Provide default welcome message if not supplied
+	const templateData = { ...data } as Record<string, unknown>
+	if (template === 'welcome' && !templateData.welcomeMessage) {
+		templateData.welcomeMessage = `Welcome to ${data.senderName}! You're now subscribed and will receive our latest updates directly in your inbox.`
+	}
+
+	const interpolated = interpolate(templateStr, templateData)
+	return inlineStyles(interpolated, data.brand)
+}

package/src/utils/tokens.ts

@@ -0,0 +1,91 @@
+const encoder = new TextEncoder()
+
+function toBase64Url(buffer: ArrayBuffer | Uint8Array): string {
+	const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer)
+	return btoa(String.fromCharCode(...bytes))
+		.replace(/\+/g, '-')
+		.replace(/\//g, '_')
+		.replace(/=+$/, '')
+}
+
+function fromBase64Url(str: string): Uint8Array {
+	const padded = str.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (str.length % 4)) % 4)
+	const binary = atob(padded)
+	const bytes = new Uint8Array(binary.length)
+	for (let i = 0; i < binary.length; i++) {
+		bytes[i] = binary.charCodeAt(i)
+	}
+	return bytes
+}
+
+async function importKey(secret: string): Promise<CryptoKey> {
+	return crypto.subtle.importKey(
+		'raw',
+		encoder.encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign', 'verify'],
+	)
+}
+
+async function hmacSign(secret: string, data: string): Promise<string> {
+	const key = await importKey(secret)
+	const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data))
+	return toBase64Url(signature)
+}
+
+async function hmacVerify(secret: string, data: string, signature: string): Promise<boolean> {
+	const key = await importKey(secret)
+	const sigBytes = fromBase64Url(signature)
+	return crypto.subtle.verify('HMAC', key, sigBytes.buffer as ArrayBuffer, encoder.encode(data))
+}
+
+interface TokenPayload {
+	subscriberId: string
+	action: 'confirm' | 'unsubscribe' | 'preferences'
+	exp?: number
+}
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000
+
+export async function generateToken(secret: string, payload: TokenPayload): Promise<string> {
+	const finalPayload = { ...payload }
+
+	if (finalPayload.action === 'confirm' && finalPayload.exp === undefined) {
+		finalPayload.exp = Date.now() + SEVEN_DAYS_MS
+	}
+
+	const payloadB64 = toBase64Url(encoder.encode(JSON.stringify(finalPayload)))
+	const signature = await hmacSign(secret, payloadB64)
+	return `${payloadB64}.${signature}`
+}
+
+export async function verifyToken(
+	secret: string,
+	token: string,
+): Promise<{ subscriberId: string; action: string; exp?: number } | null> {
+	const dotIndex = token.indexOf('.')
+	if (dotIndex === -1) return null
+
+	const payloadB64 = token.slice(0, dotIndex)
+	const signature = token.slice(dotIndex + 1)
+
+	if (!payloadB64 || !signature) return null
+
+	const valid = await hmacVerify(secret, payloadB64, signature)
+	if (!valid) return null
+
+	try {
+		const decoded = JSON.parse(new TextDecoder().decode(fromBase64Url(payloadB64))) as {
+			subscriberId: string
+			action: string
+			exp?: number
+		}
+
+		if (decoded.exp !== undefined && decoded.exp < Date.now()) return null
+
+		return decoded
+	} catch {
+		return null
+	}
+}

package/src/utils/tracking.ts

@@ -0,0 +1,58 @@
+// 43-byte 1×1 transparent GIF
+export const TRANSPARENT_GIF = new Uint8Array([
+	0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x01, 0x00, 0x01, 0x00, 0x80, 0x00, 0x00, 0xff, 0xff, 0xff,
+	0x00, 0x00, 0x00, 0x21, 0xf9, 0x04, 0x01, 0x00, 0x00, 0x00, 0x00, 0x2c, 0x00, 0x00, 0x00, 0x00,
+	0x01, 0x00, 0x01, 0x00, 0x00, 0x02, 0x02, 0x44, 0x01, 0x00, 0x3b,
+])
+
+/**
+ * Inject a tracking pixel before the closing </body> tag.
+ * If no </body> tag exists, the pixel is appended to the end.
+ * The {{TRACKING_ID}} placeholder is substituted per-recipient at send time.
+ *
+ * Only used for campaign/digest emails — never transactional.
+ */
+export function injectTrackingPixel(html: string, trackOpenUrl: string): string {
+	const pixel = `<img src="${trackOpenUrl}/{{TRACKING_ID}}" width="1" height="1" alt="" style="display:block;width:1px;height:1px;border:0;" />`
+
+	const bodyCloseIdx = html.lastIndexOf('</body>')
+	if (bodyCloseIdx !== -1) {
+		return html.slice(0, bodyCloseIdx) + pixel + html.slice(bodyCloseIdx)
+	}
+
+	return html + pixel
+}
+
+/**
+ * Rewrite all <a href="..."> links to pass through a tracking redirect.
+ * The rewritten href becomes:
+ *   {trackClickUrl}/{{TRACKING_ID}}?url={encodeURIComponent(originalUrl)}
+ *
+ * Skipped links:
+ *   - Template placeholders: {{UNSUBSCRIBE_URL}}, {{PREFERENCES_URL}}
+ *   - mailto: links
+ *   - Anchor links starting with #
+ *   - Empty href or missing href
+ *
+ * The {{TRACKING_ID}} placeholder is substituted per-recipient at send time.
+ *
+ * Only used for campaign/digest emails — never transactional.
+ */
+export function rewriteLinksForTracking(html: string, trackClickUrl: string): string {
+	return html.replace(
+		/<a\s([^>]*?)href\s*=\s*"([^"]*)"([^>]*?)>/gi,
+		(_match, before: string, href: string, after: string) => {
+			if (!href || href.startsWith('#') || href.startsWith('mailto:')) {
+				return _match
+			}
+
+			if (href.includes('{{UNSUBSCRIBE_URL}}') || href.includes('{{PREFERENCES_URL}}')) {
+				return _match
+			}
+
+			const tracked = `${trackClickUrl}/{{TRACKING_ID}}` + `?url=${encodeURIComponent(href)}`
+
+			return `<a ${before}href="${tracked}"${after}>`
+		},
+	)
+}

package/src/utils/urls.ts

@@ -0,0 +1,49 @@
+import type { ResolvedMailerOptions } from '../options.js'
+import { generateToken } from './tokens.js'
+
+export function buildSiteUrl(
+	siteUrl: string,
+	path: string,
+	searchParams?: Record<string, string | boolean | undefined>,
+): string {
+	const url = new URL(path, siteUrl)
+
+	for (const [key, value] of Object.entries(searchParams ?? {})) {
+		if (value === undefined) continue
+		url.searchParams.set(key, typeof value === 'boolean' ? String(value) : value)
+	}
+
+	return url.toString()
+}
+
+export async function buildSubscriberManageUrls(
+	options: Pick<
+		ResolvedMailerOptions,
+		'preferencesPath' | 'siteUrl' | 'signingSecret' | 'unsubscribePath'
+	>,
+	subscriberId?: string,
+): Promise<{ preferencesUrl: string; unsubscribeUrl: string }> {
+	if (!subscriberId) {
+		return { preferencesUrl: '', unsubscribeUrl: '' }
+	}
+
+	const [unsubscribeToken, preferencesToken] = await Promise.all([
+		generateToken(options.signingSecret, {
+			subscriberId,
+			action: 'unsubscribe',
+		}),
+		generateToken(options.signingSecret, {
+			subscriberId,
+			action: 'preferences',
+		}),
+	])
+
+	return {
+		unsubscribeUrl: buildSiteUrl(options.siteUrl, options.unsubscribePath, {
+			token: unsubscribeToken,
+		}),
+		preferencesUrl: buildSiteUrl(options.siteUrl, options.preferencesPath, {
+			token: preferencesToken,
+		}),
+	}
+}