@camstack/addon-provider-homeassistant 1.2.601 → 1.2.603

package/dist/ha-export/ha-export.addon.js

@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_dist = require("../dist-BXMUyWXo.js");
+const require_dist = require("../dist-DVNChk7-.js");
 let node_crypto = require("node:crypto");
 require("node:zlib");
 let node_fs = require("node:fs");
@@ -3223,6 +3223,10 @@ var CAPS_NOT_EXPORTED = [
 	{
 		cap: "zone-rules",
 		reason: "Per-stage zone rules — configuration the pipeline consumes, with no value an automation reads."
+	},
+	{
+		cap: "heating-valve",
+		reason: "Radiator valve position telemetry (0–100 %). Shown on the CamStack thermostat row; no Home Assistant / voice-assistant entity mapping is defined yet — export would mint a sensor with no agreed device_class or control surface."
 	}
 ];
 var UNNEGOTIATED_PLAN_OPTIONS = { platforms: UNNEGOTIATED_SUPPORT };
@@ -4763,14 +4767,15 @@ var PushClient = class {
 	* is flushed first — a value for an entity HA has not built yet is a
 	* value it discards.
 	*/
-	async publishEntityChange(deviceKey, cmps, dev) {
-		if (this.disposed) return;
+	async publishEntityChange(deviceKey, cmps, dev, full = false) {
+		if (this.disposed) return false;
 		await this.flush();
-		await this.send({
+		return this.send({
 			type: "entity_change",
 			device_id: deviceKey,
 			cmps,
-			dev
+			dev,
+			...full ? { full: true } : {}
 		});
 	}
 	/** Send everything buffered now. Called before any structure change. */
@@ -4787,12 +4792,15 @@ var PushClient = class {
 			items
 		});
 	}
+	/** `true` when Home Assistant took the message. */
 	async send(message) {
 		try {
 			await this.transport(message);
 			this.onReachable();
+			return true;
 		} catch (err) {
 			this.onUnreachable(message, err);
+			return false;
 		}
 	}
 	onReachable() {
@@ -4906,6 +4914,130 @@ function shouldSkipAnnounce(reason, fingerprint, lastFingerprint) {
 	return reason === "structure-changed" && fingerprint === lastFingerprint;
 }
 //#endregion
+//#region src/ha-export/held-reads.ts
+var ReadMirror = class {
+	keyOf;
+	entries = /* @__PURE__ */ new Map();
+	constructor(keyOf) {
+		this.keyOf = keyOf;
+	}
+	resolve(deviceId, outcome) {
+		const entry = this.entries.get(deviceId);
+		if (outcome.kind === "failed") {
+			if (entry === void 0) return {
+				status: "unknown",
+				reason: outcome.reason
+			};
+			return {
+				status: "held-failed",
+				items: entry.confirmed,
+				reason: outcome.reason
+			};
+		}
+		if (entry === void 0) {
+			this.entries.set(deviceId, {
+				confirmed: outcome.items,
+				pendingDrop: null
+			});
+			return {
+				status: "fresh",
+				items: outcome.items
+			};
+		}
+		const incoming = new Set(outcome.items.map(this.keyOf));
+		const dropped = entry.confirmed.map(this.keyOf).filter((key) => !incoming.has(key)).toSorted();
+		if (dropped.length === 0) {
+			entry.confirmed = outcome.items;
+			entry.pendingDrop = null;
+			return {
+				status: "fresh",
+				items: outcome.items
+			};
+		}
+		const vote = dropped.join("\0");
+		if (entry.pendingDrop === vote) {
+			entry.confirmed = outcome.items;
+			entry.pendingDrop = null;
+			return {
+				status: "fresh",
+				items: outcome.items
+			};
+		}
+		entry.pendingDrop = vote;
+		return {
+			status: "held-removal",
+			items: entry.confirmed,
+			reason: `an answered read dropped ${dropped.join(", ")}; waiting for a second answer to agree`
+		};
+	}
+};
+/**
+* The async sources `readCameraFunctions` could not obtain, or `null` when
+* every one answered. Their absence turns a function switch into "not
+* available", which removes its entity — a failure must not look like that.
+* `brokerAudioMuted` is only a read at all when the camera has a source node,
+* and `privacy` is a snapshot slice (absent = the cap is not there).
+*/
+function cameraFunctionReadsFailed(reads, sourceNodeId) {
+	const failed = [];
+	if (reads.bindableCapNames === null) failed.push("bindableCapNames");
+	if (reads.wrappedCapNames === null) failed.push("wrappedCapNames");
+	if (reads.recordingEnabled === null) failed.push("recordingEnabled");
+	if (reads.notificationsMuted === null) failed.push("notificationsMuted");
+	if (sourceNodeId !== null && reads.brokerAudioMuted === null) failed.push("brokerAudioMuted");
+	return failed.length === 0 ? null : `did not answer: ${failed.join(", ")}`;
+}
+//#endregion
+//#region src/ha-export/resync-gate.ts
+/**
+* When the exporter must send a FULL authoritative announce rather than let an
+* unchanged structure short-circuit.
+*
+* A gap is any moment after which the hub can no longer vouch for what Home
+* Assistant holds: the first pass after a start (the receiver may have been
+* running while this addon was down), a broker link that was just opened, an
+* announce or state push that was not delivered. The next pass after a gap is
+* a full resync, once, whatever its reason — an event-debounced pass included,
+* which would otherwise skip on an identical fingerprint and leave the
+* receiver unrepaired until the periodic pass.
+*
+* Passes for 'boot', 'link-restored' and 'periodic' are full by their nature.
+*/
+/** Reasons whose pass is a full resync whether or not a gap was noted. */
+var ALWAYS_FULL = new Set([
+	"boot",
+	"link-restored",
+	"periodic"
+]);
+var ResyncGate = class {
+	gap = true;
+	lastReason = "start";
+	/** Note that the receiver may be out of step; the next pass will be full. */
+	markGap(reason) {
+		this.gap = true;
+		this.lastReason = reason;
+	}
+	/** `true` while a gap is waiting for a pass. */
+	pending() {
+		return this.gap;
+	}
+	/** Why the gap was opened (for the log line). */
+	gapReason() {
+		return this.gap ? this.lastReason : null;
+	}
+	/**
+	* Called once at the start of a pass. Returns whether the pass is a full
+	* resync and consumes the gap noted so far; a gap noted DURING the pass is
+	* kept for the next one.
+	*/
+	take(reason) {
+		const full = this.gap || ALWAYS_FULL.has(reason);
+		this.gap = false;
+		this.lastReason = null;
+		return full;
+	}
+};
+//#endregion
 //#region src/ha-export/rule-triggers.ts
 function reduceOne(row) {
 	return {
@@ -5960,9 +6092,9 @@ function projectSynthetic(input, nowMs) {
 			topic: stateTopic(srv, `${slug}_memory`),
 			value: String(Math.round(node.memoryPercent))
 		});
-		if (node.online && node.uptime > 0) values.push({
+		if (node.online && node.uptimeMs > 0) values.push({
 			topic: stateTopic(srv, `${slug}_uptime`),
-			value: (/* @__PURE__ */ new Date(nowMs - node.uptime * 1e3)).toISOString()
+			value: new Date(nowMs - node.uptimeMs).toISOString()
 		});
 		if (node.footageUsedBytes !== null) values.push({
 			topic: stateTopic(srv, `${slug}_footage_used_bytes`),
@@ -6028,6 +6160,8 @@ var PUSH_PATH = "/api/camstack/push";
 var MEDIA_ROUTE_PREFIX = `/addon/${ADDON_ID}/ha-media`;
 /** How long `doorbell_pressed` stays on before its OFF edge is published. */
 var DOORBELL_PULSE_MS = 5e3;
+/** How soon a pass with a held-back read is retried. */
+var READ_RETRY_MS = 3e4;
 /**
 * The earliest timestamp a real change could plausibly carry. Below this,
 * a slice field is a placeholder or a seeded "known value, unknown change
@@ -6074,6 +6208,24 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 	* still holds through the periodic pass.
 	*/
 	lastStructureFingerprint;
+	/**
+	* When the next pass must be a FULL authoritative announce (`full: true` on
+	* the wire) whatever the fingerprint says: a start, a new broker link, an
+	* undelivered push, a failed pass. See `resync-gate.ts`.
+	*/
+	resync = new ResyncGate();
+	/**
+	* The last EXPORTED set of each part of a device's component set. A read
+	* that failed (or a provider not registered yet) holds it; a shrink needs
+	* two agreeing answers. See `held-reads.ts`.
+	*/
+	boundCapsMirror = new ReadMirror((cap) => cap);
+	zonesMirror = new ReadMirror((zone) => zone.id);
+	streamsMirror = new ReadMirror((stream) => stream.id);
+	presetsMirror = new ReadMirror((preset) => preset);
+	switchesMirror = new ReadMirror((fn) => fn.id);
+	/** A held-back read is retried soon, not at the next 300 s pass. */
+	readTimer = null;
 	entityCount = 0;
 	/** deviceId → the `lastPressedAt` already rung, so a re-read does not ring again. */
 	lastDoorbellPressAt = /* @__PURE__ */ new Map();
@@ -6150,6 +6302,8 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 			for (const timer of this.doorbellReleaseTimers.values()) clearTimeout(timer);
 			this.doorbellReleaseTimers.clear();
 			this.reachability.dispose();
+			if (this.readTimer !== null) clearTimeout(this.readTimer);
+			this.readTimer = null;
 			for (const link of this.links.values()) await link.client.dispose();
 			this.links.clear();
 		});
@@ -6622,6 +6776,8 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 		const startedAt = Date.now();
 		try {
 			await this.refreshBrokers();
+			const fullResync = this.resync.take(reason);
+			let readsHeld = false;
 			await this.refreshMediaBaseUrl();
 			await this.refreshComponentSupport();
 			const enabled = this.enabledBrokerIds();
@@ -6684,16 +6840,22 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 				* used to call the deprecated `getCameraSwitches` separately for the
 				* same answer.
 				*/
-				const cameraFunctions = device.type === "camera" ? deriveCameraFunctions(await this.readCameraFunctions({
+				const sourceNodeId = this.cameraStatusByDeviceId.get(numericId)?.assignment.sourceNodeId ?? null;
+				const functionReads = device.type === "camera" ? await this.readCameraFunctions({
 					deviceId: numericId,
 					deviceType: device.type,
 					deviceDisabled: device.disabled,
 					privacySlice: toSnapshot(snapshots[String(numericId)])["privacy-mask"],
-					sourceNodeId: this.cameraStatusByDeviceId.get(numericId)?.assignment.sourceNodeId ?? null,
+					sourceNodeId,
 					bindableCapsByType,
 					mutedDeviceIds
-				})) : null;
-				const catalogDevice = await this.buildCatalogDevice(device, snapshots[String(numericId)], cameraFunctions);
+				}) : null;
+				const cameraFunctions = functionReads !== null ? deriveCameraFunctions(functionReads) : null;
+				const functionsFailure = functionReads !== null ? cameraFunctionReadsFailed(functionReads, sourceNodeId) : null;
+				const built = await this.buildCatalogDevice(device, snapshots[String(numericId)], cameraFunctions, functionsFailure);
+				if (built.heldBack) readsHeld = true;
+				const catalogDevice = built.device;
+				if (catalogDevice === null) continue;
 				for (const cap of catalogDevice.boundCaps) allCaps.add(cap);
 				const brokerIds = brokersExposing(this.config.membership, deviceIdStr).filter((id) => enabled.includes(id));
 				/**
@@ -6764,7 +6926,8 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 			this.entityCount = entityCount;
 			this.unclassified = unclassifiedCaps([...allCaps]);
 			const fingerprint = structureFingerprint(exported);
-			if (shouldSkipAnnounce(reason, fingerprint, this.lastStructureFingerprint)) {
+			if (readsHeld) this.scheduleReadRetry();
+			if (!fullResync && shouldSkipAnnounce(reason, fingerprint, this.lastStructureFingerprint)) {
 				this.ctx.logger.debug("ha-export: structure unchanged, skipping announce", { meta: {
 					devices: exported.size,
 					entities: entityCount
@@ -6782,11 +6945,17 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 					entities: line.entities
 				}
 			});
-			await this.announce(exported);
+			const delivered = await this.announce(exported, fullResync);
 			await this.pushFullState(exported, snapshots);
 			if (synthetic !== null) await this.pushSynthetic(projectSynthetic(synthetic, Date.now()), [...enabled]);
+			if (!delivered || [...this.links.values()].some((link) => !link.client.healthy)) {
+				this.resync.markGap("push-not-delivered");
+				this.lastStructureFingerprint = void 0;
+				this.ctx.logger.warn("ha-export: a push was not delivered, the next pass is a full resync");
+			}
 			this.ctx.logger.info("ha-export: reconciled", { meta: {
 				reason,
+				fullResync,
 				brokers: enabled.length,
 				devices: exported.size,
 				entities: entityCount,
@@ -6797,6 +6966,7 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 			this.lastError = void 0;
 		} catch (err) {
 			this.lastError = errMsg(err);
+			this.resync.markGap("reconcile-failed");
 			this.ctx.logger.warn("ha-export: reconcile failed", { meta: { error: this.lastError } });
 		}
 	}
@@ -6995,7 +7165,7 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 					online: node.isOnline,
 					cpuPercent: node.cpuPercent,
 					memoryPercent: node.memoryPercent,
-					uptime: node.uptime,
+					uptimeMs: node.uptime,
 					isHub: node.isHub,
 					footageUsedBytes: footage.footageUsedBytes,
 					footageFreePercent: footage.footageFreePercent,
@@ -7014,13 +7184,16 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 			for (const value of values) link.client.publishState(value.topic, value.value);
 		}
 	}
-	async announce(exported) {
+	/** `false` when any announce was not delivered. */
+	async announce(exported, full) {
+		let allDelivered = true;
 		for (const entry of exported.values()) for (const brokerId of entry.brokerIds) {
 			const link = this.links.get(brokerId);
 			if (link === void 0) continue;
 			try {
-				await link.client.publishEntityChange(entry.plan.deviceKey, entry.plan.cmps, entry.plan.dev);
+				if (!await link.client.publishEntityChange(entry.plan.deviceKey, entry.plan.cmps, entry.plan.dev, full)) allDelivered = false;
 			} catch (err) {
+				allDelivered = false;
 				this.ctx.logger.warn("ha-export: could not announce a device, skipping it", {
 					tags: { deviceId: entry.deviceId },
 					meta: {
@@ -7030,6 +7203,7 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 				});
 			}
 		}
+		return allDelivered;
 	}
 	async pushFullState(exported, snapshots) {
 		for (const entry of exported.values()) try {
@@ -7147,46 +7321,105 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 		}
 		return values;
 	}
-	async buildCatalogDevice(device, snapshotRaw, cameraFunctions) {
+	/**
+	* `device: null` = a part of this device's component set cannot be read and
+	* nothing was ever exported for it, so the device is not announced this pass
+	* (an empty part would make Home Assistant delete what it holds). `heldBack`
+	* = at least one part is not a fresh answer, so a retry is worth arming.
+	*/
+	async buildCatalogDevice(device, snapshotRaw, cameraFunctions, functionsFailure) {
 		const snapshot = toSnapshot(snapshotRaw);
-		const boundCaps = await this.loadBoundCaps(device.id);
-		const zones = device.type === "camera" ? await this.loadZones(device.id) : [];
+		let heldBack = false;
+		let unknown = false;
+		const settle = (part, mirror, outcome) => {
+			const resolution = mirror.resolve(device.id, outcome);
+			if (resolution.status !== "fresh") heldBack = true;
+			if (resolution.status === "unknown") unknown = true;
+			this.logHeldRead(device.id, part, resolution);
+			return resolution.status === "unknown" ? [] : resolution.items;
+		};
+		const boundCaps = settle("boundCaps", this.boundCapsMirror, await this.loadBoundCaps(device.id));
+		const zones = device.type === "camera" ? settle("zones", this.zonesMirror, await this.loadZones(device.id)) : [];
 		/**
 		* Every camera function, available or not — `entity-catalog.ts` is the
 		* one place that filters to `available`, exactly as it did for
-		* `getCameraSwitches`'s answer.
+		* `getCameraSwitches`'s answer. A function that did not answer is
+		* "unavailable", which removes its entity, so the set goes through the
+		* mirror: held when a source failed, shrunk only on two agreeing passes.
 		*/
-		const switches = (cameraFunctions ?? []).map((fn) => ({
+		const mappedSwitches = (cameraFunctions ?? []).map((fn) => ({
 			id: fn.id,
 			label: fn.label,
 			available: fn.available
 		}));
-		const ptzPresets = device.type === "camera" && boundCaps.includes("ptz") ? await this.loadPresets(device.id) : [];
-		const streams = device.type === "camera" && boundCaps.includes("webrtc-session") ? await this.loadStreamChoices(device.id) : [];
+		const switches = cameraFunctions === null ? mappedSwitches : settle("cameraFunctions", this.switchesMirror, functionsFailure !== null ? {
+			kind: "failed",
+			reason: functionsFailure
+		} : {
+			kind: "answered",
+			items: mappedSwitches.filter((fn) => fn.available)
+		});
+		const ptzPresets = device.type === "camera" ? settle("ptzPresets", this.presetsMirror, boundCaps.includes("ptz") ? await this.loadPresets(device.id) : {
+			kind: "answered",
+			items: []
+		}) : [];
+		const streams = device.type === "camera" ? settle("streams", this.streamsMirror, boundCaps.includes("webrtc-session") ? await this.loadStreamChoices(device.id) : {
+			kind: "answered",
+			items: []
+		}) : [];
+		if (unknown) return {
+			device: null,
+			heldBack
+		};
 		const manufacturer = readString(device.metadata ?? {}, "manufacturer");
 		const model = readString(device.metadata ?? {}, "model");
 		return {
-			id: device.id,
-			name: device.name,
-			type: device.type,
-			...manufacturer !== null ? { manufacturer } : {},
-			...model !== null ? { model } : {},
-			features: device.features,
-			boundCaps,
-			zones,
-			switches,
-			ptzPresets,
-			streams,
-			slices: Object.keys(snapshot),
-			/**
-			* The slice VALUES, for the native platforms only: a native
-			* `climate` announces the modes the device accepts, and
-			* `availableModes` is on the slice and nowhere else. See
-			* `CatalogDevice.capSlices`.
-			*/
-			capSlices: snapshot
+			device: {
+				id: device.id,
+				name: device.name,
+				type: device.type,
+				...manufacturer !== null ? { manufacturer } : {},
+				...model !== null ? { model } : {},
+				features: device.features,
+				boundCaps,
+				zones,
+				switches,
+				ptzPresets,
+				streams,
+				slices: Object.keys(snapshot),
+				/**
+				* The slice VALUES, for the native platforms only: a native
+				* `climate` announces the modes the device accepts, and
+				* `availableModes` is on the slice and nowhere else. See
+				* `CatalogDevice.capSlices`.
+				*/
+				capSlices: snapshot
+			},
+			heldBack
 		};
 	}
+	/** One WARN per held part, with the device tag and the reason. */
+	logHeldRead(deviceId, part, resolution) {
+		if (resolution.status === "fresh") return;
+		const kept = resolution.status === "unknown" ? 0 : resolution.items.length;
+		const message = resolution.status === "unknown" ? "ha-export: a read did not answer and nothing was exported yet, the device is not announced this pass" : resolution.status === "held-failed" ? "ha-export: a read did not answer, keeping the last exported components" : "ha-export: a read dropped components, keeping them until a second answer agrees";
+		this.ctx.logger.warn(message, {
+			tags: { deviceId },
+			meta: {
+				part,
+				reason: resolution.reason,
+				kept
+			}
+		});
+	}
+	/** Retry soon after a held-back read: the provider usually registers seconds later. */
+	scheduleReadRetry() {
+		if (this.readTimer !== null) return;
+		this.readTimer = setTimeout(() => {
+			this.readTimer = null;
+			this.reconcile("read-retry");
+		}, READ_RETRY_MS);
+	}
 	/**
 	* Every stream of the camera, as the hub's own picker lists them.
 	*
@@ -7204,45 +7437,54 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 	*/
 	async loadStreamChoices(deviceId) {
 		try {
-			return (await this.ctx.api.webrtcSession.listStreams.query({ deviceId })).map((choice) => ({
-				id: choice.id,
-				label: choice.label,
-				target: choice.target,
-				...choice.resolution === null ? {} : { height: choice.resolution.height }
-			}));
+			return {
+				kind: "answered",
+				items: (await this.ctx.api.webrtcSession.listStreams.query({ deviceId })).map((choice) => ({
+					id: choice.id,
+					label: choice.label,
+					target: choice.target,
+					...choice.resolution === null ? {} : { height: choice.resolution.height }
+				}))
+			};
 		} catch (err) {
-			this.ctx.logger.warn("ha-export: could not read the camera streams, no camera entity", {
-				tags: { deviceId },
-				meta: { error: errMsg(err) }
-			});
-			return [];
+			return {
+				kind: "failed",
+				reason: errMsg(err)
+			};
 		}
 	}
 	async loadBoundCaps(deviceId) {
 		try {
-			return (await this.ctx.api.deviceManager.getBindings.query({ deviceId })).entries.map((entry) => entry.capName);
+			return {
+				kind: "answered",
+				items: (await this.ctx.api.deviceManager.getBindings.query({ deviceId })).entries.map((entry) => entry.capName)
+			};
 		} catch (err) {
-			this.ctx.logger.warn("ha-export: could not read bindings, exporting without them", {
-				tags: { deviceId },
-				meta: { error: errMsg(err) }
-			});
-			return [];
+			return {
+				kind: "failed",
+				reason: errMsg(err)
+			};
 		}
 	}
 	async loadZones(deviceId) {
 		try {
 			const snapshot = await this.ctx.api.zoneAnalytics.getCurrentSnapshot.query({ deviceId });
-			if (snapshot === null) return [];
-			return snapshot.zones.map((zone) => ({
-				id: zone.zoneId,
-				name: zone.zoneName
-			}));
+			if (snapshot === null) return {
+				kind: "answered",
+				items: []
+			};
+			return {
+				kind: "answered",
+				items: snapshot.zones.map((zone) => ({
+					id: zone.zoneId,
+					name: zone.zoneName
+				}))
+			};
 		} catch (err) {
-			this.ctx.logger.warn("ha-export: could not read zones, exporting no zone entities", {
-				tags: { deviceId },
-				meta: { error: errMsg(err) }
-			});
-			return [];
+			return {
+				kind: "failed",
+				reason: errMsg(err)
+			};
 		}
 	}
 	/**
@@ -7361,14 +7603,19 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 	async loadPresets(deviceId) {
 		try {
 			const device = await this.ctx.fetchDevice(deviceId);
-			if (device.ptz === void 0) return [];
-			return (await device.ptz.getPresets({})).map((preset) => preset.name);
+			if (device.ptz === void 0) return {
+				kind: "answered",
+				items: []
+			};
+			return {
+				kind: "answered",
+				items: (await device.ptz.getPresets({})).map((preset) => preset.name)
+			};
 		} catch (err) {
-			this.ctx.logger.debug("ha-export: could not probe PTZ presets", {
-				tags: { deviceId },
-				meta: { error: errMsg(err) }
-			});
-			return [];
+			return {
+				kind: "failed",
+				reason: errMsg(err)
+			};
 		}
 	}
 	/**
@@ -7447,6 +7694,7 @@ var HaExportAddon = class extends require_dist.BaseAddon {
 				onLinkRestored: (brokerId) => this.reachability.request(brokerId)
 			});
 			client.start();
+			this.resync.markGap("broker-connected");
 			this.links.set(broker.id, {
 				brokerId: broker.id,
 				name: broker.name,