@growth-labs/push 0.2.0 → 0.4.1

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 }
+}

package/src/utils/subscriptions.ts

@@ -0,0 +1,124 @@
+import type { PushSubscriptionRecord } from '../types.js'
+
+/** Insert or update a subscription */
+export async function saveSubscription(db: D1Database, sub: PushSubscriptionRecord): Promise<void> {
+	await db
+		.prepare(
+			`INSERT INTO gl_push_subscriptions
+			 (id, endpoint, key_p256dh, key_auth, topics, created_at, last_delivery_at, failure_count, user_agent, country)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			 ON CONFLICT (endpoint) DO UPDATE SET
+				 key_p256dh = excluded.key_p256dh,
+				 key_auth = excluded.key_auth,
+				 failure_count = excluded.failure_count,
+				 last_delivery_at = excluded.last_delivery_at`,
+		)
+		.bind(
+			sub.id,
+			sub.endpoint,
+			sub.keyP256dh,
+			sub.keyAuth,
+			sub.topics,
+			sub.createdAt,
+			sub.lastDeliveryAt,
+			sub.failureCount,
+			sub.userAgent,
+			sub.country,
+		)
+		.run()
+}
+
+/** Find a subscription by its endpoint URL */
+export async function findSubscriptionByEndpoint(
+	db: D1Database,
+	endpoint: string,
+): Promise<PushSubscriptionRecord | null> {
+	const result = await db
+		.prepare('SELECT * FROM gl_push_subscriptions WHERE endpoint = ?')
+		.bind(endpoint)
+		.first()
+
+	return result ? mapRow(result) : null
+}
+
+/** Delete a subscription by endpoint. Returns true if a row was deleted. */
+export async function deleteSubscriptionByEndpoint(
+	db: D1Database,
+	endpoint: string,
+): Promise<boolean> {
+	const result = await db
+		.prepare('DELETE FROM gl_push_subscriptions WHERE endpoint = ?')
+		.bind(endpoint)
+		.run()
+
+	return (result.meta?.changes ?? 0) > 0
+}
+
+/** Delete a subscription by ID */
+export async function deleteSubscriptionById(db: D1Database, id: string): Promise<void> {
+	await db.prepare('DELETE FROM gl_push_subscriptions WHERE id = ?').bind(id).run()
+}
+
+/** Get subscriptions with offset-based pagination. Used by enqueuePushBatchAll. */
+export async function getAllSubscriptions(
+	db: D1Database,
+	options: { limit?: number; offset?: number } = {},
+): Promise<PushSubscriptionRecord[]> {
+	const limit = options.limit ?? 1000
+	const offset = options.offset ?? 0
+
+	const result = await db
+		.prepare('SELECT * FROM gl_push_subscriptions ORDER BY created_at ASC LIMIT ? OFFSET ?')
+		.bind(limit, offset)
+		.all()
+
+	return (result.results ?? []).map(mapRow)
+}
+
+/** Count total subscriptions */
+export async function countSubscriptions(db: D1Database): Promise<number> {
+	const result = await db
+		.prepare('SELECT COUNT(*) as count FROM gl_push_subscriptions')
+		.first<{ count: number }>()
+
+	return result?.count ?? 0
+}
+
+/** Mark a subscription as successfully delivered */
+export async function markDelivered(db: D1Database, id: string): Promise<void> {
+	await db
+		.prepare(
+			`UPDATE gl_push_subscriptions
+			 SET last_delivery_at = ?, failure_count = 0
+			 WHERE id = ?`,
+		)
+		.bind(Math.floor(Date.now() / 1000), id)
+		.run()
+}
+
+/** Increment failure count for a subscription */
+export async function incrementFailureCount(db: D1Database, id: string): Promise<void> {
+	await db
+		.prepare(
+			`UPDATE gl_push_subscriptions
+			 SET failure_count = failure_count + 1
+			 WHERE id = ?`,
+		)
+		.bind(id)
+		.run()
+}
+
+function mapRow(row: Record<string, unknown>): PushSubscriptionRecord {
+	return {
+		id: row.id as string,
+		endpoint: row.endpoint as string,
+		keyP256dh: row.key_p256dh as string, // gitleaks:allow - Web Push field name, not literal secret material.
+		keyAuth: row.key_auth as string,
+		topics: row.topics as string | null,
+		createdAt: row.created_at as number,
+		lastDeliveryAt: row.last_delivery_at as number | null,
+		failureCount: row.failure_count as number,
+		userAgent: row.user_agent as string | null,
+		country: row.country as string | null,
+	}
+}

package/src/utils/turnstile.ts

@@ -0,0 +1,25 @@
+/**
+ * Verify a Turnstile token server-side.
+ */
+export async function verifyTurnstile(
+	token: string,
+	secretKey: string,
+	remoteIp: string | null,
+): Promise<boolean> {
+	try {
+		const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				secret: secretKey,
+				response: token,
+				remoteip: remoteIp,
+			}),
+		})
+
+		const result = (await response.json()) as { success: boolean }
+		return result.success
+	} catch {
+		return false
+	}
+}

package/src/utils/vapid.ts

@@ -0,0 +1,28 @@
+/**
+ * Generate a new VAPID key pair using Web Crypto API.
+ * Run this once during project setup. Store the private key as a Cloudflare Secret.
+ */
+export async function generateVapidKeys(): Promise<{
+	publicKey: string
+	privateKey: string
+}> {
+	const keyPair = await crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
+		'sign',
+		'verify',
+	])
+
+	const privateJwk = await crypto.subtle.exportKey('jwk', keyPair.privateKey)
+	const publicRaw = await crypto.subtle.exportKey('raw', keyPair.publicKey)
+	const publicKey = uint8ArrayToUrlSafeBase64(new Uint8Array(publicRaw))
+
+	return {
+		publicKey,
+		privateKey: JSON.stringify(privateJwk),
+	}
+}
+
+/** Convert a Uint8Array to URL-safe base64 (no padding) */
+function uint8ArrayToUrlSafeBase64(bytes: Uint8Array): string {
+	const binary = String.fromCharCode(...bytes)
+	return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}

package/src/client/push-sw.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"push-sw.d.ts","sourceRoot":"","sources":["push-sw.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAgBjD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAUtE"}

package/src/client/push-sw.js

@@ -1,25 +0,0 @@
-/// <reference lib="webworker" />
-export function handlePush(event) {
-	const data = event.data?.json() ?? {}
-	const options = {
-		body: data.body ?? '',
-		icon: data.icon,
-		image: data.image,
-		tag: data.tag,
-		data: {
-			url: data.url,
-			actionUrl: data.action?.url,
-		},
-		actions: data.action ? [{ action: 'primary', title: data.action.title }] : [],
-	}
-	event.waitUntil(self.registration.showNotification(data.title ?? 'Notification', options))
-}
-export function handleNotificationClick(event) {
-	event.notification.close()
-	const data = event.notification.data ?? {}
-	const url = event.action === 'primary' && data.actionUrl ? data.actionUrl : data.url
-	if (url) {
-		event.waitUntil(self.clients.openWindow(url))
-	}
-}
-//# sourceMappingURL=push-sw.js.map

package/src/client/push-sw.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"push-sw.js","sourceRoot":"","sources":["push-sw.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAGjC,MAAM,UAAU,UAAU,CAAC,KAAgB;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAErC,MAAM,OAAO,GAAG;QACf,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE;YACL,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG;SAC3B;QACD,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;KACrB,CAAA;IAEzD,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI,cAAc,EAAE,OAAO,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAwB;IAC/D,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,CAAA;IAE1B,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,IAAI,EAAE,CAAA;IAE1C,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAA;IAEpF,IAAI,GAAG,EAAE,CAAC;QACT,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;IAC9C,CAAC;AACF,CAAC"}