0 Fork 0

Files

T

John O'Keefe 6fc501b35a docs(stats): Claude-side pinning — all 4 stats endpoints + UNVERIFIED sweep to zero

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.

2026-10-24 18:25:12 -04:00

1.8 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
GET	/api/stats/books/:id	jwt	stats

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

GET /api/stats/books/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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

1.8 KiB Raw Blame History