# Kobo Sync Protocol

Kobo uses a proprietary sync protocol with JSON payloads.

## Kobo Markup Sync

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

### Request Headers

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

### Request Body

| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| ReadingSync | array | No | Array of reading progress data |
| ReadingSync[].ContentId | string | Yes | Book UUID |
| ReadingSync[].PercentRead | float | Yes | Progress percentage (0-100) |
| ReadingSync[].EntitlementId | string | Yes | Kobo entitlement ID |
| ReadingSync[].RemainingTimeMinutes | integer | No | Estimated remaining time |
| ReadingSync[].LastModified | string | Yes | ISO 8601 timestamp |
| BookmarkSync | array | No | Array of bookmarks/highlights |

### Example Request

```http
POST /api/sync/kobo/markup
Authorization: Bearer device-token
x-kobo-device: {"DeviceId":"device-id","Model":"Kobo Clara"}
Content-Type: application/json

{
  "ReadingSync": [
    {
      "ContentId": "book-uuid",
      "PercentRead": 45.6,
      "EntitlementId": "entitlement-id",
      "RemainingTimeMinutes": 120,
      "LastModified": "2026-01-30T20:00:00Z"
    }
  ],
  "BookmarkSync": [
    {
      "ContentId": "book-uuid",
      "BookmarkText": "highlighted text",
      "BookmarkType": "annotation",
      "BookmarkTitle": "Chapter 3"
    }
  ]
}
```

### Response (200 OK)

```json
{
  "Status": "Success",
  "MarkupsSynced": 5,
  "BookmarksSynced": 3
}
```

## Kobo Library Fetch

**Endpoint**: `GET /api/sync/kobo/library`
**Auth**: Device token required

### Example Request

```http
GET /api/sync/kobo/library
Authorization: Bearer device-token
```

### Response (200 OK)

```json
{
  "library_sync": [
    {
      "ContentId": "book-uuid",
      "ContentType": "6",
      "Title": "Book Title",
      "Author": "Author Name",
      "PercentRead": 42.3,
      "PagesRemaining": 115,
      "BookmarkCount": 3,
      "LastModified": "2026-01-30T20:00:00Z"
    }
  ]
}
```
