John O'Keefe
6fc501b35a
Stats docs written handler/service-first (summary/this-week/book-stats
new; library-usage frontmatter'd — its body was already accurate).
Registry: 4 entries on services.UserSummaryStats/WeekSummaryStats/
LibraryUsageStats/BookStats. Family-lens note: library-usage 403s an
explicit library_id outside the visible set (431fec0 rule).
UNVERIFIED sweep (7 -> 0), each resolved against the handler:
- device-usage takes NO date params; popular-books takes only ?limit
(the 'standard analytics date-range params' claim was wrong)
- link_book media_item_id: no validate tag but service-always-written
- push_stats book-ref field set documented (uuid/sha256/title/authors)
- filter_count: confirmed ParseMediaSearchParams machinery + 400 on bad
filter + 403 visibility
- facets values element shape pinned: {value, display?, count}
- get_config: dynamic key set IS the contract (reworded, no marker)
make test 9/9.
44 lines
923 B
Markdown
44 lines
923 B
Markdown
---
|
|
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
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| --------- | ---- | -------- | ----------- |
|
|
| limit | int | No | Result cap; default `10` |
|
|
|
|
There is no date-range filtering on this endpoint — the ranking is
|
|
computed over all reading history.
|
|
|
|
## Errors
|
|
|
|
| Status | Body | When |
|
|
| ------ | ---- | ---- |
|
|
| 500 | `{"error": "..."}` | unexpected server error |
|