Initial SolarEdge Optimizer Home Assistant App

2026-08-10 09:04:35 +02:00
commit f2887a0ab4
38 changed files with 4253 additions and 0 deletions
@@ -0,0 +1,67 @@
+# SolarEdge Monitoring API
+
+Typed, dependency-free client for the SolarEdge Monitoring API at
+`https://monitoringapi.solaredge.com`.
+
+Canonical reference: [SolarEdge Monitoring API documentation (March 2026)](https://knowledge-center.solaredge.com/sites/kc/files/se_monitoring_api.pdf)
+
+Directly readable local reference:
+[`docs/monitoring-api.md`](docs/monitoring-api.md)
+
+Keep `SOLAREDGE_API_KEY` and `SOLAREDGE_SITE_ID` on the server. Do not expose
+them through `EXPO_PUBLIC_` environment variables or bundle them into a client
+app.
+
+```ts
+import { createSolarEdgeClientFromEnv } from "@solar-dash/solaredgeapi";
+
+const client = createSolarEdgeClientFromEnv();
+const overview = await client.getSiteOverview();
+```
+
+The client exposes typed methods for site metadata, overview, energy, power,
+detailed meter series, current power flow, inventory, and equipment. Use
+`client.get<T>(path, query)` for other read-only Monitoring API endpoints.
+The site-specific methods use `SOLAREDGE_SITE_ID` by default, while still
+accepting an explicit site ID when needed.
+
+The client limits itself to three concurrent requests, matching SolarEdge's
+documented concurrency limit. SolarEdge also applies daily quotas of 300
+requests per account token and 300 requests per site ID and source IP, plus
+endpoint-specific maximum date ranges. Callers remain responsible for staying
+within those daily and date-range limits.
+
+SolarEdge date/time parameters are strings in the site's local time zone:
+
+- dates: `yyyy-MM-dd`
+- date-times: `yyyy-MM-dd HH:mm:ss`
+
+## Experimental optimizer access
+
+Optimizer values are not part of the official Monitoring API. The package also
+contains an explicitly unsupported, server-only portal client which performs
+the same OAuth2/PKCE login and session exchange as the Monitoring web portal.
+It does not require a browser at runtime.
+
+```env
+SOLAREDGE_USERNAME=owner@example.com
+SOLAREDGE_PASSWORD=...
+```
+
+```ts
+import { createSolarEdgePortalClientFromEnv } from "@solar-dash/solaredgeapi";
+
+const portal = createSolarEdgePortalClientFromEnv();
+const optimizerSerials = await portal.listOptimizerSerials();
+const optimizerMappings = await portal.listOptimizerMappings();
+const energy = await portal.getOptimizerEnergy({
+  startDate: "2026-08-09",
+  endDate: "2026-08-09",
+  optimizerSerials,
+});
+```
+
+Never expose the portal credentials through `EXPO_PUBLIC_` variables or a
+mobile/web bundle. Additional MFA challenges are detected but are not currently
+automated. Internal endpoints and response formats may change without notice.
+See [`docs/internal-optimizer-api.md`](docs/internal-optimizer-api.md).