# 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):
```json
{
  "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):
```json
{
  "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**:
```json
{
  "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):
```json
{
  "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:

```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 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
