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.
This commit is contained in:
John O'Keefe committed
1 parent
ae9588f1c6
commit
6f13dc2b63
13 files changed
+486
-34
No files matched your search
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/media-items
|
||||
auth: jwt+admin
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:1375 MediaHandler.CreateMediaItem -->
|
||||
|
||||
# Create Media Item
|
||||
|
||||
Create a new media item (Admin only).
|
||||
@@ -47,7 +55,7 @@ Tags and contributors are automatically normalized:
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"title": "Example Book Title",
|
||||
@@ -67,7 +75,7 @@ Tags and contributors are automatically normalized:
|
||||
|
||||
## Response (201 Created)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440001",
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
@@ -80,13 +88,83 @@ Tags and contributors are automatically normalized:
|
||||
"mime_type": "application/epub+zip",
|
||||
"series": "Tech Series",
|
||||
"series_number": 1,
|
||||
"tags": ["Science-Fiction", "Technology", "ACME CORP."],
|
||||
"tags_search": ["science fiction", "technology", "acme corp"],
|
||||
"tags": [
|
||||
"Science-Fiction",
|
||||
"Technology",
|
||||
"ACME CORP."
|
||||
],
|
||||
"tags_search": [
|
||||
"science fiction",
|
||||
"technology",
|
||||
"acme corp"
|
||||
],
|
||||
"publisher": "O'Reilly Media",
|
||||
"contributors": ["John Smith", "ACME CORP."],
|
||||
"contributors_search": ["john smith", "acme corp"],
|
||||
"contributors": [
|
||||
"John Smith",
|
||||
"ACME CORP."
|
||||
],
|
||||
"contributors_search": [
|
||||
"john smith",
|
||||
"acme corp"
|
||||
],
|
||||
"created_at": "2026-01-31T10:00:00Z",
|
||||
"updated_at": "2026-01-31T10:00:00Z"
|
||||
"updated_at": "2026-01-31T10:00:00Z",
|
||||
"abridged": null,
|
||||
"added_by_admin_id": null,
|
||||
"age_rating": null,
|
||||
"alternate_info": null,
|
||||
"archived_at": null,
|
||||
"asin": null,
|
||||
"audio_metadata": null,
|
||||
"authors": null,
|
||||
"authors_search": null,
|
||||
"chapter_count": null,
|
||||
"chapter_metadata": null,
|
||||
"community_rating": null,
|
||||
"copyright_year": null,
|
||||
"cover_image_path": null,
|
||||
"date_published": null,
|
||||
"edition": null,
|
||||
"entitlement_id": null,
|
||||
"explicit": null,
|
||||
"file_sha256": null,
|
||||
"format_group": null,
|
||||
"format_mimetype": null,
|
||||
"genre": null,
|
||||
"goodreads_id": null,
|
||||
"google_books_id": null,
|
||||
"has_fixed_layout": null,
|
||||
"hash_confidence": null,
|
||||
"imported_at": null,
|
||||
"imprint": null,
|
||||
"is_black_and_white": null,
|
||||
"is_reflowable": null,
|
||||
"kobo_content_id": null,
|
||||
"kobo_metadata": null,
|
||||
"language": null,
|
||||
"library_type_name": null,
|
||||
"manga_type": null,
|
||||
"metadata_notes": null,
|
||||
"metadata_overrides": null,
|
||||
"missing_scan_count": null,
|
||||
"narrators": null,
|
||||
"narrators_search": null,
|
||||
"openlibrary_id": null,
|
||||
"opf_identifier": null,
|
||||
"opf_uuid": null,
|
||||
"page_count": null,
|
||||
"publishers": null,
|
||||
"publishers_search": null,
|
||||
"reading_direction": null,
|
||||
"revision_number": null,
|
||||
"scan_information": null,
|
||||
"series_count": null,
|
||||
"story_arc": null,
|
||||
"subtitle": null,
|
||||
"summary": null,
|
||||
"total_characters": null,
|
||||
"volume": null,
|
||||
"web_url": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: DELETE
|
||||
path: /api/media-items/:id
|
||||
auth: jwt+admin
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:1805 MediaHandler.DeleteMediaItem -->
|
||||
|
||||
# Delete Media Item
|
||||
|
||||
Delete a media item from the library (Admin only).
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/media-items/:id
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:896 MediaHandler.GetMediaItem -->
|
||||
|
||||
# Get Media Item
|
||||
|
||||
Retrieve details of a specific media item.
|
||||
@@ -26,7 +34,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"id": "uuid",
|
||||
"library_id": "uuid",
|
||||
@@ -39,15 +47,47 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
"cover_image_path": "/path/to/cover.jpg",
|
||||
"series": "Series Name",
|
||||
"series_number": 1,
|
||||
"tags": ["sci-fi", "space opera"],
|
||||
"tags_search": ["sci fi", "space opera"],
|
||||
"contributors": ["Author Name", "ACME CORP."],
|
||||
"contributors_search": ["author name", "acme corp"],
|
||||
"tags": [
|
||||
"sci-fi",
|
||||
"space opera"
|
||||
],
|
||||
"contributors": [
|
||||
"Author Name",
|
||||
"ACME CORP."
|
||||
],
|
||||
"language": "en",
|
||||
"page_count": 350,
|
||||
"genre": "Science Fiction",
|
||||
"copyright_year": 2023,
|
||||
"created_at": "2026-01-31T10:00:00Z"
|
||||
"created_at": "2026-01-31T10:00:00Z",
|
||||
"abridged": null,
|
||||
"age_rating": null,
|
||||
"alternate_info": null,
|
||||
"asin": null,
|
||||
"authors": null,
|
||||
"community_rating": null,
|
||||
"date_published": null,
|
||||
"edition": null,
|
||||
"explicit": null,
|
||||
"format_group": null,
|
||||
"format_mimetype": null,
|
||||
"imprint": null,
|
||||
"is_black_and_white": null,
|
||||
"isbn": null,
|
||||
"library_type_name": null,
|
||||
"manga_type": null,
|
||||
"metadata_notes": null,
|
||||
"narrators": null,
|
||||
"publisher": null,
|
||||
"publishers": null,
|
||||
"reading_direction": null,
|
||||
"scan_information": null,
|
||||
"series_count": null,
|
||||
"story_arc": null,
|
||||
"subtitle": null,
|
||||
"summary": null,
|
||||
"updated_at": null,
|
||||
"volume": null,
|
||||
"web_url": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/media-items
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:757 MediaHandler.ListMediaItems -->
|
||||
|
||||
# List Media Items
|
||||
|
||||
Retrieve a paginated list of media items, scoped to a library or across all libraries.
|
||||
@@ -41,7 +49,7 @@ The response body is `{"data": [...]}` in both modes. The item shape differs by
|
||||
|
||||
Nullable columns serialize as `null`.
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
|
||||
@@ -1,4 +1,12 @@
|
||||
# Search Media Items (Unified)
|
||||
---
|
||||
method: GET
|
||||
path: /api/media-items/search
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:2333 MediaHandler.SearchMediaItems -->
|
||||
|
||||
# Search Media Items (Unified):<|end|><|start|>edit to=assistant<|channel|>analysis<|message|>Edited docs/developer/api/media-items/create_media_item.md (1 replacement)<|end|><|start|>edit to=assistant<|channel|>analysis<|message|>Edited docs/developer/api/media-items/update_media_item.md (1 replacement)<|end|><|start|>edit to=assistant<|channel|>analysis<|channel|>Edited docs/developer/api/media-items/delete_media_item.md (1 replacement)<|end|><|start|>edit to=assistant<|channel|>analysis<|message|>Edited docs/developer/api/media-items/search_media_items.md (1 replacement)
|
||||
|
||||
Search and filter media items with fuzzy matching support.
|
||||
|
||||
@@ -142,15 +150,88 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
## Response (200 OK)
|
||||
|
||||
**Media items search:**
|
||||
```json
|
||||
```json example-response
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Foundation",
|
||||
"author": "Isaac Asimov",
|
||||
"tags": ["Science Fiction", "Adventure"],
|
||||
"tags": [
|
||||
"Science Fiction",
|
||||
"Adventure"
|
||||
],
|
||||
"library_id": "uuid",
|
||||
"library_name": "E-Books"
|
||||
"library_name": "E-Books",
|
||||
"abridged": null,
|
||||
"added_by_admin_id": null,
|
||||
"age_rating": null,
|
||||
"alternate_info": null,
|
||||
"archived_at": null,
|
||||
"asin": null,
|
||||
"audio_metadata": null,
|
||||
"authors": null,
|
||||
"authors_search": null,
|
||||
"chapter_count": null,
|
||||
"chapter_metadata": null,
|
||||
"community_rating": null,
|
||||
"contributors": null,
|
||||
"contributors_search": null,
|
||||
"copyright_year": null,
|
||||
"cover_image_path": null,
|
||||
"created_at": null,
|
||||
"date_published": null,
|
||||
"description": null,
|
||||
"edition": null,
|
||||
"entitlement_id": null,
|
||||
"explicit": null,
|
||||
"file_path": null,
|
||||
"file_sha256": null,
|
||||
"file_size": null,
|
||||
"format_group": null,
|
||||
"format_mimetype": null,
|
||||
"genre": null,
|
||||
"goodreads_id": null,
|
||||
"google_books_id": null,
|
||||
"has_fixed_layout": null,
|
||||
"hash_confidence": null,
|
||||
"imported_at": null,
|
||||
"imprint": null,
|
||||
"is_black_and_white": null,
|
||||
"is_reflowable": null,
|
||||
"isbn": null,
|
||||
"kobo_content_id": null,
|
||||
"kobo_metadata": null,
|
||||
"language": null,
|
||||
"library_type_name": null,
|
||||
"library_type_name_2": null,
|
||||
"manga_type": null,
|
||||
"metadata_notes": null,
|
||||
"metadata_overrides": null,
|
||||
"mime_type": null,
|
||||
"missing_scan_count": null,
|
||||
"narrators": null,
|
||||
"narrators_search": null,
|
||||
"openlibrary_id": null,
|
||||
"opf_identifier": null,
|
||||
"opf_uuid": null,
|
||||
"page_count": null,
|
||||
"publisher": null,
|
||||
"publishers": null,
|
||||
"publishers_search": null,
|
||||
"reading_direction": null,
|
||||
"revision_number": null,
|
||||
"scan_information": null,
|
||||
"series": null,
|
||||
"series_count": null,
|
||||
"series_number": null,
|
||||
"story_arc": null,
|
||||
"subtitle": null,
|
||||
"summary": null,
|
||||
"tags_search": null,
|
||||
"total_characters": null,
|
||||
"updated_at": null,
|
||||
"volume": null,
|
||||
"web_url": null
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: PUT
|
||||
path: /api/media-items/:id
|
||||
auth: jwt+admin
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:1492 MediaHandler.UpdateMediaItem -->
|
||||
|
||||
# Update Media Item
|
||||
|
||||
Update media item metadata (Admin only).
|
||||
@@ -33,7 +41,7 @@ Update media item metadata (Admin only).
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"title": "Updated Title",
|
||||
"author": "Updated Author",
|
||||
@@ -45,7 +53,7 @@ Update media item metadata (Admin only).
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Updated Title",
|
||||
@@ -53,7 +61,74 @@ Update media item metadata (Admin only).
|
||||
"description": "Updated description",
|
||||
"series": "Series",
|
||||
"series_number": 2,
|
||||
"updated_at": "2026-01-31T10:00:00Z"
|
||||
"updated_at": "2026-01-31T10:00:00Z",
|
||||
"abridged": null,
|
||||
"added_by_admin_id": null,
|
||||
"age_rating": null,
|
||||
"alternate_info": null,
|
||||
"archived_at": null,
|
||||
"asin": null,
|
||||
"audio_metadata": null,
|
||||
"authors": null,
|
||||
"authors_search": null,
|
||||
"chapter_count": null,
|
||||
"chapter_metadata": null,
|
||||
"community_rating": null,
|
||||
"contributors": null,
|
||||
"contributors_search": null,
|
||||
"copyright_year": null,
|
||||
"cover_image_path": null,
|
||||
"created_at": null,
|
||||
"date_published": null,
|
||||
"edition": null,
|
||||
"entitlement_id": null,
|
||||
"explicit": null,
|
||||
"file_path": null,
|
||||
"file_sha256": null,
|
||||
"file_size": null,
|
||||
"format_group": null,
|
||||
"format_mimetype": null,
|
||||
"genre": null,
|
||||
"goodreads_id": null,
|
||||
"google_books_id": null,
|
||||
"has_fixed_layout": null,
|
||||
"hash_confidence": null,
|
||||
"imported_at": null,
|
||||
"imprint": null,
|
||||
"is_black_and_white": null,
|
||||
"is_reflowable": null,
|
||||
"isbn": null,
|
||||
"kobo_content_id": null,
|
||||
"kobo_metadata": null,
|
||||
"language": null,
|
||||
"library_id": null,
|
||||
"library_type_name": null,
|
||||
"manga_type": null,
|
||||
"metadata_notes": null,
|
||||
"metadata_overrides": null,
|
||||
"mime_type": null,
|
||||
"missing_scan_count": null,
|
||||
"narrators": null,
|
||||
"narrators_search": null,
|
||||
"openlibrary_id": null,
|
||||
"opf_identifier": null,
|
||||
"opf_uuid": null,
|
||||
"page_count": null,
|
||||
"publisher": null,
|
||||
"publishers": null,
|
||||
"publishers_search": null,
|
||||
"reading_direction": null,
|
||||
"revision_number": null,
|
||||
"scan_information": null,
|
||||
"series_count": null,
|
||||
"story_arc": null,
|
||||
"subtitle": null,
|
||||
"summary": null,
|
||||
"tags": null,
|
||||
"tags_search": null,
|
||||
"total_characters": null,
|
||||
"volume": null,
|
||||
"web_url": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user