info:
  name: Sync Progress - Single Book
  type: http
  seq: 1

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'
          chapter: 3
          epubcfi: 'epubcfi(/6/4/2:15)'
          character: 15432

docs: |-
  ## Sync KOReader Progress - Single Book

  Synchronizes reading progress for a single book from KOReader device.

  **Method:** POST

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

  **Authentication:** Bearer token (koreader_device_token)

  **Request Body:**
  - `library_id` (string, optional): Library UUID for multi-library setups
  - `books` (array): Array with single book progress
    - `uuid` (string): Unique book identifier (often SHA-256 hash)
    - `title` (string): Book title
    - `authors` (array): List of authors
    - `progress` (number): Progress decimal (0.0 to 1.0)
    - `percentage` (number): Progress percentage (0.45 = 45%)
    - `last_read` (string): ISO 8601 timestamp of last read
    - `chapter` (integer): Current chapter number
    - `epubcfi` (string): EPUB Canonical Fragment Identifier
    - `character` (integer): Character position in book
    - `page` (integer, optional): Current page number

  **Response:**
  - `synced` (integer): Number of books synced
  - `timestamp` (string): Server sync timestamp
  - `books` (array): Sync results
    - `uuid` (string): Book UUID
    - `status` (string): `synced`, `updated`, `skipped`
    - `server_progress` (object): Server-side progress data

  **Status Codes:**
  - 200: Success
  - 401: Unauthorized
  - 400: Invalid request format

  **KOReader Progress Tracking:**
  - SHA-256 based book identification (universal across devices)
  - EPUB CFI for precise location (standard format)
  - Chapter-based navigation
  - Character-level precision
  - Supports EPUB, FB2, PDF, DJVU, MOBI formats

  **EPUB CFI Format:**
  - Standardized location format for EPUBs
  - Example: `epubcfi(/6/4/2:15)`
  - Identifies exact position even after reflow
  - Works across different devices/apps
  - Preserved after file modifications

  **Book Identification:**
  - Primary: SHA-256 hash of book file
  - Universal: Same book = same UUID across devices
  - Format-agnostic: Works for any supported format
  - Case-sensitive: Hash must match exactly

  **Use Cases:**
  - Real-time page turn sync
  - Progress backup
  - Cross-device continuity
  - Reading time tracking
  - Chapter completion detection