@growth-labs/mailer 0.1.3

package/src/schema.ts

@@ -0,0 +1,56 @@
+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),
+	],
+)

package/src/types.ts

@@ -0,0 +1,145 @@
+// ─── Subscriber ───
+
+export interface Subscriber {
+	id: string
+	email: string
+	name?: string
+	status: SubscriberStatus
+	preferences: string[]
+	source: string
+	attribution?: SubscriberAttribution
+	softBounceCount: number
+	subscribedAt: string
+	confirmedAt?: string
+	unsubscribedAt?: string
+	createdAt: string
+	updatedAt: string
+}
+
+export type SubscriberStatus = 'pending' | 'active' | 'unsubscribed' | 'bounced' | 'complained'
+
+export interface SubscriberAttribution {
+	derivedSource: string
+	utmSource?: string
+	utmMedium?: string
+	utmCampaign?: string
+}
+
+// ─── Subscriber filter (for campaigns/digests) ───
+
+export interface SubscriberFilter {
+	status?: SubscriberStatus[]
+	preferences?: string[]
+	subscribedAfter?: string
+	subscribedBefore?: string
+	source?: string[]
+}
+
+// ─── Email Queue message ───
+
+export interface EmailQueueMessage {
+	type: 'transactional' | 'campaign' | 'digest'
+	recipients: QueueRecipient[]
+	subject: string
+	htmlTemplate: string
+	from: string
+	replyTo?: string
+	headers?: Record<string, string>
+	campaignId?: string
+}
+
+export interface QueueRecipient {
+	email: string
+	subscriberId: string
+	trackingId: string
+	unsubscribeToken: string
+	preferencesToken: string
+}
+
+// ─── Email send record ───
+
+export interface EmailSend {
+	id: string
+	subscriberId: string
+	campaignId?: string
+	email: string
+	subject: string
+	type: 'transactional' | 'campaign' | 'digest'
+	status: EmailSendStatus
+	sentAt?: string
+	deliveredAt?: string
+	openedAt?: string
+	clickedAt?: string
+	bouncedAt?: string
+	bounceType?: 'hard' | 'soft'
+	complainedAt?: string
+	trackingId: string
+	createdAt: string
+}
+
+export type EmailSendStatus =
+	| 'queued'
+	| 'sent'
+	| 'delivered'
+	| 'opened'
+	| 'clicked'
+	| 'bounced'
+	| 'complained'
+
+// ─── Email provider interface ───
+
+export interface EmailProvider {
+	send(email: OutboundEmail): Promise<SendResult>
+	readonly name: string
+}
+
+export interface OutboundEmail {
+	to: string
+	from: string
+	replyTo?: string
+	subject: string
+	html: string
+	headers?: Record<string, string>
+}
+
+export interface SendResult {
+	success: boolean
+	messageId?: string
+	error?: string
+	retryable: boolean
+}
+
+// ─── Template types ───
+
+export type TemplateName =
+	| 'confirmation'
+	| 'welcome'
+	| 'campaign'
+	| 'digest'
+	| 'transactional'
+	| 'unsubscribe-confirm'
+
+export interface TemplateData {
+	senderName: string
+	siteUrl: string
+	unsubscribeUrl: string
+	preferencesUrl: string
+	brand: {
+		logoUrl?: string
+		primaryColor: string
+		accentColor: string
+		footerText?: string
+	}
+	[key: string]: unknown
+}
+
+// ─── Digest content item ───
+
+export interface DigestItem {
+	title: string
+	url: string
+	description?: string
+	imageUrl?: string
+	publishedAt?: string
+	author?: string
+}

package/src/utils/bindings.ts

@@ -0,0 +1,28 @@
+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.
+ *
+ * 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`.
+ */
+export function resolveBindings(runtimeEnv: Record<string, unknown>): {
+	db: DrizzleDB
+	queue: Queue
+} {
+	const d1 = runtimeEnv[config.d1Binding] as D1Database
+	const queue = runtimeEnv[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`)
+
+	return { db: drizzle(d1), queue }
+}

package/src/utils/bounce.ts

@@ -0,0 +1,77 @@
+import { eq, sql } from 'drizzle-orm'
+import type { drizzle } from 'drizzle-orm/d1'
+import { emailSends, subscribers } from '../schema.js'
+
+type DrizzleDB = ReturnType<typeof drizzle>
+
+/**
+ * Handle an email bounce notification.
+ *
+ * - **Hard bounce**: immediately sets subscriber status to `bounced`.
+ * - **Soft bounce**: increments `softBounceCount`; if the count reaches 3
+ *   the subscriber is marked `bounced`.
+ *
+ * No-op when the email address has no matching subscriber row.
+ */
+export async function handleBounce(
+	db: DrizzleDB,
+	email: string,
+	bounceType: 'hard' | 'soft',
+): Promise<void> {
+	const rows = await db.select().from(subscribers).where(eq(subscribers.email, email))
+
+	if (rows.length === 0) return
+
+	const subscriber = rows[0]
+
+	if (bounceType === 'hard') {
+		await db.update(subscribers).set({ status: 'bounced' }).where(eq(subscribers.email, email))
+	} else {
+		const newCount = subscriber.softBounceCount + 1
+		const updates: Record<string, unknown> = { softBounceCount: newCount }
+
+		if (newCount >= 3) {
+			updates.status = 'bounced'
+		}
+
+		await db.update(subscribers).set(updates).where(eq(subscribers.email, email))
+	}
+}
+
+/**
+ * Handle an email complaint (spam report).
+ * Sets the subscriber status to `complained`.
+ */
+export async function handleComplaint(db: DrizzleDB, email: string): Promise<void> {
+	await db.update(subscribers).set({ status: 'complained' }).where(eq(subscribers.email, email))
+}
+
+/**
+ * Record a successful delivery for an email send.
+ * Only updates if the current status is `sent` — never downgrades
+ * from `opened` or `clicked`.
+ */
+export async function handleDelivery(db: DrizzleDB, trackingId: string): Promise<void> {
+	await db
+		.update(emailSends)
+		.set({
+			status: 'delivered',
+			deliveredAt: new Date().toISOString(),
+		})
+		.where(sql`${emailSends.trackingId} = ${trackingId} AND ${emailSends.status} = 'sent'`)
+}
+
+/**
+ * Generic helper to update a `gl_email_sends` row by tracking ID.
+ */
+export async function updateSendStatus(
+	db: DrizzleDB,
+	trackingId: string,
+	status: string,
+	fields: Record<string, string | null>,
+): Promise<void> {
+	await db
+		.update(emailSends)
+		.set({ status, ...fields })
+		.where(eq(emailSends.trackingId, trackingId))
+}

package/src/utils/index.ts

@@ -0,0 +1,47 @@
+export {
+	handleBounce,
+	handleComplaint,
+	handleDelivery,
+	updateSendStatus,
+} from './bounce.js'
+export type { CloudflareEmailSender } from './providers.js'
+export {
+	CloudflareEmailProvider,
+	getFallbackProvider,
+	getProvider,
+	ResendFallbackProvider,
+	sleep,
+} from './providers.js'
+export type { CampaignSchedule, DigestSchedule } from './scheduling.js'
+export {
+	executeCampaignSchedule,
+	executeDigestSchedule,
+	prepareCampaign,
+	prepareDigest,
+	sendBatchCampaigns,
+} from './scheduling.js'
+export type { MailerEnv } from './send.js'
+export { sendCampaign, sendDigest, sendTransactional } from './send.js'
+export {
+	confirmSubscriber,
+	countSubscribers,
+	createSubscriber,
+	getSubscriberBatch,
+	getSubscriberByEmail,
+	getSubscriberById,
+	unsubscribeSubscriber,
+	updatePreferences,
+} from './subscribers.js'
+export {
+	inlineStyles,
+	interpolate,
+	processConditionals,
+	renderDigestItems,
+	renderEmail,
+} from './templates.js'
+export { generateToken, verifyToken } from './tokens.js'
+export {
+	injectTrackingPixel,
+	rewriteLinksForTracking,
+	TRANSPARENT_GIF,
+} from './tracking.js'

package/src/utils/providers.ts

@@ -0,0 +1,141 @@
+import type { EmailProvider, OutboundEmail, SendResult } from '../types.js'
+
+// ─── Cloudflare Email binding shape ───
+
+export interface CloudflareEmailSender {
+	send(message: {
+		to: string
+		from: string
+		subject: string
+		content: { type: string; value: string }[]
+	}): Promise<void>
+}
+
+// ─── CloudflareEmailProvider ───
+
+export class CloudflareEmailProvider implements EmailProvider {
+	readonly name = 'cloudflare'
+	private readonly sender: CloudflareEmailSender
+
+	constructor(emailSender: CloudflareEmailSender) {
+		this.sender = emailSender
+	}
+
+	async send(email: OutboundEmail): Promise<SendResult> {
+		try {
+			await this.sender.send({
+				to: email.to,
+				from: email.from,
+				subject: email.subject,
+				content: [{ type: 'text/html', value: email.html }],
+			})
+
+			return { success: true, retryable: false }
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err)
+			const isRetryable = isNetworkOrServerError(message)
+
+			return {
+				success: false,
+				error: message,
+				retryable: isRetryable,
+			}
+		}
+	}
+}
+
+// ─── 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 ───
+
+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> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function isNetworkOrServerError(message: string): boolean {
+	const patterns = [
+		'network',
+		'timeout',
+		'econnrefused',
+		'econnreset',
+		'enotfound',
+		'socket',
+		'5',
+		'server error',
+		'service unavailable',
+		'internal server',
+	]
+	const lower = message.toLowerCase()
+	return patterns.some((p) => lower.includes(p))
+}

package/src/utils/scheduling.ts

@@ -0,0 +1,188 @@
+import type { drizzle } from 'drizzle-orm/d1'
+import { ulid } from 'ulidx'
+import type { ResolvedMailerOptions } from '../options.js'
+import type { DigestItem, SubscriberFilter } from '../types.js'
+import type { MailerEnv } from './send.js'
+import { sendCampaign, sendDigest } from './send.js'
+import { countSubscribers } from './subscribers.js'
+
+type DrizzleDB = ReturnType<typeof drizzle>
+
+// ─── Campaign schedule entry ───
+
+export interface CampaignSchedule {
+	campaignId: string
+	subject: string
+	html?: string
+	template?: 'campaign'
+	data?: Record<string, unknown>
+	filter?: SubscriberFilter
+	scheduledAt: string // ISO 8601
+}
+
+export interface DigestSchedule {
+	campaignId: string
+	subject: string
+	items: DigestItem[]
+	introText?: string
+	filter?: SubscriberFilter
+	scheduledAt: string // ISO 8601
+}
+
+// ─── Schedule builder ───
+
+/**
+ * Build a campaign schedule entry.
+ * The consumer stores this in KV/D1/R2 and uses a Cron Trigger to
+ * call `executeCampaignSchedule()` at the appropriate time.
+ *
+ * This is a lightweight helper — it pre-generates the campaignId
+ * and validates the send would have recipients.
+ */
+export async function prepareCampaign(
+	db: DrizzleDB,
+	params: {
+		subject: string
+		html?: string
+		template?: 'campaign'
+		data?: Record<string, unknown>
+		filter?: SubscriberFilter
+		scheduledAt: string
+	},
+): Promise<CampaignSchedule & { estimatedRecipients: number }> {
+	const campaignId = ulid()
+	const filter = params.filter ?? { status: ['active'] }
+	if (!filter.status) filter.status = ['active']
+
+	const estimatedRecipients = await countSubscribers(db, filter)
+
+	return {
+		campaignId,
+		subject: params.subject,
+		html: params.html,
+		template: params.template,
+		data: params.data,
+		filter: params.filter,
+		scheduledAt: params.scheduledAt,
+		estimatedRecipients,
+	}
+}
+
+/**
+ * Build a digest schedule entry with recipient estimate.
+ */
+export async function prepareDigest(
+	db: DrizzleDB,
+	params: {
+		subject: string
+		items: DigestItem[]
+		introText?: string
+		filter?: SubscriberFilter
+		scheduledAt: string
+	},
+): Promise<DigestSchedule & { estimatedRecipients: number }> {
+	const campaignId = ulid()
+	const filter = params.filter ?? { status: ['active'] }
+	if (!filter.status) filter.status = ['active']
+
+	const estimatedRecipients = await countSubscribers(db, filter)
+
+	return {
+		campaignId,
+		subject: params.subject,
+		items: params.items,
+		introText: params.introText,
+		filter: params.filter,
+		scheduledAt: params.scheduledAt,
+		estimatedRecipients,
+	}
+}
+
+// ─── Execute scheduled sends ───
+
+/**
+ * Execute a previously prepared campaign schedule.
+ * Checks that the scheduled time has arrived before sending.
+ * Returns null if not yet due.
+ */
+export async function executeCampaignSchedule(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	schedule: CampaignSchedule,
+): Promise<{ campaignId: string; recipientCount: number } | null> {
+	const now = Date.now()
+	const scheduledTime = new Date(schedule.scheduledAt).getTime()
+
+	if (scheduledTime > now) {
+		return null
+	}
+
+	return sendCampaign(env, options, {
+		subject: schedule.subject,
+		html: schedule.html,
+		template: schedule.template,
+		data: schedule.data,
+		filter: schedule.filter,
+		campaignId: schedule.campaignId,
+	})
+}
+
+/**
+ * Execute a previously prepared digest schedule.
+ * Checks that the scheduled time has arrived before sending.
+ * Returns null if not yet due.
+ */
+export async function executeDigestSchedule(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	schedule: DigestSchedule,
+): Promise<{ campaignId: string; recipientCount: number } | null> {
+	const now = Date.now()
+	const scheduledTime = new Date(schedule.scheduledAt).getTime()
+
+	if (scheduledTime > now) {
+		return null
+	}
+
+	return sendDigest(env, options, {
+		subject: schedule.subject,
+		items: schedule.items,
+		introText: schedule.introText,
+		filter: schedule.filter,
+		campaignId: schedule.campaignId,
+	})
+}
+
+/**
+ * Batch send helper: sends a campaign to multiple topic-segmented groups
+ * in a single call. Each segment gets its own campaign ID for tracking.
+ *
+ * Useful for sites that want to send the same content to different
+ * topic segments with different subject lines or intros.
+ */
+export async function sendBatchCampaigns(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	segments: Array<{
+		subject: string
+		html?: string
+		template?: 'campaign'
+		data?: Record<string, unknown>
+		filter: SubscriberFilter
+	}>,
+): Promise<Array<{ campaignId: string; recipientCount: number }>> {
+	const results: Array<{ campaignId: string; recipientCount: number }> = []
+
+	for (const segment of segments) {
+		const result = await sendCampaign(env, options, {
+			subject: segment.subject,
+			html: segment.html,
+			template: segment.template,
+			data: segment.data,
+			filter: segment.filter,
+		})
+		results.push(result)
+	}
+
+	return results
+}