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.
60 lines
1.6 KiB
Markdown
60 lines
1.6 KiB
Markdown
---
|
|
method: POST
|
|
path: /api/devices/:deviceId/sync/link-book
|
|
auth: jwt
|
|
area: devices
|
|
---
|
|
<!-- source: internal/handlers/matching.go:57 MatchingHandler.LinkBook -->
|
|
|
|
# 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
|
|
|
|
```json 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
|
|
|
|
```json 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 |
|