tesla-fleet-api 0.3.0 → 0.5.0

package/dist/oauth.mjs

@@ -0,0 +1,143 @@
+import { SERVERS, TOKEN_URLS, is_valid_region } from "./const.mjs";
+import { InvalidResponse, MissingToken, TeslaFleetConnectionError, TeslaFleetError } from "./exceptions.mjs";
+import TeslaFleetApi from "./teslafleetapi.mjs";
+// src/oauth.ts
+function nowSeconds() {
+	return Date.now() / 1e3;
+}
+/** The fields every token reply needs; a reply without them must not replace a working token. */
+function tokenFrom(data) {
+	if (typeof data?.access_token !== "string" || typeof data.expires_in !== "number") throw new InvalidResponse();
+	return {
+		access_token: data.access_token,
+		expires: Math.floor(nowSeconds()) + data.expires_in
+	};
+}
+/**
+* Tesla Fleet API client that signs a user in with OAuth and keeps its access
+* token fresh. `expires` is in epoch seconds, as in Python, so a stored
+* token works with either library.
+*/
+var TeslaFleetOAuth = class extends TeslaFleetApi {
+	client_id;
+	redirect_uri;
+	refresh_token;
+	/** Expiry of the access token, in epoch seconds. */
+	expires;
+	#client_secret;
+	#refreshing = null;
+	constructor(options) {
+		if (!is_valid_region(options.region)) throw new Error("Invalid region");
+		const { region, client_id, client_secret, redirect_uri, access_token, refresh_token, expires, ...rest } = options;
+		super({
+			...rest,
+			region,
+			accessToken: access_token
+		});
+		this.client_id = client_id;
+		this.#client_secret = client_secret ?? null;
+		this.redirect_uri = redirect_uri ?? null;
+		this.refresh_token = refresh_token ?? null;
+		this.expires = expires ?? 0;
+	}
+	/**
+	* The URL to send the user to, built exactly as Python builds it: values are
+	* not URL-encoded.
+	* @param scopes Scopes to request.
+	* @param state Value Tesla echoes back on the redirect.
+	*/
+	get_login_url(scopes, state = "login") {
+		if (this.redirect_uri == null) throw new Error("Redirect URI is missing");
+		return `https://${this.region === "cn" ? "auth.tesla.cn" : "auth.tesla.com"}/oauth2/v3/authorize?response_type=code&client_id=${this.client_id}&redirect_uri=${this.redirect_uri}&scope=${scopes.join("+")}&state=${state}`;
+	}
+	/**
+	* Exchange an authorization code for tokens. A code prefixed with a region
+	* (e.g. `NA_...`) also selects that region's server.
+	* @param code The code from the login redirect.
+	*/
+	async get_refresh_token(code) {
+		if (this.#client_secret == null) throw new Error("Client secret is missing");
+		if (this.redirect_uri == null) throw new Error("Redirect URI is missing");
+		this.server ??= SERVERS[this.region ?? "na"];
+		const data = await this.#token({
+			grant_type: "authorization_code",
+			client_id: this.client_id,
+			client_secret: this.#client_secret,
+			code,
+			audience: this.server,
+			redirect_uri: this.redirect_uri
+		});
+		const { access_token, expires } = tokenFrom(data);
+		this.refresh_token = data.refresh_token ?? null;
+		this.accessToken = access_token;
+		this.expires = expires;
+		const region = code.split("_")[0].toLowerCase();
+		if (is_valid_region(region)) this.server = SERVERS[region];
+	}
+	/**
+	* The current access token, refreshed first when `expires` has passed.
+	* @throws MissingToken when there is no token and none can be refreshed.
+	*/
+	async access_token() {
+		if (this.expires < nowSeconds()) await this.refresh_access_token();
+		if (this.accessToken && typeof this.accessToken === "string") return this.accessToken;
+		throw new MissingToken("Access token is missing");
+	}
+	/**
+	* Refresh the access token if it is missing or expired.
+	* @returns The refreshed token to persist, or `null` when none was needed.
+	*/
+	async check_access_token() {
+		if (this.accessToken && this.expires > nowSeconds()) return null;
+		return this.refresh_access_token();
+	}
+	/**
+	* Refresh the access token. Tesla rotates the refresh token, so persist what
+	* this returns.
+	* @throws MissingToken without a refresh token, or the `TeslaFleetError`
+	* matching the failure, e.g. `LoginRequired`.
+	*/
+	refresh_access_token() {
+		this.#refreshing ??= this.#refresh().finally(() => {
+			this.#refreshing = null;
+		});
+		return this.#refreshing;
+	}
+	async #refresh() {
+		if (!this.refresh_token) throw new MissingToken("Refresh token is missing");
+		const data = await this.#token({
+			grant_type: "refresh_token",
+			client_id: this.client_id,
+			refresh_token: this.refresh_token
+		});
+		const { access_token, expires } = tokenFrom(data);
+		if (typeof data.refresh_token !== "string") throw new InvalidResponse();
+		this.accessToken = access_token;
+		this.refresh_token = data.refresh_token;
+		this.expires = expires;
+		return {
+			refresh_token: data.refresh_token,
+			expires
+		};
+	}
+	/** POST a form to the region's token endpoint. Bypasses `_request`, which would log the reply. */
+	async #token(form) {
+		try {
+			const resp = await this._fetch(TOKEN_URLS[this.region ?? "na"], {
+				method: "POST",
+				headers: { "Content-Type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams(form),
+				signal: this.timeout != null ? AbortSignal.timeout(this.timeout) : null
+			});
+			return await this._response(resp);
+		} catch (error) {
+			if (error instanceof TeslaFleetError) throw error;
+			throw new TeslaFleetConnectionError(null, null, { cause: error });
+		}
+	}
+	async _request(method, path, params = null, json = null) {
+		await this.check_access_token();
+		return super._request(method, path, params, json);
+	}
+};
+export { TeslaFleetOAuth as default };

package/dist/partner.cjs

@@ -0,0 +1,32 @@
+// src/partner.ts
+var Partner = class {
+	parent;
+	constructor(parent) {
+		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 = null) {
+		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) {
+		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) {
+		return this.parent._request("GET", "api/1/partner_accounts/fleet_telemetry_errors", { domain });
+	}
+};
+exports.default = Partner;

package/dist/partner.d.cts

@@ -0,0 +1,24 @@
+import TeslaFleetApi from "./teslafleetapi.cjs";
+declare class Partner {
+  parent: TeslaFleetApi;
+  constructor(parent: TeslaFleetApi);
+  /**
+   * 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
+   */
+  public_key(domain?: string | null): Promise<Record<string, any>>;
+  /**
+   * 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
+   */
+  register(domain: string): Promise<Record<string, any>>;
+  /**
+   * Returns recent fleet telemetry errors reported by vehicles after receiving the config.
+   * @param domain Domain of the partner account.
+   * @returns
+   */
+  fleet_telemetry_errors(domain: string): Promise<Record<string, any>>;
+}
+export = Partner;

package/dist/partner.d.mts

@@ -0,0 +1,23 @@
+import TeslaFleetApi from "./teslafleetapi.mjs";
+export default class Partner {
+  parent: TeslaFleetApi;
+  constructor(parent: TeslaFleetApi);
+  /**
+   * 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
+   */
+  public_key(domain?: string | null): Promise<Record<string, any>>;
+  /**
+   * 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
+   */
+  register(domain: string): Promise<Record<string, any>>;
+  /**
+   * Returns recent fleet telemetry errors reported by vehicles after receiving the config.
+   * @param domain Domain of the partner account.
+   * @returns
+   */
+  fleet_telemetry_errors(domain: string): Promise<Record<string, any>>;
+}

package/dist/partner.mjs

@@ -0,0 +1,32 @@
+// src/partner.ts
+var Partner = class {
+	parent;
+	constructor(parent) {
+		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 = null) {
+		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) {
+		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) {
+		return this.parent._request("GET", "api/1/partner_accounts/fleet_telemetry_errors", { domain });
+	}
+};
+export { Partner as default };