info:
  name: Get User Library for KOReader
  type: http
  seq: 9

http:
  method: GET
  url: '{{base_url}}/api/sync/koreader/library'
  auth: inherit

docs: |-
  ## Get KOReader User Library

  Retrieves the user's book library for KOReader device sync.

  **Method:** GET

  **Endpoint:** /api/sync/koreader/library

  **Authentication:** Bearer token (koreader_device_token)

  **Query Parameters:**
  None (returns entire library)

  **Response:**
  - `books` (array): Library items
    - `uuid` (string): SHA-256 based book identifier
    - `title` (string): Book title
    - `authors` (array): Author names
    - `series` (string, optional): Series name
    - `series_index` (number, optional): Series position
    - `publisher` (string, optional): Publisher
    - `publication_date` (string, optional): Release date
    - `language` (string, optional): Language code
    - `description` (string, optional): Description
    - `cover_url` (string, optional): Cover image URL
    - `cover_thumbnail_url` (string, optional): Thumbnail URL
    - `file_metadata` (object):
      - `format` (string): File format
      - `file_size` (integer): Size in bytes
      - `pages` (integer, optional): Page count
    - `progress` (object, optional): Reading progress
      - `percentage` (number): Progress 0-100
      - `last_read` (string): Last read timestamp
      - `epubcfi` (string): Current position
    - `annotations_count` (object, optional): Annotation stats
      - `highlights` (integer): Highlight count
      - `notes` (integer): Note count
      - `bookmarks` (integer): Bookmark count
  - `library_info` (object):
    - `total_books` (integer): Total book count
    - `last_sync` (string): Last library sync timestamp
    - `has_updates` (boolean): Updates available
  - `user_info` (object):
    - `user_id` (string): User identifier
    - `email` (string): Email (masked)
    - `libraries` (array): Available library IDs

  **Status Codes:**
  - 200: Success
  - 401: Unauthorized
  - 403: Device not approved

  **Library Purpose for KOReader:**
  - Discover books available for download
  - Browse catalog on device
  - Sync reading progress across books
  - Download covers/metadata
  - Series-based organization
  - Cloud library access

  **KOReader Device Features:**
  - **OPDS catalog**: Native OPDS client
  - **File browser**: See server books
  - **Cloud download**: Download books on-demand
  - **Metadata sync**: Automatic metadata fetching
  - **Cover images**: Display in library view
  - **Progress sync**: See progress across all books
  - **Search**: Search library by title/author

  **KOReader-Specific Features:**
  - SHA-256 based book IDs
  - Multi-format support (EPUB, FB2, PDF, DJVU, MOBI, etc.)
  - Series sorting and grouping
  - Language filtering
  - Cover image caching
  - Metadata for file browser enhancement
  - Integration with KOReader's OPDS client

  **Performance:**
  - Typical response: 100-500KB for 100 books
  - Processing time: 300ms-1s
  - Cache duration: 5 minutes
  - Pagination support for libraries >500 books

  **Use Cases:**
  - Initial device setup
  - Library browsing on device
  - Book download
  - Metadata refresh
  - Cover image sync
  - Progress overview
  - Series-based reading