john-okeefe
ff96ffa92d
Documentation updates: - All docs/ files: Update project references - Bruno API collection: Update collection name and tests - Device setup guides: Update all examples - Implementation plan: Update database schema examples - README files: Update project references Part of project rename to Bookhoard.
244 lines
6.6 KiB
Markdown
244 lines
6.6 KiB
Markdown
# 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 (`.bookhoard.json`) is a configuration file that contains all the information a device needs to connect to Bookhoard, 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):
|
|
```json
|
|
{
|
|
"version": "1.0",
|
|
"bookhoard": {
|
|
"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...": {
|
|
"bookhoard_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 `.bookhoard.json` configuration file for device setup.
|
|
|
|
**Request Headers**:
|
|
```
|
|
Authorization: Bearer {{user_token}}
|
|
```
|
|
|
|
**Response** (200 OK):
|
|
```
|
|
Content-Type: application/json
|
|
Content-Disposition: attachment; filename="MyKoboClara.bookhoard.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):
|
|
```json
|
|
{
|
|
"base_url": "https://bookhoard.example.com",
|
|
"opds_base_url": "https://bookhoard.example.com/opds",
|
|
"api_base_url": "https://bookhoard.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**:
|
|
```json
|
|
{
|
|
"base_url": "https://bookhoard.example.com",
|
|
"opds_base_url": "https://bookhoard.example.com/opds",
|
|
"api_base_url": "https://bookhoard.example.com/api"
|
|
}
|
|
```
|
|
|
|
**Response** (200 OK):
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "System configuration updated"
|
|
}
|
|
```
|
|
|
|
## Sidecar File Format
|
|
|
|
### Version
|
|
Always "1.0" - enables future format changes
|
|
|
|
### Bookhoard 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 Bookhoard UUID
|
|
- **bookhoard_uuid**: Canonical Bookhoard 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 Bookhoard
|
|
- **shelf_mapping**: Device-specific shelf name (e.g., "Science Fiction")
|
|
- **book_ids**: Array of Bookhoard UUIDs in collection
|
|
|
|
## Device Setup Workflow
|
|
|
|
### Kobo E-Reader
|
|
|
|
1. **Download Configuration**
|
|
- Log into Bookhoard web UI
|
|
- Navigate to Device Management
|
|
- Click "Download Configuration" for your Kobo device
|
|
- File saves as `MyKoboClara.bookhoard.json`
|
|
|
|
2. **Manual Configuration** (if needed)
|
|
- Copy `.bookhoard.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:
|
|
|
|
```json
|
|
{
|
|
"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 Bookhoard
|
|
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 Bookhoard
|
|
2. Set up device-specific shelf mappings
|
|
3. Sidecar automatically includes collection info
|
|
4. Device shelves reflect collection structure
|