@happyvertical/smrt-reports 0.55.24 → 0.56.1

package/dist/index.js

@@ -4,11 +4,12 @@ import { REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPO
 import { adapterTypeFromDb, refreshReport, reportRowIdentity, tenantColumn } from "./refresh.js";
 import { ReportScheduleRunner, SmrtPrincipalReportRefreshTask, SmrtReportRefreshTask, enqueueReportRefresh, ensureReportRefreshSchedules, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner } from "./scheduler.js";
 import { bucketExpr, buildAggregate } from "./aggregate.js";
-import { DataQueryValidationError, ObjectRegistry, SmrtCollection, SmrtObject, SmrtRecipe, createDataQueryFingerprint, field, normalizeDataQueryRequest, normalizeDataQueryResult, smrt } from "@happyvertical/smrt-core";
+import { DataQueryValidationError, ObjectRegistry, SmrtCollection, SmrtError, SmrtObject, SmrtRecipe, createDataQueryFingerprint, field, normalizeDataQueryRequest, normalizeDataQueryResult, runOnce, smrt } from "@happyvertical/smrt-core";
 import { toSnakeCase } from "@happyvertical/smrt-core/utils";
-import { TenantScoped, getTenantId, isTenancyEnabled, isTenantScopedClass, tenantId, withSystemContext } from "@happyvertical/smrt-tenancy";
+import { TenantScoped, getCurrentTenant, getTenantId, isTenancyEnabled, isTenantScopedClass, tenantId, withSystemContext, withTenant } from "@happyvertical/smrt-tenancy";
 import { tableExists, validateColumnName } from "@happyvertical/sql";
 import { createHash } from "node:crypto";
+import { getPackageConfig } from "@happyvertical/smrt-config";
 //#region src/lifecycle.ts
 function registeredReport(reportCtor) {
 	return ObjectRegistry.getClassByConstructor(reportCtor) ?? ObjectRegistry.getClass(reportCtor.name);
@@ -971,108 +972,13 @@ function reportMaterializedRowKey(row) {
 	return id;
 }
 //#endregion
-//#region src/recipes.ts
-var MaterializedReportsRecipe = class extends SmrtRecipe {
-	static id = "reports.materialized";
-	static help = "./materialized.recipe.md";
-	static label = "Reports";
-	static summary = "Keep totals and trends ready to read, refreshed on a schedule and open to the assistant.";
-	static synonyms = [
-		"reports",
-		"totals",
-		"summaries",
-		"rollups",
-		"kpis",
-		"trends",
-		"dashboards"
-	];
-	static models = [
-		SmrtReportRun,
-		SmrtReportWatermark,
-		SmrtReportLock,
-		SmrtReportSchedule,
-		SmrtReportRefreshTask,
-		SmrtPrincipalReportRefreshTask
-	];
-	static runtime = "server";
-};
-//#endregion
-//#region src/report.ts
-function registryColumnName(fieldName, field) {
-	return validateColumnName(field?.columnName ?? field?._meta?.columnName ?? toSnakeCase(fieldName));
+//#region src/materialized-host.ts
+function assertMaterializedReportRead(host, context) {
+	if (!context.userId?.trim() || !context.tenantId?.trim() || !context.permissions?.includes(host.readPermission)) throw new Error("Materialized report access denied.");
 }
-function findFieldColumn(fields, fieldName) {
-	const direct = fields.get(fieldName);
-	if (direct) return registryColumnName(fieldName, direct);
-	const requestedColumn = toSnakeCase(fieldName);
-	for (const [name, field] of fields.entries()) if (toSnakeCase(name) === requestedColumn) return registryColumnName(name, field);
-	return validateColumnName(requestedColumn);
+function findMaterializedReportHost(hosts, id) {
+	return hosts.find((host) => host.id === id);
 }
-function findTenantColumn(fields, configuredField) {
-	if (configuredField) return registryColumnName(configuredField, fields.get(configuredField));
-	for (const [fieldName, field] of fields.entries()) if (fieldName === "tenantId" || field?._meta?.__tenancy?.isTenantIdField) return registryColumnName(fieldName, field);
-	return null;
-}
-var SmrtReport = class extends SmrtObject {
-	static _isReportBase = true;
-	refreshedAt = null;
-	constructor(options = {}) {
-		super(options);
-		if (options.refreshedAt !== void 0) this.refreshedAt = options.refreshedAt instanceof Date ? options.refreshedAt : options.refreshedAt ? new Date(options.refreshedAt) : null;
-	}
-	isStale(ttlMs) {
-		if (!this.refreshedAt) return true;
-		if (ttlMs === void 0) return false;
-		return Date.now() - this.refreshedAt.getTime() > ttlMs;
-	}
-	async refresh(options = {}) {
-		const result = await refreshReport(this.constructor, {
-			...options,
-			db: this.db
-		});
-		this.refreshedAt = result.refreshedAt;
-		return result;
-	}
-};
-var SmrtReportCollection = class extends SmrtCollection {
-	async refreshIfStale() {
-		const reportCtor = this.getItemClass();
-		const refresh = (await buildReportDefinition(reportCtor)).refresh;
-		if (!refresh?.ttl || refresh.manual) return;
-		const registered = ObjectRegistry.getClassByConstructor(reportCtor) ?? ObjectRegistry.getClass(reportCtor.name);
-		const reportClass = registered?.qualifiedName ?? registered?.name ?? reportCtor.name;
-		const tableName = ObjectRegistry.getTableName(reportClass);
-		if (!tableName) return;
-		const fields = await ObjectRegistry.getAllFields(reportClass);
-		const safeTableName = validateColumnName(tableName);
-		const refreshedAtColumn = findFieldColumn(fields, "refreshedAt");
-		const tenantColumn = findTenantColumn(fields, registered?.tenantScopedConfig?.field);
-		const tenantId = getTenantId() ?? null;
-		const result = tenantColumn ? await this.db.query(`SELECT MAX(${refreshedAtColumn}) AS refreshed_at FROM ${safeTableName} WHERE ${tenantColumn} ${tenantId ? "= ?" : "IS NULL"}`, ...tenantId ? [tenantId] : []) : await this.db.query(`SELECT MAX(${refreshedAtColumn}) AS refreshed_at FROM ${safeTableName}`);
-		const refreshedAt = result.rows[0]?.refreshed_at ? new Date(result.rows[0].refreshed_at) : null;
-		if (!(!refreshedAt || Date.now() - refreshedAt.getTime() > refresh.ttl)) return;
-		await refreshReport(reportCtor, {
-			db: this.db,
-			mode: refresh.mode ?? "rebuild",
-			trigger: "ttl",
-			tenantId
-		});
-	}
-	async refresh(options = {}) {
-		return refreshReport(this.getItemClass(), {
-			...options,
-			db: this.db
-		});
-	}
-	async list(options = {}) {
-		await this.refreshIfStale();
-		return super.list(options);
-	}
-	async get(filter, options = {}) {
-		await this.refreshIfStale();
-		return super.get(filter, options);
-	}
-};
 //#endregion
 //#region src/runtime-spec.ts
 var RUNTIME_REPORT_SPEC_VERSION = 1;
@@ -1137,7 +1043,7 @@ var RUNTIME_REPORT_CHART_TYPES = [
 	"pie",
 	"stat"
 ];
-var RuntimeReportError = class extends Error {
+var RuntimeReportError = class extends SmrtError {
 	code;
 	path;
 	/**
@@ -1147,7 +1053,7 @@ var RuntimeReportError = class extends Error {
 	*/
 	status;
 	constructor(code, path, message) {
-		super(path ? `${path}: ${message}` : message);
+		super(path ? `${path}: ${message}` : message, code, "validation");
 		this.name = "RuntimeReportError";
 		this.code = code;
 		this.path = path;
@@ -1909,6 +1815,248 @@ async function runRuntimeReport(compiled, options) {
 	};
 }
 //#endregion
+//#region src/runtime-server.ts
+var RuntimeReportHttpError = class extends Error {
+	constructor(status, code, message) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.name = "RuntimeReportHttpError";
+	}
+	status;
+	code;
+};
+function isRuntimeReportAccessError(error) {
+	return error.code === "unknown_field" || error.code === "unknown_source";
+}
+function assertRuntimeReportPrincipal(context, permission) {
+	if (!context?.userId) throw new RuntimeReportHttpError(401, "unauthenticated", "Sign in required");
+	const active = getCurrentTenant();
+	if (!context.tenantId || active && active.tenantId !== context.tenantId || active?.userId && active.userId !== context.userId || !context.permissions.includes(permission)) throw new RuntimeReportHttpError(403, "forbidden", "Report access denied");
+}
+function runtimeReportPrincipalCompileContext(options, principal) {
+	return {
+		sources: options.sources.filter((source) => principal.permissions.includes(`${source.collection}.read`)),
+		permissions: principal.permissions,
+		tenantId: principal.tenantId
+	};
+}
+function createRuntimeReportConfirmHandler(options) {
+	return async (request, context) => {
+		try {
+			if (request.method !== "POST") return Response.json({ code: "method_not_allowed" }, {
+				status: 405,
+				headers: { Allow: "POST" }
+			});
+			const origin = request.headers.get("origin");
+			const site = request.headers.get("sec-fetch-site");
+			if (origin !== null && origin !== new URL(request.url).origin || site !== null && site !== "same-origin" || origin === null && site !== "same-origin") throw new RuntimeReportHttpError(403, "cross_origin", "Same-origin request required");
+			assertRuntimeReportPrincipal(context, "runtimereports.create");
+			let body;
+			try {
+				body = await request.json();
+			} catch {
+				throw new RuntimeReportHttpError(422, "invalid_spec", "Invalid JSON body");
+			}
+			if (!body || typeof body !== "object" || Array.isArray(body) || Object.keys(body).some((key) => key !== "spec" && key !== "specHash")) throw new RuntimeReportHttpError(422, "invalid_spec", "Expected spec and specHash");
+			const input = body;
+			const spec = parseRuntimeReportSpec(input.spec);
+			const hash = runtimeReportSpecHash(spec);
+			if (input.specHash !== hash) throw new RuntimeReportHttpError(422, "spec_hash_mismatch", "The approved spec hash does not match");
+			const principal = context;
+			return await withTenant({
+				tenantId: principal.tenantId,
+				userId: principal.userId,
+				permissions: new Set(principal.permissions)
+			}, async () => {
+				const serverOptions = options ?? getRuntimeReportServerOptions();
+				const transaction = principal.db.transaction?.bind(principal.db);
+				if (!transaction) throw new RuntimeReportHttpError(500, "transaction_required", "Runtime report confirmation requires transaction support");
+				const { existing, archived } = await transaction(async (tx) => {
+					const lookup = {
+						db: tx,
+						tenantId: principal.tenantId,
+						createdByUserId: principal.userId,
+						specHash: hash,
+						limit: 1
+					};
+					const [existing2] = await listRuntimeReports(lookup);
+					const [archived2] = existing2 ? [] : await listRuntimeReports({
+						...lookup,
+						status: "archived"
+					});
+					return {
+						existing: existing2,
+						archived: archived2
+					};
+				});
+				if (archived) throw new RuntimeReportHttpError(409, "report_archived", "Restore the archived report before confirming it again");
+				let compiled;
+				try {
+					compiled = await compileRuntimeReportSpec(spec, runtimeReportPrincipalCompileContext(serverOptions, principal));
+				} catch (error) {
+					if (existing && error instanceof RuntimeReportError && isRuntimeReportAccessError(error)) throw new RuntimeReportHttpError(403, "forbidden", "Report access denied");
+					throw error;
+				}
+				let created = false;
+				let report = existing ? {
+					id: existing.id,
+					specHash: hash,
+					title: existing.title
+				} : void 0;
+				if (!report) report = await runOnce({
+					db: principal.db,
+					tenantId: principal.tenantId,
+					actor: principal.userId,
+					token: "runtime-report-confirm",
+					content: spec
+				}, async (tx) => {
+					const [current] = await listRuntimeReports({
+						db: tx,
+						tenantId: principal.tenantId,
+						createdByUserId: principal.userId,
+						specHash: hash,
+						limit: 1
+					});
+					const saved = current ?? await saveRuntimeReport({
+						db: tx,
+						tenantId: principal.tenantId,
+						createdByUserId: principal.userId,
+						compiled,
+						confirmedSpecHash: hash
+					});
+					created = !current;
+					if (!saved.id) throw new Error("Saved report has no id");
+					return {
+						id: saved.id,
+						specHash: hash,
+						title: saved.title
+					};
+				});
+				if (!report.id) throw new Error("Saved report has no id");
+				await serverOptions.audit?.({
+					action: "confirm",
+					userId: principal.userId,
+					tenantId: principal.tenantId,
+					specHash: hash,
+					reportId: report.id,
+					reused: !created
+				});
+				return Response.json({
+					id: report.id,
+					specHash: hash,
+					title: report.title
+				}, {
+					status: created ? 201 : 200,
+					headers: { "Cache-Control": "no-store" }
+				});
+			});
+		} catch (error) {
+			if (error instanceof RuntimeReportHttpError || error instanceof RuntimeReportError) return Response.json({
+				code: error.code,
+				message: error.message
+			}, {
+				status: error instanceof RuntimeReportError ? 422 : error.status,
+				headers: { "Cache-Control": "no-store" }
+			});
+			return Response.json({
+				code: "internal_error",
+				message: "Unable to confirm report"
+			}, {
+				status: 500,
+				headers: { "Cache-Control": "no-store" }
+			});
+		}
+	};
+}
+function getRuntimeReportServerOptions() {
+	return getPackageConfig("reports").runtime ?? { sources: [] };
+}
+function currentRuntimeReportPrincipal(db) {
+	const context = getCurrentTenant();
+	return {
+		db,
+		userId: context?.userId ?? "",
+		tenantId: context?.tenantId ?? "",
+		permissions: [...context?.permissions ?? []]
+	};
+}
+async function runRuntimeReportForPrincipal(ref, principal, options = getRuntimeReportServerOptions()) {
+	assertRuntimeReportPrincipal(principal, "runtimereports.read");
+	return withTenant({
+		tenantId: principal.tenantId,
+		userId: principal.userId,
+		permissions: new Set(principal.permissions)
+	}, async () => {
+		const report = await getRuntimeReport({
+			db: principal.db,
+			ref,
+			tenantId: principal.tenantId
+		});
+		if (!report) throw new RuntimeReportHttpError(404, "not_found", "Report not found");
+		if (report.status === "archived") throw new RuntimeReportHttpError(409, "report_archived", "Restore the archived report before running it");
+		try {
+			return await runStoredRuntimeReport({
+				db: principal.db,
+				report,
+				context: runtimeReportPrincipalCompileContext(options, principal)
+			});
+		} catch (error) {
+			if (error instanceof RuntimeReportError) {
+				if (isRuntimeReportAccessError(error)) throw new RuntimeReportHttpError(403, "forbidden", "Report access denied");
+				throw new RuntimeReportHttpError(422, error.code, error.message);
+			}
+			throw error;
+		}
+	});
+}
+async function archiveRuntimeReportForPrincipal(ref, archived, principal) {
+	assertRuntimeReportPrincipal(principal, "runtimereports.create");
+	if (typeof archived !== "boolean") throw new RuntimeReportHttpError(422, "invalid_value", "archived must be a boolean");
+	return withTenant({
+		tenantId: principal.tenantId,
+		userId: principal.userId,
+		permissions: new Set(principal.permissions)
+	}, async () => {
+		const report = await getRuntimeReport({
+			db: principal.db,
+			ref,
+			tenantId: principal.tenantId
+		});
+		if (!report?.id) throw new RuntimeReportHttpError(404, "not_found", "Report not found");
+		const status = archived ? "archived" : "active";
+		if (report.status !== status) {
+			report.status = status;
+			await report.save();
+		}
+		return {
+			id: report.id,
+			status
+		};
+	});
+}
+async function loadRuntimeReportChart(options, context) {
+	assertRuntimeReportPrincipal(context.reportPrincipal, "runtimereports.read");
+	if (typeof options.reportId !== "string" || typeof options.measure !== "string") throw new RuntimeReportHttpError(422, "invalid_value", "Select a report and measure");
+	const result = await runRuntimeReportForPrincipal(options.reportId, context.reportPrincipal);
+	const measure = result.columns.find((column) => column.id === options.measure && column.role === "measure");
+	const dimension = options.dimension === void 0 ? result.columns.find((column) => column.role === "dimension") : result.columns.find((column) => column.id === options.dimension && column.role === "dimension");
+	if (!measure || options.dimension !== void 0 && !dimension) throw new RuntimeReportHttpError(422, "invalid_value", "Invalid report measure or dimension");
+	return {
+		points: result.rows.map((row) => {
+			const value = row[measure.id];
+			if (typeof value !== "number" || !Number.isFinite(value)) throw new RuntimeReportHttpError(422, "invalid_result", "Chart requires numeric measures");
+			return {
+				label: dimension ? String(row[dimension.id] ?? "") : result.title,
+				value
+			};
+		}),
+		format: measure.format === "money" ? "money" : measure.type === "integer" ? "integer" : "decimal",
+		...context.currency ? { currency: context.currency } : {},
+		href: `/reports/${encodeURIComponent(options.reportId)}`
+	};
+}
+//#endregion
 //#region src/runtime-report.ts
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -1941,6 +2089,14 @@ var RuntimeReport = class extends SmrtObject {
 		const proof = options[CONFIRMED_SAVE];
 		if (typeof proof === "string") confirmedSaves.set(this, proof);
 	}
+	/** Run fresh totals using the authenticated viewer's current permissions. */
+	async run() {
+		return runRuntimeReportForPrincipal(this.id ?? "", currentRuntimeReportPrincipal(this.db));
+	}
+	/** Archive or restore this definition; no report content can be changed. */
+	async archive(options) {
+		return archiveRuntimeReportForPrincipal(this.id ?? "", options?.archived, currentRuntimeReportPrincipal(this.db));
+	}
 	/** Re-parse the stored JSON; never trust the column without validation. */
 	getSpec() {
 		const parsed = parseRuntimeReportSpec(this.spec);
@@ -1999,13 +2155,60 @@ __decorateClass([field({
 __decorateClass([field({ type: "text" })], RuntimeReport.prototype, "createdByUserId", 2);
 RuntimeReport = __decorateClass([TenantScoped({ mode: "required" }), smrt({
 	tableName: "runtime_reports",
-	api: { include: [
+	indexes: [{
+		name: "idx_runtime_reports_confirm",
+		columns: [
+			"tenantId",
+			"createdByUserId",
+			"specHash",
+			"status"
+		]
+	}],
+	operationPermissions: {
+		run: { action: "read" },
+		archive: {
+			action: "create",
+			databaseActions: ["SELECT", "UPDATE"]
+		}
+	},
+	api: {
+		include: [
+			"list",
+			"get",
+			"create",
+			"run",
+			"archive"
+		],
+		principalContext: true,
+		routes: {
+			run: {
+				method: "POST",
+				scope: "item",
+				effect: "read",
+				idempotent: true,
+				openWorld: false
+			},
+			archive: {
+				method: "POST",
+				scope: "item",
+				effect: "write",
+				idempotent: true,
+				openWorld: false
+			}
+		}
+	},
+	mcp: { include: [
 		"list",
 		"get",
-		"create"
+		"run",
+		"archive"
 	] },
-	mcp: { include: ["list", "get"] },
-	cli: { include: ["list", "get"] }
+	cli: { include: [
+		"list",
+		"get",
+		"run",
+		"archive"
+	] }
 })], RuntimeReport);
 var RuntimeReportCollection = class extends SmrtCollection {
 	static _itemClass = RuntimeReport;
@@ -2064,6 +2267,170 @@ async function runStoredRuntimeReport(options) {
 	});
 }
 //#endregion
+//#region src/recipes.ts
+var MaterializedReportsRecipe = class extends SmrtRecipe {
+	static id = "reports.materialized";
+	static help = "./materialized.recipe.md";
+	static label = "Reports";
+	static summary = "Keep totals and trends ready to read, refreshed on a schedule and open to the assistant.";
+	static synonyms = [
+		"reports",
+		"totals",
+		"summaries",
+		"rollups",
+		"kpis",
+		"trends",
+		"dashboards"
+	];
+	static models = [
+		SmrtReportRun,
+		SmrtReportWatermark,
+		SmrtReportLock,
+		SmrtReportSchedule,
+		SmrtReportRefreshTask,
+		SmrtPrincipalReportRefreshTask
+	];
+	static runtime = "server";
+};
+var RuntimeReportsRecipe = class extends SmrtRecipe {
+	static id = "reports.runtime";
+	static label = "Reports";
+	static summary = "Ask for a report, approve it, and share its live totals with your team.";
+	static help = "./runtime.recipe.md";
+	static models = [RuntimeReport];
+	static nav = [{
+		label: "Reports",
+		model: RuntimeReport,
+		icon: "fileText"
+	}];
+	static surfaces = [
+		{
+			kind: "route",
+			path: "/reports",
+			export: "@happyvertical/smrt-reports/svelte#RuntimeReportsRoute",
+			label: "Reports"
+		},
+		{
+			kind: "route",
+			path: "/reports/:id",
+			export: "@happyvertical/smrt-reports/svelte#RuntimeReportDetailRoute",
+			label: "Report detail"
+		},
+		{
+			kind: "widget",
+			type: "runtime-report-chart",
+			export: "@happyvertical/smrt-reports/svelte#RuntimeReportChartWidget",
+			label: "Report chart",
+			description: "Chart a measure from a saved report.",
+			icon: "chart",
+			optionsEditor: "@happyvertical/smrt-reports/svelte#RuntimeReportWidgetOptions",
+			options: [
+				{
+					key: "reportId",
+					type: "text",
+					label: "Report",
+					required: true
+				},
+				{
+					key: "measure",
+					type: "identifier",
+					label: "Measure",
+					required: true
+				},
+				{
+					key: "dimension",
+					type: "identifier",
+					label: "Dimension"
+				}
+			],
+			data: {
+				load: "@happyvertical/smrt-reports#loadRuntimeReportChart",
+				models: ["@happyvertical/smrt-reports:RuntimeReport"]
+			},
+			defaultSpan: 2,
+			maxSpan: 4
+		}
+	];
+	static runtime = "server";
+};
+//#endregion
+//#region src/report.ts
+function registryColumnName(fieldName, field) {
+	return validateColumnName(field?.columnName ?? field?._meta?.columnName ?? toSnakeCase(fieldName));
+}
+function findFieldColumn(fields, fieldName) {
+	const direct = fields.get(fieldName);
+	if (direct) return registryColumnName(fieldName, direct);
+	const requestedColumn = toSnakeCase(fieldName);
+	for (const [name, field] of fields.entries()) if (toSnakeCase(name) === requestedColumn) return registryColumnName(name, field);
+	return validateColumnName(requestedColumn);
+}
+function findTenantColumn(fields, configuredField) {
+	if (configuredField) return registryColumnName(configuredField, fields.get(configuredField));
+	for (const [fieldName, field] of fields.entries()) if (fieldName === "tenantId" || field?._meta?.__tenancy?.isTenantIdField) return registryColumnName(fieldName, field);
+	return null;
+}
+var SmrtReport = class extends SmrtObject {
+	static _isReportBase = true;
+	refreshedAt = null;
+	constructor(options = {}) {
+		super(options);
+		if (options.refreshedAt !== void 0) this.refreshedAt = options.refreshedAt instanceof Date ? options.refreshedAt : options.refreshedAt ? new Date(options.refreshedAt) : null;
+	}
+	isStale(ttlMs) {
+		if (!this.refreshedAt) return true;
+		if (ttlMs === void 0) return false;
+		return Date.now() - this.refreshedAt.getTime() > ttlMs;
+	}
+	async refresh(options = {}) {
+		const result = await refreshReport(this.constructor, {
+			...options,
+			db: this.db
+		});
+		this.refreshedAt = result.refreshedAt;
+		return result;
+	}
+};
+var SmrtReportCollection = class extends SmrtCollection {
+	async refreshIfStale() {
+		const reportCtor = this.getItemClass();
+		const refresh = (await buildReportDefinition(reportCtor)).refresh;
+		if (!refresh?.ttl || refresh.manual) return;
+		const registered = ObjectRegistry.getClassByConstructor(reportCtor) ?? ObjectRegistry.getClass(reportCtor.name);
+		const reportClass = registered?.qualifiedName ?? registered?.name ?? reportCtor.name;
+		const tableName = ObjectRegistry.getTableName(reportClass);
+		if (!tableName) return;
+		const fields = await ObjectRegistry.getAllFields(reportClass);
+		const safeTableName = validateColumnName(tableName);
+		const refreshedAtColumn = findFieldColumn(fields, "refreshedAt");
+		const tenantColumn = findTenantColumn(fields, registered?.tenantScopedConfig?.field);
+		const tenantId = getTenantId() ?? null;
+		const result = tenantColumn ? await this.db.query(`SELECT MAX(${refreshedAtColumn}) AS refreshed_at FROM ${safeTableName} WHERE ${tenantColumn} ${tenantId ? "= ?" : "IS NULL"}`, ...tenantId ? [tenantId] : []) : await this.db.query(`SELECT MAX(${refreshedAtColumn}) AS refreshed_at FROM ${safeTableName}`);
+		const refreshedAt = result.rows[0]?.refreshed_at ? new Date(result.rows[0].refreshed_at) : null;
+		if (!(!refreshedAt || Date.now() - refreshedAt.getTime() > refresh.ttl)) return;
+		await refreshReport(reportCtor, {
+			db: this.db,
+			mode: refresh.mode ?? "rebuild",
+			trigger: "ttl",
+			tenantId
+		});
+	}
+	async refresh(options = {}) {
+		return refreshReport(this.getItemClass(), {
+			...options,
+			db: this.db
+		});
+	}
+	async list(options = {}) {
+		await this.refreshIfStale();
+		return super.list(options);
+	}
+	async get(filter, options = {}) {
+		await this.refreshIfStale();
+		return super.get(filter, options);
+	}
+};
+//#endregion
 //#region src/views.ts
 var INHERITED_REPORT_SCOPE = [
 	"principal",
@@ -2584,6 +2951,6 @@ function validateReportExportArtifact(descriptor, artifact, now = /* @__PURE__ *
 	};
 }
 //#endregion
-export { MaterializedReportsRecipe, REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPORT_RUNTIME_TABLES, REPORT_SCHEDULER_TABLES, REPORT_SCHEDULES_TABLE, REPORT_WATERMARKS_TABLE, RUNTIME_REPORT_BUCKETS, RUNTIME_REPORT_CHART_TYPES, RUNTIME_REPORT_FILTER_OPS, RUNTIME_REPORT_HAVING_OPS, RUNTIME_REPORT_LIMITS, RUNTIME_REPORT_MEASURE_FNS, RUNTIME_REPORT_SPEC_VERSION, ReportScheduleRunner, ReportSurfaceValidationError, RuntimeReport, RuntimeReportCollection, RuntimeReportError, SmrtPrincipalReportRefreshTask, SmrtReport, SmrtReportCollection, SmrtReportLock, SmrtReportLockCollection, SmrtReportRefreshTask, SmrtReportRun, SmrtReportRunCollection, SmrtReportSchedule, SmrtReportScheduleCollection, SmrtReportWatermark, SmrtReportWatermarkCollection, aggregate, applyReportExport, applyReportRefresh, archiveRuntimeReport, assertReportTablesReady, avg, bucketExpr, buildAggregate, buildReportAdapterDescriptor, buildReportDefinition, buildReportDrilldownQuery, compileReportDefinition, compileReportSpec, compileRuntimeReportSpec, count, createReportExportPageRequest, createReportExportRequest, createReportExportSnapshot, day, describeRuntimeReportSource, enqueueReportRefresh, ensureReportRefreshSchedules, getReportGroupingColumns, getReportLifecycle, getRuntimeReport, getRuntimeReportOptions, groupBy, hour, listRuntimeReports, max, migrateReportSavedView, min, minute, month, normalizeReportSavedView, parseRuntimeReportSpec, previewReportExport, previewReportRefresh, quarter, queryReportMaterializedRows, refreshReport, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner, report, reportDefinitionFingerprint, reportMaterializedRowKey, reportRefreshOutcome, reportRowIdentity, restoreReportSavedView, runRuntimeReport, runStoredRuntimeReport, runtimeReportSpecHash, saveRuntimeReport, scopeKeyForTenant, serializeRuntimeReportSpec, splitReportFilterScopes, sum, validateReportExportArtifact, validateReportExportExecution, validateReportExportRequest, verifyReportExportSnapshot, week, year };
+export { MaterializedReportsRecipe, REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPORT_RUNTIME_TABLES, REPORT_SCHEDULER_TABLES, REPORT_SCHEDULES_TABLE, REPORT_WATERMARKS_TABLE, RUNTIME_REPORT_BUCKETS, RUNTIME_REPORT_CHART_TYPES, RUNTIME_REPORT_FILTER_OPS, RUNTIME_REPORT_HAVING_OPS, RUNTIME_REPORT_LIMITS, RUNTIME_REPORT_MEASURE_FNS, RUNTIME_REPORT_SPEC_VERSION, ReportScheduleRunner, ReportSurfaceValidationError, RuntimeReport, RuntimeReportCollection, RuntimeReportError, RuntimeReportHttpError, RuntimeReportsRecipe, SmrtPrincipalReportRefreshTask, SmrtReport, SmrtReportCollection, SmrtReportLock, SmrtReportLockCollection, SmrtReportRefreshTask, SmrtReportRun, SmrtReportRunCollection, SmrtReportSchedule, SmrtReportScheduleCollection, SmrtReportWatermark, SmrtReportWatermarkCollection, aggregate, applyReportExport, applyReportRefresh, archiveRuntimeReport, archiveRuntimeReportForPrincipal, assertMaterializedReportRead, assertReportTablesReady, avg, bucketExpr, buildAggregate, buildReportAdapterDescriptor, buildReportDefinition, buildReportDrilldownQuery, compileReportDefinition, compileReportSpec, compileRuntimeReportSpec, count, createReportExportPageRequest, createReportExportRequest, createReportExportSnapshot, createRuntimeReportConfirmHandler, day, describeRuntimeReportSource, enqueueReportRefresh, ensureReportRefreshSchedules, findMaterializedReportHost, getReportGroupingColumns, getReportLifecycle, getRuntimeReport, getRuntimeReportOptions, getRuntimeReportServerOptions, groupBy, hour, listRuntimeReports, loadRuntimeReportChart, max, migrateReportSavedView, min, minute, month, normalizeReportSavedView, parseRuntimeReportSpec, previewReportExport, previewReportRefresh, quarter, queryReportMaterializedRows, refreshReport, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner, report, reportDefinitionFingerprint, reportMaterializedRowKey, reportRefreshOutcome, reportRowIdentity, restoreReportSavedView, runRuntimeReport, runRuntimeReportForPrincipal, runStoredRuntimeReport, runtimeReportSpecHash, saveRuntimeReport, scopeKeyForTenant, serializeRuntimeReportSpec, splitReportFilterScopes, sum, validateReportExportArtifact, validateReportExportExecution, validateReportExportRequest, verifyReportExportSnapshot, week, year };
 
 //# sourceMappingURL=index.js.map