KPI reports via API

[2ndtlmining]

Send KPI reports via API

[2ndtlmining]

Problem statement

State: open, enhancement (to be labelled enhancement + kpi).
Decision (2026-09-11, from the reporter): the pull path. The requirement is that Hermes (the agent) fetches the KPI report itself, reads the data and produces meaningful analysis — not that the app pushes to a third-party API.

Today the report can only leave the app by being posted to a Discord webhook (scheduler) or by an operator clicking send (footer dialog). Entering a webhook through a browser would be the wrong mechanism for "agent reads the numbers and explains them" — the report's own JSON is, and it already exists.

Verified live (2026-09-11):

• GET https://fluxtracker.app.runonflux.io/api/kpi/preview?timeframe=weekly → 200, 6.8 KB, 1.6 s.
• 19 metrics across Revenue, Nodes, Resource Utilization, Applications, Decentralization, each with current, comparison, change.absolute and change.percent, plus period labels (Aug 31–Sep 6, 2026 vs Aug 24–30, 2026) and dataset.availableMetrics / totalMetrics (18 / 19).
• That is enough to produce a real weekly analysis with no browser automation and no credentials.

Two defects surfaced in that same read — both belong to documenting this contract:

1. Every metric carries changePercent: null. The percentage actually lives at change.percent (e.g. Revenue +111.6%). A consumer reading the obvious field gets null for all 19 metrics and silently concludes nothing changed.
2. The decentralization section reads Insufficient data (% Datacenter: null, topDatacenters: [], coverage 0/7 days, 14 missing). I checked before calling this a bug — it is not one: /api/decentralization/history returns only two dated rows (2026-09-10 and 2026-09-11), so decentralization snapshots exist only from ~Sep 10 onward and any report covering an earlier week legitimately has nothing to read. The action here is presentation, not diagnosis: say "not collected before 2026-09-10" rather than a bare null, so a reader can tell a data gap from a failure. (The .catch(() => []) at kpiService.js:100 still hides genuine read errors and should be distinguishable.)

What needs to change

• README.md — document the read endpoint as the contract: timeframe values, response schema, where the change percentage lives, and what Insufficient data means. This is the whole point of the issue: a documented interface an agent (or any consumer) can rely on.
• src/lib/services/kpiService.js:90-134 + src/lib/metrics.js — one place for the change percentage. Either populate changePercent or drop it from the metric shape; leaving a permanently-null field next to the real one is a trap.
• Fix the decentralization section (or make its absence explicit and correct): distinct behaviour for "snapshots exist", "no snapshots in range" and "read failed", instead of one silent null.
• Add schemaVersion to the payload so consumers can detect a breaking change.
• Cache the response per (timeframe, period) — the endpoint recomputes several DB reads on every call (1.6 s live) and an agent may poll it.
• Decide and document auth: the payload is the same public data the dashboard already shows, so read-only public access is defensible; if it needs protecting, a shared-secret header is the smallest change.
• Optional but useful: a tiny scripts/kpi-fetch.mjs (or a documented curl) that writes the report JSON to a file, so the agent/cron workflow is explicit rather than tribal knowledge.
• Agent-side delivery stays outside the app: Hermes has a connected Discord gateway, so a scheduled job can fetch the JSON, analyse it and post the digest to the configured channel — no webhook needs to be entered anywhere.
• De-scoped: the push medium (medium: 'api', KPI_API_URL, KPI_API_ALLOWED_HOSTS, SSRF guard). Not needed for this requirement; kept here only as a note in case a downstream system ever needs to be pushed to.

Implementation plan

1. Document the contract in the README's KPI section: endpoint, timeframes, full response shape, schemaVersion, aggregation semantics (sum vs average per section), and the insufficient-data rule. Publish one real response as the worked example.
2. Fix the two defects: single source for the change percentage; decentralization section honest about absence and correct when snapshots exist. Add a regression test for each.
3. Version + cache: schemaVersion in the payload; per-(timeframe, period) cache with a short TTL, same shape either way.
4. Make consumption reproducible: the documented fetch command plus an analysis step — the live read above is the proof it works; scripting it turns it into a repeatable workflow.
5. Decide delivery: manual today (agent analysis in chat), or a Hermes cron job for a weekly digest to Discord. If scheduled, the job must target the messaging gateway — output from a TUI-session job is not delivered back into that session.
6. Push path (deferred, only if asked for later): reuse the notes above and the SSRF guard from the Discord implementation.

Success criteria

• A consumer can fetch one timeframe and compute a period-over-period analysis without reading any code: schemaVersion present, one documented field holding each metric's percentage (no permanently-null sibling field), and both periods labelled.
• The README documents the endpoint, timeframes, response schema, aggregation semantics and insufficient-data behaviour, with a real sample response.
• The decentralization section returns real numbers for a period where snapshots exist (e.g. this week), and for earlier periods states the reason explicitly ("not collected before 2026-09-10") — never a bare null, and never a swallowed read error (kpiService.js:100's .catch(() => []) must not be able to masquerade as "no snapshots").
• Repeat fetches inside the cache window do not recompute (asserted), and the response shape is identical cached or fresh.
• The agent workflow is reproducible: a documented command/script returns parseable JSON, and an analysis produced from it for one timeframe is attached to this issue as evidence.
• Read-only access needs no credentials for the public data (or, if a token is added, it is env-var documented and the public dashboard is unaffected).
• If a scheduled digest is added: it arrives in the configured Discord channel once per period, produced by a job that targets the messaging gateway rather than a TUI session.

Test plan

• Payload shape, per timeframe: schemaVersion present; the change percentage is populated (or absent) in exactly one place; no metric exposes a field that is always null; dataset.empty and availableMetrics/totalMetrics behave as documented.
• Decentralization section: three cases — snapshots present in range (real numbers, e.g. the current week), none collected for that period (explicit message naming the first collected date), read failure (explicit error state, not silently []). Fixtures for all three; the current .catch(() => []) must not be able to masquerade as "no snapshots".
• Caching: two calls within the TTL trigger one buildKpiReport() (spy); the cached and fresh responses are byte-identical for the same period.
• Contract stability: a JSON-schema check in the repo (or a shape snapshot test) so an accidental field rename fails CI rather than breaking a consumer.
• Consumer smoke test: the documented fetch command returns parseable JSON for all five timeframes, and the analysis step runs on it offline.
• Manual cross-check: the JSON numbers match the KPI modal on the dashboard for the same timeframe — both read buildKpiReport(), so any divergence is a bug.