tesla-fleet-api 0.4.0 → 0.6.0

package/dist/powerwall/client.d.cts

@@ -0,0 +1,297 @@
+import { Logger } from "../log.cjs";
+import { AuthorizedClientsPayload, BackupEventsPayload, BatteryCalibrationDelayStatus, ComponentsPayload, ConfigPayload, ControllableDeviceProgramsPayload, ControllerPayload, FirmwareDetails, StatusPayload } from "./models.cjs";
+/** The gateway's own Wi-Fi access point. */
+export declare const DEFAULT_GATEWAY_HOST = "192.168.91.1";
+/** Values of `default_real_mode`. Each sticks and reads back verbatim on a Powerwall 3. */
+export declare const OPERATION_MODES: readonly ["self_consumption", "autonomous", "backup"];
+/** Values of `site_info.customer_preferred_export_rule`. Each sticks and reads back verbatim on a Powerwall 3. */
+export declare const GRID_EXPORT_RULES: readonly ["battery_ok", "pv_only", "never"];
+export interface PowerwallClientOptions {
+  /** The gateway address, optionally `host:port`. */
+  host?: string;
+  /** The full gateway/Wi-Fi password, or its last 5 characters. */
+  gatewayPassword: string;
+  /** An RSA key already paired with the gateway through the cloud. */
+  rsaPrivateKeyPem: string | Buffer;
+  /** Total time allowed per request. */
+  timeoutMs?: number;
+  /** The gateway's DIN, when known. Any other DIN fails `connect`, so nothing is sent to the wrong gateway. */
+  expectedDin?: string;
+  /** Receives debug lines. */
+  logger?: Logger;
+}
+/**
+ * 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.
+ */
+export declare class PowerwallClient {
+  #private;
+  /** @throws PowerwallAuthenticationError for a bad PEM or a key that is not RSA. */
+  constructor(options: PowerwallClientOptions, _legacyGateway?: boolean);
+  /**
+   * 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: PowerwallClientOptions): PowerwallClient;
+  get host(): string;
+  /** The gateway DIN, or `null` until `connect` succeeds. */
+  get din(): string | null;
+  /** True between `curtail` and `restore_from_curtailment`. */
+  get curtailment_active(): boolean;
+  /** Log in and fetch the gateway DIN. Idempotent, and concurrent callers share one attempt. */
+  connect(): Promise<string>;
+  /** Destroy the idle sockets. */
+  close(): void;
+  /** The cached DIN, connecting first if needed. */
+  get_din(): Promise<string>;
+  /** `/api/meters/aggregates`: instantaneous power per location. */
+  get_meters_aggregates(): Promise<Record<string, any>>;
+  /** The raw state of charge, where the bottom 5% is an inaccessible buffer. It reads higher than the Tesla app. */
+  get_battery_soe_raw(): Promise<number>;
+  /** The state of charge the Tesla app and Fleet API show. */
+  get_battery_soe(): Promise<number>;
+  /** The gateway grid status string, such as `SystemGridConnected`. */
+  get_grid_status(): Promise<string>;
+  /** The gateway's `config.json`. `battery_blocks` is always present. */
+  get_config(): Promise<ConfigPayload>;
+  /** The gateway status, from the narrow DeviceControllerQuery. */
+  get_status(): Promise<StatusPayload>;
+  /** The extended DeviceControllerQuery payload. */
+  get_device_controller(): Promise<ControllerPayload>;
+  /** Powerwall 3 component data: `pch`, `pws`, `bms`, `hvp` and `baggr`. */
+  get_components(): Promise<ComponentsPayload>;
+  /** Gateway firmware details. Python's `five` and `six` keys are `update_status` and `device_type` here. */
+  get_firmware_details(): Promise<FirmwareDetails>;
+  /** The active manual backup and any scheduled backup events. Times are epoch seconds. */
+  get_backup_events(): Promise<BackupEventsPayload>;
+  /**
+   * The battery calibration delay counters.
+   * @throws PowerwallNotSupportedError on firmware without this command. Powerwall 3 firmware 26.26.4 is one.
+   */
+  get_battery_calibration_delay_status(): Promise<BatteryCalibrationDelayStatus>;
+  /**
+   * 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.
+   */
+  get_controllable_device_programs(device_ids?: string[]): Promise<ControllableDeviceProgramsPayload>;
+  /** The keys paired with the gateway, in the gateway's raw form. */
+  list_authorized_clients(): Promise<AuthorizedClientsPayload>;
+  /**
+   * 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`.
+   */
+  write_config(updates: Record<string, unknown>): Promise<void>;
+  private _write_config;
+  /**
+   * Set the backup reserve on the app's 0-100 scale.
+   * @throws RangeError outside 0-100.
+   */
+  set_backup_reserve(percent: number): Promise<void>;
+  /**
+   * Write the backup reserve on the gateway's raw scale, where app 0% is raw 5%.
+   * @throws RangeError outside 0-100.
+   */
+  set_backup_reserve_raw(percent: number): Promise<void>;
+  /**
+   * Set the operation mode, as `operation` does through the cloud.
+   * @param mode One of `OPERATION_MODES`.
+   * @throws RangeError for any other value.
+   */
+  set_operation_mode(mode: string): Promise<void>;
+  /**
+   * 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.
+   */
+  set_tou_mode(mode: string): Promise<void>;
+  /**
+   * 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.
+   */
+  set_grid_import_export(options: {
+    customer_preferred_export_rule?: string | null;
+    disallow_charge_from_grid_with_solar_installed?: boolean | null;
+  }): Promise<void>;
+  /**
+   * 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.
+   */
+  set_export_rule(rule: string): Promise<void>;
+  /**
+   * 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".
+   */
+  set_grid_charging(enabled: boolean): Promise<void>;
+  /**
+   * Enable on-grid solar curtailment. The gateway drops the key rather than
+   * store `false`, so treat an absent key as disabled.
+   */
+  set_on_grid_solar_curtailment(enabled: boolean): Promise<void>;
+  /**
+   * Cap grid import, in kilowatts, stored as given.
+   * @throws RangeError on a negative value.
+   */
+  set_import_limit(kilowatts: number): Promise<void>;
+  /**
+   * Cap grid export, in kilowatts. Pass a positive magnitude: the gateway
+   * represents export as negative site-meter power.
+   * @throws RangeError on a negative value.
+   */
+  set_export_limit(kilowatts: number): Promise<void>;
+  /**
+   * 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.
+   */
+  curtail(options?: {
+    reserve_percent?: number;
+  }): Promise<void>;
+  /** Write back what `curtail` replaced, or `self_consumption` at a raw 5 if nothing was saved. */
+  restore_from_curtailment(): Promise<void>;
+  /**
+   * 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.
+   */
+  schedule_max_backup(duration_seconds?: number): Promise<void>;
+  /** Cancel the active manual backup event, if any. */
+  cancel_max_backup(): Promise<void>;
+  /**
+   * 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.
+   */
+  dispatch_battery_power(power_watts: number, duration_seconds: number): Promise<void>;
+  /** Release a `dispatch_battery_power` setpoint. This does not cancel a manual backup event. */
+  resume_battery_operation(): Promise<void>;
+  /**
+   * 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`.
+   */
+  delay_battery_calibration(delay_hours: number): Promise<void>;
+  /**
+   * Point the gateway at an OCPP central system.
+   * @throws PowerwallNotSupportedError on firmware without this command. Powerwall 3 firmware 26.26.4 is one.
+   */
+  configure_ocpp(csms_base_url: string): Promise<void>;
+  /**
+   * 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.
+   */
+  remove_authorized_client(public_key: Uint8Array | string): Promise<void>;
+  /**
+   * 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`.
+   */
+  set_island_mode(options: {
+    off_grid: boolean;
+    force?: boolean;
+    mode_override?: number | null;
+  }): Promise<void>;
+  /**
+   * Disconnect from the grid. See `set_island_mode`, including its warning: read
+   * `islanding.contactorClosed` afterwards.
+   * @param options.force Defaults to true.
+   */
+  go_off_grid(options?: {
+    force?: boolean;
+    mode_override?: number | null;
+  }): Promise<void>;
+  /** Reconnect to the grid. See `set_island_mode`, including its warning: read `islanding.contactorClosed` afterwards. */
+  reconnect_grid(): Promise<void>;
+  /**
+   * 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`.
+   */
+  trigger_islanding(): Promise<void>;
+  private _cancel_manual_backup;
+  private _query_graphql;
+  private _read_config;
+  /** Sign, send once, and decode the reply envelope. */
+  private _post;
+  /**
+   * 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.
+   */
+  private _send_command_request;
+}
+/**
+ * Convert a reserve percentage from the app's scale to the gateway's raw value.
+ * @throws RangeError outside 0-100.
+ */
+export declare function scaled_to_raw_reserve(percent: number): number;
+/** Convert a raw gateway reserve value to the app's scale. */
+export declare function raw_to_scaled_reserve(percent: number): number;
+/**
+ * Convert a state of charge from the app's scale to the raw value.
+ * @throws RangeError outside 0-100.
+ */
+export declare function scaled_to_raw_soc(percent: number): number;
+/** Convert a raw state of charge to the value the Tesla app and Fleet API show. */
+export declare function raw_to_scaled_soc(percent: number): number;
+/** The raw physical state of charge from a status payload, or `null` when either figure is missing or zero. */
+export declare function battery_level_raw(status: StatusPayload): number | null;
+/** The state of charge the Tesla app and Fleet API show, from a status payload, or `null`. */
+export declare function battery_level(status: StatusPayload): number | null;
+/** Real power in watts by upper-case meter location. Malformed aggregates give `{}`. */
+export declare function current_power(status: StatusPayload): Record<string, number | null>;
+/** Backup runtime in hours at the current load, or `null` when unknown. */
+export declare function backup_time_remaining(status: StatusPayload): number | null;

package/dist/powerwall/client.d.mts

@@ -0,0 +1,297 @@
+import { Logger } from "../log.mjs";
+import { AuthorizedClientsPayload, BackupEventsPayload, BatteryCalibrationDelayStatus, ComponentsPayload, ConfigPayload, ControllableDeviceProgramsPayload, ControllerPayload, FirmwareDetails, StatusPayload } from "./models.mjs";
+/** The gateway's own Wi-Fi access point. */
+export declare const DEFAULT_GATEWAY_HOST = "192.168.91.1";
+/** Values of `default_real_mode`. Each sticks and reads back verbatim on a Powerwall 3. */
+export declare const OPERATION_MODES: readonly ["self_consumption", "autonomous", "backup"];
+/** Values of `site_info.customer_preferred_export_rule`. Each sticks and reads back verbatim on a Powerwall 3. */
+export declare const GRID_EXPORT_RULES: readonly ["battery_ok", "pv_only", "never"];
+export interface PowerwallClientOptions {
+  /** The gateway address, optionally `host:port`. */
+  host?: string;
+  /** The full gateway/Wi-Fi password, or its last 5 characters. */
+  gatewayPassword: string;
+  /** An RSA key already paired with the gateway through the cloud. */
+  rsaPrivateKeyPem: string | Buffer;
+  /** Total time allowed per request. */
+  timeoutMs?: number;
+  /** The gateway's DIN, when known. Any other DIN fails `connect`, so nothing is sent to the wrong gateway. */
+  expectedDin?: string;
+  /** Receives debug lines. */
+  logger?: Logger;
+}
+/**
+ * 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.
+ */
+export declare class PowerwallClient {
+  #private;
+  /** @throws PowerwallAuthenticationError for a bad PEM or a key that is not RSA. */
+  constructor(options: PowerwallClientOptions, _legacyGateway?: boolean);
+  /**
+   * 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: PowerwallClientOptions): PowerwallClient;
+  get host(): string;
+  /** The gateway DIN, or `null` until `connect` succeeds. */
+  get din(): string | null;
+  /** True between `curtail` and `restore_from_curtailment`. */
+  get curtailment_active(): boolean;
+  /** Log in and fetch the gateway DIN. Idempotent, and concurrent callers share one attempt. */
+  connect(): Promise<string>;
+  /** Destroy the idle sockets. */
+  close(): void;
+  /** The cached DIN, connecting first if needed. */
+  get_din(): Promise<string>;
+  /** `/api/meters/aggregates`: instantaneous power per location. */
+  get_meters_aggregates(): Promise<Record<string, any>>;
+  /** The raw state of charge, where the bottom 5% is an inaccessible buffer. It reads higher than the Tesla app. */
+  get_battery_soe_raw(): Promise<number>;
+  /** The state of charge the Tesla app and Fleet API show. */
+  get_battery_soe(): Promise<number>;
+  /** The gateway grid status string, such as `SystemGridConnected`. */
+  get_grid_status(): Promise<string>;
+  /** The gateway's `config.json`. `battery_blocks` is always present. */
+  get_config(): Promise<ConfigPayload>;
+  /** The gateway status, from the narrow DeviceControllerQuery. */
+  get_status(): Promise<StatusPayload>;
+  /** The extended DeviceControllerQuery payload. */
+  get_device_controller(): Promise<ControllerPayload>;
+  /** Powerwall 3 component data: `pch`, `pws`, `bms`, `hvp` and `baggr`. */
+  get_components(): Promise<ComponentsPayload>;
+  /** Gateway firmware details. Python's `five` and `six` keys are `update_status` and `device_type` here. */
+  get_firmware_details(): Promise<FirmwareDetails>;
+  /** The active manual backup and any scheduled backup events. Times are epoch seconds. */
+  get_backup_events(): Promise<BackupEventsPayload>;
+  /**
+   * The battery calibration delay counters.
+   * @throws PowerwallNotSupportedError on firmware without this command. Powerwall 3 firmware 26.26.4 is one.
+   */
+  get_battery_calibration_delay_status(): Promise<BatteryCalibrationDelayStatus>;
+  /**
+   * 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.
+   */
+  get_controllable_device_programs(device_ids?: string[]): Promise<ControllableDeviceProgramsPayload>;
+  /** The keys paired with the gateway, in the gateway's raw form. */
+  list_authorized_clients(): Promise<AuthorizedClientsPayload>;
+  /**
+   * 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`.
+   */
+  write_config(updates: Record<string, unknown>): Promise<void>;
+  private _write_config;
+  /**
+   * Set the backup reserve on the app's 0-100 scale.
+   * @throws RangeError outside 0-100.
+   */
+  set_backup_reserve(percent: number): Promise<void>;
+  /**
+   * Write the backup reserve on the gateway's raw scale, where app 0% is raw 5%.
+   * @throws RangeError outside 0-100.
+   */
+  set_backup_reserve_raw(percent: number): Promise<void>;
+  /**
+   * Set the operation mode, as `operation` does through the cloud.
+   * @param mode One of `OPERATION_MODES`.
+   * @throws RangeError for any other value.
+   */
+  set_operation_mode(mode: string): Promise<void>;
+  /**
+   * 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.
+   */
+  set_tou_mode(mode: string): Promise<void>;
+  /**
+   * 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.
+   */
+  set_grid_import_export(options: {
+    customer_preferred_export_rule?: string | null;
+    disallow_charge_from_grid_with_solar_installed?: boolean | null;
+  }): Promise<void>;
+  /**
+   * 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.
+   */
+  set_export_rule(rule: string): Promise<void>;
+  /**
+   * 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".
+   */
+  set_grid_charging(enabled: boolean): Promise<void>;
+  /**
+   * Enable on-grid solar curtailment. The gateway drops the key rather than
+   * store `false`, so treat an absent key as disabled.
+   */
+  set_on_grid_solar_curtailment(enabled: boolean): Promise<void>;
+  /**
+   * Cap grid import, in kilowatts, stored as given.
+   * @throws RangeError on a negative value.
+   */
+  set_import_limit(kilowatts: number): Promise<void>;
+  /**
+   * Cap grid export, in kilowatts. Pass a positive magnitude: the gateway
+   * represents export as negative site-meter power.
+   * @throws RangeError on a negative value.
+   */
+  set_export_limit(kilowatts: number): Promise<void>;
+  /**
+   * 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.
+   */
+  curtail(options?: {
+    reserve_percent?: number;
+  }): Promise<void>;
+  /** Write back what `curtail` replaced, or `self_consumption` at a raw 5 if nothing was saved. */
+  restore_from_curtailment(): Promise<void>;
+  /**
+   * 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.
+   */
+  schedule_max_backup(duration_seconds?: number): Promise<void>;
+  /** Cancel the active manual backup event, if any. */
+  cancel_max_backup(): Promise<void>;
+  /**
+   * 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.
+   */
+  dispatch_battery_power(power_watts: number, duration_seconds: number): Promise<void>;
+  /** Release a `dispatch_battery_power` setpoint. This does not cancel a manual backup event. */
+  resume_battery_operation(): Promise<void>;
+  /**
+   * 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`.
+   */
+  delay_battery_calibration(delay_hours: number): Promise<void>;
+  /**
+   * Point the gateway at an OCPP central system.
+   * @throws PowerwallNotSupportedError on firmware without this command. Powerwall 3 firmware 26.26.4 is one.
+   */
+  configure_ocpp(csms_base_url: string): Promise<void>;
+  /**
+   * 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.
+   */
+  remove_authorized_client(public_key: Uint8Array | string): Promise<void>;
+  /**
+   * 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`.
+   */
+  set_island_mode(options: {
+    off_grid: boolean;
+    force?: boolean;
+    mode_override?: number | null;
+  }): Promise<void>;
+  /**
+   * Disconnect from the grid. See `set_island_mode`, including its warning: read
+   * `islanding.contactorClosed` afterwards.
+   * @param options.force Defaults to true.
+   */
+  go_off_grid(options?: {
+    force?: boolean;
+    mode_override?: number | null;
+  }): Promise<void>;
+  /** Reconnect to the grid. See `set_island_mode`, including its warning: read `islanding.contactorClosed` afterwards. */
+  reconnect_grid(): Promise<void>;
+  /**
+   * 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`.
+   */
+  trigger_islanding(): Promise<void>;
+  private _cancel_manual_backup;
+  private _query_graphql;
+  private _read_config;
+  /** Sign, send once, and decode the reply envelope. */
+  private _post;
+  /**
+   * 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.
+   */
+  private _send_command_request;
+}
+/**
+ * Convert a reserve percentage from the app's scale to the gateway's raw value.
+ * @throws RangeError outside 0-100.
+ */
+export declare function scaled_to_raw_reserve(percent: number): number;
+/** Convert a raw gateway reserve value to the app's scale. */
+export declare function raw_to_scaled_reserve(percent: number): number;
+/**
+ * Convert a state of charge from the app's scale to the raw value.
+ * @throws RangeError outside 0-100.
+ */
+export declare function scaled_to_raw_soc(percent: number): number;
+/** Convert a raw state of charge to the value the Tesla app and Fleet API show. */
+export declare function raw_to_scaled_soc(percent: number): number;
+/** The raw physical state of charge from a status payload, or `null` when either figure is missing or zero. */
+export declare function battery_level_raw(status: StatusPayload): number | null;
+/** The state of charge the Tesla app and Fleet API show, from a status payload, or `null`. */
+export declare function battery_level(status: StatusPayload): number | null;
+/** Real power in watts by upper-case meter location. Malformed aggregates give `{}`. */
+export declare function current_power(status: StatusPayload): Record<string, number | null>;
+/** Backup runtime in hours at the current load, or `null` when unknown. */
+export declare function backup_time_remaining(status: StatusPayload): number | null;