John O'Keefe
c4b62af213
New frontmatter'd docs with handler-compatible examples: - devices/get_device.md (DeviceInfo shape) - devices/regenerate_device_token.md (token + sync_urls) - devices/get_device_mappings.md (wrapper + DeviceMappingSummary) - devices/update_device_mapping.md (UpdateDeviceMappingRequest) - devices/download_sidecar_config.md (sidecar config JSON file) - devices/link_book.md (LinkBookRequest; one UNVERIFIED marker on required-tag) Schema registry: 6 new entries; DeviceMappingSummary hoisted to package scope. Gate passes (the UNVERIFIED marker is logged, not a failure). Excludes /api/devices-page (htmx page route, per ground rules).
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 | `services.LinkBookRequest` declares it as uuid; the gate only checks the Bind struct — UNVERIFIED: confirm required tag on LinkBookRequest fields |
|
|
| 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 |
|