@teslemetry/api 0.0.1 → 0.1.0

package/README.md

@@ -1,18 +1,13 @@
-# Teslemetry TypeScript API
+# Teslemetry TypeScript SDK
 
 The official TypeScript/JavaScript client for the [Teslemetry](https://teslemetry.com) API.
 
-This library provides a convenient wrapper for interacting with Tesla vehicles and energy sites via the Teslemetry service, including support for standard API commands and real-time streaming data (Server-Sent Events).
+This library provides a strictly typed, easy-to-use wrapper for interacting with Tesla vehicles and energy sites. It supports standard API commands, state retrieval, and real-time streaming data via Server-Sent Events (SSE).
 
-Further information about each API method can be found in the [Teslemetry API Documentation](https://teslemetry.com/docs/api), and [Tesla Fleet API Documentation](https://developer.tesla.com/docs/fleet-api/endpoints/vehicle-commands).
+## 📚 Documentation
 
-## Features
-
-- 🚗 **Vehicle API**: Full control and state retrieval (lock/unlock, climate, charging, etc.).
-- ⚡ **Energy API**: Monitor and control Tesla Energy sites (Solar, Powerwall).
-- 📡 **Streaming (SSE)**: Real-time vehicle data streaming with `TeslemetryStream`.
-- 🌍 **Region Aware**: Automatic region detection and handling (NA/EU).
-- 🔒 **Type-Safe**: Built with TypeScript for full type inference and safety.
+- **[Teslemetry API Reference](https://api.teslemetry.com/docs)**: Detailed documentation for all API endpoints, parameters, and response values.
+- **[Tesla Fleet API](https://developer.tesla.com/docs/fleet-api)**: Official Tesla documentation for underlying vehicle commands and data.
 
 ## Installation
 
@@ -29,26 +24,26 @@ yarn add @teslemetry/api
 ```typescript
 import { Teslemetry } from "@teslemetry/api";
 
-const token = process.env.TESLEMETRY_ACCESS_TOKEN;
-const vin = process.env.TESLEMETRY_VIN;
-
-const teslemetry = new Teslemetry(token);
+// Initialize with your access token
+const teslemetry = new Teslemetry(process.env.TESLEMETRY_ACCESS_TOKEN);
 
-// Get a vehicle instance
+// Get a specific vehicle
+const vin = "5YJ...";
 const vehicle = teslemetry.getVehicle(vin);
 
-// API: Get vehicle state
+// 1. Get Vehicle State
 const state = await vehicle.api.state();
-console.log("Battery Level:", state.charge_state.battery_level);
+console.log("Vehicle State:", state);
 
-// API: Send a command
+// 2. Send a Command (e.g., Flash Lights)
 await vehicle.api.flashLights();
 
-// Stream: Listen for real-time data
+// 3. Stream Real-time Data
 vehicle.sse.onSignal("Speed", (speed) => {
-  console.log(`Current Speed: ${speed}`);
+  console.log(`Current Speed: ${speed} mph`);
 });
 
+// Connect to the stream
 await teslemetry.sse.connect();
 ```
 
@@ -56,71 +51,120 @@ await teslemetry.sse.connect();
 
 ### Initialization
 
-Initialize the `Teslemetry` client with your access token. You can optionally specify a region ("na" or "eu"), otherwise it will be automatically detected.
+The `Teslemetry` class is the main entry point. It automatically handles region detection (NA/EU) upon the first request, or you can specify it manually.
 
 ```typescript
 import { Teslemetry } from "@teslemetry/api";
 
+// Automatic region detection (recommended)
 const teslemetry = new Teslemetry("YOUR_ACCESS_TOKEN");
-// or with specific region
-const teslemetryEu = new Teslemetry("YOUR_ACCESS_TOKEN", "eu");
+
+// Manual region specification
+const teslemetryEu = new Teslemetry("YOUR_ACCESS_TOKEN", { region: "eu" });
 ```
 
-### Vehicle Control
+### Vehicle API
 
-The `getVehicle(vin)` method returns an object containing both `api` and `sse` handlers for a specific vehicle.
+Use `getVehicle(vin)` to interact with a vehicle. This returns an object containing two specialized handlers:
+- `api`: for standard REST API calls (commands, state).
+- `sse`: for real-time streaming.
+
+#### Commands & State
+The `.api` property contains methods for all supported Tesla commands.
 
 ```typescript
-const myCar = teslemetry.getVehicle("VIN123456789");
+const vehicle = teslemetry.getVehicle("VIN...");
+
+// Get full vehicle data
+const data = await vehicle.api.vehicleData();
 
-// Get detailed vehicle data
-const vehicleData = await myCar.api.vehicleData();
+// Climate Control
+await vehicle.api.autoConditioningStart();
+await vehicle.api.setTemps(20, 20); // Driver, Passenger (Celsius)
 
-// Commands
-await myCar.api.doorLock();
-await myCar.api.autoConditioningStart();
-await myCar.api.chargeStart();
+// Charging
+await vehicle.api.chargeStart();
+await vehicle.api.setChargeLimit(80);
+
+// Locking
+await vehicle.api.lockDoors();
 ```
 
-### Real-time Streaming (SSE)
+> **Note:** For a comprehensive list of all available methods and their parameters, please refer to the [Teslemetry API Docs](https://teslemetry.com/docs/api). The SDK methods map 1:1 with these endpoints.
 
-Teslemetry supports streaming vehicle data updates via Server-Sent Events.
+#### Real-time Streaming (SSE)
+The `.sse` property allows you to subscribe to specific vehicle signals.
 
 ```typescript
-const myCar = teslemetry.getVehicle("VIN123456789");
-
-// Subscribe to specific signals
-myCar.sse.onSignal("PackCurrent", (val) => console.log("Current:", val));
-myCar.sse.onSignal("ChargerVoltage", (val) => console.log("Voltage:", val));
+// Subscribe to signals
+vehicle.sse.onSignal("PackCurrent", (val) => console.log("Current:", val));
+vehicle.sse.onSignal("ChargerVoltage", (val) => console.log("Voltage:", val));
 
-// Handle connection status
+// Monitor connection status
 teslemetry.sse.onConnection((isConnected) => {
-  console.log(isConnected ? "Connected!" : "Disconnected");
+  console.log(isConnected ? "Stream Connected" : "Stream Disconnected");
 });
 
-// Start the stream
+// Start streaming (connects to the shared Teslemetry stream)
 await teslemetry.sse.connect();
 
 // Stop streaming
 teslemetry.sse.disconnect();
 ```
 
-### Energy Sites
+### Energy API
 
-Interact with Tesla Energy products.
+Interact with Tesla Energy sites (Solar, Powerwall, Wall Connector).
 
 ```typescript
+// Get an energy site instance by Site ID
 const site = teslemetry.energySite(12345);
-const data = await site.getSiteInfo();
+
+// Get site status and info
+const status = await site.getLiveStatus();
+const info = await site.getSiteInfo();
+
+// Control operations
+await site.setBackupReserve(20); // Set backup reserve to 20%
+await site.setOperationMode("autonomous");
 ```
 
-## Development
+### Account & Discovery
 
-To build the package locally:
+If you don't know your VINs or Site IDs, you can discover all products on your account.
 
-```bash
-pnpm install
-pnpm build
+```typescript
+// Fetch all vehicles and energy sites
+const products = await teslemetry.createProducts();
+
+// Access discovered vehicles
+for (const vin in products.vehicles) {
+  const vehicle = products.vehicles[vin];
+  console.log(`Found ${vehicle.name} (${vehicle.vin})`);
+  
+  // Use the API immediately
+  await vehicle.api.honkHorn();
+}
+
+// Access discovered energy sites
+for (const siteId in products.energySites) {
+  const site = products.energySites[siteId];
+  console.log(`Found Site: ${site.name} (${site.site})`);
+}
+```
+
+### Error Handling
+
+The SDK throws standard Javascript `Error` objects for configuration issues and specific errors for API failures. Streaming errors (like connection drops) are emitted via the stream error handler or specific exception classes.
+
+```typescript
+import { TeslemetryStreamConnectionError } from "@teslemetry/api";
+
+try {
+  await vehicle.api.wakeUp();
+} catch (error) {
+  console.error("Failed to wake up vehicle:", error);
+}
 ```
 
 ## License

package/dist/index.cjs

@@ -623,6 +623,13 @@ const client = createClient(createConfig({
 //#endregion
 //#region src/client/sdk.gen.ts
 /**
+* Streaming field parameters
+*/
+const getFieldsJson = (options) => (options?.client ?? client).get({
+	url: "/fields.json",
+	...options
+});
+/**
 * Products
 *
 * Returns products mapped to user.
@@ -3081,9 +3088,6 @@ var TeslemetryVehicleStream = class {
 	onConnectivity(callback) {
 		return this.stream.onConnectivity(callback, { vin: this.vin });
 	}
-	onCredits(callback) {
-		return this.stream.onCredits(callback, { vin: this.vin });
-	}
 	onVehicleData(callback) {
 		return this.stream.onVehicleData(callback, { vin: this.vin });
 	}
@@ -3114,15 +3118,17 @@ var TeslemetryVehicleStream = class {
 var TeslemetryStream = class {
 	root;
 	active = false;
+	connected = false;
 	vin;
+	cache;
 	logger;
 	listeners = /* @__PURE__ */ new Map();
 	_connectionListeners = /* @__PURE__ */ new Map();
 	vehicles = /* @__PURE__ */ new Map();
-	controller = null;
-	constructor(root, vin) {
+	constructor(root, options) {
 		this.root = root;
-		this.vin = vin;
+		this.vin = options?.vin;
+		this.cache = options?.cache;
 		this.logger = root.logger;
 		if (this.vin) this.getVehicle(this.vin);
 	}
@@ -3130,9 +3136,6 @@ var TeslemetryStream = class {
 		if (!this.vehicles.has(vin)) this.vehicles.set(vin, new TeslemetryVehicleStream(this.root, this, vin));
 		return this.vehicles.get(vin);
 	}
-	get connected() {
-		return this.active;
-	}
 	async connect() {
 		if (this.active) return;
 		this.active = true;
@@ -3143,11 +3146,12 @@ var TeslemetryStream = class {
 		while (this.active) try {
 			const sse = await getSseByVin_({
 				client: this.root.client,
-				path: { vin: this.vin || "" }
+				path: { vin: this.vin || "" },
+				query: { cache: this.cache }
 			});
-			if (sse.controller) this.controller = sse.controller;
 			this.logger.info(`Connected to stream`);
 			retries = 0;
+			this.connected = true;
 			this._updateConnectionListeners(true);
 			if (sse.stream) for await (const event of sse.stream) {
 				if (!this.active) break;
@@ -3156,6 +3160,7 @@ var TeslemetryStream = class {
 		} catch (error) {
 			if (!this.active) break;
 			this.logger.error("SSE error:", error);
+			this.connected = false;
 			this._updateConnectionListeners(false);
 			retries++;
 			const delay = Math.min(2 ** retries, 600) * 1e3;
@@ -3170,10 +3175,6 @@ var TeslemetryStream = class {
 	}
 	close() {
 		this.active = false;
-		if (this.controller) {
-			this.controller.abort();
-			this.controller = null;
-		}
 		this.logger.info(`Disconnecting from stream`);
 		this._updateConnectionListeners(false);
 	}
@@ -4906,6 +4907,10 @@ var TeslemetryApi = class {
 			energySites: this._energySites
 		};
 	}
+	async fields() {
+		const { data } = await getFieldsJson({ client: this.root.client });
+		return data;
+	}
 	/**
 	* Returns a list of products (vehicles and energy sites) associated with the user account.
 	* @returns A promise that resolves to an object containing a `response` array and count.
@@ -4939,10 +4944,11 @@ var TeslemetryApi = class {
 	* and detailed info for each vehicle.
 	*/
 	async fleetStatus(vins) {
-		return postApi1VehiclesFleetStatus({
+		const { data } = await postApi1VehiclesFleetStatus({
 			body: { vins },
 			client: this.root.client
 		});
+		return data;
 	}
 	/**
 	* Returns vehicles belonging to the account. This endpoint is paginated.
@@ -4950,7 +4956,8 @@ var TeslemetryApi = class {
 	* pagination details, and a total count.
 	*/
 	async vehicles() {
-		return getApi1Vehicles({ client: this.root.client });
+		const { data } = await getApi1Vehicles({ client: this.root.client });
+		return data;
 	}
 	/**
 	* Redeems a share invite. Once redeemed, the account will gain access to the vehicle within the Tesla app.
@@ -4958,10 +4965,11 @@ var TeslemetryApi = class {
 	* @returns Promise to an object containing the `vehicle_id_s` and `vin` of the shared vehicle.
 	*/
 	async redeemInvitation(code) {
-		return postApi1VehiclesInvitationsRedeem({
+		const { data } = await postApi1VehiclesInvitationsRedeem({
 			body: { code },
 			client: this.root.client
 		});
+		return data;
 	}
 };
 
@@ -4989,9 +4997,9 @@ var Teslemetry = class {
 	logger;
 	_user = null;
 	_charging = null;
-	constructor(access_token, region, logger = consoleLogger) {
-		this.logger = logger;
-		if (region) this.region = region;
+	constructor(access_token, options) {
+		this.logger = options?.logger || consoleLogger;
+		if (options?.region) this.region = options.region;
 		this.client = createClient({
 			auth: access_token,
 			baseUrl: `https://${this.region || "api"}.teslemetry.com`,
@@ -5009,7 +5017,7 @@ var Teslemetry = class {
 			}
 			return response;
 		});
-		this.sse = new TeslemetryStream(this);
+		this.sse = new TeslemetryStream(this, options?.stream);
 		this.api = new TeslemetryApi(this);
 	}
 	/**
@@ -5033,6 +5041,31 @@ var Teslemetry = class {
 		return response.headers.get("x-region");
 	}
 	/**
+	* Creates API instances for all products (vehicles and energy sites) associated with the account.
+	* @returns A promise that resolves to an object containing vehicle and energy site names, API, and SSE instances.
+	*/
+	async createProducts() {
+		const { data } = await getApi1Products({ client: this.client });
+		const result = {
+			vehicles: {},
+			energySites: {}
+		};
+		data.response?.forEach((product) => {
+			if (product.device_type === "vehicle") result.vehicles[product.vin] = {
+				name: product.display_name ?? useTeslaModel(product.vin),
+				vin: product.vin,
+				api: this.api.getVehicle(product.vin),
+				sse: this.sse.getVehicle(product.vin)
+			};
+			if (product.device_type === "energy") result.energySites[product.energy_site_id] = {
+				name: product.site_name ?? "Unnamed",
+				site: product.energy_site_id,
+				api: this.api.getEnergySite(product.energy_site_id)
+			};
+		});
+		return result;
+	}
+	/**
 	* Get a vehicle API instance for the specified VIN.
 	* @param vin Vehicle Identification Number
 	* @returns TeslemetryVehicleApi instance
@@ -5065,6 +5098,15 @@ var Teslemetry = class {
 		return this._charging;
 	}
 };
+const model_names = {
+	"3": "Model 3",
+	S: "Model S",
+	X: "Model X",
+	Y: "Model Y",
+	C: "Cybertruck",
+	T: "Semi"
+};
+const useTeslaModel = (vin) => model_names?.[vin[3]] ?? "Unknown";
 
 //#endregion
 //#region src/exceptions.ts
@@ -5102,6 +5144,7 @@ var ValueError = class extends Error {
 //#endregion
 exports.Teslemetry = Teslemetry;
 exports.TeslemetryApi = TeslemetryApi;
+exports.TeslemetryEnergyApi = TeslemetryEnergyApi;
 exports.TeslemetryStream = TeslemetryStream;
 exports.TeslemetryStreamConnectionError = TeslemetryStreamConnectionError;
 exports.TeslemetryStreamEnded = TeslemetryStreamEnded;