info:
  name: Kobo Initialization
  type: http
  seq: 8

http:
  method: GET
  url: '{{base_url}}/api/sync/kobo/v1/initialization'
  auth: inherit

docs: |-
  ## Kobo Device Initialization

  Initializes Kobo device sync session and returns device configuration.

  **Method:** GET

  **Endpoint:** /api/sync/kobo/v1/initialization

  **Authentication:** Bearer token

  **Query Parameters:**
  - `Platform` (string, optional): Device platform (android, kobo)
  - `FirmwareVersion` (string, optional): Firmware version string
  - `Model` (string, optional): Device model name

  **Response:**
  - `device` (object): Device information
    - `device_id` (string): Server device ID
    - `approved` (boolean): Whether device is approved
    - `sync_enabled` (boolean): Whether sync is active
    - `last_sync` (string): Last successful sync timestamp
  - `user` (object): User information
    - `user_id` (string): User identifier
    - `email` (string): User email (masked)
    - `library_size` (integer): Number of books in library
  - `sync_config` (object): Sync configuration
    - `sync_interval_minutes` (integer): Recommended sync frequency
    - `batch_size` (integer): Max items per batch
    - `timeout_seconds` (integer): Request timeout
    - `retry_count` (integer): Max retry attempts
  - `features` (object): Available features
    - `annotation_sync` (boolean): Annotation support
    - `bookmark_sync` (boolean): Bookmark support
    - `progress_sync` (boolean): Progress tracking
    - `library_download` (boolean): Library access
  - `endpoints` (object): API endpoint URLs
    - `markup_sync` (string): Progress/annotation sync URL
    - `bookmark_sync` (string): Bookmark sync URL
    - `library` (string): Library access URL
    - `sync_from_server` (string): Download sync URL
  - `server_time` (string): Current server timestamp
  - `version` (string): API version

  **Status Codes:**
  - 200: Success
  - 401: Unauthorized (invalid token)
  - 403: Forbidden (device not approved)
  - 404: Device not found

  **Initialization Flow:**
  1. Device powers on or connects to network
  2. Device calls initialization endpoint
  3. Server returns configuration and capabilities
  4. Device adjusts sync behavior based on config
  5. Device begins sync operations

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

  **Configuration Caching:**
  - Response cached on device for 24 hours
  - Refreshed on device reboot
  - Updated when sync settings change
  - Can be force-refreshed via device settings

  **Device Approval:**
  - New devices: `approved: false`
  - Pending devices see limited functionality
  - Approval required for full sync
  - User approves via web interface
  - Re-initialization after approval

  **Use Cases:**
  - Device registration
  - Daily device wakeup
  - Post-approval initialization
  - Configuration refresh
  - Feature capability check
  - Sync endpoint discovery

  **Kobo Native Integration:**
  - Called by Kobo Nickel UI
  - Integrated with Kobo sync service
  - Part of Kobo account setup
  - Supports Kobo "Sync now" feature
  - Enables Kobo library browsing