@growth-labs/mailer 0.6.5 → 0.8.0

package/src/routes/track-open.ts

@@ -1,9 +1,10 @@
 import { env as cloudflareEnv } from 'cloudflare:workers'
 import { config } from 'virtual:growth-labs/mailer/config'
 import type { APIRoute } from 'astro'
-import { and, eq, inArray } from 'drizzle-orm'
+import { and, eq, inArray, sql } from 'drizzle-orm'
 import { drizzle } from 'drizzle-orm/d1'
-import { probeMailerSchema } from '../_internal/schema-probe.js'
+import { probeMailerSendsSchema } from '../_internal/schema-probe.js'
+import { logTrackingUpdateFailed, reportIfNoRowUpdated } from '../_internal/tracking-update.js'
 import { emailSends } from '../schema/sends.js'
 import { emitMailerAnalyticsEvent } from '../utils/analytics.js'
 import { TRANSPARENT_GIF } from '../utils/tracking.js'
@@ -16,22 +17,28 @@ export const GET: APIRoute = async (context) => {
 	}
 
 	// Update status to 'opened' only when currently 'sent' or 'delivered'
-	// 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.
+	// to avoid downgrading from 'clicked'. An open proves delivery, so
+	// delivered_at is filled when no delivery webhook set it. Only
+	// gl_email_sends is touched, so only that table is probed: the sends D1 of
+	// a realm holds no gl_subscribers. On schema miss, the probe logs
+	// GL_MAILER_SCHEMA_MISSING and we skip the D1 work; a zero-row update or a
+	// D1 error is logged loudly. The transparent GIF is returned regardless so
+	// email rendering never breaks.
+	const bindingsEnv = cloudflareEnv as Record<string, unknown>
+	const sendsBindingName = config.sendsD1Binding ?? config.d1Binding
 	try {
-		const bindingsEnv = cloudflareEnv as Record<string, unknown>
 		if (bindingsEnv) {
-			const sendsBindingName = config.sendsD1Binding ?? config.d1Binding
 			const d1 = bindingsEnv[sendsBindingName] as D1Database
-			const schema = await probeMailerSchema(d1, sendsBindingName)
+			const schema = await probeMailerSendsSchema(d1, sendsBindingName)
 			if (schema.ok) {
 				const db = drizzle(d1)
-				await db
+				const now = new Date().toISOString()
+				const result = await db
 					.update(emailSends)
 					.set({
 						status: 'opened',
-						openedAt: new Date().toISOString(),
+						openedAt: now,
+						deliveredAt: sql`coalesce(${emailSends.deliveredAt}, ${now})`,
 					})
 					.where(
 						and(
@@ -39,10 +46,11 @@ export const GET: APIRoute = async (context) => {
 							inArray(emailSends.status, ['sent', 'delivered']),
 						),
 					)
+				await reportIfNoRowUpdated(d1, sendsBindingName, trackingId, 'open', result)
 			}
 		}
-	} catch {
-		// Never fail the pixel response on DB errors
+	} catch (err) {
+		logTrackingUpdateFailed('open', trackingId, sendsBindingName, err)
 	}
 
 	emitMailerAnalyticsEvent(config, cloudflareEnv as Record<string, unknown>, 'newsletter_opened', {

package/src/types.ts

@@ -163,6 +163,8 @@ export interface SendResult {
 	success: boolean
 	messageId?: string
 	error?: string
+	/** The provider's own error code (e.g. Cloudflare `E_*`), when it supplies one. */
+	errorCode?: string
 	retryable: boolean
 }
 

package/src/utils/broadcast.ts

@@ -10,6 +10,7 @@ import { resolveSigningSecret, siteHost } from './runtime-secrets.js'
 import type { MailerEnv } from './send.js'
 import { generateToken } from './tokens.js'
 import { injectTrackingPixel, rewriteLinksForTracking } from './tracking.js'
+import { emailLinkUtm, tagLinksWithUtm } from './utm.js'
 
 type DrizzleDB = ReturnType<typeof drizzle>
 
@@ -244,10 +245,15 @@ async function filterAlreadySent(
  * Build the broadcast HTML with the tracking pixel + click-rewrite applied
  * once (the per-recipient {{TRACKING_ID}} is substituted in the consumer).
  */
-function prepareBroadcastHtml(html: string, options: ResolvedMailerOptions): string {
+function prepareBroadcastHtml(
+	html: string,
+	options: ResolvedMailerOptions,
+	campaignId: string,
+): string {
 	const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`
 	const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`
-	return rewriteLinksForTracking(injectTrackingPixel(html, trackOpenUrl), trackClickUrl)
+	const tagged = tagLinksWithUtm(html, emailLinkUtm(options, campaignId))
+	return rewriteLinksForTracking(injectTrackingPixel(tagged, trackOpenUrl), trackClickUrl)
 }
 
 function chunk<T>(items: T[], size: number): T[][] {
@@ -339,7 +345,7 @@ export async function sendBroadcast(
 	const signingSecret = signingSecretResult.secret
 	const host = siteHost(options.siteUrl)
 
-	const html = prepareBroadcastHtml(params.html, options)
+	const html = prepareBroadcastHtml(params.html, options, campaignId)
 	const now = new Date().toISOString()
 
 	// 4. Per-recipient row write + queue-recipient build.

package/src/utils/index.ts

@@ -50,4 +50,5 @@ export {
 	rewriteLinksForTracking,
 	TRANSPARENT_GIF,
 } from './tracking.js'
+export { addUtmParams, emailLinkUtm, type LinkUtm, tagLinksWithUtm } from './utm.js'
 export { signWebhookPayload, verifyWebhookSignature } from './webhook-signature.js'

package/src/utils/providers.ts

@@ -45,9 +45,11 @@ export class CloudflareEmailProvider implements EmailProvider {
 			const message = err instanceof Error ? err.message : String(err)
 			const isRetryable = isNetworkOrServerError(message)
 
+			const errorCode = providerErrorCode(err)
 			return {
 				success: false,
 				error: message,
+				...(errorCode ? { errorCode } : {}),
 				retryable: isRetryable,
 			}
 		}
@@ -66,6 +68,15 @@ export function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+/** The provider's error code, when the thrown error carries a string or numeric `code`. */
+function providerErrorCode(err: unknown): string | undefined {
+	if (typeof err !== 'object' || err === null) return undefined
+	const code = (err as { code?: unknown }).code
+	if (typeof code === 'string' && code.length > 0) return code.slice(0, 80)
+	if (typeof code === 'number' && Number.isFinite(code)) return String(code)
+	return undefined
+}
+
 function isNetworkOrServerError(message: string): boolean {
 	const patterns = [
 		'network',

package/src/utils/send.ts

@@ -17,6 +17,7 @@ import { renderDigestItems, renderEmail } from './templates.js'
 import { generateToken } from './tokens.js'
 import { injectTrackingPixel, rewriteLinksForTracking } from './tracking.js'
 import { buildSubscriberManageUrls } from './urls.js'
+import { emailLinkUtm, tagLinksWithUtm } from './utm.js'
 
 type DrizzleDB = ReturnType<typeof drizzle>
 
@@ -274,6 +275,7 @@ export async function sendCampaign(
 	// Inject tracking
 	const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`
 	const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`
+	html = tagLinksWithUtm(html, emailLinkUtm(options, campaignId))
 	html = injectTrackingPixel(html, trackOpenUrl)
 	html = rewriteLinksForTracking(html, trackClickUrl)
 
@@ -320,6 +322,7 @@ export async function sendDigest(
 	// Inject tracking
 	const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`
 	const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`
+	html = tagLinksWithUtm(html, emailLinkUtm(options, campaignId))
 	html = injectTrackingPixel(html, trackOpenUrl)
 	html = rewriteLinksForTracking(html, trackClickUrl)
 

package/src/utils/utm.ts

@@ -0,0 +1,73 @@
+// UTM tagging for links in campaign, digest and broadcast emails.
+//
+// Mailer links used to reach GA4 untagged, so email clicks landed as direct
+// traffic. Tagging happens before the click-tracking rewrite wraps each href,
+// so the tagged URL is what the redirect finally sends the reader to.
+
+/** UTM tags for links that stay on the sending site. */
+export interface LinkUtm {
+	/** Sending site's host (e.g. `fronts.co`). Only links to it, or a subdomain, are tagged. */
+	siteHost: string
+	source: string
+	medium: string
+	/** Campaign or template identifier; reduced to `[a-z0-9_-]`. */
+	campaign: string
+}
+
+function utmValue(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, 100)
+}
+
+/**
+ * The tags every campaign, digest and broadcast link to the sending site
+ * carries: source `newsletter`, medium `email`, campaign = the campaign id.
+ * GA4 files source/medium `newsletter / email` under its Email channel.
+ */
+export function emailLinkUtm(options: { siteUrl: string }, campaignId: string): LinkUtm {
+	return {
+		siteHost: new URL(options.siteUrl).hostname,
+		source: 'newsletter',
+		medium: 'email',
+		campaign: campaignId,
+	}
+}
+
+/**
+ * Add utm_source / utm_medium / utm_campaign to a link that points at the
+ * sending site. Off-site links, non-http(s) links, links with a template
+ * placeholder, and links that already carry a utm_source are returned as-is.
+ */
+export function addUtmParams(href: string, utm: LinkUtm): string {
+	if (href.includes('{{')) return href
+	let url: URL
+	try {
+		url = new URL(href)
+	} catch {
+		return href
+	}
+	if (url.protocol !== 'https:' && url.protocol !== 'http:') return href
+	const host = url.hostname.toLowerCase()
+	const site = utm.siteHost.toLowerCase()
+	if (host !== site && !host.endsWith(`.${site}`)) return href
+	if (url.searchParams.has('utm_source')) return href
+	url.searchParams.set('utm_source', utmValue(utm.source))
+	url.searchParams.set('utm_medium', utmValue(utm.medium))
+	const campaign = utmValue(utm.campaign)
+	if (campaign) url.searchParams.set('utm_campaign', campaign)
+	return url.toString()
+}
+
+/** Tag every `<a href="...">` in the HTML that addUtmParams accepts. */
+export function tagLinksWithUtm(html: string, utm: LinkUtm): string {
+	return html.replace(
+		/<a\s([^>]*?)href\s*=\s*"([^"]*)"([^>]*?)>/gi,
+		(match, before: string, href: string, after: string) => {
+			const tagged = addUtmParams(href, utm)
+			return tagged === href ? match : `<a ${before}href="${tagged}"${after}>`
+		},
+	)
+}