info:
  name: Sync Progress - Multiple Books
  type: http
  seq: 2

http:
  method: POST
  url: '{{base_url}}/api/sync/koreader/progress'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      library_id: optional-library-uuid
      books:
        - uuid: book-1-uuid
          title: Book One
          authors:
            - Author One
          progress: 0.25
          percentage: 0.25
          last_read: '2026-01-30T19:00:00Z'
          chapter: 1
          epubcfi: 'epubcfi(/6/4/2:10)'
        - uuid: book-2-uuid
          title: Book Two
          authors:
            - Author Two
          progress: 0.75
          percentage: 0.75
          last_read: '2026-01-30T20:00:00Z'
          chapter: 8
          epubcfi: 'epubcfi(/6/4/2:50)'

docs: |-
  ## Sync KOReader Progress - Multiple Books

  Synchronizes reading progress for multiple books in a single request.

  **Method:** POST

  **Endpoint:** /api/sync/koreader/progress

  **Authentication:** Bearer token

  **Request Body:**
  - `library_id` (string, optional): Library UUID
  - `books` (array): Multiple book progress items
    - Each item contains: uuid, title, authors, progress, percentage, last_read, chapter, epubcfi

  **Response:**
  - `synced` (integer): Number of books successfully synced
  - `failed` (integer): Number of books that failed
  - `results` (array): Per-book sync results
  - `timestamp` (string): Sync timestamp

  **Status Codes:**
  - 200: Batch sync completed
  - 207: Multi-status (partial success)
  - 401: Unauthorized
  - 413: Payload too large

  **Batch Sync Advantages:**
  - Efficient sync of entire library
  - Single HTTP request for multiple books
  - Faster periodic sync
  - Reduced battery usage vs individual syncs
  - Better for batch processing

  **KOReader Batch Behavior:**
  - Triggered on device wake from sleep
  - Occurs during "Sync now" operation
  - Runs on WiFi connection
  - Limited to 100 books per request
  - Automatic retry on failed books

  **Performance:**
  - Small batch (2-10 books): 200-500ms
  - Medium batch (10-50 books): 500ms-2s
  - Large batch (50-100 books): 2-5s
  - Timeout: 30 seconds

  **Use Cases:**
  - Device initialization sync
  - Periodic background sync
  - Post-offline catch-up sync
  - Library-wide progress update
  - Before firmware update