Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

Update documentation and API tests: Bookmann → Bookhoard

Browse Source 
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:
john-okeefe
2026-02-01 16:20:56 -05:00
parent 547bc6f8f8
commit ff96ffa92d
19 changed files with 103 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bruno/README.md
+2 -2
View File
@@ -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 ## Setup
bruno/bruno.json
+1 -1
View File
@@ -1,5 +1,5 @@
{ {
"version": "1", "version": "1",
"name": "Bookmann API", "name": "Bookhoard API",
"type": "collection" "type": "collection"
} }
bruno/koreader/README.md
+8 -8
View File
@@ -2,13 +2,13 @@
## Overview ## 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 ## Setup
### 1. Register Your Device ### 1. Register Your Device
First, register your KOReader device with Bookmann: First, register your KOReader device with Bookhoard:
```bash ```bash
POST /api/devices/register 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 ### 3. Configure KOReader
In KOReader settings, set: 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 - **Enable wireless sync**: ON
- **Sync frequency**: Every page turn (recommended) - **Sync frequency**: Every page turn (recommended)
@@ -241,7 +241,7 @@ Syncs periodically to save bandwidth.
## Device Matching ## 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) 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) 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) ### 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 ```json
{ {
@@ -275,7 +275,7 @@ Bookmann now supports SHA-256 hash matching for reliable book identification:
### Device File Alias System ### 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 - **UUID + FilePath**: Creates alias with confidence 1.0
- **SHA-256 + FilePath**: Creates alias with confidence 0.9 - **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 - `Sync Bookmarks.bru` - Test annotation sync
Required variables: Required variables:
- `baseUrl` - Your Bookmann server URL - `baseUrl` - Your Bookhoard server URL
- `device_token` - Device authentication token - `device_token` - Device authentication token
- `book_uuid` - UUID of a test book - `book_uuid` - UUID of a test book
@@ -368,7 +368,7 @@ Required variables:
- Compatible with Calibre wireless protocol - Compatible with Calibre wireless protocol
- Supports EPUB CFI for precise locations - Supports EPUB CFI for precise locations
- Handles reflowable and fixed-layout formats - Handles reflowable and fixed-layout formats
- Bidirectional sync (KOReader ↔ Bookmann) - Bidirectional sync (KOReader ↔ Bookhoard)
- Real-time updates via WebSocket (coming in Phase 3b) - Real-time updates via WebSocket (coming in Phase 3b)
## Next Steps ## Next Steps
bruno/opds/Download Book KEPUB (On-the-fly Conversion).bru
+2 -2
View File
@@ -17,8 +17,8 @@
"}", "}",
"", "",
"// Verify Bookhoard UUID header", "// Verify Bookhoard UUID header",
"const bookmannUUID = resp.headers.get('X-Bookhoard-UUID');", "const bookhoardUUID = resp.headers.get('X-Bookhoard-UUID');",
"tests['Bookhoard UUID present'] = bookmannUUID !== null;", "tests['Bookhoard UUID present'] = bookhoardUUID !== null;",
"", "",
"// Verify content type", "// Verify content type",
"const contentType = resp.headers.get('Content-Type');", "const contentType = resp.headers.get('Content-Type');",
bruno/sidecar/Download Device Sidecar File.bru
+1 -1
View File
@@ -15,5 +15,5 @@ get {
assert { assert {
response.status == 200 response.status == 200
response.headers["Content-Type"] contains "application/json" response.headers["Content-Type"] contains "application/json"
response.headers["Content-Disposition"] contains ".bookmann.json" response.headers["Content-Disposition"] contains ".bookhoard.json"
} }
bruno/sidecar/Get Device Sidecar Config.bru
+1 -1
View File
@@ -15,7 +15,7 @@ get {
assert { assert {
response.status == 200 response.status == 200
response.body.version == "1.0" response.body.version == "1.0"
response.body.bookmann exists() response.body.bookhoard exists()
response.body.books exists() response.body.books exists()
response.body.collections exists() response.body.collections exists()
} }
bruno/sidecar/README.md
+21 -21
View File
@@ -5,7 +5,7 @@ This document describes the sidecar configuration system that enables easy devic
## What is a Sidecar File? ## 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 - OPDS catalog URL for wireless book browsing
- Sync API endpoints for progress sync - Sync API endpoints for progress sync
- Book inventory with SHA-256 hashes - Book inventory with SHA-256 hashes
@@ -32,7 +32,7 @@ Authorization: Bearer {{user_token}}
```json ```json
{ {
"version": "1.0", "version": "1.0",
"bookmann": { "bookhoard": {
"opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog", "opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog",
"sync_api": "http://192.168.1.100:8765/api/sync/kobo", "sync_api": "http://192.168.1.100:8765/api/sync/kobo",
"opds_base_url": "http://192.168.1.100:8765/opds", "opds_base_url": "http://192.168.1.100:8765/opds",
@@ -42,7 +42,7 @@ Authorization: Bearer {{user_token}}
}, },
"books": { "books": {
"sha256:abc123...": { "sha256:abc123...": {
"bookmann_uuid": "uuid-123", "bookhoard_uuid": "uuid-123",
"title": "The Hobbit", "title": "The Hobbit",
"author": "J.R.R. Tolkien", "author": "J.R.R. Tolkien",
"available_formats": ["epub", "kepub"], "available_formats": ["epub", "kepub"],
@@ -66,7 +66,7 @@ Authorization: Bearer {{user_token}}
### 2. Download Device Sidecar File ### 2. Download Device Sidecar File
**Endpoint**: `GET /api/devices/:device_id/sidecar/download` **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**: **Request Headers**:
``` ```
@@ -76,7 +76,7 @@ Authorization: Bearer {{user_token}}
**Response** (200 OK): **Response** (200 OK):
``` ```
Content-Type: application/json 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: File contains formatted JSON (pretty-printed) suitable for:
@@ -97,9 +97,9 @@ Authorization: Bearer {{admin_token}}
**Response** (200 OK): **Response** (200 OK):
```json ```json
{ {
"base_url": "https://bookmann.example.com", "base_url": "https://bookhoard.example.com",
"opds_base_url": "https://bookmann.example.com/opds", "opds_base_url": "https://bookhoard.example.com/opds",
"api_base_url": "https://bookmann.example.com/api" "api_base_url": "https://bookhoard.example.com/api"
} }
``` ```
@@ -117,9 +117,9 @@ Content-Type: application/json
**Request Body**: **Request Body**:
```json ```json
{ {
"base_url": "https://bookmann.example.com", "base_url": "https://bookhoard.example.com",
"opds_base_url": "https://bookmann.example.com/opds", "opds_base_url": "https://bookhoard.example.com/opds",
"api_base_url": "https://bookmann.example.com/api" "api_base_url": "https://bookhoard.example.com/api"
} }
``` ```
@@ -136,7 +136,7 @@ Content-Type: application/json
### Version ### Version
Always "1.0" - enables future format changes Always "1.0" - enables future format changes
### Bookmann Section ### Bookhoard Section
Contains device connection information: Contains device connection information:
- **opds_catalog**: Full URL to device's OPDS catalog - **opds_catalog**: Full URL to device's OPDS catalog
- **sync_api**: Sync API endpoint - **sync_api**: Sync API endpoint
@@ -147,8 +147,8 @@ Contains device connection information:
### Books Section ### Books Section
Map of book identifiers to book metadata: Map of book identifiers to book metadata:
- **Key**: SHA-256 hash (preferred) or Bookmann UUID - **Key**: SHA-256 hash (preferred) or Bookhoard UUID
- **bookmann_uuid**: Canonical Bookmann UUID - **bookhoard_uuid**: Canonical Bookhoard UUID
- **title**: Book title - **title**: Book title
- **author**: Book author - **author**: Book author
- **available_formats**: Array of formats ("epub", "kepub") - **available_formats**: Array of formats ("epub", "kepub")
@@ -157,22 +157,22 @@ Map of book identifiers to book metadata:
### Collections Section ### Collections Section
Array of collection definitions: Array of collection definitions:
- **name**: Collection name in Bookmann - **name**: Collection name in Bookhoard
- **shelf_mapping**: Device-specific shelf name (e.g., "Science Fiction") - **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 ## Device Setup Workflow
### Kobo E-Reader ### Kobo E-Reader
1. **Download Configuration** 1. **Download Configuration**
- Log into Bookmann web UI - Log into Bookhoard web UI
- Navigate to Device Management - Navigate to Device Management
- Click "Download Configuration" for your Kobo device - Click "Download Configuration" for your Kobo device
- File saves as `MyKoboClara.bookmann.json` - File saves as `MyKoboClara.bookhoard.json`
2. **Manual Configuration** (if needed) 2. **Manual Configuration** (if needed)
- Copy `.bookmann.json` to Kobo device - Copy `.bookhoard.json` to Kobo device
- Kobo can import configuration automatically - Kobo can import configuration automatically
3. **OPDS Setup** (Recommended) 3. **OPDS Setup** (Recommended)
@@ -224,7 +224,7 @@ Set these in your Bruno collection:
## Testing Scenarios ## Testing Scenarios
### Scenario 1: New Kobo Device ### Scenario 1: New Kobo Device
1. Register Kobo device in Bookmann 1. Register Kobo device in Bookhoard
2. Download sidecar configuration 2. Download sidecar configuration
3. Add OPDS catalog URL from sidecar to Kobo 3. Add OPDS catalog URL from sidecar to Kobo
4. Browse and download books wirelessly 4. Browse and download books wirelessly
@@ -237,7 +237,7 @@ Set these in your Bruno collection:
4. Re-configure device with updated file 4. Re-configure device with updated file
### Scenario 3: Collection Management ### Scenario 3: Collection Management
1. Create collections in Bookmann 1. Create collections in Bookhoard
2. Set up device-specific shelf mappings 2. Set up device-specific shelf mappings
3. Sidecar automatically includes collection info 3. Sidecar automatically includes collection info
4. Device shelves reflect collection structure 4. Device shelves reflect collection structure
bruno/sidecar/Update System Configuration.bru
+3 -3
View File
@@ -7,9 +7,9 @@ meta {
put { put {
url: {{base_url}}/api/system/config url: {{base_url}}/api/system/config
body: json({ body: json({
"base_url": "https://bookmann.example.com", "base_url": "https://bookhoard.example.com",
"opds_base_url": "https://bookmann.example.com/opds", "opds_base_url": "https://bookhoard.example.com/opds",
"api_base_url": "https://bookmann.example.com/api" "api_base_url": "https://bookhoard.example.com/api"
}) })
auth: { auth: {
type: bearer type: bearer
docs/API_REFERENCE.md
+4 -4
View File
@@ -657,7 +657,7 @@ Content-Type: application/json
{ {
"device_id": "uuid", "device_id": "uuid",
"registration_id": "registration-uuid", "registration_id": "registration-uuid",
"auth_url": "https://bookmann.com/devices/auth/confirm/abc123", "auth_url": "https://bookhoard.com/devices/auth/confirm/abc123",
"qr_code": "data:image/png;base64,iVBORw0KG...", "qr_code": "data:image/png;base64,iVBORw0KG...",
"expires_in": 300 "expires_in": 300
} }
@@ -681,9 +681,9 @@ Content-Type: application/json
"auth_token": "device-bearer-token...", "auth_token": "device-bearer-token...",
"device_id": "uuid", "device_id": "uuid",
"sync_endpoints": { "sync_endpoints": {
"progress": "https://bookmann.com/api/sync/progress", "progress": "https://bookhoard.com/api/sync/progress",
"metadata": "https://bookmann.com/api/sync/metadata", "metadata": "https://bookhoard.com/api/sync/metadata",
"annotations": "https://bookmann.com/api/sync/annotations" "annotations": "https://bookhoard.com/api/sync/annotations"
} }
} }
``` ```
docs/CONVERSION_SERVICE.md
+1 -1
View File
@@ -173,7 +173,7 @@ This test verifies:
**Solution**: **Solution**:
1. Check if kepubify or ebook-convert is installed 1. Check if kepubify or ebook-convert is installed
2. Verify EPUB file is valid and accessible 2. Verify EPUB file is valid and accessible
3. Check cache directory permissions: `/var/bookmann/cache/kepub` 3. Check cache directory permissions: `/var/bookhoard/cache/kepub`
4. Review conversion logs for specific error messages 4. Review conversion logs for specific error messages
### Cache Issues ### Cache Issues
docs/Code/bookmann/IMPLEMENTATION_PLAN.md
+36 -36
View File
@@ -238,16 +238,16 @@ CREATE TABLE device_catalogs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
device_id UUID REFERENCES devices(id) ON DELETE CASCADE, device_id UUID REFERENCES devices(id) ON DELETE CASCADE,
media_item_id UUID REFERENCES media_items(id) ON DELETE CASCADE, media_item_id UUID REFERENCES media_items(id) ON DELETE CASCADE,
bookmann_uuid UUID NOT NULL, bookhoard_uuid UUID NOT NULL,
kobo_content_id VARCHAR(255) NOT NULL, kobo_content_id VARCHAR(255) NOT NULL,
content_id_type VARCHAR(20), -- 'bookmann_uuid', 'kobo_generated', 'isbn_based' content_id_type VARCHAR(20), -- 'bookhoard_uuid', 'kobo_generated', 'isbn_based'
available BOOLEAN DEFAULT TRUE, available BOOLEAN DEFAULT TRUE,
delivery_date TIMESTAMP WITH TIME ZONE, delivery_date TIMESTAMP WITH TIME ZONE,
delivery_method VARCHAR(20), -- 'wireless', 'usb', 'manual' delivery_method VARCHAR(20), -- 'wireless', 'usb', 'manual'
UNIQUE(device_id, kobo_content_id) UNIQUE(device_id, kobo_content_id)
); );
CREATE INDEX idx_device_catalogs_bookmann ON device_catalogs(bookmann_uuid); CREATE INDEX idx_device_catalogs_bookhoard ON device_catalogs(bookhoard_uuid);
CREATE INDEX idx_device_catalogs_kobo ON device_catalogs(kobo_content_id); CREATE INDEX idx_device_catalogs_kobo ON device_catalogs(kobo_content_id);
``` ```
@@ -266,9 +266,9 @@ CREATE TABLE system_config (
-- Pre-seeded values -- Pre-seeded values
INSERT INTO system_config (key, value) VALUES INSERT INTO system_config (key, value) VALUES
('base_url', 'https://bookmann.example.com'), ('base_url', 'https://bookhoard.example.com'),
('opds_base_url', 'https://bookmann.example.com/opds'), ('opds_base_url', 'https://bookhoard.example.com/opds'),
('api_base_url', 'https://bookmann.example.com/api'); ('api_base_url', 'https://bookhoard.example.com/api');
``` ```
### Table: opds_tokens (NEW) ### Table: opds_tokens (NEW)
@@ -345,7 +345,7 @@ Query Bookhoard for a book by multiple identifier types with confidence scoring.
"matches": [ "matches": [
{ {
"media_item_id": "uuid-123", "media_item_id": "uuid-123",
"bookmann_uuid": "uuid-123", "bookhoard_uuid": "uuid-123",
"confidence": 1.0, "confidence": 1.0,
"match_method": "uuid_match" "match_method": "uuid_match"
} }
@@ -663,7 +663,7 @@ Main OPDS 1.2 catalog feed.
<link rel="start" href="http://192.168.1.100:8765/opds/devices/kobo-id/nav"/> <link rel="start" href="http://192.168.1.100:8765/opds/devices/kobo-id/nav"/>
<entry> <entry>
<id>urn:uuid:bookmann-uuid-123</id> <id>urn:uuid:bookhoard-uuid-123</id>
<dc:title>The Hobbit</dc:title> <dc:title>The Hobbit</dc:title>
<dc:creator>J.R.R. Tolkien</dc:creator> <dc:creator>J.R.R. Tolkien</dc:creator>
<updated>2026-01-31T10:00:00Z</updated> <updated>2026-01-31T10:00:00Z</updated>
@@ -683,14 +683,14 @@ Main OPDS 1.2 catalog feed.
rel="alternate"/> rel="alternate"/>
<!-- Canonical ID for progress matching --> <!-- Canonical ID for progress matching -->
<dc:identifier id="bookmann">uuid-123</dc:identifier> <dc:identifier id="bookhoard">uuid-123</dc:identifier>
<!-- Hash for sidecar matching --> <!-- Hash for sidecar matching -->
<meta property="bookmann:sha256">abc123...</meta> <meta property="bookhoard:sha256">abc123...</meta>
<!-- Collections as categories --> <!-- Collections as categories -->
<category scheme="http://bookmann.example.com/collections">Science Fiction</category> <category scheme="http://bookhoard.example.com/collections">Science Fiction</category>
<category scheme="http://bookmann.example.com/collections">Reading</category> <category scheme="http://bookhoard.example.com/collections">Reading</category>
</entry> </entry>
<!-- More entries... --> <!-- More entries... -->
@@ -709,7 +709,7 @@ OPDS acquisition search endpoint.
<id>urn:uuid:device-id</id> <id>urn:uuid:device-id</id>
<entry> <entry>
<id>urn:uuid:bookmann-uuid-123</id> <id>urn:uuid:bookhoard-uuid-123</id>
<dc:title>The Hobbit</dc:title> <dc:title>The Hobbit</dc:title>
<dc:creator>J.R.R. Tolkien</dc:creator> <dc:creator>J.R.R. Tolkien</dc:creator>
<updated>2026-01-31T10:00:00Z</updated> <updated>2026-01-31T10:00:00Z</updated>
@@ -854,8 +854,8 @@ Kobo progress sync with ContentId mapping (enhanced).
catalog, err := db.GetDeviceCatalogByKoboContentId(ctx, contentId) catalog, err := db.GetDeviceCatalogByKoboContentId(ctx, contentId)
if err == nil && catalog.Valid { if err == nil && catalog.Valid {
// Found! Use canonical Bookhoard UUID // Found! Use canonical Bookhoard UUID
bookmannUUID = catalog.BookhoardUUID bookhoardUUID = catalog.BookhoardUUID
return bookmannUUID, nil return bookhoardUUID, nil
} }
// Step 2: ContentId not found - try SHA-256 (if looks like hash) // Step 2: ContentId not found - try SHA-256 (if looks like hash)
@@ -988,13 +988,13 @@ KOReader annotations sync with SHA-256 support.
#### GET `/api/sync/sidecar/:deviceId` #### GET `/api/sync/sidecar/:deviceId`
Download unified `.bookmann.json` configuration file. Download unified `.bookhoard.json` configuration file.
**Response**: **Response**:
```json ```json
{ {
"version": "1.0", "version": "1.0",
"bookmann": { "bookhoard": {
"opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog", "opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog",
"sync_api": "http://192.168.1.100:8765/api/sync/kobo", "sync_api": "http://192.168.1.100:8765/api/sync/kobo",
"opds_base_url": "http://192.168.1.100:8765/opds", "opds_base_url": "http://192.168.1.100:8765/opds",
@@ -1003,7 +1003,7 @@ Download unified `.bookmann.json` configuration file.
}, },
"books": { "books": {
"sha256:abc123...": { "sha256:abc123...": {
"bookmann_uuid": "uuid-123", "bookhoard_uuid": "uuid-123",
"title": "The Hobbit", "title": "The Hobbit",
"author": "J.R.R. Tolkien", "author": "J.R.R. Tolkien",
"available_formats": ["epub", "kepub"] "available_formats": ["epub", "kepub"]
@@ -1034,9 +1034,9 @@ Get system-wide configuration.
```json ```json
{ {
"config": { "config": {
"base_url": "https://bookmann.example.com", "base_url": "https://bookhoard.example.com",
"opds_base_url": "https://bookmann.example.com/opds", "opds_base_url": "https://bookhoard.example.com/opds",
"api_base_url": "https://bookmann.example.com/api", "api_base_url": "https://bookhoard.example.com/api",
"auto_convert_kepub": true, "auto_convert_kepub": true,
"default_opds_refresh_interval": 3600 "default_opds_refresh_interval": 3600
} }
@@ -1219,7 +1219,7 @@ func EvaluateRules(mediaItem MediaItem, rules []Rule) []RuleEvaluation {
**OPDS Response Structure (OPDS 1.2)**: **OPDS Response Structure (OPDS 1.2)**:
```xml ```xml
<entry> <entry>
<id>urn:uuid:bookmann-uuid-123</id> <id>urn:uuid:bookhoard-uuid-123</id>
<dc:title>The Hobbit</dc:title> <dc:title>The Hobbit</dc:title>
<dc:creator>J.R.R. Tolkien</dc:creator> <dc:creator>J.R.R. Tolkien</dc:creator>
<updated>2026-01-31T10:00:00Z</updated> <updated>2026-01-31T10:00:00Z</updated>
@@ -1238,15 +1238,15 @@ func EvaluateRules(mediaItem MediaItem, rules []Rule) []RuleEvaluation {
rel="alternate"/> rel="alternate"/>
<!-- Canonical ID for progress matching --> <!-- Canonical ID for progress matching -->
<dc:identifier id="bookmann">uuid-123</dc:identifier> <dc:identifier id="bookhoard">uuid-123</dc:identifier>
<!-- Hash for sidecar matching (format-specific if available) --> <!-- Hash for sidecar matching (format-specific if available) -->
<meta property="bookmann:sha256">abc123...</meta> <meta property="bookhoard:sha256">abc123...</meta>
<meta property="bookmann:kepub_sha256">xyz789...</meta> <meta property="bookhoard:kepub_sha256">xyz789...</meta>
<!-- Collections as categories --> <!-- Collections as categories -->
<category scheme="http://bookmann.example.com/collections">Science Fiction</category> <category scheme="http://bookhoard.example.com/collections">Science Fiction</category>
<category scheme="http://bookmann.example.com/collections">Reading</category> <category scheme="http://bookhoard.example.com/collections">Reading</category>
</entry> </entry>
``` ```
@@ -1367,7 +1367,7 @@ if book.FilePath != "" {
```json ```json
{ {
"version": "1.0", "version": "1.0",
"bookmann": { "bookhoard": {
"opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog", "opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog",
"sync_api": "http://192.168.1.100:8765/api/sync/kobo", "sync_api": "http://192.168.1.100:8765/api/sync/kobo",
"opds_base_url": "http://192.168.1.100:8765/opds", "opds_base_url": "http://192.168.1.100:8765/opds",
@@ -1376,7 +1376,7 @@ if book.FilePath != "" {
}, },
"books": { "books": {
"sha256:abc123...": { "sha256:abc123...": {
"bookmann_uuid": "uuid-123", "bookhoard_uuid": "uuid-123",
"title": "The Hobbit", "title": "The Hobbit",
"author": "J.R.R. Tolkien", "author": "J.R.R. Tolkien",
"available_formats": ["epub", "kepub"] "available_formats": ["epub", "kepub"]
@@ -1443,14 +1443,14 @@ if book.FilePath != "" {
1. Log into Bookhoard web UI 1. Log into Bookhoard web UI
2. Go to Device Management → Your Kobo device 2. Go to Device Management → Your Kobo device
3. Click "Download Configuration" button 3. Click "Download Configuration" button
4. File downloads as `.bookmann.json` 4. File downloads as `.bookhoard.json`
``` ```
**Step 2: Configure Kobo for OPDS** **Step 2: Configure Kobo for OPDS**
``` ```
1. On Kobo, go to Settings → Sync & Backup 1. On Kobo, go to Settings → Sync & Backup
2. Tap "Add Content Server" or "Add OPDS Feed" 2. Tap "Add Content Server" or "Add OPDS Feed"
3. Enter URL from `.bookmann.json`: 3. Enter URL from `.bookhoard.json`:
http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog
4. Kobo will automatically: 4. Kobo will automatically:
- Connect to Bookhoard - Connect to Bookhoard
@@ -1487,7 +1487,7 @@ Same as Kobo setup above
``` ```
1. Open KOReader settings 1. Open KOReader settings
2. Enable "OPDS catalog" in network/synchronization section 2. Enable "OPDS catalog" in network/synchronization section
3. Enter OPDS URL from `.bookmann.json`: 3. Enter OPDS URL from `.bookhoard.json`:
http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog
4. KOReader will automatically: 4. KOReader will automatically:
- Connect to Bookhoard catalog - Connect to Bookhoard catalog
@@ -1521,7 +1521,7 @@ Place in KOReader's config directory
**Step 3: Use Sidecar for Progress Sync** **Step 3: Use Sidecar for Progress Sync**
``` ```
KOReader plugin reads .bookmann.json KOReader plugin reads .bookhoard.json
→ Matches local files to Bookhoard UUIDs via SHA-256 → Matches local files to Bookhoard UUIDs via SHA-256
→ Syncs progress using canonical UUIDs → Syncs progress using canonical UUIDs
→ Works offline → Works offline
@@ -1622,7 +1622,7 @@ Can be: Public (no authentication required)
### Manual Testing Checklist ### Manual Testing Checklist
**Kobo Workflow**: **Kobo Workflow**:
- [ ] Download `.bookmann.json` from web UI - [ ] Download `.bookhoard.json` from web UI
- [ ] Transfer to Kobo via USB - [ ] Transfer to Kobo via USB
- [ ] Configure OPDS URL on Kobo - [ ] Configure OPDS URL on Kobo
- [ ] Browse catalog wirelessly - [ ] Browse catalog wirelessly
@@ -1631,7 +1631,7 @@ Can be: Public (no authentication required)
- [ ] Verify progress syncs to Bookhoard - [ ] Verify progress syncs to Bookhoard
**KOReader Workflow**: **KOReader Workflow**:
- [ ] Download `.bookmann.json` from web UI - [ ] Download `.bookhoard.json` from web UI
- [ ] Configure OPDS URL in KOReader - [ ] Configure OPDS URL in KOReader
- [ ] Browse catalog wirelessly - [ ] Browse catalog wirelessly
- [ ] Download book - [ ] Download book
@@ -1669,7 +1669,7 @@ Can be: Public (no authentication required)
- **Media Item Formats**: Tracks all format versions with their hashes. Pre-convert EPUB to KEPUB during scan for optimal performance. - **Media Item Formats**: Tracks all format versions with their hashes. Pre-convert EPUB to KEPUB during scan for optimal performance.
- **System Config**: Key-value store for system-wide settings (base_url, opds_base_url, api_base_url). Enables flexible deployment. - **System Config**: Key-value store for system-wide settings (base_url, opds_base_url, api_base_url). Enables flexible deployment.
- **OPDS Tokens**: Per-device access tokens for OPDS catalog browsing. Optional - can also support user-scoped and admin tokens. - **OPDS Tokens**: Per-device access tokens for OPDS catalog browsing. Optional - can also support user-scoped and admin tokens.
- **Sidecar File**: `.bookmann.json` - Unified configuration file for devices. Contains OPDS URLs, sync API endpoints, book mappings, collection mappings. - **Sidecar File**: `.bookhoard.json` - Unified configuration file for devices. Contains OPDS URLs, sync API endpoints, book mappings, collection mappings.
- **Auto-Assign Rules**: Configurable criteria for automatically adding books to collections. Fields: genre, series, author, language, publisher, copyright_year, tags. Operators: equals, contains, starts_with, ends_with, greater_than, less_than. - **Auto-Assign Rules**: Configurable criteria for automatically adding books to collections. Fields: genre, series, author, language, publisher, copyright_year, tags. Operators: equals, contains, starts_with, ends_with, greater_than, less_than.
- **Sync Direction**: For device shelf mappings. 'bidirectional' (sync both ways), 'book_to_hoard' (send to device), 'device_to_hoard' (read from device), 'none' (no sync). - **Sync Direction**: For device shelf mappings. 'bidirectional' (sync both ways), 'book_to_hoard' (send to device), 'device_to_hoard' (read from device), 'none' (no sync).
- **View Settings**: Per-device preferences for how collections are displayed (grid vs list, which collections are visible). - **View Settings**: Per-device preferences for how collections are displayed (grid vs list, which collections are visible).
docs/PHASE1_COMPLETION_SUMMARY.md
+1 -1
View File
@@ -161,7 +161,7 @@ The conversion service handles multiple failure scenarios:
### Build Verification ### Build Verification
```bash ```bash
go build -o /tmp/bookmann-test ./cmd/server go build -o /tmp/bookhoard-test ./cmd/server
# Success: Exit code 0 # Success: Exit code 0
``` ```
docs/PHASE2_COMPLETION_SUMMARY.md
+2 -2
View File
@@ -110,7 +110,7 @@ Get matching suggestions for a specific unlinked book.
"suggestions": [ "suggestions": [
{ {
"media_item_id": "uuid-2", "media_item_id": "uuid-2",
"bookmann_uuid": "uuid-2", "bookhoard_uuid": "uuid-2",
"confidence": 0.95, "confidence": 0.95,
"match_method": "sha256_match" "match_method": "sha256_match"
} }
@@ -321,7 +321,7 @@ With default threshold of 0.8, only matches with 80%+ confidence are auto-linked
### Build Verification ### Build Verification
```bash ```bash
cd /home/nymusicman/Code/bookmann cd /home/nymusicman/Code/bookhoard
go build ./cmd/server # ✅ Successful go build ./cmd/server # ✅ Successful
cd internal/database && sqlc generate # ✅ Successful cd internal/database && sqlc generate # ✅ Successful
cd templates && templ generate # ✅ Successful cd templates && templ generate # ✅ Successful
docs/SECURITY_AUDIT.md
+1 -1
View File
@@ -515,4 +515,4 @@ Audit Logs: 180 days
**Audit Completed By**: Bookhoard Security Team **Audit Completed By**: Bookhoard Security Team
**Next Audit**: Within 3 months of production deployment **Next Audit**: Within 3 months of production deployment
**Questions**: security@bookmann.example.com **Questions**: security@bookhoard.example.com
docs/SECURITY_ENHANCEMENTS.md
+4 -4
View File
@@ -284,8 +284,8 @@ e.Pre(
```go ```go
import ( import (
"bookmann/internal/middleware" "bookhoard/internal/middleware"
"bookmann/internal/handlers" "bookhoard/internal/handlers"
) )
func main() { func main() {
@@ -452,7 +452,7 @@ MAX_DEVICES_PER_USER=10
**Step 3: Update Middleware Chain** **Step 3: Update Middleware Chain**
```go ```go
// Add to main.go middleware chain // Add to main.go middleware chain
import "bookmann/internal/middleware" import "bookhoard/internal/middleware"
// In main(): // In main():
securityMiddleware := middleware.HTTPSProtectionMiddleware(true, "8443") securityMiddleware := middleware.HTTPSProtectionMiddleware(true, "8443")
@@ -594,4 +594,4 @@ While the system is production-ready, you may consider:
**Implementation Completed**: January 31, 2026 **Implementation Completed**: January 31, 2026
**Next Review**: Within 3 months **Next Review**: Within 3 months
**Questions**: security@bookmann.example.com **Questions**: security@bookhoard.example.com
docs/SYNC_USER_GUIDE.md
+7 -7
View File
@@ -94,7 +94,7 @@
- Device will receive authentication token - Device will receive authentication token
4. **Configure Sync**: 4. **Configure Sync**:
- Enter the sync URL provided (e.g., `https://bookmann.example.com/api/sync/koreader`) - Enter the sync URL provided (e.g., `https://bookhoard.example.com/api/sync/koreader`)
- Enable auto-sync - Enable auto-sync
- Set sync frequency (recommended: Every page turn) - Set sync frequency (recommended: Every page turn)
@@ -103,12 +103,12 @@
1. **From Your Device**: 1. **From Your Device**:
- Navigate to sync settings - Navigate to sync settings
- Select "Bookhoard Sync" - Select "Bookhoard Sync"
- Enter server URL: `https://bookmann.example.com` - Enter server URL: `https://bookhoard.example.com`
- Click "Register Device" - Click "Register Device"
- Device will display registration code - Device will display registration code
2. **In Your Browser**: 2. **In Your Browser**:
- Go to `https://bookmann.example.com/devices/approve` - Go to `https://bookhoard.example.com/devices/approve`
- Enter registration code - Enter registration code
- Approve the device - Approve the device
@@ -505,13 +505,13 @@ A: Yes, HTTPS/TLS 1.3 for all sync traffic.
- **Issues**: Report bugs at GitHub Issues - **Issues**: Report bugs at GitHub Issues
- **Discussions**: Join GitHub Discussions - **Discussions**: Join GitHub Discussions
- **Email**: support@bookmann.example.com - **Email**: support@bookhoard.example.com
### Community ### Community
- **Forum**: community.bookmann.example.com - **Forum**: community.bookhoard.example.com
- **Matrix**: #bookmann:matrix.org - **Matrix**: #bookhoard:matrix.org
- **Discord**: discord.gg/bookmann - **Discord**: discord.gg/bookhoard
--- ---
docs/TESTING.md
+5 -5
View File
@@ -57,7 +57,7 @@ cmd/server/tests/
export DATABASE_PASSWORD=postgres export DATABASE_PASSWORD=postgres
# Option 2: Use DATABASE_URL for containerized testing # Option 2: Use DATABASE_URL for containerized testing
export DATABASE_URL="postgresql://user:pass@localhost:5432/bookmann" export DATABASE_URL="postgresql://user:pass@localhost:5432/bookhoard"
``` ```
2. **Dependencies**: Ensure all Go dependencies are installed 2. **Dependencies**: Ensure all Go dependencies are installed
@@ -95,8 +95,8 @@ go test -v -run TestAnalyticsReadingStats
```bash ```bash
# Build and run tests in Docker container # Build and run tests in Docker container
podman-compose up -d db podman-compose up -d db
podman build -t bookmann-test . podman build -t bookhoard-test .
podman run --network bookmann_default -e DATABASE_URL="postgresql://postgres:postgres@db:5432/bookmann" bookmann-test go test ./cmd/server/tests/ -v podman run --network bookhoard_default -e DATABASE_URL="postgresql://postgres:postgres@db:5432/bookhoard" bookhoard-test go test ./cmd/server/tests/ -v
``` ```
### Test Modes ### Test Modes
@@ -452,7 +452,7 @@ jobs:
postgres: postgres:
image: postgres:15 image: postgres:15
env: env:
POSTGRES_DB: bookmann POSTGRES_DB: bookhoard
POSTGRES_USER: postgres POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres POSTGRES_PASSWORD: postgres
options: >- options: >-
@@ -469,7 +469,7 @@ jobs:
- name: Run integration tests - name: Run integration tests
env: env:
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/bookmann DATABASE_URL: postgresql://postgres:postgres@localhost:5432/bookhoard
run: | run: |
cd cmd/server/tests cd cmd/server/tests
go test -v -race -coverprofile=coverage.out go test -v -race -coverprofile=coverage.out
docs/devices/KOBO_SETUP.md
+2 -2
View File
@@ -409,7 +409,7 @@ If you're running Bookhoard with a custom domain or port:
```ini ```ini
[Sync] [Sync]
# Custom domain # Custom domain
ServerURL=https://bookmann.example.com/api/sync/kobo ServerURL=https://bookhoard.example.com/api/sync/kobo
# Custom port # Custom port
ServerURL=http://192.168.1.100:9000/api/sync/kobo ServerURL=http://192.168.1.100:9000/api/sync/kobo
@@ -424,7 +424,7 @@ If you have SSL/TLS configured on Bookhoard:
```ini ```ini
[Sync] [Sync]
ServerURL=https://bookmann.yourdomain.com/api/sync/kobo ServerURL=https://bookhoard.yourdomain.com/api/sync/kobo
``` ```
Kobo will automatically trust the certificate if properly configured. Kobo will automatically trust the certificate if properly configured.
docs/devices/KOREADER_SETUP.md
+1 -1
View File
@@ -69,7 +69,7 @@ Before you begin, make sure you have:
Find your Bookhoard instance URL. This will typically be one of: Find your Bookhoard instance URL. This will typically be one of:
- **Local Network**: `http://YOUR_COMPUTER_IP:8765` - **Local Network**: `http://YOUR_COMPUTER_IP:8765`
- **Localhost (if testing)**: `http://localhost:8765` - **Localhost (if testing)**: `http://localhost:8765`
- **Domain (if configured)**: `https://bookmann.yourdomain.com` - **Domain (if configured)**: `https://bookhoard.yourdomain.com`
### Step 2: Register Your Device in Bookhoard ### Step 2: Register Your Device in Bookhoard