@growth-labs/mailer 0.2.0 → 0.2.2

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,

package/src/routes/unsubscribe.ts

@@ -1,14 +1,19 @@
+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 { 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) {
+async function processUnsubscribe(
+	token: string,
+	context?: Parameters<APIRoute>[0],
+	request?: Request,
+) {
 	// Verify token
 	const payload = await verifyToken(config.signingSecret, token)
 	if (!payload || payload.action !== 'unsubscribe') {
@@ -16,9 +21,9 @@ async function processUnsubscribe(locals: RuntimeLocals, token: string) {
 	}
 
 	// 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 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 }
 
@@ -43,6 +48,16 @@ async function processUnsubscribe(locals: RuntimeLocals, token: string) {
 		},
 	})
 
+	emitMailerAnalyticsEvent(config, bindingsEnv, 'newsletter_unsubscribed', {
+		request,
+		context,
+		contentSlug: subscriber.id,
+		label: {
+			subscriberId: subscriber.id,
+			email: subscriber.email,
+		},
+	})
+
 	return {
 		success: true,
 		subscriberId: payload.subscriberId,
@@ -50,13 +65,14 @@ async function processUnsubscribe(locals: RuntimeLocals, token: string) {
 }
 
 // GET: Link from email footer
-export const GET: APIRoute = async ({ url, locals }) => {
+export const GET: APIRoute = async (context) => {
+	const { url, request } = context
 	const token = url.searchParams.get('token')
 	if (!token) {
 		return Response.json({ error: 'Missing token' }, { status: 400 })
 	}
 
-	const result = await processUnsubscribe(locals as RuntimeLocals, token)
+	const result = await processUnsubscribe(token, context, request)
 	if ('error' in result) {
 		return Response.json({ error: result.error }, { status: result.status })
 	}
@@ -78,7 +94,8 @@ export const GET: APIRoute = async ({ url, locals }) => {
 }
 
 // POST: RFC 8058 List-Unsubscribe-Post
-export const POST: APIRoute = async ({ request, locals }) => {
+export const POST: APIRoute = async (context) => {
+	const { request } = context
 	// RFC 8058: body is "List-Unsubscribe=One-Click"
 	// Token comes from List-Unsubscribe header URL
 	const url = new URL(request.url)
@@ -87,7 +104,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		return new Response('Missing token', { status: 400 })
 	}
 
-	const result = await processUnsubscribe(locals as RuntimeLocals, token)
+	const result = await processUnsubscribe(token, context, request)
 	if ('error' in result) {
 		return new Response(result.error, { status: result.status })
 	}

package/src/routes/webhook.ts

@@ -1,7 +1,10 @@
+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 { emitMailerAnalyticsEvent, type MailerAnalyticsEvent } from '../utils/analytics.js'
 import { handleBounce, handleComplaint, handleDelivery } from '../utils/bounce.js'
+import { verifyWebhookSignature } from '../utils/webhook-signature.js'
 
 interface WebhookPayload {
 	type: 'bounce' | 'complaint' | 'delivery'
@@ -11,25 +14,44 @@ interface WebhookPayload {
 	timestamp: string
 }
 
-export const POST: APIRoute = async ({ request, locals }) => {
-	const body = (await request.json()) as WebhookPayload
+export const POST: APIRoute = async (context) => {
+	const { request } = context
+	const rawBody = await request.text()
+	const signatureValid = await verifyWebhookSignature(config.webhookSignature, request, rawBody)
+	if (!signatureValid) {
+		return Response.json({ error: 'Invalid webhook signature' }, { status: 401 })
+	}
 
-	if (!body.type || !body.email) {
+	let body: WebhookPayload
+	try {
+		body = JSON.parse(rawBody) as WebhookPayload
+	} catch {
 		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 })
+	if (!body.type || !body.email) {
+		return Response.json({ error: 'Invalid payload' }, { status: 400 })
 	}
 
-	const d1 = runtimeEnv[config.d1Binding] as D1Database
+	const bindingsEnv = cloudflareEnv as Record<string, unknown>
+	const d1 = bindingsEnv[config.d1Binding] as D1Database
+	if (!d1) {
+		return Response.json({ error: 'D1 binding not available' }, { status: 500 })
+	}
 	const db = drizzle(d1)
 
+	emitMailerAnalyticsEvent(config, bindingsEnv, 'newsletter_webhook_received', {
+		request,
+		context,
+		contentSlug: body.trackingId ?? body.email,
+		label: {
+			type: body.type,
+			email: body.email,
+			trackingId: body.trackingId,
+			bounceType: body.bounceType,
+		},
+	})
+
 	switch (body.type) {
 		case 'delivery':
 			if (body.trackingId) {
@@ -44,5 +66,27 @@ export const POST: APIRoute = async ({ request, locals }) => {
 			break
 	}
 
+	emitMailerAnalyticsEvent(config, bindingsEnv, eventForWebhookType(body.type), {
+		request,
+		context,
+		contentSlug: body.trackingId ?? body.email,
+		label: {
+			email: body.email,
+			trackingId: body.trackingId,
+			bounceType: body.bounceType,
+		},
+	})
+
 	return Response.json({ ok: true })
 }
+
+function eventForWebhookType(type: WebhookPayload['type']): MailerAnalyticsEvent {
+	switch (type) {
+		case 'delivery':
+			return 'newsletter_delivered'
+		case 'bounce':
+			return 'newsletter_bounced'
+		case 'complaint':
+			return 'newsletter_complained'
+	}
+}

package/src/utils/analytics.ts

@@ -0,0 +1,120 @@
+import type { ResolvedMailerOptions } from '../options.js'
+
+export type MailerAnalyticsEvent =
+	| 'newsletter_subscribed'
+	| 'newsletter_confirmed'
+	| 'newsletter_unsubscribed'
+	| 'newsletter_opened'
+	| 'newsletter_clicked'
+	| 'newsletter_webhook_received'
+	| 'newsletter_delivered'
+	| 'newsletter_bounced'
+	| 'newsletter_complained'
+	| 'newsletter_sent'
+	| 'newsletter_send_failed'
+
+interface AnalyticsBinding {
+	writeDataPoint(dataPoint: unknown): Promise<unknown>
+}
+
+interface AnalyticsContext {
+	locals?: {
+		cfContext?: {
+			waitUntil(promise: Promise<unknown>): void
+		}
+	}
+}
+
+interface EmitMailerAnalyticsOptions {
+	request?: Request
+	context?: AnalyticsContext
+	label?: Record<string, unknown>
+	contentSlug?: string
+	eventValue?: number
+}
+
+export function emitMailerAnalyticsEvent(
+	options: ResolvedMailerOptions,
+	bindingsEnv: Record<string, unknown>,
+	eventName: MailerAnalyticsEvent,
+	emitOptions: EmitMailerAnalyticsOptions = {},
+): boolean {
+	if (!options.analyticsEnabled) return false
+
+	const analyticsBinding = bindingsEnv[options.analyticsBinding] as AnalyticsBinding | undefined
+	if (!analyticsBinding?.writeDataPoint) return false
+
+	const dataPoint = buildMailerAnalyticsDataPoint(options, eventName, emitOptions)
+	const write = analyticsBinding.writeDataPoint(dataPoint)
+	const waitUntil = emitOptions.context?.locals?.cfContext?.waitUntil
+	if (waitUntil) {
+		waitUntil(write.catch(() => undefined))
+	} else {
+		void write.catch(() => undefined)
+	}
+	return true
+}
+
+export function buildMailerAnalyticsDataPoint(
+	options: ResolvedMailerOptions,
+	eventName: MailerAnalyticsEvent,
+	emitOptions: EmitMailerAnalyticsOptions = {},
+): { blobs: string[]; doubles: number[]; indexes: string[] } {
+	const url = emitOptions.request ? new URL(emitOptions.request.url) : new URL(options.siteUrl)
+	const siteId = siteIdFromUrl(options.siteUrl)
+	const label = emitOptions.label ? JSON.stringify(emitOptions.label) : ''
+
+	return {
+		blobs: [
+			eventName,
+			siteId,
+			'',
+			'',
+			url.toString(),
+			url.pathname,
+			emitOptions.request?.headers.get('referer') ?? '',
+			'',
+			'',
+			'',
+			'',
+			emitOptions.request?.headers.get('cf-ipcountry') ?? '',
+			'',
+			'',
+			'',
+			emitOptions.contentSlug ?? '',
+			'newsletter',
+			categoryForMailerEvent(eventName),
+			label,
+			'false',
+		],
+		doubles: [Date.now(), emitOptions.eventValue ?? 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+		indexes: [eventName],
+	}
+}
+
+function siteIdFromUrl(siteUrl: string): string {
+	try {
+		return new URL(siteUrl).hostname.replace(/^www\./, '')
+	} catch {
+		return siteUrl
+	}
+}
+
+function categoryForMailerEvent(eventName: MailerAnalyticsEvent): string {
+	switch (eventName) {
+		case 'newsletter_subscribed':
+		case 'newsletter_confirmed':
+			return 'conversion'
+		case 'newsletter_opened':
+		case 'newsletter_clicked':
+			return 'interaction'
+		case 'newsletter_webhook_received':
+		case 'newsletter_delivered':
+		case 'newsletter_bounced':
+		case 'newsletter_complained':
+		case 'newsletter_sent':
+		case 'newsletter_send_failed':
+		case 'newsletter_unsubscribed':
+			return 'newsletter'
+	}
+}

package/src/utils/bindings.ts

@@ -1,25 +1,23 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
 import { config } from 'virtual:growth-labs/mailer/config'
 import { drizzle } from 'drizzle-orm/d1'
 
 type DrizzleDB = ReturnType<typeof drizzle>
 
-export interface RuntimeLocals {
-	runtime?: { env: Record<string, unknown> }
-}
-
 /**
- * Resolve Cloudflare bindings from the runtime environment object.
+ * Resolve Cloudflare bindings from the Astro 6 Cloudflare Workers env object.
  *
- * Route handlers call this with `context.locals.runtime.env` (the standard
- * Astro 6 + @astrojs/cloudflare adapter pattern). Binding names come from
- * the virtual config so they stay in sync with the consumer's `astro.config`.
+ * Binding names come from the virtual config so they stay in sync with the
+ * consumer's `astro.config`.
  */
-export function resolveBindings(runtimeEnv: Record<string, unknown>): {
+export function resolveBindings(
+	bindingsEnv: Record<string, unknown> = cloudflareEnv as Record<string, unknown>,
+): {
 	db: DrizzleDB
 	queue: Queue
 } {
-	const d1 = runtimeEnv[config.d1Binding] as D1Database
-	const queue = runtimeEnv[config.queueBinding] as Queue
+	const d1 = bindingsEnv[config.d1Binding] as D1Database
+	const queue = bindingsEnv[config.queueBinding] as Queue
 
 	if (!d1) throw new Error(`[mailer] D1 binding "${config.d1Binding}" not found`)
 	if (!queue) throw new Error(`[mailer] Queue binding "${config.queueBinding}" not found`)

package/src/utils/index.ts

@@ -1,3 +1,8 @@
+export {
+	buildMailerAnalyticsDataPoint,
+	emitMailerAnalyticsEvent,
+	type MailerAnalyticsEvent,
+} from './analytics.js'
 export {
 	handleBounce,
 	handleComplaint,
@@ -5,11 +10,7 @@ export {
 	updateSendStatus,
 } from './bounce.js'
 export type { CloudflareEmailSender } from './providers.js'
-export {
-	CloudflareEmailProvider,
-	getProvider,
-	sleep,
-} from './providers.js'
+export { CloudflareEmailProvider, getProvider, sleep } from './providers.js'
 export type { CampaignSchedule, DigestSchedule } from './scheduling.js'
 export {
 	executeCampaignSchedule,
@@ -43,3 +44,4 @@ export {
 	rewriteLinksForTracking,
 	TRANSPARENT_GIF,
 } from './tracking.js'
+export { signWebhookPayload, verifyWebhookSignature } from './webhook-signature.js'

package/src/utils/providers.ts

@@ -44,7 +44,7 @@ export class CloudflareEmailProvider implements EmailProvider {
 	}
 }
 
-// ─── Factory functions ───
+// ─── Factory function ───
 
 export function getProvider(emailSender: CloudflareEmailSender): EmailProvider {
 	return new CloudflareEmailProvider(emailSender)

package/src/utils/webhook-signature.ts

@@ -0,0 +1,91 @@
+import type { ResolvedMailerOptions } from '../options.js'
+
+type WebhookSignatureOptions = ResolvedMailerOptions['webhookSignature']
+
+export async function verifyWebhookSignature(
+	options: WebhookSignatureOptions,
+	request: Request,
+	body: string,
+	nowMs: number = Date.now(),
+): Promise<boolean> {
+	if (!options.enabled) return true
+
+	const timestamp = request.headers.get(options.timestampHeader)
+	const signatureHeader = request.headers.get(options.header)
+	if (!timestamp || !signatureHeader) return false
+
+	if (!timestampWithinTolerance(timestamp, options.toleranceSeconds, nowMs)) return false
+
+	const signature = signatureFromHeader(signatureHeader)
+	if (!signature) return false
+
+	const key = await importWebhookKey(options.secret)
+	const signedBody = `${timestamp}.${body}`
+	return crypto.subtle.verify(
+		'HMAC',
+		key,
+		fromBase64Url(signature),
+		new TextEncoder().encode(signedBody),
+	)
+}
+
+export async function signWebhookPayload(
+	secret: string,
+	timestamp: string,
+	body: string,
+): Promise<string> {
+	const key = await importWebhookKey(secret)
+	const signature = await crypto.subtle.sign(
+		'HMAC',
+		key,
+		new TextEncoder().encode(`${timestamp}.${body}`),
+	)
+	return toBase64Url(signature)
+}
+
+function timestampWithinTolerance(
+	timestamp: string,
+	toleranceSeconds: number,
+	nowMs: number,
+): boolean {
+	if (toleranceSeconds === 0) return true
+	const parsed = Number(timestamp)
+	if (!Number.isFinite(parsed)) return false
+	const timestampMs = parsed > 1_000_000_000_000 ? parsed : parsed * 1000
+	return Math.abs(nowMs - timestampMs) <= toleranceSeconds * 1000
+}
+
+function signatureFromHeader(header: string): string | null {
+	const parts = header.split(',').map((part) => part.trim())
+	for (const part of parts) {
+		if (part.startsWith('v1=')) return part.slice(3)
+	}
+	return parts[0] || null
+}
+
+async function importWebhookKey(secret: string): Promise<CryptoKey> {
+	return crypto.subtle.importKey(
+		'raw',
+		new TextEncoder().encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign', 'verify'],
+	)
+}
+
+function fromBase64Url(value: string): Uint8Array<ArrayBuffer> {
+	const padded = value
+		.replace(/-/g, '+')
+		.replace(/_/g, '/')
+		.padEnd(Math.ceil(value.length / 4) * 4, '=')
+	const binary = atob(padded)
+	const bytes = new Uint8Array(new ArrayBuffer(binary.length))
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+	return bytes
+}
+
+function toBase64Url(bytes: ArrayBuffer): string {
+	let binary = ''
+	for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte)
+	return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}

package/src/virtual.d.ts

@@ -15,6 +15,20 @@ declare module 'virtual:growth-labs/mailer/config' {
 		unsubscribePath: string
 		preferencesPath: string
 		webhookPath: string
+		webhookSignature:
+			| {
+					enabled: false
+					header: string
+					timestampHeader: string
+					toleranceSeconds: number
+			  }
+			| {
+					enabled: true
+					secret: string
+					header: string
+					timestampHeader: string
+					toleranceSeconds: number
+			  }
 		trackOpenPath: string
 		trackClickPath: string
 		siteUrl: string
@@ -26,5 +40,6 @@ declare module 'virtual:growth-labs/mailer/config' {
 		}
 		batchSize: number
 		analyticsEnabled: boolean
+		analyticsBinding: string
 	}
 }