info:
  name: Immediate Sync - Page Turn
  type: http
  seq: 10

http:
  method: POST
  url: '{{base_url}}/api/sync/koreader/progress'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      sync_mode: immediate
      books:
        - uuid: book-uuid
          percentage: 0.45678
          chapter: 3
          timestamp: '2026-01-30T20:00:00Z'

docs: |-
  ## Immediate Sync - Page Turn

  Real-time progress sync triggered immediately on page turn.

  **Method:** POST

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

  **Authentication:** Bearer token

  **Request Body:**
  - `sync_mode` (string): Must be `immediate`
  - `books` (array): Current book progress
    - `uuid` (string): Book UUID
    - `percentage` (number): Precise progress (0.45678 = 45.678%)
    - `chapter` (integer): Current chapter
    - `timestamp` (string): ISO 8601 timestamp
    - `epubcfi` (string, optional): Current position
    - `page` (integer, optional): Current page

  **Response:**
  - `synced` (boolean): Immediate sync status
  - `timestamp` (string): Server timestamp
  - `next_sync_suggested` (string): Suggested next sync time

  **Status Codes:**
  - 200: Sync queued
  - 202: Accepted for processing
  - 401: Unauthorized
  - 429: Too many immediate sync requests (rate limited)

  **Immediate Sync Mode:**
  - **Purpose**: Real-time progress updates
  - **Trigger**: Every page turn (configurable)
  - **Priority**: High priority processing
  - **Latency**: <100ms typical
  - **Best effort**: May be queued under load

  **Rate Limiting:**
  - Max 60 requests per minute per device
  - Throttled after limit reached
  - Suggests switching to periodic sync
  - Prevents server overload

  **Use Cases:**
  - Real-time multi-device reading
  - Live progress sharing
  - Instant position backup
  - Critical reading points
  - Test/profiling mode

  **Performance:**
  - Ultra-fast sync
  - Minimal payload
  - Optimized for speed
  - Async processing
  - No confirmation wait

  **Battery Considerations:**
  - More frequent network use
  - Higher battery consumption
  - WiFi recommended
  - Can reduce sync frequency in settings

  **Configuration:**
  - Can enable/disable per device
  - Adjustable frequency (every page, every N pages)
  - Automatic fallback to periodic sync on error
  - Respects device power-save mode

  **When to Use:**
  - Critical reading sessions
  - Multi-device concurrent reading
  - Research and study
  - Testing sync functionality
  - When power source available

  **When NOT to Use:**
  - Battery conservation needed
  - Unstable network
  - Extended reading sessions
  - Background sync preferred