@camstack/addon-post-analysis 1.2.54 → 1.2.56

package/dist/pipeline-analytics/index.js

@@ -2,11 +2,14 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-BJ65Xxa1.js");
+const require_dist = require("../dist-CcS9NwDl.js");
 let node_fs = require("node:fs");
+node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
+let node_path$1 = require_dist.__toESM(node_path, 1);
 node_path = require_dist.__toESM(node_path);
 let node_crypto = require("node:crypto");
+require("node:child_process");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
 //#region src/notification-center/action-token.ts
@@ -727,6 +730,227 @@ var NC_ALARM_DECLARATION = {
 	DeviceClass: NcAlarmPanelDevice
 };
 //#endregion
+//#region ../types/dist/node.mjs
+var node_exports = /* @__PURE__ */ require_dist.__exportAll({
+	FilesystemStorageProvider: () => FilesystemStorageProvider,
+	PYTHON_VERSION: () => PYTHON_VERSION,
+	signExpiringUrl: () => signExpiringUrl,
+	verifyExpiringUrl: () => verifyExpiringUrl
+});
+/**
+* Download portable Python (headless) from bjia56/portable-python.
+*
+* Source: https://github.com/bjia56/portable-python
+*
+* Advantages over python-build-standalone:
+* - macOS universal2 binary (arm64+x86_64 in one)
+* - Lighter (~24-28MB headless zip)
+* - glibc 2.17 minimum (better compat)
+* - Headless variant excludes tkinter/UI (ideal for ML inference)
+*
+* The zip's top-level dir is platform-specific (e.g.
+* `python-headless-3.12.12-darwin-universal2/`); after extraction
+* we rename it to a stable `python/` so consumers can rely on
+* `<dataDir>/deps/python/bin/python3`.
+*/
+var PYTHON_VERSION = "3.12.12";
+`${PYTHON_VERSION}`;
+var STORAGE_LOCATION_TYPES = [
+	"data",
+	"media",
+	"recordings",
+	"recordings-high",
+	"recordings-low",
+	"recordings-clips",
+	"event-images",
+	"models",
+	"addons-data",
+	"cache",
+	"logs",
+	"backups"
+];
+var DEFAULT_LOCATION_SUBDIRS = {
+	data: "db",
+	media: "media",
+	recordings: "recordings",
+	"recordings-high": "recordings-high",
+	"recordings-low": "recordings-low",
+	"recordings-clips": "recordings-clips",
+	"event-images": "event-images",
+	models: "models",
+	"addons-data": "addons-data",
+	cache: "/tmp/camstack-cache",
+	logs: "logs",
+	backups: "backups"
+};
+/**
+* Filesystem storage provider — serves all location types from a local directory tree.
+*
+* Default layout:
+*   {rootPath}/recordings-high/
+*   {rootPath}/recordings-low/
+*   {rootPath}/recordings-clips/
+*   {rootPath}/event-images/
+*   {rootPath}/models/
+*   {rootPath}/addons-data/
+*   {rootPath}/logs/
+*   /tmp/camstack-cache/   (cache is always local)
+*
+* Individual location paths can be overridden.
+*/
+var FilesystemStorageProvider = class {
+	id = "local";
+	name = "Local Filesystem";
+	supportedLocations = [...STORAGE_LOCATION_TYPES];
+	rootPath;
+	locationPaths;
+	constructor(rootPath, overrides) {
+		this.rootPath = node_path$1.resolve(rootPath);
+		this.locationPaths = /* @__PURE__ */ new Map();
+		for (const loc of STORAGE_LOCATION_TYPES) {
+			const override = overrides?.[loc];
+			if (override) this.locationPaths.set(loc, node_path$1.resolve(override));
+			else {
+				const subdir = DEFAULT_LOCATION_SUBDIRS[loc] ?? loc;
+				this.locationPaths.set(loc, node_path$1.isAbsolute(subdir) ? subdir : node_path$1.join(this.rootPath, subdir));
+			}
+		}
+		for (const [loc, override] of Object.entries(overrides ?? {})) if (typeof override === "string" && !this.locationPaths.has(loc)) this.locationPaths.set(loc, node_path$1.resolve(override));
+	}
+	async resolve({ location, relativePath }) {
+		const base = this.locationPaths.get(location) ?? node_path$1.join(this.rootPath, location);
+		return node_path$1.join(base, relativePath);
+	}
+	async write({ location, relativePath, data }) {
+		const filePath = await this.resolve({
+			location,
+			relativePath
+		});
+		await node_fs.promises.mkdir(node_path$1.dirname(filePath), { recursive: true });
+		if (Buffer.isBuffer(data)) await node_fs.promises.writeFile(filePath, data);
+		else {
+			const writeStream = node_fs.createWriteStream(filePath);
+			await new Promise((resolve, reject) => {
+				data.pipe(writeStream);
+				writeStream.on("finish", resolve);
+				writeStream.on("error", reject);
+			});
+		}
+	}
+	async read({ location, relativePath }) {
+		return node_fs.promises.readFile(await this.resolve({
+			location,
+			relativePath
+		}));
+	}
+	async exists({ location, relativePath }) {
+		try {
+			await node_fs.promises.access(await this.resolve({
+				location,
+				relativePath
+			}));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async list({ location, prefix }) {
+		const base = this.locationPaths.get(location);
+		if (!base) return [];
+		const dir = prefix ? node_path$1.join(base, prefix) : base;
+		try {
+			return (await node_fs.promises.readdir(dir, { withFileTypes: true })).map((e) => prefix ? `${prefix}/${e.name}` : e.name);
+		} catch {
+			return [];
+		}
+	}
+	async delete({ location, relativePath }) {
+		const filePath = await this.resolve({
+			location,
+			relativePath
+		});
+		await node_fs.promises.rm(filePath, { force: true });
+	}
+	async getAvailableSpace({ location }) {
+		const base = this.locationPaths.get(location);
+		if (!base) return null;
+		try {
+			let target = base;
+			while (!node_fs.existsSync(target)) {
+				const parent = node_path$1.dirname(target);
+				if (!parent || parent === target) return null;
+				target = parent;
+			}
+			const stats = await node_fs.promises.statfs(target);
+			return stats.bavail * stats.bsize;
+		} catch {
+			return null;
+		}
+	}
+	/** Get the resolved path for a location type (addon-declared ids fall back
+	*  to `<rootPath>/<id>`). */
+	getLocationPath(location) {
+		return this.locationPaths.get(location) ?? node_path$1.join(this.rootPath, location);
+	}
+	/** Get the root path */
+	getRootPath() {
+		return this.rootPath;
+	}
+};
+/**
+* The ONE derivation of "a signed, expiring URL".
+*
+* This repo mints unguessable, self-expiring links in three places now — the
+* notification artifact plane, the Home Assistant media plane, and the snapshot
+* link plane. The first two grew independently and are byte-identical logic
+* (`hmac(secret, "<id>:<exp>")`, expiry checked before a constant-time compare),
+* each restating the crypto locally because **addons never import each other**.
+*
+* That reason is real, and the conclusion drawn from it was wrong. Two copies of
+* a signing scheme is how one of them quietly ends up with a different TTL, a
+* different compare, or a missing expiry check, and nothing fails until a link
+* that should have died keeps working. The fix is the same one D52 applies to
+* crop geometry: one derivation, in a place every addon may depend on. A
+* framework package is exactly that place — `@camstack/types/node`, off the root
+* entry because `node:crypto` must never be traversed by a browser bundler.
+*
+* What this module deliberately does NOT decide: the TTL, the base URL, the
+* shape of `id`, and the access level of the route. Those are per-plane policy
+* and each caller states them where a reader can see them.
+*/
+/**
+* The signature over `(id, expMs)`.
+*
+* `id` is whatever the plane uses to name the thing being served — an artifact
+* id, a track id, a `<deviceId>:<width>` pair. It is joined with `:` so a caller
+* must not put a `:` inside a field whose boundary matters; where a plane has
+* more than one field, it composes them itself and owns that ambiguity.
+*/
+function signExpiringUrl(secret, id, expMs) {
+	return (0, node_crypto.createHmac)("sha256", secret).update(`${id}:${String(expMs)}`).digest("hex");
+}
+/**
+* Verify a request's `(id, exp, sig)`.
+*
+* **Expiry is checked BEFORE the compare**, so an expired link is refused
+* whether or not its signature is valid — a leaked URL stops working on its own
+* and cannot be kept alive by holding a correct signature. The compare itself is
+* constant-time so a public route cannot be probed for the signature byte by
+* byte.
+*/
+function verifyExpiringUrl(input) {
+	const { secret, id, exp, sig, nowMs } = input;
+	if (exp === void 0 || sig === void 0) return false;
+	const expMs = typeof exp === "number" ? exp : Number(exp);
+	if (!Number.isFinite(expMs)) return false;
+	if (expMs <= nowMs) return false;
+	const expected = signExpiringUrl(secret, id, expMs);
+	const a = Buffer.from(expected, "utf8");
+	const b = Buffer.from(sig, "utf8");
+	if (a.length !== b.length) return false;
+	return (0, node_crypto.timingSafeEqual)(a, b);
+}
+//#endregion
 //#region src/notification-center/artifact-url.ts
 /**
 * Signed, externally-reachable URLs for notification artifacts.
@@ -743,7 +967,10 @@ var NC_ALARM_DECLARATION = {
 *    recipient's phone) — it holds no session and no admin token. The route is
 *    therefore `access:'public'` and the authority is the signature: an
 *    unguessable HMAC over `(id, exp)` with a per-install secret, expiring on
-*    its own. Nothing else about the install is reachable through it.
+*    its own. Nothing else about the install is reachable through it. The HMAC
+*    is the shared one in `@camstack/types/node` — this module used to restate
+*    it, as did the Home Assistant media plane, and two copies of a signing
+*    scheme is how one of them quietly loses its expiry check.
 *  - **The base URL is CHOSEN, never assumed.** A notification carrying
 *    `http://127.0.0.1:...` is useless (the Alexa `hubUrl` bug, again). The
 *    ranked endpoint list the `local-network` cap already computes — public
@@ -760,9 +987,17 @@ var NC_ALARM_DECLARATION = {
 function pickArtifactBaseUrl(endpoints) {
 	return endpoints.filter((e) => e.kind !== "loopback").toSorted((a, b) => a.priority - b.priority)[0]?.baseUrl ?? null;
 }
-/** Sign `(id, exp)` — the exact string the verifier recomputes. */
+/**
+* Sign `(id, exp)` — the exact string the verifier recomputes.
+*
+* Delegates to the one derivation in `@camstack/types/node`. This used to
+* restate the HMAC locally, and so did the Home Assistant media plane, on the
+* correct reasoning that addons never import each other — but two copies of a
+* signing scheme is how one of them ends up with a different expiry check that
+* nothing catches.
+*/
 function signArtifact(secret, id, expMs) {
-	return (0, node_crypto.createHmac)("sha256", secret).update(`${id}:${expMs}`).digest("hex");
+	return signExpiringUrl(secret, id, expMs);
 }
 /**
 * Build the fully-qualified, signed URL for an artifact.
@@ -779,12 +1014,7 @@ function buildArtifactUrl(input) {
 * the compare so an expired link is rejected even with a valid signature.
 */
 function verifyArtifactSignature(input) {
-	if (!Number.isFinite(input.exp) || input.exp <= input.nowMs) return false;
-	const expected = signArtifact(input.secret, input.id, input.exp);
-	const a = Buffer.from(expected, "utf8");
-	const b = Buffer.from(input.sig, "utf8");
-	if (a.length !== b.length) return false;
-	return (0, node_crypto.timingSafeEqual)(a, b);
+	return verifyExpiringUrl(input);
 }
 //#endregion
 //#region src/notification-center/artifact-plane.ts
@@ -12452,23 +12682,73 @@ async function makeSquareThumb(bytes, size) {
 	}).jpeg({ quality: THUMB_QUALITY }).toBuffer();
 }
 //#endregion
+//#region src/pipeline-analytics/zone-name-stamp.ts
+/**
+* Copy each track with `zoneNames` stamped on.
+*
+* Three silences, all deliberate, all of them "say nothing" rather than "say
+* something wrong":
+*
+*  - a track that visited no zone gets NO field (an empty array on every row of
+*    a 1000-row page is pure wire cost for no information);
+*  - a zone id with no entry in the catalogue — a zone deleted since the track
+*    was written — is DROPPED. `zoneNames` is therefore not positionally
+*    aligned with `zonesVisited` and can be shorter;
+*  - a device whose catalogue could not be read at all leaves the track exactly
+*    as it arrived. A zones cap that is momentarily down must not look like a
+*    track that was never in a zone.
+*/
+function stampZoneNames(tracks, lookup) {
+	return tracks.map((track) => {
+		if (track.zonesVisited.length === 0) return track;
+		const catalogue = lookup(track.deviceId);
+		if (catalogue === null) return track;
+		const names = [];
+		for (const id of track.zonesVisited) {
+			const name = catalogue.get(id);
+			if (name !== void 0 && name.length > 0 && !names.includes(name)) names.push(name);
+		}
+		if (names.length === 0) return track;
+		return {
+			...track,
+			zoneNames: names
+		};
+	});
+}
+//#endregion
 //#region src/pipeline-analytics/analytics-query-facade.ts
 var AnalyticsQueryFacade = class {
 	deps;
 	constructor(deps) {
 		this.deps = deps;
 	}
+	/**
+	* Stamp the human `zoneNames` onto a batch of tracks.
+	*
+	* ONE place, on the read path, for every track surface — `zonesVisited` is
+	* ids and a client cannot resolve them without a per-camera fan-out. A hub
+	* with no catalogue reader configured returns the tracks untouched.
+	*/
+	async withZoneNames(tracks) {
+		const cache = this.deps.zoneCatalogue?.() ?? null;
+		if (cache === null || tracks.length === 0) return tracks;
+		const zoned = tracks.filter((t) => t.zonesVisited.length > 0);
+		if (zoned.length === 0) return tracks;
+		await cache.ensure(zoned.map((t) => t.deviceId));
+		return stampZoneNames(tracks, (deviceId) => cache.lookup(deviceId));
+	}
 	async getActiveTracks(input) {
-		return this.deps.trackStore()?.getActive(input.deviceId) ?? [];
+		return this.withZoneNames(this.deps.trackStore()?.getActive(input.deviceId) ?? []);
 	}
 	async getTrack(input) {
 		const store = this.deps.trackStore();
-		const active = store?.getActiveByTrack(input.trackId);
-		if (active) return active;
-		return await store?.getPersistedByTrackId(input.trackId) ?? null;
+		const track = store?.getActiveByTrack(input.trackId) ?? await store?.getPersistedByTrackId(input.trackId) ?? null;
+		if (track === null) return null;
+		const [named] = await this.withZoneNames([track]);
+		return named ?? track;
 	}
 	async listTracks(input) {
-		return this.deps.trackStore()?.queryHistorical(input) ?? [];
+		return this.withZoneNames(await this.deps.trackStore()?.queryHistorical(input) ?? []);
 	}
 	/**
 	* Batched cluster-wide track listing — one merged (`lastSeen` DESC,
@@ -12478,10 +12758,14 @@ var AnalyticsQueryFacade = class {
 	* indexed page + k-way merge and the cursor encoding.
 	*/
 	async listRecentTracks(input) {
-		return this.deps.trackStore()?.queryRecent(input) ?? {
+		const page = await this.deps.trackStore()?.queryRecent(input) ?? {
 			tracks: [],
 			nextCursor: null
 		};
+		return {
+			...page,
+			tracks: await this.withZoneNames(page.tracks)
+		};
 	}
 	/** Per-camera sensor-event history (state changes of linked devices). */
 	async getSensorEvents(input) {
@@ -17153,6 +17437,72 @@ var RetrainService = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/zone-catalogue-cache.ts
+/**
+* zone-catalogue-cache — the per-device zone id→name dictionary the track read
+* path stamps `zoneNames` from.
+*
+* The `zones` capability is per-device, so resolving names on a merged
+* `listRecentTracks` page would otherwise be one cap call per camera per page —
+* the exact fan-out that surface exists to remove. One read per camera per TTL
+* is the whole cost, against a catalogue that changes only when an operator
+* draws a polygon.
+*
+* The failure rule is the important part: a refresh that throws KEEPS the last
+* known catalogue. Dropping it would make every zoned track look unzoned for
+* the next minute, which reads as "zones stopped working" rather than "the
+* zones cap blipped".
+*/
+/** How long a device's zone catalogue is trusted before a re-read. A zone
+*  rename should reach the feed without a restart; a minute is invisible to an
+*  operator and reduces the read to ~16 cheap calls/min on this fleet. */
+var ZONE_CATALOGUE_TTL_MS = 6e4;
+var ZoneCatalogueCache = class {
+	deps;
+	entries = /* @__PURE__ */ new Map();
+	/** In-flight reads, so a burst of pages for the same camera makes one call. */
+	inFlight = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Make sure every device has a catalogue no older than the TTL. */
+	async ensure(deviceIds) {
+		const stale = [...new Set(deviceIds)].filter((id) => this.isStale(id));
+		await Promise.all(stale.map((id) => this.refresh(id)));
+	}
+	/** The device's zone id→name map, or null when it was never readable. */
+	lookup(deviceId) {
+		return this.entries.get(deviceId)?.names ?? null;
+	}
+	isStale(deviceId) {
+		const held = this.entries.get(deviceId);
+		if (held === void 0) return true;
+		return this.deps.now() - held.readAtMs >= ZONE_CATALOGUE_TTL_MS;
+	}
+	async refresh(deviceId) {
+		const running = this.inFlight.get(deviceId);
+		if (running !== void 0) return running;
+		const task = this.read(deviceId).finally(() => {
+			this.inFlight.delete(deviceId);
+		});
+		this.inFlight.set(deviceId, task);
+		return task;
+	}
+	async read(deviceId) {
+		try {
+			const zones = await this.deps.fetchZones(deviceId);
+			const names = /* @__PURE__ */ new Map();
+			for (const zone of zones) if (zone.id.length > 0 && zone.name.length > 0) names.set(zone.id, zone.name);
+			this.entries.set(deviceId, {
+				names,
+				readAtMs: this.deps.now()
+			});
+		} catch (error) {
+			this.deps.onError(deviceId, error);
+		}
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/media-capture-log.ts
 var DEFAULT_FLUSH_INTERVAL_MS$1 = 6e4;
 var MediaCaptureLogAggregator = class {
@@ -31006,6 +31356,27 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	*  bodies live in `analytics-query-facade.ts`; the class keeps one-line
 	*  delegates because the pipeline-analytics cap registers `this` as its
 	*  provider. Deps are lazy getters — the stores are late-bound in boot. */
+	/**
+	* Zone id→name dictionary for the track read path.
+	*
+	* `zonesVisited` persists ids; every operator-facing surface needs the name.
+	* Cached per device (see `ZoneCatalogueCache`) so a merged 1000-row page
+	* costs at most one `listZones` per camera per minute rather than one per
+	* page.
+	*/
+	zoneCatalogue = new ZoneCatalogueCache({
+		fetchZones: (deviceId) => this.ctx.api.zones.listZones.query({ deviceId }),
+		now: () => Date.now(),
+		onError: (deviceId, error) => {
+			this.ctx.logger.warn("zone catalogue read failed — zone names unresolved for this device", {
+				tags: { deviceId },
+				meta: {
+					deviceId,
+					error: require_dist.errMsg(error)
+				}
+			});
+		}
+	});
 	queryFacade = new AnalyticsQueryFacade({
 		trackStore: () => this.trackStore,
 		eventStore: () => this.eventStore,
@@ -31013,7 +31384,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		sensorEventStore: () => this.sensorEventStore,
 		opsLog: () => this.eventsOpsLog,
 		eventMediaBaseUrl: () => this.eventMediaBaseUrl,
-		logger: () => this.ctx.logger
+		logger: () => this.ctx.logger,
+		zoneCatalogue: () => this.zoneCatalogue
 	});
 	/** The shared crop extractor (native-res first, detection-frame fallback),
 	*  captured in the constructor so `processFrame` can crop object thumbnails in
@@ -31367,7 +31739,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		let storage = this.ctx.kernel.storage;
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
 		if (mediaRoot) {
-			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-DTrkngzv.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => node_exports);
 			storage = new FilesystemStorageProvider(mediaRoot, { eventMedia: mediaRoot });
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}