info:
  name: Get Kobo Library
  type: http
  seq: 6

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

docs: |-
  ## Get Kobo Library

  Retrieves the user's Kobo library metadata for device sync.

  **Method:** GET

  **Endpoint:** /api/sync/kobo/library

  **Authentication:** Bearer token

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

  **Response:**
  - `books` (array): Library items
    - `ContentId` (string): Unique book identifier
    - `Title` (string): Book title
    - `Author` (string): Author name
    - `Publisher` (string): Publisher name
    - `Description` (string): Book description
    - `ISBN` (string, optional): ISBN-13
    - `PublicationDate` (string): Release date
    - `EntitlementId` (string): Kobo entitlement ID
    - `CrossRevisionId` (string): Revision identifier
    - `MimeType` (string): Content type (application/epub+zip)
    - `FileSize` (integer): File size in bytes
    - `CoverImageId` (string): Cover image identifier
    - `DownloadUrls` (object): Download URLs
      - `download_url` (string): Direct download link
      - `download_acquisition_url` (string): OPDS acquisition URL
  - `sync_metadata` (object):
    - `last_sync` (string): Last library sync timestamp
    - `total_books` (integer): Total book count
    - `has_updates` (boolean): Whether updates are available

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

  **Library Sync Purpose:**
  - Kobo device needs to know available books
  - Enables download via device browser
  - Provides metadata for device display
  - Supports Kobo's "My Books" feature
  - Enables on-device purchasing integration

  **Kobo Device Usage:**
  - Device fetches library on registration
  - Refreshed daily or on manual sync
  - User can browse library on device
  - Books downloaded wirelessly to device
  - Supports "Buy on Kobo, read on device" workflow

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

  **Performance:**
  - Typical response: 50-200KB for 100 books
  - Processing time: 200-800ms
  - Cache duration: 5 minutes
  - Pagination available for large libraries (>500 books)

  **Use Cases:**
  - Initial device registration
  - Library refresh on device
  - Book discovery on device
  - Download link generation
  - Metadata sync for OPDS