tesla-fleet-api 0.1.3 → 0.2.2

package/dist/commands.d.ts

@@ -0,0 +1,352 @@
+import { RoutableMessage } from "@teslemetry/tesla-protocol/command/universal_message";
+import { VehicleStatus } from "@teslemetry/tesla-protocol/command/vcsec";
+import { ClimateMode, CommandResponse, Level, Seat, Trunk } from "./types/commands.js";
+import Vehicle from "./vehicle.js";
+import VehicleSpecific from "./vehiclespecific.js";
+/**
+ * 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. Order can be used to specify order of multiple stops.
+     * @param lat Latitude
+     * @param lon Longitude
+     * @param order Order of multiple stops
+     */
+    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.
+     *
+     * The signed-command protobuf has a single `order` field carrying the
+     * supercharger identifier; a caller-supplied multi-stop `order` has no
+     * representable slot and is rejected rather than silently dropped.
+     * @param id Supercharger ID
+     * @param order Order of multiple stops - not representable in a signed command
+     */
+    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 Seat position
+     * @param auto_climate_on `true` or `false`
+     */
+    remote_auto_seat_climate_request(auto_seat_position: Seat | 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>;
+}