tesla-fleet-api 0.4.0 → 0.6.0

package/dist/teslemetryenergy.cjs

@@ -0,0 +1,287 @@
+const require_const = require("./const.cjs");
+const require_energy = require("./energy.cjs");
+const require_energyisland = require("./energyisland.cjs");
+const require_energyparsers = require("./energyparsers.cjs");
+const require_energyspecific = require("./energyspecific.cjs");
+const require_exceptions = require("./exceptions.cjs");
+// src/teslemetryenergy.ts
+/** Default overall bound on `wait_until_paired`, in milliseconds. */
+const DEFAULT_PAIRING_TIMEOUT = 6e5;
+/** Default delay between `wait_until_paired` polls, in milliseconds. */
+const DEFAULT_PAIRING_POLL_INTERVAL = 5e3;
+const EXPIRED = Symbol("expired");
+/**
+* Settle as `step` does, or resolve `EXPIRED` after `ms`, or reject with the
+* signal's reason. JavaScript cannot cancel `step`, so one that outlives this
+* is abandoned, and its late rejection stays handled here.
+*/
+function settleWithin(step, ms, signal) {
+	return new Promise((resolve, reject) => {
+		const finish = (settle) => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			settle();
+		};
+		const onAbort = () => finish(() => reject(signal?.reason));
+		const timer = setTimeout(() => finish(() => resolve(EXPIRED)), ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		Promise.resolve().then(step).then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+	});
+}
+/**
+* Teslemetry's energy site.
+*
+* With a signing key (see `EnergySpecific`), every device command except the
+* four pre-pairing reads is signed with that key and sent through Teslemetry's
+* `device_command` route. Without a key, a command uses its Teslemetry route.
+* The `set_island_mode`, `backup_events` and `config` routes sign with
+* Teslemetry's own key, which must be verified on the gateway, or the route
+* answers 409 `energy_site_not_paired` and sends nothing. As of 2026-10-29 the
+* `dispatch_battery_power`, `resume_battery_operation` and backup-event
+* schedule and cancel routes still send unsigned, so Tesla answers HTTP 400:
+* keyless dispatch does not work until Teslemetry signs those routes.
+*/
+var TeslemetryEnergySite = class extends require_energyspecific.default {
+	/** Send a signed `RoutableMessage` through Teslemetry's route, which takes the flat body and adds Tesla's `data` wrapper itself. */
+	async _device_command(routable_message, target_id, identifier_type = require_const.EnergyDeviceIdentifierType.GATEWAY_DIN) {
+		return this.parent.parent._request("POST", `api/1/energy_sites/${this.energy_site_id}/device_command`, null, this._device_command_body(routable_message, target_id, identifier_type));
+	}
+	/** `GET` a Teslemetry command route. */
+	async _get_route(route) {
+		return this.parent.parent._request("GET", `api/1/energy_sites/${this.energy_site_id}/command/${route}`);
+	}
+	/** `POST` to a Teslemetry command route. */
+	async _post_route(route, json = null) {
+		return this.parent.parent._request("POST", `api/1/energy_sites/${this.energy_site_id}/command/${route}`, null, json);
+	}
+	/**
+	* Set the island mode on the energy gateway. With a signing key this signs
+	* the command with that key. Without one it calls the Teslemetry route, which
+	* signs it with Teslemetry's key. See `EnergySpecific.set_island_mode`.
+	*/
+	async set_island_mode(mode, force) {
+		require_energyisland.validate_island_mode(mode, force);
+		if (this.signing) return super.set_island_mode(mode, force);
+		const result = await this._post_route("set_island_mode", force == null ? { mode } : {
+			mode,
+			force
+		});
+		require_energyspecific.raise_on_island_rejection(result);
+		return result;
+	}
+	/** Get backup events. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+	async get_backup_events() {
+		return this.signing ? super.get_backup_events() : this._get_route("backup_events");
+	}
+	/** Get the TEG configuration. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+	async get_teg_config() {
+		return this.signing ? super.get_teg_config() : this._get_route("config");
+	}
+	/** Get energy device system information. A pre-pairing read: never signed, even with a key. */
+	async get_system_info() {
+		return this._get_route("system_info");
+	}
+	/** Get networking status, which Teslemetry returns already unwrapped. A pre-pairing read: never signed, even with a key. */
+	async raw_networking_status() {
+		return this._get_route("networking_status");
+	}
+	/** Scan for WiFi networks on the energy gateway. */
+	async wifi_scan() {
+		return this.signing ? super.wifi_scan() : this._get_route("wifi_scan");
+	}
+	/** Get the energy device certificate. */
+	async get_device_cert() {
+		return this.signing ? super.get_device_cert() : this._get_route("device_cert");
+	}
+	/** Get cellular modem information. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+	async get_cellular_info() {
+		return this.signing ? super.get_cellular_info() : this._get_route("cellular_info");
+	}
+	/** Check for a firmware update. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+	async check_for_update() {
+		return this.signing ? super.check_for_update() : this._get_route("check_for_update");
+	}
+	/** Check the urgency of any firmware update. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+	async check_for_update_urgency() {
+		return this.signing ? super.check_for_update_urgency() : this._get_route("check_for_update_urgency");
+	}
+	/** Test internet connectivity on the energy gateway. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+	async check_internet() {
+		return this.signing ? super.check_internet() : this._get_route("check_internet");
+	}
+	/**
+	* Update local site configuration on the energy gateway. This writes gateway
+	* configuration and is an undocumented energy device gRPC command.
+	* @param params Raw protobuf request fields.
+	*/
+	async set_local_site_config(params) {
+		return this.signing ? super.set_local_site_config(params) : this._post_route("set_local_site_config", params ?? {});
+	}
+	/** Get the gateway's signed commands public key. A pre-pairing read: never signed, even with a key. */
+	async get_signed_commands_public_key() {
+		return this._get_route("signed_commands_public_key");
+	}
+	/**
+	* Schedule a manual backup event on the energy gateway.
+	* @param start_time ISO 8601 timestamp for when the backup event should start.
+	* @param duration_seconds Duration of the backup event in seconds.
+	* @param priority Priority level for the backup event. A string carries values beyond 2^53.
+	*/
+	async schedule_backup_event(start_time, duration_seconds, priority) {
+		if (this.signing) return super.schedule_backup_event(start_time, duration_seconds, priority);
+		const scheduling_info = require_energyspecific.backupSchedulingInfo(start_time, duration_seconds, priority);
+		return this._post_route("schedule_backup_event", scheduling_info ? { scheduling_info } : {});
+	}
+	/** Cancel a scheduled backup event on the energy gateway. */
+	async cancel_backup_event() {
+		return this.signing ? super.cancel_backup_event() : this._post_route("cancel_backup_event", {});
+	}
+	/**
+	* Register an authorized client with the energy gateway. All arguments are
+	* optional: if omitted, the Teslemetry server fills in its own key details. A
+	* site with a signing key signs the request with that key when `public_key`
+	* is given. Without a public key the route registers Teslemetry's own key,
+	* which the client key cannot sign for.
+	* @param public_key Raw DER bytes in the encoding matching `key_type` (RSA PKCS#1 or ECC SPKI), which are base64-encoded, or an already base64-encoded string.
+	* @param description Human-readable description of the client.
+	* @param key_type The type of key being registered.
+	* @param authorized_client_type The authorized client type.
+	*/
+	async add_authorized_client(public_key, description, key_type, authorized_client_type) {
+		if (this.signing && public_key != null) return super.add_authorized_client(public_key, description ?? void 0, key_type ?? void 0, authorized_client_type ?? void 0);
+		return this._post_route("add_authorized_client", {
+			public_key: public_key == null ? null : require_energyspecific.publicKeyBase64(public_key),
+			description,
+			key_type,
+			authorized_client_type
+		});
+	}
+	/** Get networking status from the gateway's Teslemetry route, including WiFi, Ethernet, and cellular details. */
+	async get_networking_status() {
+		return this._get_route("networking_status");
+	}
+	/**
+	* Discover the gateway's LAN IPv4 address, for pre-filling a local control
+	* host. See `parse_gateway_address` for the selection rule.
+	* @returns The address, or `null` when the reply is well-formed but no interface yields one.
+	* @throws InvalidResponse on a null body or an unrecognized reply.
+	* @throws EnergyGatewayUnreachable when Teslemetry cannot reach the gateway.
+	*/
+	async find_gateway_address() {
+		return require_energyparsers.parse_gateway_address(await this.get_networking_status());
+	}
+	/**
+	* List authorized clients on the energy gateway. Teslemetry may return JSON
+	* `null` when no payload is available; that value is returned unchanged.
+	*/
+	async list_authorized_clients() {
+		return this._get_route("authorized_clients");
+	}
+	/**
+	* List authorized clients on the energy gateway, parsed into a typed result.
+	* For the unparsed reply, use `list_authorized_clients`.
+	* @throws InvalidResponse on a null body or an unrecognized reply, rather than treating either as "no clients".
+	*/
+	async find_authorized_clients() {
+		return require_energyparsers.parse_authorized_clients(await this.list_authorized_clients());
+	}
+	/**
+	* Remove an authorized client from the energy gateway. A site with a signing
+	* key signs the request with that key. Removal needs no physical presence
+	* proof, so any paired key can revoke every other key, including the owner's.
+	* @param public_key Raw DER bytes, which are base64-encoded, or an already base64-encoded string as `list_authorized_clients` reports it.
+	*/
+	async remove_authorized_client(public_key) {
+		if (this.signing) return super.remove_authorized_client(public_key);
+		return this._post_route("remove_authorized_client", { public_key: require_energyspecific.publicKeyBase64(public_key) });
+	}
+	/**
+	* Request a timed battery power setpoint on the energy gateway. Without a
+	* signing key the Teslemetry route still sends unsigned and gets Tesla's HTTP
+	* 400 (2026-10-29). See `EnergySpecific.dispatch_battery_power`.
+	* @param power_watts Battery power in watts: positive discharges, negative charges.
+	* @param duration_seconds Whole seconds from 1 to 86400.
+	*/
+	async dispatch_battery_power(power_watts, duration_seconds) {
+		if (this.signing) return super.dispatch_battery_power(power_watts, duration_seconds);
+		require_energyspecific.validate_dispatch_battery_power(power_watts, duration_seconds);
+		return this._post_route("dispatch_battery_power", {
+			power_watts,
+			duration_seconds
+		});
+	}
+	/**
+	* Release a `dispatch_battery_power` setpoint. Without a signing key the
+	* Teslemetry route still sends unsigned and gets Tesla's HTTP 400 (2026-10-29).
+	*/
+	async resume_battery_operation() {
+		return this.signing ? super.resume_battery_operation() : this._post_route("resume_battery_operation");
+	}
+	/**
+	* Wait for a key already registered with `add_authorized_client` to finish
+	* pairing, polling `find_authorized_clients` until its entry is `VERIFIED`.
+	*
+	* The gateway's presence-proof window is about 9 minutes, and a breaker toggle
+	* confirmed a key in as little as 59 s, with no cloud auto-verify observed.
+	* A poll that fails counts as no signal.
+	* @param public_key The key as passed to `add_authorized_client`, raw DER bytes or base64.
+	* @param options.verify_by_use A signed local read. Once the cloud reports `VERIFIED`, one successful call confirms the key is usable. A failure means "not yet" and polling continues, because `VERIFIED` can be seen slightly ahead of local usability.
+	* @param options.timeout_ms Overall bound on the wait.
+	* @param options.poll_interval_ms Delay between polls.
+	* @param options.signal Aborting rejects with the signal's reason. An in-flight call is abandoned, not cancelled.
+	* @returns The matched entry, once paired and confirmed.
+	* @throws AuthorizedClientPairingTimedOut at once on `PENDING_VERIFICATION_TIMEOUT`. The registration is dead: call `add_authorized_client` again with the same key, which resets the window, then wait again.
+	* @throws AuthorizedClientWaitExpired when `timeout_ms` elapses first. The registration is still alive: wait again.
+	*/
+	async wait_until_paired(public_key, options = {}) {
+		const { verify_by_use, timeout_ms = DEFAULT_PAIRING_TIMEOUT, poll_interval_ms = DEFAULT_PAIRING_POLL_INTERVAL, signal } = options;
+		const target = require_energyspecific.publicKeyBase64(public_key);
+		const deadline = performance.now() + timeout_ms;
+		let last_state = null;
+		const expired = () => new require_exceptions.AuthorizedClientWaitExpired({
+			public_key: target,
+			state: last_state
+		});
+		/** Run one step under the deadline. A failed step is `undefined`, unless the wait was aborted. */
+		const attempt = async (step) => {
+			const result = await settleWithin(step, deadline - performance.now(), signal).catch((error) => {
+				if (signal?.aborted) throw error;
+			});
+			if (result === EXPIRED) throw expired();
+			return result;
+		};
+		while (true) {
+			signal?.throwIfAborted();
+			if (performance.now() >= deadline) throw expired();
+			const match = (await attempt(() => this.find_authorized_clients()))?.clients.find((client) => client.public_key === target);
+			if (match !== void 0) {
+				last_state = match.state;
+				if (match.state === require_const.AuthorizedClientState.PENDING_VERIFICATION_TIMEOUT) throw new require_exceptions.AuthorizedClientPairingTimedOut({
+					public_key: target,
+					state: match.state
+				});
+				if (match.state === require_const.AuthorizedClientState.VERIFIED) {
+					if (verify_by_use === void 0) return match;
+					if (performance.now() >= deadline) throw expired();
+					if (await attempt(async () => (await verify_by_use(), true)) === true) return match;
+				}
+			}
+			const remaining = deadline - performance.now();
+			if (remaining <= 0) throw expired();
+			await settleWithin(() => new Promise(() => {}), Math.min(poll_interval_ms, remaining), signal);
+		}
+	}
+};
+/** Creates and holds Teslemetry energy sites. */
+var TeslemetryEnergySites = class extends require_energy.default {
+	static Site = TeslemetryEnergySite;
+	create(energy_site_id, private_key, din) {
+		return super.create(energy_site_id, private_key, din);
+	}
+};
+exports.DEFAULT_PAIRING_POLL_INTERVAL = DEFAULT_PAIRING_POLL_INTERVAL;
+exports.DEFAULT_PAIRING_TIMEOUT = DEFAULT_PAIRING_TIMEOUT;
+exports.TeslemetryEnergySite = TeslemetryEnergySite;
+exports.TeslemetryEnergySites = TeslemetryEnergySites;
+exports.parse_authorized_clients = require_energyparsers.parse_authorized_clients;
+exports.parse_gateway_address = require_energyparsers.parse_gateway_address;

package/dist/teslemetryenergy.d.cts

@@ -0,0 +1,154 @@
+import { AuthorizedClientKeyType, AuthorizedClientType, EnergyDeviceIdentifierType, EnergyIslandMode } from "./const.cjs";
+import Energy from "./energy.cjs";
+import { AuthorizedClient, AuthorizedClients, parse_authorized_clients, parse_gateway_address } from "./energyparsers.cjs";
+import EnergySpecific from "./energyspecific.cjs";
+import { KeyObject } from "crypto";
+/** Default overall bound on `wait_until_paired`, in milliseconds. */
+export declare const DEFAULT_PAIRING_TIMEOUT = 600000;
+/** Default delay between `wait_until_paired` polls, in milliseconds. */
+export declare const DEFAULT_PAIRING_POLL_INTERVAL = 5000;
+/**
+ * Teslemetry's energy site.
+ *
+ * With a signing key (see `EnergySpecific`), every device command except the
+ * four pre-pairing reads is signed with that key and sent through Teslemetry's
+ * `device_command` route. Without a key, a command uses its Teslemetry route.
+ * The `set_island_mode`, `backup_events` and `config` routes sign with
+ * Teslemetry's own key, which must be verified on the gateway, or the route
+ * answers 409 `energy_site_not_paired` and sends nothing. As of 2026-10-29 the
+ * `dispatch_battery_power`, `resume_battery_operation` and backup-event
+ * schedule and cancel routes still send unsigned, so Tesla answers HTTP 400:
+ * keyless dispatch does not work until Teslemetry signs those routes.
+ */
+export declare class TeslemetryEnergySite extends EnergySpecific {
+  /** Send a signed `RoutableMessage` through Teslemetry's route, which takes the flat body and adds Tesla's `data` wrapper itself. */
+  _device_command(routable_message: Uint8Array, target_id: string, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /** `GET` a Teslemetry command route. */
+  protected _get_route(route: string): Promise<any>;
+  /** `POST` to a Teslemetry command route. */
+  protected _post_route(route: string, json?: Record<string, any> | null): Promise<any>;
+  /**
+   * Set the island mode on the energy gateway. With a signing key this signs
+   * the command with that key. Without one it calls the Teslemetry route, which
+   * signs it with Teslemetry's key. See `EnergySpecific.set_island_mode`.
+   */
+  set_island_mode(mode: EnergyIslandMode | number, force?: boolean | null): Promise<Record<string, any>>;
+  /** Get backup events. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  get_backup_events(): Promise<Record<string, any>>;
+  /** Get the TEG configuration. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  get_teg_config(): Promise<Record<string, any>>;
+  /** Get energy device system information. A pre-pairing read: never signed, even with a key. */
+  get_system_info(): Promise<Record<string, any>>;
+  /** Get networking status, which Teslemetry returns already unwrapped. A pre-pairing read: never signed, even with a key. */
+  raw_networking_status(): Promise<Record<string, any>>;
+  /** Scan for WiFi networks on the energy gateway. */
+  wifi_scan(): Promise<Record<string, any>>;
+  /** Get the energy device certificate. */
+  get_device_cert(): Promise<Record<string, any>>;
+  /** Get cellular modem information. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  get_cellular_info(): Promise<Record<string, any>>;
+  /** Check for a firmware update. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  check_for_update(): Promise<Record<string, any>>;
+  /** Check the urgency of any firmware update. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  check_for_update_urgency(): Promise<Record<string, any>>;
+  /** Test internet connectivity on the energy gateway. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  check_internet(): Promise<Record<string, any>>;
+  /**
+   * Update local site configuration on the energy gateway. This writes gateway
+   * configuration and is an undocumented energy device gRPC command.
+   * @param params Raw protobuf request fields.
+   */
+  set_local_site_config(params?: Record<string, any> | null): Promise<Record<string, any>>;
+  /** Get the gateway's signed commands public key. A pre-pairing read: never signed, even with a key. */
+  get_signed_commands_public_key(): Promise<Record<string, any>>;
+  /**
+   * Schedule a manual backup event on the energy gateway.
+   * @param start_time ISO 8601 timestamp for when the backup event should start.
+   * @param duration_seconds Duration of the backup event in seconds.
+   * @param priority Priority level for the backup event. A string carries values beyond 2^53.
+   */
+  schedule_backup_event(start_time?: string | null, duration_seconds?: number | null, priority?: number | string | null): Promise<Record<string, any>>;
+  /** Cancel a scheduled backup event on the energy gateway. */
+  cancel_backup_event(): Promise<Record<string, any>>;
+  /**
+   * Register an authorized client with the energy gateway. All arguments are
+   * optional: if omitted, the Teslemetry server fills in its own key details. A
+   * site with a signing key signs the request with that key when `public_key`
+   * is given. Without a public key the route registers Teslemetry's own key,
+   * which the client key cannot sign for.
+   * @param public_key Raw DER bytes in the encoding matching `key_type` (RSA PKCS#1 or ECC SPKI), which are base64-encoded, or an already base64-encoded string.
+   * @param description Human-readable description of the client.
+   * @param key_type The type of key being registered.
+   * @param authorized_client_type The authorized client type.
+   */
+  add_authorized_client(public_key?: Uint8Array | string | null, description?: string | null, key_type?: AuthorizedClientKeyType | null, authorized_client_type?: AuthorizedClientType | null): Promise<Record<string, any>>;
+  /** Get networking status from the gateway's Teslemetry route, including WiFi, Ethernet, and cellular details. */
+  get_networking_status(): Promise<Record<string, any>>;
+  /**
+   * Discover the gateway's LAN IPv4 address, for pre-filling a local control
+   * host. See `parse_gateway_address` for the selection rule.
+   * @returns The address, or `null` when the reply is well-formed but no interface yields one.
+   * @throws InvalidResponse on a null body or an unrecognized reply.
+   * @throws EnergyGatewayUnreachable when Teslemetry cannot reach the gateway.
+   */
+  find_gateway_address(): Promise<string | null>;
+  /**
+   * List authorized clients on the energy gateway. Teslemetry may return JSON
+   * `null` when no payload is available; that value is returned unchanged.
+   */
+  list_authorized_clients(): Promise<Record<string, any>>;
+  /**
+   * List authorized clients on the energy gateway, parsed into a typed result.
+   * For the unparsed reply, use `list_authorized_clients`.
+   * @throws InvalidResponse on a null body or an unrecognized reply, rather than treating either as "no clients".
+   */
+  find_authorized_clients(): Promise<AuthorizedClients>;
+  /**
+   * Remove an authorized client from the energy gateway. A site with a signing
+   * key signs the request with that key. Removal needs no physical presence
+   * proof, so any paired key can revoke every other key, including the owner's.
+   * @param public_key Raw DER bytes, which are base64-encoded, or an already base64-encoded string as `list_authorized_clients` reports it.
+   */
+  remove_authorized_client(public_key: Uint8Array | string): Promise<Record<string, any>>;
+  /**
+   * Request a timed battery power setpoint on the energy gateway. Without a
+   * signing key the Teslemetry route still sends unsigned and gets Tesla's HTTP
+   * 400 (2026-10-29). See `EnergySpecific.dispatch_battery_power`.
+   * @param power_watts Battery power in watts: positive discharges, negative charges.
+   * @param duration_seconds Whole seconds from 1 to 86400.
+   */
+  dispatch_battery_power(power_watts: number, duration_seconds: number): Promise<Record<string, any>>;
+  /**
+   * Release a `dispatch_battery_power` setpoint. Without a signing key the
+   * Teslemetry route still sends unsigned and gets Tesla's HTTP 400 (2026-10-29).
+   */
+  resume_battery_operation(): Promise<Record<string, any>>;
+  /**
+   * Wait for a key already registered with `add_authorized_client` to finish
+   * pairing, polling `find_authorized_clients` until its entry is `VERIFIED`.
+   *
+   * The gateway's presence-proof window is about 9 minutes, and a breaker toggle
+   * confirmed a key in as little as 59 s, with no cloud auto-verify observed.
+   * A poll that fails counts as no signal.
+   * @param public_key The key as passed to `add_authorized_client`, raw DER bytes or base64.
+   * @param options.verify_by_use A signed local read. Once the cloud reports `VERIFIED`, one successful call confirms the key is usable. A failure means "not yet" and polling continues, because `VERIFIED` can be seen slightly ahead of local usability.
+   * @param options.timeout_ms Overall bound on the wait.
+   * @param options.poll_interval_ms Delay between polls.
+   * @param options.signal Aborting rejects with the signal's reason. An in-flight call is abandoned, not cancelled.
+   * @returns The matched entry, once paired and confirmed.
+   * @throws AuthorizedClientPairingTimedOut at once on `PENDING_VERIFICATION_TIMEOUT`. The registration is dead: call `add_authorized_client` again with the same key, which resets the window, then wait again.
+   * @throws AuthorizedClientWaitExpired when `timeout_ms` elapses first. The registration is still alive: wait again.
+   */
+  wait_until_paired(public_key: Uint8Array | string, options?: {
+    verify_by_use?: () => Promise<unknown>;
+    timeout_ms?: number;
+    poll_interval_ms?: number;
+    signal?: AbortSignal;
+  }): Promise<AuthorizedClient>;
+}
+/** Creates and holds Teslemetry energy sites. */
+export declare class TeslemetryEnergySites extends Energy {
+  static Site: typeof TeslemetryEnergySite;
+  create(energy_site_id: number, private_key?: KeyObject, din?: string): TeslemetryEnergySite;
+}
+export { type AuthorizedClient, type AuthorizedClients, parse_authorized_clients, parse_gateway_address };

package/dist/teslemetryenergy.d.mts

@@ -0,0 +1,154 @@
+import { AuthorizedClientKeyType, AuthorizedClientType, EnergyDeviceIdentifierType, EnergyIslandMode } from "./const.mjs";
+import Energy from "./energy.mjs";
+import { AuthorizedClient, AuthorizedClients, parse_authorized_clients, parse_gateway_address } from "./energyparsers.mjs";
+import EnergySpecific from "./energyspecific.mjs";
+import { KeyObject } from "crypto";
+/** Default overall bound on `wait_until_paired`, in milliseconds. */
+export declare const DEFAULT_PAIRING_TIMEOUT = 600000;
+/** Default delay between `wait_until_paired` polls, in milliseconds. */
+export declare const DEFAULT_PAIRING_POLL_INTERVAL = 5000;
+/**
+ * Teslemetry's energy site.
+ *
+ * With a signing key (see `EnergySpecific`), every device command except the
+ * four pre-pairing reads is signed with that key and sent through Teslemetry's
+ * `device_command` route. Without a key, a command uses its Teslemetry route.
+ * The `set_island_mode`, `backup_events` and `config` routes sign with
+ * Teslemetry's own key, which must be verified on the gateway, or the route
+ * answers 409 `energy_site_not_paired` and sends nothing. As of 2026-10-29 the
+ * `dispatch_battery_power`, `resume_battery_operation` and backup-event
+ * schedule and cancel routes still send unsigned, so Tesla answers HTTP 400:
+ * keyless dispatch does not work until Teslemetry signs those routes.
+ */
+export declare class TeslemetryEnergySite extends EnergySpecific {
+  /** Send a signed `RoutableMessage` through Teslemetry's route, which takes the flat body and adds Tesla's `data` wrapper itself. */
+  _device_command(routable_message: Uint8Array, target_id: string, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /** `GET` a Teslemetry command route. */
+  protected _get_route(route: string): Promise<any>;
+  /** `POST` to a Teslemetry command route. */
+  protected _post_route(route: string, json?: Record<string, any> | null): Promise<any>;
+  /**
+   * Set the island mode on the energy gateway. With a signing key this signs
+   * the command with that key. Without one it calls the Teslemetry route, which
+   * signs it with Teslemetry's key. See `EnergySpecific.set_island_mode`.
+   */
+  set_island_mode(mode: EnergyIslandMode | number, force?: boolean | null): Promise<Record<string, any>>;
+  /** Get backup events. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  get_backup_events(): Promise<Record<string, any>>;
+  /** Get the TEG configuration. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  get_teg_config(): Promise<Record<string, any>>;
+  /** Get energy device system information. A pre-pairing read: never signed, even with a key. */
+  get_system_info(): Promise<Record<string, any>>;
+  /** Get networking status, which Teslemetry returns already unwrapped. A pre-pairing read: never signed, even with a key. */
+  raw_networking_status(): Promise<Record<string, any>>;
+  /** Scan for WiFi networks on the energy gateway. */
+  wifi_scan(): Promise<Record<string, any>>;
+  /** Get the energy device certificate. */
+  get_device_cert(): Promise<Record<string, any>>;
+  /** Get cellular modem information. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  get_cellular_info(): Promise<Record<string, any>>;
+  /** Check for a firmware update. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  check_for_update(): Promise<Record<string, any>>;
+  /** Check the urgency of any firmware update. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  check_for_update_urgency(): Promise<Record<string, any>>;
+  /** Test internet connectivity on the energy gateway. Without a signing key, the Teslemetry route signs with Teslemetry's key. */
+  check_internet(): Promise<Record<string, any>>;
+  /**
+   * Update local site configuration on the energy gateway. This writes gateway
+   * configuration and is an undocumented energy device gRPC command.
+   * @param params Raw protobuf request fields.
+   */
+  set_local_site_config(params?: Record<string, any> | null): Promise<Record<string, any>>;
+  /** Get the gateway's signed commands public key. A pre-pairing read: never signed, even with a key. */
+  get_signed_commands_public_key(): Promise<Record<string, any>>;
+  /**
+   * Schedule a manual backup event on the energy gateway.
+   * @param start_time ISO 8601 timestamp for when the backup event should start.
+   * @param duration_seconds Duration of the backup event in seconds.
+   * @param priority Priority level for the backup event. A string carries values beyond 2^53.
+   */
+  schedule_backup_event(start_time?: string | null, duration_seconds?: number | null, priority?: number | string | null): Promise<Record<string, any>>;
+  /** Cancel a scheduled backup event on the energy gateway. */
+  cancel_backup_event(): Promise<Record<string, any>>;
+  /**
+   * Register an authorized client with the energy gateway. All arguments are
+   * optional: if omitted, the Teslemetry server fills in its own key details. A
+   * site with a signing key signs the request with that key when `public_key`
+   * is given. Without a public key the route registers Teslemetry's own key,
+   * which the client key cannot sign for.
+   * @param public_key Raw DER bytes in the encoding matching `key_type` (RSA PKCS#1 or ECC SPKI), which are base64-encoded, or an already base64-encoded string.
+   * @param description Human-readable description of the client.
+   * @param key_type The type of key being registered.
+   * @param authorized_client_type The authorized client type.
+   */
+  add_authorized_client(public_key?: Uint8Array | string | null, description?: string | null, key_type?: AuthorizedClientKeyType | null, authorized_client_type?: AuthorizedClientType | null): Promise<Record<string, any>>;
+  /** Get networking status from the gateway's Teslemetry route, including WiFi, Ethernet, and cellular details. */
+  get_networking_status(): Promise<Record<string, any>>;
+  /**
+   * Discover the gateway's LAN IPv4 address, for pre-filling a local control
+   * host. See `parse_gateway_address` for the selection rule.
+   * @returns The address, or `null` when the reply is well-formed but no interface yields one.
+   * @throws InvalidResponse on a null body or an unrecognized reply.
+   * @throws EnergyGatewayUnreachable when Teslemetry cannot reach the gateway.
+   */
+  find_gateway_address(): Promise<string | null>;
+  /**
+   * List authorized clients on the energy gateway. Teslemetry may return JSON
+   * `null` when no payload is available; that value is returned unchanged.
+   */
+  list_authorized_clients(): Promise<Record<string, any>>;
+  /**
+   * List authorized clients on the energy gateway, parsed into a typed result.
+   * For the unparsed reply, use `list_authorized_clients`.
+   * @throws InvalidResponse on a null body or an unrecognized reply, rather than treating either as "no clients".
+   */
+  find_authorized_clients(): Promise<AuthorizedClients>;
+  /**
+   * Remove an authorized client from the energy gateway. A site with a signing
+   * key signs the request with that key. Removal needs no physical presence
+   * proof, so any paired key can revoke every other key, including the owner's.
+   * @param public_key Raw DER bytes, which are base64-encoded, or an already base64-encoded string as `list_authorized_clients` reports it.
+   */
+  remove_authorized_client(public_key: Uint8Array | string): Promise<Record<string, any>>;
+  /**
+   * Request a timed battery power setpoint on the energy gateway. Without a
+   * signing key the Teslemetry route still sends unsigned and gets Tesla's HTTP
+   * 400 (2026-10-29). See `EnergySpecific.dispatch_battery_power`.
+   * @param power_watts Battery power in watts: positive discharges, negative charges.
+   * @param duration_seconds Whole seconds from 1 to 86400.
+   */
+  dispatch_battery_power(power_watts: number, duration_seconds: number): Promise<Record<string, any>>;
+  /**
+   * Release a `dispatch_battery_power` setpoint. Without a signing key the
+   * Teslemetry route still sends unsigned and gets Tesla's HTTP 400 (2026-10-29).
+   */
+  resume_battery_operation(): Promise<Record<string, any>>;
+  /**
+   * Wait for a key already registered with `add_authorized_client` to finish
+   * pairing, polling `find_authorized_clients` until its entry is `VERIFIED`.
+   *
+   * The gateway's presence-proof window is about 9 minutes, and a breaker toggle
+   * confirmed a key in as little as 59 s, with no cloud auto-verify observed.
+   * A poll that fails counts as no signal.
+   * @param public_key The key as passed to `add_authorized_client`, raw DER bytes or base64.
+   * @param options.verify_by_use A signed local read. Once the cloud reports `VERIFIED`, one successful call confirms the key is usable. A failure means "not yet" and polling continues, because `VERIFIED` can be seen slightly ahead of local usability.
+   * @param options.timeout_ms Overall bound on the wait.
+   * @param options.poll_interval_ms Delay between polls.
+   * @param options.signal Aborting rejects with the signal's reason. An in-flight call is abandoned, not cancelled.
+   * @returns The matched entry, once paired and confirmed.
+   * @throws AuthorizedClientPairingTimedOut at once on `PENDING_VERIFICATION_TIMEOUT`. The registration is dead: call `add_authorized_client` again with the same key, which resets the window, then wait again.
+   * @throws AuthorizedClientWaitExpired when `timeout_ms` elapses first. The registration is still alive: wait again.
+   */
+  wait_until_paired(public_key: Uint8Array | string, options?: {
+    verify_by_use?: () => Promise<unknown>;
+    timeout_ms?: number;
+    poll_interval_ms?: number;
+    signal?: AbortSignal;
+  }): Promise<AuthorizedClient>;
+}
+/** Creates and holds Teslemetry energy sites. */
+export declare class TeslemetryEnergySites extends Energy {
+  static Site: typeof TeslemetryEnergySite;
+  create(energy_site_id: number, private_key?: KeyObject, din?: string): TeslemetryEnergySite;
+}
+export { type AuthorizedClient, type AuthorizedClients, parse_authorized_clients, parse_gateway_address };