tesla-fleet-api 0.2.2 → 0.4.0

package/dist/commands.d.mts

@@ -0,0 +1,349 @@
+import { CommandResponse } from "./types/commands.mjs";
+import { AutoSeat, ClimateMode, Level, Seat, Trunk } from "./const.mjs";
+import Vehicle from "./vehicle.mjs";
+import VehicleSpecific from "./vehiclespecific.mjs";
+import { RoutableMessage } from "@teslemetry/tesla-protocol/command/universal_message";
+import { VehicleStatus } from "@teslemetry/tesla-protocol/command/vcsec";
+/**
+ * Transport-agnostic signed-command builder for the Tesla Vehicle Command
+ * Protocol: mirrors `python-tesla-fleet-api`'s `Commands` ABC. Every method
+ * here builds a `RoutableMessage`, signs it (HMAC-personalized), and
+ * dispatches it through the single abstract seam `_send`. A concrete
+ * subclass fills that seam for one transport - the cloud `/signed_command`
+ * HTTP endpoint (`VehicleSigned`) today, a BLE GATT link in a future story.
+ *
+ * AES-GCM personalized signing (the BLE-only auth mode) is intentionally out
+ * of scope here; see AGENTS.md.
+ */
+export default abstract class Commands extends VehicleSpecific {
+  #private;
+  /** Delay between WAIT-retries; overridable so tests don't have to wait for real timers. */
+  protected retryDelayMs: number;
+  private readonly fromDestination;
+  private readonly sessions;
+  constructor(parent: Vehicle, vin: string, privateKey?: Buffer, publicKey?: Buffer);
+  /**
+   * Transmit a signed (or session-handshake) `RoutableMessage` to the
+   * vehicle and return its reply. Implementations must call
+   * `validateAndUpdateSession(resp, msg.uuid)` on the reply before
+   * returning it.
+   */
+  protected abstract _send(msg: RoutableMessage, requires: string, expectsData?: boolean, confirmBroadcast?: (status: VehicleStatus) => boolean): Promise<RoutableMessage>;
+  private sessionFor;
+  /**
+   * Absorb session info piggy-backed on any signed-command reply and raise
+   * on a whitelist rejection or a terminal message fault. Every concrete
+   * `_send` must call this on the reply - passing the `uuid` of the request
+   * it just sent - before returning it.
+   *
+   * A `SessionInfo` is untrusted wire data until its `session_info_tag` is
+   * verified: the tag is an HMAC over the exact bytes received, keyed by a
+   * key derived from the *candidate* vehicle public key carried inside that
+   * same SessionInfo, and bound to this request's `uuid` as a challenge (so
+   * a captured older reply can't be replayed against a newer request). Only
+   * once that tag checks out do we act on anything the message claims -
+   * including its own whitelist-status field - and even then `Session.commit`
+   * still refuses a clock time that regresses within the same epoch.
+   */
+  protected validateAndUpdateSession(resp: RoutableMessage, requestUuid: Buffer): void;
+  private handshake;
+  private buildHmacMessage;
+  /**
+   * Build, sign, dispatch (with WAIT/epoch-fault retry), and interpret one
+   * domain command.
+   *
+   * VCSEC requires messages to arrive in strict counter order and warns
+   * clients to avoid simultaneous requests to it at all (unlike
+   * Infotainment, which tolerates a sliding window) - so for
+   * `DOMAIN_VEHICLE_SECURITY` the *entire* dispatch (handshake, build,
+   * send, and any retry) runs under the domain's lock, guaranteeing at
+   * most one VCSEC message is ever in flight. Infotainment keeps the
+   * narrower build-only lock, serializing only counter assignment.
+   */
+  private dispatch;
+  private interpretResponse;
+  private interpretVcsecResponse;
+  private interpretInfotainmentResponse;
+  private sendVehicleSecurity;
+  private sendInfotainment;
+  private vehicleAction;
+  private resolveSeat;
+  /**
+   * Controls the front (which_trunk: "front") or rear (which_trunk: "rear") trunk.
+   * @param which_trunk "front" or "rear"
+   */
+  actuate_truck(which_trunk: Trunk): Promise<CommandResponse>;
+  /**
+   * Adjusts vehicle media playback volume.
+   * @param volume A floating point number from 0.0 to 11.0.
+   */
+  adjust_volume(volume: number): Promise<CommandResponse>;
+  /** Starts climate preconditioning. */
+  auto_conditioning_start(): Promise<CommandResponse>;
+  /** Stops climate preconditioning. */
+  auto_conditioning_stop(): Promise<CommandResponse>;
+  /** Cancels the countdown to install the vehicle software update. */
+  cancel_software_update(): Promise<CommandResponse>;
+  /** Charges in max range mode -- we recommend limiting the use of this mode to long trips. */
+  charge_max_range(): Promise<CommandResponse>;
+  /** Closes the charge port door. */
+  charge_port_door_close(): Promise<CommandResponse>;
+  /** Opens the charge port door. */
+  charge_port_door_open(): Promise<CommandResponse>;
+  /** Charges in Standard mode. */
+  charge_standard(): Promise<CommandResponse>;
+  /** Starts charging the vehicle. */
+  charge_start(): Promise<CommandResponse>;
+  /** Stops charging the vehicle. */
+  charge_stop(): Promise<CommandResponse>;
+  /**
+   * Deactivates PIN to Drive and resets the associated PIN for vehicles running firmware versions 2023.44+. This command is only accessible to fleet managers or owners.
+   */
+  clear_pin_to_drive_admin(): Promise<CommandResponse>;
+  /** Locks the vehicle. */
+  door_lock(): Promise<CommandResponse>;
+  /** Unlocks the vehicle. */
+  door_unlock(): Promise<CommandResponse>;
+  /** Erases user's data from the user interface. Requires the vehicle to be in park. */
+  erase_user_data(): Promise<CommandResponse>;
+  /** Briefly flashes the vehicle headlights. Requires the vehicle to be in park. */
+  flash_lights(): Promise<CommandResponse>;
+  /**
+   * Restricts certain vehicle UI functionality from guest users
+   * @param enable `true` or `false`
+   */
+  guest_mode(enable: boolean): Promise<CommandResponse>;
+  /** Honks the vehicle horn. Requires the vehicle to be in park. */
+  honk_horn(): Promise<CommandResponse>;
+  /** Advances media player to next favorite track. */
+  media_next_fav(): Promise<CommandResponse>;
+  /** Advances media player to next track. */
+  media_next_track(): Promise<CommandResponse>;
+  /** Advances media player to previous favorite track. */
+  media_prev_fav(): Promise<CommandResponse>;
+  /** Advances media player to previous track. */
+  media_prev_track(): Promise<CommandResponse>;
+  /** Toggles current play/pause state. */
+  media_toggle_playback(): Promise<CommandResponse>;
+  /** Turns the volume down by one. */
+  media_volume_down(): Promise<CommandResponse>;
+  /**
+   * Start navigation to given coordinates.
+   * @param lat Latitude
+   * @param lon Longitude
+   * @param order Trip order: `0` replaces the current trip (default), `1` prepends it as the next stop, `2` appends it as the last stop
+   */
+  navigation_gps_request(lat: number, lon: number, order?: number): Promise<CommandResponse>;
+  /**
+   * Sends a location to the in-vehicle navigation system.
+   *
+   * `locale` and `type` are REST-only fields with no equivalent in the
+   * signed-command protocol (which only carries a destination string and a
+   * multi-stop order), so they are accepted for cross-transport signature
+   * parity but not sent.
+   * @param value Destination text
+   */
+  navigation_request(value: string, _locale?: string, _type?: string): Promise<CommandResponse>;
+  /**
+   * Start navigation to a supercharger.
+   * @param id Supercharger ID
+   * @param order Trip order: `0` replaces the current trip (default), `1` prepends it as the next stop, `2` appends it as the last stop
+   */
+  navigation_sc_request(id: number, order?: number): Promise<CommandResponse>;
+  /**
+   * Sets automatic seat heating and cooling. Only the front seats support this action.
+   * @param auto_seat_position `AutoSeat` position (1-indexed: front left is 1, front right is 2)
+   * @param auto_climate_on `true` or `false`
+   */
+  remote_auto_seat_climate_request(auto_seat_position: keyof typeof AutoSeat | number, auto_climate_on: boolean): Promise<CommandResponse>;
+  /**
+   * Sets automatic steering wheel heating on/off.
+   * @param on `true` or `false`
+   */
+  remote_auto_steering_wheel_heat_climate_request(on: boolean): Promise<CommandResponse>;
+  /**
+   * Plays a sound through the vehicle external speaker.
+   * @param sound Fart is `0`, Locate ping is `2000`
+   */
+  remote_boombox(sound?: number): Promise<CommandResponse>;
+  /**
+   * Sets seat cooling. Only the front seats support this action.
+   * @param seat_position Seat position
+   * @param seat_cooler_level Cooling level
+   */
+  remote_seat_cooler_request(seat_position: Seat | number, seat_cooler_level: Level): Promise<CommandResponse>;
+  /**
+   * Sets seat heating.
+   * @param seat_position Seat position
+   * @param seat_heater_level Heating level
+   */
+  remote_seat_heater_request(seat_position: Seat | number, seat_heater_level: Level): Promise<CommandResponse>;
+  /** Starts the vehicle remotely. Requires keyless driving to be enabled. */
+  remote_start_drive(): Promise<CommandResponse>;
+  /**
+   * Sets steering wheel heat level.
+   * @param level Heating level (0=Off, 1=Low, 2=High)
+   */
+  remote_steering_wheel_heat_level_request(level: Level): Promise<CommandResponse>;
+  /**
+   * Sets steering wheel heating on/off. For vehicles that do not support auto steering wheel heat.
+   * @param on `true` or `false`
+   */
+  remote_steering_wheel_heater_request(on: boolean): Promise<CommandResponse>;
+  /** Removes PIN to Drive. Requires the car to be in Pin to Drive mode and not in Valet mode. */
+  reset_pin_to_drive_pin(): Promise<CommandResponse>;
+  /** Removes PIN for Valet Mode. */
+  reset_valet_pin(): Promise<CommandResponse>;
+  /**
+   * Schedules a vehicle software update (over the air "OTA") to be installed in the future.
+   * @param offset_sec Offset in seconds
+   */
+  schedule_software_update(offset_sec: number): Promise<CommandResponse>;
+  /**
+   * Turns Bioweapon Defense Mode on and off.
+   * @param on `true` or `false`
+   * @param manual_override `true` or `false`
+   */
+  set_bioweapon_mode(on: boolean, manual_override: boolean): Promise<CommandResponse>;
+  /**
+   * Sets the vehicle overheat protection.
+   * @param on `true` or `false`
+   * @param fan_only `true` or `false`
+   */
+  set_cabin_overheat_protection(on: boolean, fan_only: boolean): Promise<CommandResponse>;
+  /**
+   * Sets the vehicle's charge limit to a custom percentage.
+   * @param percent Charge limit percentage typically between 50-100
+   */
+  set_charge_limit(percent: number): Promise<CommandResponse>;
+  /**
+   * Sets the charging amps.
+   * @param charging_amps Current limit in Amps typically between 5-32
+   */
+  set_charging_amps(charging_amps: number): Promise<CommandResponse>;
+  /**
+   * Enables climate keeper mode.
+   * @param climate_keeper_mode `0` is Off, `1` is Keep, `2` is Dog, `3` is Camp
+   */
+  set_climate_keeper_mode(climate_keeper_mode: number | ClimateMode): Promise<CommandResponse>;
+  /**
+   * Adjusts the Cabin Overheat Protection temperature (COP).
+   * @param cop_temp Integer representing Low (0/30C/90F), Medium (1/35C/95F), or High (2/40C/100F)
+   */
+  set_cop_temp(cop_temp: 0 | 1 | 2 | 30 | 35 | 40 | 90 | 95 | 100): Promise<CommandResponse>;
+  /**
+   * Sets a four-digit passcode for PIN to Drive.
+   * @param on `true` or `false`
+   * @param password Four-digit passcode
+   */
+  set_pin_to_drive(on: boolean, password: string | number): Promise<CommandResponse>;
+  /**
+   * Sets an override for preconditioning — it should default to empty if no override is used.
+   * @param on `true` or `false`
+   * @param manual_override `true` or `false`
+   */
+  set_preconditioning_max(on: boolean, manual_override: boolean): Promise<CommandResponse>;
+  /**
+   * Sets a time at which charging should be completed.
+   * @param enable `true` or `false`
+   * @param time Minutes after midnight
+   */
+  set_scheduled_charging(enable: boolean, time: number): Promise<CommandResponse>;
+  /**
+   * Sets a time at which departure should be completed.
+   *
+   * `preconditioning_enabled` and `off_peak_charging_enabled` are accepted
+   * for cross-transport signature parity but have no field in the signed
+   * command protobuf, so they are not sent.
+   * @param enable `true` or `false`
+   * @param preconditioning_enabled not representable in a signed command
+   * @param preconditioning_weekdays_only `true` or `false`
+   * @param departure_time Minutes after midnight
+   * @param off_peak_charging_enabled not representable in a signed command
+   * @param off_peak_charging_weekdays_only `true` or `false`
+   * @param end_off_peak_time Minutes after midnight
+   */
+  set_scheduled_departure(enable?: boolean, _preconditioning_enabled?: boolean, preconditioning_weekdays_only?: boolean, departure_time?: number, _off_peak_charging_enabled?: boolean, off_peak_charging_weekdays_only?: boolean, end_off_peak_time?: number): Promise<CommandResponse>;
+  /**
+   * Enables and disables Sentry Mode.
+   * @param on `true` or `false`
+   */
+  set_sentry_mode(on: boolean): Promise<CommandResponse>;
+  /**
+   * Sets the driver and/or passenger-side cabin temperature (and other zones if sync is enabled).
+   * @param driver_temp Driver temperature
+   * @param passenger_temp Passenger temperature
+   */
+  set_temps(driver_temp: number, passenger_temp: number): Promise<CommandResponse>;
+  /**
+   * Turns on Valet Mode and sets a four-digit passcode.
+   * @param on `true` or `false`
+   * @param password Four-digit passcode
+   */
+  set_valet_mode(on: boolean, password: string | number): Promise<CommandResponse>;
+  /**
+   * Changes the name of a vehicle.
+   * @param vehicle_name New name
+   */
+  set_vehicle_name(vehicle_name: string): Promise<CommandResponse>;
+  /**
+   * Activates Speed Limit Mode with a four-digit PIN.
+   * @param pin Four-digit PIN
+   */
+  speed_limit_activate(pin: string | number): Promise<CommandResponse>;
+  /**
+   * Deactivates Speed Limit Mode and resets the associated PIN.
+   * @param pin Four-digit PIN
+   */
+  speed_limit_clear_pin(pin: string | number): Promise<CommandResponse>;
+  /** Deactivates Speed Limit Mode and resets the associated PIN, for fleet managers or owners. */
+  speed_limit_clear_pin_admin(): Promise<CommandResponse>;
+  /**
+   * Deactivates Speed Limit Mode.
+   * @param pin Four-digit PIN
+   */
+  speed_limit_deactivate(pin: string | number): Promise<CommandResponse>;
+  /**
+   * Sets the maximum speed allowed when Speed Limit Mode is active.
+   * @param limit_mph Maximum speed in MPH
+   */
+  speed_limit_set_limit(limit_mph: number): Promise<CommandResponse>;
+  /**
+   * Controls the panoramic sunroof on the Model S.
+   *
+   * "stop" has no corresponding field in the signed-command protobuf (only
+   * vent/close/open), so it is rejected rather than guessed at.
+   * @param state "close" or "vent"
+   */
+  sun_roof_control(state: "stop" | "close" | "vent"): Promise<CommandResponse>;
+  /**
+   * Records a drive note. Overrides the inherited plaintext command so it is
+   * signed and dispatched over the vehicle-command protocol rather than
+   * silently falling through to the unsigned REST endpoint on vehicles that
+   * require signing.
+   * @param note Drive note
+   */
+  take_drivenote(note: string): Promise<CommandResponse>;
+  /**
+   * Turns on HomeLink (used to open and close garage doors).
+   * @param lat Latitude
+   * @param lon Longitude
+   * @param token
+   */
+  trigger_homelink(lat: number, lon: number, token?: string): Promise<CommandResponse>;
+  /**
+   * Sends upcoming calendar entries to the vehicle. Overrides the inherited
+   * plaintext command so it is signed and dispatched over the vehicle-command
+   * protocol rather than silently falling through to the unsigned REST
+   * endpoint on vehicles that require signing.
+   * @param calendar_data Calendar data
+   */
+  upcoming_calendar_entries(calendar_data: string): Promise<CommandResponse>;
+  /**
+   * Control the windows of a parked vehicle. Supported commands: vent and close.
+   * @param command "vent" or "close"
+   * @param lat Latitude
+   * @param lon Longitude
+   */
+  window_control(command: "vent" | "close", _lat?: number, _lon?: number): Promise<CommandResponse>;
+}