@camstack/addon-provider-homeassistant 1.2.649 → 1.2.651

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_ha_broker_source = require("../ha-broker-source-CE3nHkyW.js");
+const require_ha_broker_source = require("../ha-broker-source-D4_TtF2V.js");
 let node_crypto = require("node:crypto");
 require("node:zlib");
 let node_fs = require("node:fs");
@@ -975,19 +975,22 @@ var NATIVE_CAP_PLATFORMS = {
 	*/
 	cover: {
 		platform: "cover",
+		availableWhenOnline: true,
 		primary: { from: null },
 		controls: {
 			position: {
 				from: "position",
 				min: 0,
 				max: 100,
-				step: 1
+				step: 1,
+				requiresFeature: "cover-positionable"
 			},
 			tilt: {
 				from: "tilt",
 				min: 0,
 				max: 100,
-				step: 1
+				step: 1,
+				requiresFeature: "cover-tilt"
 			},
 			open: {
 				from: "open",
@@ -999,7 +1002,8 @@ var NATIVE_CAP_PLATFORMS = {
 			},
 			stop: {
 				from: "stop",
-				commandOnly: true
+				commandOnly: true,
+				requiresFeature: "cover-stoppable"
 			}
 		}
 	},
@@ -1388,9 +1392,11 @@ function buildNativeComponent(input) {
 	if (native === void 0) return null;
 	const primary = resolveBinding(input, native.primary);
 	if (primary === null) return null;
+	const features = input.features ?? [];
 	const absorbed = new Set([derivedEntityId(input.capName), ...primary.entities]);
 	const controls = {};
 	for (const [name, binding] of Object.entries(native.controls ?? {})) {
+		if (binding.requiresFeature !== void 0 && !features.includes(binding.requiresFeature)) continue;
 		const resolved = resolveBinding(input, binding);
 		if (resolved === null) continue;
 		controls[name] = resolved.control;
@@ -1409,6 +1415,11 @@ function buildNativeComponent(input) {
 			...primary.control,
 			...native.deviceClass !== void 0 ? { device_class: native.deviceClass } : {},
 			...native.icon !== void 0 ? { icon: native.icon } : {},
+			...native.availableWhenOnline === true ? {
+				availability_topic: stateTopic(input.deviceKey, "online"),
+				payload_available: "true",
+				payload_not_available: "false"
+			} : {},
 			...Object.keys(controls).length > 0 ? { controls } : {},
 			...native.constants,
 			...flags
@@ -2343,7 +2354,8 @@ var CAP_ENTITY_MAP = {
 				unit: "%",
 				icon: "mdi:arrow-up-down",
 				writable: true,
-				range: PERCENT_RANGE
+				range: PERCENT_RANGE,
+				requiresFeature: "cover-positionable"
 			},
 			tilt: {
 				platform: "number",
@@ -2353,7 +2365,8 @@ var CAP_ENTITY_MAP = {
 				icon: "mdi:angle-acute",
 				writable: true,
 				range: PERCENT_RANGE,
-				enabledByDefault: false
+				enabledByDefault: false,
+				requiresFeature: "cover-tilt"
 			}
 		},
 		commands: {
@@ -2368,7 +2381,8 @@ var CAP_ENTITY_MAP = {
 			stop: {
 				label: "Stop",
 				icon: "mdi:stop",
-				enabledByDefault: false
+				enabledByDefault: false,
+				requiresFeature: "cover-stoppable"
 			}
 		}
 	},
@@ -3375,7 +3389,8 @@ function capEntities(capName) {
 	for (const [suffix, extra] of Object.entries(mapping.extras ?? {})) refs.push({
 		entity: derivedExtraEntityId(capName, suffix),
 		label: extra.label,
-		descriptor: extra
+		descriptor: extra,
+		...extra.requiresFeature !== void 0 ? { requiresFeature: extra.requiresFeature } : {}
 	});
 	return refs;
 }
@@ -3394,8 +3409,9 @@ function deriveCapValue(derivation, raw) {
 	return derivation.kind === "equals" ? raw === derivation.value : raw !== derivation.value;
 }
 /** A capability's entities as the catalog builders consume them. */
-function capEntitySpecs(capName) {
-	const specs = capEntities(capName).map((ref) => ({
+function capEntitySpecs(capName, features = []) {
+	const declared = (required) => required === void 0 || features.includes(required);
+	const specs = capEntities(capName).filter((ref) => declared(ref.requiresFeature)).map((ref) => ({
 		entity: ref.entity,
 		platform: ref.descriptor.platform,
 		label: ref.label,
@@ -3408,15 +3424,18 @@ function capEntitySpecs(capName) {
 		...ref.descriptor.entityCategory !== void 0 ? { entityCategory: ref.descriptor.entityCategory } : {},
 		...ref.descriptor.writable === true ? { writable: true } : {}
 	}));
-	for (const ref of capCommandEntities(capName)) specs.push({
-		entity: ref.entity,
-		platform: "button",
-		label: ref.label,
-		enabledByDefault: ref.command.enabledByDefault ?? true,
-		writable: true,
-		...ref.command.icon !== void 0 ? { icon: ref.command.icon } : {},
-		...ref.command.entityCategory !== void 0 ? { entityCategory: ref.command.entityCategory } : {}
-	});
+	for (const ref of capCommandEntities(capName)) {
+		if (!declared(ref.command.requiresFeature)) continue;
+		specs.push({
+			entity: ref.entity,
+			platform: "button",
+			label: ref.label,
+			enabledByDefault: ref.command.enabledByDefault ?? true,
+			writable: true,
+			...ref.command.icon !== void 0 ? { icon: ref.command.icon } : {},
+			...ref.command.entityCategory !== void 0 ? { entityCategory: ref.command.entityCategory } : {}
+		});
+	}
 	return specs;
 }
 function readControlOptions(slice) {
@@ -3794,11 +3813,12 @@ function buildDerivedPlan(device, options = UNNEGOTIATED_PLAN_OPTIONS) {
 			deviceId: device.id,
 			capName: cap,
 			label: humanise(cap),
+			features: device.features,
 			slice: device.capSlices?.[cap],
 			mapping
 		});
 		if (plan === null) {
-			specs.push(...capEntitySpecs(cap).map((spec) => degradeUnsupported(spec, options)));
+			specs.push(...capEntitySpecs(cap, device.features).map((spec) => degradeUnsupported(spec, options)));
 			continue;
 		}
 		native[toComponentKey(plan.component.platform, derivedEntityId(cap))] = plan.component;
@@ -3809,7 +3829,7 @@ function buildDerivedPlan(device, options = UNNEGOTIATED_PLAN_OPTIONS) {
 		* to make the device look tidy would be a silent loss of a value an
 		* operator already automates on.
 		*/
-		specs.push(...capEntitySpecs(cap).filter((spec) => !plan.absorbed.has(spec.entity)));
+		specs.push(...capEntitySpecs(cap, device.features).filter((spec) => !plan.absorbed.has(spec.entity)));
 	}
 	const assembled = assemble(device, specs);
 	return {
@@ -4671,6 +4691,15 @@ function isCameraCommand(command) {
 function isCapCommand(command) {
 	return !isCameraCommand(command);
 }
+var APPLIED = { ok: true };
+/** The 422 body of a command that was not applied: the reason travels with it. */
+function commandNotAppliedBody(refusal) {
+	return {
+		error: "command not applied",
+		reason: refusal.reason,
+		...refusal.message !== void 0 ? { message: refusal.message } : {}
+	};
+}
 /**
 * Make the call the command names.
 *
@@ -5462,6 +5491,10 @@ var PushClient = class {
 	disposed = false;
 	lastFailure = null;
 	suspendedUntil = 0;
+	/** When the current unbroken streak of 404s began; 0 when there is none. */
+	first404At = 0;
+	/** A suspension was entered and not yet logged as left. */
+	suspensionLogged = false;
 	constructor(options) {
 		this.transport = options.transport;
 		this.logger = options.logger;
@@ -5480,9 +5513,20 @@ var PushClient = class {
 	get suspended() {
 		return this.suspendedUntil > Date.now();
 	}
+	/** Epoch ms of the next probe while suspended; 0 otherwise. */
+	get recheckAt() {
+		return this.suspended ? this.suspendedUntil : 0;
+	}
 	/** Probe again at once — the operator changed something. */
 	resetBackoff() {
 		this.suspendedUntil = 0;
+		this.first404At = 0;
+		this.logSuspensionEnded("reset by a settings change");
+	}
+	logSuspensionEnded(why) {
+		if (!this.suspensionLogged) return;
+		this.suspensionLogged = false;
+		this.logger.info(`ha-export: push link no longer suspended (${why}), probing again`, { meta: { brokerId: this.brokerId } });
 	}
 	/** Messages discarded because HA did not answer. Never silent. */
 	get droppedCount() {
@@ -5563,8 +5607,13 @@ var PushClient = class {
 			this.dropped += message.type === "batch" ? message.items.length : 1;
 			return false;
 		}
+		if (this.suspendedUntil !== 0 && !this.suspended) {
+			this.suspendedUntil = 0;
+			this.logSuspensionEnded("recheck time reached");
+		}
 		try {
 			await this.transport(message);
+			this.first404At = 0;
 			this.onReachable();
 			return true;
 		} catch (err) {
@@ -5591,6 +5640,7 @@ var PushClient = class {
 		this.available = true;
 		this.lastFailure = null;
 		this.suspendedUntil = 0;
+		this.logSuspensionEnded("Home Assistant answered");
 		/**
 		* The link came back. Drop the dedup cache so the reconcile that
 		* follows re-pushes every value: HA may have restarted and lost its
@@ -5628,11 +5678,29 @@ var PushClient = class {
 	*/
 	onUnreachable(message, err) {
 		this.available = false;
-		const failure = describePushFailure(err);
+		const now = Date.now();
+		const described = describePushFailure(err);
+		let failure = described;
+		if (described.kind === "component-missing") {
+			if (this.first404At === 0) this.first404At = now;
+			if (now - this.first404At < 6e4) failure = {
+				kind: "other",
+				permanent: false,
+				text: "HTTP 404 — Home Assistant has not registered the CamStack endpoint (yet); retrying"
+			};
+		} else this.first404At = 0;
 		this.lastFailure = failure;
-		if (failure.permanent) this.suspendedUntil = Date.now() + COMPONENT_RECHECK_MS;
 		this.dropped += message.type === "batch" ? message.items.length : 1;
-		const now = Date.now();
+		if (failure.permanent) {
+			this.suspendedUntil = now + COMPONENT_RECHECK_MS;
+			this.suspensionLogged = true;
+			this.logger.warn(`ha-export: push link SUSPENDED (${failure.text}); next probe at ${new Date(this.suspendedUntil).toISOString()}`, { meta: {
+				brokerId: this.brokerId,
+				failureKind: failure.kind,
+				recheckAt: this.suspendedUntil,
+				recheckInMs: COMPONENT_RECHECK_MS
+			} });
+		}
 		if (now - this.droppedLoggedAt < DROP_LOG_INTERVAL_MS) return;
 		this.droppedLoggedAt = now;
 		this.logger.warn(`ha-export: push to Home Assistant failed (${failure.text}), messages dropped`, { meta: {
@@ -5644,6 +5712,19 @@ var PushClient = class {
 		} });
 	}
 };
+//#endregion
+//#region src/ha-export/link-gaps.ts
+/** A parked link is reported, never silently excluded. */
+function summariseLinkGaps(links) {
+	return {
+		failing: links.filter((l) => !l.healthy && !l.suspended).map((l) => l.brokerId),
+		suspended: links.filter((l) => l.suspended).map((l) => ({
+			brokerId: l.brokerId,
+			recheckAt: l.recheckAt
+		})),
+		anyLive: links.some((l) => !l.suspended)
+	};
+}
 var ReachabilityReconciler = class {
 	options;
 	minIntervalMs;
@@ -8115,13 +8196,21 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 			const delivered = await this.announce(exported, fullResync);
 			await this.pushFullState(exported, snapshots);
 			if (synthetic !== null) await this.pushSynthetic(projectSynthetic(synthetic, Date.now()), [...enabled]);
-			const failing = [...this.links.values()].filter((link) => !link.client.healthy && !link.client.suspended);
-			const anyLive = [...this.links.values()].some((link) => !link.client.suspended);
-			if (failing.length > 0 || !delivered && anyLive) {
+			const gaps = summariseLinkGaps([...this.links.entries()].map(([brokerId, link]) => ({
+				brokerId,
+				healthy: link.client.healthy,
+				suspended: link.client.suspended,
+				recheckAt: link.client.recheckAt
+			})));
+			if (gaps.failing.length > 0 || !delivered && gaps.anyLive) {
 				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");
 			}
+			if (gaps.suspended.length > 0) this.ctx.logger.warn("ha-export: push links suspended, Home Assistant receives nothing", { meta: { suspended: gaps.suspended.map((s) => ({
+				brokerId: s.brokerId,
+				recheckAt: new Date(s.recheckAt).toISOString()
+			})) } });
 			this.ctx.logger.info("ha-export: reconciled", { meta: {
 				reason,
 				fullResync,
@@ -8129,6 +8218,7 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 				devices: exported.size,
 				entities: entityCount,
 				unclassifiedCaps: this.unclassified.length,
+				suspendedLinks: gaps.suspended.length,
 				durationMs: Date.now() - startedAt
 			} });
 			if (this.unclassified.length > 0) this.ctx.logger.warn("ha-export: capabilities in neither the map nor the exclusion list", { meta: { caps: this.unclassified } });
@@ -9168,9 +9258,23 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 			reply.send({ error: `unroutable command (${resolution.reason})` });
 			return;
 		}
-		const applied = await this.dispatch(resolution.command);
-		reply.status(applied ? 200 : 422);
-		reply.send(applied ? {} : { error: "command not applied" });
+		const outcome = await this.dispatch(resolution.command);
+		if (outcome.ok) {
+			reply.status(200);
+			reply.send({});
+			return;
+		}
+		this.ctx.logger.warn("ha-export: command answered 422", {
+			tags: { deviceId: exported.deviceId },
+			meta: {
+				topic,
+				entity: parsed.entity,
+				reason: outcome.reason,
+				message: outcome.message
+			}
+		});
+		reply.status(422);
+		reply.send(commandNotAppliedBody(outcome));
 	}
 	async dispatch(command) {
 		try {
@@ -9184,7 +9288,7 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 			*/
 			if (isCapCommand(command)) {
 				const outcome = await applyCapCommand(await this.ctx.fetchDevice(command.deviceId), command);
-				if (outcome.ok) return true;
+				if (outcome.ok) return APPLIED;
 				if (outcome.reason === "no-provider") return this.noProvider(command.deviceId, outcome.capName);
 				this.ctx.logger.warn("ha-export: the device refused the command", {
 					tags: { deviceId: command.deviceId },
@@ -9194,7 +9298,11 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 						...outcome.error !== void 0 ? { error: outcome.error } : {}
 					}
 				});
-				return false;
+				return {
+					ok: false,
+					reason: outcome.reason,
+					...outcome.error !== void 0 ? { message: outcome.error } : {}
+				};
 			}
 			switch (command.kind) {
 				case "camera-function": {
@@ -9204,7 +9312,11 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 							tags: { deviceId: command.deviceId },
 							meta: { switchId: command.switchId }
 						});
-						return false;
+						return {
+							ok: false,
+							reason: "unknown-function",
+							message: "the switch id is not a camera function"
+						};
 					}
 					/**
 					* A FRESH read for this one device — the pass-level caches are up to
@@ -9214,7 +9326,11 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 					const device = await this.ctx.api.deviceManager.getDevice.query({ deviceId: command.deviceId });
 					if (device === null) {
 						this.ctx.logger.warn("ha-export: dropping a camera-function command, the device is not in the registry", { tags: { deviceId: command.deviceId } });
-						return false;
+						return {
+							ok: false,
+							reason: "device-not-found",
+							message: "the device is not in the registry"
+						};
 					}
 					const privacySlice = await this.ctx.api.deviceState.getCapSlice.query({
 						deviceId: command.deviceId,
@@ -9250,22 +9366,26 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 							tags: { deviceId: command.deviceId },
 							meta: { switchId: parsed.data }
 						});
-						return false;
+						return {
+							ok: false,
+							reason: "function-unavailable",
+							message: "the camera function is not available"
+						};
 					}
 					await applyCameraFunctionWrite(this.ctx.api, command.deviceId, write, sourceNodeId);
-					return true;
+					return APPLIED;
 				}
 				case "reboot": {
 					const device = await this.ctx.fetchDevice(command.deviceId);
 					if (device.reboot === void 0) return this.noProvider(command.deviceId, "reboot");
 					await device.reboot.reboot({});
-					return true;
+					return APPLIED;
 				}
 				case "ptz-move": {
 					const device = await this.ctx.fetchDevice(command.deviceId);
 					if (device.ptz === void 0) return this.noProvider(command.deviceId, "ptz");
 					await device.ptz.move(PTZ_MOVE_BY_DIRECTION[command.direction] ?? {});
-					return true;
+					return APPLIED;
 				}
 				case "ptz-preset": {
 					const device = await this.ctx.fetchDevice(command.deviceId);
@@ -9276,10 +9396,14 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 							tags: { deviceId: command.deviceId },
 							meta: { preset: command.preset }
 						});
-						return false;
+						return {
+							ok: false,
+							reason: "no-such-preset",
+							message: "no preset by that name"
+						};
 					}
 					await device.ptz.goToPreset({ presetId: preset.id });
-					return true;
+					return APPLIED;
 				}
 			}
 		} catch (err) {
@@ -9295,7 +9419,11 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 					error: errMsg(err)
 				}
 			});
-			return false;
+			return {
+				ok: false,
+				reason: "error",
+				message: errMsg(err)
+			};
 		}
 	}
 	/** A cap the device does not provide. Refused, and never silently. */
@@ -9304,7 +9432,11 @@ var HaExportAddon = class extends require_ha_broker_source.BaseAddon {
 			tags: { deviceId },
 			meta: { capName }
 		});
-		return false;
+		return {
+			ok: false,
+			reason: "no-provider",
+			message: `the device has no provider for ${capName}`
+		};
 	}
 	/**
 	* A public, signed, expiring route Home Assistant can fetch bytes from.