@growth-labs/mailer 0.2.0 → 0.2.1

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,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,

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/virtual.d.ts

@@ -26,5 +26,6 @@ declare module 'virtual:growth-labs/mailer/config' {
 		}
 		batchSize: number
 		analyticsEnabled: boolean
+		analyticsBinding: string
 	}
 }