@camstack/system 1.0.2

package/dist/builtins/alerts/alerts.addon.mjs

@@ -0,0 +1,595 @@
+import { AlertSchema, BaseAddon, EventCategory, alertsCapability, createEvent, errMsg } from "@camstack/types";
+//#region src/builtins/alerts/alerts.addon.ts
+var CATEGORY_MAPPINGS = {
+	"addon.crashed": {
+		severity: "error",
+		titleTemplate: "Addon crashed"
+	},
+	"addon.error": {
+		severity: "error",
+		titleTemplate: "Addon error"
+	},
+	"process.crashed": {
+		severity: "error",
+		titleTemplate: "Process crashed"
+	},
+	"recording.error": {
+		severity: "error",
+		titleTemplate: "Recording error"
+	},
+	"recording.storage.critical": {
+		severity: "warning",
+		titleTemplate: "Storage critical"
+	},
+	"notification.failed": {
+		severity: "error",
+		titleTemplate: "Notification failed"
+	},
+	"agent.online": {
+		severity: "info",
+		titleTemplate: "Agent connected"
+	},
+	"agent.offline": {
+		severity: "warning",
+		titleTemplate: "Agent disconnected"
+	},
+	"system.boot": {
+		severity: "info",
+		titleTemplate: "System boot"
+	},
+	"system.restarting": {
+		severity: "warning",
+		titleTemplate: "System restarting"
+	},
+	"device.registered": {
+		severity: "info",
+		titleTemplate: "Device registered"
+	},
+	"device.unregistered": {
+		severity: "warning",
+		titleTemplate: "Device unregistered"
+	},
+	"addon.installed": {
+		severity: "info",
+		titleTemplate: "Addon installed"
+	},
+	"addon.updated": {
+		severity: "info",
+		titleTemplate: "Addon updated"
+	},
+	"addon.uninstalled": {
+		severity: "info",
+		titleTemplate: "Addon uninstalled"
+	},
+	"addon.load-failed": {
+		severity: "error",
+		titleTemplate: "Addon failed to load"
+	},
+	"addon.load-recovered": {
+		severity: "info",
+		titleTemplate: "Addon recovered"
+	},
+	"backup.completed": {
+		severity: "info",
+		titleTemplate: "Backup completed"
+	},
+	"backup.restored": {
+		severity: "info",
+		titleTemplate: "Backup restored"
+	},
+	"model.download.progress": {
+		severity: "info",
+		titleTemplate: "Model download"
+	}
+};
+var TRACKED_CATEGORIES = Object.keys(CATEGORY_MAPPINGS);
+/**
+* `[ALERT-CENTER-EVENTS]` — rate limiting. Events that fire thousands of
+* times a minute (flaky cam reconnecting, chatty integration, …) would
+* flood the alert feed and push genuinely important alerts off the
+* visible page. We collapse bursts into a single throttled summary per
+* `(category, source.id)` tuple: the first N events within the window
+* still surface as individual alerts, but once the source crosses the
+* threshold we stop emitting alerts for it and wait out the window.
+*
+* A standalone category-count map is cleared on every window rollover.
+* Keep the threshold generous enough that legitimate bursts of ~a few
+* per minute still get through, but strict enough that a reconnect loop
+* firing every second gets muted.
+*/
+var RATE_LIMIT_WINDOW_MS = 6e4;
+var RATE_LIMIT_MAX_PER_SOURCE = 5;
+/** Parse a raw settings record into a validated Alert. */
+function parseAlert(record) {
+	return AlertSchema.parse({
+		id: record.id,
+		...record.data
+	});
+}
+var DEFAULT_CONFIG = {
+	maxAlerts: 500,
+	retentionDays: 30
+};
+var ALERTS_COLLECTION = "alerts";
+var EVENT_SOURCE = {
+	type: "addon",
+	id: "alert-center"
+};
+/**
+* Alert Center addon — core builtin that persists alerts in a
+* structured SQLite table and serves them to the admin UI.
+*
+* Registers as an `alerts` collection provider and subscribes to
+* important EventBus categories to create/update alerts automatically.
+*/
+var AlertCenterAddon = class extends BaseAddon {
+	unsubscribers = [];
+	constructor() {
+		super({ ...DEFAULT_CONFIG });
+	}
+	/**
+	* Per `(category, source.id)` counter used to rate-limit chatty
+	* events. Entries are pruned lazily when they age out of
+	* `RATE_LIMIT_WINDOW_MS`; see `shouldSuppressByRate()` below.
+	*/
+	rateLimitCounters = /* @__PURE__ */ new Map();
+	async onInitialize() {
+		const alertsProvider = {
+			emit: (alert) => this.emitAlert(alert),
+			update: (input) => this.updateAlert(input.alertId, input.patch),
+			list: (filter) => this.listAlerts(filter),
+			getUnreadCount: () => this.getUnreadCount(),
+			markRead: (input) => this.markRead(input.alertId),
+			markAllRead: () => this.markAllRead(),
+			dismiss: (input) => this.dismiss(input.alertId)
+		};
+		const unsubs = [];
+		for (const category of TRACKED_CATEGORIES) {
+			const unsub = this.ctx.eventBus.subscribe({ category }, (event) => {
+				this.handleEvent(category, event);
+			});
+			unsubs.push(unsub);
+		}
+		this.unsubscribers = unsubs;
+		this.ctx.logger.info("Initialized", { meta: { trackedCategoriesCount: TRACKED_CATEGORIES.length } });
+		return [{
+			capability: alertsCapability,
+			provider: alertsProvider
+		}];
+	}
+	async onShutdown() {
+		for (const unsub of this.unsubscribers) unsub();
+		this.unsubscribers = [];
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "alerts",
+			title: "Alert Center",
+			description: "Configure alert storage and retention.",
+			columns: 1,
+			fields: [this.field({
+				type: "number",
+				key: "maxAlerts",
+				label: "Maximum stored alerts",
+				description: "Oldest read alerts are deleted when this limit is exceeded.",
+				min: 50,
+				max: 5e3,
+				step: 50,
+				default: 500
+			}), this.field({
+				type: "number",
+				key: "retentionDays",
+				label: "Alert retention (days)",
+				description: "Alerts older than this are automatically removed.",
+				min: 1,
+				max: 365,
+				step: 1,
+				default: 30
+			})]
+		}] });
+	}
+	async listAlerts(filter) {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return [];
+		const whereClause = {};
+		if (filter?.unreadOnly) whereClause.read = false;
+		return (await backend.query.query({
+			collection: ALERTS_COLLECTION,
+			filter: {
+				where: Object.keys(whereClause).length > 0 ? whereClause : void 0,
+				orderBy: {
+					field: "updatedAt",
+					direction: "desc"
+				},
+				limit: filter?.limit ?? 100
+			}
+		})).map(parseAlert);
+	}
+	async getUnreadCount() {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return 0;
+		return backend.count.query({
+			collection: ALERTS_COLLECTION,
+			filter: { where: { read: false } }
+		});
+	}
+	async markRead(alertId) {
+		await this.mergeUpdate(alertId, {
+			read: true,
+			updatedAt: Date.now()
+		});
+	}
+	async markAllRead() {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return;
+		const unread = await backend.query.query({
+			collection: ALERTS_COLLECTION,
+			filter: { where: { read: false } }
+		});
+		const now = Date.now();
+		for (const record of unread) await this.mergeUpdate(record.id, {
+			read: true,
+			updatedAt: now
+		});
+	}
+	async dismiss(alertId) {
+		await this.mergeUpdate(alertId, {
+			status: "dismissed",
+			read: true,
+			updatedAt: Date.now()
+		});
+	}
+	async handleEvent(category, event) {
+		try {
+			if (category === "model.download.progress") {
+				await this.handleModelDownload(event);
+				return;
+			}
+			if (category === EventCategory.AddonLoadFailed) {
+				await this.handleAddonLoadFailed(event);
+				return;
+			}
+			if (category === EventCategory.AddonLoadRecovered) {
+				await this.handleAddonLoadRecovered(event);
+				return;
+			}
+			const mapping = CATEGORY_MAPPINGS[category];
+			if (!mapping) return;
+			if (this.shouldSuppressByRate(category, event)) return;
+			const message = this.buildMessage(category, event.data, event.source ? String(event.source.id) : void 0);
+			const alert = {
+				id: crypto.randomUUID(),
+				category,
+				severity: mapping.severity,
+				title: mapping.titleTemplate,
+				message,
+				status: "active",
+				read: false,
+				createdAt: Date.now(),
+				updatedAt: Date.now(),
+				source: event.source ? {
+					type: event.source.type,
+					id: String(event.source.id)
+				} : void 0,
+				metadata: event.data
+			};
+			await this.emitAlert(alert);
+		} catch (err) {
+			this.ctx.logger?.warn("Failed to handle event", { meta: {
+				category,
+				error: errMsg(err)
+			} });
+		}
+	}
+	async handleModelDownload(event) {
+		const data = event.data;
+		const modelId = data.modelId ?? "unknown";
+		const progress = data.progress ?? 0;
+		const stableId = `model-download:${modelId}`;
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return;
+		if ((await backend.query.query({
+			collection: ALERTS_COLLECTION,
+			filter: { where: { id: stableId } }
+		})).length > 0) {
+			const now = Date.now();
+			if (progress >= 100) {
+				await this.mergeUpdate(stableId, {
+					status: "completed",
+					progress: 100,
+					message: `Model "${modelId}" download completed`,
+					updatedAt: now
+				});
+				this.emitAlertUpdatedEvent(stableId, {
+					status: "completed",
+					progress: 100
+				});
+			} else if (progress < 0) {
+				await this.mergeUpdate(stableId, {
+					status: "failed",
+					message: `Model "${modelId}" download failed`,
+					updatedAt: now
+				});
+				this.emitAlertUpdatedEvent(stableId, { status: "failed" });
+			} else {
+				await this.mergeUpdate(stableId, {
+					progress,
+					message: `Downloading model "${modelId}" — ${String(Math.round(progress))}%`,
+					updatedAt: now
+				});
+				this.emitAlertUpdatedEvent(stableId, { progress });
+			}
+		} else {
+			const alert = {
+				id: stableId,
+				category: EventCategory.ModelDownloadProgress,
+				severity: "info",
+				title: "Model download",
+				message: `Downloading model "${modelId}" — ${String(Math.round(progress))}%`,
+				status: "in-progress",
+				progress,
+				read: false,
+				createdAt: Date.now(),
+				updatedAt: Date.now(),
+				source: event.source ? {
+					type: event.source.type,
+					id: String(event.source.id)
+				} : void 0,
+				metadata: { modelId }
+			};
+			await this.persistAlert(alert);
+			this.emitAlertCreatedEvent(alert);
+		}
+	}
+	/**
+	* `[ALERT-CENTER-EVENTS]` — rate limit a `(category, source.id)`
+	* tuple. Returns `true` when the caller should DROP this event
+	* without persisting an alert, and `false` when the alert should
+	* proceed normally.
+	*
+	* Heuristic: the first `RATE_LIMIT_MAX_PER_SOURCE` events within a
+	* `RATE_LIMIT_WINDOW_MS` window go through. Once the threshold is
+	* crossed, subsequent events are suppressed until the window rolls
+	* over. When the threshold is first crossed, the suppression is
+	* logged once so operators know why they're not seeing the follow-
+	* up alerts; after the window rolls over the next event is
+	* un-suppressed and starts a new window.
+	*/
+	shouldSuppressByRate(category, event) {
+		const sourceId = event.source?.id ?? "unknown";
+		const key = `${category}::${sourceId}`;
+		const now = Date.now();
+		const entry = this.rateLimitCounters.get(key);
+		if (!entry || now - entry.firstAt > RATE_LIMIT_WINDOW_MS) {
+			this.rateLimitCounters.set(key, {
+				firstAt: now,
+				count: 1,
+				suppressedLogged: false
+			});
+			return false;
+		}
+		entry.count += 1;
+		if (entry.count <= RATE_LIMIT_MAX_PER_SOURCE) return false;
+		if (!entry.suppressedLogged) {
+			entry.suppressedLogged = true;
+			this.ctx.logger?.info("rate-limiting suppressing remainder of window", { meta: {
+				category,
+				sourceId,
+				maxPerSource: RATE_LIMIT_MAX_PER_SOURCE,
+				windowSeconds: RATE_LIMIT_WINDOW_MS / 1e3
+			} });
+		}
+		return true;
+	}
+	/**
+	* AddonLoadFailed — kernel's AddonHealthMonitor has post-grace
+	* failed an addon load/init. Upsert a stable-id alert keyed by
+	* `addon-load-failed:<packageName>` so the recovery path can
+	* dismiss it. Severity=error, persistent until dismissed or
+	* auto-resolved.
+	*
+	* The action `retry` carries the package name so the admin UI can
+	* dispatch `addons.retryLoad(packageName)` directly from the alert
+	* card without the operator opening the Addons page.
+	*/
+	async handleAddonLoadFailed(event) {
+		const data = event.data;
+		const packageName = String(data["packageName"] ?? "");
+		if (!packageName) return;
+		const addonId = data["addonId"];
+		const errorObj = data["error"];
+		const retryCount = Number(data["retryCount"] ?? 0);
+		const nextRetryAt = data["nextRetryAt"];
+		const stableId = `addon-load-failed:${packageName}`;
+		const message = errorObj?.message ? `${addonId ? `${addonId} — ` : ""}${errorObj.message}` : `Addon ${addonId ?? packageName} failed to load`;
+		const alert = {
+			id: stableId,
+			category: EventCategory.AddonLoadFailed,
+			severity: "error",
+			title: `Addon failed: ${addonId ?? packageName}`,
+			message,
+			status: "active",
+			read: false,
+			createdAt: Date.now(),
+			updatedAt: Date.now(),
+			source: {
+				type: "addon",
+				id: packageName
+			},
+			metadata: {
+				packageName,
+				addonId,
+				retryCount,
+				nextRetryAt,
+				stack: errorObj?.stack
+			}
+		};
+		await this.emitAlert(alert);
+	}
+	/**
+	* AddonLoadRecovered — addon previously alerting is back to healthy.
+	* Dismiss the matching alert so the operator's badge count drops.
+	*/
+	async handleAddonLoadRecovered(event) {
+		const data = event.data;
+		const packageName = String(data["packageName"] ?? "");
+		if (!packageName) return;
+		const stableId = `addon-load-failed:${packageName}`;
+		try {
+			await this.dismiss(stableId);
+		} catch (err) {
+			this.ctx.logger?.debug("AddonLoadRecovered: dismiss failed (likely already dismissed)", { meta: {
+				stableId,
+				error: errMsg(err)
+			} });
+		}
+	}
+	buildMessage(category, data, sourceId) {
+		const addonId = data.addonId ?? sourceId;
+		const deviceId = data.deviceId;
+		const error = data.error;
+		const processId = data.processId;
+		switch (category) {
+			case "addon.crashed": return `Addon "${addonId ?? "unknown"}" crashed${error ? `: ${error}` : ""}`;
+			case "addon.error": return `Addon "${addonId ?? "unknown"}" error${error ? `: ${error}` : ""}`;
+			case "addon.installed": return `Addon "${addonId ?? "unknown"}" installed`;
+			case "addon.updated": {
+				const from = data.fromVersion;
+				const to = data.toVersion;
+				return `Addon "${addonId ?? "unknown"}" updated${from && to ? ` from ${from} to ${to}` : ""}`;
+			}
+			case "addon.uninstalled": return `Addon "${addonId ?? "unknown"}" uninstalled`;
+			case "device.registered": return `Device "${data.name ?? deviceId ?? "unknown"}" registered`;
+			case "device.unregistered": return `Device "${deviceId ?? "unknown"}" unregistered`;
+			case "agent.online": return `Agent "${data.agentId ?? data.nodeId ?? "unknown"}" connected`;
+			case "agent.offline": return `Agent "${data.agentId ?? data.nodeId ?? "unknown"}" disconnected${data.reason ? `: ${String(data.reason)}` : ""}`;
+			case "backup.completed": return `Backup completed${data.targetId ? ` (${String(data.targetId)})` : ""}`;
+			case "backup.restored": return `Backup restored${data.source ? ` from ${String(data.source)}` : ""}`;
+			case "notification.failed": return `Notification failed${error ? `: ${error}` : ""}`;
+			case "system.restarting": return `System restarting${data.reason ? ` — ${String(data.reason)}` : ""}`;
+			case "recording.error": return `Recording error on device "${deviceId ?? "unknown"}"${error ? `: ${error}` : ""}`;
+			case "recording.storage.critical": return `Storage critical for device "${deviceId ?? "unknown"}"`;
+			case "system.boot": return `System booted in "${data.mode ?? "unknown"}" mode`;
+			case "process.crashed": return `Process "${processId ?? "unknown"}" crashed`;
+			default: return `Event: ${category}`;
+		}
+	}
+	async emitAlert(alert) {
+		await this.persistAlert(alert);
+		this.emitAlertCreatedEvent(alert);
+		await this.enforceMaxAlerts();
+		await this.enforceRetention();
+	}
+	async updateAlert(alertId, patch) {
+		await this.mergeUpdate(alertId, {
+			...patch,
+			updatedAt: Date.now()
+		});
+		this.emitAlertUpdatedEvent(alertId, patch);
+	}
+	/**
+	* Read-merge-write: SettingsBackend.update() replaces the entire `data` blob,
+	* so we must read the existing record, merge the patch, and write back.
+	*/
+	async mergeUpdate(id, patch) {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return;
+		const raw = await backend.get.query({
+			collection: ALERTS_COLLECTION,
+			key: id
+		});
+		if (raw === null || raw === void 0 || typeof raw !== "object") return;
+		const existing = Object.fromEntries(Object.entries(raw));
+		await backend.set.mutate({
+			collection: ALERTS_COLLECTION,
+			key: id,
+			value: {
+				...existing,
+				...patch
+			}
+		});
+	}
+	async persistAlert(alert) {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return;
+		const data = {
+			id: alert.id,
+			category: alert.category,
+			severity: alert.severity,
+			title: alert.title,
+			message: alert.message,
+			status: alert.status,
+			read: alert.read,
+			createdAt: alert.createdAt,
+			updatedAt: alert.updatedAt,
+			...alert.progress !== void 0 ? { progress: alert.progress } : {},
+			...alert.source ? { source: alert.source } : {},
+			...alert.metadata ? { metadata: alert.metadata } : {}
+		};
+		await backend.set.mutate({
+			collection: ALERTS_COLLECTION,
+			key: alert.id,
+			value: data
+		});
+	}
+	emitAlertCreatedEvent(alert) {
+		this.ctx.eventBus?.emit(createEvent("alert.created", EVENT_SOURCE, {
+			id: alert.id,
+			category: alert.category,
+			severity: alert.severity,
+			title: alert.title,
+			status: alert.status
+		}));
+	}
+	emitAlertUpdatedEvent(alertId, patch) {
+		const patchRecord = {};
+		for (const [key, value] of Object.entries(patch)) patchRecord[key] = value;
+		this.ctx.eventBus?.emit(createEvent("alert.updated", EVENT_SOURCE, {
+			alertId,
+			patch: patchRecord
+		}));
+	}
+	async enforceMaxAlerts() {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return;
+		const total = await backend.count.query({ collection: ALERTS_COLLECTION });
+		if (total <= this.config.maxAlerts) return;
+		const excess = total - this.config.maxAlerts;
+		const oldest = await backend.query.query({
+			collection: ALERTS_COLLECTION,
+			filter: {
+				where: { read: true },
+				orderBy: {
+					field: "createdAt",
+					direction: "asc"
+				},
+				limit: excess
+			}
+		});
+		for (const record of oldest) await backend.delete.mutate({
+			collection: ALERTS_COLLECTION,
+			key: record.id
+		});
+	}
+	async enforceRetention() {
+		const backend = this.ctx.api.settingsStore;
+		if (!backend) return;
+		const cutoff = Date.now() - this.config.retentionDays * 24 * 60 * 60 * 1e3;
+		const expired = await backend.query.query({
+			collection: ALERTS_COLLECTION,
+			filter: {
+				where: { read: true },
+				orderBy: {
+					field: "createdAt",
+					direction: "asc"
+				}
+			}
+		});
+		for (const record of expired) if (Number(record.data["createdAt"] ?? 0) < cutoff) await backend.delete.mutate({
+			collection: ALERTS_COLLECTION,
+			key: record.id
+		});
+	}
+};
+//#endregion
+export { AlertCenterAddon, AlertCenterAddon as default };

package/dist/builtins/alerts/index.d.ts

@@ -0,0 +1 @@
+export { AlertCenterAddon } from './alerts.addon.js';

package/dist/builtins/alerts/index.js

@@ -0,0 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Cek0wNdY.js");
+const require_builtins_alerts_alerts_addon = require("./alerts.addon.js");
+exports.AlertCenterAddon = require_builtins_alerts_alerts_addon.AlertCenterAddon;

package/dist/builtins/alerts/index.mjs

@@ -0,0 +1,2 @@
+import { AlertCenterAddon } from "./alerts.addon.mjs";
+export { AlertCenterAddon };