@growth-labs/ops-digest 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @growth-labs/ops-digest Changelog
 
+## 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
 
 - Initial release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/ops-digest",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Worker-runtime digest engine for D1/WAE operational metrics, anomaly callouts, notify delivery, and KV idempotency.",
   "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",
     "CHANGELOG.md"

package/src/anomaly.ts

@@ -0,0 +1,58 @@
+import type { AnomalyConfig, AnomalyHit } from './types.js'
+
+export function detectAnomaly(
+	current: number,
+	history: number[],
+	config: AnomalyConfig,
+	metricName = '',
+): AnomalyHit | null {
+	const override = metricName ? config.overrides?.[metricName] : undefined
+	const effective = { ...config, ...override }
+
+	if (effective.method === 'none') return null
+	if (history.length < 14) return null
+
+	const sorted = [...history].sort((a, b) => a - b)
+	const medianValue = median(sorted)
+	if (medianValue < effective.medianFloor) return null
+
+	const q1 = median(sorted.slice(0, Math.floor(sorted.length / 2)))
+	const q3 = median(sorted.slice(Math.ceil(sorted.length / 2)))
+	const iqr = q3 - q1
+	const multiplier = effective.iqrMultiplier ?? 1.5
+	const lowerBand = medianValue - multiplier * iqr
+	const upperBand = medianValue + multiplier * iqr
+
+	if (current < lowerBand) {
+		return {
+			metric: metricName,
+			current,
+			median: medianValue,
+			iqr,
+			lowerBand,
+			upperBand,
+			direction: 'below',
+		}
+	}
+
+	if (current > upperBand) {
+		return {
+			metric: metricName,
+			current,
+			median: medianValue,
+			iqr,
+			lowerBand,
+			upperBand,
+			direction: 'above',
+		}
+	}
+
+	return null
+}
+
+function median(sorted: number[]): number {
+	if (sorted.length === 0) return 0
+	const middle = Math.floor(sorted.length / 2)
+	if (sorted.length % 2 === 1) return sorted[middle]
+	return (sorted[middle - 1] + sorted[middle]) / 2
+}

package/src/engine.ts

@@ -0,0 +1,204 @@
+import { notify } from '@growth-labs/notify'
+import { detectAnomaly } from './anomaly.js'
+import { metricValueToNumber } from './handlers/common.js'
+import { computeMetric } from './handlers/index.js'
+import {
+	checkIdempotency,
+	formatIdempotencyKey,
+	hashRenderedDigest,
+	writeIdempotencyMarker,
+} from './idempotency.js'
+import { renderDigest } from './render.js'
+import type {
+	DigestDefinition,
+	DigestRunResult,
+	HandlerContext,
+	MetricDefinition,
+	MetricResult,
+	MetricValue,
+	OpsDigestConfig,
+	OpsDigestEnv,
+	PercentChange,
+	ResolvedDigestWindow,
+	WaeSourceConfig,
+} from './types.js'
+import { resolveDigestWindow, shiftWindowDays, splitTrailingDays } from './window.js'
+
+export async function runDigest(
+	definition: DigestDefinition,
+	config: OpsDigestConfig,
+	env: OpsDigestEnv,
+	_ctx: ExecutionContext,
+): Promise<DigestRunResult> {
+	const window = resolveDigestWindow(definition.window)
+	const idempotencyKey = formatIdempotencyKey(definition.name, window.startMs)
+	const errors: string[] = []
+	const context: HandlerContext = {
+		d1: resolveBinding<D1Database>(env, config.d1Binding),
+		sources: buildSources(config),
+		env,
+	}
+
+	const metrics: MetricResult[] = []
+	for (const metric of definition.metrics) {
+		const result = await computeMetricResult(metric, definition, window, context, errors)
+		if (result) metrics.push(result)
+	}
+
+	const rendered = renderDigest(definition.render, metrics, definition.brandLabel, window)
+	const renderedHash = await hashRenderedDigest(rendered)
+	const kv = resolveBinding<KVNamespace>(env, config.idempotencyKv)
+	const state = await checkIdempotency(kv, definition.name, window.startMs, renderedHash)
+
+	if (state === 'duplicate') {
+		return buildResult(definition.name, window, rendered, idempotencyKey, false, metrics, errors)
+	}
+
+	if (state === 'changed') {
+		console.warn('ops-digest: idempotency marker changed; skipping rerun', {
+			key: idempotencyKey,
+		})
+		return buildResult(definition.name, window, rendered, idempotencyKey, false, metrics, errors)
+	}
+
+	const severity = metrics.some((metric) => metric.anomaly) ? 'warning' : 'info'
+	const notifyResult = await notify(env, {
+		...config.notifyConfig,
+		channels: definition.channels,
+		severity,
+		title: `${definition.brandLabel} Ops Digest`,
+		body: rendered,
+		dedupKey: idempotencyKey,
+	})
+	const posted = notifyResult.sent.length > 0
+	if (posted) {
+		await writeIdempotencyMarker(kv, definition.name, window.startMs, renderedHash)
+	} else {
+		errors.push(`notify: no channels sent (${notifyResult.failed.map((f) => f.error).join('; ')})`)
+	}
+
+	return buildResult(definition.name, window, rendered, idempotencyKey, posted, metrics, errors)
+}
+
+async function computeMetricResult(
+	metric: MetricDefinition,
+	definition: DigestDefinition,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+	errors: string[],
+): Promise<MetricResult | null> {
+	try {
+		const current = await computeMetric(metric, window, context)
+		const currentNumber = metricValueToNumber(current)
+		const baseline = await computeBaseline(metric, window, context, errors)
+		const history = await computeHistory(metric, window, context, errors)
+		const delta = formatPercentChange(currentNumber, baseline)
+		const anomaly =
+			detectAnomaly(currentNumber, history, definition.anomaly, metric.name) ?? undefined
+		if (anomaly) anomaly.metric = metric.name
+
+		return {
+			name: metric.name,
+			current,
+			baseline,
+			delta,
+			anomaly,
+		}
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err)
+		errors.push(`${metric.name}: ${message}`)
+		console.error('ops-digest: metric failed', { metric: metric.name, err })
+		return null
+	}
+}
+
+async function computeBaseline(
+	metric: MetricDefinition,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+	errors: string[],
+): Promise<number> {
+	const values: number[] = []
+	for (let offset = 1; offset <= 7; offset += 1) {
+		try {
+			values.push(
+				metricValueToNumber(await computeMetric(metric, shiftWindowDays(window, offset), context)),
+			)
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err)
+			errors.push(`${metric.name} baseline-${offset}: ${message}`)
+		}
+	}
+	if (values.length === 0) return 0
+	return values.reduce((sum, value) => sum + value, 0) / values.length
+}
+
+async function computeHistory(
+	metric: MetricDefinition,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+	errors: string[],
+): Promise<number[]> {
+	const values: number[] = []
+	for (const [index, historyWindow] of splitTrailingDays(window, 30).entries()) {
+		try {
+			values.push(metricValueToNumber(await computeMetric(metric, historyWindow, context)))
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err)
+			errors.push(`${metric.name} history-${index + 1}: ${message}`)
+		}
+	}
+	return values
+}
+
+function buildResult(
+	digestName: string,
+	window: ResolvedDigestWindow,
+	rendered: string,
+	idempotencyKey: string,
+	posted: boolean,
+	metrics: MetricResult[],
+	errors: string[],
+): DigestRunResult {
+	return {
+		digestName,
+		windowStart: window.startMs,
+		windowEnd: window.endMs,
+		rendered,
+		idempotencyKey,
+		posted,
+		metrics,
+		errors,
+	}
+}
+
+function buildSources(config: OpsDigestConfig): Record<string, WaeSourceConfig> {
+	return {
+		...(config.authWae ? { authWae: config.authWae } : {}),
+		...(config.contentWae ? { contentWae: config.contentWae } : {}),
+		...(config.extraWae ?? {}),
+	}
+}
+
+function resolveBinding<T>(env: OpsDigestEnv, name: string): T {
+	const binding = env[name]
+	if (!binding) throw new Error(`ops-digest: env binding "${name}" is missing`)
+	return binding as T
+}
+
+function formatPercentChange(current: number, previous: number): PercentChange {
+	if (previous === 0) {
+		if (current === 0) return { value: '0%', direction: 'flat' }
+		return { value: '—', direction: current > 0 ? 'up' : 'down' }
+	}
+	const pct = ((current - previous) / previous) * 100
+	if (pct === 0) return { value: '0%', direction: 'flat' }
+	return {
+		value: `${Math.abs(pct).toFixed(1)}%`,
+		direction: pct > 0 ? 'up' : 'down',
+	}
+}
+
+export function metricValueForEngine(value: MetricValue): number {
+	return metricValueToNumber(value)
+}

package/src/handlers/common.ts

@@ -0,0 +1,86 @@
+import { queryWAE } from '@growth-labs/analytics/utils/wae-query'
+import { assertValidWaeDataset } from '@growth-labs/analytics/utils/wae-validate'
+import type {
+	HandlerContext,
+	MetricValue,
+	ResolvedDigestWindow,
+	WaeSourceConfig,
+} from '../types.js'
+import { waeWindowSql } from '../window.js'
+
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+export function quoteIdentifier(identifier: string): string {
+	assertSqlIdentifier(identifier)
+	return `"${identifier}"`
+}
+
+export function assertSqlIdentifier(identifier: string): void {
+	if (!IDENTIFIER_PATTERN.test(identifier)) {
+		throw new Error(`ops-digest: invalid SQL identifier "${identifier}"`)
+	}
+}
+
+export function numericResult(row: Record<string, unknown> | null | undefined): number {
+	const value = row?.c
+	if (typeof value === 'number') return value
+	if (typeof value === 'string') return Number(value)
+	return 0
+}
+
+export function metricValueToNumber(value: MetricValue): number {
+	if (typeof value === 'number') return value
+	if (Array.isArray(value)) return value.reduce((sum, item) => sum + item.count, 0)
+	return Object.values(value).reduce((sum, count) => sum + count, 0)
+}
+
+export function resolveD1(context: HandlerContext): D1Database {
+	if (!context.d1) throw new Error('ops-digest: D1 binding is missing')
+	return context.d1
+}
+
+export function d1TimeBounds(
+	window: ResolvedDigestWindow,
+	unit: 's' | 'ms' | undefined,
+): [number, number] {
+	if (unit === 'ms') return [window.startMs, window.endMs]
+	return [Math.floor(window.startMs / 1000), Math.floor(window.endMs / 1000)]
+}
+
+export function resolveWaeSource(context: HandlerContext, sourceName: string): WaeSourceConfig {
+	const source = context.sources?.[sourceName]
+	if (!source) throw new Error(`ops-digest: WAE source "${sourceName}" is not configured`)
+	return source
+}
+
+export async function queryWaeRows<T extends Record<string, unknown>>(
+	source: WaeSourceConfig,
+	context: HandlerContext,
+	sql: string,
+): Promise<T[]> {
+	assertValidWaeDataset(source.dataset, source.realmFilter ?? source.siteFilter ?? '')
+	const token = context.env?.[source.apiTokenSecret]
+	if (typeof token !== 'string' || token.trim() === '') {
+		throw new Error(`ops-digest: WAE token secret "${source.apiTokenSecret}" is missing`)
+	}
+	const fetchFn = context.env?.fetch ?? fetch
+	const result = await queryWAE(source.accountId, source.dataset, sql, token, fetchFn)
+	return result.data as T[]
+}
+
+export function waeConditions(
+	source: WaeSourceConfig,
+	window: ResolvedDigestWindow,
+	eventName?: string,
+): string[] {
+	const conditions: string[] = []
+	if (eventName) conditions.push(`blob1 = ${sqlString(eventName)}`)
+	const filter = source.realmFilter ?? source.siteFilter
+	if (filter) conditions.push(`blob2 = ${sqlString(filter)}`)
+	conditions.push(waeWindowSql(window))
+	return conditions
+}
+
+export function sqlString(value: string): string {
+	return `'${value.replaceAll("'", "''")}'`
+}

package/src/handlers/composite-ratio.ts

@@ -0,0 +1,26 @@
+import type { HandlerContext, MetricDefinition, ResolvedDigestWindow } from '../types.js'
+import { metricValueToNumber } from './common.js'
+
+type CompositeRatioMetric = Extract<MetricDefinition, { handler: 'composite.ratio' }>
+
+export async function computeCompositeRatio(
+	metric: CompositeRatioMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+	compute: (
+		metric: MetricDefinition,
+		window: ResolvedDigestWindow,
+		context: HandlerContext,
+	) => Promise<unknown>,
+): Promise<number> {
+	const numerator = metricValueToNumber(
+		(await compute(metric.numerator, window, context)) as Parameters<typeof metricValueToNumber>[0],
+	)
+	const denominator = metricValueToNumber(
+		(await compute(metric.denominator, window, context)) as Parameters<
+			typeof metricValueToNumber
+		>[0],
+	)
+	if (denominator === 0) return 0
+	return numerator / denominator
+}

package/src/handlers/d1-row-count-by-event.ts

@@ -0,0 +1,29 @@
+import type { HandlerContext, MetricDefinition, ResolvedDigestWindow } from '../types.js'
+import { d1TimeBounds, numericResult, quoteIdentifier, resolveD1 } from './common.js'
+
+type D1RowCountByEventMetric = Extract<MetricDefinition, { handler: 'd1.row-count-by-event' }>
+
+export async function computeD1RowCountByEvent(
+	metric: D1RowCountByEventMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<number> {
+	if (metric.eventNames.length === 0) return 0
+	const d1 = resolveD1(context)
+	const eventColumn = metric.eventColumn ?? 'event_name'
+	const timeColumn = metric.timeColumn ?? 'processed_at'
+	const placeholders = metric.eventNames.map(() => '?').join(', ')
+	const [start, end] = d1TimeBounds(window, metric.timeColumnUnit)
+	const row = await d1
+		.prepare(
+			[
+				`SELECT COUNT(*) AS c FROM ${quoteIdentifier(metric.table)}`,
+				`WHERE ${quoteIdentifier(eventColumn)} IN (${placeholders})`,
+				`AND ${quoteIdentifier(timeColumn)} >= ?`,
+				`AND ${quoteIdentifier(timeColumn)} < ?`,
+			].join(' '),
+		)
+		.bind(...metric.eventNames, start, end)
+		.first<Record<string, unknown>>()
+	return numericResult(row)
+}

package/src/handlers/d1-row-count.ts

@@ -0,0 +1,21 @@
+import type { HandlerContext, MetricDefinition, ResolvedDigestWindow } from '../types.js'
+import { d1TimeBounds, numericResult, quoteIdentifier, resolveD1 } from './common.js'
+
+type D1RowCountMetric = Extract<MetricDefinition, { handler: 'd1.row-count' }>
+
+export async function computeD1RowCount(
+	metric: D1RowCountMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<number> {
+	const d1 = resolveD1(context)
+	const timeColumn = metric.timeColumn ?? 'created_at'
+	const [start, end] = d1TimeBounds(window, metric.timeColumnUnit)
+	const row = await d1
+		.prepare(
+			`SELECT COUNT(*) AS c FROM ${quoteIdentifier(metric.table)} WHERE ${quoteIdentifier(timeColumn)} >= ? AND ${quoteIdentifier(timeColumn)} < ?`,
+		)
+		.bind(start, end)
+		.first<Record<string, unknown>>()
+	return numericResult(row)
+}

package/src/handlers/index.ts

@@ -0,0 +1,72 @@
+import type {
+	HandlerContext,
+	MetricDefinition,
+	MetricValue,
+	ResolvedDigestWindow,
+} from '../types.js'
+import { computeCompositeRatio } from './composite-ratio.js'
+import { computeD1RowCount } from './d1-row-count.js'
+import { computeD1RowCountByEvent } from './d1-row-count-by-event.js'
+import { computeWaeAvgDouble } from './wae-avg-double.js'
+import { computeWaeEventCount } from './wae-event-count.js'
+import { computeWaeEventCountByBlob } from './wae-event-count-by-blob.js'
+import { computeWaeTopNByBlob } from './wae-top-n-by-blob.js'
+import { computeWaeUniqueCount } from './wae-unique-count.js'
+
+export const handlerRegistry = {
+	'd1.row-count': {
+		description: 'Counts D1 rows in the digest window using a created/processed timestamp column.',
+	},
+	'd1.row-count-by-event': {
+		description: 'Counts D1 rows whose event column matches one of the configured event names.',
+	},
+	'wae.event-count': {
+		description: 'Counts WAE rows for one event name and optional realm/site filter.',
+	},
+	'wae.event-count-by-blob': {
+		description: 'Counts one WAE event grouped by a blob field.',
+	},
+	'wae.unique-count': {
+		description: 'Counts distinct values in a WAE blob field.',
+	},
+	'wae.avg-double': {
+		description: 'Averages a WAE double field.',
+	},
+	'wae.top-n-by-blob': {
+		description: 'Returns the top N WAE blob values by event count.',
+	},
+	'composite.ratio': {
+		description: 'Computes numerator / denominator using nested metric definitions.',
+	},
+} as const
+
+export async function computeMetric(
+	metric: MetricDefinition,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<MetricValue> {
+	switch (metric.handler) {
+		case 'd1.row-count':
+			return computeD1RowCount(metric, window, context)
+		case 'd1.row-count-by-event':
+			return computeD1RowCountByEvent(metric, window, context)
+		case 'wae.event-count':
+			return computeWaeEventCount(metric, window, context)
+		case 'wae.event-count-by-blob':
+			return computeWaeEventCountByBlob(metric, window, context)
+		case 'wae.unique-count':
+			return computeWaeUniqueCount(metric, window, context)
+		case 'wae.avg-double':
+			return computeWaeAvgDouble(metric, window, context)
+		case 'wae.top-n-by-blob':
+			return computeWaeTopNByBlob(metric, window, context)
+		case 'composite.ratio':
+			return computeCompositeRatio(metric, window, context, computeMetric)
+		default:
+			return assertNever(metric)
+	}
+}
+
+function assertNever(value: never): never {
+	throw new Error(`ops-digest: unsupported metric handler "${String(value)}"`)
+}

package/src/handlers/wae-avg-double.ts

@@ -0,0 +1,29 @@
+import type { HandlerContext, MetricDefinition, ResolvedDigestWindow } from '../types.js'
+import {
+	assertSqlIdentifier,
+	numericResult,
+	queryWaeRows,
+	resolveWaeSource,
+	waeConditions,
+} from './common.js'
+
+type WaeAvgDoubleMetric = Extract<MetricDefinition, { handler: 'wae.avg-double' }>
+
+export async function computeWaeAvgDouble(
+	metric: WaeAvgDoubleMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<number> {
+	assertSqlIdentifier(metric.doubleField)
+	const source = resolveWaeSource(context, metric.source)
+	const rows = await queryWaeRows(
+		source,
+		context,
+		[
+			`SELECT avg(${metric.doubleField}) AS c`,
+			`FROM ${source.dataset}`,
+			`WHERE ${waeConditions(source, window, metric.eventName).join(' AND ')}`,
+		].join(' '),
+	)
+	return numericResult(rows[0])
+}

package/src/handlers/wae-event-count-by-blob.ts

@@ -0,0 +1,38 @@
+import type {
+	GroupedMetricResult,
+	HandlerContext,
+	MetricDefinition,
+	ResolvedDigestWindow,
+} from '../types.js'
+import {
+	assertSqlIdentifier,
+	numericResult,
+	queryWaeRows,
+	resolveWaeSource,
+	waeConditions,
+} from './common.js'
+
+type WaeEventCountByBlobMetric = Extract<MetricDefinition, { handler: 'wae.event-count-by-blob' }>
+
+export async function computeWaeEventCountByBlob(
+	metric: WaeEventCountByBlobMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<GroupedMetricResult> {
+	assertSqlIdentifier(metric.groupBy)
+	const source = resolveWaeSource(context, metric.source)
+	const rows = await queryWaeRows<{ group: unknown; c: unknown }>(
+		source,
+		context,
+		[
+			`SELECT ${metric.groupBy} AS group, count() AS c`,
+			`FROM ${source.dataset}`,
+			`WHERE ${waeConditions(source, window, metric.eventName).join(' AND ')}`,
+			`GROUP BY ${metric.groupBy}`,
+			'ORDER BY c DESC',
+		].join(' '),
+	)
+	return Object.fromEntries(
+		rows.map((row) => [String(row.group ?? ''), numericResult(row as Record<string, unknown>)]),
+	)
+}

package/src/handlers/wae-event-count.ts

@@ -0,0 +1,22 @@
+import type { HandlerContext, MetricDefinition, ResolvedDigestWindow } from '../types.js'
+import { numericResult, queryWaeRows, resolveWaeSource, waeConditions } from './common.js'
+
+type WaeEventCountMetric = Extract<MetricDefinition, { handler: 'wae.event-count' }>
+
+export async function computeWaeEventCount(
+	metric: WaeEventCountMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<number> {
+	const source = resolveWaeSource(context, metric.source)
+	const rows = await queryWaeRows(
+		source,
+		context,
+		[
+			'SELECT count() AS c',
+			`FROM ${source.dataset}`,
+			`WHERE ${waeConditions(source, window, metric.eventName).join(' AND ')}`,
+		].join(' '),
+	)
+	return numericResult(rows[0])
+}

package/src/handlers/wae-top-n-by-blob.ts

@@ -0,0 +1,40 @@
+import type {
+	HandlerContext,
+	MetricDefinition,
+	ResolvedDigestWindow,
+	TopNResult,
+} from '../types.js'
+import {
+	assertSqlIdentifier,
+	numericResult,
+	queryWaeRows,
+	resolveWaeSource,
+	waeConditions,
+} from './common.js'
+
+type WaeTopNByBlobMetric = Extract<MetricDefinition, { handler: 'wae.top-n-by-blob' }>
+
+export async function computeWaeTopNByBlob(
+	metric: WaeTopNByBlobMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<TopNResult> {
+	assertSqlIdentifier(metric.groupBy)
+	const source = resolveWaeSource(context, metric.source)
+	const rows = await queryWaeRows<{ group: unknown; c: unknown }>(
+		source,
+		context,
+		[
+			`SELECT ${metric.groupBy} AS group, count() AS c`,
+			`FROM ${source.dataset}`,
+			`WHERE ${waeConditions(source, window, metric.eventName).join(' AND ')}`,
+			`GROUP BY ${metric.groupBy}`,
+			'ORDER BY c DESC',
+			`LIMIT ${metric.limit}`,
+		].join(' '),
+	)
+	return rows.map((row) => ({
+		group: String(row.group ?? ''),
+		count: numericResult(row as Record<string, unknown>),
+	}))
+}

package/src/handlers/wae-unique-count.ts

@@ -0,0 +1,29 @@
+import type { HandlerContext, MetricDefinition, ResolvedDigestWindow } from '../types.js'
+import {
+	assertSqlIdentifier,
+	numericResult,
+	queryWaeRows,
+	resolveWaeSource,
+	waeConditions,
+} from './common.js'
+
+type WaeUniqueCountMetric = Extract<MetricDefinition, { handler: 'wae.unique-count' }>
+
+export async function computeWaeUniqueCount(
+	metric: WaeUniqueCountMetric,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+): Promise<number> {
+	assertSqlIdentifier(metric.uniqueBlob)
+	const source = resolveWaeSource(context, metric.source)
+	const rows = await queryWaeRows(
+		source,
+		context,
+		[
+			`SELECT count(distinct ${metric.uniqueBlob}) AS c`,
+			`FROM ${source.dataset}`,
+			`WHERE ${waeConditions(source, window, metric.eventName).join(' AND ')}`,
+		].join(' '),
+	)
+	return numericResult(rows[0])
+}

package/src/idempotency.ts

@@ -0,0 +1,40 @@
+const TTL_SECONDS = 7 * 24 * 60 * 60
+
+export type IdempotencyState = 'first-run' | 'duplicate' | 'changed'
+
+export async function checkIdempotency(
+	kv: KVNamespace,
+	digestName: string,
+	windowStart: number,
+	computedHash: string,
+): Promise<IdempotencyState> {
+	const key = formatIdempotencyKey(digestName, windowStart)
+	const existing = await kv.get(key)
+	if (existing === null) return 'first-run'
+	return existing === computedHash ? 'duplicate' : 'changed'
+}
+
+export async function writeIdempotencyMarker(
+	kv: KVNamespace,
+	digestName: string,
+	windowStart: number,
+	hash: string,
+): Promise<void> {
+	await kv.put(formatIdempotencyKey(digestName, windowStart), hash, {
+		expirationTtl: TTL_SECONDS,
+	})
+}
+
+export function formatIdempotencyKey(digestName: string, windowStart: number): string {
+	return `digest:${digestName}:${formatYYYYMMDD(windowStart)}`
+}
+
+export async function hashRenderedDigest(rendered: string): Promise<string> {
+	const encoded = new TextEncoder().encode(rendered)
+	const digest = await crypto.subtle.digest('SHA-256', encoded)
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function formatYYYYMMDD(ms: number): string {
+	return new Date(ms).toISOString().slice(0, 10)
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import { runDigest as runDigestDefinition } from './engine.js'
+import { opsDigestConfigSchema } from './schema.js'
+import type { DigestRunResult, OpsDigestConfig, OpsDigestEnv, OpsDigestHandle } from './types.js'
+
+export function opsDigest(config: OpsDigestConfig): OpsDigestHandle {
+	const parsed = opsDigestConfigSchema.parse(config) as OpsDigestConfig
+
+	return {
+		async scheduledHandler(
+			event: ScheduledEvent,
+			env: OpsDigestEnv,
+			ctx: ExecutionContext,
+		): Promise<void> {
+			const cron = event.cron
+			const matchingDigest = parsed.digests.find((digest) => digest.schedule === cron)
+			if (!matchingDigest) {
+				console.warn('ops-digest: scheduled event with no matching digest', { cron })
+				return
+			}
+
+			try {
+				await runDigestDefinition(matchingDigest, parsed, env, ctx)
+			} catch (err) {
+				console.error('ops-digest: scheduled digest failed', { digest: matchingDigest.name, err })
+			}
+		},
+
+		async runDigest(
+			digestName: string,
+			env: OpsDigestEnv,
+			ctx: ExecutionContext,
+		): Promise<DigestRunResult> {
+			const definition = parsed.digests.find((digest) => digest.name === digestName)
+			if (!definition) throw new Error(`ops-digest: digest "${digestName}" is not configured`)
+			return runDigestDefinition(definition, parsed, env, ctx)
+		},
+	}
+}
+
+export { handlerRegistry } from './handlers/index.js'
+export type {
+	AnomalyConfig,
+	AnomalyHit,
+	DigestDefinition,
+	DigestRunResult,
+	GroupedMetricResult,
+	MetricDefinition,
+	MetricResult,
+	MetricValue,
+	NotifyConfig,
+	OpsDigestConfig,
+	OpsDigestEnv,
+	OpsDigestHandle,
+	PercentChange,
+	ResolvedDigestWindow,
+	TopNResult,
+	WaeSourceConfig,
+} from './types.js'

package/src/render.ts

@@ -0,0 +1,83 @@
+import type { MetricResult, MetricValue, ResolvedDigestWindow } from './types.js'
+
+export function renderDigest(
+	template: string,
+	metrics: MetricResult[],
+	brandLabel: string,
+	window: ResolvedDigestWindow,
+): string {
+	if (template !== 'standard') {
+		throw new Error(`ops-digest: unsupported render template "${template}"`)
+	}
+
+	const lines = [`*${brandLabel} - Daily Ops Digest · ${formatDate(window.startMs)}*`, '']
+
+	for (const metric of metrics) {
+		const currentTotal = metricValueTotal(metric.current)
+		lines.push(
+			`• ${metricLabel(metric.name)}   ${formatNumber(currentTotal)}   (7d avg ${formatNumber(metric.baseline)} · ${formatDelta(metric.delta)})`,
+		)
+		for (const nested of nestedMetricLines(metric.current)) {
+			lines.push(`  - ${nested}`)
+		}
+	}
+
+	lines.push('')
+	const anomalies = metrics.filter((metric) => metric.anomaly)
+	if (anomalies.length === 0) {
+		lines.push('_No anomalies._')
+	} else {
+		for (const metric of anomalies) {
+			const anomaly = metric.anomaly
+			if (!anomaly) continue
+			lines.push(
+				`⚠️ ${metricLabel(metric.name)} ${anomaly.direction} ${formatDelta(metric.delta)} vs 7d avg (${formatNumber(anomaly.current)} vs ${formatNumber(anomaly.median)} typical) - investigate`,
+			)
+		}
+	}
+
+	return lines.join('\n')
+}
+
+export function metricValueTotal(value: MetricValue): number {
+	if (typeof value === 'number') return value
+	if (Array.isArray(value)) return value.reduce((sum, item) => sum + item.count, 0)
+	return Object.values(value).reduce((sum, item) => sum + item, 0)
+}
+
+function nestedMetricLines(value: MetricValue): string[] {
+	if (typeof value === 'number') return []
+	if (Array.isArray(value)) return value.map((item) => `${item.group}: ${formatNumber(item.count)}`)
+	return Object.entries(value).map(([group, count]) => `${group}: ${formatNumber(count)}`)
+}
+
+function metricLabel(name: string): string {
+	const base = name.endsWith('-by-provider') ? name.slice(0, -'-by-provider'.length) : name
+	const special: Record<string, string> = {
+		signins: 'Sign-ins',
+		'write-for-us': 'Write-for-us',
+	}
+	if (special[base]) return special[base]
+	const words = base.split('-')
+	return words.map((word, index) => (index === 0 ? capitalize(word) : word)).join(' ')
+}
+
+function capitalize(word: string): string {
+	if (word.length === 0) return word
+	return `${word[0].toUpperCase()}${word.slice(1)}`
+}
+
+function formatDelta(delta: MetricResult['delta']): string {
+	if (delta.direction === 'up') return `+${delta.value}`
+	if (delta.direction === 'down') return `-${delta.value}`
+	return delta.value
+}
+
+function formatNumber(value: number): string {
+	if (Number.isInteger(value)) return String(value)
+	return value.toFixed(2).replace(/\.?0+$/, '')
+}
+
+function formatDate(ms: number): string {
+	return new Date(ms).toISOString().slice(0, 10)
+}

package/src/schema.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod'
+import type { OpsDigestConfig } from './types.js'
+
+const waeSourceSchema = z
+	.object({
+		accountId: z.string().min(1),
+		dataset: z.string().min(1),
+		apiTokenSecret: z.string().min(1),
+		realmFilter: z.string().min(1).optional(),
+		siteFilter: z.string().min(1).optional(),
+	})
+	.refine((source) => !(source.realmFilter && source.siteFilter), {
+		message: 'Configure either realmFilter or siteFilter, not both',
+	})
+
+const windowSpecSchema = z.union([
+	z.literal('previous-day-utc'),
+	z.literal('previous-week-utc'),
+	z.literal('previous-month-utc'),
+	z.object({ days: z.number().int().positive(), anchorTo: z.literal('utc-midnight') }),
+])
+
+const d1RowCountSchema = z.object({
+	handler: z.literal('d1.row-count'),
+	name: z.string().min(1),
+	table: z.string().min(1),
+	timeColumn: z.string().min(1).optional(),
+	timeColumnUnit: z.enum(['s', 'ms']).optional(),
+})
+
+const d1RowCountByEventSchema = d1RowCountSchema.extend({
+	handler: z.literal('d1.row-count-by-event'),
+	eventNames: z.array(z.string().min(1)).min(1),
+	eventColumn: z.string().min(1).optional(),
+})
+
+type MetricSchema = z.ZodType<OpsDigestConfig['digests'][number]['metrics'][number]>
+
+const metricSchema: MetricSchema = z.lazy(() =>
+	z.discriminatedUnion('handler', [
+		d1RowCountSchema,
+		d1RowCountByEventSchema,
+		z.object({
+			handler: z.literal('wae.event-count'),
+			name: z.string().min(1),
+			source: z.string().min(1),
+			eventName: z.string().min(1),
+		}),
+		z.object({
+			handler: z.literal('wae.event-count-by-blob'),
+			name: z.string().min(1),
+			source: z.string().min(1),
+			eventName: z.string().min(1),
+			groupBy: z.string().min(1),
+		}),
+		z.object({
+			handler: z.literal('wae.unique-count'),
+			name: z.string().min(1),
+			source: z.string().min(1),
+			eventName: z.string().min(1).optional(),
+			uniqueBlob: z.string().min(1),
+		}),
+		z.object({
+			handler: z.literal('wae.avg-double'),
+			name: z.string().min(1),
+			source: z.string().min(1),
+			eventName: z.string().min(1).optional(),
+			doubleField: z.string().min(1),
+		}),
+		z.object({
+			handler: z.literal('wae.top-n-by-blob'),
+			name: z.string().min(1),
+			source: z.string().min(1),
+			eventName: z.string().min(1).optional(),
+			groupBy: z.string().min(1),
+			limit: z.number().int().positive(),
+		}),
+		z.object({
+			handler: z.literal('composite.ratio'),
+			name: z.string().min(1),
+			numerator: metricSchema,
+			denominator: metricSchema,
+		}),
+	]),
+)
+
+const anomalySchema = z.object({
+	method: z.enum(['iqr', 'none']),
+	medianFloor: z.number().min(0),
+	iqrMultiplier: z.number().positive().optional(),
+	overrides: z.record(z.string(), z.object({}).passthrough()).optional(),
+})
+
+const digestSchema = z.object({
+	name: z.string().min(1),
+	brandLabel: z.string().min(1),
+	schedule: z.string().min(1),
+	window: windowSpecSchema,
+	metrics: z.array(metricSchema),
+	anomaly: anomalySchema,
+	render: z.string().min(1),
+	channels: z.array(z.enum(['slack', 'email'])).min(1),
+})
+
+export const opsDigestConfigSchema = z.object({
+	realmId: z.string().min(1),
+	d1Binding: z.string().min(1),
+	authWae: waeSourceSchema.optional(),
+	contentWae: waeSourceSchema.optional(),
+	extraWae: z.record(z.string(), waeSourceSchema).optional(),
+	idempotencyKv: z.string().min(1),
+	notifyConfig: z.object({}).passthrough(),
+	digests: z.array(digestSchema).min(1),
+})

package/src/types.ts

@@ -0,0 +1,175 @@
+import type { WindowSpec } from '@growth-labs/analytics/utils/time-windows'
+import type { Channel, EmailProvider, NotifyEnv, NotifyInput, Severity } from '@growth-labs/notify'
+
+export type { Channel, Severity, WindowSpec }
+
+export type NotifyConfig = Partial<
+	Pick<NotifyInput, 'blocks' | 'dedupFn' | 'onSent' | 'emailProvider'>
+> & {
+	channels?: Channel[]
+	severity?: Severity
+	emailProvider?: EmailProvider
+}
+
+export interface OpsDigestConfig {
+	realmId: string
+	d1Binding: string
+	authWae?: WaeSourceConfig
+	contentWae?: WaeSourceConfig
+	extraWae?: Record<string, WaeSourceConfig>
+	idempotencyKv: string
+	notifyConfig: NotifyConfig
+	digests: DigestDefinition[]
+}
+
+export interface WaeSourceConfig {
+	accountId: string
+	dataset: string
+	apiTokenSecret: string
+	realmFilter?: string
+	siteFilter?: string
+}
+
+export interface DigestDefinition {
+	name: string
+	brandLabel: string
+	schedule: string
+	window: WindowSpec
+	metrics: MetricDefinition[]
+	anomaly: AnomalyConfig
+	render: 'standard' | string
+	channels: Channel[]
+}
+
+interface D1MetricBase {
+	name: string
+	table: string
+	timeColumn?: string
+	timeColumnUnit?: 's' | 'ms'
+}
+
+export type MetricDefinition =
+	| ({ handler: 'd1.row-count' } & D1MetricBase)
+	| ({
+			handler: 'd1.row-count-by-event'
+			eventNames: string[]
+			eventColumn?: string
+	  } & D1MetricBase)
+	| { handler: 'wae.event-count'; name: string; source: string; eventName: string }
+	| {
+			handler: 'wae.event-count-by-blob'
+			name: string
+			source: string
+			eventName: string
+			groupBy: string
+	  }
+	| {
+			handler: 'wae.unique-count'
+			name: string
+			source: string
+			eventName?: string
+			uniqueBlob: string
+	  }
+	| {
+			handler: 'wae.avg-double'
+			name: string
+			source: string
+			eventName?: string
+			doubleField: string
+	  }
+	| {
+			handler: 'wae.top-n-by-blob'
+			name: string
+			source: string
+			eventName?: string
+			groupBy: string
+			limit: number
+	  }
+	| {
+			handler: 'composite.ratio'
+			name: string
+			numerator: MetricDefinition
+			denominator: MetricDefinition
+	  }
+
+export interface AnomalyConfig {
+	method: 'iqr' | 'none'
+	medianFloor: number
+	iqrMultiplier?: number
+	overrides?: Record<string, Partial<AnomalyConfig>>
+}
+
+export interface AnomalyHit {
+	metric: string
+	current: number
+	median: number
+	iqr: number
+	lowerBand: number
+	upperBand: number
+	direction: 'above' | 'below'
+}
+
+export interface OpsDigestHandle {
+	scheduledHandler: (
+		event: ScheduledEvent,
+		env: OpsDigestEnv,
+		ctx: ExecutionContext,
+	) => Promise<void>
+	runDigest: (
+		digestName: string,
+		env: OpsDigestEnv,
+		ctx: ExecutionContext,
+	) => Promise<DigestRunResult>
+}
+
+export interface DigestRunResult {
+	digestName: string
+	windowStart: number
+	windowEnd: number
+	rendered: string
+	idempotencyKey: string
+	posted: boolean
+	metrics: MetricResult[]
+	errors: string[]
+}
+
+export interface PercentChange {
+	value: string
+	direction: 'up' | 'down' | 'flat'
+}
+
+export type GroupedMetricResult = Record<string, number>
+export type TopNResult = { group: string; count: number }[]
+export type MetricValue = number | GroupedMetricResult | TopNResult
+
+export interface MetricResult {
+	name: string
+	current: MetricValue
+	baseline: number
+	delta: PercentChange
+	anomaly?: AnomalyHit
+}
+
+export interface ResolvedDigestWindow {
+	startMs: number
+	endMs: number
+	sqlStart: string
+	sqlEnd: string
+}
+
+export interface HandlerContext {
+	d1?: D1Database
+	sources?: Record<string, WaeSourceConfig>
+	env?: OpsDigestEnv
+}
+
+export type MetricHandler<T extends MetricDefinition = MetricDefinition> = (
+	metric: T,
+	window: ResolvedDigestWindow,
+	context: HandlerContext,
+) => Promise<MetricValue>
+
+export interface OpsDigestEnv extends NotifyEnv {
+	fetch?: typeof fetch
+	[key: string]: unknown
+}

package/src/window.ts

@@ -0,0 +1,44 @@
+import { resolveWindow, type WindowSpec } from '@growth-labs/analytics/utils/time-windows'
+import type { ResolvedDigestWindow } from './types.js'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+export function resolveDigestWindow(
+	spec: WindowSpec,
+	now: number = Date.now(),
+): ResolvedDigestWindow {
+	return resolveWindow(spec, now)
+}
+
+export function shiftWindowDays(
+	window: ResolvedDigestWindow,
+	daysBack: number,
+): ResolvedDigestWindow {
+	const delta = daysBack * DAY_MS
+	return literalWindow(window.startMs - delta, window.endMs - delta)
+}
+
+export function splitTrailingDays(
+	window: ResolvedDigestWindow,
+	days: number,
+): ResolvedDigestWindow[] {
+	return Array.from({ length: days }, (_, index) => shiftWindowDays(window, index + 1))
+}
+
+export function waeWindowSql(window: ResolvedDigestWindow, timestampColumn = 'timestamp'): string {
+	return `${timestampColumn} >= ${window.sqlStart} AND ${timestampColumn} < ${window.sqlEnd}`
+}
+
+function literalWindow(startMs: number, endMs: number): ResolvedDigestWindow {
+	return {
+		startMs,
+		endMs,
+		sqlStart: `toDateTime('${formatSqlDateTime(startMs)}')`,
+		sqlEnd: `toDateTime('${formatSqlDateTime(endMs)}')`,
+	}
+}
+
+function formatSqlDateTime(ms: number): string {
+	const iso = new Date(ms).toISOString()
+	return iso.slice(0, 19).replace('T', ' ')
+}