@growth-labs/monitoring 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @growth-labs/monitoring
 
+## 0.1.1 — 2026-05-21
+
+### Fixed
+
+- Include package source files in the published npm tarball so shipped `.js.map`
+  and `.d.ts.map` entries resolve without Vite/Astro sourcemap warnings in
+  tarball-installed consumers.
+
 ## 0.1.0 - 2026-05-18
 
 - Added synthetic prober factory with GET, POST, and code-signin happy-path runners.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/monitoring",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Operational observability primitives for Growth Labs Cloudflare Workers: synthetic probes, Tail Worker capture, alerting, D1 schemas, and a status page.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -50,8 +50,11 @@
   },
   "files": [
     "dist",
-    "src/status-page",
-    "src/schemas/migrations",
+    "src/**/*.ts",
+    "src/**/*.astro",
+    "src/**/*.css",
+    "src/**/*.md",
+    "src/**/*.sql",
     "README.md",
     "CHANGELOG.md",
     "SPEC.md"

package/src/alerting/README.md

@@ -0,0 +1,13 @@
+# Monitoring Alerting
+
+The alerting layer is shared by the prober and Tail Worker.
+
+- Probe alerts open incidents after consecutive failed checks and close them
+  after consecutive successful checks.
+- Error alerts fire on new fingerprints outside the dedup window and on rate
+  spikes inside the configured rate window.
+- Incident helpers read and write `gl_uptime_incidents`.
+- Escalation helpers generate actions at 30 minutes, 4 hours, and 24 hours.
+
+Alert delivery is delegated to `@growth-labs/notify`. This package owns when an
+alert should fire; notify owns Slack/email transport behavior.

package/src/alerting/dedup.ts

@@ -0,0 +1,70 @@
+import { errorMessage, generateId, type IdFactory, type UptimeIncident } from '../types.js'
+import type { AlertAction } from './index.js'
+
+export async function isIncidentOpen(
+	surface: string,
+	db: D1Database,
+): Promise<UptimeIncident | null> {
+	return db
+		.prepare(`
+			SELECT id, surface, opened_at, closed_at, trigger_check_id, resolve_check_id, severity, notes
+			FROM gl_uptime_incidents
+			WHERE surface = ? AND closed_at IS NULL
+			ORDER BY opened_at DESC
+			LIMIT 1
+		`)
+		.bind(surface)
+		.first<UptimeIncident>()
+}
+
+export async function openIncident(
+	action: AlertAction,
+	db: D1Database,
+	idFactory: IdFactory = generateId,
+	now = Date.now,
+): Promise<string> {
+	const existing = await isIncidentOpen(action.surface, db)
+	if (existing) return existing.id
+
+	const id = idFactory()
+	try {
+		await db
+			.prepare(`
+				INSERT INTO gl_uptime_incidents
+					(id, surface, opened_at, trigger_check_id, severity, notes)
+				VALUES (?, ?, ?, ?, ?, ?)
+			`)
+			.bind(
+				id,
+				action.surface,
+				Math.floor(now() / 1000),
+				typeof action.payload?.triggerCheckId === 'string' ? action.payload.triggerCheckId : null,
+				action.severity === 'critical' ? 'critical' : 'warning',
+				typeof action.payload?.notes === 'string' ? action.payload.notes : null,
+			)
+			.run()
+	} catch (error) {
+		console.error(`[monitoring] failed to open incident ${action.surface}: ${errorMessage(error)}`)
+	}
+	return id
+}
+
+export async function closeIncident(
+	incidentId: string,
+	resolveCheckId: string,
+	db: D1Database,
+	now = Date.now,
+): Promise<void> {
+	try {
+		await db
+			.prepare(`
+				UPDATE gl_uptime_incidents
+				SET closed_at = ?, resolve_check_id = ?
+				WHERE id = ? AND closed_at IS NULL
+			`)
+			.bind(Math.floor(now() / 1000), resolveCheckId, incidentId)
+			.run()
+	} catch (error) {
+		console.error(`[monitoring] failed to close incident ${incidentId}: ${errorMessage(error)}`)
+	}
+}

package/src/alerting/escalation.ts

@@ -0,0 +1,29 @@
+import type { UptimeIncident } from '../types.js'
+import type { AlertAction } from './index.js'
+
+export function evaluateEscalation(
+	incident: UptimeIncident,
+	nowSeconds = Math.floor(Date.now() / 1000),
+	alreadySent: Set<string> = new Set(),
+): AlertAction | null {
+	if (incident.closed_at !== null) return null
+	const ageSeconds = nowSeconds - incident.opened_at
+	const checkpoints = [
+		{ key: '24h', seconds: 24 * 60 * 60, severity: 'critical' as const },
+		{ key: '4h', seconds: 4 * 60 * 60, severity: 'critical' as const },
+		{ key: '30m', seconds: 30 * 60, severity: 'critical' as const },
+	]
+	const checkpoint = checkpoints.find((item) => ageSeconds >= item.seconds)
+	if (!checkpoint) return null
+	const dedupKey = `escalation:${incident.id}:${checkpoint.key}`
+	if (alreadySent.has(dedupKey)) return null
+	return {
+		kind: 'escalation',
+		surface: incident.surface,
+		severity: checkpoint.severity,
+		title: `${incident.surface} incident still open`,
+		body: `Incident ${incident.id} has been open for ${checkpoint.key}.`,
+		dedupKey,
+		payload: { incidentId: incident.id, checkpoint: checkpoint.key },
+	}
+}

package/src/alerting/index.ts

@@ -0,0 +1,95 @@
+import { type NotifyEnv, type NotifyResult, notify } from '@growth-labs/notify'
+import type { CategorizedEvent } from '../tail/categorize.js'
+import type {
+	AlertSeverity,
+	NotifyConfig,
+	PersistedCheckResult,
+	ThresholdConfig,
+} from '../types.js'
+import { closeIncident, openIncident } from './dedup.js'
+import { evaluateError, evaluateProbe } from './thresholds.js'
+
+export type AlertKind =
+	| 'open-incident'
+	| 'close-incident'
+	| 'rate-spike'
+	| 'new-error'
+	| 'escalation'
+
+export interface AlertAction {
+	kind: AlertKind
+	surface: string
+	severity: AlertSeverity
+	title: string
+	body: string
+	dedupKey: string
+	payload?: Record<string, unknown>
+}
+
+export interface AlertEngine {
+	activeIncidentSurfaces: Set<string>
+	handleProbeResult(
+		result: PersistedCheckResult,
+		surfaceName: string,
+		db: D1Database,
+		env: Record<string, unknown>,
+	): Promise<AlertAction | null>
+	handleErrorEvent(
+		event: CategorizedEvent & { fingerprint: string },
+		db: D1Database,
+		env: Record<string, unknown>,
+	): Promise<AlertAction | null>
+	send(env: Record<string, unknown>, action: AlertAction): Promise<NotifyResult>
+}
+
+export interface AlerterConfig {
+	notifyConfig: NotifyConfig
+	alertingConfig?: ThresholdConfig
+	notifyFn?: (env: Record<string, unknown>, action: AlertAction) => Promise<NotifyResult>
+}
+
+export function createAlerter(config: AlerterConfig): AlertEngine {
+	const activeIncidentSurfaces = new Set<string>()
+	const thresholds = config.alertingConfig ?? {}
+
+	async function send(env: Record<string, unknown>, action: AlertAction): Promise<NotifyResult> {
+		if (config.notifyFn) return config.notifyFn(env, action)
+		return notify(env as NotifyEnv, {
+			...config.notifyConfig,
+			severity: action.severity,
+			title: action.title,
+			body: action.body,
+			dedupKey: action.dedupKey,
+		})
+	}
+
+	return {
+		activeIncidentSurfaces,
+		async handleProbeResult(result, surfaceName, db, env) {
+			const action = await evaluateProbe(result, surfaceName, db, thresholds)
+			if (!action) return null
+			if (action.kind === 'open-incident') {
+				await openIncident(action, db)
+				activeIncidentSurfaces.add(action.surface)
+			}
+			if (action.kind === 'close-incident' && typeof action.payload?.incidentId === 'string') {
+				await closeIncident(action.payload.incidentId, result.id, db)
+				activeIncidentSurfaces.delete(action.surface)
+			}
+			await send(env, action)
+			return action
+		},
+		async handleErrorEvent(event, db, env) {
+			const action = await evaluateError(event, db, thresholds)
+			if (!action) return null
+			if (action.kind === 'rate-spike') activeIncidentSurfaces.add(action.surface)
+			await send(env, action)
+			return action
+		},
+		send,
+	}
+}
+
+export { closeIncident, isIncidentOpen, openIncident } from './dedup.js'
+export { evaluateEscalation } from './escalation.js'
+export { evaluateError, evaluateProbe } from './thresholds.js'

package/src/alerting/thresholds.ts

@@ -0,0 +1,148 @@
+import type { CategorizedEvent } from '../tail/categorize.js'
+import type { CheckResult, ThresholdConfig, UptimeIncident } from '../types.js'
+import { isIncidentOpen } from './dedup.js'
+import type { AlertAction } from './index.js'
+
+interface CheckRow {
+	id: string
+	status: string
+	checked_at: number
+}
+
+interface CountRow {
+	count: number
+}
+
+const DEFAULT_FAILURES_TO_OPEN = 2
+const DEFAULT_SUCCESSES_TO_CLOSE = 1
+const DEFAULT_DEDUP_WINDOW_MS = 60 * 60 * 1000
+const DEFAULT_RATE_SPIKE_THRESHOLD = 10
+const DEFAULT_RATE_SPIKE_WINDOW_MS = 5 * 60 * 1000
+
+export async function evaluateProbe(
+	result: CheckResult,
+	surfaceName: string,
+	db: D1Database,
+	config: ThresholdConfig = {},
+): Promise<AlertAction | null> {
+	const open = await isIncidentOpen(surfaceName, db)
+	if (result.status === 'pass') {
+		if (!open) return null
+		const successesToClose = config.consecutiveSuccessesToClose ?? DEFAULT_SUCCESSES_TO_CLOSE
+		const recent = await recentChecks(db, surfaceName, successesToClose)
+		if (recent.length >= successesToClose && recent.every((row) => row.status === 'pass')) {
+			return closeIncidentAction(open, result)
+		}
+		return null
+	}
+
+	if (open) return null
+	const failuresToOpen = config.consecutiveFailuresToOpen ?? DEFAULT_FAILURES_TO_OPEN
+	const recent = await recentChecks(db, surfaceName, failuresToOpen)
+	if (recent.length < failuresToOpen) return null
+	if (!recent.every((row) => row.status !== 'pass')) return null
+
+	const severity = config.minSeverity ?? 'warning'
+	return {
+		kind: 'open-incident',
+		surface: surfaceName,
+		severity,
+		title: `${surfaceName} synthetic check failing`,
+		body: `${failuresToOpen} consecutive synthetic checks failed. Latest status: ${result.status}${
+			result.errorMessage ? ` (${result.errorMessage})` : ''
+		}.`,
+		dedupKey: `incident:${surfaceName}`,
+		payload: { triggerCheckId: result.id },
+	}
+}
+
+export async function evaluateError(
+	event: CategorizedEvent & { fingerprint: string },
+	db: D1Database,
+	config: ThresholdConfig = {},
+): Promise<AlertAction | null> {
+	const occurredAtSeconds = Math.floor(event.occurredAt / 1000)
+	const rateWindowMs = config.rateSpikeWindowMs ?? DEFAULT_RATE_SPIKE_WINDOW_MS
+	const rateSpikeThreshold = config.rateSpikeThreshold ?? DEFAULT_RATE_SPIKE_THRESHOLD
+	const rateCount = await countFingerprintSince(
+		db,
+		event.fingerprint,
+		occurredAtSeconds - Math.floor(rateWindowMs / 1000),
+	)
+	if (rateCount >= rateSpikeThreshold) {
+		return {
+			kind: 'rate-spike',
+			surface: event.surface,
+			severity: 'critical',
+			title: `${event.surface} error rate spike`,
+			body: `${rateCount} events with fingerprint ${event.fingerprint} occurred in the last ${Math.round(
+				rateWindowMs / 60_000,
+			)} minutes.`,
+			dedupKey: `rate-spike:${event.surface}:${event.fingerprint}`,
+			payload: { fingerprint: event.fingerprint, count: rateCount },
+		}
+	}
+
+	const dedupWindowMs = config.newErrorDedupWindowMs ?? DEFAULT_DEDUP_WINDOW_MS
+	const dedupCount = await countFingerprintSince(
+		db,
+		event.fingerprint,
+		occurredAtSeconds - Math.floor(dedupWindowMs / 1000),
+	)
+	if (dedupCount > 0) return null
+
+	return {
+		kind: 'new-error',
+		surface: event.surface,
+		severity:
+			event.category === 'console-warn' || event.category === 'slow-request'
+				? 'warning'
+				: 'critical',
+		title: `${event.surface} new error fingerprint`,
+		body: `${event.category} fingerprint ${event.fingerprint}: ${event.message}`,
+		dedupKey: `new-error:${event.fingerprint}`,
+		payload: { fingerprint: event.fingerprint, category: event.category },
+	}
+}
+
+async function recentChecks(db: D1Database, surface: string, limit: number): Promise<CheckRow[]> {
+	const { results } = await db
+		.prepare(`
+			SELECT id, status, checked_at
+			FROM gl_uptime_checks
+			WHERE surface = ?
+			ORDER BY checked_at DESC
+			LIMIT ?
+		`)
+		.bind(surface, limit)
+		.all<CheckRow>()
+	return results ?? []
+}
+
+async function countFingerprintSince(
+	db: D1Database,
+	fingerprint: string,
+	since: number,
+): Promise<number> {
+	const row = await db
+		.prepare(`
+			SELECT COUNT(*) AS count
+			FROM gl_errors
+			WHERE fingerprint = ? AND occurred_at >= ?
+		`)
+		.bind(fingerprint, since)
+		.first<CountRow>()
+	return Number(row?.count ?? 0)
+}
+
+function closeIncidentAction(open: UptimeIncident, result: CheckResult): AlertAction {
+	return {
+		kind: 'close-incident',
+		surface: open.surface,
+		severity: 'info',
+		title: `${open.surface} recovered`,
+		body: `Synthetic check ${result.id ?? 'unknown'} passed and closed incident ${open.id}.`,
+		dedupKey: `incident-closed:${open.id}`,
+		payload: { incidentId: open.id, resolveCheckId: result.id },
+	}
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export type { AlertAction, AlertEngine, AlertKind } from './alerting/index.js'
+export { createAlerter } from './alerting/index.js'
+export type { ProberConfig } from './prober/index.js'
+export { createProber } from './prober/index.js'
+export type { StatusPageAppConfig } from './status-page/app.js'
+export { createStatusPageApp } from './status-page/app.js'
+export type { TailWorkerConfig } from './tail/index.js'
+export { createTailWorker } from './tail/index.js'
+export type {
+	AlertSeverity,
+	CheckResult,
+	CheckStatus,
+	CheckType,
+	ErrorRollup,
+	ErrorSeverity,
+	NotifyConfig,
+	PersistedCheckResult,
+	SamplingConfig,
+	StatusPageConfig,
+	SurfaceStatus,
+	ThresholdConfig,
+	UptimeIncident,
+} from './types.js'

package/src/prober/README.md

@@ -0,0 +1,18 @@
+# Monitoring Prober
+
+`createProber(config)` returns a `scheduledHandler` for Cloudflare Cron Workers.
+The handler matches `event.cron` against configured surfaces and runs all matching
+checks with `ctx.waitUntil`.
+
+Supported checks:
+
+- `kind: 'get'`: `GET`, `redirect: 'manual'`, status assertion, optional content marker.
+- `kind: 'post'`: form-url-encoded `POST`, `redirect: 'manual'`, status assertion, optional `Location` regex.
+- `kind: 'happy_path'`: code-signin flow with Gmail polling and account-page assertion.
+
+All D1 writes are best-effort. A failed persistence call logs to `console.error`
+but does not throw to the scheduled runtime.
+
+Invariant: `auth-monitor` must set `notifyConfig.emailProvider` to `'resend'`
+when email alerts are enabled. The monitor checks Cloudflare-hosted auth
+surfaces, so email alert delivery cannot rely on Cloudflare Email.

package/src/prober/index.ts

@@ -0,0 +1,83 @@
+import { createAlerter } from '../alerting/index.js'
+import type {
+	ExecutionContextLike,
+	NotifyConfig,
+	ProbeAlertingConfig,
+	ScheduledEventLike,
+} from '../types.js'
+import { errorMessage } from '../types.js'
+import { persistCheckResult } from './persist.js'
+import { runGet } from './runners/get-runner.js'
+import { type HappyPathRuntime, runHappyPath } from './runners/happy-path-runner.js'
+import { runPost } from './runners/post-runner.js'
+import type { SurfaceConfig } from './surfaces.js'
+
+export interface ProberConfig {
+	realmId: string
+	d1Binding: string
+	notifyConfig: NotifyConfig
+	alertingConfig?: ProbeAlertingConfig
+	surfaces: SurfaceConfig[]
+}
+
+export function createProber(config: ProberConfig) {
+	const alerter = createAlerter({
+		notifyConfig: config.notifyConfig,
+		alertingConfig: config.alertingConfig,
+	})
+
+	async function checkSurface(surface: SurfaceConfig, env: Record<string, unknown>): Promise<void> {
+		const db = env[config.d1Binding] as D1Database | undefined
+		try {
+			const result = await runSurface(surface, env)
+			if (!db) {
+				console.error(`[monitoring] missing D1 binding env.${config.d1Binding}`)
+				return
+			}
+			const persisted = await persistCheckResult(db, surface, result)
+			await alerter.handleProbeResult(persisted, surface.name, db, env)
+		} catch (error) {
+			console.error(
+				`[monitoring] synthetic check failed for ${surface.name}: ${errorMessage(error)}`,
+			)
+		}
+	}
+
+	async function scheduledHandler(
+		event: ScheduledEventLike,
+		env: Record<string, unknown>,
+		ctx: ExecutionContextLike,
+	): Promise<void> {
+		for (const surface of config.surfaces.filter(
+			(candidate) => candidate.schedule === event.cron,
+		)) {
+			ctx.waitUntil(checkSurface(surface, env))
+		}
+	}
+
+	return { scheduledHandler, checkSurface }
+}
+
+async function runSurface(surface: SurfaceConfig, env: Record<string, unknown>) {
+	switch (surface.kind) {
+		case 'get':
+			return runGet(surface)
+		case 'post':
+			return runPost(surface)
+		case 'happy_path':
+			return runHappyPath(surface, { env } satisfies HappyPathRuntime)
+	}
+}
+
+export { persistCheckResult } from './persist.js'
+export { runGet } from './runners/get-runner.js'
+export { extractCodeFromMessage, runHappyPath } from './runners/happy-path-runner.js'
+export { runPost } from './runners/post-runner.js'
+export type {
+	CodeSigninHappyPathConfig,
+	GetSurface,
+	GmailPollingConfig,
+	HappyPathSurface,
+	PostSurface,
+	SurfaceConfig,
+} from './surfaces.js'

package/src/prober/persist.ts

@@ -0,0 +1,46 @@
+import {
+	type CheckResult,
+	errorMessage,
+	generateId,
+	type IdFactory,
+	type PersistedCheckResult,
+} from '../types.js'
+import type { SurfaceConfig } from './surfaces.js'
+
+export async function persistCheckResult(
+	db: D1Database,
+	surface: SurfaceConfig,
+	result: CheckResult,
+	idFactory: IdFactory = generateId,
+	now = Date.now,
+): Promise<PersistedCheckResult> {
+	const id = result.id ?? idFactory()
+	const checkedAt = result.checkedAt ?? Math.floor(now() / 1000)
+	const persisted: PersistedCheckResult = { ...result, id, checkedAt }
+
+	try {
+		await db
+			.prepare(`
+				INSERT INTO gl_uptime_checks
+					(id, surface, check_type, status, status_code, latency_ms, error_message, checked_at)
+				VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+			`)
+			.bind(
+				id,
+				surface.name,
+				surface.kind,
+				result.status,
+				result.statusCode ?? null,
+				result.latencyMs,
+				result.errorMessage ?? null,
+				checkedAt,
+			)
+			.run()
+	} catch (error) {
+		console.error(
+			`[monitoring] failed to persist uptime check ${surface.name}: ${errorMessage(error)}`,
+		)
+	}
+
+	return persisted
+}

package/src/prober/runners/get-runner.ts

@@ -0,0 +1,49 @@
+import { type CheckResult, errorMessage, isTimeoutMessage, type RuntimeFetch } from '../../types.js'
+import type { GetSurface } from '../surfaces.js'
+
+export async function runGet(
+	surface: GetSurface,
+	runtime: RuntimeFetch = {},
+): Promise<CheckResult> {
+	const start = Date.now()
+	const fetcher = runtime.fetcher ?? fetch
+	try {
+		const response = await fetcher(surface.url, {
+			method: 'GET',
+			redirect: 'manual',
+			signal: AbortSignal.timeout(surface.timeoutMs),
+		})
+		const latencyMs = Date.now() - start
+
+		if (response.status !== surface.assertions.statusCode) {
+			return {
+				status: 'fail',
+				statusCode: response.status,
+				latencyMs,
+				errorMessage: `expected ${surface.assertions.statusCode}, got ${response.status}`,
+			}
+		}
+
+		if (surface.assertions.contentMarker) {
+			const body = await response.text()
+			if (!body.includes(surface.assertions.contentMarker)) {
+				return {
+					status: 'fail',
+					statusCode: response.status,
+					latencyMs,
+					errorMessage: `content marker "${surface.assertions.contentMarker}" not found in body`,
+				}
+			}
+		}
+
+		return { status: 'pass', statusCode: response.status, latencyMs }
+	} catch (error) {
+		const latencyMs = Date.now() - start
+		const message = errorMessage(error)
+		return {
+			status: isTimeoutMessage(message) ? 'timeout' : 'fail',
+			latencyMs,
+			errorMessage: message,
+		}
+	}
+}