docs(media-items): Work Order 3 batch 3a — reader-adjacent CRUD (11 endpoints)

New frontmatter'd docs with real shapes (sqlc models pinned directly):
- bookmarks: get/create/update/delete (sync-aware rows: dedup_key,
  last_modified_*, tombstones; delete is 204)
- review: upsert (empty string DELETES the review) / get (200 with
  {review:null} when absent) / delete
- get single note + highlight (full sqlc row shapes)
- annotation history: restore (POST, kind via query or body) and purge
  (DELETE, kind via required query; permanent)

Gate hardening forced by this batch:
- required-field walk now guards non-struct Request types (RawMessage pins)
- update_media_bookmark needed a full example block (no cross-reference
  shortcuts — the gate checks every doc standalone)
This commit is contained in:
John O'Keefe committed 2026-10-24 15:03:36 -04:00
1 parent 85cdaf7196
commit ed0ce5d077
13 files changed
+545 -4

No files matched your search

@@ -0,0 +1,53 @@
---
method: GET
path: /api/media-items/:id/highlights/:highlightId
auth: jwt
area: media-items
---
<!-- source: internal/handlers/media.go:2078 MediaHandler.GetMediaHighlight -->
# Get Media Highlight
Returns one highlight by id.
## Example response
```json example-response
{
"id": "440e8400-e29b-41d4-a716-446655440000",
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"user_id": "92413c3a-e1b8-4fff-b3f9-95c74478d19a",
"selection_text": "It was a bright cold day in April...",
"start_position": "kobo:3.1",
"end_position": "kobo:3.4",
"color": "yellow",
"note_id": null,
"created_at": "2026-10-24T13:57:01Z",
"updated_at": "2026-10-24T13:57:01Z",
"percentage_start": 41.2,
"percentage_end": 41.8,
"character_start": null,
"character_end": null,
"epubcfi_start": null,
"epubcfi_end": null,
"chapter_reference": 3,
"paragraph_start": null,
"paragraph_end": null,
"panel_number": null,
"device_sync_data": null,
"dedup_key": "kobo:3.1-3.4",
"last_modified_at": "2026-10-24T13:57:01Z",
"last_modified_source": "web",
"note_text": null,
"deleted": false,
"deleted_at": null
}
```
## Errors
| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "invalid highlight id"}` | malformed id |
| 404 | `{"error": "highlight not found"}` | no such highlight |
| 500 | `{"error": "..."}` | unexpected server error |