@growth-labs/push 0.2.0 → 0.4.1

package/src/options.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+
+export const pushOptionsSchema = z.object({
+	vapidPublicKey: z.string().min(1),
+	vapidPrivateKey: z.string().min(1),
+	vapidSubject: z.string().min(1),
+
+	d1Binding: z.string().default('SITE_DB'),
+	queueBinding: z.string().default('PUSH_QUEUE'),
+
+	defaults: z
+		.object({
+			icon: z.string().optional(),
+			ttl: z.number().int().positive().default(86400),
+			urgency: z.enum(['very-low', 'low', 'normal', 'high']).default('normal'),
+		})
+		.default({}),
+
+	queue: z
+		.object({
+			batchSize: z.number().int().positive().default(100),
+			maxRetries: z.number().int().nonnegative().default(3),
+		})
+		.default({}),
+
+	turnstile: z.object({
+		secretKey: z.string().min(1),
+	}),
+
+	routes: z
+		.object({
+			subscribe: z.string().default('/api/push/subscribe'),
+			unsubscribe: z.string().default('/api/push/unsubscribe'),
+		})
+		.default({}),
+
+	cleanup: z
+		.object({
+			staleAfterDays: z.number().int().positive().default(90),
+		})
+		.default({}),
+})
+
+export type PushOptions = z.input<typeof pushOptionsSchema>
+export type ResolvedPushOptions = z.output<typeof pushOptionsSchema>

package/src/routes/subscribe.ts

@@ -0,0 +1,82 @@
+import { env } from 'cloudflare:workers'
+import config from 'virtual:growth-labs/push/config'
+import type { APIRoute } from 'astro'
+import { trackPushSubscription } from '../utils/analytics.js'
+import { findSubscriptionByEndpoint, saveSubscription } from '../utils/subscriptions.js'
+import { verifyTurnstile } from '../utils/turnstile.js'
+
+export const POST: APIRoute = async ({ request }) => {
+	const body = (await request.json()) as Record<string, unknown>
+
+	const turnstileToken = body.turnstileToken as string | undefined
+	if (!turnstileToken) {
+		return new Response(JSON.stringify({ error: 'Missing Turnstile token' }), {
+			status: 400,
+			headers: { 'Content-Type': 'application/json' },
+		})
+	}
+
+	const envMap = env as Record<string, unknown>
+	const turnstileSecret =
+		(envMap[config.turnstile.secretKey] as string) ?? (envMap.TURNSTILE_SECRET as string)
+	const turnstileValid = await verifyTurnstile(
+		turnstileToken,
+		turnstileSecret,
+		request.headers.get('CF-Connecting-IP'),
+	)
+	if (!turnstileValid) {
+		return new Response(JSON.stringify({ error: 'Bot detected' }), {
+			status: 403,
+			headers: { 'Content-Type': 'application/json' },
+		})
+	}
+
+	const sub = (body.subscription ?? {}) as Record<string, unknown>
+	const endpoint = sub.endpoint as string | undefined
+	const keys = sub.keys as Record<string, string> | undefined
+	if (!endpoint || !keys?.p256dh || !keys?.auth) {
+		return new Response(JSON.stringify({ error: 'Invalid subscription' }), {
+			status: 400,
+			headers: { 'Content-Type': 'application/json' },
+		})
+	}
+
+	const db = envMap[config.d1Binding] as D1Database
+	const existing = await findSubscriptionByEndpoint(db, endpoint)
+	if (existing) {
+		await saveSubscription(db, {
+			...existing,
+			keyP256dh: keys.p256dh,
+			keyAuth: keys.auth,
+			failureCount: 0,
+			lastDeliveryAt: null,
+		})
+		return new Response(JSON.stringify({ ok: true, updated: true }), {
+			status: 200,
+			headers: { 'Content-Type': 'application/json' },
+		})
+	}
+
+	await saveSubscription(db, {
+		id: crypto.randomUUID(),
+		endpoint,
+		keyP256dh: keys.p256dh,
+		keyAuth: keys.auth,
+		topics: null,
+		createdAt: Math.floor(Date.now() / 1000),
+		lastDeliveryAt: null,
+		failureCount: 0,
+		userAgent: request.headers.get('User-Agent'),
+		country: request.headers.get('CF-IPCountry') ?? null,
+	})
+
+	trackPushSubscription('subscribed', {
+		country: request.headers.get('CF-IPCountry') ?? undefined,
+		userAgent: request.headers.get('User-Agent') ?? undefined,
+	}).catch(() => {})
+
+	return new Response(JSON.stringify({ ok: true, created: true }), {
+		status: 201,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}

package/src/routes/unsubscribe.ts

@@ -0,0 +1,29 @@
+import { env } from 'cloudflare:workers'
+import config from 'virtual:growth-labs/push/config'
+import type { APIRoute } from 'astro'
+import { trackPushSubscription } from '../utils/analytics.js'
+import { deleteSubscriptionByEndpoint } from '../utils/subscriptions.js'
+
+export const POST: APIRoute = async ({ request }) => {
+	const body = (await request.json()) as Record<string, unknown>
+	const endpoint = body.endpoint as string | undefined
+
+	if (!endpoint) {
+		return new Response(JSON.stringify({ error: 'Missing endpoint' }), {
+			status: 400,
+			headers: { 'Content-Type': 'application/json' },
+		})
+	}
+
+	const db = (env as Record<string, unknown>)[config.d1Binding] as D1Database
+	const deleted = await deleteSubscriptionByEndpoint(db, endpoint)
+
+	if (deleted) {
+		trackPushSubscription('unsubscribed').catch(() => {})
+	}
+
+	return new Response(JSON.stringify({ ok: true, deleted }), {
+		status: 200,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+/** Push notification payload — what the user sees */
+export interface PushPayload {
+	title: string
+	body: string
+	icon?: string
+	image?: string
+	url: string
+	action?: {
+		title: string
+		url: string
+	}
+	tag?: string
+}
+
+/** Per-notification delivery options */
+export interface PushSendOptions {
+	ttl?: number
+	urgency?: 'very-low' | 'low' | 'normal' | 'high'
+}
+
+/** A push subscription as stored in D1 / received from the browser */
+export interface PushSubscriptionRecord {
+	id: string
+	endpoint: string
+	keyP256dh: string
+	keyAuth: string
+	topics: string | null
+	createdAt: number
+	lastDeliveryAt: number | null
+	failureCount: number
+	userAgent: string | null
+	country: string | null
+}
+
+/**
+ * Queue message shape for batch sends.
+ *
+ * VAPID credentials are NOT included. The Queue consumer Worker reads them
+ * from its own env bindings (Cloudflare Secrets). This keeps the private key
+ * in exactly one place and avoids serializing it into every Queue message.
+ *
+ * `siteId` identifies which site enqueued the message. The realm consumer
+ * uses it with `siteConfigLookup` to apply per-site overrides (icon URL,
+ * VAPID identity, etc.). Sites in single-tenant mode can pass any string.
+ */
+export interface PushQueueMessage {
+	siteId: string
+	subscriptions: PushSubscriptionRecord[]
+	payload: PushPayload
+	options: PushSendOptions
+}
+
+/**
+ * Per-site config override applied at consumer time. Returned from
+ * SitePushConfigLookup. All fields are optional — only the ones present
+ * will override the consumer context for that message.
+ */
+export interface SitePushConfig {
+	defaults?: {
+		icon?: string
+		ttl?: number
+		urgency?: 'very-low' | 'low' | 'normal' | 'high'
+	}
+	vapid?: {
+		subject?: string
+		publicKey?: string
+		privateKey?: string
+	}
+}
+
+/**
+ * Per-message lookup. The realm consumer calls it with the message's
+ * `siteId`. Returns the per-site config to apply, or `null` to skip the
+ * override and use the consumer's context as-is.
+ */
+export type SitePushConfigLookup = (
+	siteId: string,
+	env: Record<string, unknown>,
+) => Promise<SitePushConfig | null>
+
+/** Result of a single push send attempt */
+export interface PushSendResult {
+	subscriptionId: string
+	success: boolean
+	statusCode?: number
+	error?: string
+	expired?: boolean
+}
+
+/** Batch send result */
+export interface PushBatchResult {
+	sent: number
+	failed: number
+	expired: number
+	results: PushSendResult[]
+}
+
+/** What the middleware puts on context.locals */
+export interface PushLocals {
+	push: {
+		vapidPublicKey: string
+	}
+}
+
+/** Serializable config exported by the virtual module */
+export interface PushConfig {
+	vapidPublicKey: string
+	d1Binding: string
+	queueBinding: string
+	defaults: {
+		icon?: string
+		ttl: number
+		urgency: 'very-low' | 'low' | 'normal' | 'high'
+	}
+	queue: {
+		batchSize: number
+		maxRetries: number
+	}
+	turnstile: {
+		secretKey: string
+	}
+	routes: {
+		subscribe: string
+		unsubscribe: string
+	}
+	cleanup: {
+		staleAfterDays: number
+	}
+}

package/src/utils/analytics.ts

@@ -0,0 +1,96 @@
+import type { PushBatchResult, PushPayload } from '../types.js'
+
+/** Module name kept in a variable so TypeScript doesn't try to resolve it at compile time */
+const ANALYTICS_MODULE = '@growth-labs/analytics'
+
+/**
+ * Server-side analytics helper for push events.
+ *
+ * Uses optional peer dependency on @growth-labs/analytics.
+ * If analytics is not installed, events are silently dropped.
+ * This follows the project convention: optional peer dependency + dynamic import with try/catch.
+ */
+export async function trackPushEvent(
+	eventName: string,
+	data: Record<string, unknown>,
+): Promise<void> {
+	try {
+		const analytics = (await import(/* @vite-ignore */ ANALYTICS_MODULE)) as Record<string, unknown>
+		if (analytics && typeof analytics.trackServerEvent === 'function') {
+			await (
+				analytics.trackServerEvent as (name: string, data: Record<string, unknown>) => Promise<void>
+			)(eventName, data)
+		}
+	} catch {
+		// @growth-labs/analytics not installed — silently skip
+	}
+}
+
+/**
+ * Track a push notification send completion.
+ * Call after a batch send completes (in queue consumer or direct send).
+ */
+export async function trackPushSend(payload: PushPayload, result: PushBatchResult): Promise<void> {
+	await trackPushEvent('push_notification_sent', {
+		title: payload.title,
+		tag: payload.tag,
+		url: payload.url,
+		sent: result.sent,
+		failed: result.failed,
+		expired: result.expired,
+	})
+}
+
+/**
+ * Track a push subscription event (subscribe or unsubscribe).
+ * Call from route handlers after successful subscription changes.
+ */
+export async function trackPushSubscription(
+	action: 'subscribed' | 'unsubscribed',
+	metadata: { endpoint?: string; country?: string; userAgent?: string } = {},
+): Promise<void> {
+	await trackPushEvent(`push_${action}`, {
+		country: metadata.country,
+		userAgent: metadata.userAgent,
+	})
+}
+
+/**
+ * Track a push cleanup event.
+ * Call after subscription cleanup runs.
+ */
+export async function trackPushCleanup(removed: number): Promise<void> {
+	await trackPushEvent('push_cleanup', { removed })
+}
+
+/**
+ * Emit a client-side analytics event using the gl:* CustomEvent pattern.
+ * This is meant to be called from browser-side code (service worker or page).
+ *
+ * Packages emit CustomEvent on document with gl: prefix. These are local
+ * browser signals; consumers call window.glAnalytics.track(...) when an event
+ * should be persisted to WAE.
+ *
+ * Usage in service worker notificationclick handler:
+ * ```javascript
+ * // In the page after notification click navigation
+ * document.dispatchEvent(new CustomEvent('gl:push_notification_clicked', {
+ *   detail: { tag: 'article-123', url: '/articles/123' }
+ * }))
+ * ```
+ *
+ * This function is a convenience wrapper for use in page scripts.
+ */
+export function emitPushAnalyticsEvent(
+	eventName: string,
+	detail: Record<string, unknown> = {},
+): void {
+	// Check for browser environment — this function is a no-op on the server
+	const doc =
+		typeof globalThis !== 'undefined'
+			? (globalThis as unknown as { document?: { dispatchEvent(event: Event): boolean } }).document
+			: undefined
+	if (doc) {
+		doc.dispatchEvent(new CustomEvent(`gl:${eventName}`, { detail }))
+	}
+}

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'