tesla-fleet-api 0.4.0 → 0.6.0

package/dist/energyspecific.d.cts

@@ -1,10 +1,188 @@
+import { AuthorizedClientKeyType, AuthorizedClientType, EnergyDeviceIdentifierType, EnergyIslandMode, TeslaEnergyPeriod } from "./const.cjs";
 import Energy from "./energy.cjs";
 import { LiveStatusResponse } from "./types/live_status.cjs";
+import { ResponseEnvelope } from "./types/responses.cjs";
 import { SiteInfoResponse } from "./types/site_info.cjs";
-declare class EnergySpecific {
+import { KeyObject } from "crypto";
+/**
+ * The only device commands Tesla's cloud accepts unsigned, as
+ * `category.command`: the reads a gateway answers before any key is paired.
+ * Unsigned, every other command was refused with HTTP 400 live on a Powerwall 3
+ * (2026-10-29), and signed, each one reached the gateway. A site with a signing
+ * key signs everything else.
+ */
+export declare const UNSIGNED_DEVICE_COMMANDS: ReadonlySet<string>;
+/** Upper bound on a `dispatch_battery_power` setpoint duration (one day). */
+export declare const MAX_DISPATCH_DURATION_SECONDS = 86400;
+/**
+ * Check `dispatch_battery_power` arguments before any request.
+ * @throws TypeError unless both are numbers.
+ * @throws RangeError on a non-finite power or a duration that is not a whole number from 1 to `MAX_DISPATCH_DURATION_SECONDS`.
+ */
+export declare function validate_dispatch_battery_power(power_watts: number, duration_seconds: number): void;
+export default class EnergySpecific {
+  #private;
   parent: Energy;
   energy_site_id: number;
-  constructor(parent: Energy, energy_site_id: number);
+  /** Gateway DIN (the energy site's `gateway_id` in `products`), the target of device commands. */
+  din?: string;
+  /**
+   * Pass `private_key` and `din` to send client-signed device commands through
+   * the cloud `device_command` endpoint. With a signer, every device command is
+   * signed except the four pre-pairing reads in `UNSIGNED_DEVICE_COMMANDS`.
+   * Without one, device commands are sent unsigned, and Tesla's cloud refuses
+   * most of them with 400.
+   * @param parent
+   * @param energy_site_id
+   * @param private_key RSA key `VERIFIED` on this gateway. Without one the site is unsigned: unlike vehicles, there is no fallback to the parent's key.
+   * @param din Gateway DIN (the energy site's `gateway_id` in `products`). Required with `private_key`.
+   * @throws TypeError for a key that is not RSA.
+   */
+  constructor(parent: Energy, energy_site_id: number, private_key?: KeyObject, din?: string);
+  /** Whether device commands are signed with a client key. */
+  get signing(): boolean;
+  /**
+   * Send a gRPC command to the energy device gateway.
+   *
+   * With a signing key, this signs every command except the ones in
+   * `UNSIGNED_DEVICE_COMMANDS`. Otherwise it sends the unsigned `grpc_command`.
+   * Energy device gRPC commands are based on research from
+   * https://github.com/jasonacox/pypowerwall (MIT licensed).
+   */
+  _command(category: string, command: string, params?: Record<string, any> | null, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /** Send an unsigned `grpc_command` to the energy device gateway. */
+  _unsigned_command(category: string, command: string, params?: Record<string, any> | null, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /** Build the flat `device_command` body around a signed message. */
+  protected _device_command_body(routable_message: Uint8Array, target_id: string, identifier_type: EnergyDeviceIdentifierType): Record<string, any>;
+  /**
+   * Send a signed `RoutableMessage` to the energy device. Tesla requires the
+   * body wrapped in `data` and `identifier_type` as an integer. The reply is
+   * returned unchanged; `_signed_command` checks it for a gateway error.
+   */
+  _device_command(routable_message: Uint8Array, target_id: string, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /**
+   * Sign a gRPC command with the site's key and send it to the gateway.
+   *
+   * A resend of the same signed bytes inside the TTL executes again, so this
+   * never retries.
+   * @throws SignedCommandRequired when the site has no signing key.
+   * @throws InvalidCommand when the gateway firmware has no handler for the command.
+   * @throws DeviceUnexpectedResponse when the gateway refuses the command.
+   */
+  _signed_command(category: string, command: string, params?: Record<string, any> | null): Promise<Record<string, any>>;
+  /** Get energy device system information including firmware version, device type, part number, serial number, and DIN. */
+  get_system_info(): Promise<Record<string, any>>;
+  /** Get raw energy device networking status including WiFi, Ethernet, and cellular connectivity. */
+  raw_networking_status(): Promise<Record<string, any>>;
+  /** Get energy device networking status including WiFi, Ethernet, and cellular connectivity. */
+  get_networking_status(): Promise<Record<string, any>>;
+  /** Scan for available WiFi networks from the energy gateway. */
+  wifi_scan(): Promise<Record<string, any>>;
+  /** Get the energy device certificate including subject, issuer, and validity. */
+  get_device_cert(): Promise<Record<string, any>>;
+  /** Get cellular modem information from the energy gateway including the embedded SIM identifier (EID) and supported cellular profiles. */
+  get_cellular_info(): Promise<Record<string, any>>;
+  /** Check if a firmware update is available for the energy gateway. */
+  check_for_update(): Promise<Record<string, any>>;
+  /** Check the urgency level of any available firmware update for the energy gateway. */
+  check_for_update_urgency(): Promise<Record<string, any>>;
+  /** Test internet connectivity on the energy gateway across all network interfaces (WiFi, Ethernet, GSM). */
+  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>>;
+  /** List authorized clients (paired keys) on the energy gateway including their roles and state. */
+  list_authorized_clients(): Promise<Record<string, any>>;
+  /**
+   * Register an authorized client (public key) with the energy gateway, to
+   * pair a local key with a Powerwall for the LAN TEDapi v1r protocol. The
+   * encoding follows `key_type`: RSA is raw PKCS#1 `RSAPublicKey` DER
+   * (`rsa_public_der_pkcs1`), and ECC is DER SubjectPublicKeyInfo
+   * (`ec_public_der_spki`), not a raw point, which the gateway rejects. A
+   * VERIFIED ECC key still cannot sign v1r: `SignatureData` has no ECDSA member.
+   *
+   * The key stays PENDING_VERIFICATION until a physical breaker toggle confirms
+   * it inside a window of about 9 minutes. A missed window is the terminal
+   * PENDING_VERIFICATION_TIMEOUT; registering the same key again resets it
+   * without a second record.
+   * @param public_key Raw DER bytes, 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, description?: string, key_type?: AuthorizedClientKeyType, authorized_client_type?: AuthorizedClientType): Promise<Record<string, any>>;
+  /**
+   * Remove an authorized client (public key) from the energy gateway. Removal
+   * needs no physical presence proof, so any paired key can revoke every other
+   * key, including the owner's. The reply is empty, and some firmware may
+   * return no body at all. This cloud route is inferred from
+   * `add_authorized_client`; removal was only live-verified over local v1r.
+   * @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>>;
+  /** Get the energy gateway's public key for signed commands. */
+  get_signed_commands_public_key(): Promise<Record<string, any>>;
+  /** Get backup events from the energy gateway. May time out on some firmware versions. */
+  get_backup_events(): 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 manual backup event on the energy gateway. */
+  cancel_backup_event(): Promise<Record<string, any>>;
+  /** Get Tesla Energy Gateway configuration from the TEG service. */
+  get_teg_config(): Promise<Record<string, any>>;
+  /**
+   * Request a timed battery power setpoint on the energy gateway.
+   *
+   * The gateway holds the setpoint for `duration_seconds`, then returns to its
+   * configured operating mode by itself. A new call replaces an active
+   * setpoint. Keep durations short and re-send to renew, so a caller that stops
+   * cannot leave the battery on a stale setpoint.
+   *
+   * The reply is an empty acknowledgement, not readback. A setpoint was seen to
+   * discharge below the backup reserve and to export with export set to
+   * `pv_only` or `never`. The gateway refuses a request above its power limit
+   * rather than clamping it: the signed path raises `DeviceUnexpectedResponse`
+   * with code 11.
+   *
+   * Tesla's cloud refuses this command unsigned (HTTP 400), so it acts only on
+   * a site with a signing key.
+   * @param power_watts Battery power in watts: positive discharges, negative charges.
+   * @param duration_seconds Whole seconds from 1 to 86400.
+   * @throws RangeError or TypeError before any request on invalid arguments.
+   */
+  dispatch_battery_power(power_watts: number, duration_seconds: number): Promise<Record<string, any>>;
+  /**
+   * Release a `dispatch_battery_power` setpoint, returning the gateway to its
+   * configured operating mode. The gateway also acknowledges this when no
+   * setpoint is active. It acts only on a site with a signing key.
+   */
+  resume_battery_operation(): Promise<Record<string, any>>;
+  /**
+   * Set the island mode on the energy gateway.
+   *
+   * Signed only: gateways acknowledge the unsigned `grpc_command` without
+   * operating the grid contactor, so this never sends one. A success-shaped
+   * reply still does not prove the contactor moved: confirm `island_status`
+   * with a status read before relying on it.
+   * @param mode `EnergyIslandMode.OFF_GRID` (6) or `ON_GRID` (1).
+   * @param force Sent when given. Some gateways need `true` to open the contactor.
+   * @throws TypeError on any other mode, before signing.
+   * @throws SignedCommandRequired without a signing key, before any request.
+   * @throws DeviceUnexpectedResponse when the gateway refuses, as `REJECTED_LOW_ENERGY` and the like.
+   */
+  set_island_mode(mode: EnergyIslandMode | number, force?: boolean | null): Promise<Record<string, any>>;
+  /** Request off-grid mode, with `force`. Signed only: see `set_island_mode`. */
+  go_off_grid(): Promise<Record<string, any>>;
+  /** Request on-grid mode. Signed only: see `set_island_mode`. */
+  reconnect_grid(): Promise<Record<string, any>>;
   /**
    * Adjust the site's backup reserve.
    * @param backup_reserve_percent The desired backup reserve percent.
@@ -13,33 +191,30 @@ declare class EnergySpecific {
   backup(backup_reserve_percent: number): Promise<Record<string, any>>;
   /**
    * Returns the backup (off-grid) event history of the site in duration of seconds.
-   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
+   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
    * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
    * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
    * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
    * @returns
    */
-  backup_history(kind: string, start_date: string, end_date: string, period: string, time_zone: string): Promise<Record<string, any>>;
+  backup_history(period: TeslaEnergyPeriod | string | null, start_date?: string | null, end_date?: string | null, time_zone?: string | null): Promise<Record<string, any>>;
   /**
    * Returns the charging history of a wall connector.
-   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-   * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param start_date Start date of the window to retrieve charging events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve charging events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
    * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
    * @returns
    */
-  charge_history(kind: string, start_date: string, end_date: string, time_zone: string): Promise<Record<string, any>>;
+  charge_history(start_date: string, end_date: string, time_zone?: string | null): Promise<Record<string, any>>;
   /**
-   * Returns the energy history of the site in duration of seconds.
-   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-   * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
+   * Returns the energy measurements of the site, aggregated to the requested period.
+   * @param period Period of the window to retrieve energy measurements. This can be day, week, month, year, lifetime and should align with the window requested.
+   * @param start_date Start date of the window to retrieve energy measurements in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve energy measurements in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
    * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
    * @returns
    */
-  energy_history(kind: string, start_date: string, end_date: string, period: string, time_zone: string): Promise<Record<string, any>>;
+  energy_history(period: TeslaEnergyPeriod | string | null, start_date?: string | null, end_date?: string | null, time_zone?: string | null): Promise<Record<string, any>>;
   /**
    * Allow/disallow charging from the grid and exporting energy to the grid.
    * @param disallow_charge_from_grid_with_solar_installed The desired behavior towards importing from the grid. Charging from the grid is disabled when set to true and enabled when set to false.
@@ -51,7 +226,7 @@ declare class EnergySpecific {
    * Returns the live status of the site.
    * @returns
    */
-  live_status(): Promise<LiveStatusResponse>;
+  live_status(): Promise<ResponseEnvelope<LiveStatusResponse>>;
   /**
    * Adjust the site's off-grid vehicle charging backup reserve.
    * @param off_grid_vehicle_charging_reserve_percent The desired off grid vehicle charging reserve percent.
@@ -67,12 +242,17 @@ declare class EnergySpecific {
   /**
    * Returns information about the site. Things like assets (has solar, etc), settings (backup reserve, etc), and features (storm_mode_capable, etc).
    */
-  site_info(): Promise<SiteInfoResponse>;
+  site_info(): Promise<ResponseEnvelope<SiteInfoResponse>>;
   /**
    * Update storm watch participation.
    * @param enabled The storm mode participation value to set.
    * @returns
    */
   storm_mode(enabled: boolean): Promise<Record<string, any>>;
-}
-export = EnergySpecific;
+  /**
+   * Update the time of use settings for the energy site.
+   * @param settings The `tariff_content_v2` document.
+   * @returns
+   */
+  time_of_use_settings(settings: Record<string, any>): Promise<Record<string, any>>;
+}

package/dist/energyspecific.d.mts

@@ -1,10 +1,188 @@
+import { AuthorizedClientKeyType, AuthorizedClientType, EnergyDeviceIdentifierType, EnergyIslandMode, TeslaEnergyPeriod } from "./const.mjs";
 import Energy from "./energy.mjs";
 import { LiveStatusResponse } from "./types/live_status.mjs";
+import { ResponseEnvelope } from "./types/responses.mjs";
 import { SiteInfoResponse } from "./types/site_info.mjs";
+import { KeyObject } from "crypto";
+/**
+ * The only device commands Tesla's cloud accepts unsigned, as
+ * `category.command`: the reads a gateway answers before any key is paired.
+ * Unsigned, every other command was refused with HTTP 400 live on a Powerwall 3
+ * (2026-10-29), and signed, each one reached the gateway. A site with a signing
+ * key signs everything else.
+ */
+export declare const UNSIGNED_DEVICE_COMMANDS: ReadonlySet<string>;
+/** Upper bound on a `dispatch_battery_power` setpoint duration (one day). */
+export declare const MAX_DISPATCH_DURATION_SECONDS = 86400;
+/**
+ * Check `dispatch_battery_power` arguments before any request.
+ * @throws TypeError unless both are numbers.
+ * @throws RangeError on a non-finite power or a duration that is not a whole number from 1 to `MAX_DISPATCH_DURATION_SECONDS`.
+ */
+export declare function validate_dispatch_battery_power(power_watts: number, duration_seconds: number): void;
 export default class EnergySpecific {
+  #private;
   parent: Energy;
   energy_site_id: number;
-  constructor(parent: Energy, energy_site_id: number);
+  /** Gateway DIN (the energy site's `gateway_id` in `products`), the target of device commands. */
+  din?: string;
+  /**
+   * Pass `private_key` and `din` to send client-signed device commands through
+   * the cloud `device_command` endpoint. With a signer, every device command is
+   * signed except the four pre-pairing reads in `UNSIGNED_DEVICE_COMMANDS`.
+   * Without one, device commands are sent unsigned, and Tesla's cloud refuses
+   * most of them with 400.
+   * @param parent
+   * @param energy_site_id
+   * @param private_key RSA key `VERIFIED` on this gateway. Without one the site is unsigned: unlike vehicles, there is no fallback to the parent's key.
+   * @param din Gateway DIN (the energy site's `gateway_id` in `products`). Required with `private_key`.
+   * @throws TypeError for a key that is not RSA.
+   */
+  constructor(parent: Energy, energy_site_id: number, private_key?: KeyObject, din?: string);
+  /** Whether device commands are signed with a client key. */
+  get signing(): boolean;
+  /**
+   * Send a gRPC command to the energy device gateway.
+   *
+   * With a signing key, this signs every command except the ones in
+   * `UNSIGNED_DEVICE_COMMANDS`. Otherwise it sends the unsigned `grpc_command`.
+   * Energy device gRPC commands are based on research from
+   * https://github.com/jasonacox/pypowerwall (MIT licensed).
+   */
+  _command(category: string, command: string, params?: Record<string, any> | null, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /** Send an unsigned `grpc_command` to the energy device gateway. */
+  _unsigned_command(category: string, command: string, params?: Record<string, any> | null, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /** Build the flat `device_command` body around a signed message. */
+  protected _device_command_body(routable_message: Uint8Array, target_id: string, identifier_type: EnergyDeviceIdentifierType): Record<string, any>;
+  /**
+   * Send a signed `RoutableMessage` to the energy device. Tesla requires the
+   * body wrapped in `data` and `identifier_type` as an integer. The reply is
+   * returned unchanged; `_signed_command` checks it for a gateway error.
+   */
+  _device_command(routable_message: Uint8Array, target_id: string, identifier_type?: EnergyDeviceIdentifierType): Promise<Record<string, any>>;
+  /**
+   * Sign a gRPC command with the site's key and send it to the gateway.
+   *
+   * A resend of the same signed bytes inside the TTL executes again, so this
+   * never retries.
+   * @throws SignedCommandRequired when the site has no signing key.
+   * @throws InvalidCommand when the gateway firmware has no handler for the command.
+   * @throws DeviceUnexpectedResponse when the gateway refuses the command.
+   */
+  _signed_command(category: string, command: string, params?: Record<string, any> | null): Promise<Record<string, any>>;
+  /** Get energy device system information including firmware version, device type, part number, serial number, and DIN. */
+  get_system_info(): Promise<Record<string, any>>;
+  /** Get raw energy device networking status including WiFi, Ethernet, and cellular connectivity. */
+  raw_networking_status(): Promise<Record<string, any>>;
+  /** Get energy device networking status including WiFi, Ethernet, and cellular connectivity. */
+  get_networking_status(): Promise<Record<string, any>>;
+  /** Scan for available WiFi networks from the energy gateway. */
+  wifi_scan(): Promise<Record<string, any>>;
+  /** Get the energy device certificate including subject, issuer, and validity. */
+  get_device_cert(): Promise<Record<string, any>>;
+  /** Get cellular modem information from the energy gateway including the embedded SIM identifier (EID) and supported cellular profiles. */
+  get_cellular_info(): Promise<Record<string, any>>;
+  /** Check if a firmware update is available for the energy gateway. */
+  check_for_update(): Promise<Record<string, any>>;
+  /** Check the urgency level of any available firmware update for the energy gateway. */
+  check_for_update_urgency(): Promise<Record<string, any>>;
+  /** Test internet connectivity on the energy gateway across all network interfaces (WiFi, Ethernet, GSM). */
+  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>>;
+  /** List authorized clients (paired keys) on the energy gateway including their roles and state. */
+  list_authorized_clients(): Promise<Record<string, any>>;
+  /**
+   * Register an authorized client (public key) with the energy gateway, to
+   * pair a local key with a Powerwall for the LAN TEDapi v1r protocol. The
+   * encoding follows `key_type`: RSA is raw PKCS#1 `RSAPublicKey` DER
+   * (`rsa_public_der_pkcs1`), and ECC is DER SubjectPublicKeyInfo
+   * (`ec_public_der_spki`), not a raw point, which the gateway rejects. A
+   * VERIFIED ECC key still cannot sign v1r: `SignatureData` has no ECDSA member.
+   *
+   * The key stays PENDING_VERIFICATION until a physical breaker toggle confirms
+   * it inside a window of about 9 minutes. A missed window is the terminal
+   * PENDING_VERIFICATION_TIMEOUT; registering the same key again resets it
+   * without a second record.
+   * @param public_key Raw DER bytes, 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, description?: string, key_type?: AuthorizedClientKeyType, authorized_client_type?: AuthorizedClientType): Promise<Record<string, any>>;
+  /**
+   * Remove an authorized client (public key) from the energy gateway. Removal
+   * needs no physical presence proof, so any paired key can revoke every other
+   * key, including the owner's. The reply is empty, and some firmware may
+   * return no body at all. This cloud route is inferred from
+   * `add_authorized_client`; removal was only live-verified over local v1r.
+   * @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>>;
+  /** Get the energy gateway's public key for signed commands. */
+  get_signed_commands_public_key(): Promise<Record<string, any>>;
+  /** Get backup events from the energy gateway. May time out on some firmware versions. */
+  get_backup_events(): 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 manual backup event on the energy gateway. */
+  cancel_backup_event(): Promise<Record<string, any>>;
+  /** Get Tesla Energy Gateway configuration from the TEG service. */
+  get_teg_config(): Promise<Record<string, any>>;
+  /**
+   * Request a timed battery power setpoint on the energy gateway.
+   *
+   * The gateway holds the setpoint for `duration_seconds`, then returns to its
+   * configured operating mode by itself. A new call replaces an active
+   * setpoint. Keep durations short and re-send to renew, so a caller that stops
+   * cannot leave the battery on a stale setpoint.
+   *
+   * The reply is an empty acknowledgement, not readback. A setpoint was seen to
+   * discharge below the backup reserve and to export with export set to
+   * `pv_only` or `never`. The gateway refuses a request above its power limit
+   * rather than clamping it: the signed path raises `DeviceUnexpectedResponse`
+   * with code 11.
+   *
+   * Tesla's cloud refuses this command unsigned (HTTP 400), so it acts only on
+   * a site with a signing key.
+   * @param power_watts Battery power in watts: positive discharges, negative charges.
+   * @param duration_seconds Whole seconds from 1 to 86400.
+   * @throws RangeError or TypeError before any request on invalid arguments.
+   */
+  dispatch_battery_power(power_watts: number, duration_seconds: number): Promise<Record<string, any>>;
+  /**
+   * Release a `dispatch_battery_power` setpoint, returning the gateway to its
+   * configured operating mode. The gateway also acknowledges this when no
+   * setpoint is active. It acts only on a site with a signing key.
+   */
+  resume_battery_operation(): Promise<Record<string, any>>;
+  /**
+   * Set the island mode on the energy gateway.
+   *
+   * Signed only: gateways acknowledge the unsigned `grpc_command` without
+   * operating the grid contactor, so this never sends one. A success-shaped
+   * reply still does not prove the contactor moved: confirm `island_status`
+   * with a status read before relying on it.
+   * @param mode `EnergyIslandMode.OFF_GRID` (6) or `ON_GRID` (1).
+   * @param force Sent when given. Some gateways need `true` to open the contactor.
+   * @throws TypeError on any other mode, before signing.
+   * @throws SignedCommandRequired without a signing key, before any request.
+   * @throws DeviceUnexpectedResponse when the gateway refuses, as `REJECTED_LOW_ENERGY` and the like.
+   */
+  set_island_mode(mode: EnergyIslandMode | number, force?: boolean | null): Promise<Record<string, any>>;
+  /** Request off-grid mode, with `force`. Signed only: see `set_island_mode`. */
+  go_off_grid(): Promise<Record<string, any>>;
+  /** Request on-grid mode. Signed only: see `set_island_mode`. */
+  reconnect_grid(): Promise<Record<string, any>>;
   /**
    * Adjust the site's backup reserve.
    * @param backup_reserve_percent The desired backup reserve percent.
@@ -13,33 +191,30 @@ export default class EnergySpecific {
   backup(backup_reserve_percent: number): Promise<Record<string, any>>;
   /**
    * Returns the backup (off-grid) event history of the site in duration of seconds.
-   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
+   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
    * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
    * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
    * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
    * @returns
    */
-  backup_history(kind: string, start_date: string, end_date: string, period: string, time_zone: string): Promise<Record<string, any>>;
+  backup_history(period: TeslaEnergyPeriod | string | null, start_date?: string | null, end_date?: string | null, time_zone?: string | null): Promise<Record<string, any>>;
   /**
    * Returns the charging history of a wall connector.
-   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-   * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param start_date Start date of the window to retrieve charging events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve charging events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
    * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
    * @returns
    */
-  charge_history(kind: string, start_date: string, end_date: string, time_zone: string): Promise<Record<string, any>>;
+  charge_history(start_date: string, end_date: string, time_zone?: string | null): Promise<Record<string, any>>;
   /**
-   * Returns the energy history of the site in duration of seconds.
-   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-   * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
+   * Returns the energy measurements of the site, aggregated to the requested period.
+   * @param period Period of the window to retrieve energy measurements. This can be day, week, month, year, lifetime and should align with the window requested.
+   * @param start_date Start date of the window to retrieve energy measurements in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve energy measurements in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
    * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
    * @returns
    */
-  energy_history(kind: string, start_date: string, end_date: string, period: string, time_zone: string): Promise<Record<string, any>>;
+  energy_history(period: TeslaEnergyPeriod | string | null, start_date?: string | null, end_date?: string | null, time_zone?: string | null): Promise<Record<string, any>>;
   /**
    * Allow/disallow charging from the grid and exporting energy to the grid.
    * @param disallow_charge_from_grid_with_solar_installed The desired behavior towards importing from the grid. Charging from the grid is disabled when set to true and enabled when set to false.
@@ -51,7 +226,7 @@ export default class EnergySpecific {
    * Returns the live status of the site.
    * @returns
    */
-  live_status(): Promise<LiveStatusResponse>;
+  live_status(): Promise<ResponseEnvelope<LiveStatusResponse>>;
   /**
    * Adjust the site's off-grid vehicle charging backup reserve.
    * @param off_grid_vehicle_charging_reserve_percent The desired off grid vehicle charging reserve percent.
@@ -67,11 +242,17 @@ export default class EnergySpecific {
   /**
    * Returns information about the site. Things like assets (has solar, etc), settings (backup reserve, etc), and features (storm_mode_capable, etc).
    */
-  site_info(): Promise<SiteInfoResponse>;
+  site_info(): Promise<ResponseEnvelope<SiteInfoResponse>>;
   /**
    * Update storm watch participation.
    * @param enabled The storm mode participation value to set.
    * @returns
    */
   storm_mode(enabled: boolean): Promise<Record<string, any>>;
+  /**
+   * Update the time of use settings for the energy site.
+   * @param settings The `tariff_content_v2` document.
+   * @returns
+   */
+  time_of_use_settings(settings: Record<string, any>): Promise<Record<string, any>>;
 }