@camstack/addon-provider-homeassistant 1.2.15 → 1.2.17

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

@@ -1,4 +1,4 @@
-import { Ct as EventCategory, O as deviceExportCapability, c as addonRoutesCapability, i as CameraSwitchIdSchema, r as COCO_TO_MACRO, st as BaseAddon, v as buildAddonRouteProvider, yt as string } from "../dist-DdyXnBOa.mjs";
+import { Ct as EventCategory, O as deviceExportCapability, c as addonRoutesCapability, i as CameraSwitchIdSchema, r as COCO_TO_MACRO, st as BaseAddon, v as buildAddonRouteProvider, yt as string } from "../dist-reK3lvnr.mjs";
 import { createHmac, timingSafeEqual } from "node:crypto";
 //#region src/ha-export/topics.ts
 /**
@@ -125,21 +125,25 @@ var ZONE_MACROS = [
 	"animal"
 ];
 /**
-* ~73 entities per camera with 3 zones. Only the ones people automate on
-* arrive enabled; everything else is registered and switched off, for the
-* operator to enable when they want it.
+* `enabled_by_default: false` is a DECISION, taken per entity, never
+* inferred from its name or its platform.
+*
+* It used to be inferred — a name-and-platform heuristic written for the
+* camera catalog (`endsWith('_detected')`, `platform === 'switch'`) and
+* then applied to every device the catalog builds. On a camera it is
+* right: three zones is ~73 entities and the fleet is ~880, so only what
+* an operator automates on arrives enabled. On a DERIVED device it was
+* simply wrong — every sensor, every number and the alarm panel matched
+* nothing and shipped switched off, so a temperature sensor exported its
+* temperature disabled and the operator found the thing they installed
+* the integration for turned off. Measured on the live hub, the whole
+* derived half is **228 entities across 115 devices — 2 on average, 3 at
+* most**: there is no fan-out there to protect against.
+*
+* So the flag is a required field on every spec. A new entity — or the
+* synthetic devices the design addendum still owes — cannot inherit a
+* camera's pressure valve by accident.
 */
-var ENABLED_BY_DEFAULT_SUFFIXES = ["detected"];
-var ENABLED_BY_DEFAULT_ENTITIES = [
-	"triggered",
-	"online",
-	"last_image"
-];
-function isEnabledByDefault(entity, platform) {
-	if (platform === "switch" || platform === "button" || platform === "select") return true;
-	if (ENABLED_BY_DEFAULT_ENTITIES.includes(entity)) return true;
-	return ENABLED_BY_DEFAULT_SUFFIXES.some((suffix) => entity.endsWith(`_${suffix}`));
-}
 /**
 * The snooze surface, as a `select`.
 *
@@ -175,7 +179,6 @@ var PTZ_BUTTONS = [
 ];
 function buildComponent(device, spec) {
 	const deviceKey = deviceKeyFor(device.stableId);
-	const enabled = isEnabledByDefault(spec.entity, spec.platform);
 	return {
 		platform: spec.platform,
 		unique_id: `${device.stableId}_${spec.uniqueSuffix ?? spec.entity}`,
@@ -187,7 +190,7 @@ function buildComponent(device, spec) {
 		...spec.icon !== void 0 ? { icon: spec.icon } : {},
 		...spec.options !== void 0 ? { options: spec.options } : {},
 		...spec.entityCategory !== void 0 ? { entity_category: spec.entityCategory } : {},
-		...enabled ? {} : { enabled_by_default: false },
+		...spec.enabledByDefault ? {} : { enabled_by_default: false },
 		...spec.platform === "binary_sensor" || spec.platform === "switch" ? {
 			payload_on: "true",
 			payload_off: "false"
@@ -203,6 +206,11 @@ function deviceBlock(device) {
 		mdl: device.model ?? device.type
 	};
 }
+/**
+* The fan-out, and the reason the valve exists: zones × zone-macros × 4.
+* The detector is what an operator automates on; the other three are
+* detail they can switch on per entity.
+*/
 function zoneSpecs(zone) {
 	const slug = toSlug(zone.id);
 	const specs = [];
@@ -213,24 +221,28 @@ function zoneSpecs(zone) {
 			platform: "binary_sensor",
 			label: `${label} detected`,
 			uniqueSuffix: `${zone.id}_${macro}_detected`,
-			deviceClass: "motion"
+			deviceClass: "motion",
+			enabledByDefault: true
 		}, {
 			entity: `${slug}_${macro}_last_image`,
 			platform: "image",
 			label: `${label} last image`,
-			uniqueSuffix: `${zone.id}_${macro}_last_image`
+			uniqueSuffix: `${zone.id}_${macro}_last_image`,
+			enabledByDefault: false
 		}, {
 			entity: `${slug}_${macro}_last_detection`,
 			platform: "sensor",
 			label: `${label} last detection`,
 			uniqueSuffix: `${zone.id}_${macro}_last_detection`,
-			deviceClass: "timestamp"
+			deviceClass: "timestamp",
+			enabledByDefault: false
 		}, {
 			entity: `${slug}_${macro}_objects`,
 			platform: "sensor",
 			label: `${label} objects`,
 			uniqueSuffix: `${zone.id}_${macro}_objects`,
-			icon: "mdi:counter"
+			icon: "mdi:counter",
+			enabledByDefault: false
 		});
 	}
 	return specs;
@@ -241,26 +253,30 @@ function cameraSpecs(device) {
 			entity: "triggered",
 			platform: "binary_sensor",
 			label: "Triggered",
-			deviceClass: "motion"
+			deviceClass: "motion",
+			enabledByDefault: true
 		},
 		{
 			entity: "online",
 			platform: "binary_sensor",
 			label: "Online",
 			deviceClass: "connectivity",
-			entityCategory: "diagnostic"
+			entityCategory: "diagnostic",
+			enabledByDefault: true
 		},
 		{
 			entity: "last_image",
 			platform: "image",
-			label: "Last image"
+			label: "Last image",
+			enabledByDefault: true
 		},
 		{
 			entity: "last_detection",
 			platform: "sensor",
 			label: "Last detection",
 			deviceClass: "timestamp",
-			icon: "mdi:clock"
+			icon: "mdi:clock",
+			enabledByDefault: false
 		}
 	];
 	if (device.slices.includes("battery")) specs.push({
@@ -269,18 +285,21 @@ function cameraSpecs(device) {
 		label: "Battery",
 		deviceClass: "battery",
 		unit: "%",
-		entityCategory: "diagnostic"
+		entityCategory: "diagnostic",
+		enabledByDefault: false
 	}, {
 		entity: "charger",
 		platform: "binary_sensor",
 		label: "Charging",
 		deviceClass: "battery_charging",
-		entityCategory: "diagnostic"
+		entityCategory: "diagnostic",
+		enabledByDefault: false
 	}, {
 		entity: "sleeping",
 		platform: "binary_sensor",
 		label: "Sleeping",
-		entityCategory: "diagnostic"
+		entityCategory: "diagnostic",
+		enabledByDefault: false
 	});
 	/**
 	* One HA switch per AVAILABLE camera switch, rendered from
@@ -298,28 +317,32 @@ function cameraSpecs(device) {
 			entity: toSlug(sw.id),
 			platform: "switch",
 			label: sw.label,
-			writable: true
+			writable: true,
+			enabledByDefault: true
 		});
 	}
 	if (device.features.includes("rebootable")) specs.push({
 		entity: "reboot",
 		platform: "button",
 		label: "Reboot",
-		writable: true
+		writable: true,
+		enabledByDefault: true
 	});
 	if (device.boundCaps.includes("ptz")) {
 		for (const entity of PTZ_BUTTONS) specs.push({
 			entity,
 			platform: "button",
 			label: humanise(entity),
-			writable: true
+			writable: true,
+			enabledByDefault: true
 		});
 		specs.push({
 			entity: "ptz_preset",
 			platform: "select",
 			label: "PTZ preset",
 			writable: true,
-			options: device.ptzPresets ?? []
+			options: device.ptzPresets ?? [],
+			enabledByDefault: true
 		});
 	}
 	specs.push({
@@ -327,7 +350,8 @@ function cameraSpecs(device) {
 		platform: "select",
 		label: "Snooze notifications",
 		writable: true,
-		options: SNOOZE_OPTIONS
+		options: SNOOZE_OPTIONS,
+		enabledByDefault: true
 	});
 	for (const macro of EXPORTED_MACROS) {
 		const label = humanise(macro);
@@ -335,22 +359,26 @@ function cameraSpecs(device) {
 			entity: `${macro}_detected`,
 			platform: "binary_sensor",
 			label: `${label} detected`,
-			deviceClass: "motion"
+			deviceClass: "motion",
+			enabledByDefault: true
 		}, {
 			entity: `${macro}_last_image`,
 			platform: "image",
-			label: `${label} last image`
+			label: `${label} last image`,
+			enabledByDefault: false
 		}, {
 			entity: `${macro}_last_detection`,
 			platform: "sensor",
 			label: `${label} last detection`,
-			deviceClass: "timestamp"
+			deviceClass: "timestamp",
+			enabledByDefault: false
 		});
 		if (LABELLED_MACROS.includes(macro)) specs.push({
 			entity: `${macro}_last_label`,
 			platform: "sensor",
 			label: `${label} last label`,
-			icon: "mdi:tag"
+			icon: "mdi:tag",
+			enabledByDefault: false
 		});
 	}
 	for (const zone of device.zones) specs.push(...zoneSpecs(zone));
@@ -535,6 +563,22 @@ var CAPS_NOT_EXPORTED = [
 	{
 		cap: "reboot",
 		reason: "Rendered as a button, gated on the `rebootable` feature rather than the binding."
+	},
+	{
+		cap: "device-status",
+		reason: "Auto-registered by BaseDevice on EVERY device, so it would add an entity to all of them; availability is already the heartbeat, per device."
+	},
+	{
+		cap: "feature-probe",
+		reason: "The runtime truth about what a device CAN do — it decides which entities exist, so exporting it as one would be circular."
+	},
+	{
+		cap: "device-ops",
+		reason: "The per-device operations envelope; its members surface individually (e.g. reboot)."
+	},
+	{
+		cap: "device-discovery",
+		reason: "Adoption-time only — it describes candidates, never the state of an adopted device."
 	}
 ];
 /** A capability in neither list — the thing the guard exists to surface. */
@@ -542,14 +586,28 @@ function unclassifiedCaps(caps) {
 	const known = new Set([...Object.keys(CAP_ENTITY_MAP), ...CAPS_NOT_EXPORTED.map((e) => e.cap)]);
 	return [...new Set(caps)].filter((cap) => !known.has(cap)).sort();
 }
-/** The derived half: every non-camera kind, from the caps it declares. */
+/**
+* The derived half: every non-camera kind, from the caps it declares.
+*
+* **Everything here arrives ENABLED**, and that is the rule rather than
+* an oversight in the other direction. A cap-derived entity IS the reason
+* the device exists — a temperature sensor's temperature, a light's
+* brightness, an alarm panel's state — and there is no fan-out to
+* protect against: measured on the live hub, 115 non-camera devices
+* produce 228 entities, 2 per device on average and 3 at most, because a
+* device declares one or two mapped caps and the rest of its bindings
+* (`device-status`, `feature-probe`, `device-ops`) carry no entity at
+* all. The camera valve is for 73-per-device; this is not that problem,
+* and exporting the operator's temperature switched off was the bug.
+*/
 function buildDerivedPlan(device) {
 	const specs = [{
 		entity: "online",
 		platform: "binary_sensor",
 		label: "Online",
 		deviceClass: "connectivity",
-		entityCategory: "diagnostic"
+		entityCategory: "diagnostic",
+		enabledByDefault: true
 	}];
 	for (const cap of device.boundCaps) {
 		const mapping = CAP_ENTITY_MAP[cap];
@@ -558,6 +616,7 @@ function buildDerivedPlan(device) {
 			entity: toSlug(cap),
 			platform: mapping.platform,
 			label: humanise(cap),
+			enabledByDefault: true,
 			...mapping.deviceClass !== void 0 ? { deviceClass: mapping.deviceClass } : {},
 			...mapping.unit !== void 0 ? { unit: mapping.unit } : {},
 			...mapping.writable === true ? { writable: true } : {}
@@ -674,6 +733,59 @@ function resolveCommand(target, entity, value) {
 	}
 	return null;
 }
+/**
+* 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 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 timingSafeEqual(a, b);
+}
 //#endregion
 //#region src/ha-export/media-url.ts
 /**
@@ -686,18 +798,23 @@ function resolveCommand(target, entity, value) {
 *
 * The link is signed rather than protected by a session, because the
 * fetcher is HA's own frontend or a phone — neither of which holds a
-* camstack token. This mirrors the notification artifact plane's scheme
-* (that module lives in another addon and addons never import each other,
-* so the crypto is restated here rather than reached for).
+* camstack token.
 *
-* Expiry is checked BEFORE the constant-time compare: an expired link is
-* refused whether or not its signature is valid, so a leaked URL stops
-* working on its own.
+* The HMAC itself is NOT restated here. It used to be — this module and the
+* notification artifact plane each carried their own copy, because addons never
+* import each other and neither could reach the other's. That reasoning was
+* right and the conclusion was wrong: both now delegate to the single
+* derivation in `@camstack/types/node`, which every addon may depend on. What
+* stays local is policy — the TTL below, and the id this plane signs.
+*
+* Expiry is checked BEFORE the constant-time compare (in the shared verifier):
+* an expired link is refused whether or not its signature is valid, so a leaked
+* URL stops working on its own.
 */
 /** How long a minted link stays valid. Long enough for HA to render it. */
 var MEDIA_URL_TTL_MS = 360 * 60 * 1e3;
 function signMedia(secret, id, expMs) {
-	return createHmac("sha256", secret).update(`${id}:${expMs}`).digest("hex");
+	return signExpiringUrl(secret, id, expMs);
 }
 function buildMediaUrl(input) {
 	const base = input.baseUrl.replace(/\/+$/, "");
@@ -705,13 +822,7 @@ function buildMediaUrl(input) {
 	return `${base}${input.routePrefix}/${encodeURIComponent(input.id)}?exp=${input.expMs}&sig=${sig}`;
 }
 function verifyMediaSignature(input) {
-	if (input.exp === void 0 || input.sig === void 0) return false;
-	const expMs = Number(input.exp);
-	if (!Number.isFinite(expMs)) return false;
-	if (expMs < input.nowMs) return false;
-	const expected = signMedia(input.secret, input.id, expMs);
-	if (expected.length !== input.sig.length) return false;
-	return timingSafeEqual(Buffer.from(expected), Buffer.from(input.sig));
+	return verifyExpiringUrl(input);
 }
 //#endregion
 //#region src/ha-export/membership.ts
@@ -768,6 +879,7 @@ var PushClient = class {
 	transport;
 	logger;
 	brokerId;
+	onLinkRestored;
 	/** topic → last value SENT. Dropped whenever the link is lost. */
 	stateCache = /* @__PURE__ */ new Map();
 	buffer = [];
@@ -781,6 +893,7 @@ var PushClient = class {
 		this.transport = options.transport;
 		this.logger = options.logger;
 		this.brokerId = options.brokerId;
+		this.onLinkRestored = options.onLinkRestored;
 	}
 	/** `false` once a POST has failed, `true` again on the next success. */
 	get healthy() {
@@ -882,6 +995,21 @@ var PushClient = class {
 		} });
 		this.dropped = 0;
 		this.droppedLoggedAt = 0;
+		/**
+		* Signalled AFTER the cache is gone and BEFORE anything else is sent:
+		* the handler re-announces from inside this call, and a cache that
+		* still held the old values would dedup away exactly those messages.
+		* The handler's own failure is its business — it can never take the
+		* transport, or the runner, down with it (D29).
+		*/
+		try {
+			this.onLinkRestored?.(this.brokerId);
+		} catch (err) {
+			this.logger.warn("ha-export: the re-announce handler threw, link is up but not repaired", { meta: {
+				brokerId: this.brokerId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
 	}
 	/**
 	* A failed POST discards work, so it may not be silent — an operator
@@ -903,6 +1031,48 @@ var PushClient = class {
 		} });
 	}
 };
+var ReachabilityReconciler = class {
+	options;
+	minIntervalMs;
+	timer = null;
+	lastRunAt = null;
+	pending = /* @__PURE__ */ new Set();
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+		this.minIntervalMs = options.minIntervalMs ?? 3e4;
+	}
+	/** One link came back. Ask for a full re-announce. */
+	request(brokerId) {
+		if (this.disposed) return;
+		this.pending.add(brokerId);
+		if (this.timer !== null) return;
+		const sinceLast = this.lastRunAt === null ? Number.POSITIVE_INFINITY : Date.now() - this.lastRunAt;
+		const delayMs = Math.max(0, this.minIntervalMs - sinceLast);
+		this.options.onScheduled?.({
+			brokerId,
+			delayMs
+		});
+		this.timer = setTimeout(() => {
+			this.timer = null;
+			this.fire();
+		}, delayMs);
+	}
+	dispose() {
+		this.disposed = true;
+		if (this.timer !== null) clearTimeout(this.timer);
+		this.timer = null;
+		this.pending.clear();
+	}
+	fire() {
+		if (this.disposed) return;
+		const brokerIds = [...this.pending].sort();
+		this.pending.clear();
+		if (brokerIds.length === 0) return;
+		this.lastRunAt = Date.now();
+		this.options.run({ brokerIds });
+	}
+};
 //#endregion
 //#region src/ha-export/state-projector.ts
 /**
@@ -1160,9 +1330,32 @@ var HaExportAddon = class extends BaseAddon {
 	mediaBaseUrl = null;
 	reconcileTimer = null;
 	reconcileInFlight = false;
+	/** A reason asked for while one was running. Re-run, never dropped. */
+	reconcilePending = null;
 	lastError;
 	entityCount = 0;
 	unclassified = [];
+	/**
+	* A link that returned repairs NOW, not at the next periodic pass.
+	*
+	* `PushClient` drops its dedup cache the moment Home Assistant answers
+	* again; without this, nothing re-sent anything and every entity sat
+	* blank for up to `reconcileIntervalSec` (300s). Bounded and coalesced,
+	* because the answer is the COMPLETE `cmps` set plus every value for
+	* every exported device — see `reachability-reconcile.ts`.
+	*/
+	reachability = new ReachabilityReconciler({
+		onScheduled: ({ brokerId, delayMs }) => {
+			this.ctx.logger.info("ha-export: Home Assistant link returned, re-announcing everything", { meta: {
+				brokerId,
+				inMs: delayMs
+			} });
+		},
+		run: ({ brokerIds }) => {
+			this.reconcile("link-restored");
+			this.ctx.logger.debug("ha-export: re-announce triggered by a returning link", { meta: { brokers: [...brokerIds] } });
+		}
+	});
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -1185,6 +1378,7 @@ var HaExportAddon = class extends BaseAddon {
 		this.startTimer();
 		this.ctx.addDisposer(async () => {
 			this.stopTimer();
+			this.reachability.dispose();
 			for (const link of this.links.values()) await link.client.dispose();
 			this.links.clear();
 		});
@@ -1404,10 +1598,35 @@ var HaExportAddon = class extends BaseAddon {
 	* Re-resolves the brokers, rebuilds every plan, re-sends the COMPLETE
 	* `cmps` set for every exported device, and re-pushes every value.
 	* Events are an optimisation over this, never a substitute (D8/D11).
+	*
+	* A reconcile asked for while one is running is RE-RUN after it, never
+	* dropped. It used to be dropped, and silently: a link that returned
+	* mid-pass cleared its dedup cache and then lost the only re-announce
+	* that would have refilled it, which is the exact defect this addon
+	* just fixed, arriving through a different door.
 	*/
 	async reconcile(reason) {
-		if (this.reconcileInFlight) return;
+		if (this.reconcileInFlight) {
+			this.reconcilePending = reason;
+			this.ctx.logger.debug("ha-export: a reconcile is already running, re-running after it", { meta: { reason } });
+			return;
+		}
 		this.reconcileInFlight = true;
+		try {
+			let next = reason;
+			while (next !== null) {
+				const current = next;
+				this.reconcilePending = null;
+				await this.runReconcile(current);
+				next = this.reconcilePending;
+			}
+		} finally {
+			this.reconcileInFlight = false;
+			this.reconcilePending = null;
+		}
+	}
+	/** One pass. Never throws: a failure degrades this pass and no more. */
+	async runReconcile(reason) {
 		const startedAt = Date.now();
 		try {
 			await this.refreshBrokers();
@@ -1492,8 +1711,6 @@ var HaExportAddon = class extends BaseAddon {
 		} catch (err) {
 			this.lastError = errMsg(err);
 			this.ctx.logger.warn("ha-export: reconcile failed", { meta: { error: this.lastError } });
-		} finally {
-			this.reconcileInFlight = false;
 		}
 	}
 	/**
@@ -1689,7 +1906,8 @@ var HaExportAddon = class extends BaseAddon {
 			const client = new PushClient({
 				transport: (message) => postToHomeAssistant(resolved.baseUrl, resolved.token, message),
 				logger: this.ctx.logger,
-				brokerId: broker.id
+				brokerId: broker.id,
+				onLinkRestored: (brokerId) => this.reachability.request(brokerId)
 			});
 			client.start();
 			this.links.set(broker.id, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-homeassistant",
-  "version": "1.2.15",
+  "version": "1.2.17",
   "description": "Home Assistant device provider addon for CamStack",
   "keywords": [
     "camstack",