John O'Keefe
ae9588f1c6
Beam backfilled auth core (login/register/refresh/logout/profile) and devices
core (list/update/delete/shelf CRUD/sidecar/register flow) with frontmatter,
provenance, and labeled examples. All claimed shapes verified against
handlers: AuthResponse {access_token, refresh_token omitempty, token_type,
expires_in, user}, update device {device_updated, device}, shelf wrappers,
DeviceAuthStatusResponse.
Claude registry verification: 15 entries pinned by type (LoginRequest,
RegisterRequest, AuthResponse, RefreshTokenRequest/Response, UserProfile,
DeviceListResponse, DeviceUpdateRequest, AddToShelfRequest, SidecarConfig,
DeviceRegistrationRequest/Response, DeviceAuthStatusRequest/Response).
Removed revoke_device.md — name-only duplicate of delete_device.md (same
DELETE /api/devices/:id route; was the last audit-orphan doc).
Gate catches this round (subtle Go serialization facts, now pinned in docs):
- uuid.UUID arrays never serialize as omitted: register/status response
ALWAYS carries device_id (all-zeros while pending) despite omitempty
- update device request binds device_name, not name
- register response includes device_id alongside registration_id
- list devices response is a {devices, total} wrapper
77 lines
2.2 KiB
Markdown
77 lines
2.2 KiB
Markdown
---
|
|
method: GET
|
|
path: /api/devices/:id/sidecar
|
|
auth: jwt
|
|
area: devices
|
|
---
|
|
<!-- source: internal/handlers/sidecar.go:67 SidecarHandler.GetSidecarConfig -->
|
|
|
|
# Get Device Sidecar Config
|
|
|
|
Returns the KOReader/Kobo sidecar configuration (`.bookhoard.json`) for a device: server endpoints, the user's books (keyed by SHA-256 with UUID fallback), and collections. Used by the Bookhoard KOReader plugin to self-configure after approval.
|
|
|
|
**Endpoint**: `GET /api/devices/{id}/sidecar`
|
|
**Auth**: User JWT (device owner or admin)
|
|
|
|
### Response (200 OK)
|
|
|
|
```json example-response
|
|
{
|
|
"version": "1",
|
|
"bookhoard": {
|
|
"opds_catalog": "https://bookhoard.example.com/opds/devices/<device-id>/catalog",
|
|
"sync_api": "https://bookhoard.example.com/api/sync/kobo",
|
|
"opds_base_url": "https://bookhoard.example.com/opds",
|
|
"api_base_url": "https://bookhoard.example.com",
|
|
"device_id": "<device-id>",
|
|
"device_token": "dev_..."
|
|
},
|
|
"books": {
|
|
"abc123sha256...": {
|
|
"bookhoard_uuid": "media-item-uuid",
|
|
"title": "The Hobbit",
|
|
"author": "J. R. R. Tolkien",
|
|
"available_formats": ["epub", "kepub"],
|
|
"sha256": "abc123sha256...",
|
|
"file_path": "/books/hobbit.epub"
|
|
}
|
|
},
|
|
"collections": [
|
|
{ "name": "Favorites", "shelf_mapping": "Favorites" }
|
|
],
|
|
"opds_enabled": true,
|
|
"sidecar_enabled": true,
|
|
"last_updated": "2026-08-20T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
**Notes**:
|
|
|
|
- The `books` map is keyed by per-format SHA-256 (falling back to the item UUID), so a book downloaded in a different format (e.g. KEPUB) still matches its primary entry. Each entry lists `available_formats` for the item.
|
|
- `available_formats` includes `kepub` when the source is an EPUB (conversion available).
|
|
|
|
### Example Request
|
|
|
|
```bash
|
|
curl https://bookhoard.example.com/api/devices/<device-id>/sidecar \
|
|
-H "Authorization: Bearer <token>"
|
|
```
|
|
|
|
---
|
|
|
|
# Download Device Sidecar Config
|
|
|
|
Generates the same configuration as a downloadable `.bookhoard.json` file for manual device setup.
|
|
|
|
**Endpoint**: `GET /api/devices/{id}/sidecar/download`
|
|
**Auth**: User JWT (device owner or admin)
|
|
|
|
### Response (200 OK)
|
|
|
|
**Headers**:
|
|
|
|
- `Content-Type`: `application/json`
|
|
- `Content-Disposition`: attachment; filename="<device-name>.bookhoard.json"
|
|
|
|
**Body**: the sidecar JSON (same shape as above).
|