@teslemetry/pro 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+# Teslemetry for Business TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript/JavaScript client for the [Teslemetry for Business](https://teslemetry.pro) API.
+
+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).
+
+## 📚 Documentation
+
+- **[Teslemetry API Reference](https://api.teslemetry.pro/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
+
+```bash
+npm install @teslemetry/pro
+```
+
+## Quick Start
+
+```typescript
+import { Teslemetry } from "@teslemetry/pro";
+
+// Initialize with your access token
+const teslemetry = new Teslemetry(process.env.TESLEMETRY_ACCESS_TOKEN!);
+
+// Get a specific vehicle
+const vin = "5YJ...";
+const vehicle = teslemetry.getVehicle(vin);
+
+// 1. Get Vehicle State
+const state = await vehicle.api.state();
+console.log("Vehicle State:", state);
+
+// 2. Send a Command (e.g., Flash Lights)
+await vehicle.api.flashLights();
+
+// 3. Stream Real-time Data
+vehicle.sse.onSignal("VehicleSpeed", (speed) => {
+  console.log(`Current Speed: ${speed} mph`);
+});
+
+// Connect to the stream
+await teslemetry.sse.connect();
+```
+
+## Usage
+
+### Initialization
+
+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/pro";
+
+// Automatic region detection (recommended)
+const teslemetry = new Teslemetry("YOUR_ACCESS_TOKEN");
+
+// Manual region specification
+const teslemetryEu = new Teslemetry("YOUR_ACCESS_TOKEN", { region: "eu" });
+```
+
+### Vehicle API
+
+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 vehicle = teslemetry.getVehicle("VIN...");
+
+// Get full vehicle data
+const data = await vehicle.api.vehicleData();
+
+// Climate Control
+await vehicle.api.startAutoConditioning();
+await vehicle.api.setTemps(20, 20); // Driver, Passenger (Celsius)
+
+// Charging
+await vehicle.api.startCharging();
+await vehicle.api.setChargeLimit(80);
+
+// Locking
+await vehicle.api.lockDoors();
+```
+
+> **Note:** For a comprehensive list of all available methods and their parameters, please refer to the [Teslemetry for Business API Docs](https://api.teslemetry.pro/docs). The SDK methods map 1:1 with these endpoints.
+
+#### Real-time Streaming (SSE)
+The `.sse` property allows you to subscribe to specific vehicle signals.
+
+```typescript
+// Subscribe to signals
+vehicle.sse.onSignal("PackCurrent", (val) => console.log("Current:", val));
+vehicle.sse.onSignal("ChargerVoltage", (val) => console.log("Voltage:", val));
+
+// Monitor connection status
+teslemetry.sse.on("connect", () => console.log("Stream Connected"));
+teslemetry.sse.on("disconnect", () => console.log("Stream Disconnected"));
+
+// Start streaming (connects to the shared Teslemetry stream)
+await teslemetry.sse.connect();
+
+// Stop streaming
+teslemetry.sse.disconnect();
+```
+
+##### Stream errors and reconnecting
+
+The stream reconnects automatically with exponential backoff (2 seconds,
+doubling up to 60), re-resolving your access token callback on every attempt.
+`connect` is emitted once the server has started answering, not when the
+request is sent. Each failed attempt, and each connection the server ends,
+emits a `stream_error` event with the error, the HTTP status (when one was
+received), and the number of consecutive failures.
+
+Authentication failures are handled differently: after a `401`/`403` the
+stream reconnects once immediately (so a refreshed token can take over), and
+if that attempt is also rejected it **stops reconnecting** and emits a
+terminal `auth_failure` event instead of looping forever. Listen for it to
+prompt the user to re-authenticate, then call `connect()` again to resume.
+
+```typescript
+teslemetry.sse.on("stream_error", ({ error, status, retries }) => {
+  console.warn(`Stream attempt ${retries} failed`, status, error);
+});
+
+teslemetry.sse.on("auth_failure", (error) => {
+  // error is a TeslemetryStreamAuthError with a .status of 401 or 403
+  console.error("Streaming credentials rejected, reauthorize:", error.status);
+  // ...surface reauth to the user, then: await teslemetry.sse.connect();
+});
+```
+
+##### Selecting topics
+
+By default the stream sends every event applicable to every product you can
+access (legacy-all mode). Pass `stream.topics` to receive only the events you
+need - either exact wire topic names or the bundled presets from
+`SSE_TOPIC_PRESETS` (`vehicleFull`, `vehicleCore`, `energyLive`,
+`energyFullState`, `account`, `products`), which are expanded client-side to exact names
+before the connection opens:
+
+```typescript
+// getToken is any () => Promise<string> that returns a current access token
+const getToken = async () => process.env.TESLEMETRY_ACCESS_TOKEN!;
+
+const teslemetry = new Teslemetry(getToken, {
+  stream: { topics: ["energyLive", "credits"] },
+});
+```
+
+Omitting `topics` entirely preserves legacy-all behavior forever - it is
+never reinterpreted as a narrower default.
+
+##### Energy tariffs and the composed site-info view
+
+`site_info` events no longer carry `tariff_content`/`tariff_content_v2` -
+subscribe separately to `tariff_content_v2`, whose body is `null` when Tesla
+explicitly removes the tariff (not merely "no update yet"):
+
+```typescript
+site.sse.on("tariff_content_v2", (event) => {
+  if (event.tariff_content_v2 === null) {
+    console.log("Tariff was removed");
+  } else {
+    console.log("Tariff updated:", event.tariff_content_v2);
+  }
+});
+```
+
+`site.sse.siteInfoDocument` merges the cached slim `site_info` with the last
+received tariff piece into a single whole-document view, resembling the full
+REST `site_info` response:
+
+```typescript
+const document = site.sse.siteInfoDocument; // undefined until site_info is cached
+```
+
+`getTariffPeriods` resolves the current buy/sell rate (and, optionally, the
+upcoming schedule) from a `tariff_content_v2` body - pass the site's IANA
+`installation_time_zone`, since the tariff itself carries no timezone:
+
+```typescript
+import { getTariffPeriods, type TariffContentV2 } from "@teslemetry/pro";
+
+const tariff = document?.tariff_content_v2 as TariffContentV2 | null;
+if (tariff) {
+  const resolution = getTariffPeriods(tariff, new Date(), {
+    timeZone: document.installation_time_zone,
+  });
+  console.log(resolution?.buy.price);
+}
+```
+
+### Energy API
+
+Interact with Tesla Energy sites (Solar, Powerwall, Wall Connector).
+
+```typescript
+// Get an energy site instance by Site ID
+const site = teslemetry.energySite(12345);
+
+// 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");
+```
+
+### Account & Discovery
+
+If you don't know your VINs or Site IDs, you can discover every product that customers have consented to share with your business.
+
+```typescript
+// Fetch all consented vehicles and energy sites (follows every page)
+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 (a read, not a command)
+  await vehicle.api.state();
+}
+
+// Access discovered energy sites
+for (const siteId in products.energySites) {
+  const site = products.energySites[siteId];
+  console.log(`Found Site: ${site.name} (${site.id})`);
+}
+```
+
+#### Filtering products
+
+`getProducts()` returns one page of consented products. Pass `type` (`"vehicle"` or `"energy"`), `ref` (only the customer with that reference), `since` (only consents granted at or after that time), and `limit`/`cursor` for pagination:
+
+```typescript
+const page = await teslemetry.api.getProducts({ type: "vehicle", limit: 50 });
+console.log(page.count, page.response, page.next_cursor);
+```
+
+#### Product events
+
+The stream emits a `product` event each time a vehicle or energy site joins or leaves your business (`event` is `product.joined` or `product.left`, with `type`, `vin` or `energy_site_id`, `customer`, `cause` on `product.left`, and `timestamp`). Select it with the `products` preset or the exact `product` topic:
+
+```typescript
+teslemetry.sse.on("product", (event) => {
+  console.log(event.event, event.vin ?? event.energy_site_id);
+});
+```
+
+The business webhook receives the same event as `product.joined`/`product.left`.
+
+### Business configuration and webhook
+
+The generated client contains business-only functions for `/api/business/config/default*` (`getApiBusinessConfigDefault`, `postApiBusinessConfigDefault`, `putApiBusinessConfigDefault`, `patchApiBusinessConfigDefault`, `deleteApiBusinessConfigDefault`, `getApiBusinessConfigDefaultStatus`: the default telemetry configuration applied to shared vehicles) and `/api/business/webhook` (`getApiBusinessWebhook`, `putApiBusinessWebhook`, `patchApiBusinessWebhook`, `deleteApiBusinessWebhook`: the webhook that receives telemetry from every vehicle shared with your business). `@teslemetry/pro` does not export these functions yet; call the endpoints with `teslemetry.client` or any HTTP client, as described in the [API reference](https://api.teslemetry.pro/docs).
+
+### 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/pro";
+
+try {
+  await vehicle.api.wakeUp();
+} catch (error) {
+  console.error("Failed to wake up vehicle:", error);
+}
+```
+
+## License
+
+Apache-2.0