@growth-labs/mailer 0.4.0 → 0.4.2

package/src/queue/consumer.ts

@@ -1,37 +1,45 @@
 import { drizzle } from 'drizzle-orm/d1'
-import { probeMailerSchema } from '../_internal/schema-probe.js'
-import type { ResolvedMailerOptions } from '../options.js'
-import type { EmailQueueMessage, SiteMailerConfig } 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'
 
-/**
- * Effective options for a single message — options merged with any
- * SiteMailerConfig override returned by `siteConfigLookup`.
- */
+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
+	siteUrl?: string
 	unsubscribePath: string
 	preferencesPath: string
+	senderName?: string
+	fromAddress?: string
+	replyTo?: string
 }
 
-function applyOverride(
-	options: ResolvedMailerOptions,
-	override: SiteMailerConfig | null,
-): EffectiveOptions {
+function applySiteConfig(config: SiteMailerConfig): EffectiveOptions {
 	return {
-		siteUrl: override?.siteUrl ?? options.siteUrl,
-		unsubscribePath: override?.unsubscribePath ?? options.unsubscribePath,
-		preferencesPath: override?.preferencesPath ?? options.preferencesPath,
+		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: Record<string, unknown>,
-	options: ResolvedMailerOptions,
+	options: MailerConsumerOptions,
 ): Promise<void> {
 	const d1 = env[options.d1Binding] as D1Database | undefined
 	if (!d1) {
@@ -53,7 +61,7 @@ export async function handleEmailQueue(
 	// 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)
+	const schemaProbe = await probeMailerSendsSchema(d1, options.d1Binding)
 	if (!schemaProbe.ok) {
 		console.error(
 			'[mailer] gl_email_sends not found in env.' +
@@ -73,23 +81,36 @@ export async function handleEmailQueue(
 	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 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
-		const effectiveFrom = override?.fromAddress
-			? formatFromHeader(override.senderName ?? options.senderName, override.fromAddress)
+		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 = override?.replyTo ?? replyTo
+		const effectiveReplyTo = effective.replyTo ?? replyTo
 
 		for (const recipient of recipients) {
 			let html = htmlTemplate
 			if (type !== 'transactional') {
-				const unsubscribeUrl = `${effective.siteUrl}${effective.unsubscribePath}?token=${recipient.unsubscribeToken}`
-				const preferencesUrl = `${effective.siteUrl}${effective.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)
@@ -100,7 +121,7 @@ export async function handleEmailQueue(
 				type !== 'transactional'
 					? {
 							...headers,
-							'List-Unsubscribe': `<${effective.siteUrl}${effective.unsubscribePath}?token=${recipient.unsubscribeToken}>`,
+							'List-Unsubscribe': `<${effective.siteUrl ?? ''}${effective.unsubscribePath}?token=${recipient.unsubscribeToken}>`,
 							'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
 						}
 					: headers
@@ -133,34 +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,
-						siteId: message.body.siteId,
+				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,
-						siteId: message.body.siteId,
-						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}`)
 			}
 		}
@@ -172,3 +203,19 @@ export async function handleEmailQueue(
 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/types.ts

@@ -52,12 +52,9 @@ export interface EmailQueueMessage {
 // ─── 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.
+ * 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
@@ -77,8 +74,8 @@ export interface SiteMailerConfig {
 
 /**
  * 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.
+ * `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,

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[] } {