@growth-labs/notify 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/notify",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Worker-compatible human notification delivery for Slack and email with severity routing, retry, and caller-supplied dedup hooks.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,11 @@
   },
   "files": [
     "dist",
+    "src/**/*.ts",
+    "src/**/*.astro",
+    "src/**/*.css",
+    "src/**/*.md",
+    "src/**/*.sql",
     "README.md",
     "SPEC.md"
   ],

package/src/adapters/cf-email.ts

@@ -0,0 +1,130 @@
+import {
+	DeliveryError,
+	errorMessage,
+	type RetryOptions,
+	type RetryResult,
+	shouldRetryDeliveryError,
+	withRetry,
+} from '../retry.js'
+import type { NotifyEnv, NotifyInput } from '../types.js'
+
+type EmailMessageConstructor = typeof import('cloudflare:email').EmailMessage
+
+export function hasCloudflareEmailBinding(env: NotifyEnv): boolean {
+	return (
+		typeof env.SEND_EMAIL?.send === 'function' &&
+		isNonEmptyString(env.NOTIFY_EMAIL_FROM) &&
+		isNonEmptyString(env.NOTIFY_EMAIL_TO)
+	)
+}
+
+export async function dispatchCloudflareEmail(
+	env: NotifyEnv,
+	input: NotifyInput,
+	retryOptions?: Partial<RetryOptions>,
+): Promise<RetryResult<void>> {
+	return withRetry(
+		async () => {
+			const sender = env.SEND_EMAIL
+			const from = env.NOTIFY_EMAIL_FROM
+			const to = env.NOTIFY_EMAIL_TO
+			if (typeof sender?.send !== 'function' || !isNonEmptyString(from) || !isNonEmptyString(to)) {
+				throw new DeliveryError(
+					'Cloudflare SEND_EMAIL binding or email addresses are missing',
+					false,
+				)
+			}
+
+			const EmailMessage = await loadEmailMessage()
+			const raw = buildRfc822Message({
+				from,
+				to,
+				subject: input.title,
+				bodyText: input.body,
+				bodyHtml: buildHtmlBody(input.body),
+			})
+
+			await sender.send(new EmailMessage(from, to, raw))
+		},
+		(error) => shouldRetryCloudflareEmail(error),
+		retryOptions,
+	)
+}
+
+export function buildRfc822Message(input: {
+	from: string
+	to: string
+	subject: string
+	bodyText: string
+	bodyHtml: string
+}): string {
+	const boundary = 'gl-notify-boundary'
+	return [
+		`From: ${sanitizeHeader(input.from)}`,
+		`To: ${sanitizeHeader(input.to)}`,
+		`Subject: ${sanitizeHeader(input.subject)}`,
+		'MIME-Version: 1.0',
+		`Content-Type: multipart/alternative; boundary="${boundary}"`,
+		'',
+		`--${boundary}`,
+		'Content-Type: text/plain; charset=UTF-8',
+		'Content-Transfer-Encoding: 8bit',
+		'',
+		input.bodyText,
+		`--${boundary}`,
+		'Content-Type: text/html; charset=UTF-8',
+		'Content-Transfer-Encoding: 8bit',
+		'',
+		input.bodyHtml,
+		`--${boundary}--`,
+		'',
+	].join('\r\n')
+}
+
+function shouldRetryCloudflareEmail(error: unknown): boolean {
+	const status = statusCode(error)
+	if (status && status >= 400 && status < 500) {
+		return false
+	}
+
+	const message = errorMessage(error).toLowerCase()
+	if (message.includes('destination not verified')) {
+		return false
+	}
+
+	return shouldRetryDeliveryError(error)
+}
+
+async function loadEmailMessage(): Promise<EmailMessageConstructor> {
+	const module = await import('cloudflare:email')
+	return module.EmailMessage
+}
+
+function buildHtmlBody(body: string): string {
+	return `<p>${escapeHtml(body).replace(/\n/g, '<br>')}</p>`
+}
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+}
+
+function sanitizeHeader(value: string): string {
+	return value.replace(/[\r\n]+/g, ' ').trim()
+}
+
+function statusCode(error: unknown): number | undefined {
+	if (!error || typeof error !== 'object') {
+		return undefined
+	}
+	const status = (error as { status?: unknown }).status
+	return typeof status === 'number' ? status : undefined
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === 'string' && value.trim() !== ''
+}

package/src/adapters/resend.ts

@@ -0,0 +1,80 @@
+import {
+	DeliveryError,
+	type RetryOptions,
+	type RetryResult,
+	shouldRetryDeliveryError,
+	withRetry,
+} from '../retry.js'
+import type { NotifyEnv, NotifyInput } from '../types.js'
+
+const RESEND_EMAILS_URL = 'https://api.resend.com/emails'
+
+export function hasResendBinding(env: NotifyEnv): boolean {
+	return (
+		isNonEmptyString(env.RESEND_API_KEY) &&
+		isNonEmptyString(env.NOTIFY_EMAIL_FROM) &&
+		isNonEmptyString(env.NOTIFY_EMAIL_TO)
+	)
+}
+
+export async function dispatchResendEmail(
+	env: NotifyEnv,
+	input: NotifyInput,
+	retryOptions?: Partial<RetryOptions>,
+): Promise<RetryResult<void>> {
+	return withRetry(
+		async () => {
+			if (!hasResendBinding(env)) {
+				throw new DeliveryError('Resend API key or email addresses are missing', false)
+			}
+
+			const response = await fetch(RESEND_EMAILS_URL, {
+				method: 'POST',
+				headers: {
+					Authorization: `Bearer ${env.RESEND_API_KEY}`,
+					'Content-Type': 'application/json',
+				},
+				body: JSON.stringify({
+					from: env.NOTIFY_EMAIL_FROM,
+					to: [env.NOTIFY_EMAIL_TO],
+					subject: input.title,
+					text: input.body,
+					html: buildHtmlBody(input.body),
+				}),
+			})
+
+			if (!response.ok) {
+				throw new DeliveryError(
+					await responseErrorMessage('Resend', response),
+					response.status >= 500,
+				)
+			}
+		},
+		(error) => shouldRetryDeliveryError(error),
+		retryOptions,
+	)
+}
+
+async function responseErrorMessage(label: string, response: Response): Promise<string> {
+	const body = await response.text()
+	return body.trim()
+		? `${label} responded ${response.status}: ${body}`
+		: `${label} responded ${response.status}`
+}
+
+function buildHtmlBody(body: string): string {
+	return `<p>${escapeHtml(body).replace(/\n/g, '<br>')}</p>`
+}
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === 'string' && value.trim() !== ''
+}

package/src/adapters/slack.ts

@@ -0,0 +1,65 @@
+import {
+	DeliveryError,
+	type RetryOptions,
+	type RetryResult,
+	shouldRetryDeliveryError,
+	withRetry,
+} from '../retry.js'
+import type { NotifyEnv, NotifyInput } from '../types.js'
+
+export function hasSlackBinding(env: NotifyEnv): boolean {
+	return isNonEmptyString(env.NOTIFY_SLACK_WEBHOOK)
+}
+
+export async function dispatchSlack(
+	env: NotifyEnv,
+	input: NotifyInput,
+	retryOptions?: Partial<RetryOptions>,
+): Promise<RetryResult<void>> {
+	return withRetry(
+		async () => {
+			const webhook = env.NOTIFY_SLACK_WEBHOOK
+			if (!isNonEmptyString(webhook)) {
+				throw new DeliveryError('NOTIFY_SLACK_WEBHOOK is missing', false)
+			}
+
+			const response = await fetch(webhook, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({
+					text: input.title,
+					blocks: input.blocks ?? defaultBlocks(input),
+				}),
+			})
+
+			if (!response.ok) {
+				throw new DeliveryError(
+					await responseErrorMessage('Slack webhook', response),
+					response.status >= 500,
+				)
+			}
+		},
+		(error) => shouldRetryDeliveryError(error),
+		retryOptions,
+	)
+}
+
+function defaultBlocks(input: NotifyInput) {
+	return [
+		{
+			type: 'section',
+			text: { type: 'mrkdwn' as const, text: `*${input.title}*\n${input.body}` },
+		},
+	]
+}
+
+async function responseErrorMessage(label: string, response: Response): Promise<string> {
+	const body = await response.text()
+	return body.trim()
+		? `${label} responded ${response.status}: ${body}`
+		: `${label} responded ${response.status}`
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === 'string' && value.trim() !== ''
+}

package/src/cloudflare-email.d.ts

@@ -0,0 +1,9 @@
+declare module 'cloudflare:email' {
+	export class EmailMessage {
+		from: string
+		to: string
+		raw: string
+
+		constructor(from: string, to: string, raw: string)
+	}
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { notify } from './notify.js'
+export type {
+	Channel,
+	EmailProvider,
+	NotifyEnv,
+	NotifyInput,
+	NotifyResult,
+	SendEmailBinding,
+	SentRecord,
+	Severity,
+	SlackBlock,
+} from './types.js'

package/src/notify.ts

@@ -0,0 +1,149 @@
+import { dispatchCloudflareEmail, hasCloudflareEmailBinding } from './adapters/cf-email.js'
+import { dispatchResendEmail, hasResendBinding } from './adapters/resend.js'
+import { dispatchSlack, hasSlackBinding } from './adapters/slack.js'
+import type { RetryResult } from './retry.js'
+import type { Channel, EmailProvider, NotifyEnv, NotifyInput, NotifyResult } from './types.js'
+
+type Adapter = {
+	channel: Channel
+	failureLabel: string
+	hasRequiredBindings: (env: NotifyEnv) => boolean
+	dispatch: (env: NotifyEnv, input: NotifyInput) => Promise<RetryResult<void>>
+}
+
+const VALID_CHANNELS = new Set<Channel>(['slack', 'email'])
+const VALID_SEVERITIES = new Set(['info', 'warning', 'critical'])
+const VALID_EMAIL_PROVIDERS = new Set<EmailProvider>(['cloudflare', 'resend'])
+
+export async function notify(env: NotifyEnv, input: NotifyInput): Promise<NotifyResult> {
+	validateInput(input)
+
+	const result: NotifyResult = {
+		attempted: [...input.channels],
+		sent: [],
+		skipped: [],
+		failed: [],
+	}
+	const allowed = input.channels.filter((channel) => isAllowedBySeverity(channel, input.severity))
+
+	for (const channel of input.channels) {
+		if (!allowed.includes(channel)) {
+			result.skipped.push({ channel, reason: 'severity-routing' })
+		}
+	}
+
+	for (const channel of allowed) {
+		if (input.dedupKey && input.dedupFn) {
+			try {
+				const shouldSkip = await input.dedupFn(input.dedupKey)
+				if (shouldSkip) {
+					result.skipped.push({ channel, reason: 'deduped' })
+					continue
+				}
+			} catch (err) {
+				console.warn('@growth-labs/notify: dedupFn threw, proceeding with send', {
+					dedupKey: input.dedupKey,
+					err,
+				})
+			}
+		}
+
+		const adapter = selectAdapter(channel, input.emailProvider ?? 'cloudflare')
+		if (!adapter.hasRequiredBindings(env)) {
+			result.skipped.push({ channel, reason: 'missing-binding' })
+			continue
+		}
+
+		const dispatchResult = await adapter.dispatch(env, input)
+		if (dispatchResult.ok) {
+			result.sent.push(channel)
+			if (input.onSent) {
+				try {
+					await input.onSent({
+						channel,
+						severity: input.severity,
+						title: input.title,
+						dedupKey: input.dedupKey,
+						attempts: dispatchResult.attempts,
+						sentAt: Date.now(),
+					})
+				} catch (err) {
+					console.warn('@growth-labs/notify: onSent hook threw', { channel, err })
+				}
+			}
+		} else {
+			result.failed.push({ channel, error: dispatchResult.error })
+			console.warn(`@growth-labs/notify: ${adapter.failureLabel} delivery failed`, {
+				title: input.title,
+				attempts: dispatchResult.attempts,
+				error: dispatchResult.error,
+			})
+		}
+	}
+
+	return result
+}
+
+function selectAdapter(channel: Channel, emailProvider: EmailProvider): Adapter {
+	if (channel === 'slack') {
+		return {
+			channel,
+			failureLabel: 'slack',
+			hasRequiredBindings: hasSlackBinding,
+			dispatch: dispatchSlack,
+		}
+	}
+
+	if (emailProvider === 'resend') {
+		return {
+			channel,
+			failureLabel: 'resend',
+			hasRequiredBindings: hasResendBinding,
+			dispatch: dispatchResendEmail,
+		}
+	}
+
+	return {
+		channel,
+		failureLabel: 'cf-email',
+		hasRequiredBindings: hasCloudflareEmailBinding,
+		dispatch: dispatchCloudflareEmail,
+	}
+}
+
+function isAllowedBySeverity(channel: Channel, severity: NotifyInput['severity']): boolean {
+	if (channel === 'slack') {
+		return true
+	}
+	return severity === 'critical'
+}
+
+function validateInput(input: NotifyInput): void {
+	if (!Array.isArray(input.channels) || input.channels.length === 0) {
+		throw new Error('@growth-labs/notify: channels must include at least one channel')
+	}
+
+	for (const channel of input.channels) {
+		if (!VALID_CHANNELS.has(channel)) {
+			throw new Error(`@growth-labs/notify: unsupported channel "${String(channel)}"`)
+		}
+	}
+
+	if (!VALID_SEVERITIES.has(input.severity)) {
+		throw new Error(`@growth-labs/notify: unsupported severity "${String(input.severity)}"`)
+	}
+
+	if (typeof input.title !== 'string' || input.title.trim() === '') {
+		throw new Error('@growth-labs/notify: title is required')
+	}
+
+	if (typeof input.body !== 'string' || input.body.trim() === '') {
+		throw new Error('@growth-labs/notify: body is required')
+	}
+
+	if (input.emailProvider !== undefined && !VALID_EMAIL_PROVIDERS.has(input.emailProvider)) {
+		throw new Error(
+			`@growth-labs/notify: unsupported emailProvider "${String(input.emailProvider)}"`,
+		)
+	}
+}

package/src/retry.ts

@@ -0,0 +1,86 @@
+export interface RetryOptions {
+	maxAttempts: number
+	baseMs: number
+	multiplier: number
+	jitterFactor: number
+}
+
+export type RetryResult<T> =
+	| { ok: true; value: T; attempts: number }
+	| { ok: false; error: string; attempts: number }
+
+const DEFAULT_RETRY_OPTIONS: RetryOptions = {
+	maxAttempts: 3,
+	baseMs: 250,
+	multiplier: 4,
+	jitterFactor: 0.2,
+}
+
+export class DeliveryError extends Error {
+	constructor(
+		message: string,
+		public readonly retryable: boolean,
+	) {
+		super(message)
+		this.name = 'DeliveryError'
+	}
+}
+
+export async function withRetry<T>(
+	fn: (attempt: number) => Promise<T>,
+	shouldRetry: (err: unknown, attempt: number) => boolean,
+	options?: Partial<RetryOptions>,
+): Promise<RetryResult<T>> {
+	const resolved = { ...DEFAULT_RETRY_OPTIONS, ...options }
+	const maxAttempts = Math.max(1, Math.floor(resolved.maxAttempts))
+	let lastError: unknown
+
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		try {
+			const value = await fn(attempt)
+			return { ok: true, value, attempts: attempt }
+		} catch (error) {
+			lastError = error
+			if (attempt >= maxAttempts || !shouldRetry(error, attempt)) {
+				return { ok: false, error: errorMessage(error), attempts: attempt }
+			}
+
+			await sleep(delayForAttempt(attempt, resolved))
+		}
+	}
+
+	return { ok: false, error: errorMessage(lastError), attempts: maxAttempts }
+}
+
+export function shouldRetryDeliveryError(error: unknown): boolean {
+	if (error instanceof DeliveryError) {
+		return error.retryable
+	}
+	return true
+}
+
+export function errorMessage(error: unknown): string {
+	if (error instanceof Error) {
+		return error.message
+	}
+	if (typeof error === 'string') {
+		return error
+	}
+	try {
+		return JSON.stringify(error)
+	} catch {
+		return String(error)
+	}
+}
+
+function delayForAttempt(attempt: number, options: RetryOptions): number {
+	const baseDelay = options.baseMs * options.multiplier ** (attempt - 1)
+	const jitter = 1 + (Math.random() * 2 - 1) * options.jitterFactor
+	return Math.max(0, Math.round(baseDelay * jitter))
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+export type Severity = 'info' | 'warning' | 'critical'
+export type Channel = 'slack' | 'email'
+export type EmailProvider = 'cloudflare' | 'resend'
+
+export interface SlackBlock {
+	type: string
+	text?: { type: 'mrkdwn' | 'plain_text'; text: string }
+	[key: string]: unknown
+}
+
+export interface SentRecord {
+	channel: Channel
+	severity: Severity
+	title: string
+	dedupKey?: string
+	attempts: number
+	sentAt: number
+}
+
+export interface NotifyInput {
+	channels: Channel[]
+	severity: Severity
+	title: string
+	body: string
+	blocks?: SlackBlock[]
+	dedupKey?: string
+	dedupFn?: (dedupKey: string) => Promise<boolean>
+	onSent?: (record: SentRecord) => Promise<void>
+	emailProvider?: EmailProvider
+}
+
+export interface SendEmailBinding {
+	send(message: unknown): Promise<unknown>
+}
+
+export interface NotifyEnv {
+	NOTIFY_SLACK_WEBHOOK?: string
+	SEND_EMAIL?: SendEmailBinding
+	RESEND_API_KEY?: string
+	NOTIFY_EMAIL_TO?: string
+	NOTIFY_EMAIL_FROM?: string
+}
+
+export interface NotifyResult {
+	attempted: Channel[]
+	sent: Channel[]
+	skipped: {
+		channel: Channel
+		reason: 'deduped' | 'missing-binding' | 'severity-routing'
+	}[]
+	failed: { channel: Channel; error: string }[]
+}