KeeperHub / KeeperHub/keeperhub
The Analytics summary documents four fields the endpoint does not return, and the wrong unit for successRate
- Dominant language
- TypeScript
- Stars
- 24
- Forks
- 93
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 253
Description
### Before filing
- [x] Searched open and closed issues, and open and merged PRs, for this report: no hits for `successfulRuns`, `failedRuns`, `totalGasUsedWei`, `avgExecutionTimeMs`, or the phrase.
- [x] Checked current behaviour on `staging` at commit `6c8eb1b0ebe1f7ece3f7c32b324a095fee41ab39`.
- [x] Swept every page under `docs/api/` for the same fault rather than assuming: 264 documented names across 15 pages, and the four names below are the only ones that nothing under `app/` or `lib/` mentions.
- [x] This is one change: one page's response block and its field table.
### Reason: what you cannot do today
`docs/api/analytics.md` is the only published specification of `GET /api/analytics/summary`, so an agent or an integration builds against that page. It cannot read the response:
- four of the six documented fields do not exist under those names,
- five fields the endpoint does return are not documented anywhere,
- the documented unit for `successRate` is off by a factor of 100.
The page was accurate against some earlier shape and the endpoint moved; the four unproduced names are the residue.
### Evidence
Documented, `docs/api/analytics.md:36-56`:
```
"totalRuns": 1250, "successfulRuns": 1180, "failedRuns": 70,
"successRate": 94.4, "totalGasUsedWei": "15000000000000000", "avgExecutionTimeMs": 2340
| `successRate` | number | Percentage of successful executions (0-100) | (line 54)
```
Returned, `lib/analytics/queries.ts:686-698`, typed at `lib/analytics/types.ts:90-118`:
```
{ totalRuns, successCount, errorCount, cancelledCount, skippedCount, successRate,
avgDurationMs, totalGasWei, sponsoredGasWei, activeRuns, previousPeriod }
```
| documented | actually returned | kind of drift |
|---|---|---|
| `totalRuns` | `totalRuns` | matches |
| `successfulRuns` | `successCount` | name |
| `failedRuns` | `errorCount` | name |
| `successRate` "0-100" | `successRate`, a 0-1 fraction (`queries.ts:677`: `successCount / totalRuns`) | unit |
| `totalGasUsedWei` | `totalGasWei` | name |
| `avgExecutionTimeMs` | `avgDurationMs` (`number \| null`) | name |
| not documented | `cancelledCount`, `skippedCount`, `sponsoredGasWei`, `activeRuns`, `previousPeriod` | missing |
The unit drift is the one that misleads silently rather than erroring, and the code is the correct side of it: `components/analytics/kpi-cards.tsx:312` reads `const currentRate = summary.successRate * 100;`, so the fraction is the contract the app already relies on. `previousPeriod` returning a deliberately smaller shape than the top level (no `successRate`, no `activeRuns`, see `lib/analytics/types.ts:108-118`) is likewise real behaviour that the page never states.
### Scope
One page, and no code change. Correcting the page is the whole fix:
- the four names, the fraction unit, and `avgDurationMs`'s nullability,
- the five return fields the page omits, including what `previousPeriod` carries and what it deliberately does not,
- and `sponsoredGasWei`'s relationship to `totalGasWei` (a subset, not a sibling figure: `lib/analytics/types.ts:100-106` says adding the two double counts).
Sibling sweep: the same scan over all 15 `docs/api/` pages returned no other documented name that nothing produces, so this is the only page with this fault today. The docs-versus-routes guard in `scripts/check-api-docs-routes.ts` cannot see it by design, because it checks that a documented route exists, not the shape a response returns.
### Plan
Rewrite the "Get Analytics Summary" response block and field table to the shape the endpoint returns, with the four names corrected, `successRate` documented as a 0-1 fraction and noted as rendered as a percentage by the dashboard, and the five omitted fields added. Then sweep the rest of the page for the same staleness (the response examples on `time-series` and the rest of the page's tables) so the page is self-consistent, and leave the code alone.
I am taking this one, per the claiming note in ISSUES.md.
Contributor guide
Research direction
Start with docs/api/analytics.md and compare its response block and field table against lib/analytics/queries.ts:677,686-698 and lib/analytics/types.ts:90-118; check components/analytics/kpi-cards.tsx:312 for the displayed success-rate unit. Done means the page consistently documents the returned fields, nullability, fraction semantics, nested previousPeriod shape, and gas-field relationship, with no code changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100