0 Fork 0

Files

T

John O'Keefe 6f13dc2b63 docs(media-items core): Beam WO5 batch 4 — 12 endpoints backfilled, registry pinned

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.

2026-10-24 16:09:38 -04:00

4.5 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
PUT	/api/media-items/:id/progress	jwt	media-items

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 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)

PUT /api/media-items/774641f9-317b-4087-8e04-53bb4392ae56/progress
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "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)

{
  "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.
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)

{
  "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, 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

4.5 KiB Raw Blame History