franklinwh-ha-cloud-analytics 0.1.1__tar.gz

franklinwh_ha_cloud_analytics-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 david2069
+
+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.

franklinwh_ha_cloud_analytics-0.1.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: franklinwh-ha-cloud-analytics
+Version: 0.1.1
+Summary: The FranklinWH cloud's energy reporting (periods, chart payload, page panel) shared by the FranklinWH bridges
+Author: david2069
+License: MIT
+Project-URL: Source, https://github.com/david2069/franklinwh-ha-cloud-analytics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: franklinwh-cloud>=0.6.5
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# franklinwh-ha-cloud-analytics
+
+The FranklinWH cloud's energy reporting, shared by the FranklinWH bridges. It sits next to
+a bridge's own (local) analytics behind a **Local / Cloud** switch: the same controls,
+two different sources, and the page always says which one it is showing.
+
+- **Periods:** Day (5-min), Day (hourly), Week, Month, Year, Lifetime, with a date picker.
+- **Chart:** home load, solar, battery (discharge +, charge −) and grid (import +,
+  export −) in the site's time zone.
+- **Totals:** solar production (to home, battery, grid), battery flows (discharged by
+  destination, charged by source), grid flows (imported / exported) and home load (by
+  source), each value with how sure the source is of it.
+- **History:** imported into the bridge's own database (closed months once, the current
+  month refreshed) for monthly, annual and lifetime totals, queries and download.
+
+Status: phase 1 (periods, chart payload, panel). The phased plan is in
+[direct-connect-bridge #215](https://github.com/david2069/franklinwh-direct-connect-bridge/issues/215).
+
+## How a bridge uses it
+
+The bridge keeps the cloud credentials, its routes and its database. This package makes
+the cloud calls through [franklinwh-cloud](https://github.com/david2069/franklinwh-cloud),
+builds one payload per period, and ships a dependency-free panel the bridge mounts under
+its Analytics page.
+
+```python
+import franklinwh_ha_cloud_analytics as ca
+
+cache = ca.Cache()                       # one per bridge; keyed by gateway below
+
+# GET /api/analytics/cloud?period=month&date=2026-11-05
+payload = await ca.fetch(client, "month", date(2026, 11, 5), today=site_today,
+                         cache=cache, key=gateway_id)
+```
+
+`client` is a logged-in franklinwh-cloud client for the gateway, and `site_today` is
+today's date in the site's own time zone. Serve `ca.static_dir()` at `/cloud-analytics/`,
+then:
+
+```html
+<link rel="stylesheet" href="cloud-analytics/cloud-analytics.css">
+<script src="cloud-analytics/cloud-analytics.js"></script>
+<script>FWHCloudAnalytics.mount(el, {endpoint: "api/analytics/cloud",
+                                    params: () => ({gateway: currentGatewayId})});</script>
+```
+
+`python -m franklinwh_ha_cloud_analytics.demo` serves the panel over made-up data.
+
+## Periods
+
+| Period | Library call | Chart |
+|---|---|---|
+| Day (5-min) | `get_power_by_day(day)` | lines, kW |
+| Day (hourly) | `get_power_by_day(day)`, added up per hour | bars, kWh |
+| Week | `get_power_details(2, its Monday)` | bars per day, kWh |
+| Month | `get_power_details(3, the 1st)` | bars per day, kWh |
+| Year | `get_power_details(4, 1 January)` | bars per month, kWh |
+| Lifetime | `get_power_details(5, today)` | bars per year, kWh |
+
+A Day request to `get_power_details` returns a single bucket, so both Day views read the
+5-minute power. There, home, battery and grid are sums of the cloud's directional flows
+(solar → home, grid → battery, …), so they're marked derived (≈). Every series carries
+the weakest evidence rating of the fields it uses (franklinwh-cloud's field dictionary);
+INFERRED ones are labelled. No data stays null, never 0. Signs: battery discharge +,
+charge −; grid import +, export −.
+
+Caching: a period that today falls in is kept for 5 minutes, a finished one for 6 hours.
+The cloud's rate limit is per account, shared with the FranklinWH app.
+
+## Licence
+
+MIT

franklinwh_ha_cloud_analytics-0.1.1/README.md

@@ -0,0 +1,72 @@
+# franklinwh-ha-cloud-analytics
+
+The FranklinWH cloud's energy reporting, shared by the FranklinWH bridges. It sits next to
+a bridge's own (local) analytics behind a **Local / Cloud** switch: the same controls,
+two different sources, and the page always says which one it is showing.
+
+- **Periods:** Day (5-min), Day (hourly), Week, Month, Year, Lifetime, with a date picker.
+- **Chart:** home load, solar, battery (discharge +, charge −) and grid (import +,
+  export −) in the site's time zone.
+- **Totals:** solar production (to home, battery, grid), battery flows (discharged by
+  destination, charged by source), grid flows (imported / exported) and home load (by
+  source), each value with how sure the source is of it.
+- **History:** imported into the bridge's own database (closed months once, the current
+  month refreshed) for monthly, annual and lifetime totals, queries and download.
+
+Status: phase 1 (periods, chart payload, panel). The phased plan is in
+[direct-connect-bridge #215](https://github.com/david2069/franklinwh-direct-connect-bridge/issues/215).
+
+## How a bridge uses it
+
+The bridge keeps the cloud credentials, its routes and its database. This package makes
+the cloud calls through [franklinwh-cloud](https://github.com/david2069/franklinwh-cloud),
+builds one payload per period, and ships a dependency-free panel the bridge mounts under
+its Analytics page.
+
+```python
+import franklinwh_ha_cloud_analytics as ca
+
+cache = ca.Cache()                       # one per bridge; keyed by gateway below
+
+# GET /api/analytics/cloud?period=month&date=2026-11-05
+payload = await ca.fetch(client, "month", date(2026, 11, 5), today=site_today,
+                         cache=cache, key=gateway_id)
+```
+
+`client` is a logged-in franklinwh-cloud client for the gateway, and `site_today` is
+today's date in the site's own time zone. Serve `ca.static_dir()` at `/cloud-analytics/`,
+then:
+
+```html
+<link rel="stylesheet" href="cloud-analytics/cloud-analytics.css">
+<script src="cloud-analytics/cloud-analytics.js"></script>
+<script>FWHCloudAnalytics.mount(el, {endpoint: "api/analytics/cloud",
+                                    params: () => ({gateway: currentGatewayId})});</script>
+```
+
+`python -m franklinwh_ha_cloud_analytics.demo` serves the panel over made-up data.
+
+## Periods
+
+| Period | Library call | Chart |
+|---|---|---|
+| Day (5-min) | `get_power_by_day(day)` | lines, kW |
+| Day (hourly) | `get_power_by_day(day)`, added up per hour | bars, kWh |
+| Week | `get_power_details(2, its Monday)` | bars per day, kWh |
+| Month | `get_power_details(3, the 1st)` | bars per day, kWh |
+| Year | `get_power_details(4, 1 January)` | bars per month, kWh |
+| Lifetime | `get_power_details(5, today)` | bars per year, kWh |
+
+A Day request to `get_power_details` returns a single bucket, so both Day views read the
+5-minute power. There, home, battery and grid are sums of the cloud's directional flows
+(solar → home, grid → battery, …), so they're marked derived (≈). Every series carries
+the weakest evidence rating of the fields it uses (franklinwh-cloud's field dictionary);
+INFERRED ones are labelled. No data stays null, never 0. Signs: battery discharge +,
+charge −; grid import +, export −.
+
+Caching: a period that today falls in is kept for 5 minutes, a finished one for 6 hours.
+The cloud's rate limit is per account, shared with the FranklinWH app.
+
+## Licence
+
+MIT

franklinwh_ha_cloud_analytics-0.1.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "franklinwh-ha-cloud-analytics"
+version = "0.1.1"
+description = "The FranklinWH cloud's energy reporting (periods, chart payload, page panel) shared by the FranklinWH bridges"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "david2069"}]
+dependencies = ["franklinwh-cloud>=0.6.5"]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[project.urls]
+Source = "https://github.com/david2069/franklinwh-ha-cloud-analytics"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+franklinwh_ha_cloud_analytics = ["static/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

franklinwh_ha_cloud_analytics-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/__init__.py

@@ -0,0 +1,22 @@
+"""The FranklinWH cloud's energy reporting, shared by the FranklinWH bridges.
+
+A bridge passes in its logged-in franklinwh-cloud client; :func:`fetch` makes the one
+library call a period needs (cached), and :func:`build` turns the reply into the payload
+the page panel in ``static/`` draws. The bridge keeps credentials, routes and storage.
+"""
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+from .payload import build
+from .periods import PERIODS, Period, resolve
+from .service import Cache, fetch
+
+__version__ = "0.1.1"
+__all__ = ["PERIODS", "Cache", "Period", "build", "fetch", "resolve", "static_dir"]
+
+
+def static_dir() -> Path:
+    """The folder a bridge serves at ``/cloud-analytics/`` (cloud-analytics.js and .css)."""
+    return Path(str(resources.files(__package__) / "static"))

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/demo.py

@@ -0,0 +1,119 @@
+"""A local page with the panel over made-up data, for trying it and for the browser tests.
+
+    python -m franklinwh_ha_cloud_analytics.demo [port]
+
+No cloud call is made: the endpoint builds payloads from the shapes the library returns.
+"""
+from __future__ import annotations
+
+import json
+import math
+import sys
+from datetime import date, timedelta
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from . import build, resolve, static_dir
+
+PAGE = """<!doctype html><html><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Cloud analytics demo</title><link rel="stylesheet" href="cloud-analytics/cloud-analytics.css">
+<style>body{font-family:system-ui,sans-serif;margin:16px;background:#fff;color:#18202b}
+@media (prefers-color-scheme:dark){body{background:#121924;color:#e4e9f0}}</style></head>
+<body><div id="ca"></div><script src="cloud-analytics/cloud-analytics.js"></script>
+<script>FWHCloudAnalytics.mount(document.getElementById("ca"), {endpoint: "api/cloud"});</script>
+</body></html>"""
+
+
+def _day(on: date) -> dict:
+    """288 five-minute samples of a sunny day: solar by day, battery at night."""
+    t, flows = [], {k: [] for k in ("powerSolarHomeArray", "powerSolarGirdArray",
+                                    "powerSolarFhpArray", "powerGirdHomeArray",
+                                    "powerGirdFhpArray", "powerFhpHomeArray",
+                                    "powerFhpGirdArray")}
+    for i in range(288):
+        h = i / 12
+        t.append(f"{on.isoformat()} {int(h):02d}:{i % 12 * 5:02d}")
+        sun = max(0.0, math.sin((h - 6) / 13 * math.pi)) * 6
+        home = 0.6 + 0.8 * math.exp(-((h - 19) ** 2) / 4)
+        s_home = min(sun, home)
+        s_bat = min(sun - s_home, 3.0)
+        b_home = home - s_home if sun < 0.2 else 0.0
+        vals = {"powerSolarHomeArray": s_home, "powerSolarGirdArray": sun - s_home - s_bat,
+                "powerSolarFhpArray": s_bat, "powerGirdHomeArray": home - s_home - b_home,
+                "powerGirdFhpArray": 0.0, "powerFhpHomeArray": b_home, "powerFhpGirdArray": 0.0}
+        for k, v in vals.items():
+            flows[k].append(round(max(0.0, v), 3))
+    return {"deviceTimeArray": t, **flows}
+
+
+def _buckets(labels: list[str], today: date) -> dict:
+    out = {k: [] for k in ("kwhLoadArray", "kwhSuArray", "kwhGenArray", "kwhFhpDiArray",
+                           "kwhFhpChgArray", "kwhUtiInArray", "kwhUtiOutArray")}
+    for i, lab in enumerate(labels):
+        future = lab > today.isoformat()[:len(lab)]
+        base = 18 + 6 * math.sin(i)
+        for k, v in zip(out, (base, base * 1.4, 0.0, base * 0.4, base * 0.45, 2.0, base * 0.5)):
+            out[k].append(None if future else round(v, 2))
+    return {"deviceTimeArray": labels, **out}
+
+
+def payload(period: str, on: date, today: date) -> dict:
+    p = resolve(period, on, today)
+    if p.type is None:
+        return build(p, _day(p.start) if p.start <= today else {})
+    if period == "week":
+        labels = [(p.start + timedelta(days=i)).isoformat() for i in range(7)]
+    elif period == "month":
+        nxt = date(p.start.year + p.start.month // 12, p.start.month % 12 + 1, 1)
+        labels = [(p.start + timedelta(days=i)).isoformat() for i in range((nxt - p.start).days)]
+    elif period == "year":
+        labels = [f"{p.start.year}-{m:02d}" for m in range(1, 13)]
+    else:
+        labels = [str(y) for y in range(today.year - 3, today.year + 1)]
+    return build(p, _buckets(labels, today))
+
+
+class Handler(BaseHTTPRequestHandler):
+    today = date.today()
+
+    def log_message(self, *a):  # quiet
+        pass
+
+    def _send(self, body: bytes, ctype: str, code: int = 200):
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        u = urlparse(self.path)
+        if u.path == "/":
+            return self._send(PAGE.encode(), "text/html; charset=utf-8")
+        if u.path == "/api/cloud":
+            q = {k: v[0] for k, v in parse_qs(u.query).items()}
+            try:
+                body = payload(q.get("period", "day5"),
+                               date.fromisoformat(q.get("date") or self.today.isoformat()),
+                               self.today)
+                return self._send(json.dumps(body).encode(), "application/json")
+            except ValueError as e:
+                return self._send(json.dumps({"error": str(e)}).encode(), "application/json", 400)
+        if u.path.startswith("/cloud-analytics/"):
+            f = static_dir() / u.path.rsplit("/", 1)[-1]
+            if f.is_file():
+                ctype = "text/css" if f.suffix == ".css" else "text/javascript"
+                return self._send(f.read_bytes(), ctype)
+        self._send(b"not found", "text/plain", 404)
+
+
+def serve(port: int = 8765, today: date | None = None) -> ThreadingHTTPServer:
+    if today:
+        Handler.today = today
+    return ThreadingHTTPServer(("127.0.0.1", port), Handler)
+
+
+if __name__ == "__main__":
+    srv = serve(int(sys.argv[1]) if len(sys.argv) > 1 else 8765)
+    print(f"http://127.0.0.1:{srv.server_address[1]}/")
+    srv.serve_forever()

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/payload.py

@@ -0,0 +1,124 @@
+"""The chart payload: the library's arrays as series, in the bridges' signs.
+
+kWh periods (Week, Month, Year, Lifetime) plot the cloud's own totals as bars. Day (5-min)
+plots lines in kW, and Day (hourly) bars in kWh, both made from the 5-minute directional
+flows, so those series are marked derived. Each series carries the weakest evidence rating
+of the fields it uses (franklinwh_cloud.const.energy_fields). Signs: battery discharge +,
+charge −; grid import +, export −. No data stays null, never 0.
+"""
+from __future__ import annotations
+
+from franklinwh_cloud.const.energy_fields import ELECTRIC_FIELDS, POWER_FIELDS
+
+from .periods import Period
+
+_EVIDENCE = {f.api: f.evidence for f in (*ELECTRIC_FIELDS, *POWER_FIELDS)}
+_RANK = {"CONFIRMED": 0, "CORROBORATED": 1, "INFERRED": 2}
+SAMPLES_PER_HOUR = 12
+
+LABELS = {"home": "Home load", "solar": "Solar", "generator": "Generator",
+          "battery": "Battery", "battery_discharge": "Battery discharged",
+          "battery_charge": "Battery charged", "grid": "Grid",
+          "grid_import": "Grid imported", "grid_export": "Grid exported"}
+
+#: kWh totals per bucket (getFhpElectricData): key → (API array, sign).
+_TOTALS = (("home", "kwhLoadArray", 1), ("solar", "kwhSuArray", 1),
+           ("generator", "kwhGenArray", 1), ("battery_discharge", "kwhFhpDiArray", 1),
+           ("battery_charge", "kwhFhpChgArray", -1), ("grid_import", "kwhUtiInArray", 1),
+           ("grid_export", "kwhUtiOutArray", -1))
+
+# The 5-minute directional flows (getFhpPowerByDay; "Gird" is the API's spelling).
+_S_HOME, _S_GRID, _S_BAT = "powerSolarHomeArray", "powerSolarGirdArray", "powerSolarFhpArray"
+_G_HOME, _G_BAT = "powerGirdHomeArray", "powerGirdFhpArray"
+_B_HOME, _B_GRID = "powerFhpHomeArray", "powerFhpGirdArray"
+_GEN_HOME, _GEN_BAT = "powerGenHomeArray", "powerGenFhpArray"
+
+#: key → [(flow, sign)]: what each series adds up from the flows.
+_LINES = {
+    "home": [(_S_HOME, 1), (_G_HOME, 1), (_B_HOME, 1), (_GEN_HOME, 1)],
+    "solar": [(_S_HOME, 1), (_S_GRID, 1), (_S_BAT, 1)],
+    "battery": [(_B_HOME, 1), (_B_GRID, 1), (_S_BAT, -1), (_G_BAT, -1), (_GEN_BAT, -1)],
+    "grid": [(_G_HOME, 1), (_G_BAT, 1), (_S_GRID, -1), (_B_GRID, -1)],
+}
+_HOURLY = {
+    "home": _LINES["home"], "solar": _LINES["solar"],
+    "generator": [(_GEN_HOME, 1), (_GEN_BAT, 1)],
+    "battery_discharge": [(_B_HOME, 1), (_B_GRID, 1)],
+    "battery_charge": [(_S_BAT, -1), (_G_BAT, -1), (_GEN_BAT, -1)],
+    "grid_import": [(_G_HOME, 1), (_G_BAT, 1)],
+    "grid_export": [(_S_GRID, -1), (_B_GRID, -1)],
+}
+
+
+def _weakest(apis) -> str:
+    levels = [_EVIDENCE.get(a, "INFERRED") for a in apis]
+    return max(levels, key=_RANK.__getitem__) if levels else "INFERRED"
+
+
+def _series(key, values, apis, derived) -> dict:
+    return {"key": key, "label": LABELS[key], "values": values,
+            "evidence": _weakest(apis), "derived": derived}
+
+
+def _combine(result: dict, parts, i: int):
+    """One sample of a derived series. Flows the reply doesn't carry at all are left out
+    (no generator on this site); a null in a flow it does carry makes the sample null."""
+    total, seen = 0.0, False
+    for api, sign in parts:
+        arr = result.get(api)
+        if not isinstance(arr, list):
+            continue
+        v = arr[i] if i < len(arr) else None
+        if v is None:
+            return None
+        total += sign * v
+        seen = True
+    return round(total, 4) if seen else None
+
+
+def _present(result: dict, parts) -> list[str]:
+    return [a for a, _ in parts if isinstance(result.get(a), list)]
+
+
+def build(period: Period, result: dict | None) -> dict:
+    """The payload the panel draws for ``period`` from the library's reply ``result``."""
+    result = result or {}
+    labels = list(result.get("deviceTimeArray") or [])
+    out = {"source": "cloud", "period": period.name, "date": period.start.isoformat(),
+           "nav": {"prev": period.prev and period.prev.isoformat(),
+                   "next": period.next and period.next.isoformat()},
+           "note": None}
+    if period.name == "day5":
+        series = [_series(k, [_combine(result, parts, i) for i in range(len(labels))],
+                          _present(result, parts), True) for k, parts in _LINES.items()]
+        out.update(chart="line", unit="kW")
+    elif period.name == "dayhour":
+        hours = [f"{h:02d}:00" for h in range(24)]
+        idx: dict[str, list[int]] = {h: [] for h in hours}
+        for i, t in enumerate(labels):
+            hh = str(t).split(" ")[-1][:2] + ":00"
+            if hh in idx:
+                idx[hh].append(i)
+        series = []
+        for k, parts in _HOURLY.items():
+            vals = []
+            for h in hours:
+                samples = [_combine(result, parts, i) for i in idx[h]]
+                vals.append(None if not samples or None in samples
+                            else round(sum(samples) / SAMPLES_PER_HOUR, 4))
+            series.append(_series(k, vals, _present(result, parts), True))
+        labels = hours if labels else []
+        out.update(chart="bars", unit="kWh",
+                   note="Hourly kWh added up from the 5-minute power, within about 3% of "
+                        "the day's own totals.")
+    else:
+        series = []
+        for k, api, sign in _TOTALS:
+            arr = list(result.get(api) or [None] * len(labels))
+            series.append(_series(k, [None if v is None else sign * v for v in arr],
+                                  [api], False))
+        out.update(chart="bars", unit="kWh")
+    out["labels"] = labels
+    out["series"] = series
+    out["empty"] = not any(v is not None for s in series for v in s["values"])
+    return out

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/periods.py

@@ -0,0 +1,60 @@
+"""Periods: which library call each needs, the date it is asked for, and its neighbours.
+
+getFhpElectricData honours a week only from its Monday; month and year are snapped to their
+first day so stepping never skips or repeats one (franklinwh-cloud
+docs/ENERGY_CLI_IMPLEMENTATION_PLAN.md, DEF-ENERGY-PERIOD-PARAM). A Day request returns a
+single bucket, so both Day views read the 5-minute power instead.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+#: period → getFhpElectricData type, or None for the 5-minute call.
+PERIODS: dict[str, int | None] = {
+    "day5": None, "dayhour": None, "week": 2, "month": 3, "year": 4, "lifetime": 5}
+
+
+@dataclass(frozen=True)
+class Period:
+    name: str
+    type: int | None        # None: get_power_by_day
+    start: date             # the date the library is asked for
+    prev: date | None
+    next: date | None       # None when it would be in the future
+    current: bool           # today falls inside it
+
+
+def _start(name: str, on: date, today: date) -> date:
+    if name in ("day5", "dayhour"):
+        return on
+    if name == "week":
+        return on - timedelta(days=on.weekday())
+    if name == "month":
+        return on.replace(day=1)
+    if name == "year":
+        return on.replace(month=1, day=1)
+    return today
+
+
+def _step(name: str, start: date, n: int) -> date:
+    if name in ("day5", "dayhour"):
+        return start + timedelta(days=n)
+    if name == "week":
+        return start + timedelta(weeks=n)
+    if name == "month":
+        m = start.year * 12 + start.month - 1 + n
+        return date(m // 12, m % 12 + 1, 1)
+    return start.replace(year=start.year + n)
+
+
+def resolve(name: str, on: date, today: date) -> Period:
+    """The period ``name`` that contains ``on`` (``today`` in the site's zone)."""
+    if name not in PERIODS:
+        raise ValueError(f"unknown period {name!r}; one of {', '.join(PERIODS)}")
+    start = _start(name, on, today)
+    if name == "lifetime":
+        return Period(name, PERIODS[name], start, None, None, True)
+    nxt = _step(name, start, 1)
+    return Period(name, PERIODS[name], start, _step(name, start, -1),
+                  nxt if nxt <= today else None, start <= today < nxt)

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/service.py

@@ -0,0 +1,48 @@
+"""The one library call per period, cached so the cloud is asked as little as possible.
+
+franklinwh-cloud has no energy cache of its own and its rate limits are per account
+(docs/RATE_LIMITING.md), so a period that is still filling in is kept for a few minutes
+and a finished one for hours.
+"""
+from __future__ import annotations
+
+import time
+from datetime import date
+
+from .payload import build
+from .periods import resolve
+
+
+class Cache:
+    CURRENT_S = 300           # a period today falls in
+    FINISHED_S = 6 * 3600     # a period that has ended
+
+    def __init__(self):
+        self._d: dict[tuple, tuple[float, float, dict]] = {}
+
+    def get(self, key: tuple, now: float):
+        hit = self._d.get(key)
+        return hit[2] if hit and now - hit[0] < hit[1] else None
+
+    def put(self, key: tuple, value: dict, ttl: float, now: float) -> None:
+        self._d[key] = (now, ttl, value)
+
+
+async def fetch(client, period: str, on: date, *, today: date, cache: Cache | None = None,
+                key: str = "", now: float | None = None) -> dict:
+    """The payload for ``period`` containing ``on``. ``client`` is a logged-in
+    franklinwh-cloud client for the gateway; ``key`` separates gateways in ``cache``."""
+    p = resolve(period, on, today)
+    now = time.time() if now is None else now
+    call = ("by_day", p.start.isoformat()) if p.type is None \
+        else ("details", p.type, p.start.isoformat())
+    ck = (key, *call)
+    result = cache.get(ck, now) if cache else None
+    if result is None:
+        result = (await client.get_power_by_day(p.start.isoformat()) if p.type is None
+                  else await client.get_power_details(p.type, p.start.isoformat()))
+        if cache is not None:
+            cache.put(ck, result or {}, Cache.CURRENT_S if p.current else Cache.FINISHED_S, now)
+    out = build(p, result)
+    out["fetched_at"] = now
+    return out

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/static/cloud-analytics.css

@@ -0,0 +1,40 @@
+/* FranklinWH cloud analytics panel. It sits inside the host's page and takes the host's text
+ * colour; a host can override any --ca- token. */
+.fwhca{ --ca-muted: color-mix(in srgb, currentColor 60%, transparent); --ca-line: color-mix(in srgb, currentColor 18%, transparent);
+  --ca-accent: #2f9e5d; --ca-crit: #d1453b;
+  --ca-home: #5b8def; --ca-solar: #e8b100; --ca-generator: #9b6bd6;
+  --ca-battery: #2fae6b; --ca-battery_discharge: #2fae6b; --ca-battery_charge: #7fd1a3;
+  --ca-grid: #8a94a3; --ca-grid_import: #d1453b; --ca-grid_export: #8a94a3; }
+.fwhca-bar{ display: flex; flex-wrap: wrap; gap: 8px; align-items: center; justify-content: space-between; }
+.fwhca-nav{ display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+.fwhca button, .fwhca input, .fwhca select{ font: inherit; font-size: .82rem; color: inherit; background: transparent; border: 1px solid var(--ca-line); border-radius: 8px; padding: 5px 10px; min-height: 34px; }
+.fwhca button{ cursor: pointer; }
+.fwhca button:disabled{ opacity: .4; cursor: default; }
+.fwhca button[aria-pressed="true"]{ border-color: var(--ca-accent); color: var(--ca-accent); }
+.fwhca select{ background: transparent; cursor: pointer; padding: 4px 6px; }
+.fwhca select option{ color: initial; }
+.fwhca button:focus-visible, .fwhca input:focus-visible, .fwhca select:focus-visible{ outline: 2px solid var(--ca-accent); outline-offset: 2px; }
+.fwhca-status{ margin: 10px 0 4px; font-size: .82rem; color: var(--ca-muted); }
+.fwhca-status.fwhca-err{ color: var(--ca-crit); }
+.fwhca-chart svg{ width: 100%; height: auto; display: block; }
+.fwhca-empty{ padding: 40px 0; text-align: center; color: var(--ca-muted); }
+.fwhca-grid{ stroke: var(--ca-line); stroke-width: 1; }
+.fwhca-grid.zero{ stroke: var(--ca-muted); }
+.fwhca-ax{ fill: var(--ca-muted); font-size: 11px; }
+.fwhca-line{ fill: none; stroke-width: 1.6; }
+.fwhca-hit{ fill: transparent; }
+.fwhca-hit:hover{ fill: var(--ca-line); }
+.fwhca-legend{ display: flex; flex-wrap: wrap; gap: 6px 14px; font-size: .8rem; margin-top: 6px; }
+.fwhca-key i{ display: inline-block; width: 10px; height: 10px; border-radius: 2px; margin-right: 5px; vertical-align: -1px; }
+.fwhca-note{ font-size: .78rem; color: var(--ca-muted); margin: 6px 0 0; }
+.fwhca abbr{ text-decoration: none; color: var(--ca-muted); }
+.c-home{ --c: var(--ca-home); } .c-solar{ --c: var(--ca-solar); } .c-generator{ --c: var(--ca-generator); }
+.c-battery{ --c: var(--ca-battery); } .c-battery_discharge{ --c: var(--ca-battery_discharge); } .c-battery_charge{ --c: var(--ca-battery_charge); }
+.c-grid{ --c: var(--ca-grid); } .c-grid_import{ --c: var(--ca-grid_import); } .c-grid_export{ --c: var(--ca-grid_export); }
+.fwhca-line[class*="c-"]{ stroke: var(--c); }
+.fwhca-bar-r[class*="c-"], .fwhca-key i[class*="c-"]{ fill: var(--c); background: var(--c); }
+
+.fwhca [hidden]{ display: none !important; }
+.fwhca-nav{ gap: 4px; }
+.fwhca-nav button{ min-width: 32px; padding: 4px 6px; }
+.fwhca input[type=date]{ padding: 4px 6px; height: 34px; box-sizing: border-box; }

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics/static/cloud-analytics.js

@@ -0,0 +1,190 @@
+/* FranklinWH cloud analytics: the period picker and chart, drawn inside a host's page.
+ *
+ * The bridge serves this file and cloud-analytics.css at /cloud-analytics/, includes both,
+ * and calls FWHCloudAnalytics.mount(el, {endpoint: "api/analytics/cloud"}). The endpoint
+ * takes ?period=&date= (and anything the host adds through params(), such as its gateway)
+ * and returns franklinwh_ha_cloud_analytics.build()'s payload, or {error: "..."}. Dates
+ * and their steps come from the payload (the site's own calendar), never from this
+ * browser's clock in UTC.
+ */
+(function () {
+  "use strict";
+
+  const PERIODS = [["day5", "Day (5-min)"], ["dayhour", "Day (hourly)"], ["week", "Week"],
+                   ["month", "Month"], ["year", "Year"], ["lifetime", "Lifetime"]];
+  const KEY = "fwh-cloud-analytics:period";
+  const KEY_STACK = "fwh-cloud-analytics:stacked";   // "1": bars stacked, one column per bucket
+  const esc = (s) => String(s == null ? "" : s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+  const store = {
+    get(k) { try { return localStorage.getItem(k); } catch (e) { return null; } },
+    set(k, v) { try { localStorage.setItem(k, v); } catch (e) { /* private mode */ } }
+  };
+  // Today in this browser's own zone (not toISOString, which is UTC). Only the first load
+  // uses it; after that the payload's date and nav are the site's calendar.
+  const localToday = () => { const d = new Date(); const p = (n) => String(n).padStart(2, "0");
+    return d.getFullYear() + "-" + p(d.getMonth() + 1) + "-" + p(d.getDate()); };
+  const fmt = (v, unit) => v == null ? "no data" : (Math.abs(v) >= 100 ? v.toFixed(0) : v.toFixed(2)) + " " + unit;
+
+  function mount(el, options) {
+    const o = Object.assign({ endpoint: "api/analytics/cloud", params: null, sourceLabel: "the FranklinWH cloud" }, options || {});
+    const st = { period: store.get(KEY) || "day5", date: localToday(), data: null, busy: false,
+                 stacked: store.get(KEY_STACK) === "1" };
+    if (!PERIODS.some((p) => p[0] === st.period)) st.period = "day5";
+    el.classList.add("fwhca");
+    el.innerHTML =
+      '<div class="fwhca-bar"><select class="fwhca-period" aria-label="Period">' +
+      PERIODS.map((p) => '<option value="' + p[0] + '">' + p[1] + "</option>").join("") +
+      '</select><div class="fwhca-nav"><button type="button" data-step="prev" aria-label="Previous period">‹</button>' +
+      '<input type="date" aria-label="Date"><button type="button" data-step="next" aria-label="Next period">›</button>' +
+      '<button type="button" data-stack aria-pressed="false" aria-label="Stacked bars" title="Stacked: where the energy came from above zero, where it went below">' +
+      '<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><path d="M3 2h4v5H3zM3 9h4v5H3zM9 5h4v3H9zM9 10h4v4H9z" fill="currentColor"/></svg></button>' +
+      '<button type="button" data-refresh aria-label="Refresh" title="Refresh">↻</button></div></div>' +
+      '<p class="fwhca-status" aria-live="polite"></p><div class="fwhca-chart"></div>' +
+      '<div class="fwhca-legend"></div><p class="fwhca-note"></p>';
+    const $ = (s) => el.querySelector(s);
+    const dateIn = $("input[type=date]");
+
+    el.addEventListener("click", (e) => {
+      const b = e.target.closest("button");
+      if (!b || st.busy) return;
+      if (b.dataset.step && st.data && st.data.nav[b.dataset.step]) { st.date = st.data.nav[b.dataset.step]; load(); }
+      else if ("refresh" in b.dataset) load(true);
+      else if ("stack" in b.dataset) { st.stacked = !st.stacked; store.set(KEY_STACK, st.stacked ? "1" : "0"); render(); }
+    });
+    const periodIn = $(".fwhca-period");
+    periodIn.addEventListener("change", () => { st.period = periodIn.value; store.set(KEY, st.period); load(); });
+    dateIn.addEventListener("change", () => { if (dateIn.value) { st.date = dateIn.value; load(); } });
+
+    async function load(refresh) {
+      st.busy = true; render();
+      const q = new URLSearchParams(Object.assign({ period: st.period, date: st.date },
+        refresh ? { refresh: "1" } : {}, typeof o.params === "function" ? o.params() : o.params || {}));
+      try {
+        const r = await fetch(o.endpoint + (o.endpoint.includes("?") ? "&" : "?") + q);
+        const j = await r.json().catch(() => ({ error: "HTTP " + r.status }));
+        st.data = r.ok && !j.error ? j : { error: j.error || j.detail || "HTTP " + r.status };
+        if (!st.data.error) st.date = st.data.date;
+      } catch (e) { st.data = { error: "Could not reach the bridge: " + e.message }; }
+      st.busy = false; render();
+    }
+
+    function render() {
+      const d = st.data;
+      periodIn.value = st.period;
+      periodIn.disabled = st.busy;
+      const life = st.period === "lifetime";
+      $(".fwhca-nav").hidden = life;
+      dateIn.value = st.date;
+      dateIn.max = localToday();
+      $("[data-step=prev]").disabled = !d || !!d.error || !d.nav || !d.nav.prev;
+      $("[data-step=next]").disabled = !d || !!d.error || !d.nav || !d.nav.next;
+      const stackBtn = $("[data-stack]");
+      stackBtn.hidden = !d || !!d.error || d.chart !== "bars";
+      stackBtn.setAttribute("aria-pressed", String(st.stacked));
+      const status = $(".fwhca-status");
+      status.classList.toggle("fwhca-err", !!(d && d.error));
+      if (st.busy) status.textContent = "Loading from " + o.sourceLabel + "…";
+      else if (!d) status.textContent = "";
+      else if (d.error) status.textContent = d.error;
+      else status.textContent = "Showing cloud data from " + o.sourceLabel + (life ? "" : " · " + d.date) +
+        (d.fetched_at ? " · read " + new Date(d.fetched_at * 1000).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : "");
+      const ok = d && !d.error && !st.busy;
+      $(".fwhca-chart").innerHTML = ok ? (d.empty ? '<p class="fwhca-empty">No cloud data for this period.</p>' : chart(d)) : "";
+      $(".fwhca-legend").innerHTML = ok && !d.empty ? legend(d) : "";
+      $(".fwhca-note").textContent = ok ? [d.note, st.stacked && d.chart === "bars" && !d.empty
+        ? "Stacked: where the energy came from above zero (solar, battery, grid import), where it went below (home, battery charge, grid export)." : null]
+        .filter(Boolean).join(" ") : "";
+    }
+
+    // Series with nothing but null or 0 (a site with no generator) are left out.
+    const shown = (d) => d.series.filter((s) => s.values.some((v) => v != null && v !== 0));
+
+    function legend(d) {
+      return shown(d).map((s) => '<span class="fwhca-key"><i class="c-' + esc(s.key) + '"></i>' + esc(s.label) +
+        (s.evidence === "INFERRED" ? ' <abbr title="Inferred from the field name; never checked">(inferred)</abbr>' : "") +
+        (s.derived ? ' <abbr title="Added up from the cloud\'s 5-minute flows">≈</abbr>' : "") + "</span>").join("");
+    }
+
+    function chart(d) {
+      // drawn at the panel's own width, so axis text stays readable on a phone
+      const S = shown(d), n = d.labels.length, W = Math.max(300, Math.round($(".fwhca-chart").clientWidth || 720)),
+            H = W < 520 ? 220 : 260, L = 44, R = 8, T = 24, B = 28;
+      const stack = st.stacked && d.chart === "bars";
+      // Stacked is an energy balance: sources above zero, uses below. Home load is a use, so
+      // it is drawn below (its tooltip keeps the real value).
+      const drawn = (s, v) => (stack && s.key === "home" && v != null ? -v : v);
+      // Stacked: positives pile up above zero and negatives below, so the range is the
+      // per-bucket sums rather than the single values.
+      const vals = stack ? d.labels.flatMap((_, i) => [
+          S.reduce((a, s) => a + Math.max(0, drawn(s, s.values[i]) || 0), 0),
+          S.reduce((a, s) => a + Math.min(0, drawn(s, s.values[i]) || 0), 0)])
+        : S.flatMap((s) => s.values).filter((v) => v != null);
+      let hi = Math.max(0, ...vals), lo = Math.min(0, ...vals);
+      if (hi === lo) hi = lo + 1;
+      const step = nice((hi - lo) / 4);
+      hi = Math.ceil(hi / step) * step; lo = Math.floor(lo / step) * step;
+      const y = (v) => T + (hi - v) / (hi - lo) * (H - T - B);
+      const cw = (W - L - R) / Math.max(n, 1), x = (i) => L + cw * (i + 0.5);
+      let g = "";
+      for (let v = lo; v <= hi + step / 2; v += step) {
+        g += '<line class="fwhca-grid' + (Math.abs(v) < step / 1e6 ? " zero" : "") + '" x1="' + L + '" x2="' + (W - R) + '" y1="' + y(v) + '" y2="' + y(v) + '"/>' +
+             '<text class="fwhca-ax" x="' + (L - 6) + '" y="' + (y(v) + 4) + '" text-anchor="end">' + +v.toFixed(2) + "</text>";
+      }
+      const every = Math.ceil(n / (W < 520 ? 4 : 8));
+      d.labels.forEach((t, i) => { if (i % every === 0) g += '<text class="fwhca-ax" x="' + x(i) + '" y="' + (H - 8) + '" text-anchor="middle">' + esc(short(t, d.period)) + "</text>"; });
+      if (d.chart === "line") {
+        S.forEach((s) => {
+          let path = "", pen = false;
+          s.values.forEach((v, i) => { if (v == null) { pen = false; return; } path += (pen ? "L" : "M") + x(i).toFixed(1) + " " + y(v).toFixed(1); pen = true; });
+          g += '<path class="fwhca-line c-' + esc(s.key) + '" d="' + path + '"><title>' + esc(s.label) + "</title></path>";
+        });
+        // one invisible column per sample, so hovering anywhere shows that time's values
+        d.labels.forEach((t, i) => { g += '<rect class="fwhca-hit" x="' + (x(i) - cw / 2) + '" y="' + T + '" width="' + cw + '" height="' + (H - T - B) + '"><title>' +
+          esc(t + "\n" + S.map((s) => s.label + ": " + fmt(s.values[i], d.unit)).join("\n")) + "</title></rect>"; });
+      } else if (stack) {
+        const bw = Math.max(1, cw * 0.7);
+        d.labels.forEach((t, i) => {
+          let up = 0, down = 0;
+          S.forEach((s) => {
+            const real = s.values[i], v = drawn(s, real);
+            if (v == null || v === 0) return;
+            const from = v > 0 ? up : down, to = from + v;
+            if (v > 0) up = to; else down = to;
+            g += '<rect class="fwhca-bar-r c-' + esc(s.key) + '" x="' + (x(i) - bw / 2).toFixed(1) + '" width="' + bw.toFixed(1) +
+                 '" y="' + Math.min(y(from), y(to)).toFixed(1) + '" height="' + Math.max(0.5, Math.abs(y(to) - y(from))).toFixed(1) +
+                 '"><title>' + esc(t + " · " + s.label + ": " + fmt(real, d.unit)) + "</title></rect>";
+          });
+        });
+      } else {
+        const bw = Math.max(1, cw * 0.8 / Math.max(S.length, 1));
+        S.forEach((s, k) => s.values.forEach((v, i) => {
+          if (v == null) return;
+          const bx = x(i) - cw * 0.4 + k * bw;
+          g += '<rect class="fwhca-bar-r c-' + esc(s.key) + '" x="' + bx.toFixed(1) + '" width="' + bw.toFixed(1) + '" y="' + Math.min(y(v), y(0)).toFixed(1) +
+               '" height="' + Math.max(0.5, Math.abs(y(v) - y(0))).toFixed(1) + '"><title>' + esc(d.labels[i] + " · " + s.label + ": " + fmt(v, d.unit)) + "</title></rect>";
+        }));
+      }
+      return '<svg viewBox="0 0 ' + W + " " + H + '" role="img" aria-label="Cloud energy chart in ' + esc(d.unit) + '">' +
+             '<text class="fwhca-ax" x="4" y="12">' + esc(d.unit) + "</text>" + g + "</svg>";
+    }
+
+    // redraw at the new width when the panel is resized (rotation, sidebar)
+    let lastW = 0;
+    if (window.ResizeObserver) new ResizeObserver(() => {
+      const w = $(".fwhca-chart").clientWidth;
+      if (Math.abs(w - lastW) > 8) { lastW = w; if (!st.busy) render(); }
+    }).observe(el);
+    load();
+    return { reload: () => load(true) };
+  }
+
+  function nice(x) { const p = Math.pow(10, Math.floor(Math.log10(x))); const m = x / p; return (m <= 1 ? 1 : m <= 2 ? 2 : m <= 5 ? 5 : 10) * p; }
+  function short(t, period) {
+    t = String(t);
+    if (period === "day5") return t.split(" ").pop().slice(0, 5);
+    if (period === "week" || period === "month") return t.slice(5);
+    return t;
+  }
+
+  window.FWHCloudAnalytics = { mount };
+})();

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics.egg-info/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: franklinwh-ha-cloud-analytics
+Version: 0.1.1
+Summary: The FranklinWH cloud's energy reporting (periods, chart payload, page panel) shared by the FranklinWH bridges
+Author: david2069
+License: MIT
+Project-URL: Source, https://github.com/david2069/franklinwh-ha-cloud-analytics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: franklinwh-cloud>=0.6.5
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# franklinwh-ha-cloud-analytics
+
+The FranklinWH cloud's energy reporting, shared by the FranklinWH bridges. It sits next to
+a bridge's own (local) analytics behind a **Local / Cloud** switch: the same controls,
+two different sources, and the page always says which one it is showing.
+
+- **Periods:** Day (5-min), Day (hourly), Week, Month, Year, Lifetime, with a date picker.
+- **Chart:** home load, solar, battery (discharge +, charge −) and grid (import +,
+  export −) in the site's time zone.
+- **Totals:** solar production (to home, battery, grid), battery flows (discharged by
+  destination, charged by source), grid flows (imported / exported) and home load (by
+  source), each value with how sure the source is of it.
+- **History:** imported into the bridge's own database (closed months once, the current
+  month refreshed) for monthly, annual and lifetime totals, queries and download.
+
+Status: phase 1 (periods, chart payload, panel). The phased plan is in
+[direct-connect-bridge #215](https://github.com/david2069/franklinwh-direct-connect-bridge/issues/215).
+
+## How a bridge uses it
+
+The bridge keeps the cloud credentials, its routes and its database. This package makes
+the cloud calls through [franklinwh-cloud](https://github.com/david2069/franklinwh-cloud),
+builds one payload per period, and ships a dependency-free panel the bridge mounts under
+its Analytics page.
+
+```python
+import franklinwh_ha_cloud_analytics as ca
+
+cache = ca.Cache()                       # one per bridge; keyed by gateway below
+
+# GET /api/analytics/cloud?period=month&date=2026-11-05
+payload = await ca.fetch(client, "month", date(2026, 11, 5), today=site_today,
+                         cache=cache, key=gateway_id)
+```
+
+`client` is a logged-in franklinwh-cloud client for the gateway, and `site_today` is
+today's date in the site's own time zone. Serve `ca.static_dir()` at `/cloud-analytics/`,
+then:
+
+```html
+<link rel="stylesheet" href="cloud-analytics/cloud-analytics.css">
+<script src="cloud-analytics/cloud-analytics.js"></script>
+<script>FWHCloudAnalytics.mount(el, {endpoint: "api/analytics/cloud",
+                                    params: () => ({gateway: currentGatewayId})});</script>
+```
+
+`python -m franklinwh_ha_cloud_analytics.demo` serves the panel over made-up data.
+
+## Periods
+
+| Period | Library call | Chart |
+|---|---|---|
+| Day (5-min) | `get_power_by_day(day)` | lines, kW |
+| Day (hourly) | `get_power_by_day(day)`, added up per hour | bars, kWh |
+| Week | `get_power_details(2, its Monday)` | bars per day, kWh |
+| Month | `get_power_details(3, the 1st)` | bars per day, kWh |
+| Year | `get_power_details(4, 1 January)` | bars per month, kWh |
+| Lifetime | `get_power_details(5, today)` | bars per year, kWh |
+
+A Day request to `get_power_details` returns a single bucket, so both Day views read the
+5-minute power. There, home, battery and grid are sums of the cloud's directional flows
+(solar → home, grid → battery, …), so they're marked derived (≈). Every series carries
+the weakest evidence rating of the fields it uses (franklinwh-cloud's field dictionary);
+INFERRED ones are labelled. No data stays null, never 0. Signs: battery discharge +,
+charge −; grid import +, export −.
+
+Caching: a period that today falls in is kept for 5 minutes, a finished one for 6 hours.
+The cloud's rate limit is per account, shared with the FranklinWH app.
+
+## Licence
+
+MIT

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/franklinwh_ha_cloud_analytics/__init__.py
+src/franklinwh_ha_cloud_analytics/demo.py
+src/franklinwh_ha_cloud_analytics/payload.py
+src/franklinwh_ha_cloud_analytics/periods.py
+src/franklinwh_ha_cloud_analytics/service.py
+src/franklinwh_ha_cloud_analytics.egg-info/PKG-INFO
+src/franklinwh_ha_cloud_analytics.egg-info/SOURCES.txt
+src/franklinwh_ha_cloud_analytics.egg-info/dependency_links.txt
+src/franklinwh_ha_cloud_analytics.egg-info/requires.txt
+src/franklinwh_ha_cloud_analytics.egg-info/top_level.txt
+src/franklinwh_ha_cloud_analytics/static/cloud-analytics.css
+src/franklinwh_ha_cloud_analytics/static/cloud-analytics.js
+tests/test_page.py
+tests/test_payload.py

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics.egg-info/requires.txt

@@ -0,0 +1,4 @@
+franklinwh-cloud>=0.6.5
+
+[test]
+pytest>=8.0

franklinwh_ha_cloud_analytics-0.1.1/src/franklinwh_ha_cloud_analytics.egg-info/top_level.txt

@@ -0,0 +1 @@
+franklinwh_ha_cloud_analytics

franklinwh_ha_cloud_analytics-0.1.1/tests/test_page.py

@@ -0,0 +1,150 @@
+"""The panel in a real browser: periods, stepping, units, nulls, empty periods.
+
+Needs Playwright with a Chrome or Chromium; skipped where it isn't installed.
+"""
+import threading
+from datetime import date
+
+import pytest
+
+sync_api = pytest.importorskip("playwright.sync_api")
+
+from franklinwh_ha_cloud_analytics.demo import serve  # noqa: E402
+
+TODAY = date(2026, 11, 9)
+
+
+@pytest.fixture(scope="module")
+def base():
+    srv = serve(port=0, today=TODAY)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    yield f"http://127.0.0.1:{srv.server_address[1]}"
+    srv.shutdown()
+
+
+@pytest.fixture(scope="module")
+def browser():
+    with sync_api.sync_playwright() as p:
+        try:
+            b = p.chromium.launch(channel="chrome", headless=True)
+        except Exception:  # noqa: BLE001
+            try:
+                b = p.chromium.launch(headless=True)
+            except Exception as e:  # noqa: BLE001
+                pytest.skip(f"no browser: {e}")
+        yield b
+        b.close()
+
+
+@pytest.fixture
+def page(browser, base):
+    ctx = browser.new_context(viewport={"width": 1100, "height": 800})
+    pg = ctx.new_page()
+    errors = []
+    pg.on("pageerror", lambda e: errors.append(str(e)))
+    # a fresh start once per test; a reload inside the test keeps what was remembered
+    pg.add_init_script("if (!sessionStorage.t) { localStorage.clear(); sessionStorage.t = 1; }")
+    pg.goto(base + "/")
+    pg.wait_for_selector(".fwhca-chart svg")
+    yield pg
+    assert errors == []
+    ctx.close()
+
+
+def _status(pg):
+    return pg.locator(".fwhca-status").inner_text()
+
+
+def test_opens_on_day_5min_lines_in_kw(page):
+    assert page.input_value(".fwhca-period") == "day5"
+    assert page.locator(".fwhca-line").count() >= 3
+    assert page.locator("svg text").first.text_content() == "kW"
+    assert "Showing cloud data from the FranklinWH cloud" in _status(page)
+
+
+def test_periods_switch_to_kwh_bars_and_remember(page):
+    page.select_option(".fwhca-period", "month")
+    page.wait_for_selector(".fwhca-bar-r")
+    assert page.locator("svg text").first.text_content() == "kWh"
+    assert page.input_value("input[type=date]") == "2026-11-01"
+    assert page.locator("[data-step=next]").is_disabled()          # no future month
+    page.click("[data-step=prev]")
+    page.wait_for_function("document.querySelector('input[type=date]').value === '2026-10-01'")
+    page.reload()
+    page.wait_for_selector(".fwhca-bar-r")
+    assert page.input_value(".fwhca-period") == "month"
+
+
+def test_week_snaps_to_monday_and_lifetime_has_no_dates(page):
+    page.select_option(".fwhca-period", "week")
+    page.wait_for_function("document.querySelector('input[type=date]').value === '2026-11-09'")
+    page.fill("input[type=date]", "2026-11-05")
+    page.dispatch_event("input[type=date]", "change")
+    page.wait_for_function("document.querySelector('input[type=date]').value === '2026-11-02'")
+    page.select_option(".fwhca-period", "lifetime")
+    page.wait_for_selector(".fwhca-bar-r")
+    assert page.locator(".fwhca-nav").is_hidden()
+
+
+def test_hourly_says_it_is_derived_and_future_day_is_empty(page):
+    page.select_option(".fwhca-period", "dayhour")
+    page.wait_for_selector(".fwhca-bar-r")
+    assert "5-minute" in page.locator(".fwhca-note").inner_text()
+    assert "≈" in page.locator(".fwhca-legend").inner_text()
+    page.fill("input[type=date]", "2026-12-01")
+    page.dispatch_event("input[type=date]", "change")
+    page.wait_for_selector(".fwhca-empty")
+
+
+def test_a_generator_that_never_ran_is_not_in_the_legend(page):
+    page.select_option(".fwhca-period", "year")
+    page.wait_for_selector(".fwhca-bar-r")
+    assert "Generator" not in page.locator(".fwhca-legend").inner_text()
+    assert page.locator(".fwhca-bar-r.c-generator").count() == 0
+
+
+def test_phone_width_has_no_horizontal_scroll(browser, base):
+    ctx = browser.new_context(viewport={"width": 375, "height": 740})
+    pg = ctx.new_page()
+    pg.goto(base + "/")
+    pg.wait_for_selector(".fwhca-chart svg")
+    assert pg.evaluate("document.documentElement.scrollWidth <= window.innerWidth")
+    ctx.close()
+
+
+def test_period_is_one_dropdown_so_the_bar_is_one_line_on_a_phone(browser, base):
+    ctx = browser.new_context(viewport={"width": 375, "height": 740})
+    pg = ctx.new_page()
+    pg.goto(base + "/")
+    pg.wait_for_selector(".fwhca-chart svg")
+    assert pg.locator("select.fwhca-period option").count() == 6
+    period, nav = pg.locator(".fwhca-period").bounding_box(), pg.locator(".fwhca-nav").bounding_box()
+    assert abs(period["y"] - nav["y"]) < 4          # side by side, not stacked
+    ctx.close()
+
+
+def test_bars_can_be_stacked_and_the_choice_is_remembered(page):
+    page.select_option(".fwhca-period", "week")
+    page.wait_for_selector(".fwhca-bar-r")
+    page.click("[data-step=prev]")                       # a whole week of data
+    page.wait_for_function("document.querySelector('input[type=date]').value === '2026-11-02'")
+    page.wait_for_selector(".fwhca-bar-r")
+    btn = page.locator("[data-stack]")
+    assert btn.is_visible() and btn.get_attribute("aria-pressed") == "false"
+    xs = lambda: {round(float(r.get_attribute("x"))) for r in page.locator(".fwhca-bar-r").all()}
+    side_by_side = len(xs())
+    btn.click()
+    assert btn.get_attribute("aria-pressed") == "true"
+    assert len(xs()) == 7 < side_by_side                 # one column per day
+    assert "came from above zero" in page.locator(".fwhca-note").inner_text()
+    zero = page.evaluate("+document.querySelector('.fwhca-grid.zero').getAttribute('y1')")
+    home = page.locator(".fwhca-bar-r.c-home").first
+    assert float(home.get_attribute("y")) >= zero - 0.5   # home load is a use: below zero
+    assert "Home load: -" not in home.locator("title").text_content()   # the real value
+    page.reload()
+    page.wait_for_selector(".fwhca-bar-r")
+    assert page.locator("[data-stack]").get_attribute("aria-pressed") == "true"
+    assert len(xs()) == 1                                # this week: today only, one column
+    page.select_option(".fwhca-period", "day5")
+    page.wait_for_selector(".fwhca-line")
+    assert page.locator("[data-stack]").is_hidden()     # lines don't stack

franklinwh_ha_cloud_analytics-0.1.1/tests/test_payload.py

@@ -0,0 +1,130 @@
+"""Periods, the chart payload and the fetch, against the franklinwh-cloud response shapes."""
+import asyncio
+from datetime import date
+
+import pytest
+
+import franklinwh_ha_cloud_analytics as ca
+
+TODAY = date(2026, 11, 9)
+
+
+# ── periods ──────────────────────────────────────────────────────────────────
+@pytest.mark.parametrize("period,on,want", [
+    ("day5", date(2026, 11, 5), date(2026, 11, 5)),
+    ("dayhour", date(2026, 11, 5), date(2026, 11, 5)),
+    ("week", date(2026, 11, 5), date(2026, 11, 2)),        # Thursday → its Monday
+    ("month", date(2026, 11, 5), date(2026, 11, 1)),
+    ("year", date(2026, 11, 5), date(2026, 1, 1)),
+    ("lifetime", date(2020, 1, 1), TODAY),                  # the date is ignored
+])
+def test_resolve_snaps_to_the_period_start(period, on, want):
+    assert ca.resolve(period, on, TODAY).start == want
+
+
+def test_navigation_steps_whole_periods_and_stops_at_today():
+    assert ca.resolve("month", date(2026, 1, 31), TODAY).prev == date(2025, 12, 1)
+    assert ca.resolve("month", date(2026, 10, 31), TODAY).next == date(2026, 11, 1)
+    assert ca.resolve("month", date(2026, 11, 5), TODAY).next is None        # no future
+    assert ca.resolve("week", date(2026, 11, 5), TODAY).prev == date(2026, 10, 26)
+    assert ca.resolve("year", date(2025, 6, 1), TODAY).next == date(2026, 1, 1)
+    assert ca.resolve("day5", date(2026, 11, 8), TODAY).next == TODAY
+    life = ca.resolve("lifetime", TODAY, TODAY)
+    assert life.prev is None and life.next is None
+
+
+def test_unknown_period_is_refused():
+    with pytest.raises(ValueError):
+        ca.resolve("ytd", TODAY, TODAY)
+
+
+# ── kWh periods: bars of the cloud's own totals ──────────────────────────────
+MONTH = {"deviceTimeArray": ["2026-11-01", "2026-11-02"],
+         "kwhLoadArray": [20.5, None], "kwhSuArray": [30.0, None],
+         "kwhGenArray": [0.0, None],
+         "kwhFhpDiArray": [8.0, None], "kwhFhpChgArray": [10.0, None],
+         "kwhUtiInArray": [2.0, None], "kwhUtiOutArray": [9.5, None]}
+
+
+def test_kwh_period_is_bars_with_signs_nulls_and_evidence():
+    p = ca.build(ca.resolve("month", date(2026, 11, 1), TODAY), MONTH)
+    assert p["chart"] == "bars" and p["unit"] == "kWh" and p["source"] == "cloud"
+    assert p["labels"] == ["2026-11-01", "2026-11-02"]
+    s = {x["key"]: x for x in p["series"]}
+    assert s["home"]["values"] == [20.5, None]                   # no data is null, never 0
+    assert s["battery_charge"]["values"] == [-10.0, None]        # charge −
+    assert s["battery_discharge"]["values"] == [8.0, None]       # discharge +
+    assert s["grid_export"]["values"] == [-9.5, None]            # export −
+    assert s["grid_import"]["values"] == [2.0, None]             # import +
+    assert s["home"]["evidence"] == "CORROBORATED" and s["home"]["derived"] is False
+    assert s["generator"]["evidence"] == "INFERRED"
+    assert p["empty"] is False
+    assert p["date"] == "2026-11-01" and p["nav"] == {"prev": "2026-10-01", "next": None}
+
+
+def test_a_period_with_no_data_says_empty():
+    p = ca.build(ca.resolve("year", date(2027, 1, 1), date(2027, 1, 1)), {})
+    assert p["empty"] is True and p["labels"] == []
+
+
+# ── Day (5-min): lines in kW, home / battery / grid derived from the flows ───
+DAY = {"deviceTimeArray": ["2026-11-05 00:00", "2026-11-05 00:05", "2026-11-05 01:00"],
+       "powerSolarHomeArray": [1.0, 0.0, None], "powerSolarGirdArray": [0.5, 0.0, 0.0],
+       "powerSolarFhpArray": [0.5, 0.0, 0.0], "powerGirdHomeArray": [0.0, 0.2, 0.0],
+       "powerGirdFhpArray": [0.0, 1.0, 0.0], "powerFhpHomeArray": [0.0, 0.0, 0.6],
+       "powerFhpGirdArray": [0.0, 0.0, 0.0]}
+
+
+def test_day_5min_lines_are_derived_kw_and_null_when_a_part_is_null():
+    p = ca.build(ca.resolve("day5", date(2026, 11, 5), TODAY), DAY)
+    assert p["chart"] == "line" and p["unit"] == "kW"
+    s = {x["key"]: x for x in p["series"]}
+    assert set(s) == {"home", "solar", "battery", "grid"}
+    assert s["home"]["values"][:2] == [1.0, 0.2]
+    assert s["solar"]["values"][:2] == [2.0, 0.0]
+    assert s["battery"]["values"][:2] == [-0.5, -1.0]            # charging −
+    assert s["grid"]["values"][:2] == [-0.5, 1.2]                # export −, import +
+    assert s["home"]["values"][2] is None                        # solar→home was null
+    assert s["home"]["derived"] is True and s["home"]["evidence"] == "CORROBORATED"
+
+
+def test_day_hourly_integrates_the_5min_flows_into_kwh():
+    p = ca.build(ca.resolve("dayhour", date(2026, 11, 5), TODAY), DAY)
+    assert p["chart"] == "bars" and p["unit"] == "kWh"
+    assert p["labels"][:2] == ["00:00", "01:00"] and len(p["labels"]) == 24
+    s = {x["key"]: x for x in p["series"]}
+    assert s["home"]["values"][0] == pytest.approx((1.0 + 0.2) / 12)
+    assert s["battery_charge"]["values"][0] == pytest.approx(-(0.5 + 1.0) / 12)
+    assert s["home"]["values"][2] is None                        # an hour with no samples
+    assert s["home"]["derived"] is True
+    assert "5-minute" in p["note"]
+
+
+# ── fetch: the right call, cached ────────────────────────────────────────────
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    async def get_power_details(self, type, timeperiod):
+        self.calls.append(("details", type, timeperiod))
+        return MONTH
+
+    async def get_power_by_day(self, dayTime):
+        self.calls.append(("by_day", dayTime))
+        return DAY
+
+
+def test_fetch_uses_the_library_call_for_each_period_and_caches():
+    c, cache = FakeClient(), ca.Cache()
+    run = lambda period, on, now=0.0: asyncio.run(
+        ca.fetch(c, period, on, today=TODAY, cache=cache, key="gw1", now=now))
+    run("week", date(2026, 11, 5))
+    run("dayhour", date(2026, 11, 5))
+    run("day5", date(2026, 11, 5))                       # same day: cached
+    assert c.calls == [("details", 2, "2026-11-02"), ("by_day", "2026-11-05")]
+    run("month", date(2026, 11, 5))                      # current month
+    run("month", date(2026, 11, 5), now=ca.Cache.CURRENT_S + 1)   # stale → fetched again
+    run("month", date(2026, 10, 5))
+    run("month", date(2026, 10, 5), now=ca.Cache.CURRENT_S + 1)   # finished month: still cached
+    assert c.calls[2:] == [("details", 3, "2026-11-01"), ("details", 3, "2026-11-01"),
+                           ("details", 3, "2026-10-01")]