@growth-labs/push 0.4.0 → 0.4.2

package/src/utils/cleanup.ts

@@ -0,0 +1,28 @@
+interface CleanupResult {
+	removed: number
+}
+
+/**
+ * Remove stale or high-failure subscriptions.
+ * Call from a cron trigger or maintenance script.
+ */
+export async function cleanupStaleSubscriptions(
+	db: D1Database,
+	options: { staleAfterDays: number },
+): Promise<CleanupResult> {
+	const cutoff = Math.floor(Date.now() / 1000) - options.staleAfterDays * 86400
+
+	const result = await db
+		.prepare(
+			`DELETE FROM gl_push_subscriptions
+			 WHERE (last_delivery_at IS NOT NULL AND last_delivery_at < ?)
+					OR (last_delivery_at IS NULL AND created_at < ?)
+					OR failure_count >= 10`,
+		)
+		.bind(cutoff, cutoff)
+		.run()
+
+	return {
+		removed: result.meta?.changes ?? 0,
+	}
+}

package/src/utils/composer.ts

@@ -0,0 +1,141 @@
+import type { PushPayload } from '../types.js'
+
+/**
+ * A push notification template with placeholder support.
+ * Placeholders use {{key}} syntax and are replaced at compose time.
+ */
+export interface PushTemplate {
+	/** Template name for identification */
+	name: string
+	/** Title with optional {{placeholders}} */
+	title: string
+	/** Body with optional {{placeholders}} */
+	body: string
+	/** Default icon URL (can be overridden at compose time) */
+	icon?: string
+	/** Default image URL with optional {{placeholders}} */
+	image?: string
+	/** URL pattern with optional {{placeholders}} */
+	url: string
+	/** Optional action button */
+	action?: {
+		title: string
+		url: string
+	}
+	/** Optional dedup tag with {{placeholders}} */
+	tag?: string
+}
+
+/** Variables to interpolate into a template */
+export type TemplateVariables = Record<string, string>
+
+/**
+ * Replace {{key}} placeholders in a string with values from the variables map.
+ * Unknown placeholders are left as-is.
+ */
+function interpolate(template: string, variables: TemplateVariables): string {
+	return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+		return key in variables ? variables[key] : match
+	})
+}
+
+/**
+ * Compose a PushPayload from a template and variables.
+ *
+ * Templates define the structure with {{placeholder}} tokens.
+ * Variables fill in the dynamic parts at send time.
+ *
+ * ```typescript
+ * const template: PushTemplate = {
+ *   name: 'new-article',
+ *   title: 'New on {{siteName}}',
+ *   body: '{{articleTitle}}',
+ *   url: 'https://{{domain}}/articles/{{slug}}',
+ *   icon: '/icons/notification-192.png',
+ *   tag: 'article-{{slug}}',
+ *   action: {
+ *     title: 'Read article',
+ *     url: 'https://{{domain}}/articles/{{slug}}',
+ *   },
+ * }
+ *
+ * const payload = composePushPayload(template, {
+ *   siteName: 'FEDweek',
+ *   domain: 'fedweek.com',
+ *   articleTitle: 'Federal Pay Freeze Announced',
+ *   slug: 'pay-freeze-2026',
+ * })
+ * ```
+ */
+export function composePushPayload(
+	template: PushTemplate,
+	variables: TemplateVariables = {},
+	overrides: Partial<PushPayload> = {},
+): PushPayload {
+	const payload: PushPayload = {
+		title: interpolate(template.title, variables),
+		body: interpolate(template.body, variables),
+		url: interpolate(template.url, variables),
+	}
+
+	if (template.icon) {
+		payload.icon = interpolate(template.icon, variables)
+	}
+
+	if (template.image) {
+		payload.image = interpolate(template.image, variables)
+	}
+
+	if (template.tag) {
+		payload.tag = interpolate(template.tag, variables)
+	}
+
+	if (template.action) {
+		payload.action = {
+			title: interpolate(template.action.title, variables),
+			url: interpolate(template.action.url, variables),
+		}
+	}
+
+	return { ...payload, ...overrides }
+}
+
+/**
+ * Built-in templates for common notification patterns.
+ * Consumers can use these directly or define their own.
+ */
+export const templates = {
+	/** New content published notification */
+	newContent: {
+		name: 'new-content',
+		title: 'New on {{siteName}}',
+		body: '{{contentTitle}}',
+		url: '{{contentUrl}}',
+		tag: 'content-{{contentId}}',
+		action: {
+			title: 'Read now',
+			url: '{{contentUrl}}',
+		},
+	},
+
+	/** Breaking news / high-urgency notification */
+	breaking: {
+		name: 'breaking',
+		title: 'Breaking: {{headline}}',
+		body: '{{summary}}',
+		url: '{{contentUrl}}',
+		tag: 'breaking-{{contentId}}',
+		action: {
+			title: 'Read more',
+			url: '{{contentUrl}}',
+		},
+	},
+
+	/** Generic notification with just title and body */
+	generic: {
+		name: 'generic',
+		title: '{{title}}',
+		body: '{{body}}',
+		url: '{{url}}',
+	},
+} as const satisfies Record<string, PushTemplate>

package/src/utils/index.ts

@@ -0,0 +1,38 @@
+export {
+	emitPushAnalyticsEvent,
+	trackPushCleanup,
+	trackPushEvent,
+	trackPushSend,
+	trackPushSubscription,
+} from './analytics.js'
+export { cleanupStaleSubscriptions } from './cleanup.js'
+export {
+	composePushPayload,
+	type PushTemplate,
+	type TemplateVariables,
+	templates,
+} from './composer.js'
+export { enqueuePushBatch, enqueuePushBatchAll } from './queue.js'
+export {
+	handleScheduledPush,
+	type ScheduledContentProvider,
+	type ScheduledPushContext,
+	type ScheduledPushResult,
+} from './scheduled.js'
+export {
+	type SendContext,
+	sendPushBatch,
+	sendPushNotification,
+} from './send.js'
+export {
+	countSubscriptions,
+	deleteSubscriptionByEndpoint,
+	deleteSubscriptionById,
+	findSubscriptionByEndpoint,
+	getAllSubscriptions,
+	incrementFailureCount,
+	markDelivered,
+	saveSubscription,
+} from './subscriptions.js'
+export { verifyTurnstile } from './turnstile.js'
+export { generateVapidKeys } from './vapid.js'

package/src/utils/queue.ts

@@ -0,0 +1,173 @@
+import type {
+	PushPayload,
+	PushQueueMessage,
+	PushSendOptions,
+	PushSubscriptionRecord,
+	SitePushConfig,
+	SitePushConfigLookup,
+} from '../types.js'
+import { type SendContext, sendPushBatch } from './send.js'
+import {
+	deleteSubscriptionById,
+	getAllSubscriptions,
+	incrementFailureCount,
+	markDelivered,
+} from './subscriptions.js'
+
+interface EnqueueContext {
+	queue: Queue
+	siteId: string
+	batchSize?: number
+}
+
+/**
+ * Split a known set of subscriptions into batches and enqueue each batch.
+ * Each emitted message carries the caller's `siteId` so the realm consumer
+ * can apply per-site overrides via `siteConfigLookup`.
+ */
+export async function enqueuePushBatch(
+	subscriptions: PushSubscriptionRecord[],
+	payload: PushPayload,
+	context: EnqueueContext,
+	options: PushSendOptions = {},
+): Promise<{ batches: number; totalSubscriptions: number }> {
+	const batchSize = context.batchSize ?? 100
+	let batches = 0
+
+	for (let i = 0; i < subscriptions.length; i += batchSize) {
+		const batch = subscriptions.slice(i, i + batchSize)
+		const message: PushQueueMessage = {
+			siteId: context.siteId,
+			subscriptions: batch,
+			payload,
+			options,
+		}
+		await context.queue.send(message)
+		batches++
+	}
+
+	return {
+		batches,
+		totalSubscriptions: subscriptions.length,
+	}
+}
+
+/**
+ * Page through all subscriptions in D1 and enqueue batches as it goes.
+ * Never holds more than one page of subscriptions in memory.
+ */
+export async function enqueuePushBatchAll(
+	db: D1Database,
+	payload: PushPayload,
+	context: EnqueueContext,
+	options: PushSendOptions = {},
+): Promise<{ batches: number; totalSubscriptions: number }> {
+	const batchSize = context.batchSize ?? 100
+	let offset = 0
+	let batches = 0
+	let total = 0
+
+	while (true) {
+		const subs = await getAllSubscriptions(db, { limit: batchSize, offset })
+		if (subs.length === 0) break
+
+		const message: PushQueueMessage = {
+			siteId: context.siteId,
+			subscriptions: subs,
+			payload,
+			options,
+		}
+		await context.queue.send(message)
+
+		batches++
+		total += subs.length
+		offset += batchSize
+	}
+
+	return { batches, totalSubscriptions: total }
+}
+
+interface QueueConsumerContext {
+	db: D1Database
+	vapid: {
+		subject: string
+		publicKey: string
+		privateKey: string
+	}
+	defaults: {
+		icon?: string
+		ttl: number
+		urgency: 'very-low' | 'low' | 'normal' | 'high'
+	}
+	/**
+	 * Optional realm-level multi-tenant lookup. When provided, the consumer
+	 * calls it per message using `message.body.siteId` and merges the result
+	 * over the base context for that batch.
+	 */
+	siteConfigLookup?: SitePushConfigLookup
+	/**
+	 * Worker env, forwarded to `siteConfigLookup` so the lookup can read
+	 * KV / D1 / etc. Required when `siteConfigLookup` is set.
+	 */
+	env?: Record<string, unknown>
+}
+
+function applyOverride(
+	context: QueueConsumerContext,
+	override: SitePushConfig | null,
+): { vapid: QueueConsumerContext['vapid']; defaults: QueueConsumerContext['defaults'] } {
+	if (!override) return { vapid: context.vapid, defaults: context.defaults }
+	return {
+		vapid: {
+			subject: override.vapid?.subject ?? context.vapid.subject,
+			publicKey: override.vapid?.publicKey ?? context.vapid.publicKey,
+			privateKey: override.vapid?.privateKey ?? context.vapid.privateKey,
+		},
+		defaults: {
+			icon: override.defaults?.icon ?? context.defaults.icon,
+			ttl: override.defaults?.ttl ?? context.defaults.ttl,
+			urgency: override.defaults?.urgency ?? context.defaults.urgency,
+		},
+	}
+}
+
+/**
+ * Queue consumer handler. Process a batch of push notification sends.
+ * VAPID credentials come from context — they are NOT in the Queue message.
+ * When `context.siteConfigLookup` is configured, per-message overrides are
+ * applied for VAPID identity and notification defaults.
+ */
+export async function handlePushQueue(
+	batch: MessageBatch<PushQueueMessage>,
+	context: QueueConsumerContext,
+): Promise<void> {
+	for (const message of batch.messages) {
+		const override = context.siteConfigLookup
+			? await context.siteConfigLookup(message.body.siteId, context.env ?? {})
+			: null
+		const effective = applyOverride(context, override)
+
+		const sendContext: SendContext = {
+			vapidSubject: effective.vapid.subject,
+			vapidPublicKey: effective.vapid.publicKey,
+			vapidPrivateKey: effective.vapid.privateKey,
+			defaults: effective.defaults,
+		}
+
+		const { subscriptions, payload, options } = message.body
+
+		const result = await sendPushBatch(subscriptions, payload, sendContext, options)
+
+		for (const sendResult of result.results) {
+			if (sendResult.success) {
+				await markDelivered(context.db, sendResult.subscriptionId)
+			} else if (sendResult.expired) {
+				await deleteSubscriptionById(context.db, sendResult.subscriptionId)
+			} else {
+				await incrementFailureCount(context.db, sendResult.subscriptionId)
+			}
+		}
+
+		message.ack()
+	}
+}

package/src/utils/scheduled.ts

@@ -0,0 +1,152 @@
+import type { PushPayload, PushSendOptions } from '../types.js'
+import { trackPushSend } from './analytics.js'
+import { cleanupStaleSubscriptions } from './cleanup.js'
+import { enqueuePushBatchAll } from './queue.js'
+
+/**
+ * Context required by the scheduled push handler.
+ * The consumer provides this from their cron trigger's env bindings.
+ */
+export interface ScheduledPushContext {
+	db: D1Database
+	queue: Queue
+	siteId: string
+	batchSize?: number
+	cleanup: {
+		staleAfterDays: number
+	}
+}
+
+/**
+ * Result of a scheduled push run.
+ */
+export interface ScheduledPushResult {
+	notification: {
+		batches: number
+		totalSubscriptions: number
+	} | null
+	cleanup: {
+		removed: number
+	}
+}
+
+/**
+ * A content provider function that returns a push payload if there is
+ * something to send, or null if there is nothing to notify about.
+ *
+ * The consumer implements this to check for new content, scheduled
+ * campaigns, or other triggers that should produce a notification.
+ *
+ * ```typescript
+ * const provider: ScheduledContentProvider = async (context) => {
+ *   const latest = await context.db
+ *     .prepare('SELECT * FROM articles WHERE published_at > ? AND push_sent = 0 LIMIT 1')
+ *     .bind(Date.now() / 1000 - 3600)
+ *     .first()
+ *
+ *   if (!latest) return null
+ *
+ *   await context.db
+ *     .prepare('UPDATE articles SET push_sent = 1 WHERE id = ?')
+ *     .bind(latest.id)
+ *     .run()
+ *
+ *   return {
+ *     payload: {
+ *       title: 'New article',
+ *       body: latest.title as string,
+ *       url: `https://example.com/articles/${latest.slug}`,
+ *     },
+ *   }
+ * }
+ * ```
+ */
+export type ScheduledContentProvider = (context: {
+	db: D1Database
+}) => Promise<{ payload: PushPayload; options?: PushSendOptions } | null>
+
+/**
+ * Cron-triggered push handler. Wires together content checking, notification
+ * enqueuing, and subscription cleanup into a single scheduled invocation.
+ *
+ * The consumer wires this into their Cloudflare Worker's scheduled handler:
+ *
+ * ```typescript
+ * import { handleScheduledPush } from '@growth-labs/push/utils'
+ *
+ * export default {
+ *   async scheduled(event, env) {
+ *     await handleScheduledPush(
+ *       {
+ *         db: env.SITE_DB,
+ *         queue: env.PUSH_QUEUE,
+ *         cleanup: { staleAfterDays: 90 },
+ *       },
+ *       async ({ db }) => {
+ *         // Check for unsent content
+ *         const article = await db
+ *           .prepare('SELECT * FROM articles WHERE push_sent = 0 LIMIT 1')
+ *           .first()
+ *         if (!article) return null
+ *         return {
+ *           payload: {
+ *             title: 'New article',
+ *             body: article.title as string,
+ *             url: `https://example.com/${article.slug}`,
+ *           },
+ *         }
+ *       },
+ *     )
+ *   },
+ * }
+ * ```
+ *
+ * On each invocation:
+ * 1. Calls the content provider to check if there's something to send
+ * 2. If yes, enqueues push batches for all subscribers via the Queue
+ * 3. Always runs subscription cleanup to remove stale/dead subscriptions
+ */
+export async function handleScheduledPush(
+	context: ScheduledPushContext,
+	contentProvider: ScheduledContentProvider,
+): Promise<ScheduledPushResult> {
+	let notification: ScheduledPushResult['notification'] = null
+
+	// Step 1: Check if there's content to push
+	const content = await contentProvider({ db: context.db })
+
+	// Step 2: Enqueue notifications if content is available
+	if (content) {
+		const enqueueResult = await enqueuePushBatchAll(
+			context.db,
+			content.payload,
+			{ queue: context.queue, siteId: context.siteId, batchSize: context.batchSize },
+			content.options ?? {},
+		)
+
+		notification = {
+			batches: enqueueResult.batches,
+			totalSubscriptions: enqueueResult.totalSubscriptions,
+		}
+
+		// Emit server-side analytics event if @growth-labs/analytics is available
+		await trackPushSend(content.payload, {
+			sent: enqueueResult.totalSubscriptions,
+			failed: 0,
+			expired: 0,
+			results: [],
+		})
+	}
+
+	// Step 3: Always clean up stale subscriptions
+	const cleanupResult = await cleanupStaleSubscriptions(context.db, {
+		staleAfterDays: context.cleanup.staleAfterDays,
+	})
+
+	return {
+		notification,
+		cleanup: {
+			removed: cleanupResult.removed,
+		},
+	}
+}

package/src/utils/send.ts

@@ -0,0 +1,140 @@
+import { buildPushPayload } from '@block65/webcrypto-web-push'
+import type {
+	PushBatchResult,
+	PushPayload,
+	PushSendOptions,
+	PushSendResult,
+	PushSubscriptionRecord,
+} from '../types.js'
+
+export interface SendContext {
+	vapidSubject: string
+	vapidPublicKey: string
+	vapidPrivateKey: string
+	defaults: {
+		icon?: string
+		ttl: number
+		urgency: 'very-low' | 'low' | 'normal' | 'high'
+	}
+}
+
+/** Map our urgency values to what the library supports */
+function mapUrgency(urgency: 'very-low' | 'low' | 'normal' | 'high'): 'low' | 'normal' | 'high' {
+	return urgency === 'very-low' ? 'low' : urgency
+}
+
+/**
+ * Send a push notification to a single subscription.
+ * Uses Web Crypto API for VAPID signing and RFC 8291 payload encryption.
+ */
+export async function sendPushNotification(
+	subscription: PushSubscriptionRecord,
+	payload: PushPayload,
+	context: SendContext,
+	options: PushSendOptions = {},
+): Promise<PushSendResult> {
+	const ttl = options.ttl ?? context.defaults.ttl
+	const urgency = options.urgency ?? context.defaults.urgency
+
+	const resolvedPayload: PushPayload = {
+		...payload,
+		icon: payload.icon ?? context.defaults.icon,
+	}
+
+	try {
+		// buildPushPayload(message, subscription, vapid) per @block65/webcrypto-web-push API
+		const pushRequest = await buildPushPayload(
+			{
+				data: JSON.parse(JSON.stringify(resolvedPayload)),
+				options: { ttl, urgency: mapUrgency(urgency) },
+			},
+			{
+				endpoint: subscription.endpoint,
+				expirationTime: null,
+				keys: {
+					p256dh: subscription.keyP256dh,
+					auth: subscription.keyAuth,
+				},
+			},
+			{
+				subject: context.vapidSubject,
+				publicKey: context.vapidPublicKey,
+				privateKey: context.vapidPrivateKey,
+			},
+		)
+
+		const response = await fetch(subscription.endpoint, {
+			method: pushRequest.method,
+			headers: pushRequest.headers,
+			body: pushRequest.body,
+		} as RequestInit)
+
+		if (response.status === 201) {
+			return { subscriptionId: subscription.id, success: true, statusCode: 201 }
+		}
+
+		if (response.status === 404 || response.status === 410) {
+			return {
+				subscriptionId: subscription.id,
+				success: false,
+				statusCode: response.status,
+				expired: true,
+				error: 'Subscription expired or unsubscribed',
+			}
+		}
+
+		if (response.status === 429) {
+			return {
+				subscriptionId: subscription.id,
+				success: false,
+				statusCode: 429,
+				error: 'Rate limited by push service',
+			}
+		}
+
+		return {
+			subscriptionId: subscription.id,
+			success: false,
+			statusCode: response.status,
+			error: `Push service returned ${response.status}`,
+		}
+	} catch (err) {
+		return {
+			subscriptionId: subscription.id,
+			success: false,
+			error: err instanceof Error ? err.message : 'Unknown error',
+		}
+	}
+}
+
+/**
+ * Send a push notification to multiple subscriptions sequentially.
+ * For small batches (< 100 subscriptions) called directly.
+ * For large subscriber counts, use enqueuePushBatchAll() instead.
+ */
+export async function sendPushBatch(
+	subscriptions: PushSubscriptionRecord[],
+	payload: PushPayload,
+	context: SendContext,
+	options: PushSendOptions = {},
+): Promise<PushBatchResult> {
+	const results: PushSendResult[] = []
+	let sent = 0
+	let failed = 0
+	let expired = 0
+
+	for (const sub of subscriptions) {
+		const result = await sendPushNotification(sub, payload, context, options)
+		results.push(result)
+
+		if (result.success) {
+			sent++
+		} else if (result.expired) {
+			expired++
+		} else {
+			failed++
+		}
+	}
+
+	return { sent, failed, expired, results }
+}