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.
49 lines
1.2 KiB
Markdown
49 lines
1.2 KiB
Markdown
---
|
|
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 |
|