tesla-fleet-api 0.2.2 → 0.4.0

package/src/energyspecific.ts

@@ -1,116 +0,0 @@
-import Energy from "./energy.js";
-import { LiveStatusResponse } from "./types/live_status.js";
-import { SiteInfoResponse } from "./types/site_info.js";
-
-// Energy Class
-export default class EnergySpecific {
-    parent: Energy;
-    energy_site_id: number;
-
-    constructor(parent: Energy, energy_site_id: number) {
-        this.parent = parent;
-        this.energy_site_id = energy_site_id;
-    }
-
-    /**
-     * Adjust the site's backup reserve.
-     * @param backup_reserve_percent The desired backup reserve percent.
-     * @returns
-     */
-    async backup(backup_reserve_percent: number): Promise<Record<string, any>> {
-        return this.parent.backup(this.energy_site_id, backup_reserve_percent);
-    }
-
-    /**
-     * 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 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
-     */
-    async backup_history(kind: string, start_date: string, end_date: string, period: string, time_zone: string): Promise<Record<string, any>> {
-        return this.parent.backup_history(this.energy_site_id, kind, start_date, end_date, period, time_zone);
-    }
-
-    /**
-     * 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 time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
-     * @returns
-     */
-    async charge_history(kind: string, start_date: string, end_date: string, time_zone: string): Promise<Record<string, any>> {
-        return this.parent.charge_history(this.energy_site_id, kind, start_date, end_date, time_zone);
-    }
-
-    /**
-     * 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.
-     * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
-     * @returns
-     */
-    async energy_history(kind: string, start_date: string, end_date: string, period: string, time_zone: string): Promise<Record<string, any>> {
-        return this.parent.energy_history(this.energy_site_id, kind, start_date, end_date, period, time_zone);
-    }
-
-    /**
-     * 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.
-     * @param customer_preferred_export_rule The desired behavior for grid exporting. The available options are battery_ok, pv_only, and never.
-     * @returns
-     */
-    async grid_import_export(
-        disallow_charge_from_grid_with_solar_installed: boolean | null = null,
-        customer_preferred_export_rule: string | null = null
-    ): Promise<Record<string, any>> {
-        return this.parent.grid_import_export(this.energy_site_id, disallow_charge_from_grid_with_solar_installed, customer_preferred_export_rule);
-    }
-
-    /**
-     * Returns the live status of the site.
-     * @returns
-     */
-    async live_status(): Promise<LiveStatusResponse> {
-        return this.parent.live_status(this.energy_site_id);
-    }
-
-    /**
-     * 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.
-     * @returns
-     */
-    async off_grid_vehicle_charging_reserve(off_grid_vehicle_charging_reserve_percent: number): Promise<Record<string, any>> {
-        return this.parent.off_grid_vehicle_charging_reserve(this.energy_site_id, off_grid_vehicle_charging_reserve_percent);
-    }
-
-    /**
-     * Set the site's mode.
-     * @param default_real_mode
-     * @returns
-     */
-    async operation(default_real_mode: string): Promise<Record<string, any>> {
-        return this.parent.operation(this.energy_site_id, default_real_mode);
-    }
-
-    /**
-     * Returns information about the site. Things like assets (has solar, etc), settings (backup reserve, etc), and features (storm_mode_capable, etc).
-     */
-    async site_info(): Promise<SiteInfoResponse> {
-        return this.parent.site_info(this.energy_site_id);
-    }
-
-    /**
-     * Update storm watch participation.
-     * @param enabled The storm mode participation value to set.
-     * @returns
-     */
-    async storm_mode(enabled: boolean): Promise<Record<string, any>> {
-        return this.parent.storm_mode(this.energy_site_id, enabled);
-    }
-}

package/src/helpers.ts

@@ -1,11 +0,0 @@
-import { CommandResponse } from "./types/commands.js";
-
-export const validate = async (body: CommandResponse): Promise<void> => {
-    if (body?.error) {
-        return Promise.reject(body.error);
-    }
-    if (body?.response?.result == false) {
-        return Promise.reject(body.response.reason);
-    }
-    return Promise.resolve();
-};

package/src/index.ts

@@ -1,20 +0,0 @@
-import Commands from "./commands.js";
-import Energy from "./energy.js";
-import EnergySpecific from "./energyspecific.js";
-import TeslaFleetApi from "./teslafleetapi.js";
-import Teslemetry from "./teslemetry.js";
-import Tessie from "./tessie.js";
-import Vehicle from "./vehicle.js";
-import VehicleSigned from "./vehiclesigned.js";
-import VehicleSpecific from "./vehiclespecific.js";
-
-export { Commands, Energy, EnergySpecific, TeslaFleetApi, Teslemetry, Tessie, Vehicle, VehicleSigned, VehicleSpecific };
-export { Session } from "./signing/session.js";
-export {
-    SignedCommandError,
-    NotOnVehicleWhitelistError,
-    SignedCommandFaultError,
-    RetryableSignedCommandFaultError,
-} from "./signing/errors.js";
-export { getTariffPeriods } from "./tariff.js";
-export type { TariffRate, TariffPeriod, TariffResolution } from "./tariff.js";

package/src/partner.ts

@@ -1,37 +0,0 @@
-import TeslaFleetApi from "./teslafleetapi.js";
-
-// Partner Class
-export default class Partner {
-    parent: TeslaFleetApi;
-
-    constructor(parent: TeslaFleetApi) {
-        this.parent = parent;
-    }
-
-    /**
-     * Returns the public key associated with a domain. It can be used to ensure the registration was successful.
-     * @param domain Domain of the partner account.
-     * @returns
-     */
-    async public_key(domain: string | null = null): Promise<Record<string, any>> {
-        return this.parent._request("GET", "api/1/partner_accounts/public_key", { domain });
-    }
-
-    /**
-     * Registers an existing account before it can be used for general API access. Each application from developer.tesla.com must complete this step.
-     * @param domain Domain of the partner account.
-     * @returns
-     */
-    async register(domain: string): Promise<Record<string, any>> {
-        return this.parent._request("POST", "api/1/partner_accounts", null, { domain });
-    }
-
-    /**
-     * Returns recent fleet telemetry errors reported by vehicles after receiving the config.
-     * @param domain Domain of the partner account.
-     * @returns
-     */
-    async fleet_telemetry_errors(domain: string): Promise<Record<string, any>> {
-        return this.parent._request("GET", "api/1/partner_accounts/fleet_telemetry_errors", { domain });
-    }
-}

package/src/signing/crypto.ts

@@ -1,29 +0,0 @@
-import crypto from "crypto";
-
-const CURVE = "prime256v1"; // NIST P-256, matches the vehicle-command protocol.
-
-/** Derive the uncompressed public key point for a raw P-256 private scalar. */
-export function publicKeyFor(privateKey: Buffer): Buffer {
-    const ecdh = crypto.createECDH(CURVE);
-    ecdh.setPrivateKey(privateKey);
-    return ecdh.getPublicKey();
-}
-
-/**
- * Derive the 16-byte signed-command shared key: ECDH(ourPrivate, vehiclePublic),
- * then SHA-1 truncated to 16 bytes - matching the vehicle-command protocol
- * (not a general-purpose KDF, do not reuse this for anything else).
- */
-export function deriveSharedKey(privateKey: Buffer, vehiclePublicKey: Buffer): Buffer {
-    const ecdh = crypto.createECDH(CURVE);
-    ecdh.setPrivateKey(privateKey);
-    const secret = ecdh.computeSecret(vehiclePublicKey);
-    return crypto.createHash("sha1").update(secret).digest().subarray(0, 16);
-}
-
-/** Big-endian uint32, as used throughout the signed-command metadata tags. */
-export function uint32BE(value: number): Buffer {
-    const buffer = Buffer.alloc(4);
-    buffer.writeUInt32BE(value >>> 0, 0);
-    return buffer;
-}

package/src/signing/errors.ts

@@ -1,50 +0,0 @@
-import { MessageFaultE, messageFaultEToJSON } from "@teslemetry/tesla-protocol/command/universal_message";
-
-/**
- * Base class for every error raised by the signed-command layer.
- */
-export class SignedCommandError extends Error {}
-
-/**
- * The vehicle rejected the session handshake because this key has not been
- * paired with it (added via the Tesla app / NFC card).
- */
-export class NotOnVehicleWhitelistError extends SignedCommandError {
-    constructor() {
-        super(
-            "This public key is not on the vehicle's key whitelist. Pair it with the vehicle first.",
-        );
-    }
-}
-
-/**
- * The vehicle rejected a signed command with a `MessageFaultE` other than
- * `MESSAGEFAULT_ERROR_NONE`.
- */
-export class SignedCommandFaultError extends SignedCommandError {
-    fault: MessageFaultE;
-
-    constructor(fault: MessageFaultE) {
-        super(`Vehicle rejected signed command: ${messageFaultEToJSON(fault)}`);
-        this.fault = fault;
-    }
-}
-
-/**
- * A `SignedCommandFaultError` whose fault the vehicle resolves by handing back
- * fresh session info (epoch/counter drift) - `_command` retries these,
- * bounded, by re-signing against the updated session before giving up.
- */
-export class RetryableSignedCommandFaultError extends SignedCommandFaultError {}
-
-export function createFaultError(
-    fault: MessageFaultE,
-): SignedCommandFaultError {
-    if (
-        fault === MessageFaultE.MESSAGEFAULT_ERROR_INCORRECT_EPOCH ||
-        fault === MessageFaultE.MESSAGEFAULT_ERROR_INVALID_TOKEN_OR_COUNTER
-    ) {
-        return new RetryableSignedCommandFaultError(fault);
-    }
-    return new SignedCommandFaultError(fault);
-}

package/src/signing/session.ts

@@ -1,132 +0,0 @@
-import crypto from "crypto";
-import { Domain } from "@teslemetry/tesla-protocol/command/universal_message";
-import {
-    HMACPersonalizedSignatureData,
-    SessionInfo,
-} from "@teslemetry/tesla-protocol/command/signatures";
-
-/** Key material derived (but not yet trusted/committed) for a candidate vehicle public key. */
-export interface SessionKeys {
-    sharedKey: Buffer;
-    hmacKey: Buffer;
-    sessionInfoKey: Buffer;
-}
-
-/**
- * Per-domain (VCSEC / Infotainment) signed-command session: tracks the
- * anti-replay counter/epoch handed out by the vehicle's handshake reply and
- * the HMAC keys derived from it.
- *
- * Deriving key material (`keysFor`) is split from committing it (`commit`)
- * because the caller must authenticate a `SessionInfo` reply - by verifying
- * its `session_info_tag` against the very keys derived here - *before*
- * trusting anything in it, including the vehicle public key the shared key
- * itself is derived from. See `Commands.validateAndUpdateSession`.
- *
- * A `Session` is not itself thread-safe; `withLock` serializes the
- * message-build step (which mutates `counter`) so concurrent commands on the
- * same domain cannot race on the same counter value.
- */
-export class Session {
-    readonly domain: Domain;
-    counter: number = 0;
-    epoch?: Buffer;
-    delta?: number;
-    sharedKey?: Buffer;
-    hmacKey?: Buffer;
-    sessionInfoKey?: Buffer;
-    publicKey?: Buffer;
-
-    /** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
-    private lastAuthenticatedClockTime?: number;
-    private queue: Promise<void> = Promise.resolve();
-
-    constructor(
-        domain: Domain,
-        private readonly deriveSharedKey: (vehiclePublicKey: Buffer) => Buffer,
-    ) {
-        this.domain = domain;
-    }
-
-    /** Whether the handshake has completed and commands can be signed. */
-    get ready(): boolean {
-        return this.epoch !== undefined && this.hmacKey !== undefined && this.delta !== undefined;
-    }
-
-    /**
-     * Derive the shared key and its two HMAC sub-keys for a candidate vehicle
-     * public key, without touching any session state. Pure and side-effect
-     * free so a caller can verify authenticity first and discard the result
-     * if verification fails.
-     */
-    keysFor(vehiclePublicKey: Buffer): SessionKeys {
-        const sharedKey = this.deriveSharedKey(vehiclePublicKey);
-        const hmacKey = crypto.createHmac("sha256", sharedKey).update("authenticated command").digest();
-        const sessionInfoKey = crypto.createHmac("sha256", sharedKey).update("session info").digest();
-        return { sharedKey, hmacKey, sessionInfoKey };
-    }
-
-    /**
-     * Commit an already-authenticated `SessionInfo` plus the `keysFor` result
-     * derived from its public key. Per the vehicle-command protocol, the
-     * anti-replay counter must never roll back within the same epoch, and a
-     * clock time that regresses within the same epoch marks the reply as
-     * stale/replayed - returns `false` (without mutating any state) in that
-     * case so the caller can reject it.
-     */
-    commit(sessionInfo: SessionInfo, keys: SessionKeys): boolean {
-        const incomingEpoch = Buffer.from(sessionInfo.epoch);
-        const sameEpoch = this.epoch !== undefined && this.epoch.equals(incomingEpoch);
-
-        if (sameEpoch && this.lastAuthenticatedClockTime !== undefined && sessionInfo.clockTime < this.lastAuthenticatedClockTime) {
-            return false;
-        }
-
-        this.counter = sameEpoch ? Math.max(this.counter, sessionInfo.counter) : sessionInfo.counter;
-        this.epoch = incomingEpoch;
-        this.delta = Math.floor(Date.now() / 1000) - sessionInfo.clockTime;
-        this.lastAuthenticatedClockTime = sessionInfo.clockTime;
-        this.publicKey = Buffer.from(sessionInfo.publicKey);
-        this.sharedKey = keys.sharedKey;
-        this.hmacKey = keys.hmacKey;
-        this.sessionInfoKey = keys.sessionInfoKey;
-        return true;
-    }
-
-    /**
-     * Advance the anti-replay counter and return fresh signature metadata for
-     * an HMAC-personalized command. The command expires 10 seconds from now,
-     * corrected for clock drift against the vehicle (`delta`).
-     */
-    hmacPersonalized(): HMACPersonalizedSignatureData {
-        if (!this.ready || !this.epoch || this.delta === undefined) {
-            throw new Error("Session is not ready: perform the handshake first.");
-        }
-        this.counter++;
-        return HMACPersonalizedSignatureData.create({
-            epoch: this.epoch,
-            counter: this.counter,
-            expiresAt: Math.floor(Date.now() / 1000) - this.delta + 10,
-        });
-    }
-
-    /**
-     * Run `fn` with exclusive access to this session, queuing behind any
-     * in-flight caller. Held only for as long as `fn` takes - callers should
-     * keep it scoped to the synchronous message-build step, not a full
-     * network round trip.
-     */
-    async withLock<T>(fn: () => T | Promise<T>): Promise<T> {
-        const previous = this.queue;
-        let release!: () => void;
-        this.queue = new Promise<void>((resolve) => {
-            release = resolve;
-        });
-        await previous.catch((): void => undefined);
-        try {
-            return await fn();
-        } finally {
-            release();
-        }
-    }
-}