Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 52 Wiki Activity

docs(conflicts,queue): Beam WO5 batch — 13 endpoints backfilled, registry pinned

Browse Source 
Beam added frontmatter + provenance + labeled examples to the 7 conflict and
6 queue docs, fixing real field drift on the way (resolve response keys,
bulk result shape, dismiss-all deleted count, queue stats counts).

Claude registry verification found TWO Beam catches of Claude's own draft:
- queue routes use :device_id / :item_id params (registry first draft said :id)
- resolve_conflict DOES take a body (ConflictResolutionRequest) — registry
  first draft said nil
Both fixed; gate then surfaced one real Beam defect: example-request used a
nonexistent "resolution" field in resolve + bulk-resolve (real contract:
winner=<source|manual> with required manual_data for manual; strategy=
most_recent|highest_progress|manual). Fixed in the docs.

Pinned by type: ConflictListResponse, ConflictDetailResponse,
ConflictResolveResponse, BulkResolveRequest/Response, QueueStatsResponse,
ConflictResolutionRequest. dismiss-all deleted is an int count.
This commit is contained in:
John O'Keefe committed 2026-10-24 15:37:45 -04:00
1 parent fa00d6d3cb
commit eacc33bfac
14 files changed
+224 -98
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/developer/api/conflicts/bulk_dismiss_conflicts.md
+14 -4
View File
@@ -1,3 +1,11 @@
---
method: POST
path: /api/conflicts/bulk-dismiss
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:789 ConflictHandler.BulkDismissConflicts -->
# Bulk Dismiss Conflicts
Dismiss multiple conflicts at once.
@@ -14,7 +22,7 @@ Dismiss multiple conflicts at once.
### Example Request
```json
```json example-request
{
"conflict_ids": [
"550e8400-e29b-41d4-a716-446655440000",
@@ -25,10 +33,12 @@ Dismiss multiple conflicts at once.
## Response (200 OK)
```json
```json example-response
{
"message": "Conflicts dismissed successfully",
"dismissed_count": 2
"results": [],
"total": 2,
"success": 2,
"failed": 0
}
```
docs/developer/api/conflicts/bulk_resolve_conflicts.md
+15 -6
View File
@@ -1,3 +1,11 @@
---
method: POST
path: /api/conflicts/bulk-resolve
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:594 ConflictHandler.BulkResolveConflicts -->
# Bulk Resolve Conflicts
Resolve multiple conflicts at once using a specified strategy.
@@ -15,23 +23,24 @@ Resolve multiple conflicts at once using a specified strategy.
### Example Request
```json
```json example-request
{
"conflict_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
],
"resolution": "highest_progress"
"strategy": "highest_progress"
}
```
## Response (200 OK)
```json
```json example-response
{
"message": "Conflicts resolved successfully",
"resolved_count": 2,
"failed_count": 0
"results": [],
"total": 2,
"success": 2,
"failed": 0
}
```
docs/developer/api/conflicts/delete_conflict.md
+8
View File
@@ -1,3 +1,11 @@
---
method: DELETE
path: /api/conflicts/:id
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:524 ConflictHandler.DeleteConflict -->
# Delete Conflict
Delete a specific conflict record.
docs/developer/api/conflicts/dismiss_all_resolved.md
+10 -3
View File
@@ -1,3 +1,11 @@
---
method: POST
path: /api/conflicts/dismiss-all
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:552 ConflictHandler.DismissAllResolved -->
# Dismiss All Resolved
Dismiss all resolved conflicts.
@@ -20,10 +28,9 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"message": "All resolved conflicts dismissed",
"count": 15
"deleted": 15
}
```
docs/developer/api/conflicts/get_conflict.md
+14 -35
View File
@@ -1,3 +1,11 @@
---
method: GET
path: /api/conflicts/:id
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:169 ConflictHandler.GetConflict -->
# Get Conflict Details
Get detailed information about a specific conflict.
@@ -26,43 +34,14 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"id": "uuid",
"media_item": {
"id": "book-uuid",
"title": "Sample Book",
"authors": ["Author Name"]
},
"device_progress": {
"device_id": "device-uuid",
"device_name": "My Kobo",
"percentage": 75,
"position": 1234,
"page": 150,
"updated_at": "2026-02-08T10:00:00Z"
},
"server_progress": {
"percentage": 50,
"position": 800,
"page": 100,
"updated_at": "2026-02-08T09:00:00Z"
},
"device_bookmarks": [
{
"position": 1234,
"text": "Interesting passage",
"created_at": "2026-02-08T10:00:00Z"
}
],
"server_bookmarks": [
{
"position": 800,
"text": "Another passage",
"created_at": "2026-02-07T15:00:00Z"
}
],
"status": "active",
"media_item_id": "book-uuid",
"media_item_title": "Sample Book",
"conflict_type": "progress",
"conflict_data": {},
"resolution_status": "unresolved",
"created_at": "2026-02-08T10:00:00Z"
}
```
docs/developer/api/conflicts/list_conflicts.md
+13 -16
View File
@@ -1,3 +1,11 @@
---
method: GET
path: /api/conflicts
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:156 ConflictHandler.ListConflicts -->
# List Conflicts
List all sync conflicts for the current user.
@@ -29,32 +37,21 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"conflicts": [
{
"id": "uuid",
"media_item_id": "book-uuid",
"media_item_title": "Sample Book",
"device_progress": {
"device_id": "device-uuid",
"device_name": "My Kobo",
"percentage": 75,
"position": 1234,
"updated_at": "2026-02-08T10:00:00Z"
},
"server_progress": {
"percentage": 50,
"position": 800,
"updated_at": "2026-02-08T09:00:00Z"
},
"status": "active",
"conflict_type": "progress",
"conflict_data": {},
"resolution_status": "unresolved",
"created_at": "2026-02-08T10:00:00Z"
}
],
"total": 5,
"limit": 10,
"offset": 0
"unresolved": 5
}
```
docs/developer/api/conflicts/resolve_conflict.md
+17 -6
View File
@@ -1,3 +1,11 @@
---
method: POST
path: /api/conflicts/:id/resolve
auth: jwt
area: conflicts
---
<!-- source: internal/handlers/conflicts.go:208 ConflictHandler.ResolveConflict -->
# Resolve Conflict
Resolve a specific conflict by choosing which version to keep.
@@ -20,19 +28,22 @@ Resolve a specific conflict by choosing which version to keep.
### Example Request
```json
```json example-request
{
"resolution": "device"
"winner": "kobo"
}
```
`winner` is one of the conflict's source keys (e.g. `"kobo"`, `"koreader"`,
`"web"`) or `"manual"` — the latter requires `manual_data`.
## Response (200 OK)
```json
```json example-response
{
"message": "Conflict resolved successfully",
"conflict_id": "uuid",
"resolution": "device"
"conflict_resolved": true,
"applied_to": {},
"devices_synced": []
}
```
docs/developer/api/queue/clear_device_queue.md
+14 -2
View File
@@ -1,3 +1,11 @@
---
method: DELETE
path: /api/queue/devices/:device_id/clear
auth: jwt
area: queue
---
<!-- source: internal/handlers/queue.go:291 QueueHandler.ClearDeviceQueue -->
# Clear Device Queue
Clear all queue items for a specific device.
@@ -24,9 +32,13 @@ DELETE /api/queue/devices/550e8400-e29b-41d4-a716-446655440000/clear
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (204 No Content)
## Response (200 OK)
Device queue cleared successfully.
```json example-response
{
"message": "queue cleared"
}
```
## Error Responses
docs/developer/api/queue/delete_queue_item.md
+8
View File
@@ -1,3 +1,11 @@
---
method: DELETE
path: /api/queue/items/:item_id
auth: jwt
area: queue
---
<!-- source: internal/handlers/queue.go:261 QueueHandler.DeleteQueueItem -->
# Delete Queue Item
Delete a specific queue item.
docs/developer/api/queue/get_device_queue_stats.md
+14 -6
View File
@@ -1,3 +1,11 @@
---
method: GET
path: /api/queue/devices/:device_id/stats
auth: jwt
area: queue
---
<!-- source: internal/handlers/queue.go:58 QueueHandler.GetDeviceQueueStats -->
# Get Device Queue Statistics
Get statistics for a specific device's sync queue.
@@ -26,13 +34,13 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"total_items": 15,
"pending_items": 8,
"processing_items": 2,
"completed_items": 4,
"failed_items": 1
"pending_count": 8,
"processing_count": 2,
"failed_count": 1,
"completed_count": 4,
"total_count": 15
}
```
docs/developer/api/queue/list_all_queue_items.md
+17 -9
View File
@@ -1,3 +1,11 @@
---
method: GET
path: /api/queue/items
auth: jwt+admin
area: queue
---
<!-- source: internal/handlers/queue.go:208 QueueHandler.ListAllQueueItems -->
# List All Queue Items (Admin)
List all queue items across all devices (admin only).
@@ -29,24 +37,24 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"items": [
{
"id": "uuid",
"device_id": "device-uuid",
"device_name": "My Kobo",
"media_item_id": "book-uuid",
"operation": "sync_progress",
"device_type": "kobo",
"user_email": "user@example.com",
"sync_type": "sync_progress",
"priority": 0,
"attempts": 0,
"max_attempts": 0,
"status": "failed",
"error_message": "Connection timeout",
"created_at": "2026-02-08T10:00:00Z",
"updated_at": "2026-02-08T10:05:00Z"
"created_at": "2026-02-08T10:00:00Z"
}
],
"total": 45,
"limit": 20,
"offset": 0
"count": 45
}
```
docs/developer/api/queue/list_device_queue_items.md
+18 -8
View File
@@ -1,3 +1,11 @@
---
method: GET
path: /api/queue/devices/:device_id/items
auth: jwt
area: queue
---
<!-- source: internal/handlers/queue.go:89 QueueHandler.ListDeviceQueueItems -->
# List Device Queue Items
List all queue items for a specific device.
@@ -34,22 +42,24 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"items": [
{
"id": "uuid",
"device_id": "device-uuid",
"media_item_id": "book-uuid",
"operation": "sync_progress",
"device_name": "My Kobo",
"device_type": "kobo",
"user_email": "user@example.com",
"sync_type": "sync_progress",
"priority": 0,
"attempts": 0,
"max_attempts": 0,
"status": "pending",
"created_at": "2026-02-08T10:00:00Z",
"updated_at": "2026-02-08T10:00:00Z"
"created_at": "2026-02-08T10:00:00Z"
}
],
"total": 8,
"limit": 10,
"offset": 0
"count": 8
}
```
docs/developer/api/queue/retry_queue_item.md
+14 -3
View File
@@ -1,3 +1,11 @@
---
method: POST
path: /api/queue/items/:item_id/retry
auth: jwt
area: queue
---
<!-- source: internal/handlers/queue.go:220 QueueHandler.RetryQueueItem -->
# Retry Queue Item
Retry a failed queue item.
@@ -26,10 +34,13 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Response (200 OK)
```json
```json example-response
{
"message": "Queue item retry initiated",
"item_id": "uuid"
"message": "item queued for retry",
"item_id": "uuid",
"status": "pending",
"attempts": 0,
"max_attempts": 0
}
```
internal/docs/schema.go
+48
View File
@@ -324,4 +324,52 @@ var Schemas = map[string]Schema{
"name": "", "library_id": "", "books": [], "total": 0
}`),
},
// --- Beam batch 2: conflicts + queue backfill ---
"GET /api/conflicts": {
Response: handlers.ConflictListResponse{},
},
"GET /api/conflicts/:id": {
Response: handlers.ConflictDetailResponse{},
},
"DELETE /api/conflicts/:id": {},
"POST /api/conflicts/:id/resolve": {
Request: handlers.ConflictResolutionRequest{},
Response: handlers.ConflictResolveResponse{},
},
"POST /api/conflicts/dismiss-all": {
// deleted is an INT count of dismissed rows.
Response: json.RawMessage(`{"deleted": 0}`),
},
"POST /api/conflicts/bulk-resolve": {
Request: handlers.BulkResolveRequest{},
Response: handlers.BulkResolveResponse{},
},
"POST /api/conflicts/bulk-dismiss": {
// Inline anonymous request struct {conflict_ids} — pinned by sample.
Request: json.RawMessage(`{"conflict_ids": []}`),
Response: handlers.BulkResolveResponse{},
},
// NOTE: queue param names are :device_id / :item_id in the router —
// first registry draft used :id and the gate caught it.
"GET /api/queue/devices/:device_id/stats": {
Response: handlers.QueueStatsResponse{},
},
"GET /api/queue/devices/:device_id/items": {
Response: json.RawMessage(`{"items": [{}], "count": 0}`),
},
"GET /api/queue/items": {
Response: json.RawMessage(`{"items": [{}], "count": 0}`),
},
"POST /api/queue/items/:item_id/retry": {
Response: json.RawMessage(`{
"message": "", "item_id": "", "status": "",
"attempts": 0, "max_attempts": 0
}`),
},
"DELETE /api/queue/items/:item_id": {},
"DELETE /api/queue/devices/:device_id/clear": {
Response: json.RawMessage(`{"message": ""}`),
},
}