KeeperHub / KeeperHub/keeperhub

The Analytics summary documents four fields the endpoint does not return, and the wrong unit for successRate

Open
#2,485 3 comments 0 reactions 0 assignees View on GitHub
accepted confirmed documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.