info:
  name: Checkpoint Sync
  type: http
  seq: 11

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: checkpoint
      checkpoint_id: checkpoint-uuid
      since_timestamp: '2026-01-30T19:00:00Z'
      books:
        - uuid: book-uuid-1
          percentage: 0.45
          chapter: 3
        - uuid: book-uuid-2
          percentage: 0.75
          chapter: 8

docs: |-
  ## Checkpoint Sync

  Incremental sync using checkpoint-based change tracking.

  **Method:** POST

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

  **Authentication:** Bearer token

  **Request Body:**
  - `sync_mode` (string): Must be `checkpoint`
  - `checkpoint_id` (string): Unique checkpoint identifier
  - `since_timestamp` (string): ISO 8601 timestamp for incremental sync
  - `books` (array): Book progress items
    - `uuid` (string): Book UUID
    - `percentage` (number): Progress 0.0-1.0
    - `chapter` (integer): Current chapter
    - `epubcfi` (string, optional): Current position
    - `modified_since` (boolean, optional): Whether modified since checkpoint

  **Response:**
  - `checkpoint_id` (string): Server checkpoint ID
  - `checkpoint_timestamp` (string): Checkpoint creation time
  - `processed` (integer): Books processed
  - `changes_only` (boolean): Whether only changed items synced
  - `next_checkpoint_id` (string): ID for next checkpoint sync
  - `results` (array): Per-book results

  **Status Codes:**
  - 200: Checkpoint sync completed
  - 401: Unauthorized
  - 400: Invalid checkpoint or timestamp

  **Checkpoint Sync Benefits:**
  - **Incremental**: Only sync changed items
  - **Efficient**: Smaller payloads
  - **Fast**: Reduced processing time
  - **Reliable**: Checkpoint-based tracking
  - **Resumable**: Can continue from last checkpoint

  **Checkpoint Mechanism:**
  - Server tracks changes since checkpoint
  - Client provides checkpoint ID or timestamp
  - Only modified books returned/processed
  - Checkpoint ID advances on each sync
  - Supports large libraries efficiently

  **Use Cases:**
  - Large libraries (100+ books)
  - Intermittent connectivity
  - Bandwidth optimization
  - Battery conservation
  - Background sync
  - Periodic sync (every 5-15 minutes)

  **Checkpoint Lifecycle:**
  1. Initial sync: No checkpoint (full sync)
  2. Server returns checkpoint_id
  3. Next sync: Client sends checkpoint_id
  4. Server processes only changes
  5. New checkpoint_id returned
  6. Repeat from step 3

  **Sync Optimization:**
  - Only books with progress changes
  - Skips unmodified books
  - Delta transfer
  - Compression for large payloads
  - Batch processing

  **Failure Handling:**
  - Checkpoint ID preserved on failure
  - Retry with same checkpoint
  - Full sync if checkpoint expired
  - Checkpoint validity: 24 hours
  - Auto-fallback to full sync

  **Performance:**
  - Small changes (1-10 books): 100-300ms
  - Medium changes (10-50 books): 300ms-1s
  - Large changes (50-100 books): 1-3s
  - Typical: 5-10x faster than full sync

  **When to Use:**
  - Default sync mode for most users
  - Periodic background sync
  - Large library management
  - Mobile/network-constrained environments
  - Battery-powered devices

  **Configuration:**
  - Checkpoint expiration: 24 hours
  - Max history: 100 checkpoints
  - Auto-cleanup of old checkpoints
  - Configurable sync interval