@growth-labs/mailer 0.1.3 → 0.2.1

package/package.json

@@ -1,85 +1,87 @@
 {
-	"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"
-	}
-}
+  "name": "@growth-labs/mailer",
+  "version": "0.2.1",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "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/"
+  },
+  "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"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "biome check src/",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/cloudflare-workers.d.ts

@@ -0,0 +1,3 @@
+declare module 'cloudflare:workers' {
+	export const env: Record<string, unknown>
+}

package/src/options.ts

@@ -1,65 +1,57 @@
 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 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({}),
+
+	// ─── Queue batching ───
+	batchSize: z.number().min(1).max(500).default(100),
+
+	// ─── Optional peer: analytics ───
+	analyticsEnabled: z.boolean().default(false),
+	analyticsBinding: z.string().default('ANALYTICS'),
+})
 
 export type MailerOptions = z.input<typeof mailerOptionsSchema>
 export type ResolvedMailerOptions = z.output<typeof mailerOptionsSchema>

package/src/queue/consumer.ts

@@ -1,13 +1,18 @@
 import { drizzle } from 'drizzle-orm/d1'
 import type { ResolvedMailerOptions } from '../options.js'
 import type { EmailProvider, EmailQueueMessage } from '../types.js'
+import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import { updateSendStatus } from '../utils/bounce.js'
 import type { CloudflareEmailSender } from '../utils/providers.js'
-import { CloudflareEmailProvider, getFallbackProvider, sleep } from '../utils/providers.js'
+import { CloudflareEmailProvider, sleep } from '../utils/providers.js'
 
 export async function handleEmailQueue(
 	batch: MessageBatch<EmailQueueMessage>,
-	env: { DB: D1Database; EMAIL_SENDER?: CloudflareEmailSender },
+	env: {
+		DB: D1Database
+		EMAIL_SENDER?: CloudflareEmailSender
+		[key: string]: unknown
+	},
 	options: ResolvedMailerOptions,
 ): Promise<void> {
 	const db = drizzle(env.DB)
@@ -16,7 +21,6 @@ export async function handleEmailQueue(
 		: 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
@@ -65,31 +69,36 @@ export async function handleEmailQueue(
 				}
 			}
 
-			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(),
 				})
+				emitMailerAnalyticsEvent(options, env, 'newsletter_sent', {
+					contentSlug: recipient.trackingId,
+					label: {
+						trackingId: recipient.trackingId,
+						subscriberId: recipient.subscriberId,
+						email: recipient.email,
+						campaignId: message.body.campaignId,
+						type,
+					},
+				})
 			} else {
 				await updateSendStatus(db, recipient.trackingId, 'bounced', {
 					bouncedAt: new Date().toISOString(),
 					bounceType: 'hard',
 				})
+				emitMailerAnalyticsEvent(options, env, 'newsletter_send_failed', {
+					contentSlug: recipient.trackingId,
+					label: {
+						trackingId: recipient.trackingId,
+						subscriberId: recipient.subscriberId,
+						email: recipient.email,
+						campaignId: message.body.campaignId,
+						type,
+						error: result.error,
+					},
+				})
 				console.error(`[mailer] Send failed for ${recipient.email}: ${result.error}`)
 			}
 		}

package/src/routes/confirm.ts

@@ -1,13 +1,15 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
 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 { emitMailerAnalyticsEvent } from '../utils/analytics.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 }) => {
+export const GET: APIRoute = async (context) => {
+	const { url } = context
 	const token = url.searchParams.get('token')
 	if (!token) {
 		return Response.json({ error: 'Missing token' }, { status: 400 })
@@ -20,9 +22,9 @@ export const GET: APIRoute = async ({ url, locals }) => {
 	}
 
 	// 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 bindingsEnv = cloudflareEnv as Record<string, unknown>
+	const d1 = bindingsEnv[config.d1Binding] as D1Database
+	const queue = bindingsEnv[config.queueBinding] as Queue
 	const db = drizzle(d1)
 	const env: MailerEnv = { DB: d1, QUEUE: queue }
 
@@ -58,6 +60,15 @@ export const GET: APIRoute = async ({ url, locals }) => {
 		data: { name: subscriber.name },
 	})
 
+	emitMailerAnalyticsEvent(config, bindingsEnv, 'newsletter_confirmed', {
+		context,
+		contentSlug: subscriber.id,
+		label: {
+			subscriberId: subscriber.id,
+			email: subscriber.email,
+		},
+	})
+
 	// Redirect to site with confirmed flag
 	return new Response(null, {
 		status: 302,

package/src/routes/preferences.astro

@@ -1,5 +1,6 @@
 ---
 import { config } from "virtual:growth-labs/mailer/config";
+import { env as cloudflareEnv } from "cloudflare:workers";
 import { drizzle } from "drizzle-orm/d1";
 import PreferenceCenter from "../components/PreferenceCenter.astro";
 import {
@@ -50,16 +51,11 @@ 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 bindingsEnv = cloudflareEnv as Record<string, unknown>;
+const d1 = bindingsEnv[config.d1Binding] as D1Database;
+if (!d1) {
+	return new Response("D1 binding not available", { status: 500 });
 }
-
-const d1 = runtimeEnv[config.d1Binding] as D1Database;
 const db = drizzle(d1);
 
 // Handle POST (form submission)

package/src/routes/subscribe.ts

@@ -1,13 +1,15 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
 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 { emitMailerAnalyticsEvent } from '../utils/analytics.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 }) => {
+export const POST: APIRoute = async (context) => {
+	const { request } = context
 	// 1. Parse request body
 	const body = (await request.json()) as {
 		email?: string
@@ -48,9 +50,9 @@ export const POST: APIRoute = async ({ request, locals }) => {
 	}
 
 	// 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 bindingsEnv = cloudflareEnv as Record<string, unknown>
+	const d1 = bindingsEnv[config.d1Binding] as D1Database
+	const queue = bindingsEnv[config.queueBinding] as Queue
 	const db = drizzle(d1)
 	const env: MailerEnv = { DB: d1, QUEUE: queue }
 
@@ -92,6 +94,20 @@ export const POST: APIRoute = async ({ request, locals }) => {
 			})
 		}
 
+		emitMailerAnalyticsEvent(config, bindingsEnv, 'newsletter_subscribed', {
+			request,
+			context,
+			contentSlug: subscriber.id,
+			label: {
+				subscriberId: subscriber.id,
+				email: subscriber.email,
+				source: body.source ?? 'form',
+				preferences: body.preferences ?? [],
+				requiresConfirmation: config.doubleOptIn,
+				isNew,
+			},
+		})
+
 		// Return success (always 200 to avoid email enumeration)
 		return Response.json({
 			success: true,

package/src/routes/track-click.ts

@@ -1,10 +1,13 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
 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 { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 
-export const GET: APIRoute = async ({ params, url, locals }) => {
+export const GET: APIRoute = async (context) => {
+	const { params, request, url } = context
 	const trackingId = params.trackingId
 	const destination = url.searchParams.get('url')
 
@@ -24,13 +27,9 @@ export const GET: APIRoute = async ({ params, url, locals }) => {
 
 	// 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 bindingsEnv = cloudflareEnv as Record<string, unknown>
+		if (bindingsEnv) {
+			const d1 = bindingsEnv[config.d1Binding] as D1Database
 			const db = drizzle(d1)
 			await db
 				.update(emailSends)
@@ -49,6 +48,13 @@ export const GET: APIRoute = async ({ params, url, locals }) => {
 		// Never fail the redirect on DB errors
 	}
 
+	emitMailerAnalyticsEvent(config, cloudflareEnv as Record<string, unknown>, 'newsletter_clicked', {
+		request,
+		context,
+		contentSlug: trackingId,
+		label: { trackingId, destination },
+	})
+
 	// 302 redirect to original destination
 	return new Response(null, {
 		status: 302,

package/src/routes/track-open.ts

@@ -1,11 +1,14 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
 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 { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import { TRANSPARENT_GIF } from '../utils/tracking.js'
 
-export const GET: APIRoute = async ({ params, locals }) => {
+export const GET: APIRoute = async (context) => {
+	const { params, request } = context
 	const trackingId = params.trackingId
 	if (!trackingId) {
 		return new Response(null, { status: 400 })
@@ -14,13 +17,9 @@ export const GET: APIRoute = async ({ params, locals }) => {
 	// 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 bindingsEnv = cloudflareEnv as Record<string, unknown>
+		if (bindingsEnv) {
+			const d1 = bindingsEnv[config.d1Binding] as D1Database
 			const db = drizzle(d1)
 			await db
 				.update(emailSends)
@@ -39,6 +38,13 @@ export const GET: APIRoute = async ({ params, locals }) => {
 		// Never fail the pixel response on DB errors
 	}
 
+	emitMailerAnalyticsEvent(config, cloudflareEnv as Record<string, unknown>, 'newsletter_opened', {
+		request,
+		context,
+		contentSlug: trackingId,
+		label: { trackingId },
+	})
+
 	// 1x1 transparent GIF
 	return new Response(TRANSPARENT_GIF, {
 		status: 200,