docs(book-matching,collections): Beam batch 10 — 15 endpoints
WO3 sync internals resolved: the book-matching docs ARE the sync surface
(books/query, link-book, bulk/auto-link, unlinked-books, suggestions,
file-alias CRUD) + collections rule/test/bulk-assign/shelf-mapping
surface.
Dedupe resolved (Claude call): search_books.md declared
GET /api/books/match but its BODY documents POST /api/sync/books/query —
both routes exist and are distinct (query-param device protocol vs JSON
body plugin protocol). Repointed search_books.md frontmatter to the POST
route; get_book_matches.md keeps the GET.
Claude registry: 15 entries (one pre-existing link-book entry deduped).
Drift fixed by gate: auto-link request {confidence_threshold, limit} not
{device_id, threshold}; bulk-link link objects {unlinked_book_id,
media_item_id, confidence_score} not {device_id, book_id, ...};
responses {results,total,successful,failed}/{auto_linked,results}; added
missing example-responses (bare delete, remove-rule is_smart-after
semantics, bulk-assign per-book results). make test 9/9.
This commit is contained in:
John O'Keefe committed
1 parent
7a7b2ab82a
commit
18084de7a6
16 files changed
+334
-72
No files matched your search
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/sync/auto-link-books
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/book_matching.go:316 Handler.AutoLinkBooks -->
|
||||
|
||||
# Auto Link Books
|
||||
|
||||
Automatically link books to media items based on matching metadata.
|
||||
@@ -15,27 +23,19 @@ Automatically link books to media items based on matching metadata.
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"threshold": 0.8
|
||||
"confidence_threshold": 0.8,
|
||||
"limit": 100
|
||||
}
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"message": "Auto-link completed",
|
||||
"linked_count": 15,
|
||||
"unmatched_count": 5,
|
||||
"links": [
|
||||
{
|
||||
"book_id": "book-123",
|
||||
"media_item_id": "uuid",
|
||||
"confidence": 0.95
|
||||
}
|
||||
]
|
||||
"auto_linked": null,
|
||||
"results": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/sync/bulk-link-books
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/book_matching.go:238 Handler.BulkLinkBooks -->
|
||||
|
||||
# Bulk Link Books
|
||||
|
||||
Link multiple books to media items at once.
|
||||
@@ -21,18 +29,18 @@ Each link object contains:
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"links": [
|
||||
{
|
||||
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"book_id": "book-123",
|
||||
"media_item_id": "660e8400-e29b-41d4-a716-446655440001"
|
||||
"unlinked_book_id": "770e8400-e29b-41d4-a716-446655440002",
|
||||
"media_item_id": "660e8400-e29b-41d4-a716-446655440001",
|
||||
"confidence_score": 0.95
|
||||
},
|
||||
{
|
||||
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"book_id": "book-456",
|
||||
"media_item_id": "770e8400-e29b-41d4-a716-446655440002"
|
||||
"unlinked_book_id": "880e8400-e29b-41d4-a716-446655440003",
|
||||
"media_item_id": "990e8400-e29b-41d4-a716-446655440004",
|
||||
"confidence_score": 0.87
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -40,11 +48,12 @@ Each link object contains:
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"message": "Books linked successfully",
|
||||
"linked_count": 2,
|
||||
"failed_count": 0
|
||||
"failed": null,
|
||||
"results": null,
|
||||
"successful": null,
|
||||
"total": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/devices/:id/file-aliases
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:166 MatchingHandler.CreateDeviceFileAlias -->
|
||||
|
||||
# Create Device File Alias
|
||||
|
||||
Create a new file alias for a device.
|
||||
@@ -22,7 +30,7 @@ Create a new file alias for a device.
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"media_item_id": "550e8400-e29b-41d4-a716-446655440001",
|
||||
"file_name": "book.epub",
|
||||
@@ -32,14 +40,15 @@ Create a new file alias for a device.
|
||||
|
||||
## Response (201 Created)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"id": "uuid",
|
||||
"device_id": "device-uuid",
|
||||
"media_item_id": "book-uuid",
|
||||
"file_name": "book.epub",
|
||||
"file_hash": "abc123...",
|
||||
"created_at": "2026-02-08T10:00:00Z"
|
||||
"confidence_score": null,
|
||||
"file_path": null,
|
||||
"file_sha256": null,
|
||||
"last_seen_at": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: DELETE
|
||||
path: /api/devices/:id/file-aliases/:aliasId
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:287 MatchingHandler.DeleteDeviceFileAlias -->
|
||||
|
||||
# Delete Device File Alias
|
||||
|
||||
Delete a device file alias.
|
||||
@@ -29,6 +37,12 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
File alias deleted successfully.
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"message": "File alias deleted successfully"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/devices/:id/file-aliases
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:121 MatchingHandler.GetDeviceFileAliases -->
|
||||
|
||||
# Get Device File Aliases
|
||||
|
||||
Get all file aliases for a specific device.
|
||||
@@ -26,7 +34,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"aliases": [
|
||||
{
|
||||
@@ -38,7 +46,8 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
"created_at": "2026-02-08T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 23
|
||||
"total": 23,
|
||||
"device_id": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/sync/unlinked-books/:id/suggestions
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/book_matching.go:392 Handler.GetUnlinkedBookSuggestions -->
|
||||
|
||||
# Get Unlinked Book Suggestions
|
||||
|
||||
Get suggested matches for unlinked books on a device.
|
||||
@@ -33,7 +41,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"suggestions": [
|
||||
{
|
||||
@@ -44,18 +52,27 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
{
|
||||
"media_item_id": "uuid",
|
||||
"title": "Foundation",
|
||||
"authors": ["Isaac Asimov"],
|
||||
"authors": [
|
||||
"Isaac Asimov"
|
||||
],
|
||||
"confidence": 0.95
|
||||
},
|
||||
{
|
||||
"media_item_id": "uuid-2",
|
||||
"title": "Foundation and Empire",
|
||||
"authors": ["Isaac Asimov"],
|
||||
"authors": [
|
||||
"Isaac Asimov"
|
||||
],
|
||||
"confidence": 0.75
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
],
|
||||
"action": null,
|
||||
"sha256": null,
|
||||
"title_from_device": null,
|
||||
"total_suggestions": null,
|
||||
"unlinked_book_id": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: GET
|
||||
path: /api/devices/:deviceId/sync/unlinked-books
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:96 MatchingHandler.GetUnlinkedBooks -->
|
||||
|
||||
# Get Unlinked Books
|
||||
|
||||
Get all books that haven't been linked to media items yet for a specific device.
|
||||
@@ -33,20 +41,10 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"file_name": "book.epub",
|
||||
"file_path": "/path/to/book.epub",
|
||||
"size_bytes": 1234567,
|
||||
"modified_at": "2026-02-08T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 15,
|
||||
"limit": 10,
|
||||
"offset": 0
|
||||
"unlinked": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,7 +1,45 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/devices/:deviceId/sync/link-book
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:57 MatchingHandler.LinkBook -->
|
||||
|
||||
# Link Book
|
||||
|
||||
Link a device book to a Bookhoard media item. Supports bulk linking.
|
||||
|
||||
## Example request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"device_file": {
|
||||
"file_path": "/books/hobbit.epub",
|
||||
"sha256": "abc123...",
|
||||
"title": "The Hobbit"
|
||||
},
|
||||
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"confidence_score": 1.0
|
||||
}
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"status": "linked",
|
||||
"device_file_alias": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"file_path": "/books/hobbit.epub",
|
||||
"file_sha256": "abc123...",
|
||||
"confidence_score": 1.0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Endpoint**: `POST /api/sync/bulk-link-books` or `POST /api/sync/auto-link-books`
|
||||
**Auth**: Required
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/sync/books/query
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:309 MatchingHandler.GetBookMatches -->
|
||||
|
||||
# Search Books for Matching
|
||||
|
||||
Query books to find potential matches for linking.
|
||||
@@ -18,7 +26,7 @@ Query books to find potential matches for linking.
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"identifiers": ["isbn:978-0345391802", "uuid:abc-123"],
|
||||
"sha256": "a1b2c3d4e5f6abc123...",
|
||||
@@ -30,7 +38,7 @@ Query books to find potential matches for linking.
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"matches": [
|
||||
{
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
method: PUT
|
||||
path: /api/devices/:id/file-aliases/:aliasId
|
||||
auth: jwt
|
||||
area: book-matching
|
||||
---
|
||||
<!-- source: internal/handlers/matching.go:221 MatchingHandler.UpdateDeviceFileAlias -->
|
||||
|
||||
# Update Device File Alias
|
||||
|
||||
Update an existing device file alias.
|
||||
@@ -22,7 +30,7 @@ Update an existing device file alias.
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
```json example-request
|
||||
{
|
||||
"file_name": "updated-book.epub",
|
||||
"file_hash": "newhash123..."
|
||||
@@ -31,14 +39,14 @@ Update an existing device file alias.
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
```json example-response
|
||||
{
|
||||
"id": "uuid",
|
||||
"device_id": "device-uuid",
|
||||
"media_item_id": "book-uuid",
|
||||
"file_name": "updated-book.epub",
|
||||
"file_hash": "newhash123...",
|
||||
"updated_at": "2026-02-08T11:00:00Z"
|
||||
"confidence_score": null,
|
||||
"file_path": null,
|
||||
"file_sha256": null,
|
||||
"last_seen_at": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user