# 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).