@growth-labs/mailer 0.1.3

package/src/utils/send.ts

@@ -0,0 +1,282 @@
+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 type {
+	DigestItem,
+	EmailQueueMessage,
+	QueueRecipient,
+	SubscriberFilter,
+	TemplateData,
+	TemplateName,
+} from '../types.js'
+import { getSubscriberBatch } from './subscribers.js'
+import { renderDigestItems, renderEmail } from './templates.js'
+import { generateToken } from './tokens.js'
+import { injectTrackingPixel, rewriteLinksForTracking } from './tracking.js'
+import { buildSubscriberManageUrls } from './urls.js'
+
+type DrizzleDB = ReturnType<typeof drizzle>
+
+// ─── MailerEnv ───
+
+export interface MailerEnv {
+	DB: D1Database
+	QUEUE: Queue
+}
+
+// ─── sendTransactional ───
+
+export async function sendTransactional(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	params: {
+		to: string
+		subscriberId?: string
+		subject: string
+		html?: string
+		template?: TemplateName
+		data?: Record<string, unknown>
+	},
+): Promise<{ trackingId: string }> {
+	const db = drizzle(env.DB)
+	const trackingId = ulid()
+	const subscriberId = params.subscriberId ?? ulid()
+
+	// Render HTML
+	let html: string
+	if (params.template) {
+		const manageUrls = await buildSubscriberManageUrls(options, params.subscriberId)
+		html = renderEmail(params.template, {
+			...params.data,
+			senderName: options.senderName,
+			siteUrl: options.siteUrl,
+			unsubscribeUrl: manageUrls.unsubscribeUrl,
+			preferencesUrl: manageUrls.preferencesUrl,
+			brand: options.brand,
+		} as TemplateData)
+	} else if (params.html) {
+		html = params.html
+	} else {
+		throw new Error('Either template or html must be provided')
+	}
+
+	// Record the send
+	await db.insert(emailSends).values({
+		id: ulid(),
+		subscriberId,
+		email: params.to,
+		subject: params.subject,
+		type: 'transactional',
+		status: 'queued',
+		trackingId,
+		createdAt: new Date().toISOString(),
+	})
+
+	// Build and enqueue the message
+	const message: EmailQueueMessage = {
+		type: 'transactional',
+		recipients: [
+			{
+				email: params.to,
+				subscriberId,
+				trackingId,
+				unsubscribeToken: '',
+				preferencesToken: '',
+			},
+		],
+		subject: params.subject,
+		htmlTemplate: html,
+		from: `${options.senderName} <${options.fromAddress}>`,
+		replyTo: options.replyTo,
+	}
+
+	await env.QUEUE.send(message)
+
+	return { trackingId }
+}
+
+// ─── Fan-out helper (shared by campaign + digest) ───
+
+async function fanOutToSubscribers(
+	env: MailerEnv,
+	db: DrizzleDB,
+	options: ResolvedMailerOptions,
+	params: {
+		subject: string
+		html: string
+		campaignId: string
+		type: 'campaign' | 'digest'
+		filter?: SubscriberFilter
+	},
+): Promise<number> {
+	let cursor: string | null = null
+	let recipientCount = 0
+	const filter: SubscriberFilter = params.filter ?? { status: ['active'] }
+	if (!filter.status) filter.status = ['active']
+
+	while (true) {
+		const batch = await getSubscriberBatch(db, filter, options.batchSize, cursor)
+		if (batch.length === 0) break
+
+		const recipients: QueueRecipient[] = []
+		for (const sub of batch) {
+			const trackingId = ulid()
+			const unsubscribeToken = await generateToken(options.signingSecret, {
+				subscriberId: sub.id,
+				action: 'unsubscribe',
+			})
+			const preferencesToken = await generateToken(options.signingSecret, {
+				subscriberId: sub.id,
+				action: 'preferences',
+			})
+
+			await db.insert(emailSends).values({
+				id: ulid(),
+				subscriberId: sub.id,
+				campaignId: params.campaignId,
+				email: sub.email,
+				subject: params.subject,
+				type: params.type,
+				status: 'queued',
+				trackingId,
+				createdAt: new Date().toISOString(),
+			})
+
+			recipients.push({
+				email: sub.email,
+				subscriberId: sub.id,
+				trackingId,
+				unsubscribeToken,
+				preferencesToken,
+			})
+		}
+
+		const message: EmailQueueMessage = {
+			type: params.type,
+			recipients,
+			subject: params.subject,
+			htmlTemplate: params.html,
+			from: `${options.senderName} <${options.fromAddress}>`,
+			replyTo: options.replyTo,
+			campaignId: params.campaignId,
+		}
+		await env.QUEUE.send(message)
+
+		recipientCount += batch.length
+		cursor = batch[batch.length - 1].id
+	}
+
+	return recipientCount
+}
+
+// ─── sendCampaign ───
+
+export async function sendCampaign(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	params: {
+		subject: string
+		html?: string
+		template?: 'campaign'
+		data?: Record<string, unknown>
+		filter?: SubscriberFilter
+		campaignId?: string
+	},
+): Promise<{ campaignId: string; recipientCount: number }> {
+	const campaignId = params.campaignId ?? ulid()
+	const db = drizzle(env.DB)
+
+	// Render HTML
+	let html: string
+	if (params.template) {
+		html = renderEmail('campaign', {
+			...params.data,
+			senderName: options.senderName,
+			siteUrl: options.siteUrl,
+			unsubscribeUrl: '{{UNSUBSCRIBE_URL}}',
+			preferencesUrl: '{{PREFERENCES_URL}}',
+			brand: options.brand,
+		} as TemplateData)
+	} else if (params.html) {
+		html = params.html
+	} else {
+		throw new Error('Either template or html must be provided')
+	}
+
+	// Inject tracking
+	const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`
+	const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`
+	html = injectTrackingPixel(html, trackOpenUrl)
+	html = rewriteLinksForTracking(html, trackClickUrl)
+
+	const recipientCount = await fanOutToSubscribers(env, db, options, {
+		subject: params.subject,
+		html,
+		campaignId,
+		type: 'campaign',
+		filter: params.filter,
+	})
+
+	return { campaignId, recipientCount }
+}
+
+// ─── sendDigest ───
+
+export async function sendDigest(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	params: {
+		subject: string
+		items: DigestItem[]
+		introText?: string
+		filter?: SubscriberFilter
+		campaignId?: string
+	},
+): Promise<{ campaignId: string; recipientCount: number }> {
+	const campaignId = params.campaignId ?? ulid()
+	const db = drizzle(env.DB)
+
+	// Render digest items then full template
+	const itemsHtml = renderDigestItems(params.items)
+	let html = renderEmail('digest', {
+		senderName: options.senderName,
+		siteUrl: options.siteUrl,
+		unsubscribeUrl: '{{UNSUBSCRIBE_URL}}',
+		preferencesUrl: '{{PREFERENCES_URL}}',
+		brand: options.brand,
+		introText: params.introText ?? '',
+		digestItems: itemsHtml,
+	} as TemplateData)
+
+	// Inject tracking
+	const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`
+	const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`
+	html = injectTrackingPixel(html, trackOpenUrl)
+	html = rewriteLinksForTracking(html, trackClickUrl)
+
+	const recipientCount = await fanOutToSubscribers(env, db, options, {
+		subject: params.subject,
+		html,
+		campaignId,
+		type: 'digest',
+		filter: params.filter,
+	})
+
+	return { campaignId, recipientCount }
+}
+
+// ─── updateSendStatus ───
+
+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/subscribers.ts

@@ -0,0 +1,277 @@
+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 type { Subscriber, SubscriberAttribution, SubscriberFilter } from '../types.js'
+
+type DrizzleDB = ReturnType<typeof drizzle>
+
+// ─── Helpers ───
+
+function rowToSubscriber(row: Record<string, unknown>): Subscriber {
+	return {
+		id: row.id as string,
+		email: row.email as string,
+		name: (row.name as string) ?? undefined,
+		status: row.status as Subscriber['status'],
+		preferences: JSON.parse((row.preferences as string) ?? '[]') as string[],
+		source: row.source as string,
+		attribution: row.attribution
+			? (JSON.parse(row.attribution as string) as SubscriberAttribution)
+			: undefined,
+		softBounceCount: (row.softBounceCount as number) ?? 0,
+		subscribedAt: row.subscribedAt as string,
+		confirmedAt: (row.confirmedAt as string) ?? undefined,
+		unsubscribedAt: (row.unsubscribedAt as string) ?? undefined,
+		createdAt: row.createdAt as string,
+		updatedAt: row.updatedAt as string,
+	}
+}
+
+// ─── createSubscriber ───
+
+export async function createSubscriber(
+	db: DrizzleDB,
+	params: {
+		email: string
+		name?: string
+		source: string
+		preferences?: string[]
+		attribution?: SubscriberAttribution
+		doubleOptIn?: boolean
+	},
+): Promise<{ subscriber: Subscriber; isNew: boolean }> {
+	const doubleOptIn = params.doubleOptIn ?? true
+
+	const existing = await db.select().from(subscribers).where(eq(subscribers.email, params.email))
+
+	if (existing.length > 0) {
+		const row = existing[0]
+
+		if (row.status === 'active') {
+			return { subscriber: rowToSubscriber(row), isNew: false }
+		}
+
+		if (row.status === 'pending') {
+			return { subscriber: rowToSubscriber(row), isNew: false }
+		}
+
+		if (row.status === 'bounced' || row.status === 'complained') {
+			throw new Error('Cannot re-subscribe a bounced or complained address')
+		}
+
+		// status === 'unsubscribed' → reactivate
+		const now = new Date().toISOString()
+		const newStatus = doubleOptIn ? 'pending' : 'active'
+
+		const updated = await db
+			.update(subscribers)
+			.set({
+				status: newStatus,
+				subscribedAt: now,
+				unsubscribedAt: null,
+				updatedAt: now,
+			})
+			.where(eq(subscribers.id, row.id as string))
+			.returning()
+
+		return {
+			subscriber: rowToSubscriber(updated[0]),
+			isNew: false,
+		}
+	}
+
+	// New subscriber
+	const now = new Date().toISOString()
+	const id = ulid()
+	const status = doubleOptIn ? 'pending' : 'active'
+
+	const inserted = await db
+		.insert(subscribers)
+		.values({
+			id,
+			email: params.email,
+			name: params.name ?? null,
+			status,
+			preferences: JSON.stringify(params.preferences ?? []),
+			source: params.source,
+			attribution: params.attribution ? JSON.stringify(params.attribution) : null,
+			softBounceCount: 0,
+			subscribedAt: now,
+			confirmedAt: null,
+			unsubscribedAt: null,
+			createdAt: now,
+			updatedAt: now,
+		})
+		.returning()
+
+	return { subscriber: rowToSubscriber(inserted[0]), isNew: true }
+}
+
+// ─── confirmSubscriber ───
+
+export async function confirmSubscriber(db: DrizzleDB, subscriberId: string): Promise<Subscriber> {
+	const rows = await db.select().from(subscribers).where(eq(subscribers.id, subscriberId))
+
+	if (rows.length === 0) {
+		throw new Error('Subscriber not found')
+	}
+
+	if (rows[0].status !== 'pending') {
+		throw new Error('Subscriber is not in pending status')
+	}
+
+	const now = new Date().toISOString()
+
+	const updated = await db
+		.update(subscribers)
+		.set({ status: 'active', confirmedAt: now, updatedAt: now })
+		.where(eq(subscribers.id, subscriberId))
+		.returning()
+
+	return rowToSubscriber(updated[0])
+}
+
+// ─── unsubscribeSubscriber ───
+
+export async function unsubscribeSubscriber(db: DrizzleDB, subscriberId: string): Promise<void> {
+	const now = new Date().toISOString()
+
+	await db
+		.update(subscribers)
+		.set({
+			status: 'unsubscribed',
+			unsubscribedAt: now,
+			updatedAt: now,
+		})
+		.where(eq(subscribers.id, subscriberId))
+}
+
+// ─── updatePreferences ───
+
+export async function updatePreferences(
+	db: DrizzleDB,
+	subscriberId: string,
+	preferences: string[],
+): Promise<void> {
+	const now = new Date().toISOString()
+
+	await db
+		.update(subscribers)
+		.set({
+			preferences: JSON.stringify(preferences),
+			updatedAt: now,
+		})
+		.where(eq(subscribers.id, subscriberId))
+}
+
+// ─── getSubscriberByEmail ───
+
+export async function getSubscriberByEmail(
+	db: DrizzleDB,
+	email: string,
+): Promise<Subscriber | null> {
+	const rows = await db.select().from(subscribers).where(eq(subscribers.email, email))
+
+	if (rows.length === 0) return null
+	return rowToSubscriber(rows[0])
+}
+
+// ─── getSubscriberById ───
+
+export async function getSubscriberById(db: DrizzleDB, id: string): Promise<Subscriber | null> {
+	const rows = await db.select().from(subscribers).where(eq(subscribers.id, id))
+
+	if (rows.length === 0) return null
+	return rowToSubscriber(rows[0])
+}
+
+// ─── getSubscriberBatch ───
+
+export async function getSubscriberBatch(
+	db: DrizzleDB,
+	filter: SubscriberFilter,
+	limit: number,
+	cursor: string | null,
+): Promise<Subscriber[]> {
+	const conditions = []
+
+	// Status filter (default: active only)
+	const statuses = filter.status ?? ['active']
+	conditions.push(inArray(subscribers.status, statuses))
+
+	// Preferences overlap — any match
+	if (filter.preferences && filter.preferences.length > 0) {
+		const prefConditions = filter.preferences.map((pref) =>
+			like(subscribers.preferences, `%"${pref}"%`),
+		)
+		const prefOr = or(...prefConditions)
+		if (prefOr) conditions.push(prefOr)
+	}
+
+	// Date range
+	if (filter.subscribedAfter) {
+		conditions.push(gt(subscribers.subscribedAt, filter.subscribedAfter))
+	}
+	if (filter.subscribedBefore) {
+		conditions.push(lt(subscribers.subscribedAt, filter.subscribedBefore))
+	}
+
+	// Source filter
+	if (filter.source && filter.source.length > 0) {
+		conditions.push(inArray(subscribers.source, filter.source))
+	}
+
+	// Cursor-based pagination
+	if (cursor) {
+		conditions.push(gt(subscribers.id, cursor))
+	}
+
+	const rows = await db
+		.select()
+		.from(subscribers)
+		.where(and(...conditions))
+		.orderBy(subscribers.id)
+		.limit(limit)
+
+	return rows.map(rowToSubscriber)
+}
+
+// ─── countSubscribers ───
+
+export async function countSubscribers(db: DrizzleDB, filter?: SubscriberFilter): Promise<number> {
+	const conditions = []
+
+	if (filter) {
+		const statuses = filter.status ?? ['active']
+		conditions.push(inArray(subscribers.status, statuses))
+
+		if (filter.preferences && filter.preferences.length > 0) {
+			const prefConditions = filter.preferences.map((pref) =>
+				like(subscribers.preferences, `%"${pref}"%`),
+			)
+			const prefOr = or(...prefConditions)
+			if (prefOr) conditions.push(prefOr)
+		}
+
+		if (filter.subscribedAfter) {
+			conditions.push(gt(subscribers.subscribedAt, filter.subscribedAfter))
+		}
+		if (filter.subscribedBefore) {
+			conditions.push(lt(subscribers.subscribedAt, filter.subscribedBefore))
+		}
+
+		if (filter.source && filter.source.length > 0) {
+			conditions.push(inArray(subscribers.source, filter.source))
+		}
+	}
+
+	const whereClause = conditions.length > 0 ? and(...conditions) : undefined
+
+	const result = await db
+		.select({ count: sql<number>`count(*)` })
+		.from(subscribers)
+		.where(whereClause)
+
+	return result[0].count
+}