docs: add sync protocols and WebSocket API documentation

Phase 2 part 7: Add real-time sync protocol documentation - KOReader Protocol: progress sync, metadata fetch - Kobo Protocol: markup sync, library fetch - WebSocket: real-time events (progress updates, conflicts) - Include message format examples for all protocols
2026-02-02 08:52:13 -05:00
parent 55024bb70a
commit 3e81477341
3 changed files with 337 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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"
+    }
+  ]
+}
+```
+
+## Try It Out
+
+<!-- API Explorer will be inserted here in Phase 3 -->