info:
  name: Sync Progress - With Bookmarks
  type: http
  seq: 3

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-uuid-here
          title: Book Title
          authors:
            - Author Name
          progress: 0.45
          percentage: 0.45
          last_read: '2026-01-30T20:00:00Z'
          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

docs: |-
  ## Sync Progress with Bookmarks

  Synchronizes reading progress with bookmarks/highlights from KOReader.

  **Method:** POST

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

  **Authentication:** Bearer token

  **Request Body:**
  - `library_id` (string, optional): Library UUID
  - `books` (array): Books with progress and bookmarks
    - `uuid`, `title`, `authors`, `progress`, etc.
    - `bookmarks` (array): Bookmark items
      - `chapter` (integer): Chapter number
      - `datetime` (string): ISO 8601 timestamp
      - `notes` (string): Note content or highlighted text
      - `pos0` (string): EPUB CFI start position
      - `pos1` (string): EPUB CFI end position
      - `page` (integer): Page number
      - `text` (string): Displayed text excerpt
      - `type` (string): `highlight`, `bookmark`, or `note`

  **Response:**
  - `progress_synced` (integer): Progress items synced
  - `bookmarks_synced` (integer): Bookmark items synced
  - `highlights_synced` (integer): Highlight count
  - `timestamp` (string): Sync timestamp

  **KOReader Bookmark Types:**
  - **highlight**: Selected text passages
  - **bookmark**: Location markers
  - **note**: Text annotations (can be attached to highlights)

  **KOReader Highlight Features:**
  - Custom colors (via color extensions)
  - Multi-color support
  - Precise EPUB CFI positioning
  - Chapter-based organization
  - Text excerpts preserved
  - Date/time stamped
  - Page number tracking

  **EPUB CFI in Bookmarks:**
  - `pos0`: Start position (highlight start)
  - `pos1`: End position (highlight end)
  - Exact text selection boundaries
  - Survives text reflow
  - Works across different font sizes

  **Sync Behavior:**
  - Duplicate detection by text + position
  - Most recent edit wins
  - Chapter references maintained
  - Order preserved from device
  - Merges with existing server bookmarks

  **KOReader Device Integration:**
  - Created in KOReader highlight interface
  - Shows in "Bookmarks" menu
  - Can be edited/deleted on device
  - Exportable to JSON/XML
  - Searchable by content

  **Use Cases:**
  - Study and research
  - Content review
  - Passage tracking
  - Quick navigation
  - Cross-device bookmark access