@camstack/addon-provider-bosch 0.1.49 → 0.1.50

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.50] - 2026-11-11
+
+### Added
+
+- HomeCom: a read-only resource-tree explorer action for diagnosing what a gateway serves
+
 ## [0.1.49] - 2026-11-11
 
 ### Changed

package/dist/{account-integration-offline-Dcx0sq_v.js → account-integration-offline-7CH3r5jI.js}

@@ -1,4 +1,4 @@
-const require_bosch_instances = require("./bosch-instances-BHFcR1TK.js");
+const require_bosch_instances = require("./bosch-instances-CYBnIcHg.js");
 let node_crypto = require("node:crypto");
 //#region src/shared/sign-in-redirects.ts
 /** The addresses each vendor sends the browser to after a sign-in; no browser can open them. Kept free of imports so the form schema can name them. */

package/dist/{account-integration-offline-BKDol6kz.mjs → account-integration-offline-B1Wgr_rT.mjs}

@@ -1,4 +1,4 @@
-import { X as errMsg } from "./bosch-instances-B2e4DAI1.mjs";
+import { Q as errMsg } from "./bosch-instances-CdvcBYye.mjs";
 import { randomBytes } from "node:crypto";
 //#region src/shared/sign-in-redirects.ts
 /** The addresses each vendor sends the browser to after a sign-in; no browser can open them. Kept free of imports so the form schema can name them. */

package/dist/{bosch-instances-BHFcR1TK.js → bosch-instances-CYBnIcHg.js}

@@ -102380,6 +102380,12 @@ Object.defineProperty(exports, "_enum", {
 		return _enum;
 	}
 });
+Object.defineProperty(exports, "_null", {
+	enumerable: true,
+	get: function() {
+		return _null;
+	}
+});
 Object.defineProperty(exports, "array", {
 	enumerable: true,
 	get: function() {
@@ -102398,6 +102404,12 @@ Object.defineProperty(exports, "binaryCapability", {
 		return binaryCapability;
 	}
 });
+Object.defineProperty(exports, "boolean", {
+	enumerable: true,
+	get: function() {
+		return boolean;
+	}
+});
 Object.defineProperty(exports, "boschRowsMigration", {
 	enumerable: true,
 	get: function() {

package/dist/{bosch-instances-B2e4DAI1.mjs → bosch-instances-CdvcBYye.mjs}

@@ -102326,4 +102326,4 @@ function keepBodyKeys(provider, keys) {
 	};
 }
 //#endregion
-export { RecordIntegrationInstances as A, array as B, powerMeterCapability as C, switchCapability as D, runningStateCapability as E, entryBody as F, string as G, number$1 as H, isSecretMarker as I, DeviceRole as J, union as K, isSecretMarkerLike as L, customAction as M, defineCustomActions as N, temperatureSensorCapability as O, defineEntryKind as P, rowsDepsOver as R, numericSensorCapability as S, runningFromDishwasherOperation as T, object as U, literal as V, record as W, errMsg as X, DeviceType as Y, EventCategory as Z, heatPumpControlCapability as _, BaseDevice as a, ingestReading as b, RUNNING_STATE_COLD as c, climateControlCapability as d, consumablesCapability as f, eventEmitterCapability as g, enumSensorCapability as h, testBoschInstance as i, createEvent as j, waterHeaterCapability as k, batteryCapability as l, dishwasherCapability as m, boschRowsPorts as n, BaseDeviceProvider as o, deviceAdoptionCapability as p, unknown as q, keepBodyKeys as r, DishwasherOperationStateSchema as s, boschRowsMigration as t, binaryCapability as u, heatPumpStatusCapability as v, quantityFromUnit as w, integrationInstancesCapability as x, heatingValveCapability as y, _enum as z };
+export { EventCategory as $, RecordIntegrationInstances as A, _null as B, powerMeterCapability as C, switchCapability as D, runningStateCapability as E, entryBody as F, object as G, boolean as H, isSecretMarker as I, union as J, record as K, isSecretMarkerLike as L, customAction as M, defineCustomActions as N, temperatureSensorCapability as O, defineEntryKind as P, errMsg as Q, rowsDepsOver as R, numericSensorCapability as S, runningFromDishwasherOperation as T, literal as U, array as V, number$1 as W, DeviceRole as X, unknown as Y, DeviceType as Z, heatPumpControlCapability as _, BaseDevice as a, ingestReading as b, RUNNING_STATE_COLD as c, climateControlCapability as d, consumablesCapability as f, eventEmitterCapability as g, enumSensorCapability as h, testBoschInstance as i, createEvent as j, waterHeaterCapability as k, batteryCapability as l, dishwasherCapability as m, boschRowsPorts as n, BaseDeviceProvider as o, deviceAdoptionCapability as p, string as q, keepBodyKeys as r, DishwasherOperationStateSchema as s, boschRowsMigration as t, binaryCapability as u, heatPumpStatusCapability as v, quantityFromUnit as w, integrationInstancesCapability as x, heatingValveCapability as y, _enum as z };

package/dist/home-connect/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_bosch_instances = require("../bosch-instances-BHFcR1TK.js");
-const require_account_integration_offline = require("../account-integration-offline-Dcx0sq_v.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-B2e4DAI1.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-BKDol6kz.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-BHFcR1TK.js");
-const require_account_integration_offline = require("../account-integration-offline-Dcx0sq_v.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
@@ -1592,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
+			};
 		}
 	};
 }
@@ -3095,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,
@@ -3121,7 +3514,8 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 				signOut: async () => ({
 					signedOut: true,
 					summary: "Signed out."
-				})
+				}),
+				exploreResources: explore
 			}
 		};
 	}

package/dist/homecom/addon.mjs

@@ -1,5 +1,5 @@
-import { A as RecordIntegrationInstances, B as array, F as entryBody, G as string, H as number, M as customAction, N as defineCustomActions, P as defineEntryKind, R as rowsDepsOver, U as object, V as literal, X as errMsg, Y as DeviceType, Z as EventCategory, _ as heatPumpControlCapability, a as BaseDevice, d as climateControlCapability, i as testBoschInstance, k as waterHeaterCapability, n as boschRowsPorts, o as BaseDeviceProvider, p as deviceAdoptionCapability, r as keepBodyKeys, t as boschRowsMigration, v as heatPumpStatusCapability, x as integrationInstancesCapability, z as _enum } from "../bosch-instances-B2e4DAI1.mjs";
-import { a as loginFailureForAttempt, i as createSignInAttemptStore, n as cascadeRemoveDevicesForIntegration, o as parseOAuthCallback, r as buildSignInGuideFields, s as HOMECOM_REDIRECT_URI, t as setIntegrationDevicesOnline } from "../account-integration-offline-BKDol6kz.mjs";
+import { $ as EventCategory, A as RecordIntegrationInstances, B as _null, F as entryBody, G as object, H as boolean, J as union, M as customAction, N as defineCustomActions, P as defineEntryKind, Q as errMsg, R as rowsDepsOver, U as literal, V as array, W as number, Z as DeviceType, _ as heatPumpControlCapability, a as BaseDevice, d as climateControlCapability, i as testBoschInstance, k as waterHeaterCapability, n as boschRowsPorts, o as BaseDeviceProvider, p as deviceAdoptionCapability, q as string, r as keepBodyKeys, t as boschRowsMigration, v as heatPumpStatusCapability, x as integrationInstancesCapability, z as _enum } from "../bosch-instances-CdvcBYye.mjs";
+import { a as loginFailureForAttempt, i as createSignInAttemptStore, n as cascadeRemoveDevicesForIntegration, o as parseOAuthCallback, r as buildSignInGuideFields, s as HOMECOM_REDIRECT_URI, t as setIntegrationDevicesOnline } from "../account-integration-offline-B1Wgr_rT.mjs";
 import { createHash, randomBytes } from "node:crypto";
 //#region src/homecom/config.ts
 var HOMECOM_BRANDS = ["bosch", "buderus"];
@@ -177,6 +177,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 = _enum([
+	"ok",
+	"forbidden",
+	"not-found",
+	"rate-limited",
+	"error"
+]);
+var exploredResourceSchema = object({
+	path: string(),
+	httpStatus: number(),
+	outcome: explorerOutcomeSchema,
+	type: string().optional(),
+	value: union([
+		string(),
+		number(),
+		boolean(),
+		_null()
+	]).optional(),
+	unit: string().optional(),
+	writeable: boolean().optional(),
+	recordable: boolean().optional(),
+	allowedValues: array(string()).optional(),
+	minValue: number().optional(),
+	maxValue: number().optional(),
+	childCount: number().optional(),
+	/** References of this container that were not a walkable path. */
+	droppedReferences: number().optional(),
+	error: string().optional()
+});
+var explorerSummarySchema = object({
+	ok: number(),
+	forbidden: number(),
+	"not-found": number(),
+	"rate-limited": number(),
+	error: number()
+});
+var explorerStopReasonSchema = _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 = object({
@@ -185,6 +459,27 @@ var gatewayChoice = object({
 	brand: HomeComBrandSchema,
 	region: HomeComRegionSchema
 });
+var exploreResourcesInput = object({
+	/** The HomeCom integration instance; may be omitted when exactly one is connected. */
+	integrationId: string().min(1).optional(),
+	root: string().refine(isResourcePath, "an absolute resource path such as /heatSources, no . or .. segment").optional(),
+	maxNodes: number().int().min(1).max(EXPLORER_MAX_NODES_CAP).optional(),
+	/** Wall-clock budget; the walk returns what it has, with `stoppedBy: 'deadline'`. */
+	deadlineMs: number().int().min(1e3).max(EXPLORER_MAX_DEADLINE_MS).optional()
+});
+var exploreResourcesOutput = object({
+	integrationId: string(),
+	/** Null when the integration has no snapshot yet: unknown, not empty. */
+	gatewayId: string().nullable(),
+	root: string(),
+	stoppedBy: explorerStopReasonSchema,
+	unvisited: number(),
+	unvisitedPaths: array(string()),
+	droppedReferences: number(),
+	droppedSamples: array(string()),
+	summary: explorerSummarySchema,
+	resources: array(exploredResourceSchema)
+});
 var homeComActions = defineCustomActions({
 	beginSignIn: customAction(object({}), object({
 		attemptId: string().min(1),
@@ -218,9 +513,95 @@ var homeComActions = defineCustomActions({
 	}), {
 		kind: "mutation",
 		auth: "admin"
+	}),
+	/** Read-only walk of the gateway's resource tree, for diagnosing what it serves. */
+	exploreResources: 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
@@ -1591,6 +1972,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
+			};
 		}
 	};
 }
@@ -3094,6 +3482,11 @@ var BoschHomeComProviderAddon = class extends BaseDeviceProvider {
 		});
 		await this.reconcileIntegrations();
 		this.subscribeIntegrationLifecycle();
+		const explore = createHomeComExploreAction(homeComExploreDeps({
+			registry: this.clients,
+			connections: homeComConnections,
+			logger: this.ctx.logger
+		}));
 		return {
 			providers: [
 				...regs,
@@ -3120,7 +3513,8 @@ var BoschHomeComProviderAddon = class extends BaseDeviceProvider {
 				signOut: async () => ({
 					signedOut: true,
 					summary: "Signed out."
-				})
+				}),
+				exploreResources: explore
 			}
 		};
 	}

package/dist/shc/addon.js

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
-const require_bosch_instances = require("../bosch-instances-BHFcR1TK.js");
+const require_bosch_instances = require("../bosch-instances-CYBnIcHg.js");
 let node_crypto = require("node:crypto");
 let node_https = require("node:https");
 let node_child_process = require("node:child_process");

package/dist/shc/addon.mjs

@@ -1,4 +1,4 @@
-import { A as RecordIntegrationInstances, B as array, D as switchCapability, F as entryBody, G as string, H as number, M as customAction, N as defineCustomActions, O as temperatureSensorCapability, P as defineEntryKind, R as rowsDepsOver, U as object, V as literal, X as errMsg, Y as DeviceType, Z as EventCategory, a as BaseDevice, d as climateControlCapability, i as testBoschInstance, l as batteryCapability, n as boschRowsPorts, o as BaseDeviceProvider, p as deviceAdoptionCapability, r as keepBodyKeys, t as boschRowsMigration, x as integrationInstancesCapability, y as heatingValveCapability, z as _enum } from "../bosch-instances-B2e4DAI1.mjs";
+import { $ as EventCategory, A as RecordIntegrationInstances, D as switchCapability, F as entryBody, G as object, M as customAction, N as defineCustomActions, O as temperatureSensorCapability, P as defineEntryKind, Q as errMsg, R as rowsDepsOver, U as literal, V as array, W as number, Z as DeviceType, a as BaseDevice, d as climateControlCapability, i as testBoschInstance, l as batteryCapability, n as boschRowsPorts, o as BaseDeviceProvider, p as deviceAdoptionCapability, q as string, r as keepBodyKeys, t as boschRowsMigration, x as integrationInstancesCapability, y as heatingValveCapability, z as _enum } from "../bosch-instances-CdvcBYye.mjs";
 import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import { request } from "node:https";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-bosch",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Bosch smart-home device-provider addons for CamStack — SHC, Home Connect, and HomeCom cloud integrations (scaffold)",
   "keywords": [
     "camstack",