tesla-fleet-api 0.3.0 → 0.5.0

package/dist/powerwall/client.cjs

@@ -0,0 +1,818 @@
+const require_exceptions = require("./exceptions.cjs");
+const require_energyisland = require("../energyisland.cjs");
+const require_energyspecific = require("../energyspecific.cjs");
+const require_queries = require("./queries.cjs");
+const require_transport = require("./transport.cjs");
+let _teslemetry_tesla_protocol_energy_device_transport = require("@teslemetry/tesla-protocol/energy_device/transport");
+let _teslemetry_tesla_protocol_energy_device_teg_api = require("@teslemetry/tesla-protocol/energy_device/teg_api");
+let _teslemetry_tesla_protocol_energy_device_authorization_types = require("@teslemetry/tesla-protocol/energy_device/authorization_types");
+let _teslemetry_tesla_protocol_energy_device_common_api = require("@teslemetry/tesla-protocol/energy_device/common_api");
+let _teslemetry_tesla_protocol_energy_device_filestore_api = require("@teslemetry/tesla-protocol/energy_device/filestore_api");
+let _teslemetry_tesla_protocol_energy_device_graphql_api = require("@teslemetry/tesla-protocol/energy_device/graphql_api");
+let _teslemetry_tesla_protocol_energy_device_local_auth_api = require("@teslemetry/tesla-protocol/energy_device/local_auth_api");
+// src/powerwall/client.ts
+/** The gateway's own Wi-Fi access point. */
+const DEFAULT_GATEWAY_HOST = "192.168.91.1";
+/** Values of `default_real_mode`. Each sticks and reads back verbatim on a Powerwall 3. */
+const OPERATION_MODES = [
+	"self_consumption",
+	"autonomous",
+	"backup"
+];
+/** Values of `site_info.customer_preferred_export_rule`. Each sticks and reads back verbatim on a Powerwall 3. */
+const GRID_EXPORT_RULES = [
+	"battery_ok",
+	"pv_only",
+	"never"
+];
+/** The default length of a manual backup event, and the shortest the gateway takes. */
+const DEFAULT_BACKUP_DURATION_SECONDS = 7200;
+const MIN_BACKUP_DURATION_SECONDS = 60;
+/** `2^64 - 1`, which pre-empts any other event. A string because it does not fit a JS number. */
+const MAX_PRIORITY = "18446744073709551615";
+const MAX_UINT32 = 2 ** 32 - 1;
+/** `google.rpc.Code.UNIMPLEMENTED`, for a command the firmware does not implement. */
+const STATUS_UNIMPLEMENTED = 12;
+/** `google.rpc.Code.NOT_FOUND`: a cancel with no active event to cancel. */
+const STATUS_NOT_FOUND = 5;
+/** The bottom 5% of both scales is an inaccessible buffer: `raw = scaled * 0.95 + 5`. */
+const SCALE = .95;
+const OFFSET = 5;
+const CONFIG_FILE = "config.json";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Walk nested objects; `undefined` if any step is missing. */
+function lookup(data, ...keys) {
+	return keys.reduce((value, key) => isRecord(value) ? value[key] : void 0, data);
+}
+/** Round to 4 decimal places. Within 0.0001 of Python's `round` on exact binary ties. */
+function round4(value) {
+	return Number(value.toFixed(4));
+}
+/**
+* Enum name with `prefix` removed. A firmware newer than this package can
+* report a number with no name: that comes back as the number, and never throws.
+*/
+function enumSuffix(toJSON, value, prefix) {
+	const name = toJSON(value);
+	return name === "UNRECOGNIZED" ? value : name.slice(prefix.length);
+}
+function seconds(date) {
+	return Math.floor(date.getTime() / 1e3);
+}
+function base64(bytes) {
+	return Buffer.from(bytes).toString("base64");
+}
+function parseJsonObject(text, what) {
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch (error) {
+		throw new require_exceptions.PowerwallProtocolError(`${what} payload is not valid JSON`, { cause: error });
+	}
+	if (!isRecord(data)) throw new require_exceptions.PowerwallProtocolError(`${what} payload is not an object`);
+	return data;
+}
+function decodeConfig(blob) {
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(blob);
+	} catch (error) {
+		throw new require_exceptions.PowerwallProtocolError("config.json blob is not UTF-8", { cause: error });
+	}
+	return parseJsonObject(text, "config.json");
+}
+/** Set a dotted path in `config`. A missing or non-object step becomes `{}`. */
+function applyDottedUpdate(config, dottedPath, value) {
+	const keys = dottedPath.split(".");
+	const last = keys.pop();
+	let target = config;
+	for (const key of keys) {
+		const existing = Object.hasOwn(target, key) ? target[key] : void 0;
+		target = isRecord(existing) ? existing : target[key] = {};
+	}
+	target[last] = value;
+}
+function requireNonEmptyString(value, name) {
+	if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+	if (!value) throw new RangeError(`${name} must not be empty`);
+}
+function requireNonNegative(value, name) {
+	if (typeof value !== "number") throw new TypeError(`${name} must be a number`);
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`${name} must be a finite, non-negative number`);
+}
+/** `JSON.stringify` writes a non-finite number as `null`, so reject one at any depth rather than store it. */
+function requireFiniteNumbers(value, name) {
+	if (typeof value === "number" && !Number.isFinite(value)) throw new RangeError(`${name} must be finite`);
+	if (typeof value === "object" && value !== null) for (const [key, item] of Object.entries(value)) requireFiniteNumbers(item, `${name}.${key}`);
+}
+function requireIntegerInRange(value, name, minimum, maximum) {
+	if (typeof value !== "number") throw new TypeError(`${name} must be a number`);
+	if (!Number.isInteger(value) || value < minimum || value > maximum) throw new RangeError(`${name} must be an integer from ${minimum} to ${maximum}`);
+}
+function decodeEnvelope(inner, what) {
+	try {
+		return _teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.decode(inner);
+	} catch (error) {
+		throw new require_exceptions.PowerwallProtocolError(`Malformed ${what} response`, { cause: error });
+	}
+}
+/** True when a reply's categories, such as `teg`, hold no message. The header says nothing about the command. */
+function isEmptyReply(reply) {
+	const { deliveryChannel: _channel, sender: _sender, recipient: _recipient, ...categories } = reply;
+	return Object.values(categories).every((category) => category === void 0 || isRecord(category) && Object.values(category).every((item) => item === void 0));
+}
+/** Header for the `filestore`, `teg` and `authorization` messages. */
+function commandHeader(din) {
+	return {
+		deliveryChannel: _teslemetry_tesla_protocol_energy_device_transport.DeliveryChannel.DELIVERY_CHANNEL_HERMES_COMMAND,
+		sender: { authorizedClient: _teslemetry_tesla_protocol_energy_device_authorization_types.AuthorizedClientType.AUTHORIZED_CLIENT_TYPE_CUSTOMER_MOBILE_APP },
+		recipient: { din }
+	};
+}
+/** Header for GraphQL and system-info reads, sent as a local installer. */
+function localHeader(din) {
+	return {
+		deliveryChannel: _teslemetry_tesla_protocol_energy_device_transport.DeliveryChannel.DELIVERY_CHANNEL_LOCAL_HTTPS,
+		sender: { local: _teslemetry_tesla_protocol_energy_device_local_auth_api.LocalParticipant.LOCAL_PARTICIPANT_INSTALLER },
+		recipient: { din }
+	};
+}
+function programBoundary(boundary) {
+	if (boundary === void 0) return null;
+	return {
+		static_condition: enumSuffix(_teslemetry_tesla_protocol_energy_device_teg_api.controllableDeviceProgramScheduleBoundary_StaticConditionToJSON, boundary.staticCondition, "STATIC_CONDITION_"),
+		timestamp: boundary.timestamp ? seconds(boundary.timestamp) : null,
+		islanding_state: enumSuffix(_teslemetry_tesla_protocol_energy_device_teg_api.controllableDeviceProgramScheduleBoundary_IslandingStateToJSON, boundary.islandingState, "ISLANDING_STATE_"),
+		state_of_energy: enumSuffix(_teslemetry_tesla_protocol_energy_device_teg_api.controllableDeviceProgramScheduleBoundary_StateOfEnergyToJSON, boundary.stateOfEnergy, "STATE_OF_ENERGY_")
+	};
+}
+function controllableProgram(program) {
+	return {
+		key: {
+			device_id: program.key?.deviceId ?? "",
+			priority: enumSuffix(_teslemetry_tesla_protocol_energy_device_teg_api.controllableDeviceProgramKey_PriorityToJSON, program.key?.priority ?? 0, "PRIORITY_")
+		},
+		settings: { contactor_state: enumSuffix(_teslemetry_tesla_protocol_energy_device_teg_api.controllableDeviceProgramSettings_ContactorStateToJSON, program.settings?.contactorState ?? 0, "CONTACTOR_STATE_") },
+		schedule: {
+			start: programBoundary(program.schedule?.start),
+			end: programBoundary(program.schedule?.end),
+			expiry: programBoundary(program.schedule?.expiry)
+		}
+	};
+}
+function authorizedClient(record) {
+	return {
+		public_key: base64(record.publicKey),
+		state: enumSuffix(_teslemetry_tesla_protocol_energy_device_authorization_types.authorizedStateToJSON, record.state, "AUTHORIZED_STATE_"),
+		type: enumSuffix(_teslemetry_tesla_protocol_energy_device_authorization_types.authorizedClientTypeToJSON, record.type, "AUTHORIZED_CLIENT_TYPE_"),
+		description: record.description,
+		key_type: enumSuffix(_teslemetry_tesla_protocol_energy_device_authorization_types.authorizedKeyTypeToJSON, record.keyType, "AUTHORIZED_KEY_TYPE_"),
+		roles: record.roles.map((role) => enumSuffix(_teslemetry_tesla_protocol_energy_device_authorization_types.authorizationRoleToJSON, role, "AUTHORIZATION_ROLE_")),
+		verification: enumSuffix(_teslemetry_tesla_protocol_energy_device_authorization_types.authorizedVerificationTypeToJSON, record.verification, "AUTHORIZED_VERIFICATION_TYPE_"),
+		added_time: record.addedTime ? seconds(record.addedTime) : null,
+		identifier: record.identifier ?? null,
+		authorized_by_public_key: record.authorizedByPublicKey ? base64(record.authorizedByPublicKey) : null
+	};
+}
+/**
+* Client for a gateway on the LAN, over `/tedapi/v1r` and its REST reads.
+*
+* The connection is not authenticated: like Python, this accepts any
+* certificate, and replies carry no signature. A device on the LAN that can
+* intercept traffic can read the password and forge readings, but it cannot
+* forge a signed command.
+*/
+var PowerwallClient = class PowerwallClient {
+	#transport;
+	#logger;
+	#expectedDin;
+	#din = null;
+	#connecting = null;
+	#configWrites = Promise.resolve();
+	#savedRealMode = null;
+	#savedReservePercent = null;
+	#curtailmentActive = false;
+	/** @throws PowerwallAuthenticationError for a bad PEM or a key that is not RSA. */
+	constructor(options, _legacyGateway = false) {
+		this.#transport = new require_transport.V1rTransport({
+			host: options.host ?? "192.168.91.1",
+			password: options.gatewayPassword,
+			rsaPrivateKeyPem: options.rsaPrivateKeyPem,
+			timeoutMs: options.timeoutMs,
+			legacyGateway: _legacyGateway
+		});
+		this.#logger = options.logger;
+		this.#expectedDin = options.expectedDin;
+	}
+	/**
+	* A client for an early Gateway 1 unit, which rejects the last-5 login and
+	* needs the full `gatewayPassword`. Everything else is the same.
+	*/
+	static legacy_gateway(options) {
+		return new PowerwallClient(options, true);
+	}
+	get host() {
+		return this.#transport.host;
+	}
+	/** The gateway DIN, or `null` until `connect` succeeds. */
+	get din() {
+		return this.#din;
+	}
+	/** True between `curtail` and `restore_from_curtailment`. */
+	get curtailment_active() {
+		return this.#curtailmentActive;
+	}
+	/** Log in and fetch the gateway DIN. Idempotent, and concurrent callers share one attempt. */
+	connect() {
+		if (this.#din !== null) return Promise.resolve(this.#din);
+		this.#connecting ??= (async () => {
+			await this.#transport.login();
+			const din = await this.#transport.fetch_din();
+			if (this.#expectedDin && din !== this.#expectedDin) throw new require_exceptions.PowerwallAuthenticationError("The gateway at this address is not the expected one");
+			this.#din = din;
+			return din;
+		})().finally(() => {
+			this.#connecting = null;
+		});
+		return this.#connecting;
+	}
+	/** Destroy the idle sockets. */
+	close() {
+		this.#transport.close();
+	}
+	/** The cached DIN, connecting first if needed. */
+	get_din() {
+		return this.connect();
+	}
+	/** `/api/meters/aggregates`: instantaneous power per location. */
+	async get_meters_aggregates() {
+		await this.connect();
+		const data = await this.#transport.api_get("/api/meters/aggregates");
+		if (!isRecord(data)) throw new require_exceptions.PowerwallProtocolError("meters/aggregates payload is not an object");
+		return data;
+	}
+	/** The raw state of charge, where the bottom 5% is an inaccessible buffer. It reads higher than the Tesla app. */
+	async get_battery_soe_raw() {
+		await this.connect();
+		const data = await this.#transport.api_get("/api/system_status/soe");
+		const percentage = isRecord(data) ? Number(data.percentage ?? NaN) : NaN;
+		if (Number.isNaN(percentage)) throw new require_exceptions.PowerwallProtocolError("Unexpected SoE payload");
+		return percentage;
+	}
+	/** The state of charge the Tesla app and Fleet API show. */
+	async get_battery_soe() {
+		return raw_to_scaled_soc(await this.get_battery_soe_raw());
+	}
+	/** The gateway grid status string, such as `SystemGridConnected`. */
+	async get_grid_status() {
+		await this.connect();
+		const data = await this.#transport.api_get("/api/system_status/grid_status");
+		if (!isRecord(data) || !("grid_status" in data)) throw new require_exceptions.PowerwallProtocolError("Unexpected grid_status payload");
+		return String(data.grid_status);
+	}
+	/** The gateway's `config.json`. `battery_blocks` is always present. */
+	async get_config() {
+		const din = await this.connect();
+		const { blob } = await this._read_config(din);
+		const config = decodeConfig(blob);
+		config.battery_blocks ??= [];
+		return config;
+	}
+	/** The gateway status, from the narrow DeviceControllerQuery. */
+	async get_status() {
+		return parseJsonObject(await this._query_graphql(require_queries.STATUS_QUERY, require_queries.STATUS_CODE, "{}"), "status");
+	}
+	/** The extended DeviceControllerQuery payload. */
+	async get_device_controller() {
+		return parseJsonObject(await this._query_graphql(require_queries.CONTROLLER_QUERY, require_queries.CONTROLLER_CODE, require_queries.CONTROLLER_VARIABLES), "device_controller");
+	}
+	/** Powerwall 3 component data: `pch`, `pws`, `bms`, `hvp` and `baggr`. */
+	async get_components() {
+		return parseJsonObject(await this._query_graphql(require_queries.COMPONENTS_QUERY, require_queries.COMPONENTS_CODE, require_queries.COMPONENTS_VARIABLES), "components");
+	}
+	/** Gateway firmware details. Python's `five` and `six` keys are `update_status` and `device_type` here. */
+	async get_firmware_details() {
+		const din = await this.connect();
+		const info = (await this._post(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.create({
+			...localHeader(din),
+			common: { getSystemInfoRequest: {} }
+		}), din, "firmware")).common?.getSystemInfoResponse ?? _teslemetry_tesla_protocol_energy_device_common_api.CommonAPIGetSystemInfoResponse.create();
+		return { system: {
+			gateway: {
+				partNumber: info.deviceId?.partNumber ?? "",
+				serialNumber: info.deviceId?.serialNumber ?? ""
+			},
+			din: info.din,
+			version: {
+				text: info.firmwareVersion?.version ?? "",
+				githash: info.firmwareVersion?.githash ?? /* @__PURE__ */ new Uint8Array()
+			},
+			update_status: info.systemUpdate?.updateStatus ?? 0,
+			device_type: info.deviceType,
+			wireless: { device: [] }
+		} };
+	}
+	/** The active manual backup and any scheduled backup events. Times are epoch seconds. */
+	async get_backup_events() {
+		const din = await this.connect();
+		const events = (await this._send_command_request(din, { teg: { getBackupEventsRequest: {} } }, (reply) => reply.teg?.getBackupEventsResponse, "get_backup_events_request")).teg?.getBackupEventsResponse;
+		const manual = events?.manualBackupEvent;
+		const start_time = manual?.schedulingInfo?.startTime ? seconds(manual.schedulingInfo.startTime) : 0;
+		const duration_seconds = manual?.schedulingInfo?.durationSeconds ?? 0;
+		const end_time = start_time + duration_seconds;
+		return {
+			manual_backup: manual ? {
+				start_time,
+				duration_seconds,
+				end_time,
+				active: Math.floor(Date.now() / 1e3) < end_time,
+				priority: manual.schedulingInfo?.priority ?? "0"
+			} : null,
+			backup_events: (events?.backupEvents ?? []).map((event) => ({
+				id: event.id,
+				name: event.name,
+				start_time: event.schedulingInfo?.startTime ? seconds(event.schedulingInfo.startTime) : 0,
+				duration_seconds: event.schedulingInfo?.durationSeconds ?? 0,
+				priority: event.schedulingInfo?.priority ?? "0"
+			}))
+		};
+	}
+	/**
+	* The battery calibration delay counters.
+	* @throws PowerwallNotSupportedError on firmware without this command. Powerwall 3 firmware 26.26.4 is one.
+	*/
+	async get_battery_calibration_delay_status() {
+		const din = await this.connect();
+		const status = (await this._send_command_request(din, { teg: { getDelayBatteryCalibrationStatusRequest: {} } }, (reply) => reply.teg?.getDelayBatteryCalibrationStatusResponse, "get_delay_battery_calibration_status_request")).teg?.getDelayBatteryCalibrationStatusResponse;
+		return {
+			calibration_delays_left: status?.calibrationDelaysLeft ?? 0,
+			calibration_delay_remaining_seconds: status?.calibrationDelayRemainingSeconds ?? 0,
+			max_calibration_delays: status?.maxCalibrationDelays ?? 0
+		};
+	}
+	/**
+	* The load programs of Backup Switch and smart breaker devices. A site with
+	* none returns two empty lists.
+	* @param device_ids The devices to read, or every device when omitted.
+	*/
+	async get_controllable_device_programs(device_ids) {
+		const din = await this.connect();
+		const programs = (await this._send_command_request(din, { teg: { getControllableDeviceProgramsRequest: { deviceIds: device_ids ?? [] } } }, (reply) => reply.teg?.getControllableDeviceProgramsResponse, "get_controllable_device_programs_request")).teg?.getControllableDeviceProgramsResponse;
+		return {
+			active_programs: (programs?.activePrograms ?? []).map(controllableProgram),
+			inactive_programs: (programs?.inactivePrograms ?? []).map(controllableProgram)
+		};
+	}
+	/** The keys paired with the gateway, in the gateway's raw form. */
+	async list_authorized_clients() {
+		const din = await this.connect();
+		const clients = (await this._send_command_request(din, { authorization: { listAuthorizedClientsRequest: {} } }, (reply) => reply.authorization?.listAuthorizedClientsResponse, "list_authorized_clients_request")).authorization?.listAuthorizedClientsResponse;
+		return {
+			clients: (clients?.clients ?? []).map(authorizedClient),
+			enable_line_switch_off: clients?.enableLineSwitchOff ?? false
+		};
+	}
+	/**
+	* Patch `config.json`, a read-modify-write. The update carries the hash from
+	* the read unchanged: it is an optimistic lock held by the gateway, and the
+	* client never computes one.
+	* @param updates Dotted paths to values, such as `{"site_info.backup_reserve_percent": 24}`.
+	* Writes on one client run one at a time, so two cannot interleave. Another
+	* client's write is caught by that lock instead, and refused.
+	* @throws RangeError on a number that is not finite, before any request.
+	* @throws PowerwallProtocolError on bad JSON, or a reply with no `filestore`.
+	*/
+	async write_config(updates) {
+		requireFiniteNumbers(updates, "updates");
+		const write = this.#configWrites.then(() => this._write_config(updates));
+		this.#configWrites = write.catch(() => void 0);
+		return write;
+	}
+	async _write_config(updates) {
+		const din = await this.connect();
+		const { blob, hash } = await this._read_config(din);
+		const config = decodeConfig(blob);
+		for (const [dottedPath, value] of Object.entries(updates)) applyDottedUpdate(config, dottedPath, value);
+		if (!(await this._post(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.create({
+			...commandHeader(din),
+			filestore: { updateFileRequest: {
+				domain: _teslemetry_tesla_protocol_energy_device_filestore_api.FileStoreAPIDomain.FILE_STORE_API_DOMAIN_CONFIG_JSON,
+				file: {
+					name: CONFIG_FILE,
+					blob: Buffer.from(JSON.stringify(config), "utf8")
+				},
+				hash
+			} }
+		}), din, "updateFile")).filestore) throw new require_exceptions.PowerwallProtocolError("updateFile response missing filestore payload");
+	}
+	/**
+	* Set the backup reserve on the app's 0-100 scale.
+	* @throws RangeError outside 0-100.
+	*/
+	async set_backup_reserve(percent) {
+		await this.write_config({ "site_info.backup_reserve_percent": scaled_to_raw_reserve(percent) });
+	}
+	/**
+	* Write the backup reserve on the gateway's raw scale, where app 0% is raw 5%.
+	* @throws RangeError outside 0-100.
+	*/
+	async set_backup_reserve_raw(percent) {
+		assertPercent(percent, "percent");
+		await this.write_config({ "site_info.backup_reserve_percent": percent });
+	}
+	/**
+	* Set the operation mode, as `operation` does through the cloud.
+	* @param mode One of `OPERATION_MODES`.
+	* @throws RangeError for any other value.
+	*/
+	async set_operation_mode(mode) {
+		if (!OPERATION_MODES.includes(mode)) throw new RangeError(`mode must be one of ${OPERATION_MODES.join(", ")}`);
+		await this.write_config({ default_real_mode: mode });
+	}
+	/**
+	* Set `strategy.TOU_mode`, which is local-only: the cloud API does not expose it.
+	*
+	* The gateway does not validate this field, so a typo silently sets an
+	* unrecognized mode. Only `economic` is confirmed in use. The tariff itself
+	* lives in the cloud and cannot be set here.
+	* @throws RangeError on an empty string.
+	*/
+	async set_tou_mode(mode) {
+		requireNonEmptyString(mode, "mode");
+		await this.write_config({ "strategy.TOU_mode": mode });
+	}
+	/**
+	* Set the export rule, the grid-charging flag, or both in one write. See
+	* `set_export_rule` and `set_grid_charging` for one of each.
+	* @throws RangeError for an unknown rule.
+	* @throws TypeError when given neither.
+	*/
+	async set_grid_import_export(options) {
+		const { customer_preferred_export_rule: rule, disallow_charge_from_grid_with_solar_installed: disallow } = options;
+		const updates = {};
+		if (rule != null) {
+			if (!GRID_EXPORT_RULES.includes(rule)) throw new RangeError(`customer_preferred_export_rule must be one of ${GRID_EXPORT_RULES.join(", ")}`);
+			updates["site_info.customer_preferred_export_rule"] = rule;
+		}
+		if (disallow != null) updates["site_info.disallow_charge_from_grid_with_solar_installed"] = Boolean(disallow);
+		if (Object.keys(updates).length === 0) throw new TypeError("set_grid_import_export requires customer_preferred_export_rule and/or disallow_charge_from_grid_with_solar_installed");
+		await this.write_config(updates);
+	}
+	/**
+	* Set the export rule. `net_meter_mode` is independent and does not move.
+	* @param rule `battery_ok` exports solar and battery, `pv_only` solar only, `never` nothing.
+	* @throws RangeError for any other value.
+	*/
+	async set_export_rule(rule) {
+		await this.set_grid_import_export({ customer_preferred_export_rule: rule });
+	}
+	/**
+	* Allow or disallow charging from the grid. The gateway stores the inverse
+	* flag and drops the key rather than store `false`, so treat an absent key
+	* as "allowed".
+	*/
+	async set_grid_charging(enabled) {
+		await this.set_grid_import_export({ disallow_charge_from_grid_with_solar_installed: !enabled });
+	}
+	/**
+	* Enable on-grid solar curtailment. The gateway drops the key rather than
+	* store `false`, so treat an absent key as disabled.
+	*/
+	async set_on_grid_solar_curtailment(enabled) {
+		await this.write_config({ "site_info.on_grid_solar_curtailment_enabled": Boolean(enabled) });
+	}
+	/**
+	* Cap grid import, in kilowatts, stored as given.
+	* @throws RangeError on a negative value.
+	*/
+	async set_import_limit(kilowatts) {
+		requireNonNegative(kilowatts, "kilowatts");
+		await this.write_config({ "site_info.max_site_meter_power_ac": kilowatts });
+	}
+	/**
+	* Cap grid export, in kilowatts. Pass a positive magnitude: the gateway
+	* represents export as negative site-meter power.
+	* @throws RangeError on a negative value.
+	*/
+	async set_export_limit(kilowatts) {
+		requireNonNegative(kilowatts, "kilowatts");
+		await this.write_config({ "site_info.min_site_meter_power_ac": kilowatts === 0 ? 0 : -kilowatts });
+	}
+	/**
+	* Stop grid export by switching to `backup` mode at a high reserve. This uses
+	* a config write, so no contactor cycles, but it takes about 90 seconds to
+	* apply. `restore_from_curtailment` puts back what this replaced.
+	* @param options.reserve_percent The reserve during curtailment, on the **raw** scale.
+	* @throws RangeError outside 0-100.
+	*/
+	async curtail(options = {}) {
+		const { reserve_percent = 100 } = options;
+		assertPercent(reserve_percent, "reserve_percent");
+		if (!this.#curtailmentActive) {
+			const config = await this.get_config();
+			const reserve = lookup(config, "site_info", "backup_reserve_percent");
+			const saved = typeof reserve === "string" ? Number(reserve || NaN) : reserve;
+			this.#savedRealMode = String(config.default_real_mode || "self_consumption");
+			this.#savedReservePercent = typeof saved === "number" && Number.isFinite(saved) ? saved : OFFSET;
+		}
+		await this.write_config({
+			default_real_mode: "backup",
+			"site_info.backup_reserve_percent": reserve_percent
+		});
+		this.#curtailmentActive = true;
+	}
+	/** Write back what `curtail` replaced, or `self_consumption` at a raw 5 if nothing was saved. */
+	async restore_from_curtailment() {
+		await this.write_config({
+			default_real_mode: this.#savedRealMode ?? "self_consumption",
+			"site_info.backup_reserve_percent": this.#savedReservePercent ?? OFFSET
+		});
+		this.#curtailmentActive = false;
+	}
+	/**
+	* Schedule a manual "max backup" event that starts now, at maximum priority.
+	* The gateway requires any earlier event to be cancelled first, even an
+	* expired one, so this sends that cancel before scheduling.
+	* @param duration_seconds At least 60.
+	* @throws RangeError on a shorter or fractional duration.
+	*/
+	async schedule_max_backup(duration_seconds = DEFAULT_BACKUP_DURATION_SECONDS) {
+		requireIntegerInRange(duration_seconds, "duration_seconds", MIN_BACKUP_DURATION_SECONDS, MAX_UINT32);
+		const din = await this.connect();
+		await this._cancel_manual_backup(din);
+		await this._send_command_request(din, { teg: { scheduleManualBackupEventRequest: { schedulingInfo: {
+			startTime: /* @__PURE__ */ new Date(Math.floor(Date.now() / 1e3) * 1e3),
+			durationSeconds: duration_seconds,
+			priority: MAX_PRIORITY
+		} } } }, (reply) => reply.teg?.scheduleManualBackupEventResponse, "schedule_manual_backup_event_request");
+	}
+	/** Cancel the active manual backup event, if any. */
+	async cancel_max_backup() {
+		await this._cancel_manual_backup(await this.connect());
+	}
+	/**
+	* Request a timed battery power setpoint.
+	*
+	* The gateway holds it for the duration and then returns to its mode by
+	* itself. A new call replaces the active setpoint, power and timer both. The
+	* reply only acknowledges the request, so read `get_meters_aggregates` to see
+	* what the battery does. Keep durations short and renew them: a third party
+	* reports a dispatch discharging below reserve and exporting regardless of the
+	* export setting. Verified on Powerwall 3 firmware 26.26.4.
+	* @param power_watts Positive discharges, negative charges.
+	* @param duration_seconds Whole seconds from 1 to 86400.
+	* @throws PowerwallCommandError with code 11 above the site limit. The gateway refuses, and does not clamp.
+	* @throws PowerwallNotSupportedError on firmware without this command.
+	*/
+	async dispatch_battery_power(power_watts, duration_seconds) {
+		require_energyspecific.validate_dispatch_battery_power(power_watts, duration_seconds);
+		const din = await this.connect();
+		await this._send_command_request(din, { teg: { dispatchBatteryPowerRequest: { realPower: {
+			powerWatts: power_watts,
+			durationSeconds: duration_seconds
+		} } } }, (reply) => reply.teg?.dispatchBatteryPowerResponse, "dispatch_battery_power_request");
+	}
+	/** Release a `dispatch_battery_power` setpoint. This does not cancel a manual backup event. */
+	async resume_battery_operation() {
+		const din = await this.connect();
+		await this._send_command_request(din, { teg: { dispatchBatteryPowerRequest: { resumeDeviceMode: {} } } }, (reply) => reply.teg?.dispatchBatteryPowerResponse, "dispatch_battery_power_request");
+	}
+	/**
+	* Postpone the next battery calibration. Powerwall 3 firmware 26.26.4
+	* acknowledges this, but its effect is unverified: that firmware cannot report
+	* the delay status.
+	* @param delay_hours An integer from 1 to `2^32 - 1`.
+	*/
+	async delay_battery_calibration(delay_hours) {
+		requireIntegerInRange(delay_hours, "delay_hours", 1, MAX_UINT32);
+		const din = await this.connect();
+		await this._send_command_request(din, { teg: { delayBatteryCalibrationRequest: { delayHours: delay_hours } } }, (reply) => reply.teg?.delayBatteryCalibrationResponse, "delay_battery_calibration_request");
+	}
+	/**
+	* Point the gateway at an OCPP central system.
+	* @throws PowerwallNotSupportedError on firmware without this command. Powerwall 3 firmware 26.26.4 is one.
+	*/
+	async configure_ocpp(csms_base_url) {
+		requireNonEmptyString(csms_base_url, "csms_base_url");
+		const din = await this.connect();
+		await this._send_command_request(din, { teg: { configureOcppRequest: { csmsBaseUrl: csms_base_url } } }, (reply) => reply.teg?.configureOcppResponse, "configure_ocpp_request");
+	}
+	/**
+	* Revoke a paired key. This needs no presence proof, and any paired key can
+	* remove any other. Removing the signing key locks this client out, and
+	* pairing it again needs the usual registration and breaker toggle. A success
+	* carries no fields, so call `list_authorized_clients` to confirm.
+	* @param public_key Raw DER bytes, or base64 as `list_authorized_clients` reports it.
+	* @throws RangeError on an empty key.
+	*/
+	async remove_authorized_client(public_key) {
+		const publicKey = typeof public_key === "string" ? Buffer.from(public_key, "base64") : public_key;
+		if (!(publicKey instanceof Uint8Array)) throw new TypeError("public_key must be bytes or a base64 string");
+		if (publicKey.length === 0) throw new RangeError("public_key must not be empty");
+		const din = await this.connect();
+		await this._send_command_request(din, { authorization: { removeAuthorizedClientRequest: { publicKey } } }, (reply) => reply.authorization?.removeAuthorizedClientResponse, "remove_authorized_client_request", "empty");
+	}
+	/**
+	* Ask the gateway to go off grid or reconnect.
+	*
+	* A success-shaped reply does not prove the contactor moved: PowerSync reports
+	* firmware that acknowledges without acting. Read `islanding.contactorClosed`
+	* from `get_status` afterwards before relying on it.
+	* @param options.off_grid Mode 6 (off grid) when true, mode 1 (on grid) when false.
+	* @param options.force Required by some Powerwalls.
+	* @param options.mode_override Send this mode instead: 1 or 6.
+	* @throws TypeError on any other mode, or an `off_grid` that is not a boolean.
+	* @throws PowerwallCommandError on a `REJECTED_*` result, with `code` the enum value and `status_message` its name, or on `common.error_response`.
+	*/
+	async set_island_mode(options) {
+		const { off_grid, force = false, mode_override } = options;
+		if (typeof off_grid !== "boolean") throw new TypeError("off_grid must be a boolean");
+		const mode = mode_override ?? (off_grid ? _teslemetry_tesla_protocol_energy_device_teg_api.TEGIslandMode.TEG_ISLAND_MODE_INTENTIONAL_WITH_RECONNECT_FAILSAFE : _teslemetry_tesla_protocol_energy_device_teg_api.TEGIslandMode.TEG_ISLAND_MODE_AUTO_ACTIVE);
+		require_energyisland.validate_island_mode(mode, force);
+		const din = await this.connect();
+		const result = (await this._send_command_request(din, { teg: { setIslandModeRequest: {
+			mode,
+			force
+		} } }, (reply) => reply.teg?.setIslandModeResponse, "set_island_mode_request", "unverified")).teg?.setIslandModeResponse?.result;
+		this.#logger?.debug(`set_island_mode: mode=${mode} force=${force} result=${result ?? "absent"}`);
+		const rejection = require_energyisland.island_mode_rejection(result);
+		if (rejection) throw new require_exceptions.PowerwallCommandError("set_island_mode_request", rejection.code, rejection.name);
+	}
+	/**
+	* Disconnect from the grid. See `set_island_mode`, including its warning: read
+	* `islanding.contactorClosed` afterwards.
+	* @param options.force Defaults to true.
+	*/
+	async go_off_grid(options = {}) {
+		const { force = true, mode_override } = options;
+		await this.set_island_mode({
+			off_grid: true,
+			force,
+			mode_override
+		});
+	}
+	/** Reconnect to the grid. See `set_island_mode`, including its warning: read `islanding.contactorClosed` afterwards. */
+	async reconnect_grid() {
+		await this.set_island_mode({
+			off_grid: false,
+			force: false
+		});
+	}
+	/**
+	* The explicit black-start command, which drives the full islanding
+	* transition: grid-frequency ramp-down, contactor open, inverter restart.
+	* `set_island_mode` only updates the desired mode. No hardware result is
+	* recorded for this command, so check the contactor afterwards.
+	* @throws PowerwallCommandError on `common.error_response`.
+	*/
+	async trigger_islanding() {
+		const din = await this.connect();
+		await this._send_command_request(din, { teg: { triggerIslandingBlackStartRequest: {} } }, (reply) => reply.teg?.triggerIslandingBlackStartResponse, "trigger_islanding_black_start_request", "unverified");
+	}
+	async _cancel_manual_backup(din) {
+		await this._send_command_request(din, { teg: { cancelManualBackupEventRequest: {} } }, (reply) => reply.teg?.cancelManualBackupEventResponse, "cancel_manual_backup_event_request", "empty", STATUS_NOT_FOUND);
+	}
+	async _query_graphql(query, code, variables) {
+		const din = await this.connect();
+		const reply = (await this._post(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.create({
+			...localHeader(din),
+			graphql: { queryRequest: {
+				format: _teslemetry_tesla_protocol_energy_device_graphql_api.GraphQLQueryFormat.GRAPH_QL_QUERY_FORMAT_SIGNED_SHA256_ECDSA_ASN1,
+				query: _teslemetry_tesla_protocol_energy_device_graphql_api.SignedGraphQLQuery.encode({
+					version: 1,
+					query: Buffer.from(query, "utf8")
+				}).finish(),
+				signature: code,
+				variablesJson: variables
+			} }
+		}), din, "query")).graphql?.queryResponse;
+		if (!reply) throw new require_exceptions.PowerwallProtocolError("v1r query response missing payload");
+		if (!reply.data) throw new require_exceptions.PowerwallProtocolError("v1r query response payload is empty");
+		return reply.data;
+	}
+	async _read_config(din) {
+		const response = await this._post(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.create({
+			...commandHeader(din),
+			filestore: { readFileRequest: {
+				domain: _teslemetry_tesla_protocol_energy_device_filestore_api.FileStoreAPIDomain.FILE_STORE_API_DOMAIN_CONFIG_JSON,
+				name: CONFIG_FILE
+			} }
+		}), din, "FileStore");
+		if (!response.filestore) throw new require_exceptions.PowerwallProtocolError("FileStore response missing filestore payload");
+		const reply = response.filestore.readFileResponse;
+		return {
+			blob: reply?.file?.blob ?? /* @__PURE__ */ new Uint8Array(),
+			hash: reply?.hash ?? /* @__PURE__ */ new Uint8Array()
+		};
+	}
+	/** Sign, send once, and decode the reply envelope. */
+	async _post(envelope, din, what) {
+		return decodeEnvelope(await this.#transport.post_v1r(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.encode(envelope).finish(), din), what);
+	}
+	/**
+	* The one path for Command-header messages.
+	*
+	* Python's tolerated calls swallow every error, so a BUSY fault while revoking
+	* a compromised key reports success with the key still paired. Here `empty`
+	* accepts only an empty reply, and `ignored_status` the one refusal that means
+	* there was nothing to do.
+	* @param din The gateway DIN.
+	* @param payload The message's category and request.
+	* @param answered Reads the expected response field from a reply.
+	* @param request The request's proto field name, for errors.
+	* @param missing What to do when the reply lacks the response.
+	* @param ignored_status A `common.error_response` code that is not a failure.
+	*/
+	async _send_command_request(din, payload, answered, request, missing = "raise", ignored_status) {
+		let inner;
+		try {
+			inner = await this.#transport.post_v1r(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.encode(_teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.create({
+				...commandHeader(din),
+				...payload
+			})).finish(), din);
+		} catch (error) {
+			if (missing === "empty" && error instanceof require_transport.PowerwallEmptyReplyError) return _teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.create();
+			throw error;
+		}
+		const response = decodeEnvelope(inner, request);
+		if (answered(response) !== void 0) return response;
+		const status = response.common?.errorResponse?.status;
+		if (status && status.code === ignored_status) return response;
+		if (status) throw new (status.code === STATUS_UNIMPLEMENTED ? require_exceptions.PowerwallNotSupportedError : require_exceptions.PowerwallCommandError)(request, status.code, status.message);
+		if (missing === "unverified" || missing === "empty" && isEmptyReply(response)) {
+			this.#logger?.debug(`${request}: reply has no response (${inner.length} bytes)`);
+			return response;
+		}
+		throw new require_exceptions.PowerwallProtocolError(`${request} reply missing its response`);
+	}
+};
+/**
+* Convert a reserve percentage from the app's scale to the gateway's raw value.
+* @throws RangeError outside 0-100.
+*/
+function scaled_to_raw_reserve(percent) {
+	return scaledToRaw(percent);
+}
+/** Convert a raw gateway reserve value to the app's scale. */
+function raw_to_scaled_reserve(percent) {
+	return rawToScaled(percent);
+}
+/**
+* Convert a state of charge from the app's scale to the raw value.
+* @throws RangeError outside 0-100.
+*/
+function scaled_to_raw_soc(percent) {
+	return scaledToRaw(percent);
+}
+/** Convert a raw state of charge to the value the Tesla app and Fleet API show. */
+function raw_to_scaled_soc(percent) {
+	return rawToScaled(percent);
+}
+function scaledToRaw(percent) {
+	assertPercent(percent, "percent");
+	return round4(percent * SCALE + OFFSET);
+}
+function rawToScaled(percent) {
+	return round4((percent - OFFSET) / SCALE);
+}
+function assertPercent(value, name) {
+	if (typeof value !== "number") throw new TypeError(`${name} must be a number`);
+	if (!(value >= 0 && value <= 100)) throw new RangeError(`${name} must be between 0 and 100`);
+}
+/** The raw physical state of charge from a status payload, or `null` when either figure is missing or zero. */
+function battery_level_raw(status) {
+	const remaining = Number(lookup(status, "control", "systemStatus", "nominalEnergyRemainingWh") ?? NaN);
+	const full = Number(lookup(status, "control", "systemStatus", "nominalFullPackEnergyWh") ?? NaN);
+	return remaining && full ? remaining / full * 100 : null;
+}
+/** The state of charge the Tesla app and Fleet API show, from a status payload, or `null`. */
+function battery_level(status) {
+	const raw = battery_level_raw(status);
+	return raw === null ? null : raw_to_scaled_soc(raw);
+}
+/** Real power in watts by upper-case meter location. Malformed aggregates give `{}`. */
+function current_power(status) {
+	const meters = lookup(status, "control", "meterAggregates");
+	if (!Array.isArray(meters)) return {};
+	return Object.fromEntries(meters.filter((meter) => isRecord(meter) && meter.location != null).map((meter) => [String(meter.location).toUpperCase(), meter.realPowerW]));
+}
+/** Backup runtime in hours at the current load, or `null` when unknown. */
+function backup_time_remaining(status) {
+	const remaining = Number(lookup(status, "control", "systemStatus", "nominalEnergyRemainingWh") ?? NaN);
+	const load = current_power(status).LOAD;
+	return remaining && typeof load === "number" && load > 0 ? remaining / load : null;
+}
+exports.DEFAULT_GATEWAY_HOST = DEFAULT_GATEWAY_HOST;
+exports.GRID_EXPORT_RULES = GRID_EXPORT_RULES;
+exports.OPERATION_MODES = OPERATION_MODES;
+exports.PowerwallClient = PowerwallClient;
+exports.backup_time_remaining = backup_time_remaining;
+exports.battery_level = battery_level;
+exports.battery_level_raw = battery_level_raw;
+exports.current_power = current_power;
+exports.raw_to_scaled_reserve = raw_to_scaled_reserve;
+exports.raw_to_scaled_soc = raw_to_scaled_soc;
+exports.scaled_to_raw_reserve = scaled_to_raw_reserve;
+exports.scaled_to_raw_soc = scaled_to_raw_soc;