@growth-labs/mailer 0.1.3

package/dist/utils/urls.js

@@ -0,0 +1,34 @@
+import { generateToken } from './tokens.js';
+export function buildSiteUrl(siteUrl, path, searchParams) {
+    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, subscriberId) {
+    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,
+        }),
+    };
+}
+//# sourceMappingURL=urls.js.map

package/dist/utils/urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.js","sourceRoot":"","sources":["../../src/utils/urls.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,MAAM,UAAU,YAAY,CAC3B,OAAe,EACf,IAAY,EACZ,YAA2D;IAE3D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAElC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,KAAK,KAAK,SAAS;YAAE,SAAQ;QACjC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;IAC9E,CAAC;IAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAA;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC9C,OAGC,EACD,YAAqB;IAErB,IAAI,CAAC,YAAY,EAAE,CAAC;QACnB,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,CAAA;IAClD,CAAC;IAED,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC9D,aAAa,CAAC,OAAO,CAAC,aAAa,EAAE;YACpC,YAAY;YACZ,MAAM,EAAE,aAAa;SACrB,CAAC;QACF,aAAa,CAAC,OAAO,CAAC,aAAa,EAAE;YACpC,YAAY;YACZ,MAAM,EAAE,aAAa;SACrB,CAAC;KACF,CAAC,CAAA;IAEF,OAAO;QACN,cAAc,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,EAAE;YACtE,KAAK,EAAE,gBAAgB;SACvB,CAAC;QACF,cAAc,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,EAAE;YACtE,KAAK,EAAE,gBAAgB;SACvB,CAAC;KACF,CAAA;AACF,CAAC"}

package/dist/vite-plugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+import type { ResolvedMailerOptions } from './options.js';
+export declare function growthLabsMailerPlugin(config: ResolvedMailerOptions): Plugin;
+//# sourceMappingURL=vite-plugin.d.ts.map

package/dist/vite-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../src/vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAKzD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAc5E"}

package/dist/vite-plugin.js

@@ -0,0 +1,18 @@
+const VIRTUAL_MODULE_ID = 'virtual:growth-labs/mailer/config';
+const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+export function growthLabsMailerPlugin(config) {
+    return {
+        name: 'growth-labs-mailer-config',
+        resolveId(id) {
+            if (id === VIRTUAL_MODULE_ID) {
+                return RESOLVED_VIRTUAL_MODULE_ID;
+            }
+        },
+        load(id) {
+            if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                return `export const config = ${JSON.stringify(config)};`;
+            }
+        },
+    };
+}
+//# sourceMappingURL=vite-plugin.js.map

package/dist/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../src/vite-plugin.ts"],"names":[],"mappings":"AAGA,MAAM,iBAAiB,GAAG,mCAAmC,CAAA;AAC7D,MAAM,0BAA0B,GAAG,KAAK,iBAAiB,EAAE,CAAA;AAE3D,MAAM,UAAU,sBAAsB,CAAC,MAA6B;IACnE,OAAO;QACN,IAAI,EAAE,2BAA2B;QACjC,SAAS,CAAC,EAAE;YACX,IAAI,EAAE,KAAK,iBAAiB,EAAE,CAAC;gBAC9B,OAAO,0BAA0B,CAAA;YAClC,CAAC;QACF,CAAC;QACD,IAAI,CAAC,EAAE;YACN,IAAI,EAAE,KAAK,0BAA0B,EAAE,CAAC;gBACvC,OAAO,yBAAyB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAA;YAC1D,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC"}

package/package.json

@@ -0,0 +1,85 @@
+{
+	"name": "@growth-labs/mailer",
+	"version": "0.1.3",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./components": {
+			"types": "./src/components/index.ts",
+			"import": "./src/components/index.ts"
+		},
+		"./utils": {
+			"types": "./dist/utils/index.d.ts",
+			"import": "./dist/utils/index.js"
+		},
+		"./utils/*": {
+			"types": "./dist/utils/*.d.ts",
+			"import": "./dist/utils/*.js"
+		},
+		"./middleware/*": {
+			"types": "./dist/middleware/*.d.ts",
+			"import": "./dist/middleware/*.js",
+			"default": "./dist/middleware/*.js"
+		},
+		"./routes/preferences": {
+			"types": "./src/routes/preferences.astro",
+			"import": "./src/routes/preferences.astro",
+			"default": "./src/routes/preferences.astro"
+		},
+		"./routes/*": {
+			"types": "./dist/routes/*.d.ts",
+			"import": "./dist/routes/*.js",
+			"default": "./dist/routes/*.js"
+		},
+		"./queue": {
+			"types": "./dist/queue/consumer.d.ts",
+			"import": "./dist/queue/consumer.js"
+		},
+		"./components/*": {
+			"types": "./src/components/*.astro",
+			"import": "./src/components/*.astro"
+		},
+		"./schema": {
+			"types": "./dist/schema.d.ts",
+			"import": "./dist/schema.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md"
+	],
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"scripts": {
+		"build": "tsc",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"peerDependencies": {
+		"astro": "^6.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@growth-labs/analytics": {
+			"optional": true
+		}
+	},
+	"dependencies": {
+		"drizzle-orm": "^0.38.0",
+		"ulidx": "^2.4.0",
+		"zod": "^3.23.0"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20260402.1",
+		"astro": "^6.0.0",
+		"drizzle-kit": "^0.30.0",
+		"typescript": "^5.7.0",
+		"vite": "^7.0.0",
+		"vitest": "^3.0.0"
+	}
+}

package/src/astro.d.ts

@@ -0,0 +1,4 @@
+declare module '*.astro' {
+	const Component: any
+	export default Component
+}

package/src/components/PreferenceCenter.astro

@@ -0,0 +1,147 @@
+---
+import type { Subscriber } from "../types.js";
+
+interface Props {
+	subscriber: Subscriber;
+	topics: string[];
+	token: string;
+	siteUrl: string;
+	subscribePath: string;
+	senderName: string;
+	brand?: {
+		primaryColor?: string;
+		accentColor?: string;
+		logoUrl?: string;
+		footerText?: string;
+	};
+}
+
+const {
+	subscriber,
+	topics,
+	token,
+	siteUrl,
+	subscribePath,
+	senderName,
+	brand,
+} = Astro.props;
+
+const primaryColor = brand?.primaryColor ?? "#1a365d";
+const accentColor = brand?.accentColor ?? "#e53e3e";
+const resubscribeUrl = new URL(subscribePath, siteUrl).toString();
+---
+
+<div class="gl-preference-center" style="max-width: 600px; margin: 0 auto; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color: #111827;">
+	<div
+		class="gl-toast gl-toast-success"
+		data-toast="updated"
+		hidden
+		style={`background-color: #ecfdf5; border: 1px solid #6ee7b7; color: #065f46; padding: 12px 16px; border-radius: 8px; margin-bottom: 24px; font-size: 14px;`}
+	>
+		Your preferences have been updated.
+	</div>
+	<div
+		class="gl-toast gl-toast-info"
+		data-toast="unsubscribed"
+		hidden
+		style={`background-color: #eff6ff; border: 1px solid #93c5fd; color: #1e40af; padding: 12px 16px; border-radius: 8px; margin-bottom: 24px; font-size: 14px;`}
+	>
+		You have been unsubscribed from all emails.
+	</div>
+
+	<div style={`background-color: ${primaryColor}; padding: 24px; border-radius: 8px 8px 0 0; text-align: center;`}>
+		{brand?.logoUrl && (
+			<img
+				src={brand.logoUrl}
+				alt={senderName}
+				style="max-height: 48px; margin-bottom: 8px;"
+			/>
+		)}
+		<h1 style="color: #ffffff; margin: 0; font-size: 24px; font-weight: 700;">
+			Email Preferences
+		</h1>
+	</div>
+
+	<div style="background-color: #ffffff; padding: 32px 24px; border: 1px solid #e5e7eb; border-top: none;">
+		<p style="font-size: 16px; line-height: 24px; color: #374151; margin: 0 0 24px 0;">
+			Managing preferences for <strong>{subscriber.email}</strong>
+		</p>
+
+		{subscriber.status === "unsubscribed" ? (
+			<div style="text-align: center; padding: 24px 0;">
+				<p style="font-size: 16px; color: #374151; margin: 0 0 16px 0;">
+					You are currently unsubscribed from {senderName}.
+				</p>
+				<a
+					href={resubscribeUrl}
+					style={`display: inline-block; background-color: ${primaryColor}; color: #ffffff; text-decoration: none; padding: 12px 24px; border-radius: 4px; font-weight: 700; font-size: 16px;`}
+				>
+					Re-subscribe
+				</a>
+			</div>
+		) : (
+			<>
+				{topics.length > 0 && (
+					<form method="POST">
+						<input type="hidden" name="token" value={token} />
+						<input type="hidden" name="action" value="preferences" />
+
+						<fieldset style="border: none; padding: 0; margin: 0 0 24px 0;">
+							<legend style="font-size: 16px; font-weight: 700; color: #111827; margin-bottom: 12px;">
+								Choose the topics you'd like to receive:
+							</legend>
+							{topics.map((topic) => (
+								<label
+									style="display: flex; align-items: center; padding: 8px 12px; margin-bottom: 4px; border-radius: 4px; cursor: pointer; font-size: 15px; color: #374151;"
+								>
+									<input
+										type="checkbox"
+										name={`pref_${topic}`}
+										value="on"
+										checked={subscriber.preferences.includes(topic)}
+										style={`margin-right: 10px; width: 18px; height: 18px; accent-color: ${primaryColor};`}
+									/>
+									{topic}
+								</label>
+							))}
+						</fieldset>
+
+						<button
+							type="submit"
+							style={`display: inline-block; background-color: ${primaryColor}; color: #ffffff; border: none; padding: 12px 24px; border-radius: 4px; font-weight: 700; font-size: 16px; cursor: pointer;`}
+						>
+							Update preferences
+						</button>
+					</form>
+				)}
+
+				<hr style="border: none; border-top: 1px solid #e5e7eb; margin: 32px 0;" />
+
+				<form method="POST" style="text-align: center;">
+					<input type="hidden" name="token" value={token} />
+					<input type="hidden" name="action" value="unsubscribe" />
+					<p style="font-size: 14px; color: #6b7280; margin: 0 0 12px 0;">
+						Don't want to receive any more emails?
+					</p>
+					<button
+						type="submit"
+						style="display: inline-block; background-color: transparent; color: #6b7280; border: 1px solid #d1d5db; padding: 8px 20px; border-radius: 4px; font-size: 14px; cursor: pointer;"
+					>
+						Unsubscribe from all
+					</button>
+				</form>
+			</>
+		)}
+	</div>
+
+	<div style="padding: 16px; text-align: center;">
+		{brand?.footerText && (
+			<p style="font-size: 12px; color: #9ca3af; margin: 0 0 8px 0;">
+				{brand.footerText}
+			</p>
+		)}
+		<p style="font-size: 12px; color: #9ca3af; margin: 0;">
+			{senderName}
+		</p>
+	</div>
+</div>

package/src/components/SubscribeForm.astro

@@ -0,0 +1,161 @@
+---
+import { config } from "virtual:growth-labs/mailer/config";
+
+interface Props {
+	source?: string;
+	topics?: string[];
+	showNameField?: boolean;
+	showTopics?: boolean;
+	submitText?: string;
+	successMessage?: string;
+	class?: string;
+}
+
+const {
+	source = "form",
+	topics,
+	showNameField = false,
+	showTopics = false,
+	submitText = "Subscribe",
+	successMessage = "Check your email to confirm!",
+	class: className,
+} = Astro.props;
+
+const formTopics = showTopics ? (topics ?? config.topics ?? []) : [];
+const formId = `gl-subscribe-${Math.random().toString(36).slice(2, 8)}`;
+---
+
+<div class:list={['gl-subscribe-form', className]} id={formId}>
+	<form
+		method="POST"
+		action={config.subscribePath}
+		data-gl-subscribe-form
+	>
+		<div class="gl-subscribe-fields">
+			{showNameField && (
+				<div class="gl-subscribe-field">
+					<label for={`${formId}-name`}>Name</label>
+					<input
+						type="text"
+						id={`${formId}-name`}
+						name="name"
+						autocomplete="name"
+					/>
+				</div>
+			)}
+			<div class="gl-subscribe-field">
+				<label for={`${formId}-email`}>Email</label>
+				<input
+					type="email"
+					id={`${formId}-email`}
+					name="email"
+					required
+					autocomplete="email"
+					placeholder="you@example.com"
+				/>
+			</div>
+		</div>
+
+		{formTopics.length > 0 && (
+			<fieldset class="gl-subscribe-topics">
+				<legend>Topics</legend>
+				{formTopics.map((topic) => (
+					<label class="gl-subscribe-topic">
+						<input
+							type="checkbox"
+							name="preferences"
+							value={topic}
+							checked
+						/>
+						{topic}
+					</label>
+				))}
+			</fieldset>
+		)}
+
+		<input type="hidden" name="source" value={source} />
+		<div class="gl-turnstile" data-sitekey={config.turnstileSiteKey}></div>
+
+		<button type="submit" data-gl-submit>
+			{submitText}
+		</button>
+
+		<div class="gl-subscribe-message" data-gl-message hidden>
+			<p data-gl-success hidden>{successMessage}</p>
+			<p data-gl-error hidden></p>
+		</div>
+	</form>
+</div>
+
+<script define:vars={{ subscribePath: config.subscribePath, formId }}>
+	;(function () {
+		const container = document.getElementById(formId)
+		if (!container) return
+
+		const form = container.querySelector('[data-gl-subscribe-form]')
+		const submitBtn = container.querySelector('[data-gl-submit]')
+		const messageEl = container.querySelector('[data-gl-message]')
+		const successEl = container.querySelector('[data-gl-success]')
+		const errorEl = container.querySelector('[data-gl-error]')
+
+		// Load Turnstile
+		if (!document.querySelector('script[src*="turnstile"]')) {
+			const script = document.createElement('script')
+			script.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js'
+			script.async = true
+			document.head.appendChild(script)
+		}
+
+		form?.addEventListener('submit', async function (e) {
+			e.preventDefault()
+			if (!form || !submitBtn) return
+
+			submitBtn.setAttribute('disabled', 'true')
+			messageEl?.setAttribute('hidden', '')
+			successEl?.setAttribute('hidden', '')
+			errorEl?.setAttribute('hidden', '')
+
+			const formData = new FormData(form)
+			const preferences = formData.getAll('preferences')
+			const turnstileInput = form.querySelector(
+				'[name="cf-turnstile-response"]',
+			)
+			const turnstileToken = turnstileInput?.value ?? ''
+
+			try {
+				const res = await fetch(subscribePath, {
+					method: 'POST',
+					headers: { 'Content-Type': 'application/json' },
+					body: JSON.stringify({
+						email: formData.get('email'),
+						name: formData.get('name') || undefined,
+						source: formData.get('source'),
+						preferences: preferences.length ? preferences : undefined,
+						turnstileToken,
+					}),
+				})
+
+				const data = await res.json()
+
+				messageEl?.removeAttribute('hidden')
+				if (data.success) {
+					successEl?.removeAttribute('hidden')
+					form.reset()
+				} else {
+					if (errorEl) {
+						errorEl.textContent = data.error || 'Something went wrong'
+						errorEl.removeAttribute('hidden')
+					}
+				}
+			} catch {
+				messageEl?.removeAttribute('hidden')
+				if (errorEl) {
+					errorEl.textContent = 'Network error. Please try again.'
+					errorEl.removeAttribute('hidden')
+				}
+			} finally {
+				submitBtn.removeAttribute('disabled')
+			}
+		})
+	})()
+</script>

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { default as PreferenceCenter } from './PreferenceCenter.astro'
+export { default as SubscribeForm } from './SubscribeForm.astro'

package/src/index.ts

@@ -0,0 +1,101 @@
+import type { AstroIntegration } from 'astro'
+import type { MailerOptions, ResolvedMailerOptions } from './options.js'
+import { mailerOptionsSchema } from './options.js'
+import { growthLabsMailerPlugin } from './vite-plugin.js'
+
+export default function mailer(userOptions: MailerOptions): AstroIntegration {
+	const options = mailerOptionsSchema.parse(userOptions) as ResolvedMailerOptions
+
+	return {
+		name: '@growth-labs/mailer',
+		hooks: {
+			'astro:config:setup': ({ injectRoute, addMiddleware, updateConfig, config: astroConfig }) => {
+				// Auto-detect @growth-labs/analytics
+				const hasAnalytics = astroConfig.integrations.some(
+					(i) => i.name === '@growth-labs/analytics',
+				)
+				if (hasAnalytics) {
+					;(options as Record<string, unknown>).analyticsEnabled = true
+				}
+
+				// Install Vite plugin for virtual module
+				updateConfig({
+					vite: { plugins: [growthLabsMailerPlugin(options)] },
+				})
+
+				// Inject routes
+				injectRoute({
+					pattern: options.subscribePath,
+					entrypoint: '@growth-labs/mailer/routes/subscribe',
+				})
+				injectRoute({
+					pattern: options.confirmPath,
+					entrypoint: '@growth-labs/mailer/routes/confirm',
+				})
+				injectRoute({
+					pattern: options.unsubscribePath,
+					entrypoint: '@growth-labs/mailer/routes/unsubscribe',
+				})
+				injectRoute({
+					pattern: options.preferencesPath,
+					entrypoint: '@growth-labs/mailer/routes/preferences',
+				})
+				injectRoute({
+					pattern: options.webhookPath,
+					entrypoint: '@growth-labs/mailer/routes/webhook',
+				})
+				injectRoute({
+					pattern: `${options.trackOpenPath}/[trackingId]`,
+					entrypoint: '@growth-labs/mailer/routes/track-open',
+				})
+				injectRoute({
+					pattern: `${options.trackClickPath}/[trackingId]`,
+					entrypoint: '@growth-labs/mailer/routes/track-click',
+				})
+
+				// Add tracking middleware
+				addMiddleware({
+					entrypoint: '@growth-labs/mailer/middleware/tracking',
+					order: 'post',
+				})
+			},
+		},
+	}
+}
+
+export type { MailerOptions, ResolvedMailerOptions } from './options.js'
+// Re-export options and types
+export { mailerOptionsSchema } from './options.js'
+export { handleEmailQueue } from './queue/consumer.js'
+export type {
+	DigestItem,
+	EmailProvider,
+	EmailQueueMessage,
+	EmailSend,
+	EmailSendStatus,
+	OutboundEmail,
+	SendResult,
+	Subscriber,
+	SubscriberFilter,
+	SubscriberStatus,
+	TemplateData,
+	TemplateName,
+} from './types.js'
+export type { CampaignSchedule, DigestSchedule } from './utils/scheduling.js'
+export {
+	executeCampaignSchedule,
+	executeDigestSchedule,
+	prepareCampaign,
+	prepareDigest,
+	sendBatchCampaigns,
+} from './utils/scheduling.js'
+export type { MailerEnv } from './utils/send.js'
+// Re-export utilities for standalone use
+export { sendCampaign, sendDigest, sendTransactional } from './utils/send.js'
+export {
+	countSubscribers,
+	createSubscriber,
+	getSubscriberByEmail,
+	getSubscriberById,
+} from './utils/subscribers.js'
+export { renderEmail } from './utils/templates.js'

package/src/middleware/tracking.ts

@@ -0,0 +1,18 @@
+import { config } from 'virtual:growth-labs/mailer/config'
+import type { MiddlewareHandler } from 'astro'
+
+export const onRequest: MiddlewareHandler = async (_context, next) => {
+	const response = await next()
+	const url = new URL(_context.request.url)
+
+	if (
+		url.pathname.startsWith(config.trackOpenPath) ||
+		url.pathname.startsWith(config.trackClickPath)
+	) {
+		response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate')
+		response.headers.delete('ETag')
+		response.headers.delete('Last-Modified')
+	}
+
+	return response
+}

package/src/options.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+
+export const mailerOptionsSchema = z
+	.object({
+		// ─── Required ───
+		senderName: z.string(),
+		fromAddress: z.string().email(),
+
+		// ─── Reply-to ───
+		replyTo: z.string().email().optional(),
+
+		// ─── Cloudflare bindings ───
+		d1Binding: z.string().default('SITE_DB'),
+		queueBinding: z.string().default('EMAIL_QUEUE'),
+
+		// ─── Turnstile (subscribe form) ───
+		turnstileSiteKey: z.string(),
+		turnstileSecretKey: z.string(),
+
+		// ─── Subscriber lifecycle ───
+		doubleOptIn: z.boolean().default(true),
+		topics: z.array(z.string()).optional(),
+
+		// ─── Token signing ───
+		signingSecret: z.string(),
+
+		// ─── Routes ───
+		subscribePath: z.string().default('/api/newsletter/subscribe'),
+		confirmPath: z.string().default('/api/newsletter/confirm'),
+		unsubscribePath: z.string().default('/api/newsletter/unsubscribe'),
+		preferencesPath: z.string().default('/email/preferences'),
+		webhookPath: z.string().default('/api/email/webhook'),
+
+		// ─── Tracking ───
+		trackOpenPath: z.string().default('/api/email/open'),
+		trackClickPath: z.string().default('/api/email/click'),
+		siteUrl: z.string().url(),
+
+		// ─── Branding (for built-in templates) ───
+		brand: z
+			.object({
+				logoUrl: z.string().url().optional(),
+				primaryColor: z.string().default('#1a365d'),
+				accentColor: z.string().default('#e53e3e'),
+				footerText: z.string().optional(),
+			})
+			.default({}),
+
+		// ─── Fallback provider ───
+		fallbackProvider: z.enum(['resend', 'none']).default('none'),
+		resendApiKey: z.string().optional(),
+
+		// ─── Queue batching ───
+		batchSize: z.number().min(1).max(500).default(100),
+
+		// ─── Optional peer: analytics ───
+		analyticsEnabled: z.boolean().default(false),
+	})
+	.refine((data) => data.fallbackProvider !== 'resend' || data.resendApiKey, {
+		message: 'resendApiKey is required when fallbackProvider is "resend"',
+		path: ['resendApiKey'],
+	})
+
+export type MailerOptions = z.input<typeof mailerOptionsSchema>
+export type ResolvedMailerOptions = z.output<typeof mailerOptionsSchema>