tesla-fleet-api 0.3.0 → 0.5.0

package/dist/powerwall/gateway.cjs

@@ -0,0 +1,102 @@
+const require_energyparsers = require("../energyparsers.cjs");
+const require_client = require("./client.cjs");
+const require_exceptions = require("./exceptions.cjs");
+// src/powerwall/gateway.ts
+function createClient(options, legacy_gateway) {
+	return legacy_gateway ? require_client.PowerwallClient.legacy_gateway(options) : new require_client.PowerwallClient(options);
+}
+/**
+* Connect at the stored host, and if that fails ask the cloud where the gateway
+* is. Any error is a lead, because another device may have taken the address.
+*
+* Certificate checks are off and a login sends the password, so the reported
+* address is not trusted: anything outside a private or link-local range gets no
+* request at all. A gateway whose DIN is not the expected one is refused after
+* login, because the DIN read needs a token.
+*
+* Every outcome returns a client, so the caller still builds the router. A stale
+* client's calls fail with `PowerwallConnectionError` and go to the cloud, so a
+* site degrades to cloud control and does not break.
+*
+* @throws PowerwallAuthenticationError for a bad PEM, which no address can repair.
+*/
+async function connect_gateway(options) {
+	const { cloud, legacy_gateway, allow_address = require_energyparsers.is_lan_address } = options;
+	const clientOptions = {
+		...options.client,
+		expectedDin: options.client.expectedDin ?? cloud.din
+	};
+	const stored = clientOptions.host ?? "192.168.91.1";
+	const client = createClient(clientOptions, legacy_gateway);
+	let error;
+	try {
+		await client.connect();
+		return {
+			client,
+			host: stored,
+			outcome: "connected"
+		};
+	} catch (caught) {
+		if (!(caught instanceof require_exceptions.PowerwallError)) throw caught;
+		if (caught instanceof require_exceptions.PowerwallRateLimitError) return {
+			client,
+			host: stored,
+			outcome: "rate_limited",
+			error: caught
+		};
+		error = caught;
+	}
+	let address = null;
+	try {
+		address = await cloud.find_gateway_address();
+	} catch {}
+	if (address === stored && !(error instanceof require_exceptions.PowerwallConnectionError)) return {
+		client,
+		host: stored,
+		outcome: "refused",
+		error
+	};
+	if (address != null && address !== stored && allow_address(address)) {
+		const moved = createClient({
+			...clientOptions,
+			host: address
+		}, legacy_gateway);
+		try {
+			await moved.connect();
+			client.close();
+			return {
+				client: moved,
+				host: address,
+				outcome: "moved"
+			};
+		} catch (caught) {
+			moved.close();
+			if (!(caught instanceof require_exceptions.PowerwallError)) throw caught;
+		}
+	}
+	return {
+		client,
+		host: stored,
+		outcome: "not_found",
+		error
+	};
+}
+/**
+* Prove a stored password and key against the gateway. A login proves the
+* password and a signed read proves the key: they are independent.
+*
+* @throws PowerwallAuthenticationError when the password is wrong.
+* @throws PowerwallKeyRejectedError when the password worked and the key did not.
+* @throws Any other `PowerwallError` when the gateway cannot be reached.
+*/
+async function verify_local_gateway(client) {
+	await client.connect();
+	try {
+		await client.get_status();
+	} catch (error) {
+		if (error instanceof require_exceptions.PowerwallAuthenticationError) throw new require_exceptions.PowerwallKeyRejectedError("The gateway accepted the password but not the signing key", { cause: error });
+		throw error;
+	}
+}
+exports.connect_gateway = connect_gateway;
+exports.verify_local_gateway = verify_local_gateway;

package/dist/powerwall/gateway.d.cts

@@ -0,0 +1,57 @@
+import { PowerwallClient, PowerwallClientOptions } from "./client.cjs";
+import { PowerwallError } from "./exceptions.cjs";
+export type GatewayOutcome =
+/** Connected at the stored host. */
+"connected" |
+/** The gateway answered 429 or 503: it is there, so there is nothing to repair. */
+"rate_limited" |
+/** Connected at a new host. The caller must persist `host`: nothing here does. */
+"moved" |
+/** The cloud confirms this address and the gateway refused us. A wrong password lands here. */
+"refused" |
+/** No usable address. The caller should offer a repair. */
+"not_found";
+export type ConnectGatewayOptions = {
+  client: PowerwallClientOptions;
+  /** A cloud site, or anything that can report the gateway's address. Its `din`, when set, is the DIN to expect. */
+  cloud: {
+    find_gateway_address(): Promise<string | null>;
+    din?: string;
+  };
+  /** Use `PowerwallClient.legacy_gateway` for an early Gateway 1 unit. */
+  legacy_gateway?: boolean;
+  /** Which reported addresses may receive the password. Defaults to private and link-local IPv4. */
+  allow_address?: (address: string) => boolean;
+};
+export type ConnectGatewayResult = {
+  client: PowerwallClient;
+  host: string;
+  outcome: GatewayOutcome;
+  /** Why the stored host did not connect. Absent for `connected` and `moved`. */
+  error?: PowerwallError;
+};
+/**
+ * Connect at the stored host, and if that fails ask the cloud where the gateway
+ * is. Any error is a lead, because another device may have taken the address.
+ *
+ * Certificate checks are off and a login sends the password, so the reported
+ * address is not trusted: anything outside a private or link-local range gets no
+ * request at all. A gateway whose DIN is not the expected one is refused after
+ * login, because the DIN read needs a token.
+ *
+ * Every outcome returns a client, so the caller still builds the router. A stale
+ * client's calls fail with `PowerwallConnectionError` and go to the cloud, so a
+ * site degrades to cloud control and does not break.
+ *
+ * @throws PowerwallAuthenticationError for a bad PEM, which no address can repair.
+ */
+export declare function connect_gateway(options: ConnectGatewayOptions): Promise<ConnectGatewayResult>;
+/**
+ * Prove a stored password and key against the gateway. A login proves the
+ * password and a signed read proves the key: they are independent.
+ *
+ * @throws PowerwallAuthenticationError when the password is wrong.
+ * @throws PowerwallKeyRejectedError when the password worked and the key did not.
+ * @throws Any other `PowerwallError` when the gateway cannot be reached.
+ */
+export declare function verify_local_gateway(client: PowerwallClient): Promise<void>;

package/dist/powerwall/gateway.d.mts

@@ -0,0 +1,57 @@
+import { PowerwallClient, PowerwallClientOptions } from "./client.mjs";
+import { PowerwallError } from "./exceptions.mjs";
+export type GatewayOutcome =
+/** Connected at the stored host. */
+"connected" |
+/** The gateway answered 429 or 503: it is there, so there is nothing to repair. */
+"rate_limited" |
+/** Connected at a new host. The caller must persist `host`: nothing here does. */
+"moved" |
+/** The cloud confirms this address and the gateway refused us. A wrong password lands here. */
+"refused" |
+/** No usable address. The caller should offer a repair. */
+"not_found";
+export type ConnectGatewayOptions = {
+  client: PowerwallClientOptions;
+  /** A cloud site, or anything that can report the gateway's address. Its `din`, when set, is the DIN to expect. */
+  cloud: {
+    find_gateway_address(): Promise<string | null>;
+    din?: string;
+  };
+  /** Use `PowerwallClient.legacy_gateway` for an early Gateway 1 unit. */
+  legacy_gateway?: boolean;
+  /** Which reported addresses may receive the password. Defaults to private and link-local IPv4. */
+  allow_address?: (address: string) => boolean;
+};
+export type ConnectGatewayResult = {
+  client: PowerwallClient;
+  host: string;
+  outcome: GatewayOutcome;
+  /** Why the stored host did not connect. Absent for `connected` and `moved`. */
+  error?: PowerwallError;
+};
+/**
+ * Connect at the stored host, and if that fails ask the cloud where the gateway
+ * is. Any error is a lead, because another device may have taken the address.
+ *
+ * Certificate checks are off and a login sends the password, so the reported
+ * address is not trusted: anything outside a private or link-local range gets no
+ * request at all. A gateway whose DIN is not the expected one is refused after
+ * login, because the DIN read needs a token.
+ *
+ * Every outcome returns a client, so the caller still builds the router. A stale
+ * client's calls fail with `PowerwallConnectionError` and go to the cloud, so a
+ * site degrades to cloud control and does not break.
+ *
+ * @throws PowerwallAuthenticationError for a bad PEM, which no address can repair.
+ */
+export declare function connect_gateway(options: ConnectGatewayOptions): Promise<ConnectGatewayResult>;
+/**
+ * Prove a stored password and key against the gateway. A login proves the
+ * password and a signed read proves the key: they are independent.
+ *
+ * @throws PowerwallAuthenticationError when the password is wrong.
+ * @throws PowerwallKeyRejectedError when the password worked and the key did not.
+ * @throws Any other `PowerwallError` when the gateway cannot be reached.
+ */
+export declare function verify_local_gateway(client: PowerwallClient): Promise<void>;

package/dist/powerwall/gateway.mjs

@@ -0,0 +1,101 @@
+import { is_lan_address } from "../energyparsers.mjs";
+import { PowerwallClient } from "./client.mjs";
+import { PowerwallAuthenticationError, PowerwallConnectionError, PowerwallError, PowerwallKeyRejectedError, PowerwallRateLimitError } from "./exceptions.mjs";
+// src/powerwall/gateway.ts
+function createClient(options, legacy_gateway) {
+	return legacy_gateway ? PowerwallClient.legacy_gateway(options) : new PowerwallClient(options);
+}
+/**
+* Connect at the stored host, and if that fails ask the cloud where the gateway
+* is. Any error is a lead, because another device may have taken the address.
+*
+* Certificate checks are off and a login sends the password, so the reported
+* address is not trusted: anything outside a private or link-local range gets no
+* request at all. A gateway whose DIN is not the expected one is refused after
+* login, because the DIN read needs a token.
+*
+* Every outcome returns a client, so the caller still builds the router. A stale
+* client's calls fail with `PowerwallConnectionError` and go to the cloud, so a
+* site degrades to cloud control and does not break.
+*
+* @throws PowerwallAuthenticationError for a bad PEM, which no address can repair.
+*/
+async function connect_gateway(options) {
+	const { cloud, legacy_gateway, allow_address = is_lan_address } = options;
+	const clientOptions = {
+		...options.client,
+		expectedDin: options.client.expectedDin ?? cloud.din
+	};
+	const stored = clientOptions.host ?? "192.168.91.1";
+	const client = createClient(clientOptions, legacy_gateway);
+	let error;
+	try {
+		await client.connect();
+		return {
+			client,
+			host: stored,
+			outcome: "connected"
+		};
+	} catch (caught) {
+		if (!(caught instanceof PowerwallError)) throw caught;
+		if (caught instanceof PowerwallRateLimitError) return {
+			client,
+			host: stored,
+			outcome: "rate_limited",
+			error: caught
+		};
+		error = caught;
+	}
+	let address = null;
+	try {
+		address = await cloud.find_gateway_address();
+	} catch {}
+	if (address === stored && !(error instanceof PowerwallConnectionError)) return {
+		client,
+		host: stored,
+		outcome: "refused",
+		error
+	};
+	if (address != null && address !== stored && allow_address(address)) {
+		const moved = createClient({
+			...clientOptions,
+			host: address
+		}, legacy_gateway);
+		try {
+			await moved.connect();
+			client.close();
+			return {
+				client: moved,
+				host: address,
+				outcome: "moved"
+			};
+		} catch (caught) {
+			moved.close();
+			if (!(caught instanceof PowerwallError)) throw caught;
+		}
+	}
+	return {
+		client,
+		host: stored,
+		outcome: "not_found",
+		error
+	};
+}
+/**
+* Prove a stored password and key against the gateway. A login proves the
+* password and a signed read proves the key: they are independent.
+*
+* @throws PowerwallAuthenticationError when the password is wrong.
+* @throws PowerwallKeyRejectedError when the password worked and the key did not.
+* @throws Any other `PowerwallError` when the gateway cannot be reached.
+*/
+async function verify_local_gateway(client) {
+	await client.connect();
+	try {
+		await client.get_status();
+	} catch (error) {
+		if (error instanceof PowerwallAuthenticationError) throw new PowerwallKeyRejectedError("The gateway accepted the password but not the signing key", { cause: error });
+		throw error;
+	}
+}
+export { connect_gateway, verify_local_gateway };

package/dist/powerwall/merge.cjs

@@ -0,0 +1,163 @@
+const require_energysite = require("../router/energysite.cjs");
+const require_exceptions = require("./exceptions.cjs");
+// src/powerwall/merge.ts
+/** How often to call `LiveStatusMerge.poll()`. */
+const ENERGY_LIVE_INTERVAL_MS = 5e3;
+/** The longest `LiveStatusMerge` waits between local attempts after failures. */
+const ENERGY_LIVE_LOCAL_MAX_BACKOFF_MS = 6e4;
+/** How often to call `SiteInfoMerge.poll()`. */
+const ENERGY_CONFIG_INTERVAL_MS = 3e4;
+const MAX_BACKOFF_TICKS = ENERGY_LIVE_LOCAL_MAX_BACKOFF_MS / ENERGY_LIVE_INTERVAL_MS;
+/**
+* Keeps the latest cloud `live_status` and local reading, and re-merges on either
+* update. The cloud never clobbers a healthy local key, and a failed poll clears
+* the local reading, so everything falls back to cloud values rather than to
+* unavailable. All documents are unwrapped: the value under `response`.
+*
+* A failed poll never changes availability by itself. `poll()` resolves on a
+* `PowerwallError` and rejects on anything else, which is a bug, so attach a
+* rejection handler.
+*/
+var LiveStatusMerge = class {
+	#site;
+	#owned_keys;
+	#cloud;
+	#local = null;
+	#healthy = null;
+	#last_error = null;
+	#polling = false;
+	#backoff_ticks = 1;
+	#ticks_to_skip = 0;
+	constructor(local, cloud, options = {}) {
+		this.#site = local;
+		this.#cloud = cloud;
+		this.#owned_keys = options.owned_keys ?? require_energysite.LOCAL_LIVE_STATUS_KEYS;
+	}
+	/** The cloud document with the local reading overlaid. */
+	get merged() {
+		return require_energysite.merge_local_into_cloud(this.#cloud, this.#local, this.#owned_keys);
+	}
+	/** True after a successful poll, false after a failed one, null before the first. */
+	get healthy() {
+		return this.#healthy;
+	}
+	/** The error from the last poll, or null after a success. */
+	get last_error() {
+		return this.#last_error;
+	}
+	/** Store a cloud document and return the merged view. */
+	set_cloud(cloud) {
+		this.#cloud = cloud;
+		return this.merged;
+	}
+	/** One 5 s tick. Returns the merged view, or null when the tick was skipped. */
+	async poll() {
+		if (this.#polling) return null;
+		if (this.#ticks_to_skip > 0) {
+			this.#ticks_to_skip--;
+			return null;
+		}
+		this.#polling = true;
+		try {
+			this.#local = (await this.#site.live_status()).response;
+			this.#backoff_ticks = 1;
+			this.#healthy = true;
+			this.#last_error = null;
+		} catch (error) {
+			if (!(error instanceof require_exceptions.PowerwallError)) throw error;
+			this.#local = null;
+			this.#backoff_ticks = Math.min(this.#backoff_ticks * 2, MAX_BACKOFF_TICKS);
+			this.#ticks_to_skip = this.#backoff_ticks - 1;
+			this.#healthy = false;
+			this.#last_error = error;
+		} finally {
+			this.#polling = false;
+		}
+		return this.merged;
+	}
+};
+/**
+* Keeps the latest cloud `site_info` and local `config.json` view, and holds a
+* command's value until its source next reports it, so neither a poll that
+* straddles the command nor a failed poll reverts what the user just set. All
+* documents are unwrapped: the value under `response`.
+*
+* `poll()` resolves on a `PowerwallError` and rejects on anything else, which is a
+* bug, so attach a rejection handler.
+*/
+var SiteInfoMerge = class {
+	#site;
+	#owned_keys;
+	#cloud;
+	#local = null;
+	#held = {};
+	#generation = 0;
+	#healthy = null;
+	#last_error = null;
+	#polling = false;
+	constructor(local, cloud, options = {}) {
+		this.#site = local;
+		this.#cloud = cloud;
+		this.#owned_keys = options.owned_keys ?? require_energysite.LOCAL_SITE_INFO_KEYS;
+	}
+	/** The cloud document with held values, then the local view, overlaid. */
+	get merged() {
+		return require_energysite.merge_local_into_cloud({
+			...this.#cloud,
+			...this.#held
+		}, this.#local, this.#owned_keys);
+	}
+	/** True after a successful read, false after a failed one, null before the first. */
+	get healthy() {
+		return this.#healthy;
+	}
+	/** The error from the last read, or null after a success. */
+	get last_error() {
+		return this.#last_error;
+	}
+	/** Store a cloud document, which reports every held value, and return the merged view. */
+	set_cloud(cloud) {
+		this.#cloud = cloud;
+		this.#held = {};
+		return this.merged;
+	}
+	/** One 30 s tick. Returns the merged view, or null when the tick was skipped or its read discarded. */
+	async poll() {
+		if (this.#polling) return null;
+		const generation = this.#generation;
+		this.#polling = true;
+		let local = null;
+		try {
+			local = await this.#site.local_config();
+			this.#healthy = true;
+			this.#last_error = null;
+		} catch (error) {
+			if (!(error instanceof require_exceptions.PowerwallError)) throw error;
+			this.#healthy = false;
+			this.#last_error = error;
+		} finally {
+			this.#polling = false;
+		}
+		if (generation !== this.#generation) return null;
+		this.#local = local;
+		for (const key of this.#owned_keys) if (local?.[key] !== void 0 && local[key] !== null) delete this.#held[key];
+		return this.merged;
+	}
+	/** Hold a successful command's value until its source next reports it. */
+	hold_command_value(key, value) {
+		if (this.#owned_keys.includes(key)) {
+			this.#local = {
+				...this.#local,
+				[key]: value
+			};
+			this.#generation++;
+		}
+		this.#held[key] = value;
+		return this.merged;
+	}
+};
+exports.ENERGY_CONFIG_INTERVAL_MS = ENERGY_CONFIG_INTERVAL_MS;
+exports.ENERGY_LIVE_INTERVAL_MS = ENERGY_LIVE_INTERVAL_MS;
+exports.ENERGY_LIVE_LOCAL_MAX_BACKOFF_MS = ENERGY_LIVE_LOCAL_MAX_BACKOFF_MS;
+exports.LiveStatusMerge = LiveStatusMerge;
+exports.SiteInfoMerge = SiteInfoMerge;

package/dist/powerwall/merge.d.cts

@@ -0,0 +1,63 @@
+import { LiveStatusResponse } from "../types/live_status.cjs";
+import { SiteInfoResponse } from "../types/site_info.cjs";
+import { PowerwallEnergySite } from "./energysite.cjs";
+import { PowerwallError } from "./exceptions.cjs";
+/** How often to call `LiveStatusMerge.poll()`. */
+export declare const ENERGY_LIVE_INTERVAL_MS = 5000;
+/** The longest `LiveStatusMerge` waits between local attempts after failures. */
+export declare const ENERGY_LIVE_LOCAL_MAX_BACKOFF_MS = 60000;
+/** How often to call `SiteInfoMerge.poll()`. */
+export declare const ENERGY_CONFIG_INTERVAL_MS = 30000;
+export type MergeOptions = {
+  /** The keys local overlays. Homey passes the live list without `island_status`. */
+  owned_keys?: readonly string[];
+};
+/**
+ * Keeps the latest cloud `live_status` and local reading, and re-merges on either
+ * update. The cloud never clobbers a healthy local key, and a failed poll clears
+ * the local reading, so everything falls back to cloud values rather than to
+ * unavailable. All documents are unwrapped: the value under `response`.
+ *
+ * A failed poll never changes availability by itself. `poll()` resolves on a
+ * `PowerwallError` and rejects on anything else, which is a bug, so attach a
+ * rejection handler.
+ */
+export declare class LiveStatusMerge {
+  #private;
+  constructor(local: Pick<PowerwallEnergySite, "live_status">, cloud: LiveStatusResponse, options?: MergeOptions);
+  /** The cloud document with the local reading overlaid. */
+  get merged(): LiveStatusResponse;
+  /** True after a successful poll, false after a failed one, null before the first. */
+  get healthy(): boolean | null;
+  /** The error from the last poll, or null after a success. */
+  get last_error(): PowerwallError | null;
+  /** Store a cloud document and return the merged view. */
+  set_cloud(cloud: LiveStatusResponse): LiveStatusResponse;
+  /** One 5 s tick. Returns the merged view, or null when the tick was skipped. */
+  poll(): Promise<LiveStatusResponse | null>;
+}
+/**
+ * Keeps the latest cloud `site_info` and local `config.json` view, and holds a
+ * command's value until its source next reports it, so neither a poll that
+ * straddles the command nor a failed poll reverts what the user just set. All
+ * documents are unwrapped: the value under `response`.
+ *
+ * `poll()` resolves on a `PowerwallError` and rejects on anything else, which is a
+ * bug, so attach a rejection handler.
+ */
+export declare class SiteInfoMerge {
+  #private;
+  constructor(local: Pick<PowerwallEnergySite, "local_config">, cloud: SiteInfoResponse, options?: MergeOptions);
+  /** The cloud document with held values, then the local view, overlaid. */
+  get merged(): SiteInfoResponse;
+  /** True after a successful read, false after a failed one, null before the first. */
+  get healthy(): boolean | null;
+  /** The error from the last read, or null after a success. */
+  get last_error(): PowerwallError | null;
+  /** Store a cloud document, which reports every held value, and return the merged view. */
+  set_cloud(cloud: SiteInfoResponse): SiteInfoResponse;
+  /** One 30 s tick. Returns the merged view, or null when the tick was skipped or its read discarded. */
+  poll(): Promise<SiteInfoResponse | null>;
+  /** Hold a successful command's value until its source next reports it. */
+  hold_command_value(key: string, value: unknown): SiteInfoResponse;
+}

package/dist/powerwall/merge.d.mts

@@ -0,0 +1,63 @@
+import { LiveStatusResponse } from "../types/live_status.mjs";
+import { SiteInfoResponse } from "../types/site_info.mjs";
+import { PowerwallEnergySite } from "./energysite.mjs";
+import { PowerwallError } from "./exceptions.mjs";
+/** How often to call `LiveStatusMerge.poll()`. */
+export declare const ENERGY_LIVE_INTERVAL_MS = 5000;
+/** The longest `LiveStatusMerge` waits between local attempts after failures. */
+export declare const ENERGY_LIVE_LOCAL_MAX_BACKOFF_MS = 60000;
+/** How often to call `SiteInfoMerge.poll()`. */
+export declare const ENERGY_CONFIG_INTERVAL_MS = 30000;
+export type MergeOptions = {
+  /** The keys local overlays. Homey passes the live list without `island_status`. */
+  owned_keys?: readonly string[];
+};
+/**
+ * Keeps the latest cloud `live_status` and local reading, and re-merges on either
+ * update. The cloud never clobbers a healthy local key, and a failed poll clears
+ * the local reading, so everything falls back to cloud values rather than to
+ * unavailable. All documents are unwrapped: the value under `response`.
+ *
+ * A failed poll never changes availability by itself. `poll()` resolves on a
+ * `PowerwallError` and rejects on anything else, which is a bug, so attach a
+ * rejection handler.
+ */
+export declare class LiveStatusMerge {
+  #private;
+  constructor(local: Pick<PowerwallEnergySite, "live_status">, cloud: LiveStatusResponse, options?: MergeOptions);
+  /** The cloud document with the local reading overlaid. */
+  get merged(): LiveStatusResponse;
+  /** True after a successful poll, false after a failed one, null before the first. */
+  get healthy(): boolean | null;
+  /** The error from the last poll, or null after a success. */
+  get last_error(): PowerwallError | null;
+  /** Store a cloud document and return the merged view. */
+  set_cloud(cloud: LiveStatusResponse): LiveStatusResponse;
+  /** One 5 s tick. Returns the merged view, or null when the tick was skipped. */
+  poll(): Promise<LiveStatusResponse | null>;
+}
+/**
+ * Keeps the latest cloud `site_info` and local `config.json` view, and holds a
+ * command's value until its source next reports it, so neither a poll that
+ * straddles the command nor a failed poll reverts what the user just set. All
+ * documents are unwrapped: the value under `response`.
+ *
+ * `poll()` resolves on a `PowerwallError` and rejects on anything else, which is a
+ * bug, so attach a rejection handler.
+ */
+export declare class SiteInfoMerge {
+  #private;
+  constructor(local: Pick<PowerwallEnergySite, "local_config">, cloud: SiteInfoResponse, options?: MergeOptions);
+  /** The cloud document with held values, then the local view, overlaid. */
+  get merged(): SiteInfoResponse;
+  /** True after a successful read, false after a failed one, null before the first. */
+  get healthy(): boolean | null;
+  /** The error from the last read, or null after a success. */
+  get last_error(): PowerwallError | null;
+  /** Store a cloud document, which reports every held value, and return the merged view. */
+  set_cloud(cloud: SiteInfoResponse): SiteInfoResponse;
+  /** One 30 s tick. Returns the merged view, or null when the tick was skipped or its read discarded. */
+  poll(): Promise<SiteInfoResponse | null>;
+  /** Hold a successful command's value until its source next reports it. */
+  hold_command_value(key: string, value: unknown): SiteInfoResponse;
+}