@camstack/addon-provider-homeassistant 1.2.639 → 1.2.640

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

@@ -1,23 +1,9 @@
-import { $t as object, Bt as baseUnitOf, Gt as isReadingQuantity, I as consumableFormOf, Jt as array, Kt as nodePin, L as consumableKindOf, O as buildAddonRouteProvider, Rt as BaseAddon, U as deviceExportCapability, a as COCO_TO_MACRO, an as EventCategory, c as ConsumableItemSchema, d as FanDirectionSchema, f as HvacModeSchema, ht as runExportedAction, i as CAMERA_SWITCH_ORDER, l as ConsumableStatusSchema, m as PLUG_APPLIANCE_TYPES, o as CameraSwitchIdSchema, p as MediaPlayerRepeatSchema, pt as pruneDeletedEntities, rn as unknown, s as ConsumableFormSchema, st as oauthIntegrationCapability, t as AlarmArmModeSchema, tn as string, v as addonRoutesCapability, xt as sendToExportedTarget } from "../dist-Cvz76AD1.mjs";
+import { B as consumableKindOf, Jt as isReadingQuantity, K as deviceExportCapability, Ut as baseUnitOf, Vt as BaseAddon, Yt as nodePin, Zt as array, _ as PLUG_APPLIANCE_TYPES, c as COCO_TO_MACRO, cn as EventCategory, d as ConsumableItemSchema, f as ConsumableStatusSchema, g as MediaPlayerRepeatSchema, gt as pruneDeletedEntities, h as HvacModeSchema, i as AlarmArmModeSchema, in as string, j as buildAddonRouteProvider, l as CameraSwitchIdSchema, m as FanDirectionSchema, nn as object, on as unknown, r as listHomeAssistantBrokers, s as CAMERA_SWITCH_ORDER, u as ConsumableFormSchema, ut as oauthIntegrationCapability, vt as runExportedAction, wt as sendToExportedTarget, x as addonRoutesCapability, z as consumableFormOf } from "../ha-broker-source-FHFpUlgq.mjs";
 import { createHmac, timingSafeEqual } from "node:crypto";
 import "node:zlib";
 import "node:fs";
 import "node:path";
 import "node:child_process";
-/** The `BrokerInfo.kind` tag the Home Assistant provider stamps. */
-var HA_BROKER_KIND = "home-assistant";
-/**
-* Every Home Assistant broker currently registered, cluster-wide.
-*
-* Unpinned by design (see the module docblock) and filtered by `kind`, which is
-* the contract check that matters: whatever mix of providers answered the
-* union, only `home-assistant` brokers are ever exported to over Home
-* Assistant's transport.
-*/
-async function listHomeAssistantBrokers(query) {
-	return (await query({})).filter((broker) => broker.kind === HA_BROKER_KIND);
-}
-//#endregion
 //#region src/ha-export/camera-function-writes.ts
 /**
 * Performs the WRITE of a camera function on the authority that owns it.
@@ -5213,12 +5199,125 @@ var HOME_ASSISTANT_OAUTH_INTEGRATION = {
 	refreshTokenTtlSec: 365 * 24 * 60 * 60
 };
 //#endregion
+//#region src/ha-export/push-failure.ts
+/**
+* Why a push to Home Assistant failed, in words an operator can act on.
+*
+* The reason used to live only in the log line's `meta.error`, which a log
+* viewer that shows the message alone never displays: an operator saw
+* "push failed, messages dropped" every 30 s for hours with nothing to act on.
+*/
+/** Where the custom component registers its push view inside HA. */
+var PUSH_PATH = "/api/camstack/push";
+var MAX_BODY_CHARS = 200;
+/** A non-2xx answer from Home Assistant's push view. */
+var PushHttpError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`Home Assistant answered ${String(status)}`);
+		this.status = status;
+		this.body = body;
+		this.name = "PushHttpError";
+	}
+};
+/** First 200 chars of a response body, with any bearer token removed. */
+function scrubBody(body) {
+	return body.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]").slice(0, MAX_BODY_CHARS);
+}
+var NETWORK_CODES = new Set([
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"ETIMEDOUT",
+	"ECONNRESET",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"EAI_AGAIN",
+	"UND_ERR_CONNECT_TIMEOUT"
+]);
+function networkCode(err) {
+	for (let current = err, depth = 0; current instanceof Error && depth < 4; depth += 1) {
+		const code = Reflect.get(current, "code");
+		if (typeof code === "string" && NETWORK_CODES.has(code)) return code;
+		current = current.cause;
+	}
+}
+function describePushFailure(err) {
+	if (err instanceof PushHttpError) {
+		const http = `HTTP ${String(err.status)}`;
+		if (err.status === 404) return {
+			kind: "component-missing",
+			permanent: true,
+			text: `${http} — Home Assistant has no CamStack integration installed (the ${PUSH_PATH} endpoint is missing). Install it from HACS, or turn off Home Assistant export`
+		};
+		if (err.status === 401 || err.status === 403) return {
+			kind: "token-rejected",
+			permanent: false,
+			text: `${http} — Home Assistant rejected the access token (revoked, or the user lacks rights); create a new long-lived token`
+		};
+		if (err.status === 413) return {
+			kind: "too-large",
+			permanent: false,
+			text: `${http} — the batch is too large for Home Assistant or a proxy in front of it`
+		};
+		const body = scrubBody(err.body);
+		return {
+			kind: "other",
+			permanent: false,
+			text: body.length > 0 ? `${http} — ${body}` : http
+		};
+	}
+	const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+	const code = networkCode(err);
+	const fetchFailed = err instanceof TypeError && err.message === "fetch failed";
+	if (timedOut || code !== void 0 || fetchFailed) return {
+		kind: "unreachable",
+		permanent: false,
+		text: `Home Assistant is unreachable (${timedOut ? "timed out" : code ?? "network error"}) — check the address and that it is running`
+	};
+	return {
+		kind: "other",
+		permanent: false,
+		text: err instanceof Error ? err.message : String(err)
+	};
+}
+/**
+* POST one message to Home Assistant's push view.
+*
+* Authenticated with the broker's OWN long-lived token: the component
+* registers its view behind HA auth, so there is no second shared secret
+* to configure or rotate. A non-2xx throws `PushHttpError` carrying the first
+* 200 chars of the body (never the request headers), which is how the push
+* client learns why the instance is not taking the push.
+*/
+async function postToHomeAssistant(baseUrl, token, message) {
+	const response = await fetch(`${baseUrl.replace(/\/+$/, "")}${PUSH_PATH}`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify(message),
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (!response.ok) {
+		const body = await response.text().catch(() => "");
+		throw new PushHttpError(response.status, scrubBody(body));
+	}
+}
+//#endregion
 //#region src/ha-export/push-client.ts
 /** How long state updates accumulate before one POST carries them all. */
 var BATCH_FLUSH_MS = 1e3;
 /** Availability cadence. The component's timeout is a multiple of this. */
 var HEARTBEAT_INTERVAL_MS = 3e4;
 var IMAGE_SIGNAL_PREFIX = "__image_updated__:";
+/**
+* How long a permanent failure (a missing component) is left alone before the
+* next probe. A 404 does not heal by retrying; it heals when the operator
+* installs the component, which the settings-change reset picks up at once.
+*/
+var COMPONENT_RECHECK_MS = 10 * 6e4;
 /** Rate limit for the "HA is not answering" warning. */
 var DROP_LOG_INTERVAL_MS = 3e4;
 var PushClient = class {
@@ -5235,6 +5334,8 @@ var PushClient = class {
 	dropped = 0;
 	droppedLoggedAt = 0;
 	disposed = false;
+	lastFailure = null;
+	suspendedUntil = 0;
 	constructor(options) {
 		this.transport = options.transport;
 		this.logger = options.logger;
@@ -5245,6 +5346,18 @@ var PushClient = class {
 	get healthy() {
 		return this.available;
 	}
+	/** Why the last push failed; `null` while the link is healthy. */
+	get failure() {
+		return this.lastFailure;
+	}
+	/** A permanent failure is being left alone until the next probe. */
+	get suspended() {
+		return this.suspendedUntil > Date.now();
+	}
+	/** Probe again at once — the operator changed something. */
+	resetBackoff() {
+		this.suspendedUntil = 0;
+	}
 	/** Messages discarded because HA did not answer. Never silent. */
 	get droppedCount() {
 		return this.dropped;
@@ -5320,11 +5433,29 @@ var PushClient = class {
 	}
 	/** `true` when Home Assistant took the message. */
 	async send(message) {
+		if (this.suspended) {
+			this.dropped += message.type === "batch" ? message.items.length : 1;
+			return false;
+		}
 		try {
 			await this.transport(message);
 			this.onReachable();
 			return true;
 		} catch (err) {
+			if (err instanceof PushHttpError && err.status === 413 && message.type === "batch") {
+				const half = Math.ceil(message.items.length / 2);
+				if (message.items.length > 1) {
+					const first = await this.send({
+						type: "batch",
+						items: message.items.slice(0, half)
+					});
+					const second = await this.send({
+						type: "batch",
+						items: message.items.slice(half)
+					});
+					return first && second;
+				}
+			}
 			this.onUnreachable(message, err);
 			return false;
 		}
@@ -5332,6 +5463,8 @@ var PushClient = class {
 	onReachable() {
 		if (this.available) return;
 		this.available = true;
+		this.lastFailure = null;
+		this.suspendedUntil = 0;
 		/**
 		* The link came back. Drop the dedup cache so the reconcile that
 		* follows re-pushes every value: HA may have restarted and lost its
@@ -5369,14 +5502,18 @@ var PushClient = class {
 	*/
 	onUnreachable(message, err) {
 		this.available = false;
+		const failure = describePushFailure(err);
+		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 (now - this.droppedLoggedAt < DROP_LOG_INTERVAL_MS) return;
 		this.droppedLoggedAt = now;
-		this.logger.warn("ha-export: push to Home Assistant failed, messages dropped", { meta: {
+		this.logger.warn(`ha-export: push to Home Assistant failed (${failure.text}), messages dropped`, { meta: {
 			brokerId: this.brokerId,
 			dropped: this.dropped,
 			messageType: message.type,
+			failureKind: failure.kind,
 			error: err instanceof Error ? err.message : String(err)
 		} });
 	}
@@ -6942,8 +7079,6 @@ var SUPPORTED_DEVICE_KINDS = [
 *     one switch per broker over the single membership store.
 */
 var ADDON_ID = "homeassistant-export";
-/** Where the custom component registers its push view inside HA. */
-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;
@@ -7166,6 +7301,7 @@ var HaExportAddon = class extends BaseAddon {
 		];
 	}
 	async onConfigChanged() {
+		for (const link of this.links.values()) link.client.resetBackoff();
 		await this.reconcile("config-changed");
 		this.startTimer();
 	}
@@ -7848,7 +7984,9 @@ var HaExportAddon = class extends BaseAddon {
 			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)) {
+			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) {
 				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");
@@ -9190,7 +9328,7 @@ var HaExportAddon = class extends BaseAddon {
 				id: "ha-export-brokers",
 				title: "Home Assistant instances",
 				titleKey: "provider-homeassistant:globalSettings.s_ha-export-brokers.title",
-				description: brokerFields.length > 0 ? "An instance that is off receives nothing; its exported devices resume when it is turned back on." : "No Home Assistant broker is registered yet.",
+				description: brokerFields.length > 0 ? "An instance that is off receives nothing; its exported devices resume when it is turned back on. Export needs the CamStack custom component installed in Home Assistant (HACS)." : "No Home Assistant broker is registered yet.",
 				columns: 1,
 				fields: brokerFields.length > 0 ? brokerFields : [{
 					type: "info",
@@ -9324,16 +9462,21 @@ var HaExportAddon = class extends BaseAddon {
 	buildStatus() {
 		const enabled = this.enabledBrokerIds();
 		const healthy = [...this.links.values()].filter((link) => link.client.healthy).length;
+		const linkFailure = [...this.links.values()].map((link) => link.client.failure).filter((failure) => failure !== null)[0]?.text;
 		return {
 			linkState: enabled.length === 0 ? "unlinked" : healthy === this.links.size ? "linked" : "error",
 			exposedDeviceCount: exposedDeviceIds(this.config.membership, enabled).length,
-			...this.lastError !== void 0 ? { error: this.lastError } : {},
+			...linkFailure !== void 0 ? { error: linkFailure } : this.lastError !== void 0 ? { error: this.lastError } : {},
 			setup: {
 				fields: [
 					{
 						label: "Home Assistant instances",
 						value: `${healthy} / ${this.links.size} reachable`
 					},
+					{
+						label: "Last push failure",
+						value: linkFailure ?? "none"
+					},
 					{
 						label: "Entities pushed",
 						value: String(this.entityCount)
@@ -9368,26 +9511,6 @@ var HaExportAddon = class extends BaseAddon {
 * CAPABILITIES, not its type, and restricting the picker by type is what
 * confined the previous exporter to cameras.
 */
-/**
-* POST one message to Home Assistant's push view.
-*
-* Authenticated with the broker's OWN long-lived token: the component
-* registers its view behind HA auth, so there is no second shared secret
-* to configure or rotate. A non-2xx throws, which is how the push client
-* learns the instance is unreachable.
-*/
-async function postToHomeAssistant(baseUrl, token, message) {
-	const response = await fetch(`${baseUrl.replace(/\/+$/, "")}${PUSH_PATH}`, {
-		method: "POST",
-		headers: {
-			authorization: `Bearer ${token}`,
-			"content-type": "application/json"
-		},
-		body: JSON.stringify(message),
-		signal: AbortSignal.timeout(1e4)
-	});
-	if (!response.ok) throw new Error(`Home Assistant answered ${response.status}`);
-}
 function randomSecret() {
 	const bytes = new Uint8Array(32);
 	crypto.getRandomValues(bytes);

package/i18n/en.json

@@ -22,7 +22,7 @@
   "contribution.s_ha-export.title": "Home Assistant",
   "haConfig.s_connection.title": "Home Assistant notify",
   "haConfig.s_connection.service.label": "Notify service",
-  "haConfig.s_connection.service.description": "The part after `notify.` (e.g. `mobile_app_pixel_7`); use Discover to list them.",
+  "haConfig.s_connection.service.description": "Loaded from the broker once it is picked. If the list does not load, type the part after `notify.`.",
   "haConfig.s_connection.brokerId.label": "Broker",
-  "haConfig.s_connection.brokerId.description": "Optional; blank uses the only configured broker."
+  "haConfig.s_connection.brokerId.description": "The Home Assistant connection the notification goes through."
 }

package/i18n/it.json

@@ -22,7 +22,7 @@
   "contribution.s_ha-export.title": "Home Assistant",
   "haConfig.s_connection.title": "Notifica Home Assistant",
   "haConfig.s_connection.service.label": "Servizio di notifica",
-  "haConfig.s_connection.service.description": "La parte dopo `notify.` (es. `mobile_app_pixel_7`); usa Discover per elencarli.",
+  "haConfig.s_connection.service.description": "Caricato dal broker una volta scelto. Se l'elenco non si carica, scrivi la parte dopo `notify.`.",
   "haConfig.s_connection.brokerId.label": "Broker",
-  "haConfig.s_connection.brokerId.description": "Facoltativo; se vuoto usa l'unico broker configurato."
+  "haConfig.s_connection.brokerId.description": "La connessione Home Assistant attraverso cui passa la notifica."
 }

package/package.json

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