docs(analytics,jobs): Work Order 3 batch 4 — device usage, popular books, job create/status

DeviceUsageResponse / PopularBooksResponse / services.JobResult pinned by
type; jobs create uses an inline anonymous request struct (RawMessage pin).
Two UNVERIFIED markers recorded (analytics date-range params, facet value
element shape).
This commit is contained in:
John O'Keefe committed 2026-10-24 15:08:18 -04:00
1 parent 4a6fb033cb
commit 7471ca99e8
5 files changed
+169

No files matched your search

@@ -0,0 +1,39 @@
---
method: GET
path: /api/analytics/popular-books
auth: jwt
area: analytics
---
<!-- source: internal/handlers/analytics.go PopularBooksResponse / GetPopularBooks -->
# Get Popular Books
Most-read books for the signed-in user.
## Example response
```json example-response
{
"books": [
{
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "1984",
"author": "George Orwell",
"read_count": 3,
"avg_completion": 0.95,
"last_read": "2026-10-24T13:57:01Z"
}
]
}
```
## Query parameters
UNVERIFIED: accepts the standard analytics date-range params; confirm exact
names before relying on them.
## Errors
| Status | Body | When |
| ------ | ---- | ---- |
| 500 | `{"error": "..."}` | unexpected server error |