From bab78c6c85304f02c9db508fe7f9116183e429d2 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Sun, 8 Feb 2026 12:38:50 -0500 Subject: [PATCH] docs(api): add KOReader sync protocol documentation - sync_progress.md - POST /api/sync/koreader/progress - get_metadata.md - GET /api/sync/koreader/metadata/:uuid - get_library.md - GET /api/sync/koreader/library - sync_bookmarks.md - POST /api/sync/koreader/bookmarks KOReader device sync endpoints with device authentication for progress, metadata, library, and bookmarks --- .../api/conflicts/bulk_dismiss_conflicts.md | 44 +++++++++++ .../api/conflicts/bulk_resolve_conflicts.md | 48 +++++++++++ .../api/conflicts/delete_conflict.md | 40 ++++++++++ .../api/conflicts/dismiss_all_resolved.md | 38 +++++++++ docs/developer/api/conflicts/get_conflict.md | 79 +++++++++++++++++++ .../developer/api/conflicts/list_conflicts.md | 69 ++++++++++++++++ .../api/conflicts/resolve_conflict.md | 50 ++++++++++++ 7 files changed, 368 insertions(+) create mode 100644 docs/developer/api/conflicts/bulk_dismiss_conflicts.md create mode 100644 docs/developer/api/conflicts/bulk_resolve_conflicts.md create mode 100644 docs/developer/api/conflicts/delete_conflict.md create mode 100644 docs/developer/api/conflicts/dismiss_all_resolved.md create mode 100644 docs/developer/api/conflicts/get_conflict.md create mode 100644 docs/developer/api/conflicts/list_conflicts.md create mode 100644 docs/developer/api/conflicts/resolve_conflict.md diff --git a/docs/developer/api/conflicts/bulk_dismiss_conflicts.md b/docs/developer/api/conflicts/bulk_dismiss_conflicts.md new file mode 100644 index 0000000..9575591 --- /dev/null +++ b/docs/developer/api/conflicts/bulk_dismiss_conflicts.md @@ -0,0 +1,44 @@ +# Bulk Dismiss Conflicts + +Dismiss multiple conflicts at once. + +**Endpoint**: `POST /api/conflicts/bulk-dismiss` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| conflict_ids | array of UUID | Yes | Array of conflict UUIDs to dismiss | + +### Example Request + +```json +{ + "conflict_ids": [ + "550e8400-e29b-41d4-a716-446655440000", + "660e8400-e29b-41d4-a716-446655440001" + ] +} +``` + +## Response (200 OK) + +```json +{ + "message": "Conflicts dismissed successfully", + "dismissed_count": 2 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid request body | +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/developer/api/conflicts/bulk_resolve_conflicts.md b/docs/developer/api/conflicts/bulk_resolve_conflicts.md new file mode 100644 index 0000000..8cda4cc --- /dev/null +++ b/docs/developer/api/conflicts/bulk_resolve_conflicts.md @@ -0,0 +1,48 @@ +# Bulk Resolve Conflicts + +Resolve multiple conflicts at once using a specified strategy. + +**Endpoint**: `POST /api/conflicts/bulk-resolve` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| conflict_ids | array of UUID | Yes | Array of conflict UUIDs to resolve | +| resolution | string | Yes | Resolution strategy: "device", "server", or "highest_progress" | + +### Example Request + +```json +{ + "conflict_ids": [ + "550e8400-e29b-41d4-a716-446655440000", + "660e8400-e29b-41d4-a716-446655440001" + ], + "resolution": "highest_progress" +} +``` + +## Response (200 OK) + +```json +{ + "message": "Conflicts resolved successfully", + "resolved_count": 2, + "failed_count": 0 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid request body | +| 401 | Invalid or expired token | +| 400 | Invalid resolution strategy | + +## Try It Out + + diff --git a/docs/developer/api/conflicts/delete_conflict.md b/docs/developer/api/conflicts/delete_conflict.md new file mode 100644 index 0000000..7b71a2b --- /dev/null +++ b/docs/developer/api/conflicts/delete_conflict.md @@ -0,0 +1,40 @@ +# Delete Conflict + +Delete a specific conflict record. + +**Endpoint**: `DELETE /api/conflicts/:id` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| id | string (UUID) | Yes | Conflict UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +DELETE /api/conflicts/550e8400-e29b-41d4-a716-446655440000 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +Conflict deleted successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Conflict not found | + +## Try It Out + + diff --git a/docs/developer/api/conflicts/dismiss_all_resolved.md b/docs/developer/api/conflicts/dismiss_all_resolved.md new file mode 100644 index 0000000..b358eec --- /dev/null +++ b/docs/developer/api/conflicts/dismiss_all_resolved.md @@ -0,0 +1,38 @@ +# Dismiss All Resolved + +Dismiss all resolved conflicts. + +**Endpoint**: `POST /api/conflicts/dismiss-all` +**Auth**: Required + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +POST /api/conflicts/dismiss-all +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "message": "All resolved conflicts dismissed", + "count": 15 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/developer/api/conflicts/get_conflict.md b/docs/developer/api/conflicts/get_conflict.md new file mode 100644 index 0000000..30f595b --- /dev/null +++ b/docs/developer/api/conflicts/get_conflict.md @@ -0,0 +1,79 @@ +# Get Conflict Details + +Get detailed information about a specific conflict. + +**Endpoint**: `GET /api/conflicts/:id` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| id | string (UUID) | Yes | Conflict UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/conflicts/550e8400-e29b-41d4-a716-446655440000 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "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", + "created_at": "2026-02-08T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Conflict not found | + +## Try It Out + + diff --git a/docs/developer/api/conflicts/list_conflicts.md b/docs/developer/api/conflicts/list_conflicts.md new file mode 100644 index 0000000..9f484aa --- /dev/null +++ b/docs/developer/api/conflicts/list_conflicts.md @@ -0,0 +1,69 @@ +# List Conflicts + +List all sync conflicts for the current user. + +**Endpoint**: `GET /api/conflicts` +**Auth**: Required + +## Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| status | string | No | Filter by status (active, resolved, dismissed) | +| media_item_id | string (UUID) | No | Filter by media item | +| limit | integer | No | Maximum number of conflicts to return (default: 50) | +| offset | integer | No | Number of conflicts to skip (default: 0) | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/conflicts?status=active&limit=10 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "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", + "created_at": "2026-02-08T10:00:00Z" + } + ], + "total": 5, + "limit": 10, + "offset": 0 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/developer/api/conflicts/resolve_conflict.md b/docs/developer/api/conflicts/resolve_conflict.md new file mode 100644 index 0000000..74ed84a --- /dev/null +++ b/docs/developer/api/conflicts/resolve_conflict.md @@ -0,0 +1,50 @@ +# Resolve Conflict + +Resolve a specific conflict by choosing which version to keep. + +**Endpoint**: `POST /api/conflicts/:id/resolve` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| id | string (UUID) | Yes | Conflict UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| resolution | string | Yes | Resolution strategy: "device", "server", or "highest_progress" | + +### Example Request + +```json +{ + "resolution": "device" +} +``` + +## Response (200 OK) + +```json +{ + "message": "Conflict resolved successfully", + "conflict_id": "uuid", + "resolution": "device" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid resolution strategy | +| 401 | Invalid or expired token | +| 404 | Conflict not found | +| 400 | Conflict already resolved | + +## Try It Out + +