Update documentation and API tests: Bookmann → Bookhoard
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.
This commit is contained in:
+2
-2
@@ -1,6 +1,6 @@
|
||||
# Bruno API Tests for Bookmann
|
||||
# Bruno API Tests for Bookhoard
|
||||
|
||||
This directory contains Bruno collection for testing the Bookmann API with comprehensive REST documentation.
|
||||
This directory contains Bruno collection for testing the Bookhoard API with comprehensive REST documentation.
|
||||
|
||||
## Setup
|
||||
|
||||
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"version": "1",
|
||||
"name": "Bookmann API",
|
||||
"name": "Bookhoard API",
|
||||
"type": "collection"
|
||||
}
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Bookmann provides full Calibre-compatible wireless sync for KOReader devices, enabling seamless reading progress, highlights, and notes synchronization.
|
||||
Bookhoard provides full Calibre-compatible wireless sync for KOReader devices, enabling seamless reading progress, highlights, and notes synchronization.
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Register Your Device
|
||||
|
||||
First, register your KOReader device with Bookmann:
|
||||
First, register your KOReader device with Bookhoard:
|
||||
|
||||
```bash
|
||||
POST /api/devices/register
|
||||
@@ -31,7 +31,7 @@ Visit the approval URL in your web browser (or scan the QR code) to authenticate
|
||||
### 3. Configure KOReader
|
||||
|
||||
In KOReader settings, set:
|
||||
- **Calibre wireless URL**: `https://your-bookmann-domain.com/api/sync/koreader`
|
||||
- **Calibre wireless URL**: `https://your-bookhoard-domain.com/api/sync/koreader`
|
||||
- **Enable wireless sync**: ON
|
||||
- **Sync frequency**: Every page turn (recommended)
|
||||
|
||||
@@ -241,7 +241,7 @@ Syncs periodically to save bandwidth.
|
||||
|
||||
## Device Matching
|
||||
|
||||
Bookmann tries multiple strategies to match books:
|
||||
Bookhoard tries multiple strategies to match books:
|
||||
|
||||
1. **By UUID**: Most reliable if your book files have unique IDs (confidence: 1.0)
|
||||
2. **By SHA-256**: Hash-based matching for reliable identification (confidence: 0.9)
|
||||
@@ -251,7 +251,7 @@ Bookmann tries multiple strategies to match books:
|
||||
|
||||
### SHA-256 Matching (Phase 7 Enhancement)
|
||||
|
||||
Bookmann now supports SHA-256 hash matching for reliable book identification:
|
||||
Bookhoard now supports SHA-256 hash matching for reliable book identification:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -275,7 +275,7 @@ Bookmann now supports SHA-256 hash matching for reliable book identification:
|
||||
|
||||
### Device File Alias System
|
||||
|
||||
When a book is matched with a file path, Bookmann automatically creates a device file alias:
|
||||
When a book is matched with a file path, Bookhoard automatically creates a device file alias:
|
||||
|
||||
- **UUID + FilePath**: Creates alias with confidence 1.0
|
||||
- **SHA-256 + FilePath**: Creates alias with confidence 0.9
|
||||
@@ -359,7 +359,7 @@ Use the Bruno API collection in `/bruno/koreader/` to test endpoints:
|
||||
- `Sync Bookmarks.bru` - Test annotation sync
|
||||
|
||||
Required variables:
|
||||
- `baseUrl` - Your Bookmann server URL
|
||||
- `baseUrl` - Your Bookhoard server URL
|
||||
- `device_token` - Device authentication token
|
||||
- `book_uuid` - UUID of a test book
|
||||
|
||||
@@ -368,7 +368,7 @@ Required variables:
|
||||
- Compatible with Calibre wireless protocol
|
||||
- Supports EPUB CFI for precise locations
|
||||
- Handles reflowable and fixed-layout formats
|
||||
- Bidirectional sync (KOReader ↔ Bookmann)
|
||||
- Bidirectional sync (KOReader ↔ Bookhoard)
|
||||
- Real-time updates via WebSocket (coming in Phase 3b)
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -17,8 +17,8 @@
|
||||
"}",
|
||||
"",
|
||||
"// Verify Bookhoard UUID header",
|
||||
"const bookmannUUID = resp.headers.get('X-Bookhoard-UUID');",
|
||||
"tests['Bookhoard UUID present'] = bookmannUUID !== null;",
|
||||
"const bookhoardUUID = resp.headers.get('X-Bookhoard-UUID');",
|
||||
"tests['Bookhoard UUID present'] = bookhoardUUID !== null;",
|
||||
"",
|
||||
"// Verify content type",
|
||||
"const contentType = resp.headers.get('Content-Type');",
|
||||
|
||||
@@ -15,5 +15,5 @@ get {
|
||||
assert {
|
||||
response.status == 200
|
||||
response.headers["Content-Type"] contains "application/json"
|
||||
response.headers["Content-Disposition"] contains ".bookmann.json"
|
||||
response.headers["Content-Disposition"] contains ".bookhoard.json"
|
||||
}
|
||||
|
||||
@@ -15,7 +15,7 @@ get {
|
||||
assert {
|
||||
response.status == 200
|
||||
response.body.version == "1.0"
|
||||
response.body.bookmann exists()
|
||||
response.body.bookhoard exists()
|
||||
response.body.books exists()
|
||||
response.body.collections exists()
|
||||
}
|
||||
|
||||
+21
-21
@@ -5,7 +5,7 @@ This document describes the sidecar configuration system that enables easy devic
|
||||
|
||||
## 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:
|
||||
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
|
||||
@@ -32,7 +32,7 @@ Authorization: Bearer {{user_token}}
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"bookmann": {
|
||||
"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",
|
||||
@@ -42,7 +42,7 @@ Authorization: Bearer {{user_token}}
|
||||
},
|
||||
"books": {
|
||||
"sha256:abc123...": {
|
||||
"bookmann_uuid": "uuid-123",
|
||||
"bookhoard_uuid": "uuid-123",
|
||||
"title": "The Hobbit",
|
||||
"author": "J.R.R. Tolkien",
|
||||
"available_formats": ["epub", "kepub"],
|
||||
@@ -66,7 +66,7 @@ Authorization: Bearer {{user_token}}
|
||||
### 2. Download Device Sidecar File
|
||||
**Endpoint**: `GET /api/devices/:device_id/sidecar/download`
|
||||
|
||||
**Description**: Downloads a `.bookmann.json` configuration file for device setup.
|
||||
**Description**: Downloads a `.bookhoard.json` configuration file for device setup.
|
||||
|
||||
**Request Headers**:
|
||||
```
|
||||
@@ -76,7 +76,7 @@ Authorization: Bearer {{user_token}}
|
||||
**Response** (200 OK):
|
||||
```
|
||||
Content-Type: application/json
|
||||
Content-Disposition: attachment; filename="MyKoboClara.bookmann.json"
|
||||
Content-Disposition: attachment; filename="MyKoboClara.bookhoard.json"
|
||||
```
|
||||
|
||||
File contains formatted JSON (pretty-printed) suitable for:
|
||||
@@ -97,9 +97,9 @@ 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"
|
||||
"base_url": "https://bookhoard.example.com",
|
||||
"opds_base_url": "https://bookhoard.example.com/opds",
|
||||
"api_base_url": "https://bookhoard.example.com/api"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -117,9 +117,9 @@ 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"
|
||||
"base_url": "https://bookhoard.example.com",
|
||||
"opds_base_url": "https://bookhoard.example.com/opds",
|
||||
"api_base_url": "https://bookhoard.example.com/api"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -136,7 +136,7 @@ Content-Type: application/json
|
||||
### Version
|
||||
Always "1.0" - enables future format changes
|
||||
|
||||
### Bookmann Section
|
||||
### Bookhoard Section
|
||||
Contains device connection information:
|
||||
- **opds_catalog**: Full URL to device's OPDS catalog
|
||||
- **sync_api**: Sync API endpoint
|
||||
@@ -147,8 +147,8 @@ Contains device connection information:
|
||||
|
||||
### Books Section
|
||||
Map of book identifiers to book metadata:
|
||||
- **Key**: SHA-256 hash (preferred) or Bookmann UUID
|
||||
- **bookmann_uuid**: Canonical Bookmann UUID
|
||||
- **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")
|
||||
@@ -157,22 +157,22 @@ Map of book identifiers to book metadata:
|
||||
|
||||
### Collections Section
|
||||
Array of collection definitions:
|
||||
- **name**: Collection name in Bookmann
|
||||
- **name**: Collection name in Bookhoard
|
||||
- **shelf_mapping**: Device-specific shelf name (e.g., "Science Fiction")
|
||||
- **book_ids**: Array of Bookmann UUIDs in collection
|
||||
- **book_ids**: Array of Bookhoard UUIDs in collection
|
||||
|
||||
## Device Setup Workflow
|
||||
|
||||
### Kobo E-Reader
|
||||
|
||||
1. **Download Configuration**
|
||||
- Log into Bookmann web UI
|
||||
- Log into Bookhoard web UI
|
||||
- Navigate to Device Management
|
||||
- Click "Download Configuration" for your Kobo device
|
||||
- File saves as `MyKoboClara.bookmann.json`
|
||||
- File saves as `MyKoboClara.bookhoard.json`
|
||||
|
||||
2. **Manual Configuration** (if needed)
|
||||
- Copy `.bookmann.json` to Kobo device
|
||||
- Copy `.bookhoard.json` to Kobo device
|
||||
- Kobo can import configuration automatically
|
||||
|
||||
3. **OPDS Setup** (Recommended)
|
||||
@@ -224,7 +224,7 @@ Set these in your Bruno collection:
|
||||
## Testing Scenarios
|
||||
|
||||
### Scenario 1: New Kobo Device
|
||||
1. Register Kobo device in Bookmann
|
||||
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
|
||||
@@ -237,7 +237,7 @@ Set these in your Bruno collection:
|
||||
4. Re-configure device with updated file
|
||||
|
||||
### Scenario 3: Collection Management
|
||||
1. Create collections in Bookmann
|
||||
1. Create collections in Bookhoard
|
||||
2. Set up device-specific shelf mappings
|
||||
3. Sidecar automatically includes collection info
|
||||
4. Device shelves reflect collection structure
|
||||
|
||||
@@ -7,9 +7,9 @@ meta {
|
||||
put {
|
||||
url: {{base_url}}/api/system/config
|
||||
body: json({
|
||||
"base_url": "https://bookmann.example.com",
|
||||
"opds_base_url": "https://bookmann.example.com/opds",
|
||||
"api_base_url": "https://bookmann.example.com/api"
|
||||
"base_url": "https://bookhoard.example.com",
|
||||
"opds_base_url": "https://bookhoard.example.com/opds",
|
||||
"api_base_url": "https://bookhoard.example.com/api"
|
||||
})
|
||||
auth: {
|
||||
type: bearer
|
||||
|
||||
Reference in New Issue
Block a user