docs: update references for new configuration structure

- Update README.md with simplified documentation links - Update docs/API_REFERENCE.md formatting and structure - Update docs/SYNC_USER_GUIDE.md with minor improvements These updates reflect the reorganized documentation structure and new configuration approach with defaults in docker-compose.yml.
2026-02-01 17:34:21 -05:00
parent 7d1fc546a8
commit 555bd0df15
3 changed files with 497 additions and 629 deletions
@@ -12,12 +12,16 @@ Complete API documentation for Bookhoard v1.0 with Universal Cross-Platform Sync
 6. [Notes & Highlights](#notes--highlights)
 7. [Ratings](#ratings)
 8. [Device Management](#device-management)
-9. [Sync Protocol - KOReader](#sync-protocol---koreader)
-10. [Sync Protocol - Kobo](#sync-protocol---kobo)
-11. [Universal Progress](#universal-progress)
-12. [Conflicts](#conflicts)
-13. [Sync Queue](#sync-queue)
-14. [WebSocket](#websocket)
+9. [Analytics](#analytics)
+10. [Book Matching & Linking](#book-matching--linking)
+11. [Collections](#collections) → See [COLLECTIONS_API.md](COLLECTIONS_API.md)
+12. [OPDS](#opds-open-publication-distribution-system)
+13. [Sync Protocol - KOReader](#sync-protocol---koreader)
+14. [Sync Protocol - Kobo](#sync-protocol---kobo)
+15. [Universal Progress](#universal-progress)
+16. [Conflicts](#conflicts)
+17. [Sync Queue](#sync-queue)
+18. [WebSocket](#websocket)

 ## Base URL

@@ -735,6 +739,323 @@ DELETE /api/devices/{device_id}
 Authorization: Bearer <token>
 ```

+## Analytics
+
+### Get Reading Statistics
+
+```http
+GET /api/analytics/reading-stats?start_date={date}&end_date={date}
+Authorization: Bearer <token>
+```
+
+**Query Parameters**:
+- `start_date` (optional): Start date (ISO 8601 format)
+- `end_date` (optional): End date (ISO 8601 format)
+
+**Response** (200):
+```json
+{
+  "pages_read": 1250,
+  "books_completed": 5,
+  "reading_time_hours": 42.5,
+  "sessions_count": 28,
+  "average_session_minutes": 91
+}
+```
+
+### Get Device Usage Statistics
+
+```http
+GET /api/analytics/device-usage
+Authorization: Bearer <token>
+```
+
+**Response** (200):
+```json
+{
+  "devices": [
+    {
+      "device_id": "uuid",
+      "device_name": "My Kobo Clara",
+      "device_type": "kobo",
+      "sync_count": 145,
+      "last_sync": "2026-02-01T10:00:00Z",
+      "pages_synced": 890
+    }
+  ]
+}
+```
+
+### Get Popular Books
+
+```http
+GET /api/analytics/popular-books?limit={limit}
+Authorization: Bearer <token>
+```
+
+**Query Parameters**:
+- `limit` (optional): Number of results (default: 10)
+
+**Response** (200):
+```json
+{
+  "books": [
+    {
+      "media_item_id": "uuid",
+      "title": "Book Title",
+      "author": "Author Name",
+      "cover_image_path": "/covers/book.jpg",
+      "read_count": 15,
+      "average_rating": 8.5
+    }
+  ]
+}
+```
+
+## Book Matching & Linking
+
+### Query Books for Matching
+
+```http
+POST /api/sync/books/query
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "identifiers": ["isbn:978-0345391802", "uuid:abc-123"],
+  "sha256": "a1b2c3d4e5f6abc123...",
+  "title": "The Hobbit",
+  "author": "J.R.R. Tolkien",
+  "file_size": 2456789
+}
+```
+
+**Response** (200):
+```json
+{
+  "matches": [
+    {
+      "media_item_id": "uuid-123",
+      "bookhoard_uuid": "uuid-123",
+      "confidence": 1.0,
+      "match_method": "uuid_match"
+    }
+  ],
+  "action": "auto_link"
+}
+```
+
+### Bulk Link Books
+
+```http
+POST /api/sync/bulk-link-books
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "links": [
+    {
+      "unlinked_book_id": "uuid-1",
+      "media_item_id": "uuid-2",
+      "confidence_score": 1.0
+    }
+  ]
+}
+```
+
+**Response** (200):
+```json
+{
+  "results": [
+    {
+      "unlinked_book_id": "uuid-1",
+      "status": "success",
+      "media_item_id": "uuid-2"
+    }
+  ],
+  "total": 1,
+  "successful": 1,
+  "failed": 0
+}
+```
+
+### Auto-Link Books
+
+```http
+POST /api/sync/auto-link-books
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "confidence_threshold": 0.8,
+  "limit": 50
+}
+```
+
+**Response** (200):
+```json
+{
+  "auto_linked": 15,
+  "results": [
+    {
+      "unlinked_book_id": "uuid-1",
+      "title": "The Hobbit",
+      "matched_media_item_id": "uuid-2",
+      "confidence": 0.95,
+      "match_method": "sha256_match"
+    }
+  ]
+}
+```
+
+### Get Unlinked Book Suggestions
+
+```http
+GET /api/sync/unlinked-books/{id}/suggestions
+Authorization: Bearer <token>
+```
+
+**Response** (200):
+```json
+{
+  "unlinked_book_id": "uuid-1",
+  "title_from_device": "The Hobbit",
+  "sha256": "",
+  "suggestions": [
+    {
+      "media_item_id": "uuid-2",
+      "bookhoard_uuid": "uuid-2",
+      "confidence": 0.95,
+      "match_method": "sha256_match"
+    }
+  ],
+  "total_suggestions": 1,
+  "action": "auto_link"
+}
+```
+
+## Collections
+
+For complete collection management documentation, see **[COLLECTIONS_API.md](COLLECTIONS_API.md)**.
+
+**Quick Reference**:
+- `GET /api/collections` - List all collections
+- `POST /api/collections` - Create new collection
+- `GET /api/collections/{id}` - Get collection details
+- `PUT /api/collections/{id}` - Update collection
+- `DELETE /api/collections/{id}` - Delete collection
+- `POST /api/collections/test-rules` - Test auto-assign rules
+- `POST /api/collections/bulk-add-books` - Bulk add books to collections
+- `GET /api/collections/{id}/books` - Get books in collection
+
+**Features**:
+- Auto-assign rules based on genre, author, series, tags, language, publisher, year
+- Device shelf mappings (Kobo shelves, KOReader categories)
+- Test rules before applying
+- Bulk book operations
+
+## OPDS (Open Publication Distribution System)
+
+### Get Device Catalog
+
+```http
+GET /opds/devices/{deviceId}/catalog?page={page}&per_page={per_page}
+```
+
+**Query Parameters**:
+- `page` (optional): Page number (default: 1)
+- `per_page` (optional): Items per page (default: 50, max: 200)
+
+**Response** (200 - OPDS 1.2 XML):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom" 
+       xmlns:opds="http://opds-spec.org/2010/"
+       xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <id>urn:uuid:device-id</id>
+  <title>Bookhoard Library</title>
+  <updated>2026-02-01T12:00:00Z</updated>
+  
+  <link rel="self" href="http://localhost:8765/opds/devices/kobo-id/catalog"/>
+  <link rel="search" href="http://localhost:8765/opds/devices/kobo-id/search"/>
+  <link rel="start" href="http://localhost:8765/opds/devices/kobo-id/nav"/>
+  
+  <entry>
+    <id>urn:uuid:bookhoard-uuid-123</id>
+    <dc:title>The Hobbit</dc:title>
+    <dc:creator>J.R.R. Tolkien</dc:creator>
+    <updated>2026-02-01T10:00:00Z</updated>
+    
+    <link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123" 
+          type="application/epub+zip" 
+          rel="http://opds-spec.org/acquisition/open-access"/>
+    
+    <link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123?format=kepub" 
+          type="application/vnd.kobo+xml+zip" 
+          rel="alternate"/>
+    
+    <dc:identifier id="bookhoard">uuid-123</dc:identifier>
+    <meta property="bookhoard:sha256">abc123...</meta>
+  </entry>
+</feed>
+```
+
+### Download Book with Format Conversion
+
+```http
+GET /opds/devices/{deviceId}/download/{bookId}?format={format}
+```
+
+**Query Parameters**:
+- `format` (optional): Book format - `epub` (default), `kepub`
+
+**Response** (200):
+- Headers:
+  - `Content-Type`: `application/epub+zip` or `application/vnd.kobo+xml+zip`
+  - `Content-Disposition`: attachment; filename="The Hobbit.epub"
+  - `X-Bookhoard-UUID`: uuid-123
+  - `X-Bookhoard-SHA256`: abc123... (original hash)
+  - `X-Bookhoard-KEPUB-SHA256`: xyz789... (KEPUB hash if format=kepub)
+
+### Search OPDS Catalog
+
+```http
+GET /opds/devices/{deviceId}/search?q={query}
+```
+
+**Response** (200 - OPDS 1.2 XML with search results)
+
+### List Available Formats
+
+```http
+GET /opds/devices/{deviceId}/formats/{bookId}
+```
+
+**Response** (200):
+```json
+{
+  "media_item_id": "uuid-123",
+  "formats": [
+    {
+      "format_type": "epub",
+      "file_path": "/path/to/book.epub",
+      "file_sha256": "abc123...",
+      "file_size_bytes": 2456789,
+      "mime_type": "application/epub+zip",
+      "available": true
+    },
+    {
+      "format_type": "kepub",
+      "file_path": "/cache/book.kepub.epub",
+      "file_sha256": "xyz789...",
+      "file_size_bytes": 2478932,
+      "mime_type": "application/vnd.kobo+xml+zip",
+      "available": true
+    }
+  ]
+}
+```
+
 ## Sync Protocol - KOReader

 ### KOReader Progress Sync
@@ -4,10 +4,11 @@
 1. [What is Universal Sync?](#what-is-universal-sync)
 2. [Supported Devices](#supported-devices)
 3. [Getting Started](#getting-started)
-4. [Device Registration](#device-registration)
-5. [Sync Features](#sync-features)
-6. [Troubleshooting](#troubleshooting)
-7. [Best Practices](#best-practices)
+4. [Device Setup](#device-setup)
+5. [Using Sync Features](#using-sync-features)
+6. [Book Matching](#book-matching)
+7. [Managing Conflicts](#managing-conflicts)
+8. [Best Practices](#best-practices)

 ---

@@ -61,72 +62,83 @@

 ### Quick Start

-1. **Start Reading** - Open any book in the web interface or on your device
-2. **Turn Pages** - Progress syncs automatically
-3. **Switch Devices** - Pick up any other device - your progress is there!
+1. **Set up your first device** - See [Device Setup](#device-setup) below
+2. **Start reading** - Open any book in the web interface or on your device
+3. **Turn pages** - Progress syncs automatically
+4. **Switch devices** - Pick up any other device - your progress is there!

 ---

-## Device Registration
+## Device Setup

-### Step-by-Step Guide
+For detailed device configuration instructions, see the appropriate setup guide:

-#### Option 1: Web-Based Registration (Recommended)
+- **[Kobo Setup Guide](devices/KOBO_SETUP.md)** - Kobo e-reader configuration
+- **[KOReader Setup Guide](devices/KOREADER_SETUP.md)** - KOReader configuration

-1. **On Your Device**:
-   - Open your reading app (KOReader/Kobo)
-   - Navigate to sync settings
-   - Find "Bookhoard Sync" or "Calibre Sync"
-   - Copy your device identifier (hardware ID)
+### Quick Overview

-2. **In Your Browser**:
-   - Go to your Bookhoard server
-   - Log in with your account
-   - Navigate to **Settings → Devices**
-   - Click **Register New Device**
-   - Enter your device name and type
-   - Click **Generate Registration**
+**Registration Process**:
+1. Register device in Bookhoard web interface (Settings → Devices)
+2. Approve device via QR code or approval URL
+3. Configure sync settings on your device
+4. Start reading - progress syncs automatically!

-3. **Complete Registration**:
-   - Scan the QR code OR copy the registration URL
-   - Visit the approval URL in your browser
-   - Review device details and click **Approve**
-   - Device will receive authentication token
-
-4. **Configure Sync**:
-   - Enter the sync URL provided (e.g., `https://bookhoard.example.com/api/sync/koreader`)
-   - Enable auto-sync
-   - Set sync frequency (recommended: Every page turn)
-
-#### Option 2: Direct Device Registration
-
-1. **From Your Device**:
-   - Navigate to sync settings
-   - Select "Bookhoard Sync"
-   - Enter server URL: `https://bookhoard.example.com`
-   - Click "Register Device"
-   - Device will display registration code
-
-2. **In Your Browser**:
-   - Go to `https://bookhoard.example.com/devices/approve`
-   - Enter registration code
-   - Approve the device
-
-### Device Management
-
-**View Your Devices**:
+**Device Management**:
 ```
 Settings → Devices
 ```

-**Manage Devices**:
- **Rename**: Click device name → Edit
- **Disable Sync**: Toggle "Sync Enabled"
- **Remove Device**: Click "Delete" (revokes access immediately)
+You can:
+- View all your registered devices
+- See last sync time and status
+- Disable or remove devices
+- View unlinked books that need matching
+- Manage file aliases

 ---

-## Sync Features
+## Book Matching
+
+### What is Book Matching?
+
+When devices sync books, Bookhoard tries to automatically match them using:
+- **SHA-256 hash** (most reliable) - Content-based fingerprint
+- **ISBN** - Standard book identifier
+- **UUID** - Unique identifier from EPUB metadata
+- **Title + Author** (fallback) - Last resort matching
+
+### Unlinked Books
+
+Sometimes a book on your device can't be automatically matched to your library. This happens when:
+- The book was side-loaded (not downloaded via Bookhoard)
+- The file format was converted (EPUB → KEPUB)
+- The metadata doesn't match exactly
+
+### Viewing Unlinked Books
+
+```
+Settings → Devices → Select Device → View Unlinked Books
+```
+
+### Resolving Unlinked Books
+
+1. **Auto-Link** - Automatically link books with 80%+ confidence
+2. **Get Suggestions** - Review potential matches before linking
+3. **Manual Link** - Choose the correct match yourself
+
+### Book Matching Priority
+
+1. **Bookhoard UUID** - 100% confidence
+2. **OPF UUID** - 95% confidence
+3. **SHA-256 hash** - 90% confidence
+4. **OPF identifier** - 85% confidence
+5. **ISBN/ASIN** - 80% confidence
+6. **Title + Author + File Size** - 50% confidence
+
+---
+
+## Managing Conflicts

 ### Reading Progress