@growth-labs/mailer 0.7.0 → 0.8.1

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}>`
+		},
+	)
+}