@growth-labs/mailer 0.3.0 → 0.4.1

package/src/queue/consumer.ts

@@ -1,48 +1,116 @@
 import { drizzle } from 'drizzle-orm/d1'
-import { probeMailerSchema } from '../_internal/schema-probe.js'
-import type { ResolvedMailerOptions } from '../options.js'
-import type { EmailProvider, EmailQueueMessage } from '../types.js'
+import { probeMailerSendsSchema } from '../_internal/schema-probe.js'
+import type { EmailQueueMessage, SiteConfigLookup, SiteMailerConfig } from '../types.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import { updateSendStatus } from '../utils/bounce.js'
 import type { CloudflareEmailSender } from '../utils/providers.js'
 import { CloudflareEmailProvider, sleep } from '../utils/providers.js'
 
+export type { SiteConfigLookup, SiteMailerConfig } from '../types.js'
+
+export interface MailerConsumerOptions {
+	d1Binding: string
+	senderBinding: string
+	analyticsBinding?: string
+	siteConfigLookup: SiteConfigLookup
+}
+
+/** Effective options for a single message, resolved from `siteConfigLookup`. */
+interface EffectiveOptions {
+	siteUrl?: string
+	unsubscribePath: string
+	preferencesPath: string
+	senderName?: string
+	fromAddress?: string
+	replyTo?: string
+}
+
+function applySiteConfig(config: SiteMailerConfig): EffectiveOptions {
+	return {
+		siteUrl: config.siteUrl,
+		unsubscribePath: config.unsubscribePath ?? '/api/newsletter/unsubscribe',
+		preferencesPath: config.preferencesPath ?? '/email/preferences',
+		senderName: config.senderName,
+		fromAddress: config.fromAddress,
+		replyTo: config.replyTo,
+	}
+}
+
 export async function handleEmailQueue(
 	batch: MessageBatch<EmailQueueMessage>,
-	env: {
-		DB: D1Database
-		EMAIL_SENDER?: CloudflareEmailSender
-		[key: string]: unknown
-	},
-	options: ResolvedMailerOptions,
+	env: Record<string, unknown>,
+	options: MailerConsumerOptions,
 ): Promise<void> {
+	const d1 = env[options.d1Binding] as D1Database | undefined
+	if (!d1) {
+		throw new Error(
+			`[mailer] env.${options.d1Binding} is undefined; ` +
+				'pass d1Binding option to the mailer integration or bind that name in wrangler.toml.',
+		)
+	}
+
+	const sender = env[options.senderBinding] as CloudflareEmailSender | undefined
+	if (!sender) {
+		throw new Error(
+			`[mailer] env.${options.senderBinding} is undefined; ` +
+				'pass senderBinding option to the mailer integration or bind a [[send_email]] entry of that name.',
+		)
+	}
+
 	// Schema probe — runs once per Worker instance. On miss the probe logs
 	// GL_MAILER_SCHEMA_MISSING and we ack every message in the batch without
 	// retry. Re-queueing without the schema would cycle indefinitely and burn
 	// Cloudflare Queue retry budget.
-	const schemaProbe = await probeMailerSchema(env.DB, options.d1Binding)
+	const schemaProbe = await probeMailerSendsSchema(d1, options.d1Binding)
 	if (!schemaProbe.ok) {
+		console.error(
+			'[mailer] gl_email_sends not found in env.' +
+				options.d1Binding +
+				' — apply mailer migrations before processing queue. ' +
+				'Acking ' +
+				batch.messages.length +
+				' message(s) to avoid retry storm.',
+		)
 		for (const message of batch.messages) {
 			message.ack()
 		}
 		return
 	}
 
-	const db = drizzle(env.DB)
-	const provider: EmailProvider = env.EMAIL_SENDER
-		? new CloudflareEmailProvider(env.EMAIL_SENDER)
-		: new CloudflareEmailProvider({
-				send: () => Promise.reject(new Error('No email sender configured')),
-			})
+	const db = drizzle(d1)
+	const provider = new CloudflareEmailProvider(sender)
 
 	for (const message of batch.messages) {
+		const siteConfig = await options.siteConfigLookup(message.body.siteId, env)
+		if (!siteConfig) {
+			console.error(
+				`[mailer] No SiteMailerConfig for siteId=${message.body.siteId}; acking without send.`,
+			)
+			message.ack()
+			continue
+		}
+		const effective = applySiteConfig(siteConfig)
+
 		const { recipients, htmlTemplate, subject, from, replyTo, headers, type } = message.body
+		if (type !== 'transactional' && !effective.siteUrl) {
+			console.error(
+				`[mailer] SiteMailerConfig for siteId=${message.body.siteId} is missing siteUrl; acking without send.`,
+			)
+			message.ack()
+			continue
+		}
+
+		const effectiveFrom = effective.fromAddress
+			? formatFromHeader(effective.senderName ?? effective.fromAddress, effective.fromAddress)
+			: from
+		const effectiveReplyTo = effective.replyTo ?? replyTo
 
 		for (const recipient of recipients) {
 			let html = htmlTemplate
 			if (type !== 'transactional') {
-				const unsubscribeUrl = `${options.siteUrl}${options.unsubscribePath}?token=${recipient.unsubscribeToken}`
-				const preferencesUrl = `${options.siteUrl}${options.preferencesPath}?token=${recipient.preferencesToken}`
+				const siteUrl = effective.siteUrl ?? ''
+				const unsubscribeUrl = `${siteUrl}${effective.unsubscribePath}?token=${recipient.unsubscribeToken}`
+				const preferencesUrl = `${siteUrl}${effective.preferencesPath}?token=${recipient.preferencesToken}`
 				html = html
 					.replaceAll('{{TRACKING_ID}}', recipient.trackingId)
 					.replaceAll('{{UNSUBSCRIBE_URL}}', unsubscribeUrl)
@@ -53,15 +121,15 @@ export async function handleEmailQueue(
 				type !== 'transactional'
 					? {
 							...headers,
-							'List-Unsubscribe': `<${options.siteUrl}${options.unsubscribePath}?token=${recipient.unsubscribeToken}>`,
+							'List-Unsubscribe': `<${effective.siteUrl ?? ''}${effective.unsubscribePath}?token=${recipient.unsubscribeToken}>`,
 							'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
 						}
 					: headers
 
 			let result = await provider.send({
 				to: recipient.email,
-				from,
-				replyTo,
+				from: effectiveFrom,
+				replyTo: effectiveReplyTo,
 				subject,
 				html,
 				headers: recipientHeaders,
@@ -72,8 +140,8 @@ export async function handleEmailQueue(
 					await sleep(2 ** attempt * 1000)
 					result = await provider.send({
 						to: recipient.email,
-						from,
-						replyTo,
+						from: effectiveFrom,
+						replyTo: effectiveReplyTo,
 						subject,
 						html,
 						headers: recipientHeaders,
@@ -86,32 +154,44 @@ export async function handleEmailQueue(
 				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,
+				emitMailerAnalyticsEvent(
+					analyticsOptions(options, effective, message.body.siteId),
+					env,
+					'newsletter_sent',
+					{
+						contentSlug: recipient.trackingId,
+						label: {
+							trackingId: recipient.trackingId,
+							subscriberId: recipient.subscriberId,
+							email: recipient.email,
+							campaignId: message.body.campaignId,
+							type,
+							siteId: message.body.siteId,
+						},
 					},
-				})
+				)
 			} 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,
+				emitMailerAnalyticsEvent(
+					analyticsOptions(options, effective, message.body.siteId),
+					env,
+					'newsletter_send_failed',
+					{
+						contentSlug: recipient.trackingId,
+						label: {
+							trackingId: recipient.trackingId,
+							subscriberId: recipient.subscriberId,
+							email: recipient.email,
+							campaignId: message.body.campaignId,
+							type,
+							siteId: message.body.siteId,
+							error: result.error,
+						},
 					},
-				})
+				)
 				console.error(`[mailer] Send failed for ${recipient.email}: ${result.error}`)
 			}
 		}
@@ -119,3 +199,23 @@ export async function handleEmailQueue(
 		message.ack()
 	}
 }
+
+function formatFromHeader(senderName: string, fromAddress: string): string {
+	return `${senderName} <${fromAddress}>`
+}
+
+function analyticsOptions(
+	options: MailerConsumerOptions,
+	effective: EffectiveOptions,
+	siteId: string,
+): {
+	siteUrl: string
+	analyticsEnabled: boolean
+	analyticsBinding: string
+} {
+	return {
+		siteUrl: effective.siteUrl ?? `https://${siteId}`,
+		analyticsEnabled: Boolean(options.analyticsBinding),
+		analyticsBinding: options.analyticsBinding ?? 'ANALYTICS',
+	}
+}

package/src/routes/track-click.ts

@@ -4,7 +4,7 @@ import type { APIRoute } from 'astro'
 import { and, eq, inArray } from 'drizzle-orm'
 import { drizzle } from 'drizzle-orm/d1'
 import { probeMailerSchema } from '../_internal/schema-probe.js'
-import { emailSends } from '../schema.js'
+import { emailSends } from '../schema/sends.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 
 export const GET: APIRoute = async (context) => {

package/src/routes/track-open.ts

@@ -4,7 +4,7 @@ import type { APIRoute } from 'astro'
 import { and, eq, inArray } from 'drizzle-orm'
 import { drizzle } from 'drizzle-orm/d1'
 import { probeMailerSchema } from '../_internal/schema-probe.js'
-import { emailSends } from '../schema.js'
+import { emailSends } from '../schema/sends.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import { TRANSPARENT_GIF } from '../utils/tracking.js'
 

package/src/schema/index.ts

@@ -0,0 +1,2 @@
+export { emailSends } from './sends.js'
+export { subscribers } from './subscribers.js'

package/src/schema/sends.ts

@@ -0,0 +1,30 @@
+import { index, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+export const emailSends = sqliteTable(
+	'gl_email_sends',
+	{
+		id: text('id').primaryKey(),
+		subscriberId: text('subscriber_id').notNull(),
+		campaignId: text('campaign_id'),
+		email: text('email').notNull(),
+		subject: text('subject').notNull(),
+		type: text('type').notNull(),
+		status: text('status').notNull().default('queued'),
+		sentAt: text('sent_at'),
+		deliveredAt: text('delivered_at'),
+		openedAt: text('opened_at'),
+		clickedAt: text('clicked_at'),
+		bouncedAt: text('bounced_at'),
+		bounceType: text('bounce_type'),
+		complainedAt: text('complained_at'),
+		trackingId: text('tracking_id').notNull().unique(),
+		createdAt: text('created_at').notNull(),
+	},
+	(table) => [
+		index('idx_sends_subscriber').on(table.subscriberId),
+		index('idx_sends_campaign').on(table.campaignId),
+		index('idx_sends_tracking').on(table.trackingId),
+		index('idx_sends_status').on(table.status),
+		index('idx_sends_type_created').on(table.type, table.createdAt),
+	],
+)

package/src/schema/subscribers.ts

@@ -0,0 +1,25 @@
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+export const subscribers = sqliteTable(
+	'gl_subscribers',
+	{
+		id: text('id').primaryKey(),
+		email: text('email').notNull().unique(),
+		name: text('name'),
+		status: text('status').notNull().default('pending'),
+		preferences: text('preferences').notNull().default('[]'),
+		source: text('source').notNull(),
+		attribution: text('attribution'),
+		softBounceCount: integer('soft_bounce_count').notNull().default(0),
+		subscribedAt: text('subscribed_at').notNull(),
+		confirmedAt: text('confirmed_at'),
+		unsubscribedAt: text('unsubscribed_at'),
+		createdAt: text('created_at').notNull(),
+		updatedAt: text('updated_at').notNull(),
+	},
+	(table) => [
+		index('idx_subscribers_status').on(table.status),
+		index('idx_subscribers_email').on(table.email),
+		index('idx_subscribers_subscribed_at').on(table.subscribedAt),
+	],
+)

package/src/types.ts

@@ -38,6 +38,7 @@ export interface SubscriberFilter {
 // ─── Email Queue message ───
 
 export interface EmailQueueMessage {
+	siteId: string
 	type: 'transactional' | 'campaign' | 'digest'
 	recipients: QueueRecipient[]
 	subject: string
@@ -48,6 +49,39 @@ export interface EmailQueueMessage {
 	campaignId?: string
 }
 
+// ─── Realm-level multi-tenant config lookup ───
+
+/**
+ * Per-site config resolved at consumer time. Realm consumers keep bindings in
+ * their own Worker config and load sender / URL metadata from this object for
+ * every queued message.
+ */
+export interface SiteMailerConfig {
+	siteUrl?: string
+	unsubscribePath?: string
+	preferencesPath?: string
+	senderName?: string
+	fromAddress?: string
+	replyTo?: string
+	signingSecret?: string
+	brand?: {
+		logoUrl?: string
+		primaryColor?: string
+		accentColor?: string
+		footerText?: string
+	}
+}
+
+/**
+ * Per-message lookup, called by the realm consumer with the message's
+ * `siteId`. Returns the per-site config to apply, or `null` when the consumer
+ * should ack the message without sending because the registry entry is absent.
+ */
+export type SiteConfigLookup = (
+	siteId: string,
+	env: Record<string, unknown>,
+) => Promise<SiteMailerConfig | null>
+
 export interface QueueRecipient {
 	email: string
 	subscriberId: string

package/src/utils/analytics.ts

@@ -1,5 +1,3 @@
-import type { ResolvedMailerOptions } from '../options.js'
-
 export type MailerAnalyticsEvent =
 	| 'newsletter_subscribed'
 	| 'newsletter_confirmed'
@@ -25,6 +23,12 @@ interface AnalyticsContext {
 	}
 }
 
+export interface MailerAnalyticsRuntimeOptions {
+	siteUrl: string
+	analyticsEnabled: boolean
+	analyticsBinding: string
+}
+
 interface EmitMailerAnalyticsOptions {
 	request?: Request
 	context?: AnalyticsContext
@@ -34,7 +38,7 @@ interface EmitMailerAnalyticsOptions {
 }
 
 export function emitMailerAnalyticsEvent(
-	options: ResolvedMailerOptions,
+	options: MailerAnalyticsRuntimeOptions,
 	bindingsEnv: Record<string, unknown>,
 	eventName: MailerAnalyticsEvent,
 	emitOptions: EmitMailerAnalyticsOptions = {},
@@ -56,7 +60,7 @@ export function emitMailerAnalyticsEvent(
 }
 
 export function buildMailerAnalyticsDataPoint(
-	options: ResolvedMailerOptions,
+	options: MailerAnalyticsRuntimeOptions,
 	eventName: MailerAnalyticsEvent,
 	emitOptions: EmitMailerAnalyticsOptions = {},
 ): { blobs: string[]; doubles: number[]; indexes: string[] } {

package/src/utils/bounce.ts

@@ -1,6 +1,7 @@
 import { eq, sql } from 'drizzle-orm'
 import type { drizzle } from 'drizzle-orm/d1'
-import { emailSends, subscribers } from '../schema.js'
+import { emailSends } from '../schema/sends.js'
+import { subscribers } from '../schema/subscribers.js'
 
 type DrizzleDB = ReturnType<typeof drizzle>
 

package/src/utils/send.ts

@@ -2,7 +2,7 @@ import { eq } from 'drizzle-orm'
 import { drizzle } from 'drizzle-orm/d1'
 import { ulid } from 'ulidx'
 import type { ResolvedMailerOptions } from '../options.js'
-import { emailSends } from '../schema.js'
+import { emailSends } from '../schema/sends.js'
 import type {
 	DigestItem,
 	EmailQueueMessage,
@@ -21,9 +21,38 @@ type DrizzleDB = ReturnType<typeof drizzle>
 
 // ─── MailerEnv ───
 
-export interface MailerEnv {
-	DB: D1Database
-	QUEUE: Queue
+/**
+ * Producer-side env. The actual binding *names* come from
+ * `options.d1Binding` / `options.queueBinding` (default `SITE_DB` /
+ * `EMAIL_QUEUE`); MailerEnv is a generic record so consumers can pass
+ * their full Worker env without renaming bindings.
+ */
+export type MailerEnv = Record<string, unknown>
+
+interface ResolvedProducerBindings {
+	db: DrizzleDB
+	queue: Queue
+}
+
+function resolveProducerBindings(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+): ResolvedProducerBindings {
+	const d1 = env[options.d1Binding] as D1Database | undefined
+	if (!d1) {
+		throw new Error(
+			`[mailer] env.${options.d1Binding} is undefined; ` +
+				'pass d1Binding option to the mailer integration or bind that name in wrangler.toml.',
+		)
+	}
+	const queue = env[options.queueBinding] as Queue | undefined
+	if (!queue) {
+		throw new Error(
+			`[mailer] env.${options.queueBinding} is undefined; ` +
+				'pass queueBinding option to the mailer integration or bind that name in wrangler.toml.',
+		)
+	}
+	return { db: drizzle(d1), queue }
 }
 
 // ─── sendTransactional ───
@@ -40,7 +69,7 @@ export async function sendTransactional(
 		data?: Record<string, unknown>
 	},
 ): Promise<{ trackingId: string }> {
-	const db = drizzle(env.DB)
+	const { db, queue } = resolveProducerBindings(env, options)
 	const trackingId = ulid()
 	const subscriberId = params.subscriberId ?? ulid()
 
@@ -76,6 +105,7 @@ export async function sendTransactional(
 
 	// Build and enqueue the message
 	const message: EmailQueueMessage = {
+		siteId: options.siteId,
 		type: 'transactional',
 		recipients: [
 			{
@@ -92,7 +122,7 @@ export async function sendTransactional(
 		replyTo: options.replyTo,
 	}
 
-	await env.QUEUE.send(message)
+	await queue.send(message)
 
 	return { trackingId }
 }
@@ -100,7 +130,7 @@ export async function sendTransactional(
 // ─── Fan-out helper (shared by campaign + digest) ───
 
 async function fanOutToSubscribers(
-	env: MailerEnv,
+	queue: Queue,
 	db: DrizzleDB,
 	options: ResolvedMailerOptions,
 	params: {
@@ -154,6 +184,7 @@ async function fanOutToSubscribers(
 		}
 
 		const message: EmailQueueMessage = {
+			siteId: options.siteId,
 			type: params.type,
 			recipients,
 			subject: params.subject,
@@ -162,7 +193,7 @@ async function fanOutToSubscribers(
 			replyTo: options.replyTo,
 			campaignId: params.campaignId,
 		}
-		await env.QUEUE.send(message)
+		await queue.send(message)
 
 		recipientCount += batch.length
 		cursor = batch[batch.length - 1].id
@@ -186,7 +217,7 @@ export async function sendCampaign(
 	},
 ): Promise<{ campaignId: string; recipientCount: number }> {
 	const campaignId = params.campaignId ?? ulid()
-	const db = drizzle(env.DB)
+	const { db, queue } = resolveProducerBindings(env, options)
 
 	// Render HTML
 	let html: string
@@ -211,7 +242,7 @@ export async function sendCampaign(
 	html = injectTrackingPixel(html, trackOpenUrl)
 	html = rewriteLinksForTracking(html, trackClickUrl)
 
-	const recipientCount = await fanOutToSubscribers(env, db, options, {
+	const recipientCount = await fanOutToSubscribers(queue, db, options, {
 		subject: params.subject,
 		html,
 		campaignId,
@@ -236,7 +267,7 @@ export async function sendDigest(
 	},
 ): Promise<{ campaignId: string; recipientCount: number }> {
 	const campaignId = params.campaignId ?? ulid()
-	const db = drizzle(env.DB)
+	const { db, queue } = resolveProducerBindings(env, options)
 
 	// Render digest items then full template
 	const itemsHtml = renderDigestItems(params.items)
@@ -256,7 +287,7 @@ export async function sendDigest(
 	html = injectTrackingPixel(html, trackOpenUrl)
 	html = rewriteLinksForTracking(html, trackClickUrl)
 
-	const recipientCount = await fanOutToSubscribers(env, db, options, {
+	const recipientCount = await fanOutToSubscribers(queue, db, options, {
 		subject: params.subject,
 		html,
 		campaignId,

package/src/utils/subscribers.ts

@@ -1,7 +1,7 @@
 import { and, eq, gt, inArray, like, lt, or, sql } from 'drizzle-orm'
 import type { drizzle } from 'drizzle-orm/d1'
 import { ulid } from 'ulidx'
-import { subscribers } from '../schema.js'
+import { subscribers } from '../schema/subscribers.js'
 import type { Subscriber, SubscriberAttribution, SubscriberFilter } from '../types.js'
 
 type DrizzleDB = ReturnType<typeof drizzle>

package/src/virtual.d.ts

@@ -1,10 +1,14 @@
 declare module 'virtual:growth-labs/mailer/config' {
+	import type { SiteConfigLookup } from './types.js'
 	export const config: {
+		siteId: string
 		senderName: string
 		fromAddress: string
 		replyTo?: string
 		d1Binding: string
 		queueBinding: string
+		senderBinding: string
+		siteConfigLookup?: SiteConfigLookup
 		turnstileSiteKey: string
 		turnstileSecretKey: string
 		doubleOptIn: boolean

package/src/schema.ts

@@ -1,56 +0,0 @@
-import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
-
-export const subscribers = sqliteTable(
-	'gl_subscribers',
-	{
-		id: text('id').primaryKey(),
-		email: text('email').notNull().unique(),
-		name: text('name'),
-		status: text('status').notNull().default('pending'),
-		preferences: text('preferences').notNull().default('[]'),
-		source: text('source').notNull(),
-		attribution: text('attribution'),
-		softBounceCount: integer('soft_bounce_count').notNull().default(0),
-		subscribedAt: text('subscribed_at').notNull(),
-		confirmedAt: text('confirmed_at'),
-		unsubscribedAt: text('unsubscribed_at'),
-		createdAt: text('created_at').notNull(),
-		updatedAt: text('updated_at').notNull(),
-	},
-	(table) => [
-		index('idx_subscribers_status').on(table.status),
-		index('idx_subscribers_email').on(table.email),
-		index('idx_subscribers_subscribed_at').on(table.subscribedAt),
-	],
-)
-
-export const emailSends = sqliteTable(
-	'gl_email_sends',
-	{
-		id: text('id').primaryKey(),
-		subscriberId: text('subscriber_id')
-			.notNull()
-			.references(() => subscribers.id),
-		campaignId: text('campaign_id'),
-		email: text('email').notNull(),
-		subject: text('subject').notNull(),
-		type: text('type').notNull(),
-		status: text('status').notNull().default('queued'),
-		sentAt: text('sent_at'),
-		deliveredAt: text('delivered_at'),
-		openedAt: text('opened_at'),
-		clickedAt: text('clicked_at'),
-		bouncedAt: text('bounced_at'),
-		bounceType: text('bounce_type'),
-		complainedAt: text('complained_at'),
-		trackingId: text('tracking_id').notNull().unique(),
-		createdAt: text('created_at').notNull(),
-	},
-	(table) => [
-		index('idx_sends_subscriber').on(table.subscriberId),
-		index('idx_sends_campaign').on(table.campaignId),
-		index('idx_sends_tracking').on(table.trackingId),
-		index('idx_sends_status').on(table.status),
-		index('idx_sends_type_created').on(table.type, table.createdAt),
-	],
-)