Phase 3 Week 7: Add KOReader routes, tests, and documentation
- Add KOReader sync endpoints to main application router - Create Bruno API collection for testing KOReader endpoints - Add integration tests for KOReader functionality - Include comprehensive README with setup instructions - Test coverage for progress, metadata, library, and bookmarks sync - Part of Phase 3 KOReader Integration implementation
This commit is contained in:
@@ -0,0 +1,20 @@
|
||||
meta {
|
||||
name: KOReader Get Book Metadata
|
||||
type: http
|
||||
seq: 2
|
||||
}
|
||||
|
||||
get {
|
||||
url: {{baseUrl}}/api/sync/koreader/metadata/{{book_uuid}}
|
||||
headers: {
|
||||
Authorization: Bearer {{device_token}},
|
||||
Content-Type: application/json
|
||||
}
|
||||
}
|
||||
|
||||
assert {
|
||||
res.status == 200
|
||||
res.body.uuid != null
|
||||
res.body.title != null
|
||||
res.body.progress != null
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
meta {
|
||||
name: KOReader Get Library
|
||||
type: http
|
||||
seq: 3
|
||||
}
|
||||
|
||||
get {
|
||||
url: {{baseUrl}}/api/sync/koreader/library
|
||||
headers: {
|
||||
Authorization: Bearer {{device_token}},
|
||||
Content-Type: application/json
|
||||
}
|
||||
}
|
||||
|
||||
assert {
|
||||
res.status == 200
|
||||
res.body.library_sync != null
|
||||
res.body.total_books >= 0
|
||||
}
|
||||
@@ -0,0 +1,307 @@
|
||||
# KOReader Integration
|
||||
|
||||
## Overview
|
||||
|
||||
Bookmann provides full Calibre-compatible wireless sync for KOReader devices, enabling seamless reading progress, highlights, and notes synchronization.
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Register Your Device
|
||||
|
||||
First, register your KOReader device with Bookmann:
|
||||
|
||||
```bash
|
||||
POST /api/devices/register
|
||||
{
|
||||
"device_name": "My Kindle Paperwhite",
|
||||
"device_type": "koreader",
|
||||
"device_identifier": "unique-hardware-id"
|
||||
}
|
||||
```
|
||||
|
||||
You'll receive:
|
||||
- A registration URL to approve the device
|
||||
- A QR code for easy setup
|
||||
- Setup instructions for your device type
|
||||
|
||||
### 2. Approve Device
|
||||
|
||||
Visit the approval URL in your web browser (or scan the QR code) to authenticate the device.
|
||||
|
||||
### 3. Configure KOReader
|
||||
|
||||
In KOReader settings, set:
|
||||
- **Calibre wireless URL**: `https://your-bookmann-domain.com/api/sync/koreader`
|
||||
- **Enable wireless sync**: ON
|
||||
- **Sync frequency**: Every page turn (recommended)
|
||||
|
||||
### 4. Enter Device Token
|
||||
|
||||
After approval, you'll receive a device token. Add this to KOReader:
|
||||
- Settings → Wireless sync → Password
|
||||
- Paste the token: `dev_xxxxx...`
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Sync Progress
|
||||
|
||||
Updates reading progress for one or more books.
|
||||
|
||||
```bash
|
||||
POST /api/sync/koreader/progress
|
||||
Authorization: Bearer {device_token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"books": [
|
||||
{
|
||||
"uuid": "book-uuid",
|
||||
"title": "Book Title",
|
||||
"authors": ["Author Name"],
|
||||
"percentage": 0.45,
|
||||
"progress": 0.45,
|
||||
"chapter": 5,
|
||||
"character": 15432,
|
||||
"epubcfi": "epubcfi(/6/4/2:15)",
|
||||
"page": 89,
|
||||
"total_pages": 200,
|
||||
"last_read": "2026-01-30T20:00:00Z"
|
||||
}
|
||||
],
|
||||
"sync_mode": "immediate"
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (202 Accepted):
|
||||
```json
|
||||
{
|
||||
"sync_status": "accepted",
|
||||
"books_synced": 1,
|
||||
"conflicts": [],
|
||||
"timestamp": "2026-01-30T20:00:00Z",
|
||||
"device_updated": true
|
||||
}
|
||||
```
|
||||
|
||||
### Get Book Metadata
|
||||
|
||||
Fetches progress and annotations for a specific book.
|
||||
|
||||
```bash
|
||||
GET /api/sync/koreader/metadata/{book_uuid}
|
||||
Authorization: Bearer {device_token}
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"uuid": "book-uuid",
|
||||
"title": "Book Title",
|
||||
"authors": ["Author Name"],
|
||||
"progress": {
|
||||
"percentage": 0.45,
|
||||
"chapter": 5,
|
||||
"epubcfi": "epubcfi(/6/4/2:15)",
|
||||
"character": 15432,
|
||||
"page": 89,
|
||||
"total_pages": 200
|
||||
},
|
||||
"annotations": {
|
||||
"highlights": [
|
||||
{
|
||||
"text": "highlighted text",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"pos1": "epubcfi(/6/4/2:20)",
|
||||
"color": "#ffff00",
|
||||
"datetime": "2026-01-30T19:55:00Z"
|
||||
}
|
||||
],
|
||||
"notes": [
|
||||
{
|
||||
"text": "My note",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"datetime": "2026-01-30T19:55:00Z"
|
||||
}
|
||||
]
|
||||
},
|
||||
"last_sync": "2026-01-30T20:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Library
|
||||
|
||||
Fetches all books available for sync.
|
||||
|
||||
```bash
|
||||
GET /api/sync/koreader/library
|
||||
Authorization: Bearer {device_token}
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"library_sync": [
|
||||
{
|
||||
"uuid": "book-uuid",
|
||||
"title": "Book Title",
|
||||
"author": "Author Name",
|
||||
"content_type": "6",
|
||||
"percent_read": 45.0,
|
||||
"pages_remaining": 115,
|
||||
"bookmark_count": 3,
|
||||
"last_modified": "2026-01-30T20:00:00Z"
|
||||
}
|
||||
],
|
||||
"total_books": 10,
|
||||
"last_sync": "2026-01-30T20:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Sync Bookmarks/Notes/Highlights
|
||||
|
||||
Syncs annotations for a specific book.
|
||||
|
||||
```bash
|
||||
POST /api/sync/koreader/bookmarks
|
||||
Authorization: Bearer {device_token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"book_uuid": "book-uuid",
|
||||
"bookmarks": [
|
||||
{
|
||||
"chapter": 3,
|
||||
"datetime": "2026-01-30T19:55:00Z",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"page": 45,
|
||||
"text": "Bookmarked text",
|
||||
"type": "bookmark"
|
||||
}
|
||||
],
|
||||
"highlights": [
|
||||
{
|
||||
"chapter": 3,
|
||||
"datetime": "2026-01-30T19:55:00Z",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"pos1": "epubcfi(/6/4/2:20)",
|
||||
"page": 45,
|
||||
"text": "highlighted text",
|
||||
"color": "#ffff00"
|
||||
}
|
||||
],
|
||||
"notes": [
|
||||
{
|
||||
"chapter": 3,
|
||||
"datetime": "2026-01-30T19:55:00Z",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"notes": "My note content",
|
||||
"page": 45
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
{
|
||||
"sync_status": "completed",
|
||||
"bookmarks_synced": 1,
|
||||
"notes_synced": 1,
|
||||
"highlights_synced": 1,
|
||||
"total_synced": 3,
|
||||
"timestamp": "2026-01-30T20:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Sync Modes
|
||||
|
||||
### Immediate Mode (Recommended)
|
||||
Syncs on every page turn for real-time updates across all devices.
|
||||
|
||||
```json
|
||||
{ "sync_mode": "immediate" }
|
||||
```
|
||||
|
||||
### Checkpoint Mode
|
||||
Syncs periodically to save bandwidth.
|
||||
|
||||
```json
|
||||
{
|
||||
"sync_mode": "checkpoint",
|
||||
"checkpoint_id": "checkpoint-uuid",
|
||||
"since_timestamp": "2026-01-30T19:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- **Sync requests**: 60/minute
|
||||
- **Progress updates**: 120/minute
|
||||
- **Metadata requests**: 30/minute
|
||||
|
||||
## Device Matching
|
||||
|
||||
Bookmann tries multiple strategies to match books:
|
||||
|
||||
1. **By UUID**: Most reliable if your book files have unique IDs
|
||||
2. **By file path**: Matches exact file path
|
||||
3. **By title + author**: Fallback for unmatched books
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
When the same book is read on multiple devices within 5 minutes:
|
||||
|
||||
- Auto-resolution uses "most recent progress wins"
|
||||
- Conflicts are logged for review
|
||||
- Users can manually resolve conflicts via the web UI
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Sync Not Working
|
||||
|
||||
1. **Check device token**: Ensure token is valid and not revoked
|
||||
2. **Verify sync enabled**: Device must have `sync_enabled: true`
|
||||
3. **Check rate limits**: Device may be rate-limited
|
||||
4. **Book matching**: Ensure books can be matched by UUID, path, or title
|
||||
|
||||
### Progress Not Updating
|
||||
|
||||
1. **Verify percentage value**: Must be between 0.0 and 1.0
|
||||
2. **Check book ownership**: User must have access to the book
|
||||
3. **Review sync logs**: Check for error messages
|
||||
|
||||
### Authentication Errors
|
||||
|
||||
1. **Token expired**: Re-register device
|
||||
2. **Device revoked**: Check device status in web UI
|
||||
3. **Invalid token format**: Ensure `Bearer dev_xxxxx...` format
|
||||
|
||||
## Testing
|
||||
|
||||
Use the Bruno API collection in `/bruno/koreader/` to test endpoints:
|
||||
|
||||
- `Sync Progress.bru` - Test progress sync
|
||||
- `Get Book Metadata.bru` - Test metadata retrieval
|
||||
- `Get Library.bru` - Test library sync
|
||||
- `Sync Bookmarks.bru` - Test annotation sync
|
||||
|
||||
Required variables:
|
||||
- `baseUrl` - Your Bookmann server URL
|
||||
- `device_token` - Device authentication token
|
||||
- `book_uuid` - UUID of a test book
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- Compatible with Calibre wireless protocol
|
||||
- Supports EPUB CFI for precise locations
|
||||
- Handles reflowable and fixed-layout formats
|
||||
- Bidirectional sync (KOReader ↔ Bookmann)
|
||||
- Real-time updates via WebSocket (coming in Phase 3b)
|
||||
|
||||
## Next Steps
|
||||
|
||||
See Phase 3 implementation guide for:
|
||||
- WebSocket real-time sync
|
||||
- Advanced conflict resolution
|
||||
- Offline sync queue management
|
||||
- Performance optimization
|
||||
@@ -0,0 +1,60 @@
|
||||
meta {
|
||||
name: KOReader Sync Bookmarks
|
||||
type: http
|
||||
seq: 4
|
||||
}
|
||||
|
||||
post {
|
||||
url: {{baseUrl}}/api/sync/koreader/bookmarks
|
||||
body: json({
|
||||
"book_uuid": "{{book_uuid}}",
|
||||
"bookmarks": [
|
||||
{
|
||||
"chapter": 3,
|
||||
"datetime": "2026-01-30T19:55:00Z",
|
||||
"notes": "Bookmarked text",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"pos1": "epubcfi(/6/4/2:20)",
|
||||
"page": 45,
|
||||
"text": "This is important",
|
||||
"type": "highlight",
|
||||
"percentage": 0.45
|
||||
}
|
||||
],
|
||||
"notes": [
|
||||
{
|
||||
"chapter": 3,
|
||||
"datetime": "2026-01-30T19:55:00Z",
|
||||
"notes": "My note here",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"page": 45,
|
||||
"text": "Note content",
|
||||
"type": "note"
|
||||
}
|
||||
],
|
||||
"highlights": [
|
||||
{
|
||||
"chapter": 3,
|
||||
"datetime": "2026-01-30T19:55:00Z",
|
||||
"notes": "highlighted text",
|
||||
"pos0": "epubcfi(/6/4/2:15)",
|
||||
"pos1": "epubcfi(/6/4/2:20)",
|
||||
"page": 45,
|
||||
"text": "highlighted text excerpt",
|
||||
"type": "highlight",
|
||||
"color": "#ffff00",
|
||||
"percentage": 0.45
|
||||
}
|
||||
]
|
||||
})
|
||||
headers: {
|
||||
Authorization: Bearer {{device_token}},
|
||||
Content-Type: application/json
|
||||
}
|
||||
}
|
||||
|
||||
assert {
|
||||
res.status == 200
|
||||
res.body.sync_status == "completed"
|
||||
res.body.total_synced >= 0
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
meta {
|
||||
name: KOReader Sync Progress
|
||||
type: http
|
||||
seq: 1
|
||||
}
|
||||
|
||||
post {
|
||||
url: {{baseUrl}}/api/sync/koreader/progress
|
||||
body: json({
|
||||
"library_id": null,
|
||||
"books": [
|
||||
{
|
||||
"uuid": "{{book_uuid}}",
|
||||
"title": "Test Book",
|
||||
"authors": ["Test Author"],
|
||||
"progress": 0.45,
|
||||
"percentage": 0.45,
|
||||
"last_read": "2026-01-30T20:00:00Z",
|
||||
"chapter": 5,
|
||||
"character": 15432,
|
||||
"epubcfi": "epubcfi(/6/4/2:15)",
|
||||
"page": 89,
|
||||
"total_pages": 200
|
||||
}
|
||||
],
|
||||
"sync_mode": "immediate",
|
||||
"device_info": {
|
||||
"koreader_version": "2024.01",
|
||||
"device_model": "kindle-paperwhite-5"
|
||||
}
|
||||
})
|
||||
headers: {
|
||||
Authorization: Bearer {{device_token}},
|
||||
Content-Type: application/json
|
||||
}
|
||||
}
|
||||
|
||||
assert {
|
||||
res.status == 202
|
||||
res.body.sync_status == "accepted"
|
||||
res.body.books_synced >= 0
|
||||
}
|
||||
Reference in New Issue
Block a user