diff --git a/docs/developer/api/koreader/get_library.md b/docs/developer/api/koreader/get_library.md new file mode 100644 index 0000000..4fe49a4 --- /dev/null +++ b/docs/developer/api/koreader/get_library.md @@ -0,0 +1,53 @@ +# Get Library + +Get library metadata for KOReader device. + +**Endpoint**: `GET /api/sync/koreader/library` +**Auth**: Required (Device authentication) + +## Device Authentication + +This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials. + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| X-Device-ID | string | Yes | Device UUID | +| X-Device-Key | string | Yes | Device authentication key | + +### Example Request + +```http +GET /api/sync/koreader/library +X-Device-ID: 550e8400-e29b-41d4-a716-446655440000 +X-Device-Key: device-auth-key +``` + +## Response (200 OK) + +```json +{ + "books": [ + { + "id": "uuid", + "title": "Book Title", + "authors": ["Author Name"], + "file": "book.epub", + "size": 1234567 + } + ], + "total": 42 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Device authentication failed | +| 404 | Device not found | + +## Try It Out + + diff --git a/docs/developer/api/koreader/get_metadata.md b/docs/developer/api/koreader/get_metadata.md new file mode 100644 index 0000000..2b692ab --- /dev/null +++ b/docs/developer/api/koreader/get_metadata.md @@ -0,0 +1,55 @@ +# Get Metadata + +Get metadata for a book from KOReader device. + +**Endpoint**: `GET /api/sync/koreader/metadata/:uuid` +**Auth**: Required (Device authentication) + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| uuid | string (UUID) | Yes | Book UUID | + +## Device Authentication + +This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials. + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| X-Device-ID | string | Yes | Device UUID | +| X-Device-Key | string | Yes | Device authentication key | + +### Example Request + +```http +GET /api/sync/koreader/metadata/550e8400-e29b-41d4-a716-446655440000 +X-Device-ID: 550e8400-e29b-41d4-a716-446655440000 +X-Device-Key: device-auth-key +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "title": "Book Title", + "authors": ["Author Name"], + "path": "/path/to/book.epub", + "file_size": 1234567, + "modified_at": "2026-02-08T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Device authentication failed | +| 404 | Book or device not found | + +## Try It Out + + diff --git a/docs/developer/api/koreader/sync_bookmarks.md b/docs/developer/api/koreader/sync_bookmarks.md new file mode 100644 index 0000000..c722aa3 --- /dev/null +++ b/docs/developer/api/koreader/sync_bookmarks.md @@ -0,0 +1,71 @@ +# Sync Bookmarks + +Sync bookmarks from KOReader device. + +**Endpoint**: `POST /api/sync/koreader/bookmarks` +**Auth**: Required (Device authentication) + +## Device Authentication + +This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials. + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| device_id | string (UUID) | Yes | Device UUID | +| bookmarks | array | Yes | Array of bookmark objects | + +### Bookmark Object + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| book | string | Yes | Book identifier | +| chapter | string | No | Chapter title | +| page | integer | No | Page number | +| position | float | Yes | Position in document (0-1) | +| notes | string | No | Bookmark notes | +| highlighted_text | string | No | Highlighted text | +| time | string | Yes | ISO 8601 timestamp | +| created_at | string | Yes | ISO 8601 timestamp | + +### Example Request + +```json +{ + "device_id": "550e8400-e29b-41d4-a716-446655440000", + "bookmarks": [ + { + "book": "book.epub", + "chapter": "Chapter 1", + "page": 25, + "position": 0.125, + "notes": "Important section", + "highlighted_text": "Text to remember", + "time": "2026-02-08T10:00:00Z", + "created_at": "2026-02-08T10:00:00Z" + } + ] +} +``` + +## Response (200 OK) + +```json +{ + "message": "Bookmarks synced successfully", + "synced_count": 1 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Device authentication failed | +| 400 | Invalid request data | +| 404 | Device not found | + +## Try It Out + + diff --git a/docs/developer/api/koreader/sync_progress.md b/docs/developer/api/koreader/sync_progress.md new file mode 100644 index 0000000..a4b7c90 --- /dev/null +++ b/docs/developer/api/koreader/sync_progress.md @@ -0,0 +1,67 @@ +# Sync Progress + +Sync reading progress from KOReader device. + +**Endpoint**: `POST /api/sync/koreader/progress` +**Auth**: Required (Device authentication) + +## Device Authentication + +This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials. + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| device_id | string (UUID) | Yes | Device UUID | +| progress | array | Yes | Array of progress objects | + +### Progress Object + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| book | string | Yes | Book identifier (filename or UUID) | +| percent | float | Yes | Progress percentage (0-100) | +| page | integer | No | Current page number | +| total_pages | integer | No | Total pages in document | +| date_read | string | No | ISO 8601 timestamp of last read | +| updated_at | string | Yes | ISO 8601 timestamp | + +### Example Request + +```json +{ + "device_id": "550e8400-e29b-41d4-a716-446655440000", + "progress": [ + { + "book": "book.epub", + "percent": 75.5, + "page": 150, + "total_pages": 200, + "date_read": "2026-02-08T10:00:00Z", + "updated_at": "2026-02-08T10:00:00Z" + } + ] +} +``` + +## Response (200 OK) + +```json +{ + "message": "Progress synced successfully", + "synced_count": 1 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Device authentication failed | +| 400 | Invalid request data | +| 404 | Device not found | + +## Try It Out + +