@growth-labs/mailer 0.1.3 → 0.2.1

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,6 +1,8 @@
+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'
 
 interface WebhookPayload {
@@ -11,23 +13,19 @@ interface WebhookPayload {
 	timestamp: string
 }
 
-export const POST: APIRoute = async ({ request, locals }) => {
+export const POST: APIRoute = async (context) => {
+	const { request } = context
 	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 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 d1 = runtimeEnv[config.d1Binding] as D1Database
 	const db = drizzle(d1)
 
 	switch (body.type) {
@@ -44,5 +42,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,118 @@
+import type { ResolvedMailerOptions } from '../options.js'
+
+export type MailerAnalyticsEvent =
+	| 'newsletter_subscribed'
+	| 'newsletter_confirmed'
+	| 'newsletter_unsubscribed'
+	| 'newsletter_opened'
+	| 'newsletter_clicked'
+	| '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_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,13 +10,7 @@ export {
 	updateSendStatus,
 } from './bounce.js'
 export type { CloudflareEmailSender } from './providers.js'
-export {
-	CloudflareEmailProvider,
-	getFallbackProvider,
-	getProvider,
-	ResendFallbackProvider,
-	sleep,
-} from './providers.js'
+export { CloudflareEmailProvider, getProvider, sleep } from './providers.js'
 export type { CampaignSchedule, DigestSchedule } from './scheduling.js'
 export {
 	executeCampaignSchedule,

package/src/utils/providers.ts

@@ -44,79 +44,12 @@ export class CloudflareEmailProvider implements EmailProvider {
 	}
 }
 
-// ─── ResendFallbackProvider ───
-
-export class ResendFallbackProvider implements EmailProvider {
-	readonly name = 'resend'
-	private readonly apiKey: string
-
-	constructor(apiKey: string) {
-		this.apiKey = apiKey
-	}
-
-	async send(email: OutboundEmail): Promise<SendResult> {
-		try {
-			const response = await fetch('https://api.resend.com/emails', {
-				method: 'POST',
-				headers: {
-					Authorization: `Bearer ${this.apiKey}`,
-					'Content-Type': 'application/json',
-				},
-				body: JSON.stringify({
-					to: email.to,
-					from: email.from,
-					reply_to: email.replyTo,
-					subject: email.subject,
-					html: email.html,
-					headers: email.headers,
-				}),
-			})
-
-			if (response.ok) {
-				const data = (await response.json()) as { id?: string }
-				return {
-					success: true,
-					messageId: data.id,
-					retryable: false,
-				}
-			}
-
-			const retryable = response.status === 429 || response.status >= 500
-			const errorText = await response.text().catch(() => 'Unknown error')
-
-			return {
-				success: false,
-				error: `Resend API ${response.status}: ${errorText}`,
-				retryable,
-			}
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err)
-			return {
-				success: false,
-				error: message,
-				retryable: true,
-			}
-		}
-	}
-}
-
-// ─── Factory functions ───
+// ─── Factory function ───
 
 export function getProvider(emailSender: CloudflareEmailSender): EmailProvider {
 	return new CloudflareEmailProvider(emailSender)
 }
 
-export function getFallbackProvider(options: {
-	fallbackProvider: string
-	resendApiKey?: string
-}): EmailProvider | null {
-	if (options.fallbackProvider === 'resend' && options.resendApiKey) {
-		return new ResendFallbackProvider(options.resendApiKey)
-	}
-
-	return null
-}
-
 // ─── Helpers ───
 
 export function sleep(ms: number): Promise<void> {

package/src/virtual.d.ts

@@ -24,9 +24,8 @@ declare module 'virtual:growth-labs/mailer/config' {
 			accentColor: string
 			footerText?: string
 		}
-		fallbackProvider: 'resend' | 'none'
-		resendApiKey?: string
 		batchSize: number
 		analyticsEnabled: boolean
+		analyticsBinding: string
 	}
 }