docs(media-items,collections,koreader,admin): Beam batch 11 — final backfill
All remaining endpoint docs frontmatter'd: media-item bulk ops + audio surface, collections book-listing/preview, koreader rating/review/stats plugin protocol, hash-conflicts JSON list. Scope call (Claude): resolve_hash_conflict.md DELETED — the resolve POST renders an htmx fragment (renderResolved), a web-admin flow under rule 3; only the GET list is a JSON API. update_media_review skipped by Beam (correct): ratings/upsert_media_review.md already covers the PUT. Registry: 16 entries. koreader rating/review/stats all bind koreaderBookRef (query or body) — odd=half-star rating scale; audio track endpoint serves raw bytes (ServeContent, Range) — response nil. Fixed drift: deleted_annotations doc's secondary restore/purge fences unlabeled (gate validates labeled blocks against the ONE frontmatter route); chapters example labeled. UNVERIFIED: 1 (koreader book-ref fields, push_stats). make test 9/9.
This commit is contained in:
John O'Keefe committed
1 parent
18084de7a6
commit
e21e1facde
17 files changed
+515
-6
No files matched your search
@@ -0,0 +1,52 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/admin/hash-conflicts
|
||||
auth: jwt+admin
|
||||
area: admin
|
||||
---
|
||||
<!-- source: internal/handlers/hash_conflicts.go:69 HashConflictsHandler.ListHashConflicts -->
|
||||
|
||||
# Hash Conflicts (API)
|
||||
|
||||
Lists pending content-duplicate groups (same library + SHA-256 at different
|
||||
paths) with per-item usage counts.
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"conflicts": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"library_id": "uuid",
|
||||
"library_name": "Manga",
|
||||
"sha256": "abc123...",
|
||||
"created_at": "2026-10-24T13:57:01Z",
|
||||
"items": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Book Title",
|
||||
"author": "Author",
|
||||
"file_path": "/path/to/book.epub",
|
||||
"file_size": 12345,
|
||||
"created_at": "2026-10-24T13:57:01Z",
|
||||
"progress_count": 0,
|
||||
"highlight_count": 0,
|
||||
"bookmark_count": 0,
|
||||
"note_count": 0,
|
||||
"collection_count": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
| Status | Body | When |
|
||||
| ------ | ---- | ---- |
|
||||
| 401 | `{"error": "unauthorized"}` | no/invalid JWT |
|
||||
| 403 | `{"error": "admin access required"}` | non-admin |
|
||||
| 500 | `{"error": "failed to list hash conflicts"}` | unexpected server error |
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/collections/bulk-add-books
|
||||
auth: jwt
|
||||
area: collections
|
||||
---
|
||||
<!-- source: internal/handlers/collections.go:1133 CollectionHandler.HandleBulkAddBooks -->
|
||||
|
||||
# Bulk Add Books
|
||||
|
||||
Adds books to multiple collections in one request.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"operations": [
|
||||
{
|
||||
"collection_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"book_ids": [
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"results": [],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
| ----- | ---- | -------- | ----- |
|
||||
| operations | array | Yes | List of {collection_id, book_ids} |
|
||||
| operations[].collection_id | string (uuid) | Yes | Target collection |
|
||||
| operations[].book_ids | array of string (uuid) | Yes | Books to add |
|
||||
|
||||
## Errors
|
||||
|
||||
| Status | Body | When |
|
||||
| ------ | ---- | ---- |
|
||||
| 400 | `{"error": "Invalid request"}` / `{"error": "operations required"}` | malformed |
|
||||
| 400 | `{"error": "smart collections are rule-based..."}` | smart collection |
|
||||
| 500 | `{"error": "..."}` | unexpected server error |
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/collections/:id/books/bulk-remove
|
||||
auth: jwt
|
||||
area: collections
|
||||
---
|
||||
<!-- source: internal/handlers/collections.go:601 CollectionHandler.BulkRemoveBooks -->
|
||||
|
||||
# Bulk Remove Books
|
||||
|
||||
Removes multiple books from a collection at once.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"book_ids": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"removed": 2,
|
||||
"total": 2
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
| ----- | ---- | -------- | ----- |
|
||||
| book_ids | array of string (uuid) | Yes | Book ids to remove |
|
||||
|
||||
## Errors
|
||||
|
||||
| Status | Body | When |
|
||||
| ------ | ---- | ---- |
|
||||
| 400 | `{"error": "invalid collection id"}` / `{"error": "invalid request"}` | malformed |
|
||||
| 400 | `{"error": "smart collections are rule-based..."}` | smart collection |
|
||||
| 500 | `{"error": "..."}` | unexpected server error |
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: DELETE
|
||||
path: /api/devices/:id/collections/:collectionId
|
||||
auth: jwt
|
||||
area: collections
|
||||
---
|
||||
<!-- source: internal/handlers/collections.go:760 CollectionHandler.DeleteDeviceMapping -->
|
||||
|
||||
# Delete Shelf Mapping
|
||||
|
||||
Remove a collection-to-shelf mapping for a device.
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/collections/:id/books
|
||||
auth: jwt
|
||||
area: collections
|
||||
---
|
||||
<!-- source: internal/handlers/collections.go:774 CollectionHandler.GetBookCollections -->
|
||||
|
||||
# Get Book Collections
|
||||
|
||||
Returns the collections a given book belongs to.
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"book_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"collections": [
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "To Read",
|
||||
"description": "Books I want to read soon",
|
||||
"color": "#00FF00",
|
||||
"icon": "📖"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
| Status | Body | When |
|
||||
| ------ | ---- | ---- |
|
||||
| 400 | `{"error": "invalid book id"}` | malformed id |
|
||||
| 500 | `{"error": "..."}` | unexpected server error |
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/collections/preview
|
||||
auth: jwt
|
||||
area: collections
|
||||
---
|
||||
<!-- source: internal/handlers/collections.go:1241 CollectionHandler.PreviewCollection -->
|
||||
|
||||
# Preview Collection
|
||||
|
||||
Previews which books would match a set of rules without saving.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"rules": [],
|
||||
"manual_book_ids": [],
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"items": []
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
| ----- | ---- | -------- | ----- |
|
||||
| library_id | string (uuid) | Yes | Library to preview against |
|
||||
| rules | array | No | Rule objects |
|
||||
| manual_book_ids | array of string (uuid) | No | Manually included books |
|
||||
| limit | int | No | Max items (default 20) |
|
||||
|
||||
## Errors
|
||||
|
||||
| Status | Body | When |
|
||||
| ------ | ---- | ---- |
|
||||
| 400 | `{"error": "Invalid request"}` / `{"error": "invalid library_id"}` / `{"error": "library not found"}` | malformed |
|
||||
| 500 | `{"error": "..."}` | unexpected server error |
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/sync/koreader/rating
|
||||
auth: device-token
|
||||
area: koreader
|
||||
---
|
||||
<!-- source: internal/handlers/koreader.go:1715 KOReaderHandler.GetKOReaderRating -->
|
||||
|
||||
# Get KOReader Rating
|
||||
|
||||
Returns the stored rating for a book (koreader device-token auth).
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"rating": 8
|
||||
}
|
||||
```
|
||||
|
||||
When unrated, `rating` is `null`.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/sync/koreader/review
|
||||
auth: device-token
|
||||
area: koreader
|
||||
---
|
||||
<!-- source: internal/handlers/koreader.go:1783 KOReaderHandler.GetKOReaderReview -->
|
||||
|
||||
# Get KOReader Review
|
||||
|
||||
Returns the raw markdown review for a book.
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"review": "A slow start, but the second act earns it."
|
||||
}
|
||||
```
|
||||
|
||||
When no review exists, `review` is `null`.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/sync/koreader/stats
|
||||
auth: device-token
|
||||
area: koreader
|
||||
---
|
||||
<!-- source: internal/handlers/koreader.go:1854 KOReaderHandler.PushKOReaderStats -->
|
||||
|
||||
# Push KOReader Stats
|
||||
|
||||
Pushes cumulative reading seconds for a book; only the delta above the
|
||||
stored watermark becomes a reading_history session.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"total_seconds": 3600
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"total_seconds": 3600,
|
||||
"watermark": 0,
|
||||
"delta_seconds": 3600,
|
||||
"session_recorded": true,
|
||||
"session_seconds": 3600
|
||||
}
|
||||
```
|
||||
|
||||
UNVERIFIED: the request body also carries the koreader book reference fields (md5, title, etc.) used to resolve the book; field set not copied here.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/sync/koreader/rating
|
||||
auth: device-token
|
||||
area: koreader
|
||||
---
|
||||
<!-- source: internal/handlers/koreader.go:1740 KOReaderHandler.SetKOReaderRating -->
|
||||
|
||||
# Set KOReader Rating
|
||||
|
||||
Sets (or clears, when rating is 0) the rating for a book.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"rating": 8
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"rating": 8
|
||||
}
|
||||
```
|
||||
|
||||
A rating of 0 clears the stored rating and returns `{"rating": null}`.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/sync/koreader/review
|
||||
auth: device-token
|
||||
area: koreader
|
||||
---
|
||||
<!-- source: internal/handlers/koreader.go:1808 KOReaderHandler.SetKOReaderReview -->
|
||||
|
||||
# Set KOReader Review
|
||||
|
||||
Sets (or clears, when empty) the review for a book.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"review": "A slow start, but the second act earns it."
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"review": "A slow start, but the second act earns it."
|
||||
}
|
||||
```
|
||||
|
||||
An empty review clears the stored review and returns `{"review": null}`.
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/media-items/bulk-delete
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:448 MediaHandler.HandleBulkDelete -->
|
||||
|
||||
# Bulk Delete Media Items
|
||||
|
||||
Delete multiple media items at once (supports ebooks, comics, manga).
|
||||
@@ -14,7 +22,7 @@ Delete multiple media items at once (supports ebooks, comics, manga).
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"media_item_ids": [
|
||||
"550e8400-e29b-41d4-a716-446655440001",
|
||||
@@ -26,7 +34,7 @@ Delete multiple media items at once (supports ebooks, comics, manga).
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/media-items/bulk-update
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:540 MediaHandler.HandleBulkUpdate -->
|
||||
|
||||
# Bulk Update Media Items
|
||||
|
||||
Update multiple media items at once (supports ebooks, comics, manga).
|
||||
@@ -26,7 +34,7 @@ Update multiple media items at once (supports ebooks, comics, manga).
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"media_item_updates": [
|
||||
{
|
||||
@@ -50,7 +58,7 @@ Update multiple media items at once (supports ebooks, comics, manga).
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/media-items/:id/annotations/deleted
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/annotation_history.go:61 MediaHandler.GetDeletedAnnotations -->
|
||||
|
||||
# Deleted Annotations History
|
||||
|
||||
List, restore, or permanently delete tombstoned annotations (highlights,
|
||||
@@ -18,7 +26,7 @@ Returns tombstoned annotations for the book, newest deletion first.
|
||||
|
||||
### Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"deleted_annotations": [
|
||||
{
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/media-items/:id/chapters
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:2947 MediaHandler.GetAudioChapters -->
|
||||
|
||||
# Get Audio Chapters
|
||||
|
||||
The format-abstraction chapter list for audiobooks, sourced from
|
||||
@@ -11,7 +19,7 @@ which file model produced them.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"media_item_id": "…",
|
||||
"chapters": [
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/media-items/:id/audio/:trackIndex
|
||||
auth: jwt
|
||||
area: media-items
|
||||
---
|
||||
<!-- source: internal/handlers/media.go:3088 MediaHandler.GetAudioTrack -->
|
||||
|
||||
# Get Audio Track
|
||||
|
||||
Streams one playable track of a multi-file audiobook (folder-of-tracks
|
||||
|
||||
Reference in new issue
Block a user