# KOReader Sync Protocol

KOReader uses a custom JSON-based sync protocol.

## KOReader Progress Sync

**Endpoint**: `POST /api/sync/koreader/progress`
**Auth**: Device token required
**Content-Type**: `application/json`

### Request Headers

| Header        | Type   | Required | Description         |
| ------------- | ------ | -------- | ------------------- |
| Authorization | string | Yes      | Bearer device token |
| Content-Type  | string | Yes      | application/json    |

### Request Body

| Field              | Type    | Required | Description                   |
| ------------------ | ------- | -------- | ----------------------------- |
| library_id         | string  | No       | Library UUID                  |
| books              | array   | Yes      | Array of book sync data       |
| books[].uuid       | string  | Yes      | Book UUID                     |
| books[].title      | string  | Yes      | Book title                    |
| books[].authors    | array   | Yes      | Array of author names         |
| books[].progress   | float   | Yes      | Progress percentage (0-1)     |
| books[].percentage | float   | Yes      | Progress percentage (0-1)     |
| books[].last_read  | string  | Yes      | ISO 8601 timestamp            |
| books[].chapter    | integer | No       | Current chapter               |
| books[].epubcfi    | string  | No       | EPUB CFI location             |
| books[].character  | integer | No       | Character offset              |
| books[].bookmarks  | array   | No       | Array of bookmarks/highlights |

### Example Request

```json
{
  "library_id": "optional-uuid",
  "books": [
    {
      "uuid": "book-uuid",
      "title": "Book Title",
      "authors": ["Author Name"],
      "progress": 0.45,
      "percentage": 0.45,
      "last_read": "2026-01-30T20:00:00Z",
      "chapter": 3,
      "epubcfi": "epubcfi(/6/4/2:15)",
      "character": 15432,
      "bookmarks": [
        {
          "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"
        }
      ],
      "highlights": [],
      "notes": []
    }
  ]
}
```

### Response (202 Accepted)

```json
{
  "sync_status": "accepted",
  "books_synced": 1,
  "conflicts": [
    {
      "book_uuid": "book-uuid",
      "conflict_type": "progress_mismatch",
      "device_progress": 0.45,
      "server_progress": 0.42,
      "resolution": "device_wins"
    }
  ]
}
```

## KOReader Metadata Fetch

**Endpoint**: `GET /api/sync/koreader/metadata/{book_uuid}`
**Auth**: Device token required

### Example Request

```http
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.42,
    "character": 15432,
    "epubcfi": "epubcfi(/6/4/2:15)",
    "chapter": 3,
    "chapter_progress": 0.234
  },
  "annotations": {
    "highlights": [...],
    "notes": [...],
    "bookmarks": [...]
  },
  "last_sync": "2026-01-30T20:00:00Z"
}
```