John O'Keefe
6f13dc2b63
Beam backfilled list/get/create/update/delete media-item, search, ratings
CRUD, progress GET/PUT. Beam correctly identified create/update/delete as
jwt+admin (admin group in the router — verified).
Claude registry: 12 entries. Notable pins:
- get_media_item: hand-built ~44-key map pinned verbatim from the handler
- create/update return the full database.MediaItems row (74 columns) —
examples merged up to the real shape via gate-driven merge script
- search returns []SearchMediaItemsRow (sqlc row — Real type pinned)
- rating scale is 1-10 int (odd = half-star); GET returns {rating: null} when
absent; update reuses the create handler (201)
- progress GET: 25 base keys + 4 CONDITIONAL position-authority keys
(css_selector/anchor_href/char_offset/context_text — added by the handler
for convertible formats with a valid CFI); PUT progress binds
sync.SaveProgressRequest and returns database.ReadingProgress
- Beam's examples were missing entirely on 4 files (list/search/progress
GET/PUT) — relabeled existing fences or inserted contract-shaped blocks
Gate-driven merge scripts (object + array variants) brought all examples to
the exact handler key sets. make test 9/9.
130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
---
|
|
method: PUT
|
|
path: /api/media-items/:id/progress
|
|
auth: jwt
|
|
area: media-items
|
|
---
|
|
<!-- source: internal/handlers/media.go:1275 MediaHandler.UpdateMediaReadingProgress -->
|
|
|
|
# Update Media Item Progress
|
|
|
|
Submit reading progress for a media item. This is the position-authority
|
|
ingest point: the server independently verifies the submission against
|
|
the book and heals it when the client's projection is wrong.
|
|
|
|
**Endpoint**: `PUT /api/media-items/:id/progress`
|
|
**Auth**: Required (Bearer token)
|
|
**Content-Type**: `application/json`
|
|
|
|
See the [Position Contract](position-contract.md) for the three-tier
|
|
submission model, the verification/healing semantics, and the offset
|
|
currencies.
|
|
|
|
## Path Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| --------- | ------------- | -------- | ---------------- |
|
|
| id | string (UUID) | Yes | Media item UUID |
|
|
|
|
## Request Body
|
|
|
|
All fields are optional; submit what your renderer can observe.
|
|
|
|
| Field | Type | Description |
|
|
| ----- | ---- | ----------- |
|
|
| `percentage` | float | Position as a fraction of the whole book (0..1). Tier 1 — the universal field. |
|
|
| `context_text` | string | Up to 100 whitespace-normalized chars starting at the anchor. Tier 2 — enables verification and healing. |
|
|
| `epubcfi` | string | Standard wrapped CFI (UTF-16 terminals). Tier 3 — the structural anchor. Note: the server re-derives the stored canonical CFI; a client's own spine numbering is healed if it disagrees with the OPF spine. |
|
|
| `character_offset` | int | Book-wide rune offset. Accepted but recomputed server-side from the verified anchor on every verified save. |
|
|
| `current_page`, `total_pages` | int | Fixed-layout position. For fixed-layout formats the page index is the canonical locator. |
|
|
| `chapter`, `chapter_progress` | int, float | Chapter index and within-chapter fraction. |
|
|
| `reading_mode` | string | `paged` or `scrolled` (fixed-layout reader state). |
|
|
| `zoom_level`, `scroll_position_x`, `scroll_position_y` | float | Fixed-layout viewport state. |
|
|
|
|
### Example Request (reflowable, all three tiers)
|
|
|
|
```http
|
|
PUT /api/media-items/774641f9-317b-4087-8e04-53bb4392ae56/progress
|
|
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
|
Content-Type: application/json
|
|
```
|
|
|
|
```json example-request
|
|
{
|
|
"percentage": 0.0415,
|
|
"context_text": "was at war with one of these Powers it was generally at peace with the other. But what was strange w",
|
|
"epubcfi": "epubcfi(/6/4!/4/8[_idContainer003]/62/1:456)"
|
|
}
|
|
```
|
|
|
|
### Example Request (fixed-layout)
|
|
|
|
```json
|
|
{
|
|
"percentage": 0.15,
|
|
"current_page": 30,
|
|
"total_pages": 194,
|
|
"reading_mode": "paged"
|
|
}
|
|
```
|
|
|
|
## Behavior
|
|
|
|
- The submission is verified against the book's XHTML when
|
|
`context_text` is present and the book is convertible reflowable: the
|
|
CFI is resolved, the text at the anchor is compared with
|
|
`context_text`, and mismatches heal by text search (percentage
|
|
disambiguates repeats). See [Position Contract](position-contract.md).
|
|
- **Anti-clobber guard**: a submission with `percentage < 0.005` is
|
|
ignored with `{"status": "ignored"}` when the stored row already holds
|
|
a percentage above `0.01` — re-opening a book at its first page does
|
|
not wipe real progress.
|
|
- The response is the stored row after verification, including the
|
|
healed `epubcfi` and the refreshed `character_offset` when
|
|
verification ran.
|
|
|
|
## Response (200 OK)
|
|
|
|
```json example-response
|
|
{
|
|
"id": "e8239659-0ed6-42ae-a946-8440d7655b42",
|
|
"media_item_id": "774641f9-317b-4087-8e04-53bb4392ae56",
|
|
"user_id": "1b64992e-3408-4d84-9e03-e2dc4950e1dd",
|
|
"current_page": null,
|
|
"total_pages": null,
|
|
"last_read_at": "2026-09-26T14:52:34.806446Z",
|
|
"percentage": 0.045,
|
|
"character_offset": 16375,
|
|
"epubcfi": "epubcfi(/6/4!/4/8[_idContainer003]/58/1:598)",
|
|
"context_text": null,
|
|
"chapter": null,
|
|
"chapter_progress": null,
|
|
"audio_offset_seconds": null,
|
|
"viewport_x": null,
|
|
"viewport_y": null,
|
|
"zoom_level": null,
|
|
"scroll_position_x": null,
|
|
"scroll_position_y": null,
|
|
"panel_number": null,
|
|
"reading_mode": "reflowable",
|
|
"last_sync_device": "web",
|
|
"last_sync_source": "koreader",
|
|
"last_sync_timestamp": "2026-09-26T14:52:34.806446Z",
|
|
"conflict_detected": false,
|
|
"conflict_resolved": false
|
|
}
|
|
```
|
|
|
|
The saved progress row (same shape as
|
|
[GET](get_media_progress.md), minus the GET-time handles). The
|
|
`epubcfi` and `percentage` in the response are the server-verified
|
|
values, which may differ from the submitted ones when healing occurred.
|
|
|
|
## Error Responses
|
|
|
|
| Code | Description |
|
|
| ---- | ----------- |
|
|
| 400 | Invalid request data |
|
|
| 401 | Invalid or expired token |
|
|
| 500 | Database error |
|