info:
  name: Sync Reading Progress
  type: http
  seq: 1

http:
  method: POST
  url: '{{base_url}}/api/sync/kobo/markup'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
    - key: x-kobo-device
      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
  body:
    type: json
    json:
      ReadingSync:
        - ContentId: book-uuid-here
          PercentRead: 45.6
          EntitlementId: entitlement-id-here
          RemainingTimeMinutes: 120
          FirstReadTime: '2026-01-25T10:00:00Z'
          LastModified: '2026-01-30T20:00:00Z'
      BookmarkSync: []

docs: |-
  ## Sync Kobo Reading Progress

  Synchronizes reading progress from a Kobo device to the server using Bearer token authentication.

  **Method:** POST

  **Endpoint:** /api/sync/kobo/markup

  **Authentication:** Bearer token (in Authorization header)

  **Headers:**
  - `Authorization`: Bearer {{kobo_device_token}}
  - `x-kobo-device`: JSON-encoded device info
    - `DeviceId`: Kobo device identifier
    - `Model`: Device model (e.g., "Kobo Clara", "Kobo Libra", "Kobo Aura")

  **Request Body:**
  - `ReadingSync` (array): Reading progress items
    - `ContentId` (string): Book/Content UUID
    - `PercentRead` (number): Reading progress 0-100
    - `EntitlementId` (string): Kobo entitlement ID
    - `RemainingTimeMinutes` (integer): Estimated reading time remaining
    - `FirstReadTime` (string): ISO 8601 timestamp when first opened
    - `LastModified` (string): ISO 8601 timestamp of last progress update
  - `BookmarkSync` (array): Empty array for progress-only sync

  **Response:**
  - `synced` (integer): Number of items synced
  - `failed` (integer): Number of items that failed to sync
  - `timestamp` (string): Server timestamp of sync
  - `books` (array): Synced book data
    - `ContentId` (string): Book UUID
    - `status` (string): `synced`, `failed`, `skipped`
    - `server_percent` (number): Server-side progress (for conflict detection)

  **Status Codes:**
  - 200: Sync successful
  - 401: Invalid device token
  - 403: Device not approved
  - 400: Invalid request format

  **Authentication Methods:**
  This endpoint uses **Bearer token authentication** (token in Authorization header).
  Alternative: Use `/sync/kobo/{token}/markup` with token in URL path.

  **Kobo Sync Features:**
  - Native Kobo sync protocol
  - Supports Kobo Clara, Libra, Aura, Forma, Sage, Elipsa
  - Progress percentage tracking
  - Reading time estimation
  - Cross-device synchronization
  - Automatic conflict resolution (most recent wins)

  **Sync Frequency:**
  - Kobo devices auto-sync every 15-30 minutes when connected to WiFi
  - Manual sync available from device settings
  - Sync triggers on: device wake, book close, WiFi connection