aiosolaredge-one 0.2.0__py3-none-any.whl

aiosolaredge_one/__init__.py

@@ -0,0 +1,66 @@
+"""Async client for the SolarEdge ONE (Monitoring v2) API."""
+
+from __future__ import annotations
+
+from .budget import (
+    BudgetPlan,
+    backoff_interval,
+    compute_interval,
+    plan_interval,
+    project_month_end_usage,
+)
+from .client import SolarEdgeOneClient
+from .const import (
+    DEFAULT_BASE_URL,
+    RESOLUTION_DAY,
+    RESOLUTION_HOUR,
+    RESOLUTION_QUARTER_HOUR,
+)
+from .exceptions import (
+    SolarEdgeApiError,
+    SolarEdgeAuthError,
+    SolarEdgeConnectionError,
+    SolarEdgeError,
+    SolarEdgeNotFoundError,
+    SolarEdgeRateLimitError,
+)
+from .models import (
+    ConsumptionOverview,
+    Device,
+    ProductionOverview,
+    Site,
+    SiteOverview,
+    TimeSeries,
+    TimeValue,
+)
+from .ratelimit import CreditLedger, RateLimit
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SolarEdgeOneClient",
+    "BudgetPlan",
+    "backoff_interval",
+    "compute_interval",
+    "plan_interval",
+    "project_month_end_usage",
+    "DEFAULT_BASE_URL",
+    "RESOLUTION_DAY",
+    "RESOLUTION_HOUR",
+    "RESOLUTION_QUARTER_HOUR",
+    "SolarEdgeError",
+    "SolarEdgeApiError",
+    "SolarEdgeAuthError",
+    "SolarEdgeConnectionError",
+    "SolarEdgeNotFoundError",
+    "SolarEdgeRateLimitError",
+    "Site",
+    "SiteOverview",
+    "ProductionOverview",
+    "ConsumptionOverview",
+    "Device",
+    "TimeSeries",
+    "TimeValue",
+    "CreditLedger",
+    "RateLimit",
+]

aiosolaredge_one/budget.py

@@ -0,0 +1,145 @@
+"""Credit-budget pacing math (HA-agnostic, pure functions).
+
+The SolarEdge ONE API exposes only a per-minute rate limit; the monthly credit
+quota (e.g. 2000/month) is tracked locally via :class:`CreditLedger`. This module
+turns "credits remaining this month" into "how long to wait before the next poll"
+so a caller spends its budget evenly instead of burning it early.
+
+The core function, :func:`compute_interval`, is *remaining-budget aware*: it
+paces against the credits still available for the rest of the month, so it
+self-corrects. If earlier cycles overspent, later intervals lengthen; if the
+budget is nearly exhausted it backs off to ``max_interval``. This doubles as the
+budget guard — no separate "are we over budget?" branch is needed for pacing.
+
+All functions are pure (no clock, no I/O) so they can be unit-tested by feeding
+in ``remaining_credits`` / ``seconds_until_reset`` directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Sensible defaults; the HA integration overrides these from config/options.
+DEFAULT_SAFETY_FACTOR = 0.7
+DEFAULT_NIGHT_FACTOR = 3.0
+DEFAULT_MIN_INTERVAL = 60.0  # seconds — never poll faster than once a minute
+DEFAULT_MAX_INTERVAL = 6 * 60 * 60.0  # seconds — poll at least every 6h
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    if low > high:
+        # A pathological config (floor above ceiling); prefer respecting the
+        # per-minute floor over the ceiling to avoid violating the hard limit.
+        return low
+    return max(low, min(high, value))
+
+
+def cpm_floor(credits_per_cycle: int, calls_per_minute: int) -> float:
+    """Minimum seconds between cycles so we never exceed the per-minute limit.
+
+    A cycle issues ``credits_per_cycle`` calls; spacing cycles at least this far
+    apart keeps the average call rate at or below ``calls_per_minute``.
+    """
+    cpm = max(1, calls_per_minute)
+    return 60.0 * max(1, credits_per_cycle) / cpm
+
+
+@dataclass(slots=True, frozen=True)
+class BudgetPlan:
+    """User-configurable pacing parameters for one config entry."""
+
+    monthly_budget: int
+    calls_per_minute: int = 10
+    credits_per_cycle: int = 2
+    safety_factor: float = DEFAULT_SAFETY_FACTOR
+    night_factor: float = DEFAULT_NIGHT_FACTOR
+    min_interval: float = DEFAULT_MIN_INTERVAL
+    max_interval: float = DEFAULT_MAX_INTERVAL
+
+    @property
+    def target_credits(self) -> float:
+        """Credits we actually aim to spend per month (budget × safety)."""
+        return self.monthly_budget * self.safety_factor
+
+
+def compute_interval(
+    *,
+    remaining_credits: float,
+    seconds_until_reset: float,
+    credits_per_cycle: int,
+    calls_per_minute: int,
+    min_interval: float = DEFAULT_MIN_INTERVAL,
+    max_interval: float = DEFAULT_MAX_INTERVAL,
+    is_night: bool = False,
+    night_factor: float = DEFAULT_NIGHT_FACTOR,
+) -> float:
+    """Seconds to wait before the next poll, paced to the remaining budget.
+
+    ``remaining_credits`` should already have the safety factor applied (i.e. it
+    is the *target* remaining, not the raw quota). When it drops below one
+    cycle's cost — or the month has effectively ended — this returns
+    ``max_interval`` so polling backs off instead of overspending.
+    """
+    floor = max(min_interval, cpm_floor(credits_per_cycle, calls_per_minute))
+    if remaining_credits < credits_per_cycle or seconds_until_reset <= 0:
+        return max(max_interval, floor)
+
+    cycles_left = remaining_credits / max(1, credits_per_cycle)
+    interval = seconds_until_reset / cycles_left
+    if is_night:
+        interval *= night_factor
+    return _clamp(interval, floor, max_interval)
+
+
+def plan_interval(
+    plan: BudgetPlan,
+    *,
+    used_this_month: int,
+    seconds_until_reset: float,
+    is_night: bool = False,
+) -> float:
+    """Convenience wrapper: interval for a :class:`BudgetPlan` given usage."""
+    remaining = max(0.0, plan.target_credits - used_this_month)
+    return compute_interval(
+        remaining_credits=remaining,
+        seconds_until_reset=seconds_until_reset,
+        credits_per_cycle=plan.credits_per_cycle,
+        calls_per_minute=plan.calls_per_minute,
+        min_interval=plan.min_interval,
+        max_interval=plan.max_interval,
+        is_night=is_night,
+        night_factor=plan.night_factor,
+    )
+
+
+def project_month_end_usage(
+    *, used_this_month: int, elapsed_seconds: float, total_seconds: float
+) -> float:
+    """Linear projection of end-of-month spend from usage so far.
+
+    Used to decide whether to raise a "you'll blow the budget" repair issue.
+    Returns the current usage unchanged until a little time has elapsed (avoids
+    wild extrapolation from the first few seconds of the month).
+    """
+    if elapsed_seconds <= 0 or total_seconds <= 0:
+        return float(used_this_month)
+    return used_this_month * total_seconds / elapsed_seconds
+
+
+def backoff_interval(
+    attempt: int,
+    *,
+    base: float = 60.0,
+    cap: float = 60 * 60.0,
+    retry_after: float | None = None,
+) -> float:
+    """Exponential backoff after a 429, honouring ``Retry-After`` when present.
+
+    ``attempt`` is 1-based (first failure → ``base``). The result is capped at
+    ``cap`` and never shorter than a supplied ``Retry-After``.
+    """
+    exp = base * (2.0 ** max(0, attempt - 1))
+    interval = min(exp, cap)
+    if retry_after is not None:
+        interval = max(interval, retry_after)
+    return interval

aiosolaredge_one/client.py

@@ -0,0 +1,203 @@
+"""Async client for the SolarEdge ONE (Monitoring v2) API."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, cast
+
+import aiohttp
+
+from .const import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    HEADER_ACCOUNT_KEY,
+    HEADER_API_KEY,
+)
+from .exceptions import (
+    SolarEdgeApiError,
+    SolarEdgeAuthError,
+    SolarEdgeConnectionError,
+    SolarEdgeNotFoundError,
+    SolarEdgeRateLimitError,
+)
+from .models import (
+    Device,
+    Site,
+    SiteOverview,
+    TimeSeries,
+    parse_device_list,
+    parse_site_list,
+)
+from .ratelimit import CreditLedger, RateLimit
+
+
+def _fmt_time(value: str | datetime | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.isoformat()
+    return value
+
+
+class SolarEdgeOneClient:
+    """Thin async wrapper over the SolarEdge ONE v2 REST API.
+
+    The caller injects an ``aiohttp.ClientSession``. Only endpoints confirmed in
+    Phase 0 are implemented; query-param names for the time-series endpoints are
+    best-effort and may need adjustment once the docs are captured.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        api_key: str,
+        *,
+        account_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        ledger: CreditLedger | None = None,
+    ) -> None:
+        self._session = session
+        self._api_key = api_key
+        self._account_key = account_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self.ledger = ledger
+        self.rate_limit: RateLimit | None = None
+
+    # -- internals -----------------------------------------------------------
+    def _headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/json", HEADER_API_KEY: self._api_key}
+        if self._account_key:
+            headers[HEADER_ACCOUNT_KEY] = self._account_key
+        return headers
+
+    async def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        url = f"{self._base_url}{path}"
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            async with self._session.get(
+                url,
+                headers=self._headers(),
+                params=clean_params or None,
+                timeout=self._timeout,
+            ) as resp:
+                self.rate_limit = RateLimit.from_headers(resp.headers)
+                await self._raise_for_status(resp)
+                data = await resp.json()
+        except aiohttp.ClientError as err:
+            raise SolarEdgeConnectionError(f"Request to {path} failed: {err}") from err
+
+        # Count the credit only on a successful call (1 call = 1 credit).
+        if self.ledger is not None:
+            self.ledger.record(now=datetime.now(UTC))
+        return data
+
+    async def _raise_for_status(self, resp: aiohttp.ClientResponse) -> None:
+        if resp.status < 400:
+            return
+        payload: Any = None
+        try:
+            payload = await resp.json()
+        except (aiohttp.ContentTypeError, ValueError):
+            payload = await resp.text()
+
+        if resp.status in (401, 403):
+            raise SolarEdgeAuthError(
+                "Authentication failed — check the API key",
+                status=resp.status,
+                payload=payload,
+            )
+        if resp.status == 404:
+            raise SolarEdgeNotFoundError(
+                f"Resource not found: {resp.url.path}",
+                status=resp.status,
+                payload=payload,
+            )
+        if resp.status == 429:
+            retry_after = _parse_retry_after(resp.headers.get("Retry-After"))
+            raise SolarEdgeRateLimitError(
+                "Rate limit exceeded",
+                retry_after=retry_after,
+                status=resp.status,
+                payload=payload,
+            )
+        raise SolarEdgeApiError(
+            f"Unexpected API error (HTTP {resp.status})",
+            status=resp.status,
+            payload=payload,
+        )
+
+    # -- endpoints -----------------------------------------------------------
+    async def get_sites(self) -> list[Site]:
+        """``GET /sites`` — all sites visible to the token."""
+        return parse_site_list(await self._get("/sites"))
+
+    async def get_site_overview(self, site_id: int | str) -> SiteOverview:
+        """``GET /sites/{id}/overview`` — cumulative production/consumption."""
+        return SiteOverview.from_dict(await self._get(f"/sites/{site_id}/overview"))
+
+    async def get_devices(self, site_id: int | str) -> list[Device]:
+        """``GET /sites/{id}/devices`` — site inventory."""
+        return parse_device_list(await self._get(f"/sites/{site_id}/devices"))
+
+    async def get_energy(
+        self,
+        site_id: int | str,
+        *,
+        date_from: str | datetime | None = None,
+        date_to: str | datetime | None = None,
+        resolution: str | None = None,
+    ) -> TimeSeries:
+        """``GET /sites/{id}/energy`` — energy time series (Wh per interval)."""
+        params = {
+            "from": _fmt_time(date_from),
+            "to": _fmt_time(date_to),
+            "resolution": resolution,
+        }
+        return TimeSeries.from_dict(await self._get(f"/sites/{site_id}/energy", params))
+
+    async def get_power(
+        self,
+        site_id: int | str,
+        *,
+        date_from: str | datetime | None = None,
+        date_to: str | datetime | None = None,
+        resolution: str | None = None,
+    ) -> TimeSeries:
+        """``GET /sites/{id}/power`` — power time series (W, 15-min average)."""
+        params = {
+            "from": _fmt_time(date_from),
+            "to": _fmt_time(date_to),
+            "resolution": resolution,
+        }
+        return TimeSeries.from_dict(await self._get(f"/sites/{site_id}/power", params))
+
+    async def get_alerts(self, site_id: int | str) -> list[dict[str, Any]]:
+        """``GET /sites/{id}/alerts`` — returns a list (empty when none)."""
+        data = await self._get(f"/sites/{site_id}/alerts")
+        if isinstance(data, dict):
+            for key in ("alerts", "alert", "data", "items"):
+                value = data.get(key)
+                if isinstance(value, list):
+                    return cast("list[dict[str, Any]]", value)
+            return []
+        if isinstance(data, list):
+            return cast("list[dict[str, Any]]", data)
+        return []
+
+    async def validate(self) -> list[Site]:
+        """Cheapest credential check for a config flow: list sites.
+
+        Raises ``SolarEdgeAuthError`` on bad credentials.
+        """
+        return await self.get_sites()
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None

aiosolaredge_one/const.py

@@ -0,0 +1,20 @@
+"""Constants for the SolarEdge ONE (Monitoring v2) API client."""
+
+from __future__ import annotations
+
+DEFAULT_BASE_URL = "https://monitoringapi.solaredge.com/v2"
+DEFAULT_TIMEOUT = 30.0
+
+# Auth headers (v2 uses headers, not a bearer token).
+HEADER_API_KEY = "X-API-Key"
+HEADER_ACCOUNT_KEY = "X-Account-Key"
+
+# Rate-limit response headers observed in Phase 0. Only per-minute is exposed;
+# the monthly credit quota must be tracked locally (see CreditLedger).
+HEADER_RATELIMIT_LIMIT = "x-ratelimit-limit-minute"
+HEADER_RATELIMIT_REMAINING = "x-ratelimit-remaining-minute"
+
+# Resolutions accepted by the time-series endpoints (values seen: QUARTER_HOUR).
+RESOLUTION_QUARTER_HOUR = "QUARTER_HOUR"
+RESOLUTION_HOUR = "HOUR"
+RESOLUTION_DAY = "DAY"

aiosolaredge_one/exceptions.py

@@ -0,0 +1,38 @@
+"""Exceptions raised by the SolarEdge ONE client."""
+
+from __future__ import annotations
+
+
+class SolarEdgeError(Exception):
+    """Base class for all SolarEdge ONE client errors."""
+
+
+class SolarEdgeConnectionError(SolarEdgeError):
+    """Network-level failure talking to the API (timeout, DNS, connection)."""
+
+
+class SolarEdgeApiError(SolarEdgeError):
+    """The API returned an unexpected error status."""
+
+    def __init__(self, message: str, *, status: int | None = None,
+                 payload: object | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.payload = payload
+
+
+class SolarEdgeAuthError(SolarEdgeApiError):
+    """Authentication failed (HTTP 401/403) — invalid or missing API key."""
+
+
+class SolarEdgeNotFoundError(SolarEdgeApiError):
+    """Requested resource or endpoint does not exist (HTTP 404)."""
+
+
+class SolarEdgeRateLimitError(SolarEdgeApiError):
+    """Rate limit exceeded (HTTP 429)."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None,
+                 status: int | None = 429, payload: object | None = None) -> None:
+        super().__init__(message, status=status, payload=payload)
+        self.retry_after = retry_after

aiosolaredge_one/models.py

@@ -0,0 +1,235 @@
+"""Typed models for SolarEdge ONE (Monitoring v2) responses.
+
+Shapes are derived from Phase 0 live captures (see ../prd fixtures). All models
+are tolerant of missing/null fields — the API returns nulls freely on sites
+without meters or storage.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _as_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass(slots=True)
+class Site:
+    """A site as returned by ``GET /sites``."""
+
+    site_id: int
+    name: str | None = None
+    peak_power: float | None = None
+    installation_date: str | None = None
+    location: str | None = None
+    activation_status: str | None = None
+    note: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def is_active(self) -> bool:
+        return (self.activation_status or "").upper() == "ACTIVE"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Site:
+        return cls(
+            site_id=int(data["siteId"]),
+            name=data.get("name"),
+            peak_power=_as_float(data.get("peakPower")),
+            installation_date=data.get("installationDate"),
+            location=data.get("location"),
+            activation_status=data.get("activationStatus"),
+            note=data.get("note"),
+            raw=data,
+        )
+
+
+def parse_site_list(data: dict[str, Any]) -> list[Site]:
+    """Parse the nested ``{"sites": {"count": N, "site": [...]}}`` envelope."""
+    container = data.get("sites", data)
+    if isinstance(container, dict):
+        items = container.get("site") or container.get("sites") or []
+    elif isinstance(container, list):
+        items = container
+    else:
+        items = []
+    return [Site.from_dict(item) for item in items if isinstance(item, dict)]
+
+
+@dataclass(slots=True)
+class ProductionOverview:
+    total: float | None = None
+    unit: str | None = None
+    to_self_consumption: float | None = None
+    to_storage: float | None = None
+    to_grid: float | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> ProductionOverview:
+        data = data or {}
+        return cls(
+            total=_as_float(data.get("total")),
+            unit=data.get("unit"),
+            to_self_consumption=_as_float(data.get("toSelfConsumption")),
+            to_storage=_as_float(data.get("toStorage")),
+            to_grid=_as_float(data.get("toGrid")),
+        )
+
+
+@dataclass(slots=True)
+class ConsumptionOverview:
+    total: float | None = None
+    unit: str | None = None
+    from_pv: float | None = None
+    from_storage: float | None = None
+    from_grid: float | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> ConsumptionOverview:
+        data = data or {}
+        return cls(
+            total=_as_float(data.get("total")),
+            unit=data.get("unit"),
+            from_pv=_as_float(data.get("fromPv")),
+            from_storage=_as_float(data.get("fromStorage")),
+            from_grid=_as_float(data.get("fromGrid")),
+        )
+
+
+@dataclass(slots=True)
+class SiteOverview:
+    """Cumulative lifetime totals from ``GET /sites/{id}/overview``."""
+
+    site_id: int | None
+    production: ProductionOverview
+    consumption: ConsumptionOverview
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SiteOverview:
+        return cls(
+            site_id=_as_int(data.get("siteId")),
+            production=ProductionOverview.from_dict(data.get("production")),
+            consumption=ConsumptionOverview.from_dict(data.get("consumption")),
+            raw=data,
+        )
+
+
+@dataclass(slots=True)
+class Device:
+    """A device from ``GET /sites/{id}/devices`` (inverter, meter, battery...)."""
+
+    type: str | None = None
+    serial_number: str | None = None
+    manufacturer: str | None = None
+    part_number: str | None = None
+    created_at: str | None = None
+    firmware_version: str | None = None
+    active: bool | None = None
+    name: str | None = None
+    communication_type: str | None = None
+    firmware: str | None = None
+    connected_optimizers: int | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Device:
+        return cls(
+            type=data.get("type"),
+            serial_number=data.get("serialNumber"),
+            manufacturer=data.get("manufacturer"),
+            part_number=data.get("partNumber"),
+            created_at=data.get("createdAt"),
+            firmware_version=data.get("firmwareVersion"),
+            active=data.get("active"),
+            name=data.get("name"),
+            communication_type=data.get("communicationType"),
+            firmware=data.get("firmware"),
+            connected_optimizers=_as_int(data.get("connectedOptimizers")),
+            raw=data,
+        )
+
+
+def parse_device_list(data: Any) -> list[Device]:
+    """Devices may be a bare list or wrapped; be liberal."""
+    if isinstance(data, dict):
+        for key in ("devices", "device", "data", "items"):
+            if isinstance(data.get(key), list):
+                data = data[key]
+                break
+    if not isinstance(data, list):
+        return []
+    return [Device.from_dict(item) for item in data if isinstance(item, dict)]
+
+
+@dataclass(slots=True)
+class TimeValue:
+    timestamp: str
+    value: float | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TimeValue:
+        return cls(timestamp=data.get("timestamp", ""), value=_as_float(data.get("value")))
+
+
+@dataclass(slots=True)
+class TimeSeries:
+    """Response shape of ``/energy`` and ``/power`` (time series of values)."""
+
+    period_from: str | None
+    period_to: str | None
+    unit: str | None
+    resolution: str | None
+    values: list[TimeValue] = field(default_factory=list)
+
+    @property
+    def non_null_values(self) -> list[TimeValue]:
+        return [v for v in self.values if v.value is not None]
+
+    @property
+    def latest_value(self) -> float | None:
+        """Most recent non-null value (use for 'current power')."""
+        for v in reversed(self.values):
+            if v.value is not None:
+                return v.value
+        return None
+
+    @property
+    def latest(self) -> TimeValue | None:
+        for v in reversed(self.values):
+            if v.value is not None:
+                return v
+        return None
+
+    @property
+    def total(self) -> float:
+        """Sum of non-null values (e.g. energy accumulated over the period)."""
+        return sum(v.value for v in self.values if v.value is not None)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TimeSeries:
+        period = data.get("period") or {}
+        raw_values = data.get("values") or []
+        return cls(
+            period_from=period.get("from"),
+            period_to=period.get("to"),
+            unit=data.get("unit"),
+            resolution=data.get("resolution"),
+            values=[TimeValue.from_dict(v) for v in raw_values if isinstance(v, dict)],
+        )

aiosolaredge_one/ratelimit.py

@@ -0,0 +1,93 @@
+"""Rate-limit + credit tracking helpers.
+
+Phase 0 finding: the API exposes only a *per-minute* limit via response headers
+(``x-ratelimit-limit-minute`` / ``x-ratelimit-remaining-minute``). The monthly
+credit quota (e.g. 2000/month) is NOT exposed, so it must be tracked locally.
+``CreditLedger`` provides that local accounting and is JSON-serialisable so the
+Home Assistant integration can persist it across restarts.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from .const import HEADER_RATELIMIT_LIMIT, HEADER_RATELIMIT_REMAINING
+
+
+def _month_key(now: datetime) -> str:
+    return f"{now.year:04d}-{now.month:02d}"
+
+
+@dataclass(slots=True)
+class RateLimit:
+    """Per-minute rate-limit snapshot parsed from response headers."""
+
+    limit_minute: int | None = None
+    remaining_minute: int | None = None
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> RateLimit:
+        # Header names are case-insensitive; aiohttp's CIMultiDict handles that,
+        # but fall back to a manual lower-cased lookup for plain dicts.
+        def _get(name: str) -> str | None:
+            if name in headers:
+                return headers[name]
+            lowered = {k.lower(): v for k, v in headers.items()}
+            return lowered.get(name.lower())
+
+        def _int(value: str | None) -> int | None:
+            if value is None:
+                return None
+            try:
+                return int(value)
+            except ValueError:
+                return None
+
+        return cls(
+            limit_minute=_int(_get(HEADER_RATELIMIT_LIMIT)),
+            remaining_minute=_int(_get(HEADER_RATELIMIT_REMAINING)),
+        )
+
+
+@dataclass(slots=True)
+class CreditLedger:
+    """Local monthly-credit accounting (the API does not expose monthly quota).
+
+    Assumes 1 API call = 1 credit (Phase 0 finding). Resets automatically when
+    the calendar month changes.
+    """
+
+    monthly_budget: int
+    used: int = 0
+    month: str | None = None
+
+    def record(self, cost: int = 1, *, now: datetime | None = None) -> None:
+        now = now or datetime.now(UTC)
+        key = _month_key(now)
+        if self.month != key:
+            self.month = key
+            self.used = 0
+        self.used += cost
+
+    def remaining(self, *, now: datetime | None = None) -> int:
+        now = now or datetime.now(UTC)
+        if self.month != _month_key(now):
+            return self.monthly_budget
+        return max(0, self.monthly_budget - self.used)
+
+    def would_exceed(self, cost: int = 1, *, now: datetime | None = None) -> bool:
+        return self.remaining(now=now) < cost
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"monthly_budget": self.monthly_budget, "used": self.used, "month": self.month}
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> CreditLedger:
+        return cls(
+            monthly_budget=int(data.get("monthly_budget", 0)),
+            used=int(data.get("used", 0)),
+            month=data.get("month"),
+        )

aiosolaredge_one-0.2.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: aiosolaredge-one
+Version: 0.2.0
+Summary: Async client for the SolarEdge ONE (Monitoring v2) API
+Project-URL: Homepage, https://github.com/CathalOConnorRH/solaredge-v2
+Project-URL: Repository, https://github.com/CathalOConnorRH/solaredge-v2
+Project-URL: Issues, https://github.com/CathalOConnorRH/solaredge-v2/issues
+Project-URL: Changelog, https://github.com/CathalOConnorRH/solaredge-v2/blob/main/CHANGELOG.md
+Author: aiosolaredge-one contributors
+License: MIT License
+        
+        Copyright (c) 2026 aiosolaredge-one contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: async,home-assistant,monitoring,solar,solaredge
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: build>=1.2; extra == 'publish'
+Requires-Dist: twine>=5.0; extra == 'publish'
+Description-Content-Type: text/markdown
+
+# aiosolaredge-one
+
+Async Python client for the **SolarEdge ONE** (Monitoring API v2) platform. It
+powers the
+[SolarEdge ONE Home Assistant integration](https://github.com/CathalOConnorRH/ha-solaredge-one),
+which lives in its own repo and depends on this package.
+
+Base URL: `https://monitoringapi.solaredge.com/v2` · Auth: `X-API-Key` header
+(plus optional `X-Account-Key` for Fleet accounts).
+
+> Status: **alpha**. Endpoint coverage and models are derived from Phase 0 live
+> captures. Some query-param names and the storage/battery/environmental paths
+> are still unconfirmed pending docs.
+
+## Install (dev)
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+import aiohttp
+from aiosolaredge_one import SolarEdgeOneClient
+
+async with aiohttp.ClientSession() as session:
+    client = SolarEdgeOneClient(session, api_key="...")
+    sites = await client.get_sites()
+    overview = await client.get_site_overview(sites[0].site_id)
+    print(overview.production.total, overview.production.unit)
+    power = await client.get_power(sites[0].site_id)
+    print("current power:", power.latest_value, power.unit)
+```
+
+## What it covers (Phase 0-confirmed endpoints)
+
+| Method | Endpoint |
+|--------|----------|
+| `get_sites()` | `GET /sites` |
+| `get_site_overview(id)` | `GET /sites/{id}/overview` |
+| `get_devices(id)` | `GET /sites/{id}/devices` |
+| `get_energy(id, ...)` | `GET /sites/{id}/energy` |
+| `get_power(id, ...)` | `GET /sites/{id}/power` |
+| `get_alerts(id)` | `GET /sites/{id}/alerts` |
+
+Rate limiting: the client exposes `client.rate_limit` (per-minute limit +
+remaining, parsed from response headers) and an optional `CreditLedger` for
+tracking the monthly quota locally (not exposed by the API).

aiosolaredge_one-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+aiosolaredge_one/__init__.py,sha256=hF3GdTNHqhqT2T9k4e0svUnSnvjbLFXI87YQZToEHHI,1377
+aiosolaredge_one/budget.py,sha256=P2-1nS4IGtMrsebxYgSPq40iVrQ0B_sknclIkkHnmUU,5443
+aiosolaredge_one/client.py,sha256=5zZ8ApUAsP1sBdWy7nSWQeGD5nihbOX1NDNLJKDXPjE,6957
+aiosolaredge_one/const.py,sha256=RVaY1-Nc6X21uIGDyCTnQyYgLmqIxhHXSyLy51FUhu8,741
+aiosolaredge_one/exceptions.py,sha256=h1b4jwk4LWvsuw2yM8p0rv3h9Fr1-e1E4SrDtcabbXs,1230
+aiosolaredge_one/models.py,sha256=iCGZTLEyH7gu3f5G8jcLv1GpicsrvniMUbC7HpgDYQU,7408
+aiosolaredge_one/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiosolaredge_one/ratelimit.py,sha256=FPWOV8TlGRyloDsjtJT9H07KZmffYtM3aJFPlwkKuTE,3113
+aiosolaredge_one-0.2.0.dist-info/METADATA,sha256=E_mbp10GSkVkndRwc7aOIcpNh5GgeHFS7BSZ-AnUihk,4301
+aiosolaredge_one-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+aiosolaredge_one-0.2.0.dist-info/licenses/LICENSE,sha256=lxPKwJaSIe0P5wsDiL_2UEbcw2VTCmU-cop198q9N5c,1086
+aiosolaredge_one-0.2.0.dist-info/RECORD,,

aiosolaredge_one-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aiosolaredge_one-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiosolaredge-one contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.