Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 53 Wiki Activity

docs(stats): Claude-side pinning — all 4 stats endpoints + UNVERIFIED sweep to zero

Browse Source 
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.
This commit is contained in:
John O'Keefe committed 2026-10-24 18:25:12 -04:00
1 parent e21e1facde
commit 6fc501b35a
12 files changed
+264 -11
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/developer/api/stats/get_book_stats.md
+60
View File
@@ -0,0 +1,60 @@
---
method: GET
path: /api/stats/books/:id
auth: jwt
area: stats
---
<!-- source: internal/handlers/stats.go:118 StatsHandler.BookStats -> services/statistics_service.go:697 BookStats -->
# Get Book Stats
Per-book reading card on the book detail page: lifetime totals plus recent
sessions (newest first, capped). Scoped to the requesting user's own
reading history.
## Example Request
```http
GET /api/stats/books/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Example response
```json example-response
{
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"total_minutes": 610,
"total_seconds": 36612,
"total_pages": 0,
"session_count": 41,
"max_progress": 0.62,
"finished": false,
"first_session": "2026-09-30T18:02:11Z",
"last_session": "2026-10-23T21:44:05Z",
"recent_sessions": [
{
"started_at": "2026-10-23T21:44:05Z",
"ended_at": "2026-10-23T22:19:40Z",
"minutes": 35,
"pages": 0,
"device_id": "660e8400-e29b-41d4-a716-446655440001"
}
]
}
```
## Response fields
| Field | Type | Notes |
| ------------- | ------- | ---------------------------------------------------------------- |
| total_seconds | int | exact wall-clock (audio "Time listened"; minutes lose remainder) |
| max_progress | float | highest progress fraction ever reached (0-1) |
| recent_sessions | array | newest first, server-capped |
## Errors
| Status | Body | When |
| ------ | ------------------------ | ----------------------- |
| 400 | `invalid media item id` | malformed id |
| 401 | `invalid user` | no user in JWT context |
docs/developer/api/stats/get_library_usage.md
+9 -1
View File
@@ -1,3 +1,11 @@
---
method: GET
path: /api/stats/library-usage
auth: jwt
area: stats
---
<!-- source: internal/handlers/stats.go:88 StatsHandler.LibraryUsage -> services/statistics_service.go:586 LibraryUsageStats -->
# Get Library Usage Statistics
The `/stats` page's **Library tab** payload: media_items **inventory**
@@ -29,7 +37,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"library_id": "8c8d0cee-1cca-4def-9a37-edad3a4d438b",
"items": 743,
docs/developer/api/stats/get_summary.md
+106
View File
@@ -0,0 +1,106 @@
---
method: GET
path: /api/stats/summary
auth: jwt
area: stats
---
<!-- source: internal/handlers/stats.go:33 StatsHandler.Summary -> services/statistics_service.go:213 UserSummaryStats -->
# Get Reading Summary
The `/stats` page's complete payload: totals, zero-filled daily arrays,
streaks, most-active day, top books, and per-library/per-device breakdowns
for a time range. All day boundaries and buckets are computed in the
**requesting user's timezone**.
## Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------- |
| range | string | No | `7` (default), `30`, `90`, or `year` (days window) |
Invalid `range` values return **400**.
## Example Request
```http
GET /api/stats/summary?range=30
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Example response
```json example-response
{
"range": "30",
"days": 30,
"start_date": "2026-09-24",
"end_date": "2026-10-24",
"total_minutes": 1250,
"total_audio_minutes": 1100,
"total_pages": 412,
"session_count": 96,
"books_with_activity": 7,
"books_finished": 2,
"completion_rate": 0.29,
"average_session_minutes": 13.0,
"daily": [
{
"date": "2026-09-24",
"minutes": 42,
"pages": 15,
"sessions": 3,
"audio_minutes": 42
}
],
"streak": { "current": 5, "longest": 12 },
"most_active_weekday": "Saturday",
"most_active_day": "2026-10-17",
"most_active_day_minutes": 87,
"top_books": [
{
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Gardens of the Moon",
"author": "Steven Erikson",
"minutes": 610,
"pages": 0
}
],
"library_breakdown": [
{
"library_id": "8c8d0cee-1cca-4def-9a37-edad3a4d438b",
"name": "Audiobooks",
"minutes": 1100,
"pages": 0,
"sessions": 84,
"books": 5
}
],
"device_breakdown": [
{ "device_id": "", "name": "Web", "type": "web", "minutes": 150 },
{
"device_id": "660e8400-e29b-41d4-a716-446655440001",
"name": "Pixel 9",
"type": "android",
"minutes": 1100
}
]
}
```
## Response fields
| Field | Type | Notes |
| ---------------- | ------- | --------------------------------------------------------------------- |
| total_audio_minutes | int | listening minutes inside `total_minutes` (mode-aware wording surface) |
| daily | array | zero-filled across the whole range — every day present |
| streak | object | `current` / `longest` day streaks |
| most_active_weekday | string | `""` when the range has no sessions |
| device_breakdown | array | `device_id` is `""` for the web bucket (pushes with no device credential) |
## Errors
| Status | Body | When |
| ------ | -------------------------- | ----------------------- |
| 400 | `invalid range ...` | unknown range key |
| 401 | `invalid user` | no user in JWT context |
docs/developer/api/stats/get_this_week.md
+48
View File
@@ -0,0 +1,48 @@
---
method: GET
path: /api/stats/this-week
auth: jwt
area: stats
---
<!-- source: internal/handlers/stats.go:56 StatsHandler.ThisWeek -> services/statistics_service.go:451 WeekSummaryStats -->
# Get This Week's Stats
Compact week-vs-previous-week comparison powering the dashboard widget.
Week boundaries are the requesting user's calendar week (timezone-aware).
## Query Parameters
| Parameter | Type | Required | Description |
| ---------- | ------------- | -------- | --------------------------------------- |
| library_id | string (UUID) | No | Scope totals to one library |
## Example Request
```http
GET /api/stats/this-week
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Example response
```json example-response
{
"week_minutes": 315,
"week_pages": 122,
"week_sessions": 21,
"week_books": 3,
"prev_week_minutes": 402,
"prev_week_pages": 160,
"prev_week_sessions": 25,
"active_today": true,
"current_streak": 5
}
```
## Errors
| Status | Body | When |
| ------ | -------------------- | ---------------------- |
| 400 | `invalid library id` | malformed library_id |
| 401 | `invalid user` | no user in JWT context |