@camstack/addon-provider-bosch 0.1.48 → 0.1.50

package/dist/home-connect/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_bosch_instances = require("../bosch-instances-CRvxRbDk.js");
-const require_account_integration_offline = require("../account-integration-offline-CQ7UB6U_.js");
+const require_bosch_instances = require("../bosch-instances-CYBnIcHg.js");
+const require_account_integration_offline = require("../account-integration-offline-7CH3r5jI.js");
 let node_crypto = require("node:crypto");
 let node_tls = require("node:tls");
 let node_zlib = require("node:zlib");

package/dist/home-connect/addon.mjs

@@ -1,5 +1,5 @@
-import { A as RecordIntegrationInstances, B as array, C as powerMeterCapability, E as runningStateCapability, F as entryBody, G as string, I as isSecretMarker, J as DeviceRole, K as union, L as isSecretMarkerLike, M as customAction, N as defineCustomActions, P as defineEntryKind, R as rowsDepsOver, S as numericSensorCapability, T as runningFromDishwasherOperation, U as object, V as literal, W as record, X as errMsg, Y as DeviceType, Z as EventCategory, a as BaseDevice, b as ingestReading, c as RUNNING_STATE_COLD, f as consumablesCapability, g as eventEmitterCapability, h as enumSensorCapability, i as testBoschInstance, j as createEvent, m as dishwasherCapability, n as boschRowsPorts, o as BaseDeviceProvider, p as deviceAdoptionCapability, q as unknown, r as keepBodyKeys, s as DishwasherOperationStateSchema, t as boschRowsMigration, u as binaryCapability, w as quantityFromUnit, x as integrationInstancesCapability, z as _enum } from "../bosch-instances-t9x1fGVW.mjs";
-import { a as loginFailureForAttempt, c as HOME_CONNECT_REDIRECT_URI, i as createSignInAttemptStore, n as cascadeRemoveDevicesForIntegration, o as parseOAuthCallback, r as buildSignInGuideFields, t as setIntegrationDevicesOnline } from "../account-integration-offline-DLCUxCxS.mjs";
+import { $ as EventCategory, A as RecordIntegrationInstances, C as powerMeterCapability, E as runningStateCapability, F as entryBody, G as object, I as isSecretMarker, J as union, K as record, L as isSecretMarkerLike, M as customAction, N as defineCustomActions, P as defineEntryKind, Q as errMsg, R as rowsDepsOver, S as numericSensorCapability, T as runningFromDishwasherOperation, U as literal, V as array, X as DeviceRole, Y as unknown, Z as DeviceType, a as BaseDevice, b as ingestReading, c as RUNNING_STATE_COLD, f as consumablesCapability, g as eventEmitterCapability, h as enumSensorCapability, i as testBoschInstance, j as createEvent, m as dishwasherCapability, n as boschRowsPorts, o as BaseDeviceProvider, p as deviceAdoptionCapability, q as string, r as keepBodyKeys, s as DishwasherOperationStateSchema, t as boschRowsMigration, u as binaryCapability, w as quantityFromUnit, x as integrationInstancesCapability, z as _enum } from "../bosch-instances-CdvcBYye.mjs";
+import { a as loginFailureForAttempt, c as HOME_CONNECT_REDIRECT_URI, i as createSignInAttemptStore, n as cascadeRemoveDevicesForIntegration, o as parseOAuthCallback, r as buildSignInGuideFields, t as setIntegrationDevicesOnline } from "../account-integration-offline-B1Wgr_rT.mjs";
 import { createHash, randomBytes } from "node:crypto";
 import { connect } from "node:tls";
 import { inflateRawSync } from "node:zlib";

package/dist/homecom/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_bosch_instances = require("../bosch-instances-CRvxRbDk.js");
-const require_account_integration_offline = require("../account-integration-offline-CQ7UB6U_.js");
+const require_bosch_instances = require("../bosch-instances-CYBnIcHg.js");
+const require_account_integration_offline = require("../account-integration-offline-7CH3r5jI.js");
 let node_crypto = require("node:crypto");
 //#region src/homecom/config.ts
 var HOMECOM_BRANDS = ["bosch", "buderus"];
@@ -178,6 +178,280 @@ function buildHomeComFormSchema() {
 		]
 	}] };
 }
+var EXPLORER_MAX_NODES_CAP = 1500;
+var VALUE_MAX_CHARS = 200;
+/** Roots walked when `/` does not list its children. */
+var EXPLORER_SEED_ROOTS = [
+	"/system",
+	"/heatSources",
+	"/heatingCircuits",
+	"/dhwCircuits",
+	"/gateway",
+	"/notifications",
+	"/recordings",
+	"/devices",
+	"/solarCircuits",
+	"/ventilation"
+];
+/** Under the 60 s UDS request timeout a forked addon's action answers within. */
+var EXPLORER_MAX_DEADLINE_MS = 5e4;
+var DROPPED_SAMPLE_MAX = 20;
+var UNVISITED_SAMPLE_MAX = 100;
+var PATH_SHAPE = /^\/(?:[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*)?$/;
+/**
+* A resource path this walker will request: absolute, plain segments, and no `.` or `..`
+* segment — URL resolution would otherwise lift the request out of the gateway's tree.
+*/
+function isResourcePath(path) {
+	if (!PATH_SHAPE.test(path)) return false;
+	return path.split("/").slice(1).every((segment) => segment !== "." && segment !== "..");
+}
+var explorerOutcomeSchema = require_bosch_instances._enum([
+	"ok",
+	"forbidden",
+	"not-found",
+	"rate-limited",
+	"error"
+]);
+var exploredResourceSchema = require_bosch_instances.object({
+	path: require_bosch_instances.string(),
+	httpStatus: require_bosch_instances.number(),
+	outcome: explorerOutcomeSchema,
+	type: require_bosch_instances.string().optional(),
+	value: require_bosch_instances.union([
+		require_bosch_instances.string(),
+		require_bosch_instances.number(),
+		require_bosch_instances.boolean(),
+		require_bosch_instances._null()
+	]).optional(),
+	unit: require_bosch_instances.string().optional(),
+	writeable: require_bosch_instances.boolean().optional(),
+	recordable: require_bosch_instances.boolean().optional(),
+	allowedValues: require_bosch_instances.array(require_bosch_instances.string()).optional(),
+	minValue: require_bosch_instances.number().optional(),
+	maxValue: require_bosch_instances.number().optional(),
+	childCount: require_bosch_instances.number().optional(),
+	/** References of this container that were not a walkable path. */
+	droppedReferences: require_bosch_instances.number().optional(),
+	error: require_bosch_instances.string().optional()
+});
+var explorerSummarySchema = require_bosch_instances.object({
+	ok: require_bosch_instances.number(),
+	forbidden: require_bosch_instances.number(),
+	"not-found": require_bosch_instances.number(),
+	"rate-limited": require_bosch_instances.number(),
+	error: require_bosch_instances.number()
+});
+var explorerStopReasonSchema = require_bosch_instances._enum([
+	"complete",
+	"max-nodes",
+	"rate-limited",
+	"deadline"
+]);
+function isRecord$3(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finite$1(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function text$1(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function truncate(value) {
+	return value.length > VALUE_MAX_CHARS ? `${value.slice(0, VALUE_MAX_CHARS - 1)}…` : value;
+}
+function shownValue(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "string") return truncate(value);
+	return truncate(JSON.stringify(value));
+}
+function outcomeOf(status) {
+	if (status >= 200 && status < 300) return "ok";
+	if (status === 403) return "forbidden";
+	if (status === 404) return "not-found";
+	if (status === 429) return "rate-limited";
+	return "error";
+}
+/** What a reference names: its `id`, else the part of its `uri` after `/resource`. */
+function referenceText(ref) {
+	if (!isRecord$3(ref)) return null;
+	const id = text$1(ref["id"]);
+	if (id !== void 0 && id.startsWith("/")) return id;
+	const uri = text$1(ref["uri"]);
+	if (uri === void 0) return id ?? null;
+	const at = uri.indexOf("/resource/");
+	if (at < 0) return uri;
+	return uri.slice(at + 9);
+}
+/** The walkable resource path a reference names, or null. */
+function referencePath(ref) {
+	const path = referenceText(ref);
+	return path !== null && isResourcePath(path) ? path : null;
+}
+function referencesOf(body) {
+	if (!isRecord$3(body)) return null;
+	const refs = body["references"];
+	if (!Array.isArray(refs)) return null;
+	const paths = [];
+	const dropped = [];
+	for (const ref of refs) {
+		const path = referencePath(ref);
+		if (path !== null) paths.push(path);
+		else dropped.push(truncate(referenceText(ref) ?? JSON.stringify(ref) ?? "undefined"));
+	}
+	return {
+		total: refs.length,
+		paths,
+		dropped
+	};
+}
+function describeLeaf(path, status, body) {
+	if (!isRecord$3(body)) return {
+		path,
+		httpStatus: status,
+		outcome: "ok"
+	};
+	const allowed = body["allowedValues"];
+	const allowedValues = Array.isArray(allowed) ? allowed.map((v) => truncate(String(v))) : void 0;
+	const type = text$1(body["type"]);
+	const unit = text$1(body["unitOfMeasure"]);
+	const minValue = finite$1(body["minValue"]);
+	const maxValue = finite$1(body["maxValue"]);
+	const writeable = body["writeable"];
+	const recordable = body["recordable"];
+	return {
+		path,
+		httpStatus: status,
+		outcome: "ok",
+		...type !== void 0 ? { type } : {},
+		..."value" in body ? { value: shownValue(body["value"]) } : {},
+		...unit !== void 0 ? { unit } : {},
+		...typeof writeable === "number" || typeof writeable === "boolean" ? { writeable: Boolean(writeable) } : {},
+		...typeof recordable === "number" || typeof recordable === "boolean" ? { recordable: Boolean(recordable) } : {},
+		...allowedValues !== void 0 ? { allowedValues } : {},
+		...minValue !== void 0 ? { minValue } : {},
+		...maxValue !== void 0 ? { maxValue } : {}
+	};
+}
+function emptySummary() {
+	return {
+		ok: 0,
+		forbidden: 0,
+		"not-found": 0,
+		"rate-limited": 0,
+		error: 0
+	};
+}
+function clampDeadline(requested) {
+	return Math.min(Math.max(Math.floor(requested ?? 45e3), 1), EXPLORER_MAX_DEADLINE_MS);
+}
+function clampNodes(requested) {
+	return Math.min(Math.max(Math.floor(requested ?? 400), 1), EXPLORER_MAX_NODES_CAP);
+}
+var defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+async function exploreHomeComResources(input) {
+	const root = input.root ?? "/";
+	if (!isResourcePath(root)) throw new Error(`Not a resource path: ${root}`);
+	const maxNodes = clampNodes(input.maxNodes);
+	const delayMs = Math.max(input.delayMs ?? 150, 150);
+	const sleep = input.sleep ?? defaultSleep;
+	const now = input.now ?? Date.now;
+	const deadlineAt = now() + clampDeadline(input.deadlineMs);
+	const queue = [root];
+	const queued = new Set([root]);
+	const resources = [];
+	const summary = emptySummary();
+	let calls = 0;
+	let stoppedBy = "complete";
+	let droppedReferences = 0;
+	const droppedSamples = [];
+	const enqueue = (paths) => {
+		for (const path of paths) {
+			if (queued.has(path)) continue;
+			queued.add(path);
+			queue.push(path);
+		}
+	};
+	while (queue.length > 0) {
+		if (calls >= maxNodes) {
+			stoppedBy = "max-nodes";
+			break;
+		}
+		if (now() + (calls > 0 ? delayMs : 0) >= deadlineAt) {
+			stoppedBy = "deadline";
+			break;
+		}
+		const path = queue.shift();
+		if (path === void 0) break;
+		if (calls > 0) await sleep(delayMs);
+		calls += 1;
+		let answer;
+		try {
+			answer = await input.read(path);
+		} catch (err) {
+			const error = err instanceof Error ? err.message : String(err);
+			resources.push({
+				path,
+				httpStatus: 0,
+				outcome: "error",
+				error
+			});
+			summary.error += 1;
+			continue;
+		}
+		const outcome = outcomeOf(answer.status);
+		summary[outcome] += 1;
+		if (outcome === "rate-limited") {
+			resources.push({
+				path,
+				httpStatus: answer.status,
+				outcome
+			});
+			stoppedBy = "rate-limited";
+			break;
+		}
+		if (outcome !== "ok") {
+			resources.push({
+				path,
+				httpStatus: answer.status,
+				outcome
+			});
+			if (path === "/" && root === "/") enqueue(EXPLORER_SEED_ROOTS);
+			continue;
+		}
+		const children = referencesOf(answer.body);
+		if (children !== null) {
+			const type = isRecord$3(answer.body) ? text$1(answer.body["type"]) : void 0;
+			resources.push({
+				path,
+				httpStatus: answer.status,
+				outcome,
+				type: type ?? "refEnum",
+				childCount: children.total,
+				...children.dropped.length > 0 ? { droppedReferences: children.dropped.length } : {}
+			});
+			droppedReferences += children.dropped.length;
+			for (const ref of children.dropped) if (droppedSamples.length < DROPPED_SAMPLE_MAX) droppedSamples.push(`${path} -> ${ref}`);
+			enqueue(children.paths);
+			continue;
+		}
+		resources.push(describeLeaf(path, answer.status, answer.body));
+		if (path === "/" && root === "/") enqueue(EXPLORER_SEED_ROOTS);
+	}
+	return {
+		root,
+		resources,
+		summary,
+		stoppedBy,
+		unvisited: queue.length,
+		unvisitedPaths: queue.slice(0, UNVISITED_SAMPLE_MAX),
+		droppedReferences,
+		droppedSamples
+	};
+}
 //#endregion
 //#region src/homecom/custom-actions.ts
 var gatewayChoice = require_bosch_instances.object({
@@ -186,6 +460,27 @@ var gatewayChoice = require_bosch_instances.object({
 	brand: HomeComBrandSchema,
 	region: HomeComRegionSchema
 });
+var exploreResourcesInput = require_bosch_instances.object({
+	/** The HomeCom integration instance; may be omitted when exactly one is connected. */
+	integrationId: require_bosch_instances.string().min(1).optional(),
+	root: require_bosch_instances.string().refine(isResourcePath, "an absolute resource path such as /heatSources, no . or .. segment").optional(),
+	maxNodes: require_bosch_instances.number().int().min(1).max(EXPLORER_MAX_NODES_CAP).optional(),
+	/** Wall-clock budget; the walk returns what it has, with `stoppedBy: 'deadline'`. */
+	deadlineMs: require_bosch_instances.number().int().min(1e3).max(EXPLORER_MAX_DEADLINE_MS).optional()
+});
+var exploreResourcesOutput = require_bosch_instances.object({
+	integrationId: require_bosch_instances.string(),
+	/** Null when the integration has no snapshot yet: unknown, not empty. */
+	gatewayId: require_bosch_instances.string().nullable(),
+	root: require_bosch_instances.string(),
+	stoppedBy: explorerStopReasonSchema,
+	unvisited: require_bosch_instances.number(),
+	unvisitedPaths: require_bosch_instances.array(require_bosch_instances.string()),
+	droppedReferences: require_bosch_instances.number(),
+	droppedSamples: require_bosch_instances.array(require_bosch_instances.string()),
+	summary: explorerSummarySchema,
+	resources: require_bosch_instances.array(exploredResourceSchema)
+});
 var homeComActions = require_bosch_instances.defineCustomActions({
 	beginSignIn: require_bosch_instances.customAction(require_bosch_instances.object({}), require_bosch_instances.object({
 		attemptId: require_bosch_instances.string().min(1),
@@ -219,9 +514,95 @@ var homeComActions = require_bosch_instances.defineCustomActions({
 	}), {
 		kind: "mutation",
 		auth: "admin"
+	}),
+	/** Read-only walk of the gateway's resource tree, for diagnosing what it serves. */
+	exploreResources: require_bosch_instances.customAction(exploreResourcesInput, exploreResourcesOutput, {
+		kind: "query",
+		auth: "admin"
 	})
 });
 //#endregion
+//#region src/homecom/homecom-explore-action.ts
+/** The action refused before it walked anything; `reason` says why. */
+var HomeComExploreRefusedError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "HomeComExploreRefusedError";
+		this.reason = reason;
+	}
+};
+function pickIntegration(input, connected) {
+	if (input.integrationId !== void 0) return input.integrationId;
+	if (connected.length === 1 && connected[0] !== void 0) return connected[0];
+	if (connected.length === 0) throw new HomeComExploreRefusedError("not-connected", "No HomeCom integration is connected.");
+	throw new HomeComExploreRefusedError("ambiguous", `Several HomeCom integrations are connected; name one with integrationId (${connected.join(", ")}).`);
+}
+/**
+* The `exploreResources` action: a read-only walk of one integration's gateway. One walk
+* per integration at a time — a second call while one runs is refused, never queued.
+*/
+function createHomeComExploreAction(deps) {
+	const running = /* @__PURE__ */ new Set();
+	return async (input) => {
+		const integrationId = pickIntegration(input, deps.listConnected());
+		if (running.has(integrationId)) throw new HomeComExploreRefusedError("already-running", `A resource walk is already running for HomeCom integration ${integrationId}.`);
+		const client = deps.getClient(integrationId);
+		if (client === null) throw new HomeComExploreRefusedError("not-connected", `HomeCom integration ${integrationId} is not connected.`);
+		running.add(integrationId);
+		try {
+			return await walk(input, integrationId, client, deps);
+		} finally {
+			running.delete(integrationId);
+		}
+	};
+}
+async function walk(input, integrationId, client, deps) {
+	const result = await exploreHomeComResources({
+		read: (path) => client.readResource(path),
+		...input.root !== void 0 ? { root: input.root } : {},
+		...input.maxNodes !== void 0 ? { maxNodes: input.maxNodes } : {},
+		...input.deadlineMs !== void 0 ? { deadlineMs: input.deadlineMs } : {},
+		...deps.sleep !== void 0 ? { sleep: deps.sleep } : {},
+		...deps.now !== void 0 ? { now: deps.now } : {}
+	});
+	const gatewayId = deps.getGatewayId(integrationId);
+	if (result.droppedReferences > 0) deps.logger.warn("HomeCom resource walk dropped references that are not a walkable path", {
+		tags: { integrationId },
+		meta: {
+			gatewayId,
+			droppedReferences: result.droppedReferences,
+			samples: result.droppedSamples
+		}
+	});
+	deps.logger.info("HomeCom resource tree explored", {
+		tags: { integrationId },
+		meta: {
+			gatewayId,
+			root: result.root,
+			visited: result.resources.length,
+			stoppedBy: result.stoppedBy,
+			unvisited: result.unvisited,
+			droppedReferences: result.droppedReferences,
+			...result.summary
+		}
+	});
+	return {
+		integrationId,
+		gatewayId,
+		...result
+	};
+}
+/** The addon's deps: registered integrations that hold a live client; gateway from the snapshot. */
+function homeComExploreDeps(wiring) {
+	return {
+		listConnected: () => wiring.registry.list().filter((id) => wiring.connections.getClient(id) !== null),
+		getClient: (id) => wiring.connections.getClient(id),
+		getGatewayId: (id) => wiring.connections.getSnapshot(id)?.gateway.gatewayId ?? null,
+		logger: wiring.logger
+	};
+}
+//#endregion
 //#region src/homecom/homecom-device-type.ts
 /**
 * Device types the PointT gateway list reports. The set is the one the MIT
@@ -735,6 +1116,14 @@ var HEAT_PUMP_PATHS = {
 		pressureBar: "/heatSources/hs1/waterPressure",
 		starts: "/heatSources/hs1/numberOfStarts"
 	},
+	/**
+	* Resources only a heat pump's heat source has. A gateway that answers one of them with
+	* anything but 404 (a 403 or a 500 included) has a heat pump it will not let us read.
+	*/
+	identity: {
+		heatPumpType: "/heatSources/hs1/heatPumpType",
+		heatPumpPower: "/heatSources/hs1/heatPumpPower"
+	},
 	circuit: {
 		operationMode: "operationMode",
 		heatCoolMode: "heatCoolMode",
@@ -763,6 +1152,7 @@ async function readHeatPump(input) {
 	const circuits = await Promise.all([...input.circuitIds.hc.map((id) => readHc(get, id)), ...input.circuitIds.dhw.map((id) => readDhwCircuit(get, id))]);
 	const r = HEAT_PUMP_PATHS.readings;
 	const s = HEAT_PUMP_PATHS.system;
+	const heatSourceAnswered = await anyAnswers(input.answers, input.onFailure, [HEAT_PUMP_PATHS.identity.heatPumpType, HEAT_PUMP_PATHS.identity.heatPumpPower]);
 	const [silent, away, additionalHeater, holiday] = await Promise.all([
 		setting(get, s.silent),
 		setting(get, s.away),
@@ -785,6 +1175,7 @@ async function readHeatPump(input) {
 	]);
 	return {
 		circuits,
+		heatSourceAnswered,
 		silent,
 		away,
 		additionalHeater,
@@ -801,6 +1192,17 @@ async function readHeatPump(input) {
 		starts
 	};
 }
+async function anyAnswers(answers, onFailure, paths) {
+	if (answers === void 0) return false;
+	return (await Promise.all(paths.map(async (path) => {
+		try {
+			return await answers(path);
+		} catch (error) {
+			onFailure?.(path, error);
+			return false;
+		}
+	}))).some(Boolean);
+}
 /** Any failure of a heat-pump read (HTTP 4xx/5xx, a throw) is "not answered", never an error. */
 function safeGet(get, onFailure) {
 	return async (path) => {
@@ -828,16 +1230,28 @@ var HEAT_PUMP_ONLY_READINGS = [
 *
 * A system mode counts when the gateway answered it: silent, away, the
 * additional heater, or holiday. An empty string is an answer (holiday often
-* comes back empty); a path that did not answer is not. HomeCom returns no
-* value for silent mode and the auxiliary heater on some heat-pump firmware,
-* so away and holiday alone are enough. A heat-pump-only reading counts too
-* (thermal power, electrical power, compressor modulation). Supply, return,
-* outdoor, pressure, starts and the energy meters do not: a gas boiler's heat
-* source answers flow, pressure and starts, and that is not a heat pump.
+* comes back empty); a path that did not answer is not. A heat-pump-only
+* reading counts too (thermal power, electrical power, compressor modulation).
+* So does a circuit whose `heatCoolMode` can be cooling, and a heat source that
+* answers a heat-pump-only resource with any status but 404: some gateways
+* refuse (403) or fail (500) the whole system tree and still serve the
+* circuits. Supply, return, outdoor, pressure, starts and the energy meters do
+* not count: a gas boiler's heat source answers flow, pressure and starts, and
+* that is not a heat pump.
 */
 function hasSystemDevice(reading) {
 	if (SYSTEM_MODE_KEYS.some((key) => reading[key] !== null)) return true;
-	return HEAT_PUMP_ONLY_READINGS.some((key) => reading[key] !== null);
+	if (HEAT_PUMP_ONLY_READINGS.some((key) => reading[key] !== null)) return true;
+	if (reading.heatSourceAnswered) return true;
+	return reading.circuits.some((c) => c.kind === "hc" && offersCooling(c.heatCoolMode));
+}
+/**
+* A boiler circuit can carry a `heatCoolMode` that only ever says heating, so the mode alone
+* is no proof. A circuit that can switch to (or already is in) cooling is a heat pump's.
+*/
+function offersCooling(setting) {
+	if (setting === null) return false;
+	return setting.value === "cooling" || setting.allowed.includes("cooling");
 }
 /** Which heat-pump paths this gateway answered. One log per gateway corrects the path table. */
 function heatPumpPathCensus(reading) {
@@ -1376,6 +1790,17 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 		if (!res.ok) throw new Error(`HomeCom API ${path} failed: HTTP ${res.status}`);
 		return res.body;
 	}
+	/**
+	* Evidence that the resource exists: a 2xx, or the 403 the gateway gives a resource it
+	* serves but will not show. 404 is "absent". Anything else (429, 5xx) is a transient
+	* failure, so it is NOT evidence either way: it is logged and counts as unknown.
+	*/
+	async function resourceAnswers(path) {
+		const res = await authed(homeComResourceUrl(gatewayId, path), { method: "GET" });
+		if (res.ok || res.status === 403) return true;
+		if (res.status !== 404) logHeatPumpFailure(path, /* @__PURE__ */ new Error(`HTTP ${res.status}`));
+		return false;
+	}
 	async function putWrite(write) {
 		const res = await authed(homeComResourceUrl(gatewayId, write.path), {
 			method: "PUT",
@@ -1457,6 +1882,7 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 		const heatPump = await readHeatPump({
 			get: getResource,
 			onFailure: logHeatPumpFailure,
+			answers: resourceAnswers,
 			circuitIds: {
 				hc: snapshot.circuits.map((circuit) => circuit.id),
 				dhw: dhwId === void 0 ? [] : [dhwId]
@@ -1547,6 +1973,13 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 		},
 		async writeHeatPump(writes) {
 			for (const write of writes) await putWrite(write);
+		},
+		async readResource(path) {
+			const res = await authed(homeComResourceUrl(gatewayId, path), { method: "GET" });
+			return {
+				status: res.status,
+				body: res.body
+			};
 		}
 	};
 }
@@ -1851,6 +2284,15 @@ var HomeComConnectionResolver = class {
 		this.#surfaces.clear();
 	}
 };
+/** Native id of the gateway pick: a Gateway device, sibling of the circuits. */
+var HOMECOM_GATEWAY_NATIVE_ID = "gateway:0";
+function gatewayDiscoverable(snapshot) {
+	return {
+		nativeId: HOMECOM_GATEWAY_NATIVE_ID,
+		name: snapshot.gateway.name.length > 0 ? snapshot.gateway.name : "HomeCom gateway",
+		kind: "gateway"
+	};
+}
 var BOILER_DHW_NAME = "Domestic hot water";
 function circuitDiscoverable(circuit) {
 	return {
@@ -1868,18 +2310,25 @@ function dhwDiscoverable(name) {
 	};
 }
 /**
-* A gateway with a heat pump is one pick. A boiler still offers each circuit
+* The gateway itself is always the first pick. A gateway with a heat pump is one more pick. A boiler still offers each circuit
 * and the hot-water row on its own.
 */
 function buildDiscoverables(snapshot) {
 	const circuits = snapshot.circuits.map(circuitDiscoverable);
-	if (snapshot.heatPump !== void 0) return [{
-		nativeId: "hp:0",
-		name: "Heat pump",
-		kind: "heat-pump",
-		children: [...circuits, ...snapshot.dhw === null ? [] : [dhwDiscoverable(HOMECOM_HOT_WATER_CHILD_NAME)]]
-	}];
-	return [...circuits, ...snapshot.dhw === null ? [] : [dhwDiscoverable(BOILER_DHW_NAME)]];
+	if (snapshot.heatPump !== void 0) {
+		const children = [...circuits, ...snapshot.dhw === null ? [] : [dhwDiscoverable(HOMECOM_HOT_WATER_CHILD_NAME)]];
+		return [gatewayDiscoverable(snapshot), {
+			nativeId: "hp:0",
+			name: "Heat pump",
+			kind: "heat-pump",
+			children
+		}];
+	}
+	return [
+		gatewayDiscoverable(snapshot),
+		...circuits,
+		...snapshot.dhw === null ? [] : [dhwDiscoverable(BOILER_DHW_NAME)]
+	];
 }
 var homeComConnections = new HomeComConnectionResolver();
 //#endregion
@@ -1962,6 +2411,10 @@ function shapeOf(kind) {
 			type: require_bosch_instances.DeviceType.WaterHeater,
 			caps: ["water-heater"]
 		};
+		case "gateway": return {
+			type: require_bosch_instances.DeviceType.Gateway,
+			caps: []
+		};
 		case "heat-pump": return {
 			type: require_bosch_instances.DeviceType.HeatPump,
 			caps: ["heat-pump-status", "heat-pump-control"]
@@ -2809,6 +3262,35 @@ var HomeComWaterHeaterDevice = class extends require_bosch_instances.BaseDevice
 	}
 };
 //#endregion
+//#region src/homecom/devices/homecom-gateway-device.ts
+var homeComGatewaySchema = require_bosch_instances.object({
+	nativeId: require_bosch_instances.string().min(1),
+	brokerId: require_bosch_instances.string().min(1),
+	system: require_bosch_instances.literal("homecom").optional(),
+	integrationId: require_bosch_instances.string().optional()
+});
+/**
+* The HomeCom gateway, as a {@link DeviceType.Gateway}. Its connection lives on the
+* INTEGRATION; this device is the gateway's presence in the device list and follows the
+* integration's online state (its connect and disconnect callbacks flip it).
+*
+* It registers no action: the cloud account offers no reboot, no update and no local page,
+* so there is nothing real to expose. The circuits, the hot water and the heat pump are NOT
+* children of it; each is adopted as its own top-level device of the same integration.
+*/
+var HomeComGatewayDevice = class extends require_bosch_instances.BaseDevice {
+	features = [];
+	constructor(ctx) {
+		const cfg = homeComGatewaySchema.parse(ctx.persistedConfig ?? {});
+		super(ctx, homeComGatewaySchema, { type: require_bosch_instances.DeviceType.Gateway });
+		this.online = homeComConnections.has(cfg.brokerId);
+		this.updateSourceInfo({
+			id: cfg.nativeId,
+			system: "homecom"
+		});
+	}
+};
+//#endregion
 //#region src/homecom/devices/homecom-heat-pump-device.ts
 var homeComHeatPumpSchema = require_bosch_instances.object({
 	nativeId: require_bosch_instances.string().min(1),
@@ -2959,7 +3441,8 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 	deviceClasses = {
 		[require_bosch_instances.DeviceType.Climate]: HomeComClimateDevice,
 		[require_bosch_instances.DeviceType.WaterHeater]: HomeComWaterHeaterDevice,
-		[require_bosch_instances.DeviceType.HeatPump]: HomeComHeatPumpDevice
+		[require_bosch_instances.DeviceType.HeatPump]: HomeComHeatPumpDevice,
+		[require_bosch_instances.DeviceType.Gateway]: HomeComGatewayDevice
 	};
 	clients = null;
 	instances = null;
@@ -3000,6 +3483,11 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 		});
 		await this.reconcileIntegrations();
 		this.subscribeIntegrationLifecycle();
+		const explore = createHomeComExploreAction(homeComExploreDeps({
+			registry: this.clients,
+			connections: homeComConnections,
+			logger: this.ctx.logger
+		}));
 		return {
 			providers: [
 				...regs,
@@ -3026,7 +3514,8 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 				signOut: async () => ({
 					signedOut: true,
 					summary: "Signed out."
-				})
+				}),
+				exploreResources: explore
 			}
 		};
 	}