@growth-labs/mailer 0.1.3

package/src/queue/consumer.ts

@@ -0,0 +1,99 @@
+import { drizzle } from 'drizzle-orm/d1'
+import type { ResolvedMailerOptions } from '../options.js'
+import type { EmailProvider, EmailQueueMessage } from '../types.js'
+import { updateSendStatus } from '../utils/bounce.js'
+import type { CloudflareEmailSender } from '../utils/providers.js'
+import { CloudflareEmailProvider, getFallbackProvider, sleep } from '../utils/providers.js'
+
+export async function handleEmailQueue(
+	batch: MessageBatch<EmailQueueMessage>,
+	env: { DB: D1Database; EMAIL_SENDER?: CloudflareEmailSender },
+	options: ResolvedMailerOptions,
+): Promise<void> {
+	const db = drizzle(env.DB)
+	const provider: EmailProvider = env.EMAIL_SENDER
+		? new CloudflareEmailProvider(env.EMAIL_SENDER)
+		: new CloudflareEmailProvider({
+				send: () => Promise.reject(new Error('No email sender configured')),
+			})
+	const fallback = getFallbackProvider(options)
+
+	for (const message of batch.messages) {
+		const { recipients, htmlTemplate, subject, from, replyTo, headers, type } = message.body
+
+		for (const recipient of recipients) {
+			let html = htmlTemplate
+			if (type !== 'transactional') {
+				const unsubscribeUrl = `${options.siteUrl}${options.unsubscribePath}?token=${recipient.unsubscribeToken}`
+				const preferencesUrl = `${options.siteUrl}${options.preferencesPath}?token=${recipient.preferencesToken}`
+				html = html
+					.replaceAll('{{TRACKING_ID}}', recipient.trackingId)
+					.replaceAll('{{UNSUBSCRIBE_URL}}', unsubscribeUrl)
+					.replaceAll('{{PREFERENCES_URL}}', preferencesUrl)
+			}
+
+			const recipientHeaders =
+				type !== 'transactional'
+					? {
+							...headers,
+							'List-Unsubscribe': `<${options.siteUrl}${options.unsubscribePath}?token=${recipient.unsubscribeToken}>`,
+							'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+						}
+					: headers
+
+			let result = await provider.send({
+				to: recipient.email,
+				from,
+				replyTo,
+				subject,
+				html,
+				headers: recipientHeaders,
+			})
+
+			if (!result.success && result.retryable) {
+				for (let attempt = 1; attempt <= 3; attempt++) {
+					await sleep(2 ** attempt * 1000)
+					result = await provider.send({
+						to: recipient.email,
+						from,
+						replyTo,
+						subject,
+						html,
+						headers: recipientHeaders,
+					})
+					if (result.success) break
+				}
+			}
+
+			if (!result.success && fallback) {
+				result = await fallback.send({
+					to: recipient.email,
+					from,
+					replyTo,
+					subject,
+					html,
+					headers: recipientHeaders,
+				})
+				if (result.success) {
+					console.warn(
+						`[mailer] Fallback provider used for ${recipient.email}: ${provider.name} → ${fallback.name}`,
+					)
+				}
+			}
+
+			if (result.success) {
+				await updateSendStatus(db, recipient.trackingId, 'sent', {
+					sentAt: new Date().toISOString(),
+				})
+			} else {
+				await updateSendStatus(db, recipient.trackingId, 'bounced', {
+					bouncedAt: new Date().toISOString(),
+					bounceType: 'hard',
+				})
+				console.error(`[mailer] Send failed for ${recipient.email}: ${result.error}`)
+			}
+		}
+
+		message.ack()
+	}
+}

package/src/routes/confirm.ts

@@ -0,0 +1,68 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { APIRoute } from 'astro'
+import { drizzle } from 'drizzle-orm/d1'
+import type { RuntimeLocals } from '../utils/bindings.js'
+import type { MailerEnv } from '../utils/send.js'
+import { sendTransactional } from '../utils/send.js'
+import { confirmSubscriber, getSubscriberById } from '../utils/subscribers.js'
+import { verifyToken } from '../utils/tokens.js'
+
+export const GET: APIRoute = async ({ url, locals }) => {
+	const token = url.searchParams.get('token')
+	if (!token) {
+		return Response.json({ error: 'Missing token' }, { status: 400 })
+	}
+
+	// Verify token
+	const payload = await verifyToken(config.signingSecret, token)
+	if (!payload || payload.action !== 'confirm') {
+		return Response.json({ error: 'Invalid or expired token' }, { status: 400 })
+	}
+
+	// Resolve bindings
+	const runtimeEnv = (locals as RuntimeLocals).runtime?.env as Record<string, unknown>
+	const d1 = runtimeEnv[config.d1Binding] as D1Database
+	const queue = runtimeEnv[config.queueBinding] as Queue
+	const db = drizzle(d1)
+	const env: MailerEnv = { DB: d1, QUEUE: queue }
+
+	// Get subscriber to check status
+	const subscriber = await getSubscriberById(db, payload.subscriberId)
+	if (!subscriber) {
+		return Response.json({ error: 'Subscriber not found' }, { status: 404 })
+	}
+
+	if (subscriber.status === 'active') {
+		// Already confirmed — redirect with flag
+		return new Response(null, {
+			status: 302,
+			headers: {
+				Location: `${config.siteUrl}?already_confirmed=true`,
+			},
+		})
+	}
+
+	// Confirm subscriber
+	try {
+		await confirmSubscriber(db, payload.subscriberId)
+	} catch {
+		return Response.json({ error: 'Confirmation failed' }, { status: 400 })
+	}
+
+	// Send welcome email
+	await sendTransactional(env, config, {
+		to: subscriber.email,
+		subscriberId: subscriber.id,
+		subject: `Welcome to ${config.senderName}`,
+		template: 'welcome',
+		data: { name: subscriber.name },
+	})
+
+	// Redirect to site with confirmed flag
+	return new Response(null, {
+		status: 302,
+		headers: {
+			Location: `${config.siteUrl}?confirmed=true`,
+		},
+	})
+}

package/src/routes/preferences.astro

@@ -0,0 +1,137 @@
+---
+import { config } from "virtual:growth-labs/mailer/config";
+import { drizzle } from "drizzle-orm/d1";
+import PreferenceCenter from "../components/PreferenceCenter.astro";
+import {
+	getSubscriberById,
+	unsubscribeSubscriber,
+	updatePreferences,
+} from "../utils/subscribers.js";
+import { generateToken, verifyToken } from "../utils/tokens.js";
+import { buildSiteUrl } from "../utils/urls.js";
+
+const url = Astro.url;
+const unsubscribed = url.searchParams.get("unsubscribed") === "true";
+const updated = url.searchParams.get("updated") === "true";
+const formData = Astro.request.method === "POST" ? await Astro.request.formData() : null;
+const submittedToken = formData?.get("token");
+const token =
+	Astro.request.method === "POST"
+		? typeof submittedToken === "string"
+			? submittedToken
+			: null
+		: url.searchParams.get("token");
+
+if (!token) {
+	return new Response("Missing token", { status: 400 });
+}
+
+const payload = await verifyToken(config.signingSecret, token);
+if (!payload || !["preferences", "unsubscribe"].includes(payload.action)) {
+	return new Response("Invalid or expired token", { status: 400 });
+}
+
+if (Astro.request.method === "GET" && payload.action === "unsubscribe") {
+	const preferencesToken = await generateToken(config.signingSecret, {
+		subscriberId: payload.subscriberId,
+		action: "preferences",
+	});
+
+	return Astro.redirect(
+		buildSiteUrl(config.siteUrl, config.preferencesPath, {
+			token: preferencesToken,
+			unsubscribed: unsubscribed || undefined,
+			updated: updated || undefined,
+		}),
+	);
+}
+
+if (Astro.request.method === "POST" && payload.action !== "preferences") {
+	return new Response("Invalid or expired token", { status: 400 });
+}
+
+const runtimeEnv = (
+	Astro.locals as Record<string, unknown> & {
+		runtime?: { env: Record<string, unknown> };
+	}
+).runtime?.env;
+if (!runtimeEnv) {
+	return new Response("Runtime not available", { status: 500 });
+}
+
+const d1 = runtimeEnv[config.d1Binding] as D1Database;
+const db = drizzle(d1);
+
+// Handle POST (form submission)
+if (Astro.request.method === "POST") {
+	const action = formData.get("action");
+
+	if (action === "unsubscribe") {
+		await unsubscribeSubscriber(db, payload.subscriberId);
+		return Astro.redirect(
+			buildSiteUrl(config.siteUrl, config.preferencesPath, {
+				token,
+				unsubscribed: true,
+			}),
+		);
+	}
+
+	const newPreferences: string[] = [];
+	for (const topic of config.topics ?? []) {
+		if (formData.get(`pref_${topic}`)) {
+			newPreferences.push(topic);
+		}
+	}
+	await updatePreferences(db, payload.subscriberId, newPreferences);
+	return Astro.redirect(
+		buildSiteUrl(config.siteUrl, config.preferencesPath, {
+			token,
+			updated: true,
+		}),
+	);
+}
+
+const subscriber = await getSubscriberById(db, payload.subscriberId);
+if (!subscriber) {
+	return new Response("Subscriber not found", { status: 404 });
+}
+---
+
+<html lang="en">
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1" />
+	<title>Email Preferences — {config.senderName}</title>
+	<style>
+		body {
+			margin: 0;
+			padding: 24px 16px;
+			background-color: #f4f4f5;
+			min-height: 100vh;
+		}
+	</style>
+</head>
+<body>
+	<PreferenceCenter
+		subscriber={subscriber}
+		topics={config.topics ?? []}
+		token={token}
+		siteUrl={config.siteUrl}
+		subscribePath={config.subscribePath}
+		senderName={config.senderName}
+		brand={config.brand}
+	/>
+	{unsubscribed && (
+		<script>
+			document.querySelector('[data-toast="unsubscribed"]')
+				?.removeAttribute('hidden')
+		</script>
+	)}
+	{updated && (
+		<script>
+			document.querySelector('[data-toast="updated"]')
+				?.removeAttribute('hidden')
+		</script>
+	)}
+</body>
+</html>

package/src/routes/subscribe.ts

@@ -0,0 +1,107 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { APIRoute } from 'astro'
+import { drizzle } from 'drizzle-orm/d1'
+import type { RuntimeLocals } from '../utils/bindings.js'
+import type { MailerEnv } from '../utils/send.js'
+import { sendTransactional } from '../utils/send.js'
+import { createSubscriber } from '../utils/subscribers.js'
+import { generateToken } from '../utils/tokens.js'
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	// 1. Parse request body
+	const body = (await request.json()) as {
+		email?: string
+		name?: string
+		source?: string
+		preferences?: string[]
+		turnstileToken?: string
+	}
+
+	// 2. Validate required fields
+	if (!body.email || !body.turnstileToken) {
+		return Response.json({ error: 'Missing required fields' }, { status: 400 })
+	}
+
+	// 3. Basic email format validation
+	if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(body.email)) {
+		return Response.json({ error: 'Invalid email format' }, { status: 400 })
+	}
+
+	// 4. Validate Turnstile token
+	const turnstileResponse = await fetch(
+		'https://challenges.cloudflare.com/turnstile/v0/siteverify',
+		{
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				secret: config.turnstileSecretKey,
+				response: body.turnstileToken,
+				remoteip: request.headers.get('cf-connecting-ip') ?? undefined,
+			}),
+		},
+	)
+	const turnstileResult = (await turnstileResponse.json()) as {
+		success: boolean
+	}
+	if (!turnstileResult.success) {
+		return Response.json({ error: 'Turnstile verification failed' }, { status: 400 })
+	}
+
+	// 5. Resolve bindings
+	const runtimeEnv = (locals as RuntimeLocals).runtime?.env as Record<string, unknown>
+	const d1 = runtimeEnv[config.d1Binding] as D1Database
+	const queue = runtimeEnv[config.queueBinding] as Queue
+	const db = drizzle(d1)
+	const env: MailerEnv = { DB: d1, QUEUE: queue }
+
+	// 6. Create subscriber
+	try {
+		const { subscriber, isNew } = await createSubscriber(db, {
+			email: body.email,
+			name: body.name,
+			source: body.source ?? 'form',
+			preferences: body.preferences,
+			doubleOptIn: config.doubleOptIn,
+		})
+
+		// 7. Send confirmation or welcome email
+		if (config.doubleOptIn && (isNew || subscriber.status === 'pending')) {
+			const confirmToken = await generateToken(config.signingSecret, {
+				subscriberId: subscriber.id,
+				action: 'confirm',
+			})
+			const confirmUrl = `${config.siteUrl}${config.confirmPath}?token=${confirmToken}`
+
+			await sendTransactional(env, config, {
+				to: body.email,
+				subscriberId: subscriber.id,
+				subject: `Confirm your ${config.senderName} subscription`,
+				template: 'confirmation',
+				data: {
+					name: body.name,
+					confirmUrl,
+				},
+			})
+		} else if (!config.doubleOptIn && isNew) {
+			await sendTransactional(env, config, {
+				to: body.email,
+				subscriberId: subscriber.id,
+				subject: `Welcome to ${config.senderName}`,
+				template: 'welcome',
+				data: { name: body.name },
+			})
+		}
+
+		// Return success (always 200 to avoid email enumeration)
+		return Response.json({
+			success: true,
+			requiresConfirmation: config.doubleOptIn,
+		})
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err)
+		if (message.includes('bounced') || message.includes('complained')) {
+			return Response.json({ error: 'This email address cannot be subscribed' }, { status: 422 })
+		}
+		throw err
+	}
+}

package/src/routes/track-click.ts

@@ -0,0 +1,57 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { APIRoute } from 'astro'
+import { and, eq, inArray } from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/d1'
+import { emailSends } from '../schema.js'
+
+export const GET: APIRoute = async ({ params, url, locals }) => {
+	const trackingId = params.trackingId
+	const destination = url.searchParams.get('url')
+
+	if (!trackingId || !destination) {
+		return new Response('Bad request', { status: 400 })
+	}
+
+	// Validate: must be http or https (prevent javascript:, data:, etc.)
+	try {
+		const destUrl = new URL(destination)
+		if (!['http:', 'https:'].includes(destUrl.protocol)) {
+			return new Response('Invalid redirect', { status: 400 })
+		}
+	} catch {
+		return new Response('Invalid URL', { status: 400 })
+	}
+
+	// Update status to 'clicked' only when it hasn't already reached 'clicked'
+	try {
+		const runtimeEnv = (
+			locals as Record<string, unknown> & {
+				runtime?: { env: Record<string, unknown> }
+			}
+		).runtime?.env
+		if (runtimeEnv) {
+			const d1 = runtimeEnv[config.d1Binding] as D1Database
+			const db = drizzle(d1)
+			await db
+				.update(emailSends)
+				.set({
+					status: 'clicked',
+					clickedAt: new Date().toISOString(),
+				})
+				.where(
+					and(
+						eq(emailSends.trackingId, trackingId),
+						inArray(emailSends.status, ['sent', 'delivered', 'opened']),
+					),
+				)
+		}
+	} catch {
+		// Never fail the redirect on DB errors
+	}
+
+	// 302 redirect to original destination
+	return new Response(null, {
+		status: 302,
+		headers: { Location: destination },
+	})
+}

package/src/routes/track-open.ts

@@ -0,0 +1,51 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { APIRoute } from 'astro'
+import { and, eq, inArray } from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/d1'
+import { emailSends } from '../schema.js'
+import { TRANSPARENT_GIF } from '../utils/tracking.js'
+
+export const GET: APIRoute = async ({ params, locals }) => {
+	const trackingId = params.trackingId
+	if (!trackingId) {
+		return new Response(null, { status: 400 })
+	}
+
+	// Update status to 'opened' only when currently 'sent' or 'delivered'
+	// to avoid downgrading from 'clicked'.
+	try {
+		const runtimeEnv = (
+			locals as Record<string, unknown> & {
+				runtime?: { env: Record<string, unknown> }
+			}
+		).runtime?.env
+		if (runtimeEnv) {
+			const d1 = runtimeEnv[config.d1Binding] as D1Database
+			const db = drizzle(d1)
+			await db
+				.update(emailSends)
+				.set({
+					status: 'opened',
+					openedAt: new Date().toISOString(),
+				})
+				.where(
+					and(
+						eq(emailSends.trackingId, trackingId),
+						inArray(emailSends.status, ['sent', 'delivered']),
+					),
+				)
+		}
+	} catch {
+		// Never fail the pixel response on DB errors
+	}
+
+	// 1x1 transparent GIF
+	return new Response(TRANSPARENT_GIF, {
+		status: 200,
+		headers: {
+			'Content-Type': 'image/gif',
+			'Cache-Control': 'no-store, no-cache, must-revalidate',
+			'Content-Length': String(TRANSPARENT_GIF.length),
+		},
+	})
+}

package/src/routes/unsubscribe.ts

@@ -0,0 +1,96 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { APIRoute } from 'astro'
+import { drizzle } from 'drizzle-orm/d1'
+import type { RuntimeLocals } from '../utils/bindings.js'
+import type { MailerEnv } from '../utils/send.js'
+import { sendTransactional } from '../utils/send.js'
+import { getSubscriberById, unsubscribeSubscriber } from '../utils/subscribers.js'
+import { generateToken, verifyToken } from '../utils/tokens.js'
+import { buildSiteUrl } from '../utils/urls.js'
+
+async function processUnsubscribe(locals: RuntimeLocals, token: string) {
+	// Verify token
+	const payload = await verifyToken(config.signingSecret, token)
+	if (!payload || payload.action !== 'unsubscribe') {
+		return { error: 'Invalid or expired token', status: 400 }
+	}
+
+	// Resolve bindings
+	const runtimeEnv = locals.runtime?.env as Record<string, unknown>
+	const d1 = runtimeEnv[config.d1Binding] as D1Database
+	const queue = runtimeEnv[config.queueBinding] as Queue
+	const db = drizzle(d1)
+	const env: MailerEnv = { DB: d1, QUEUE: queue }
+
+	// Get subscriber
+	const subscriber = await getSubscriberById(db, payload.subscriberId)
+	if (!subscriber) {
+		return { error: 'Subscriber not found', status: 404 }
+	}
+
+	// Unsubscribe
+	await unsubscribeSubscriber(db, payload.subscriberId)
+
+	// Send confirmation email
+	await sendTransactional(env, config, {
+		to: subscriber.email,
+		subscriberId: subscriber.id,
+		subject: `You've been unsubscribed from ${config.senderName}`,
+		template: 'unsubscribe-confirm',
+		data: {
+			name: subscriber.name,
+			resubscribeUrl: buildSiteUrl(config.siteUrl, config.subscribePath),
+		},
+	})
+
+	return {
+		success: true,
+		subscriberId: payload.subscriberId,
+	}
+}
+
+// GET: Link from email footer
+export const GET: APIRoute = async ({ url, locals }) => {
+	const token = url.searchParams.get('token')
+	if (!token) {
+		return Response.json({ error: 'Missing token' }, { status: 400 })
+	}
+
+	const result = await processUnsubscribe(locals as RuntimeLocals, token)
+	if ('error' in result) {
+		return Response.json({ error: result.error }, { status: result.status })
+	}
+
+	// Generate preferences token for the redirect
+	const preferencesToken = await generateToken(config.signingSecret, {
+		subscriberId: result.subscriberId,
+		action: 'preferences',
+	})
+	const preferencesUrl = buildSiteUrl(config.siteUrl, config.preferencesPath, {
+		token: preferencesToken,
+		unsubscribed: true,
+	})
+
+	return new Response(null, {
+		status: 302,
+		headers: { Location: preferencesUrl },
+	})
+}
+
+// POST: RFC 8058 List-Unsubscribe-Post
+export const POST: APIRoute = async ({ request, locals }) => {
+	// RFC 8058: body is "List-Unsubscribe=One-Click"
+	// Token comes from List-Unsubscribe header URL
+	const url = new URL(request.url)
+	const token = url.searchParams.get('token')
+	if (!token) {
+		return new Response('Missing token', { status: 400 })
+	}
+
+	const result = await processUnsubscribe(locals as RuntimeLocals, token)
+	if ('error' in result) {
+		return new Response(result.error, { status: result.status })
+	}
+
+	return new Response('OK', { status: 200 })
+}

package/src/routes/webhook.ts

@@ -0,0 +1,48 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { APIRoute } from 'astro'
+import { drizzle } from 'drizzle-orm/d1'
+import { handleBounce, handleComplaint, handleDelivery } from '../utils/bounce.js'
+
+interface WebhookPayload {
+	type: 'bounce' | 'complaint' | 'delivery'
+	email: string
+	bounceType?: 'hard' | 'soft'
+	trackingId?: string
+	timestamp: string
+}
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const body = (await request.json()) as WebhookPayload
+
+	if (!body.type || !body.email) {
+		return Response.json({ error: 'Invalid payload' }, { status: 400 })
+	}
+
+	const runtimeEnv = (
+		locals as Record<string, unknown> & {
+			runtime?: { env: Record<string, unknown> }
+		}
+	).runtime?.env
+	if (!runtimeEnv) {
+		return Response.json({ error: 'Runtime not available' }, { status: 500 })
+	}
+
+	const d1 = runtimeEnv[config.d1Binding] as D1Database
+	const db = drizzle(d1)
+
+	switch (body.type) {
+		case 'delivery':
+			if (body.trackingId) {
+				await handleDelivery(db, body.trackingId)
+			}
+			break
+		case 'bounce':
+			await handleBounce(db, body.email, body.bounceType ?? 'hard')
+			break
+		case 'complaint':
+			await handleComplaint(db, body.email)
+			break
+	}
+
+	return Response.json({ ok: true })
+}