@camstack/addon-provider-homeassistant 1.2.632 → 1.2.634

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.634] - 2026-10-28
+
+### Changed
+
+- Device value fields are named after their quantity instead of their unit; run the quantity-field migration after updating
+
+## [1.2.633] - 2026-10-27
+
+### Changed
+
+- Shown as "Home Assistant" (was "Home Assistant Provider").
+
+## [1.2.632] - 2026-10-27
+
 ### Added
 
-- Package README and changelog, included in the published files list.
+- Home Assistant: Home Assistant device provider addon for CamStack.
+- Provides the addons Home Assistant, Home Assistant Export.

package/README.md

@@ -1,22 +1,42 @@
-# @camstack/addon-provider-homeassistant
+# Home Assistant
 
-Home Assistant device provider addon for CamStack
+Home Assistant device provider addon for CamStack. Device provider (import) + native entity export (push). Two addons, one bundle, separate processes.
 
-## What it does
+<!-- readme:generated:start (derived from the manifest; edit outside this block) -->
 
-- **Home Assistant Provider** (`provider-homeassistant`): Adopt Home Assistant devices into CamStack via WebSocket
-  - Node placement: `hub-only`.
+Package `@camstack/addon-provider-homeassistant` on npm.
+
+## What it provides
+
+- **Home Assistant** (`provider-homeassistant`): Adopt Home Assistant devices into CamStack via WebSocket. Category: messaging.
   - Capabilities: `broker`, `device-adoption`, `vacuum-control`, `lawn-mower-control`, `running-state`, `valve`, `humidifier`, `water-heater`, `weather`, `image`, `update`, `notification-output`, `addon-routes`, `calendar-source`.
-- **Home Assistant Export** (`homeassistant-export`): Pushes CamStack entities to the CamStack Home Assistant custom component over HTTP. Chooses which devices reach which Home Assistant instance; Home Assistant never polls the hub for a value.
-  - Node placement: `hub-only`.
+- **Home Assistant Export** (`homeassistant-export`): Pushes CamStack entities to the CamStack Home Assistant custom component over HTTP. Chooses which devices reach which Home Assistant instance; Home Assistant never polls the hub for a value. Category: exports.
   - Capabilities: `device-export`, `addon-routes`, `oauth-integration`.
 
-## Settings
+## Configuration
+
+Edit these from System, Addons, this addon, Settings (a device's own settings are on its device page). A password field is stored in the keychain.
+
+**Addon settings**
 
-Settings this addon exposes are edited from System → Addons → this addon → Settings when they apply to the whole cluster, and from the device page when they belong to one device. A password field is stored in the keychain.
+- Calendars to import: Calendars
+- Home Assistant broker: Brokers are managed separately
+- Home Assistant connection: Auth mode, HA base URL, Long-lived access token, Supervisor token
+- Home Assistant instances: No brokers
+- Connection: Hub URL Home Assistant can reach
+- Advanced: Reconcile interval (s)
 
 ## Requirements
 
-- Peer packages already on the node: `@camstack/types`.
-- A CamStack hub. An agent is used only when the placement above allows it.
+- Placement: hub-only.
+- A CamStack hub. An agent is used only where the placement above allows it.
+
+## Documentation
+
+- [docs/addons/addon-provider-homeassistant.md](https://github.com/camstack/server/blob/main/docs/addons/addon-provider-homeassistant.md)
+- [docs/architecture/device-model.md](https://github.com/camstack/server/blob/main/docs/architecture/device-model.md)
+- [packages/addon-provider-homeassistant/AGENTS.md](https://github.com/camstack/server/blob/main/packages/addon-provider-homeassistant/AGENTS.md)
+
+See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version.
 
+<!-- readme:generated:end -->

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dist = require("./dist-D0ZiJUPy.js");
+const require_dist = require("./dist-DSRitvmZ.js");
 let node_crypto = require("node:crypto");
 let node_zlib = require("node:zlib");
 //#region src/ha-admin-link.ts
@@ -129,10 +129,10 @@ var haSourceSchemaFields = {
 	features: require_dist.array(require_dist.string()).optional(),
 	/** Sibling meter sensors whose readings this entity carries as `power-meter` (D951). */
 	meterEntities: require_dist.object({
-		watts: require_dist.string().optional(),
-		kwhTotal: require_dist.string().optional(),
-		volts: require_dist.string().optional(),
-		amps: require_dist.string().optional()
+		power: require_dist.string().optional(),
+		energy: require_dist.string().optional(),
+		voltage: require_dist.string().optional(),
+		current: require_dist.string().optional()
 	}).optional()
 };
 /** Project a persisted config blob into a typed source, or null when the
@@ -332,26 +332,26 @@ function takeReading(logger, deviceId, value, rawUnit, quantity) {
 */
 /** The `power-meter` status field a reading lands in. */
 var METER_FIELDS = [
-	"watts",
-	"kwhTotal",
-	"volts",
-	"amps"
+	"power",
+	"energy",
+	"voltage",
+	"current"
 ];
 var METER_BY_DEVICE_CLASS = {
 	power: {
-		field: "watts",
+		field: "power",
 		quantity: "power"
 	},
 	energy: {
-		field: "kwhTotal",
+		field: "energy",
 		quantity: "energy"
 	},
 	voltage: {
-		field: "volts",
+		field: "voltage",
 		quantity: "voltage"
 	},
 	current: {
-		field: "amps",
+		field: "current",
 		quantity: "current"
 	}
 };
@@ -953,10 +953,10 @@ var SUPPORTED_CAP_NAMES$1 = [
 ];
 /** Map a supported cap to its canonical "value" field. */
 var VALUE_FIELD = {
-	"temperature-sensor": "celsius",
-	"humidity-sensor": "percent",
-	"ambient-light-sensor": "lux",
-	"pressure-sensor": "hpa",
+	"temperature-sensor": "temperature",
+	"humidity-sensor": "humidity",
+	"ambient-light-sensor": "illuminance",
+	"pressure-sensor": "pressure",
 	"numeric-sensor": "value"
 };
 /** Typed sensors already name their quantity. The generic sensor learns it. */
@@ -1080,7 +1080,7 @@ var HaNumericSensorDevice = class extends HaBaseChildDevice {
 		switch (name) {
 			case "temperature-sensor": {
 				const COLD_START = {
-					celsius: 0,
+					temperature: 0,
 					lastFetchedAt: 0
 				};
 				this.ctx.registerNativeCap(require_dist.temperatureSensorCapability, { getStatus: async () => this.readSlice(COLD_START) });
@@ -1088,7 +1088,7 @@ var HaNumericSensorDevice = class extends HaBaseChildDevice {
 			}
 			case "humidity-sensor": {
 				const COLD_START = {
-					percent: 0,
+					humidity: 0,
 					lastFetchedAt: 0
 				};
 				this.ctx.registerNativeCap(require_dist.humiditySensorCapability, { getStatus: async () => this.readSlice(COLD_START) });
@@ -1096,7 +1096,7 @@ var HaNumericSensorDevice = class extends HaBaseChildDevice {
 			}
 			case "ambient-light-sensor": {
 				const COLD_START = {
-					lux: 0,
+					illuminance: 0,
 					lastFetchedAt: 0
 				};
 				this.ctx.registerNativeCap(require_dist.ambientLightSensorCapability, { getStatus: async () => this.readSlice(COLD_START) });
@@ -1104,7 +1104,7 @@ var HaNumericSensorDevice = class extends HaBaseChildDevice {
 			}
 			case "pressure-sensor": {
 				const COLD_START = {
-					hpa: 0,
+					pressure: 0,
 					lastFetchedAt: 0
 				};
 				this.ctx.registerNativeCap(require_dist.pressureSensorCapability, { getStatus: async () => this.readSlice(COLD_START) });
@@ -1400,7 +1400,7 @@ var HaLightDevice = class extends HaBaseChildDevice {
 			lastChangedAt: 0
 		});
 		if (this.capSet.has("brightness")) this.runtimeState.setCapState("brightness", {
-			percentage: 0,
+			level: 0,
 			lastChangedAt: 0
 		});
 		if (this.capSet.has("color")) this.runtimeState.setCapState("color", {
@@ -1420,7 +1420,7 @@ var HaLightDevice = class extends HaBaseChildDevice {
 			if (haBrightness !== null) {
 				const percentage = Math.max(0, Math.min(100, Math.round(haBrightness / 255 * 100)));
 				this.runtimeState.setCapState("brightness", {
-					percentage,
+					level: percentage,
 					lastChangedAt
 				});
 			}
@@ -1450,11 +1450,11 @@ var HaLightDevice = class extends HaBaseChildDevice {
 		this.ctx.registerNativeCap(require_dist.brightnessCapability, {
 			getStatus: async () => {
 				return this.runtimeState.getCapState("brightness") ?? {
-					percentage: 0,
+					level: 0,
 					lastChangedAt: 0
 				};
 			},
-			setBrightness: async ({ percentage }) => {
+			setBrightness: async ({ level: percentage }) => {
 				await this.callHaService("light", "turn_on", { brightness_pct: percentage });
 			}
 		});
@@ -1513,7 +1513,7 @@ function decodeColorSlice(colorMode, attrs, lastChangedAt) {
 		const mireds = readNumberAttr$6(attrs, "color_temp");
 		if (mireds !== null) return {
 			mode: "mired",
-			mireds,
+			colorTemperature: mireds,
 			lastChangedAt
 		};
 		return null;
@@ -1531,7 +1531,7 @@ function colorInputToHaServiceData(color) {
 			hs_color: [color.hsv.h, color.hsv.s],
 			brightness_pct: color.hsv.v
 		};
-		case "mired": return { color_temp: color.mireds };
+		case "mired": return { color_temp: color.colorTemperature };
 	}
 }
 //#endregion
@@ -2159,7 +2159,7 @@ function readNumberAttr$3(attrs, key) {
 //#endregion
 //#region src/devices/ha-fan-device.ts
 var FAN_COLD_START = {
-	percentage: null,
+	speed: null,
 	preset: "",
 	availablePresets: [],
 	direction: null,
@@ -2195,7 +2195,7 @@ var HaFanDevice = class extends HaBaseChildDevice {
 		});
 		const attrs = state.attributes;
 		const slice = {
-			percentage: readNumberAttr$2(attrs, "percentage"),
+			speed: readNumberAttr$2(attrs, "percentage"),
 			percentageStep: readNumberAttr$2(attrs, "percentage_step") ?? void 0,
 			preset: readStringAttr$4(attrs, "preset_mode") ?? "",
 			availablePresets: readStringArray$1(attrs, "preset_modes"),
@@ -2223,7 +2223,7 @@ var HaFanDevice = class extends HaBaseChildDevice {
 			getStatus: async () => {
 				return this.runtimeState.getCapState("fan-control") ?? FAN_COLD_START;
 			},
-			setPercentage: async ({ percentage }) => {
+			setPercentage: async ({ speed: percentage }) => {
 				await this.callHaService("fan", "set_percentage", { percentage });
 			},
 			setPreset: async ({ preset }) => {
@@ -2265,7 +2265,7 @@ var COLD_START$12 = {
 	batteryLevel: null,
 	fanSpeed: null,
 	availableFanSpeeds: [],
-	progressPercent: null,
+	progress: null,
 	errorCode: null,
 	errorLabel: null,
 	lastChangedAt: 0
@@ -2302,7 +2302,7 @@ var HaVacuumDevice = class extends HaBaseChildDevice {
 			batteryLevel,
 			fanSpeed,
 			availableFanSpeeds,
-			progressPercent: null,
+			progress: null,
 			errorCode: null,
 			errorLabel: lifecycleState === "error" ? readStringAttr$3(state.attributes, "error") : null,
 			lastChangedAt
@@ -2367,7 +2367,7 @@ function readStringArrayAttr(attrs, key) {
 var COLD_START$11 = {
 	activity: "idle",
 	batteryLevel: null,
-	progressPercent: null,
+	progress: null,
 	currentCode: null,
 	currentCodeLabel: null,
 	severity: "info",
@@ -2397,7 +2397,7 @@ var HaLawnMowerDevice = class extends HaBaseChildDevice {
 		if (activity !== null) this.runtimeState.setCapState("lawn-mower-control", {
 			activity,
 			batteryLevel,
-			progressPercent: readNumericAttr$1(state.attributes, "mowing_progress"),
+			progress: readNumericAttr$1(state.attributes, "mowing_progress"),
 			currentCode: null,
 			currentCodeLabel: null,
 			severity: activity === "error" ? "error" : "info",
@@ -2448,8 +2448,8 @@ var COLD_START$10 = {
 	source: "",
 	availableSources: [],
 	currentMedia: null,
-	positionMs: null,
-	durationMs: null,
+	position: null,
+	duration: null,
 	shuffle: null,
 	repeat: null,
 	lastChangedAt: 0
@@ -2479,8 +2479,8 @@ var HaMediaPlayerDevice = class extends HaBaseChildDevice {
 			source: readStringAttr$2(attrs, "source") ?? "",
 			availableSources: readStringArray(attrs, "source_list"),
 			currentMedia: buildCurrentMedia(attrs),
-			positionMs: readDurationMs(attrs, "media_position"),
-			durationMs: readDurationMs(attrs, "media_duration"),
+			position: readDurationMs(attrs, "media_position"),
+			duration: readDurationMs(attrs, "media_duration"),
 			shuffle: readBooleanAttr(attrs, "shuffle"),
 			repeat: readRepeat(attrs["repeat"]),
 			lastChangedAt
@@ -2513,7 +2513,7 @@ var HaMediaPlayerDevice = class extends HaBaseChildDevice {
 			previous: async () => {
 				await this.callHaService("media_player", "media_previous_track");
 			},
-			seek: async ({ positionMs }) => {
+			seek: async ({ position: positionMs }) => {
 				await this.callHaService("media_player", "media_seek", { seek_position: positionMs / 1e3 });
 			},
 			setVolume: async ({ volumeLevel }) => {
@@ -2682,11 +2682,17 @@ function deriveAvailableModes(attrs) {
 }
 //#endregion
 //#region src/devices/ha-presence-device.ts
+/** No reading yet: unknown, never 0 % (D393). */
+var COLD_BATTERY = {
+	level: null,
+	charging: "unknown",
+	sleeping: false,
+	lastUpdated: 0
+};
 var COLD_START$8 = {
 	state: "unknown",
 	location: null,
 	gps: null,
-	batteryPercent: null,
 	lastChangedAt: 0
 };
 /**
@@ -2696,14 +2702,17 @@ var COLD_START$8 = {
 *
 * HA attributes consumed:
 *   - `latitude` / `longitude` / `gps_accuracy` → gps envelope
-*   - `battery_level` → batteryPercent
+*   - `battery_level` → the `battery` cap (a presence provider never reports
+*     battery on the presence status)
 *   - `friendly_name` and the state value drive the `location` label
 */
 var HaPresenceDevice = class extends HaBaseChildDevice {
 	constructor(ctx) {
 		super(ctx);
 		this.registerPresenceCap();
+		this.registerBatteryCap();
 		this.runtimeState.setCapState("presence", COLD_START$8);
+		if (this.runtimeState.getCapState("battery") === void 0) this.runtimeState.setCapState("battery", COLD_BATTERY);
 	}
 	handleStatePush(state) {
 		if (state.state === "unavailable") return;
@@ -2721,10 +2730,24 @@ var HaPresenceDevice = class extends HaBaseChildDevice {
 				longitude: lon,
 				accuracyMeters: acc ?? 0
 			} : null,
-			batteryPercent: battery,
 			lastChangedAt
 		};
 		this.runtimeState.setCapState("presence", slice);
+		if (battery !== null) this.runtimeState.setCapState("battery", {
+			level: Math.min(100, Math.max(0, battery)),
+			charging: "unknown",
+			sleeping: false,
+			lastUpdated: lastChangedAt
+		});
+	}
+	registerBatteryCap() {
+		this.ctx.registerNativeCap(require_dist.batteryCapability, {
+			getStatus: async () => this.runtimeState.getCapState("battery") ?? COLD_BATTERY,
+			wakeForStream: async () => ({
+				awoke: true,
+				durationMs: 0
+			})
+		});
 	}
 	registerPresenceCap() {
 		this.ctx.registerNativeCap(require_dist.presenceCapability, { getStatus: async () => {
@@ -3200,7 +3223,7 @@ var HaNotifierDevice = class extends HaBaseChildDevice {
 var COLD_START$4 = { lastFetchedAt: 0 };
 /**
 * HA-backed power-meter sensor child. Multi-field cap — the slice
-* carries `watts` / `volts` / `amps` / `kwhTotal` etc., but each HA
+* carries `power` / `voltage` / `current` / `energy` etc., but each HA
 * `sensor.*` entity surfaces ONE metric (device_class = `power` /
 * `voltage` / `current` / `energy`). The class populates the field
 * corresponding to the entity's device_class.
@@ -3263,22 +3286,22 @@ function applyDeviceClass$1(prev, deviceClass, value, lastFetchedAt) {
 	switch (deviceClass) {
 		case "power": return {
 			...prev,
-			watts: value,
+			power: value,
 			lastFetchedAt
 		};
 		case "energy": return {
 			...prev,
-			kwhTotal: value,
+			energy: value,
 			lastFetchedAt
 		};
 		case "voltage": return {
 			...prev,
-			volts: value,
+			voltage: value,
 			lastFetchedAt
 		};
 		case "current": return {
 			...prev,
-			amps: value,
+			current: value,
 			lastFetchedAt
 		};
 		default: return null;
@@ -3344,12 +3367,12 @@ function applyDeviceClass(prev, deviceClass, value, lastFetchedAt) {
 	switch (deviceClass) {
 		case "co2": return {
 			...prev,
-			co2Ppm: value,
+			co2: value,
 			lastFetchedAt
 		};
 		case "volatile_organic_compounds": return {
 			...prev,
-			vocPpb: value,
+			voc: value,
 			lastFetchedAt
 		};
 		case "pm25":
@@ -3854,10 +3877,10 @@ var containerEntitySchema = require_dist.object({
 	dateTimeFormat: require_dist.EnumSensorDateTimeFormatSchema.optional(),
 	entityCategory: require_dist._enum(["config", "diagnostic"]).optional(),
 	meterEntities: require_dist.object({
-		watts: require_dist.string().optional(),
-		kwhTotal: require_dist.string().optional(),
-		volts: require_dist.string().optional(),
-		amps: require_dist.string().optional()
+		power: require_dist.string().optional(),
+		energy: require_dist.string().optional(),
+		voltage: require_dist.string().optional(),
+		current: require_dist.string().optional()
 	}).optional(),
 	foldedInto: require_dist.string().optional()
 });
@@ -4041,10 +4064,10 @@ var haEntitySchema = require_dist.object({
 	entityCategory: require_dist._enum(["config", "diagnostic"]).optional(),
 	/** Sibling meter sensors this entity reads as its own power-meter (D951). */
 	meterEntities: require_dist.object({
-		watts: require_dist.string().optional(),
-		kwhTotal: require_dist.string().optional(),
-		volts: require_dist.string().optional(),
-		amps: require_dist.string().optional()
+		power: require_dist.string().optional(),
+		energy: require_dist.string().optional(),
+		voltage: require_dist.string().optional(),
+		current: require_dist.string().optional()
 	}).optional(),
 	/** Set on a meter sensor folded into another entity: sectioned as Diagnostic. */
 	foldedInto: require_dist.string().optional()
@@ -4119,7 +4142,7 @@ function deriveBatteryStatus(entities, entityId, state, now) {
 	if (isBinaryBattery(battery)) {
 		if (state.state !== "on" && state.state !== "off") return null;
 		return {
-			percentage: state.state === "on" ? BINARY_BATTERY_LOW_PCT : BINARY_BATTERY_NORMAL_PCT,
+			level: state.state === "on" ? BINARY_BATTERY_LOW_PCT : BINARY_BATTERY_NORMAL_PCT,
 			charging: "none",
 			sleeping: false,
 			lastUpdated: now,
@@ -4129,7 +4152,7 @@ function deriveBatteryStatus(entities, entityId, state, now) {
 	const raw = Number(state.state);
 	if (!Number.isFinite(raw)) return null;
 	return {
-		percentage: Math.min(100, Math.max(0, raw)),
+		level: Math.min(100, Math.max(0, raw)),
 		charging: "none",
 		sleeping: false,
 		lastUpdated: now
@@ -4186,7 +4209,7 @@ var HaContainerDevice = class HaContainerDevice extends require_dist.BaseDevice
 		this.batteryEntityId = batteryEntityId(cfg.entities);
 		if (this.batteryEntityId !== null) {
 			const COLD = {
-				percentage: null,
+				level: null,
 				charging: "unknown",
 				sleeping: false,
 				lastUpdated: 0