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.
1.6 KiB
1.6 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| POST | /api/devices/:deviceId/sync/link-book | jwt | devices |
Link Book
Links a device file (by path + SHA256) to a media item, optionally with a confidence score. Used by the book-matching flow.
Example request
{
"device_file": {
"file_path": "/books/1984.epub",
"sha256": "abc123...",
"title": "1984"
},
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"confidence_score": 0.95
}
Example response
{
"status": "linked",
"device_file_alias": {
"id": "660e8400-e29b-41d4-a716-446655440000",
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"device_id": "770e8400-e29b-41d4-a716-446655440000",
"file_path": "/books/1984.epub",
"file_sha256": "abc123...",
"confidence_score": 0.95
}
}
Request fields
| Field | Type | Required | Notes |
|---|---|---|---|
| device_file.file_path | string | no | path on the device |
| device_file.sha256 | string | no | file content hash |
| device_file.title | string | no | device-side title |
| media_item_id | string (uuid) | yes | no validate tag, but the service always writes it (upsert keyed on media item) — omitting it orphans the alias |
| confidence_score | number | no | match confidence (0-1) |
Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error": "Invalid device ID"} / {"error": "Invalid request body"} |
malformed id or body |
| 500 | {"error": "Failed to link book: ..."} |
service failure |