@growth-labs/mailer 0.2.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/mailer",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -35,7 +35,7 @@
       "import": "./dist/routes/*.js",
       "default": "./dist/routes/*.js"
     },
-    "./queue": {
+    "./consumer": {
       "types": "./dist/queue/consumer.d.ts",
       "import": "./dist/queue/consumer.js"
     },
@@ -44,12 +44,21 @@
       "import": "./src/components/*.astro"
     },
     "./schema": {
-      "types": "./dist/schema.d.ts",
-      "import": "./dist/schema.js"
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js"
+    },
+    "./schema/subscribers": {
+      "types": "./dist/schema/subscribers.d.ts",
+      "import": "./dist/schema/subscribers.js"
+    },
+    "./schema/sends": {
+      "types": "./dist/schema/sends.d.ts",
+      "import": "./dist/schema/sends.js"
     }
   },
   "files": [
     "dist",
+    "migrations",
     "src",
     "README.md"
   ],

package/src/_internal/schema-probe.ts

@@ -0,0 +1,89 @@
+// One-shot D1 schema probe with module-scoped cache. Mailer routes that touch
+// gl_subscribers / gl_email_sends call this before doing D1 work. On miss the
+// route returns 503 with the GL_MAILER_SCHEMA_MISSING code instead of letting
+// drizzle throw and falling into Astro's SSR error template.
+//
+// Does NOT throw. A throw here would recreate the silent-500 cascade that
+// motivates this release. The contract: schema missing → mailer disabled
+// for this Worker's lifetime, affected routes return 503 with a diagnostic
+// body, observability gets one loud error per instance startup.
+
+export const GL_MAILER_SCHEMA_MISSING = 'GL_MAILER_SCHEMA_MISSING'
+
+export type ProbeResult = { ok: boolean }
+
+interface D1PreparedStatement {
+	first<T = unknown>(): Promise<T | null>
+}
+
+interface D1DatabaseLike {
+	prepare(query: string): D1PreparedStatement
+}
+
+let _cached: ProbeResult | null = null
+
+/** @internal Reset the module-scoped cache — tests only. */
+export function _resetSchemaProbeCache(): void {
+	_cached = null
+}
+
+/**
+ * Probe the configured D1 binding for `gl_subscribers` AND `gl_email_sends`.
+ * Returns `{ ok: true }` on success, `{ ok: false }` on failure (either table
+ * missing). Caches the result on the first call per Worker instance.
+ *
+ * Does not throw. A missing binding is treated as `ok: false` and logged —
+ * mailer cannot function without D1, so unlike analytics this is loud rather
+ * than silent.
+ */
+export async function probeMailerSchema(
+	db: D1DatabaseLike | undefined,
+	d1Binding: string,
+): Promise<ProbeResult> {
+	if (_cached) return _cached
+	if (!db) {
+		logSchemaMissing(d1Binding, 'D1 binding is not bound')
+		_cached = { ok: false }
+		return _cached
+	}
+	try {
+		await db.prepare('SELECT 1 FROM gl_subscribers LIMIT 1').first()
+		await db.prepare('SELECT 1 FROM gl_email_sends LIMIT 1').first()
+		_cached = { ok: true }
+		return _cached
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err)
+		logSchemaMissing(d1Binding, message)
+		_cached = { ok: false }
+		return _cached
+	}
+}
+
+function logSchemaMissing(d1Binding: string, underlying: string): void {
+	console.error(
+		`[${GL_MAILER_SCHEMA_MISSING}] @growth-labs/mailer: D1 binding "${d1Binding}" is ` +
+			'missing one or both of the gl_subscribers / gl_email_sends tables.\n' +
+			'Remediation:\n' +
+			'  1. Add to wrangler.toml under your [[d1_databases]] block:\n' +
+			'       migrations_dir = "node_modules/@growth-labs/mailer/migrations"\n' +
+			`  2. Run: pnpm exec wrangler d1 migrations apply ${d1Binding} --remote\n` +
+			'See packages-docs/mailer-d1-migrations.md for the full guide.\n' +
+			'Mailer routes return 503 until the schema is present. ' +
+			`Underlying error: ${underlying}`,
+	)
+}
+
+/**
+ * Helper: build the standard 503 response mailer routes return on schema
+ * miss. The body shape is stable so observability dashboards can match on
+ * `code === 'GL_MAILER_SCHEMA_MISSING'`.
+ */
+export function schemaMissingResponse(): Response {
+	return Response.json(
+		{
+			error: 'Mailer schema is not initialized',
+			code: GL_MAILER_SCHEMA_MISSING,
+		},
+		{ status: 503 },
+	)
+}

package/src/index.ts

@@ -66,7 +66,6 @@ export default function mailer(userOptions: MailerOptions): AstroIntegration {
 export type { MailerOptions, ResolvedMailerOptions } from './options.js'
 // Re-export options and types
 export { mailerOptionsSchema } from './options.js'
-export { handleEmailQueue } from './queue/consumer.js'
 export type {
 	DigestItem,
 	EmailProvider,
@@ -75,6 +74,8 @@ export type {
 	EmailSendStatus,
 	OutboundEmail,
 	SendResult,
+	SiteConfigLookup,
+	SiteMailerConfig,
 	Subscriber,
 	SubscriberFilter,
 	SubscriberStatus,

package/src/options.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod'
+import type { SiteConfigLookup } from './types.js'
 
 export const mailerOptionsSchema = z.object({
 	// ─── Required ───
+	siteId: z.string().min(1),
 	senderName: z.string(),
 	fromAddress: z.string().email(),
 
@@ -11,6 +13,10 @@ export const mailerOptionsSchema = z.object({
 	// ─── Cloudflare bindings ───
 	d1Binding: z.string().default('SITE_DB'),
 	queueBinding: z.string().default('EMAIL_QUEUE'),
+	senderBinding: z.string().default('EMAIL_SENDER'),
+
+	// ─── Realm-level multi-tenant lookup (optional) ───
+	siteConfigLookup: z.custom<SiteConfigLookup>().optional(),
 
 	// ─── Turnstile (subscribe form) ───
 	turnstileSiteKey: z.string(),

package/src/queue/consumer.ts

@@ -1,35 +1,95 @@
 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 type { EmailQueueMessage, 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'
 
+/**
+ * Effective options for a single message — options merged with any
+ * SiteMailerConfig override returned by `siteConfigLookup`.
+ */
+interface EffectiveOptions {
+	siteUrl: string
+	unsubscribePath: string
+	preferencesPath: string
+}
+
+function applyOverride(
+	options: ResolvedMailerOptions,
+	override: SiteMailerConfig | null,
+): EffectiveOptions {
+	return {
+		siteUrl: override?.siteUrl ?? options.siteUrl,
+		unsubscribePath: override?.unsubscribePath ?? options.unsubscribePath,
+		preferencesPath: override?.preferencesPath ?? options.preferencesPath,
+	}
+}
+
 export async function handleEmailQueue(
 	batch: MessageBatch<EmailQueueMessage>,
-	env: {
-		DB: D1Database
-		EMAIL_SENDER?: CloudflareEmailSender
-		[key: string]: unknown
-	},
+	env: Record<string, unknown>,
 	options: ResolvedMailerOptions,
 ): Promise<void> {
-	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 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(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(d1)
+	const provider = new CloudflareEmailProvider(sender)
 
 	for (const message of batch.messages) {
+		const override =
+			options.siteConfigLookup && message.body.siteId
+				? await options.siteConfigLookup(message.body.siteId, env)
+				: null
+		const effective = applyOverride(options, override)
+
 		const { recipients, htmlTemplate, subject, from, replyTo, headers, type } = message.body
+		const effectiveFrom = override?.fromAddress
+			? formatFromHeader(override.senderName ?? options.senderName, override.fromAddress)
+			: from
+		const effectiveReplyTo = override?.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 unsubscribeUrl = `${effective.siteUrl}${effective.unsubscribePath}?token=${recipient.unsubscribeToken}`
+				const preferencesUrl = `${effective.siteUrl}${effective.preferencesPath}?token=${recipient.preferencesToken}`
 				html = html
 					.replaceAll('{{TRACKING_ID}}', recipient.trackingId)
 					.replaceAll('{{UNSUBSCRIBE_URL}}', unsubscribeUrl)
@@ -40,15 +100,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,
@@ -59,8 +119,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,
@@ -81,6 +141,7 @@ export async function handleEmailQueue(
 						email: recipient.email,
 						campaignId: message.body.campaignId,
 						type,
+						siteId: message.body.siteId,
 					},
 				})
 			} else {
@@ -96,6 +157,7 @@ export async function handleEmailQueue(
 						email: recipient.email,
 						campaignId: message.body.campaignId,
 						type,
+						siteId: message.body.siteId,
 						error: result.error,
 					},
 				})
@@ -106,3 +168,7 @@ export async function handleEmailQueue(
 		message.ack()
 	}
 }
+
+function formatFromHeader(senderName: string, fromAddress: string): string {
+	return `${senderName} <${fromAddress}>`
+}

package/src/routes/confirm.ts

@@ -2,6 +2,7 @@ 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 { probeMailerSchema, schemaMissingResponse } from '../_internal/schema-probe.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import type { MailerEnv } from '../utils/send.js'
 import { sendTransactional } from '../utils/send.js'
@@ -25,6 +26,11 @@ export const GET: APIRoute = async (context) => {
 	const bindingsEnv = cloudflareEnv as Record<string, unknown>
 	const d1 = bindingsEnv[config.d1Binding] as D1Database
 	const queue = bindingsEnv[config.queueBinding] as Queue
+
+	// Schema probe — return 503 with GL_MAILER_SCHEMA_MISSING on miss.
+	const schema = await probeMailerSchema(d1, config.d1Binding)
+	if (!schema.ok) return schemaMissingResponse()
+
 	const db = drizzle(d1)
 	const env: MailerEnv = { DB: d1, QUEUE: queue }
 

package/src/routes/subscribe.ts

@@ -2,6 +2,7 @@ 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 { probeMailerSchema, schemaMissingResponse } from '../_internal/schema-probe.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import type { MailerEnv } from '../utils/send.js'
 import { sendTransactional } from '../utils/send.js'
@@ -53,6 +54,12 @@ export const POST: APIRoute = async (context) => {
 	const bindingsEnv = cloudflareEnv as Record<string, unknown>
 	const d1 = bindingsEnv[config.d1Binding] as D1Database
 	const queue = bindingsEnv[config.queueBinding] as Queue
+
+	// 5a. Schema probe — runs once per Worker instance. On miss, return 503
+	// with GL_MAILER_SCHEMA_MISSING so the consumer's site doesn't 500-cascade.
+	const schema = await probeMailerSchema(d1, config.d1Binding)
+	if (!schema.ok) return schemaMissingResponse()
+
 	const db = drizzle(d1)
 	const env: MailerEnv = { DB: d1, QUEUE: queue }
 

package/src/routes/track-click.ts

@@ -3,7 +3,8 @@ 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 { probeMailerSchema } from '../_internal/schema-probe.js'
+import { emailSends } from '../schema/sends.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 
 export const GET: APIRoute = async (context) => {
@@ -25,24 +26,30 @@ export const GET: APIRoute = async (context) => {
 		return new Response('Invalid URL', { status: 400 })
 	}
 
-	// Update status to 'clicked' only when it hasn't already reached 'clicked'
+	// Update status to 'clicked' only when it hasn't already reached 'clicked'.
+	// On schema miss the probe logs GL_MAILER_SCHEMA_MISSING and we skip the
+	// D1 update — but always still 302 to the destination so we don't break
+	// the user's actual click intent.
 	try {
 		const bindingsEnv = cloudflareEnv as Record<string, unknown>
 		if (bindingsEnv) {
 			const d1 = bindingsEnv[config.d1Binding] as D1Database
-			const db = drizzle(d1)
-			await db
-				.update(emailSends)
-				.set({
-					status: 'clicked',
-					clickedAt: new Date().toISOString(),
-				})
-				.where(
-					and(
-						eq(emailSends.trackingId, trackingId),
-						inArray(emailSends.status, ['sent', 'delivered', 'opened']),
-					),
-				)
+			const schema = await probeMailerSchema(d1, config.d1Binding)
+			if (schema.ok) {
+				const db = drizzle(d1)
+				await db
+					.update(emailSends)
+					.set({
+						status: 'clicked',
+						clickedAt: new Date().toISOString(),
+					})
+					.where(
+						and(
+							eq(emailSends.trackingId, trackingId),
+							inArray(emailSends.status, ['sent', 'delivered', 'opened']),
+						),
+					)
+			}
 		}
 	} catch {
 		// Never fail the redirect on DB errors

package/src/routes/track-open.ts

@@ -3,7 +3,8 @@ 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 { probeMailerSchema } from '../_internal/schema-probe.js'
+import { emailSends } from '../schema/sends.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import { TRANSPARENT_GIF } from '../utils/tracking.js'
 
@@ -15,24 +16,29 @@ export const GET: APIRoute = async (context) => {
 	}
 
 	// Update status to 'opened' only when currently 'sent' or 'delivered'
-	// to avoid downgrading from 'clicked'.
+	// to avoid downgrading from 'clicked'. On schema miss, the probe logs
+	// GL_MAILER_SCHEMA_MISSING and we skip the D1 work — but always still
+	// return the transparent GIF so we don't break email rendering.
 	try {
 		const bindingsEnv = cloudflareEnv as Record<string, unknown>
 		if (bindingsEnv) {
 			const d1 = bindingsEnv[config.d1Binding] as D1Database
-			const db = drizzle(d1)
-			await db
-				.update(emailSends)
-				.set({
-					status: 'opened',
-					openedAt: new Date().toISOString(),
-				})
-				.where(
-					and(
-						eq(emailSends.trackingId, trackingId),
-						inArray(emailSends.status, ['sent', 'delivered']),
-					),
-				)
+			const schema = await probeMailerSchema(d1, config.d1Binding)
+			if (schema.ok) {
+				const db = drizzle(d1)
+				await db
+					.update(emailSends)
+					.set({
+						status: 'opened',
+						openedAt: new Date().toISOString(),
+					})
+					.where(
+						and(
+							eq(emailSends.trackingId, trackingId),
+							inArray(emailSends.status, ['sent', 'delivered']),
+						),
+					)
+			}
 		}
 	} catch {
 		// Never fail the pixel response on DB errors

package/src/routes/unsubscribe.ts

@@ -2,6 +2,7 @@ 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 { probeMailerSchema, schemaMissingResponse } from '../_internal/schema-probe.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import type { MailerEnv } from '../utils/send.js'
 import { sendTransactional } from '../utils/send.js'
@@ -24,6 +25,12 @@ async function processUnsubscribe(
 	const bindingsEnv = cloudflareEnv as Record<string, unknown>
 	const d1 = bindingsEnv[config.d1Binding] as D1Database
 	const queue = bindingsEnv[config.queueBinding] as Queue
+
+	// Schema probe — short-circuit with a Response on miss; both GET and POST
+	// handlers below forward it unchanged.
+	const schema = await probeMailerSchema(d1, config.d1Binding)
+	if (!schema.ok) return { schemaMissing: true as const }
+
 	const db = drizzle(d1)
 	const env: MailerEnv = { DB: d1, QUEUE: queue }
 
@@ -73,6 +80,7 @@ export const GET: APIRoute = async (context) => {
 	}
 
 	const result = await processUnsubscribe(token, context, request)
+	if ('schemaMissing' in result) return schemaMissingResponse()
 	if ('error' in result) {
 		return Response.json({ error: result.error }, { status: result.status })
 	}
@@ -105,6 +113,7 @@ export const POST: APIRoute = async (context) => {
 	}
 
 	const result = await processUnsubscribe(token, context, request)
+	if ('schemaMissing' in result) return schemaMissingResponse()
 	if ('error' in result) {
 		return new Response(result.error, { status: result.status })
 	}

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,42 @@ export interface EmailQueueMessage {
 	campaignId?: string
 }
 
+// ─── Realm-level multi-tenant config lookup ───
+
+/**
+ * Per-site config override applied at consumer time. Returned from
+ * SiteConfigLookup. All fields are optional — only the ones present
+ * will override the consumer's resolved options for that message.
+ *
+ * Bindings (d1Binding, queueBinding, senderBinding) and route paths
+ * are NOT overridable per-site; they're realm-wide.
+ */
+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` to skip the
+ * override and use the consumer's options as-is.
+ */
+export type SiteConfigLookup = (
+	siteId: string,
+	env: Record<string, unknown>,
+) => Promise<SiteMailerConfig | null>
+
 export interface QueueRecipient {
 	email: string
 	subscriberId: 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>