info:
  name: Sync Books from Server to Kobo
  type: http
  seq: 9

http:
  method: POST
  url: '{{base_url}}/api/sync/kobo/sync-from-server'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      force_sync: true
      books:
        - book-uuid-1
        - book-uuid-2

docs: |-
  ## Sync Books from Server to Kobo

  Pulls reading progress, annotations, and bookmarks from server to Kobo device.

  **Method:** POST

  **Endpoint:** /api/sync/kobo/sync-from-server

  **Authentication:** Bearer token

  **Request Body:**
  - `force_sync` (boolean): Force full sync (ignore last sync time)
  - `books` (array, optional): List of book UUIDs to sync
    - If empty, syncs all books with server data
    - If specified, only syncs listed books
  - `sync_options` (object, optional):
    - `since_date` (string): ISO 8601 timestamp for incremental sync
    - `include_annotations` (boolean): Include highlights/notes
    - `include_progress` (boolean): Include reading progress
    - `conflict_resolution` (string): `most_recent`, `server_wins`, `client_wins`

  **Response:**
  - `synced` (integer): Number of books synced
  - `skipped` (integer): Books with no server changes
  - `failed` (integer): Books that failed to sync
  - `results` (array): Per-book sync results
    - `book_id` (string): Book UUID
    - `status` (string): `synced`, `skipped`, `failed`
    - `progress_pulled` (boolean): Whether progress was downloaded
    - `annotations_pulled` (integer): Number of annotations downloaded
    - `error` (string, optional): Error message if failed
  - `server_timestamp` (string): Server timestamp of sync

  **Status Codes:**
  - 200: Sync completed
  - 207: Multi-status (some succeeded, some failed)
  - 401: Unauthorized
  - 400: Invalid request

  **Sync Direction:**
  - **Server → Device** (this endpoint)
  - Device → Server: Use `/sync/kobo/markup` endpoint
  - Bidirectional sync achieved by calling both

  **Pull Sync Use Cases:**
  - New device setup (download all progress)
  - Device replacement (restore from server)
  - Multi-device sync (pull changes from other devices)
  - Conflict resolution (server wins)
  - Manual "Download from server" operation

  **Conflict Resolution:**
  - `most_recent`: Latest timestamp wins (default)
  - `server_wins`: Server data always used
  - `client_wins`: Device data preserved
  - Applied per-book, per-item

  **Sync Optimization:**
  - Incremental sync by default (since last sync)
  - Force sync does full comparison
  - Book-level batching (10 books per batch)
  - Delta transfer (only changed items)
  - Compression for large annotation sets

  **Kobo Device Behavior:**
  - Device updates local database
  - Progress reflected in reading view
  - Annotations appear in Notebook
  - Bookmarks updated in navigation
  - Conflict warnings shown to user
  - Sync progress displayed on screen

  **Performance:**
  - Small sync (1-10 books): 2-5 seconds
  - Medium sync (10-50 books): 5-15 seconds
  - Large sync (50-200 books): 15-45 seconds
  - Timeout: 120 seconds

  **Use Cases:**
  - Initial device sync
  - After firmware update
  - From another device's changes
  - Manual sync request
  - Conflict recovery
  - Data restoration