bookhoard/bruno/sidecar

Phase 8: Sidecar Configuration System - API Documentation

Overview

This document describes the sidecar configuration system that enables easy device setup for Kobo and KOReader devices.

What is a Sidecar File?

A sidecar file (.bookmann.json) is a configuration file that contains all the information a device needs to connect to Bookmann, including:

• OPDS catalog URL for wireless book browsing
• Sync API endpoints for progress sync
• Book inventory with SHA-256 hashes
• Collection metadata with shelf mappings

Authentication

All endpoints require authentication:

• User endpoints: Use user JWT token (Authorization: Bearer {{user_token}})
• Admin endpoints: Use admin JWT token (Authorization: Bearer {{admin_token}})

Endpoints

1. Get Device Sidecar Config

Endpoint: GET /api/devices/:device_id/sidecar

Description: Returns sidecar configuration for a device as JSON.

Request Headers:

Authorization: Bearer {{user_token}}

Response (200 OK):

{
  "version": "1.0",
  "bookmann": {
    "opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog",
    "sync_api": "http://192.168.1.100:8765/api/sync/kobo",
    "opds_base_url": "http://192.168.1.100:8765/opds",
    "api_base_url": "http://192.168.1.100:8765/api",
    "device_id": "kobo-device-uuid",
    "device_token": "dev_xxxxx..."
  },
  "books": {
    "sha256:abc123...": {
      "bookmann_uuid": "uuid-123",
      "title": "The Hobbit",
      "author": "J.R.R. Tolkien",
      "available_formats": ["epub", "kepub"],
      "sha256": "abc123...",
      "file_path": "/path/to/book.epub"
    }
  },
  "collections": [
    {
      "name": "Sci-Fi",
      "shelf_mapping": "Science Fiction",
      "book_ids": ["uuid-1", "uuid-2", "uuid-3"]
    }
  ],
  "opds_enabled": true,
  "sidecar_enabled": true,
  "last_updated": "2026-01-31T12:00:00Z"
}

2. Download Device Sidecar File

Endpoint: GET /api/devices/:device_id/sidecar/download

Description: Downloads a .bookmann.json configuration file for device setup.

Request Headers:

Authorization: Bearer {{user_token}}

Response (200 OK):

Content-Type: application/json
Content-Disposition: attachment; filename="MyKoboClara.bookmann.json"

File contains formatted JSON (pretty-printed) suitable for:

• Manual device configuration
• Backup and restore
• Transfer via USB

3. Get System Configuration

Endpoint: GET /api/system/config

Description: Returns system-wide configuration settings (admin only).

Request Headers:

Authorization: Bearer {{admin_token}}

Response (200 OK):

{
  "base_url": "https://bookmann.example.com",
  "opds_base_url": "https://bookmann.example.com/opds",
  "api_base_url": "https://bookmann.example.com/api"
}

4. Update System Configuration

Endpoint: PUT /api/system/config

Description: Updates system-wide configuration settings (admin only).

Request Headers:

Authorization: Bearer {{admin_token}}
Content-Type: application/json

Request Body:

{
  "base_url": "https://bookmann.example.com",
  "opds_base_url": "https://bookmann.example.com/opds",
  "api_base_url": "https://bookmann.example.com/api"
}

Response (200 OK):

{
  "status": "success",
  "message": "System configuration updated"
}

Sidecar File Format

Version

Always "1.0" - enables future format changes

Bookmann Section

Contains device connection information:

• opds_catalog: Full URL to device's OPDS catalog
• sync_api: Sync API endpoint
• opds_base_url: Base URL for all OPDS operations
• api_base_url: Base URL for all API operations
• device_id: Device's unique identifier
• device_token: Device authentication token

Books Section

Map of book identifiers to book metadata:

• Key: SHA-256 hash (preferred) or Bookmann UUID
• bookmann_uuid: Canonical Bookmann UUID
• title: Book title
• author: Book author
• available_formats: Array of formats ("epub", "kepub")
• sha256: SHA-256 hash of book file
• file_path: Original file path

Collections Section

Array of collection definitions:

• name: Collection name in Bookmann
• shelf_mapping: Device-specific shelf name (e.g., "Science Fiction")
• book_ids: Array of Bookmann UUIDs in collection

Device Setup Workflow

Kobo E-Reader

1. Download Configuration

   • Log into Bookmann web UI
   • Navigate to Device Management
   • Click "Download Configuration" for your Kobo device
   • File saves as MyKoboClara.bookmann.json

2. Manual Configuration (if needed)

   • Copy .bookmann.json to Kobo device
   • Kobo can import configuration automatically

3. OPDS Setup (Recommended)

   • Use opds_catalog URL from sidecar
   • Add as new content catalog in Kobo settings
   • Browse and download books wirelessly

KOReader

1. Download Configuration

   • Same process as Kobo above

2. Configure Wireless Sync

   • In KOReader, set Calibre wireless URL to sync_api from sidecar
   • Enable password and use device_token
   • Set sync frequency to desired interval

Environment Variables

Set these in your Bruno collection:

{
  "base_url": "http://localhost:8765/api",
  "user_token": "your-user-jwt-token",
  "admin_token": "your-admin-jwt-token",
  "device_id": "uuid-of-device"
}

Error Codes

• 200: Success
• 400: Bad Request (invalid device ID, invalid JSON)
• 401: Unauthorized (missing or invalid token)
• 403: Forbidden (admin access required)
• 404: Not Found (device not found)
• 500: Internal Server Error (database error, generation failure)

Benefits

1. Easy Setup: One file contains all configuration
2. No Manual Entry: URLs and tokens pre-populated
3. SHA-256 Matching: Reliable book identification
4. Collection Sync: Shelf mappings included
5. Backup/Restore: Save and transfer device configs
6. Offline Configuration: Configure devices without network access initially

Testing Scenarios

Scenario 1: New Kobo Device

1. Register Kobo device in Bookmann
2. Download sidecar configuration
3. Add OPDS catalog URL from sidecar to Kobo
4. Browse and download books wirelessly
5. Progress syncs automatically

Scenario 2: Device Re-configuration

1. Download current sidecar file
2. Update system configuration if needed
3. Re-download sidecar with new settings
4. Re-configure device with updated file

Scenario 3: Collection Management

1. Create collections in Bookmann
2. Set up device-specific shelf mappings
3. Sidecar automatically includes collection info
4. Device shelves reflect collection structure