tesla-fleet-api 0.4.0 → 0.6.0

package/dist/teslafleetapi.d.mts

@@ -3,25 +3,39 @@ import Energy from "./energy.mjs";
 import Partner from "./partner.mjs";
 import User from "./user.mjs";
 import Vehicle from "./vehicle.mjs";
-import { Method, Region } from "./const.mjs";
-import { EnergyProduct, ProductsResponse, VehicleProduct } from "./types/products.mjs";
+import { Method, Region, Scope } from "./const.mjs";
+import { EnergyProduct, ProductsData, VehicleProduct } from "./types/products.mjs";
+import { Logger } from "./log.mjs";
+import { KeyObject } from "node:crypto";
 export type ProductsByType = {
   vehicles: VehicleProduct[];
   energy_sites: EnergyProduct[];
 };
+/** An access token, or a function returning the current one (e.g. after an OAuth refresh). */
+export type AccessToken = string | (() => Promise<string | null>);
 export default class TeslaFleetApi {
+  #private;
+  /** Class backing `vehicles`; a subclass (e.g. `Teslemetry`) overrides it instead of its constructor. */
+  static Vehicles: new (parent: TeslaFleetApi) => Vehicle;
+  /** Class backing `energySites`; a subclass overrides it instead of its constructor. */
+  static EnergySites: new (parent: TeslaFleetApi) => Energy;
   server: string | null;
-  accessToken: string | null;
+  region: Region | null;
+  accessToken: AccessToken | null;
   charging?: Charging;
-  energy?: Energy;
+  energySites?: Energy;
   partner?: Partner;
   user?: User;
-  vehicle?: Vehicle;
+  vehicles?: Vehicle;
+  /** Log to `console.debug` when no `logger` is set. */
   debug: boolean;
+  logger: Logger | null;
   /** Abort a request (including reading its body) after this many milliseconds; `null` waits indefinitely. */
   timeout: number | null;
+  /** Transport identity for debug logging; Teslemetry and Tessie override this. */
+  readonly _transport_name: string;
   constructor(options: {
-    accessToken?: string;
+    accessToken?: AccessToken;
     region?: Region;
     server?: string;
     chargingScope?: boolean;
@@ -30,8 +44,26 @@ export default class TeslaFleetApi {
     userScope?: boolean;
     vehicleScope?: boolean;
     debug?: boolean;
+    logger?: Logger;
+    /** Used for every request in place of the global `fetch`. */
+    fetch?: typeof fetch;
     timeout?: number;
   });
+  /** Write a debug line to `logger`, or to `console.debug` when `debug` is set. */
+  _log(message: string): void;
+  /** The injected `fetch`, resolved per call so the global is read late. */
+  protected _fetch(input: string, init?: RequestInit): Promise<Response>;
+  /**
+   * Find the server for this user's region by asking each Tesla server in
+   * turn, skipping any that answers `InvalidRegion`.
+   * @returns The region, e.g. `"na"`.
+   */
+  find_server(): Promise<string>;
+  /**
+   * The current access token, calling it first if it is a function.
+   * @throws MissingToken when there is no token.
+   */
+  access_token(): Promise<string>;
   /**
    * Turn a response into its decoded JSON body, throwing the matching
    * `TeslaFleetError` for an error status and `ResponseError` for a
@@ -42,23 +74,87 @@ export default class TeslaFleetApi {
    * Make a request to the Tesla Fleet API.
    * @param method
    * @param path
-   * @param params
-   * @param json
+   * @param params Query parameters; null and undefined values are dropped.
+   * @param json Body; null and undefined values are dropped, and a GET sends none.
    * @returns The decoded JSON body.
-   * @throws A `TeslaFleetError` subclass for an error status, or
-   * `TeslaFleetConnectionError` (with the original error as `cause`) when the
-   * request could not complete or timed out.
+   * @throws `MissingToken` when there is no access token, a `TeslaFleetError`
+   * subclass for an error status, or `TeslaFleetConnectionError` (with the
+   * original error as `cause`) when the request could not complete or timed out.
    */
   _request(method: Method, path: string, params?: Record<string, any> | null, json?: Record<string, any> | null): Promise<any>;
+  /**
+   * Returns `"ok"` if the API is operating normally. Sends no headers.
+   */
+  status(): Promise<string>;
+  /**
+   * Generate a partner token using client credentials authentication, and use
+   * it as the access token for later requests.
+   * @param client_id Partner application client ID.
+   * @param client_secret Partner application client secret.
+   * @param scopes Scopes to request.
+   * @returns The token response, including `access_token`.
+   */
+  partner_login(client_id: string, client_secret: string, scopes?: Scope[]): Promise<Record<string, any>>;
   /**
    * Returns products mapped to user.
    * @returns An array of products including both vehicles and energy sites.
    */
-  products(): Promise<ProductsResponse>;
+  products(): Promise<ProductsData>;
   /**
    * Return Tesla products separated into vehicles and energy_sites
    * @returns A dictionary of vehicles and energy sites, each with an array of those products
    */
   products_by_type(): Promise<ProductsByType>;
-  loadPrivateKey(path: string): Promise<void>;
-}
+  /**
+   * Get or create the P-256 key that signs vehicle commands, and keep it as
+   * `private_key`. The file is an unencrypted PEM that Python's
+   * `get_private_key` shares, created at mode 0600. If another process wins the
+   * create race, its file is read instead.
+   * @param path Key file.
+   * @returns The raw 32-byte key `Commands` takes.
+   * @throws PrivateKeyError for an existing file that cannot be used.
+   */
+  get_private_key(path?: string): Promise<Buffer>;
+  /** The raw 32-byte P-256 key, which `createSigned` falls back to. */
+  get private_key(): Buffer | null;
+  set private_key(key: Buffer | null);
+  /** Whether the private key has been set. */
+  get has_private_key(): boolean;
+  /** The public key in PEM format. */
+  get public_pem(): string;
+  /** The public key's uncompressed point, in hex. */
+  get public_uncompressed_point(): string;
+  /**
+   * The EC public key in DER SubjectPublicKeyInfo form, as an energy gateway
+   * expects when registering an ECC authorized client. It rejects the raw point
+   * that vehicles use.
+   */
+  get ec_public_der_spki(): Buffer;
+  /** `ec_public_der_spki`, base64-encoded. */
+  get ec_public_der_spki_b64(): string;
+  /**
+   * Get or create the RSA key for energy gateway client registration, and keep
+   * it as `rsa_private_key`. The file is an unencrypted PEM that Python's
+   * `get_rsa_private_key` shares, created at mode 0600. If another process wins
+   * the create race, its file is read instead. Generation runs off the event loop.
+   * @param path Key file.
+   * @param key_size Modulus length in bits for a new key; 4096 is what Powerwall v1r expects.
+   * @throws PrivateKeyError for an existing file that cannot be used.
+   */
+  get_rsa_private_key(path?: string, key_size?: number): Promise<KeyObject>;
+  /** The RSA key for energy gateway client registration. */
+  get rsa_private_key(): KeyObject | null;
+  set rsa_private_key(key: KeyObject | null);
+  /** Whether the RSA private key has been set. */
+  get has_rsa_private_key(): boolean;
+  /**
+   * The RSA public key in DER PKCS#1 form, as an energy gateway expects when
+   * registering an authorized client.
+   */
+  get rsa_public_der_pkcs1(): Buffer;
+  /** `rsa_public_der_pkcs1`, base64-encoded. */
+  get rsa_public_der_pkcs1_b64(): string;
+  /** The RSA public key in PEM (SubjectPublicKeyInfo) format. */
+  get rsa_public_pem(): string;
+}
+export type { Logger };

package/dist/teslafleetapi.mjs

@@ -3,33 +3,95 @@ import Energy from "./energy.mjs";
 import Partner from "./partner.mjs";
 import User from "./user.mjs";
 import Vehicle from "./vehicle.mjs";
-import { SERVERS, is_valid_region } from "./const.mjs";
-import { ResponseError, TeslaFleetConnectionError, TeslaFleetError, raise_for_status } from "./exceptions.mjs";
+import { SERVERS, Scope, TOKEN_URLS, is_valid_region } from "./const.mjs";
+import { InvalidRegion, LibraryError, MissingToken, ResponseError, TeslaFleetConnectionError, TeslaFleetError, raise_for_status } from "./exceptions.mjs";
+import { logRequestError, logRequestResult, redactedJson, redactedQuery } from "./log.mjs";
+import { publicKeyFor } from "./signing/crypto.mjs";
+import { ecPrivateKeyFile, ecPublicKey, rsaPrivateKeyFile, rsaPublicDerPkcs1 } from "./signing/keys.mjs";
+import { createPublicKey } from "node:crypto";
 // src/teslafleetapi.ts
 var TeslaFleetApi = class {
+	/** Class backing `vehicles`; a subclass (e.g. `Teslemetry`) overrides it instead of its constructor. */
+	static Vehicles = Vehicle;
+	/** Class backing `energySites`; a subclass overrides it instead of its constructor. */
+	static EnergySites = Energy;
 	server = null;
+	region = null;
 	accessToken;
 	charging;
-	energy;
+	energySites;
 	partner;
 	user;
-	vehicle;
+	vehicles;
+	/** Log to `console.debug` when no `logger` is set. */
 	debug = false;
+	logger;
 	/** Abort a request (including reading its body) after this many milliseconds; `null` waits indefinitely. */
 	timeout;
+	/** Transport identity for debug logging; Teslemetry and Tessie override this. */
+	_transport_name = "fleet";
+	#fetch;
+	#privateKey = null;
+	#rsaPrivateKey = null;
 	constructor(options) {
 		this.debug = !!options.debug;
+		this.logger = options.logger ?? null;
+		this.#fetch = options.fetch ?? null;
 		this.timeout = options.timeout ?? null;
 		this.accessToken = options.accessToken ?? null;
 		if (options.server) this.server = options.server;
-		else if (options.region && is_valid_region(options.region)) this.server = SERVERS[options.region];
-		else throw new Error("Either server or region must be provided.");
-		this.debug && console.debug(`Using server ${this.server}`);
+		else if (options.region && is_valid_region(options.region)) {
+			this.region = options.region;
+			this.server = SERVERS[options.region];
+		} else throw new Error("Either server or region must be provided.");
+		this._log(`Using server ${this.server}`);
+		const factories = this.constructor;
 		if (options.chargingScope !== false) this.charging = new Charging(this);
-		if (options.energyScope !== false) this.energy = new Energy(this);
+		if (options.energyScope !== false) this.energySites = new factories.EnergySites(this);
 		if (options.userScope !== false) this.user = new User(this);
 		if (options.partnerScope !== false) this.partner = new Partner(this);
-		if (options.vehicleScope !== false) this.vehicle = new Vehicle(this);
+		if (options.vehicleScope !== false) this.vehicles = new factories.Vehicles(this);
+	}
+	/** Write a debug line to `logger`, or to `console.debug` when `debug` is set. */
+	_log(message) {
+		if (this.logger) this.logger.debug(message);
+		else if (this.debug) console.debug(message);
+	}
+	/** The injected `fetch`, resolved per call so the global is read late. */
+	_fetch(input, init) {
+		return (this.#fetch ?? fetch)(input, init);
+	}
+	/**
+	* Find the server for this user's region by asking each Tesla server in
+	* turn, skipping any that answers `InvalidRegion`.
+	* @returns The region, e.g. `"na"`.
+	*/
+	async find_server() {
+		for (const server of Object.values(SERVERS)) {
+			this.server = server;
+			try {
+				const { response } = await this._request("GET", "api/1/users/region");
+				if (response) {
+					this.server = response.fleet_api_base_url;
+					if (is_valid_region(response.region)) this.region = response.region;
+					this._log(`Using server ${this.server}`);
+					return response.region;
+				}
+			} catch (error) {
+				if (error instanceof InvalidRegion) continue;
+				throw error;
+			}
+		}
+		throw new LibraryError("Could not find a valid Tesla API server.");
+	}
+	/**
+	* The current access token, calling it first if it is a function.
+	* @throws MissingToken when there is no token.
+	*/
+	async access_token() {
+		const token = typeof this.accessToken === "function" ? await this.accessToken() : this.accessToken;
+		if (token == null) throw new MissingToken();
+		return token;
 	}
 	/**
 	* Turn a response into its decoded JSON body, throwing the matching
@@ -42,6 +104,7 @@ var TeslaFleetApi = class {
 		try {
 			return JSON.parse(text);
 		} catch {
+			this._log(`Response type is: ${resp.headers.get("content-type")}`);
 			throw new ResponseError(text, resp.status);
 		}
 	}
@@ -49,77 +112,215 @@ var TeslaFleetApi = class {
 	* Make a request to the Tesla Fleet API.
 	* @param method
 	* @param path
-	* @param params
-	* @param json
+	* @param params Query parameters; null and undefined values are dropped.
+	* @param json Body; null and undefined values are dropped, and a GET sends none.
 	* @returns The decoded JSON body.
-	* @throws A `TeslaFleetError` subclass for an error status, or
-	* `TeslaFleetConnectionError` (with the original error as `cause`) when the
-	* request could not complete or timed out.
+	* @throws `MissingToken` when there is no access token, a `TeslaFleetError`
+	* subclass for an error status, or `TeslaFleetConnectionError` (with the
+	* original error as `cause`) when the request could not complete or timed out.
 	*/
 	async _request(method, path, params = null, json = null) {
-		if (!this.server) throw new Error("Server was not set at init. Call findServer() first.");
-		if (method === "GET" && json !== null) throw new Error("GET requests cannot have a body.");
-		this.debug && console.debug(`Sending request to ${path}`);
-		if (params) {
-			params = Object.fromEntries(Object.entries(params).filter(([_, v]) => v != null));
-			this.debug && console.debug(`Parameters: ${JSON.stringify(params)}`);
-		}
-		if (json) {
-			json = Object.fromEntries(Object.entries(json).filter(([_, v]) => v != null));
-			this.debug && console.debug(`Body: ${JSON.stringify(json)}`);
-		}
-		const headers = {
-			Authorization: `Bearer ${this.accessToken}`,
-			"Content-Type": "application/json",
-			"X-Library": `node tesla_fleet_api`
-		};
-		const query = params ? "?" + new URLSearchParams(params).toString() : "";
+		const command = path.slice(path.lastIndexOf("/") + 1);
+		let data;
 		try {
-			const resp = await fetch(`${this.server}/${path}${query}`, {
-				method,
-				headers,
-				body: json ? JSON.stringify(json) : null,
-				signal: this.timeout != null ? AbortSignal.timeout(this.timeout) : null
-			});
-			return await this._response(resp);
+			if (!this.server) throw new Error("Server was not set at init. Call find_server() first.");
+			if (method === "GET") json = null;
+			const headers = {
+				Authorization: `Bearer ${await this.access_token()}`,
+				"X-Library": `node tesla_fleet_api 0.6.0`
+			};
+			const query = new URLSearchParams();
+			if (params) {
+				for (const [key, value] of Object.entries(params)) if (value != null) query.append(key, typeof value === "boolean" ? value ? "true" : "false" : String(value));
+				this._log(`Parameters: ${redactedQuery(query)}`);
+			}
+			let body = null;
+			if (json) {
+				json = Object.fromEntries(Object.entries(json).filter(([_, v]) => v != null));
+				body = JSON.stringify(json);
+				this._log(`Body: ${redactedJson(json)}`);
+				headers["Content-Type"] = "application/json";
+			}
+			const search = query.size ? `?${query.toString()}` : "";
+			const url = `${this.server}/${path}${search}`;
+			try {
+				const resp = await this._fetch(url, {
+					method,
+					headers,
+					body,
+					signal: this.timeout != null ? AbortSignal.timeout(this.timeout) : null
+				});
+				this._log(`Status ${resp.status} from ${this.server}/${path}`);
+				for (const [header, label] of [
+					["x-txid", "Response TXID"],
+					["RateLimit-Reset", "Rate limit reset"],
+					["Retry-After", "Retry after"]
+				]) if (resp.headers.has(header)) this._log(`${label}: ${resp.headers.get(header)}`);
+				data = await this._response(resp);
+			} catch (error) {
+				if (error instanceof TeslaFleetError) throw error;
+				throw new TeslaFleetConnectionError(null, null, { cause: error });
+			}
+			this._log(`Response JSON: ${redactedJson(data)}`);
 		} catch (error) {
-			if (error instanceof TeslaFleetError) throw error;
-			throw new TeslaFleetConnectionError(null, null, { cause: error });
+			logRequestError((m) => this._log(m), command, this._transport_name, error);
+			throw error;
 		}
+		logRequestResult((m) => this._log(m), command, this._transport_name, data);
+		return data;
+	}
+	/**
+	* Returns `"ok"` if the API is operating normally. Sends no headers.
+	*/
+	async status() {
+		if (!this.server) throw new Error("Server was not set at init. Call find_server() first.");
+		return (await this._fetch(`${this.server}/status`)).text();
+	}
+	/**
+	* Generate a partner token using client credentials authentication, and use
+	* it as the access token for later requests.
+	* @param client_id Partner application client ID.
+	* @param client_secret Partner application client secret.
+	* @param scopes Scopes to request.
+	* @returns The token response, including `access_token`.
+	*/
+	async partner_login(client_id, client_secret, scopes = [Scope.OPENID]) {
+		if (!this.server) throw new Error("Server was not set at init. Call find_server() first.");
+		const resp = await this._fetch(TOKEN_URLS[this.region ?? "na"], {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "client_credentials",
+				client_id,
+				client_secret,
+				audience: this.server,
+				scope: scopes.join(" ")
+			})
+		});
+		await raise_for_status(resp);
+		const tokenData = await resp.json();
+		this.accessToken = tokenData.access_token;
+		return tokenData;
 	}
 	/**
 	* Returns products mapped to user.
 	* @returns An array of products including both vehicles and energy sites.
 	*/
 	async products() {
-		return this._request("GET", "api/1/products").then(({ response }) => response);
+		return this._request("GET", "api/1/products");
 	}
 	/**
 	* Return Tesla products separated into vehicles and energy_sites
 	* @returns A dictionary of vehicles and energy sites, each with an array of those products
 	*/
 	async products_by_type() {
-		return this.products().then((products) => ({
+		return this.products().then(({ response: products }) => ({
 			vehicles: products.filter((product) => "vin" in product),
 			energy_sites: products.filter((product) => "energy_site_id" in product)
 		}));
 	}
-	async loadPrivateKey(path) {
-		return (await import("fs")).promises.readFile(path, "utf8").then((key) => {
-			this.accessToken = key;
-		}).catch(async () => {
-			const { privateKey: _privateKey } = (await import("crypto")).generateKeyPairSync("ec", {
-				namedCurve: "secp256r1",
-				publicKeyEncoding: {
-					type: "spki",
-					format: "pem"
-				},
-				privateKeyEncoding: {
-					type: "pkcs8",
-					format: "pem"
-				}
-			});
+	/**
+	* Get or create the P-256 key that signs vehicle commands, and keep it as
+	* `private_key`. The file is an unencrypted PEM that Python's
+	* `get_private_key` shares, created at mode 0600. If another process wins the
+	* create race, its file is read instead.
+	* @param path Key file.
+	* @returns The raw 32-byte key `Commands` takes.
+	* @throws PrivateKeyError for an existing file that cannot be used.
+	*/
+	async get_private_key(path = "private_key.pem") {
+		const key = await ecPrivateKeyFile(path);
+		this.private_key = key;
+		return key;
+	}
+	/** The raw 32-byte P-256 key, which `createSigned` falls back to. */
+	get private_key() {
+		return this.#privateKey;
+	}
+	set private_key(key) {
+		this.#privateKey = key;
+	}
+	/** Whether the private key has been set. */
+	get has_private_key() {
+		return this.#privateKey != null;
+	}
+	/** The public key in PEM format. */
+	get public_pem() {
+		return this.#ecPublicKey("Private key is not set").export({
+			type: "spki",
+			format: "pem"
+		});
+	}
+	/** The public key's uncompressed point, in hex. */
+	get public_uncompressed_point() {
+		if (this.#privateKey == null) throw new LibraryError("Private key is not set");
+		return publicKeyFor(this.#privateKey).toString("hex");
+	}
+	/**
+	* The EC public key in DER SubjectPublicKeyInfo form, as an energy gateway
+	* expects when registering an ECC authorized client. It rejects the raw point
+	* that vehicles use.
+	*/
+	get ec_public_der_spki() {
+		return this.#ecPublicKey("EC private key is not set").export({
+			type: "spki",
+			format: "der"
 		});
 	}
+	/** `ec_public_der_spki`, base64-encoded. */
+	get ec_public_der_spki_b64() {
+		return this.ec_public_der_spki.toString("base64");
+	}
+	#ecPublicKey(unsetMessage) {
+		if (this.#privateKey == null) throw new LibraryError(unsetMessage);
+		return ecPublicKey(this.#privateKey);
+	}
+	/**
+	* Get or create the RSA key for energy gateway client registration, and keep
+	* it as `rsa_private_key`. The file is an unencrypted PEM that Python's
+	* `get_rsa_private_key` shares, created at mode 0600. If another process wins
+	* the create race, its file is read instead. Generation runs off the event loop.
+	* @param path Key file.
+	* @param key_size Modulus length in bits for a new key; 4096 is what Powerwall v1r expects.
+	* @throws PrivateKeyError for an existing file that cannot be used.
+	*/
+	async get_rsa_private_key(path = "tedapi_rsa_private.pem", key_size = 4096) {
+		const key = await rsaPrivateKeyFile(path, key_size);
+		this.rsa_private_key = key;
+		return key;
+	}
+	/** The RSA key for energy gateway client registration. */
+	get rsa_private_key() {
+		return this.#rsaPrivateKey;
+	}
+	set rsa_private_key(key) {
+		this.#rsaPrivateKey = key;
+	}
+	/** Whether the RSA private key has been set. */
+	get has_rsa_private_key() {
+		return this.#rsaPrivateKey != null;
+	}
+	/**
+	* The RSA public key in DER PKCS#1 form, as an energy gateway expects when
+	* registering an authorized client.
+	*/
+	get rsa_public_der_pkcs1() {
+		return rsaPublicDerPkcs1(this.#rsaKey());
+	}
+	/** `rsa_public_der_pkcs1`, base64-encoded. */
+	get rsa_public_der_pkcs1_b64() {
+		return this.rsa_public_der_pkcs1.toString("base64");
+	}
+	/** The RSA public key in PEM (SubjectPublicKeyInfo) format. */
+	get rsa_public_pem() {
+		return createPublicKey(this.#rsaKey()).export({
+			type: "spki",
+			format: "pem"
+		});
+	}
+	#rsaKey() {
+		if (this.#rsaPrivateKey == null) throw new LibraryError("RSA private key is not set");
+		return this.#rsaPrivateKey;
+	}
 };
 export { TeslaFleetApi as default };