From 55024bb70a3c8de3b43e0a48c1b1777f8c7db89c Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Feb 2026 08:51:56 -0500 Subject: [PATCH] docs: add book-matching, collections, and OPDS API endpoints Phase 2 part 6: Split advanced features endpoints - Book Matching: search_books, link_book (manual and auto-link) - Collections: INDEX.md linking to COLLECTIONS_API.md - OPDS: feeds, acquisition, publication (OPDS 1.2 protocol) - Include format conversion details (EPUB to KEPUB) --- docs/api/book-matching/link_book.md | 92 ++++++++++++++++++++++++++ docs/api/book-matching/search_books.md | 56 ++++++++++++++++ docs/api/collections/INDEX.md | 35 ++++++++++ docs/api/opds/acquisition.md | 72 ++++++++++++++++++++ docs/api/opds/feeds.md | 81 +++++++++++++++++++++++ docs/api/opds/publication.md | 56 ++++++++++++++++ 6 files changed, 392 insertions(+) create mode 100644 docs/api/book-matching/link_book.md create mode 100644 docs/api/book-matching/search_books.md create mode 100644 docs/api/collections/INDEX.md create mode 100644 docs/api/opds/acquisition.md create mode 100644 docs/api/opds/feeds.md create mode 100644 docs/api/opds/publication.md diff --git a/docs/api/book-matching/link_book.md b/docs/api/book-matching/link_book.md new file mode 100644 index 0000000..00cb423 --- /dev/null +++ b/docs/api/book-matching/link_book.md @@ -0,0 +1,92 @@ +# Link Book + +Link a device book to a Bookhoard media item. Supports bulk linking. + +**Endpoint**: `POST /api/sync/bulk-link-books` or `POST /api/sync/auto-link-books` +**Auth**: Required +**Content-Type**: `application/json` + +## Manual Link Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| links | array | Yes | List of book links | +| links[].unlinked_book_id | string | Yes | Device book UUID | +| links[].media_item_id | string | Yes | Bookhoard media item UUID | +| links[].confidence_score | float | No | Match confidence (0-1) | + +### Example Manual Link Request + +```json +{ + "links": [ + { + "unlinked_book_id": "uuid-1", + "media_item_id": "uuid-2", + "confidence_score": 1.0 + } + ] +} +``` + +## Auto-Link Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| confidence_threshold | float | No | Minimum confidence for auto-link (default: 0.8) | +| limit | integer | No | Maximum books to auto-link (default: 50) | + +### Example Auto-Link Request + +```json +{ + "confidence_threshold": 0.8, + "limit": 50 +} +``` + +## Response (200 OK) - Manual Link + +```json +{ + "results": [ + { + "unlinked_book_id": "uuid-1", + "status": "success", + "media_item_id": "uuid-2" + } + ], + "total": 1, + "successful": 1, + "failed": 0 +} +``` + +## Response (200 OK) - Auto-Link + +```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" + } + ] +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid link data | +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/book-matching/search_books.md b/docs/api/book-matching/search_books.md new file mode 100644 index 0000000..fa1d9c3 --- /dev/null +++ b/docs/api/book-matching/search_books.md @@ -0,0 +1,56 @@ +# Search Books for Matching + +Query books to find potential matches for linking. + +**Endpoint**: `POST /api/sync/books/query` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| identifiers | array | No | List of identifiers (ISBN, UUID) | +| sha256 | string | No | SHA256 hash of book file | +| title | string | No | Book title | +| author | string | No | Book author | +| file_size | integer | No | File size in bytes | + +### Example Request + +```json +{ + "identifiers": ["isbn:978-0345391802", "uuid:abc-123"], + "sha256": "a1b2c3d4e5f6abc123...", + "title": "The Hobbit", + "author": "J.R.R. Tolkien", + "file_size": 2456789 +} +``` + +## Response (200 OK) + +```json +{ + "matches": [ + { + "media_item_id": "uuid-123", + "bookhoard_uuid": "uuid-123", + "confidence": 1.0, + "match_method": "uuid_match" + } + ], + "action": "auto_link" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid query parameters | +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/api/collections/INDEX.md b/docs/api/collections/INDEX.md new file mode 100644 index 0000000..4c88cd1 --- /dev/null +++ b/docs/api/collections/INDEX.md @@ -0,0 +1,35 @@ +# Collections API + +See [COLLECTIONS_API.md](../../COLLECTIONS_API.md) for complete collections documentation. + +## Quick Links + +- [List Collections](list_collections.md) - Get all collections +- [Get Collection](get_collection.md) - Get collection details +- [Create Collection](create_collection.md) - Create a new collection +- [Update Collection](update_collection.md) - Update collection metadata +- [Delete Collection](delete_collection.md) - Delete a collection +- [Add Auto-Assign Rule](add_auto_assign_rule.md) - Add automatic book assignment rule +- [Remove Auto-Assign Rule](remove_auto_assign_rule.md) - Remove assignment rule +- [Test Rule](test_rule.md) - Test assignment rule +- [Bulk Assign](bulk_assign.md) - Bulk assign books to collection +- [Create Shelf Mapping](create_shelf_mapping.md) - Map collection to device shelf +- [Delete Shelf Mapping](delete_shelf_mapping.md) - Remove shelf mapping + +--- + +## Overview + +Collections allow you to organize your books into custom groups with automatic assignment rules. + +## Features + +- **Manual Assignment**: Add specific books to collections +- **Auto-Assignment**: Define rules to automatically assign books based on metadata +- **Device Sync**: Collections sync as shelves on Kobo/KOReader devices +- **Flexible Rules**: Filter by genre, series, tags, and more + +## See Also + +- [COLLECTIONS_API.md](../../COLLECTIONS_API.md) - Complete API reference +- [Sync Guide](../../SYNC_USER_GUIDE.md) - How collections sync to devices diff --git a/docs/api/opds/acquisition.md b/docs/api/opds/acquisition.md new file mode 100644 index 0000000..0e5e4bf --- /dev/null +++ b/docs/api/opds/acquisition.md @@ -0,0 +1,72 @@ +# OPDS Acquisition + +Download books and list available formats. + +## Download Book with Format Conversion + +**Endpoint**: `GET /opds/devices/{deviceId}/download/{bookId}` +**Auth**: Device token required + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| format | string | No | Book format: `epub` (default), `kepub` | + +### Example Request + +```http +GET /opds/devices/kobo-id/download/uuid-123?format=kepub +``` + +### Response (200 OK) + +**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) + +**Body:** Book file binary data + +## List Available Formats + +**Endpoint**: `GET /opds/devices/{deviceId}/formats/{bookId}` +**Auth**: Device token required + +### Example Request + +```http +GET /opds/devices/kobo-id/formats/uuid-123 +``` + +### Response (200 OK) + +```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 + } + ] +} +``` + +## Try It Out + + diff --git a/docs/api/opds/feeds.md b/docs/api/opds/feeds.md new file mode 100644 index 0000000..73ccc04 --- /dev/null +++ b/docs/api/opds/feeds.md @@ -0,0 +1,81 @@ +# OPDS Feeds + +Bookhoard provides OPDS 1.2 feeds for device compatibility. + +## Get Device Catalog + +**Endpoint**: `GET /opds/devices/{deviceId}/catalog` +**Auth**: Device token required + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| page | integer | No | Page number (default: 1) | +| per_page | integer | No | Items per page (default: 50, max: 200) | + +### Example Request + +```http +GET /opds/devices/kobo-id/catalog?page=1&per_page=50 +``` + +### Response (200 OK - OPDS 1.2 XML) + +```xml + + + urn:uuid:device-id + Bookhoard Library + 2026-02-01T12:00:00Z + + + + + + + urn:uuid:bookhoard-uuid-123 + The Hobbit + J.R.R. Tolkien + 2026-02-01T10:00:00Z + + + + + + uuid-123 + abc123... + + +``` + +## Search OPDS Catalog + +**Endpoint**: `GET /opds/devices/{deviceId}/search` +**Auth**: Device token required + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| q | string | Yes | Search query | + +### Example Request + +```http +GET /opds/devices/kobo-id/search?q=Hobbit +``` + +### Response (200 OK - OPDS 1.2 XML with search results) + +Returns OPDS feed with matching books. + +## Try It Out + + diff --git a/docs/api/opds/publication.md b/docs/api/opds/publication.md new file mode 100644 index 0000000..3ea8496 --- /dev/null +++ b/docs/api/opds/publication.md @@ -0,0 +1,56 @@ +# OPDS Publication + +OPDS navigation and publication feeds. + +## Navigation Feed + +**Endpoint**: `GET /opds/devices/{deviceId}/nav` +**Auth**: Device token required + +### Example Request + +```http +GET /opds/devices/kobo-id/nav +``` + +### Response (200 OK - OPDS 1.2 Navigation XML) + +Returns OPDS navigation feed with links to: +- Root catalog +- Search +- Collections/shelves +- Filtered views (by author, series, etc.) + +## Publication Feeds by Collection + +**Endpoint**: `GET /opds/devices/{deviceId}/collections/{collectionId}` +**Auth**: Device token required + +### Example Request + +```http +GET /opds/devices/kobo-id/collections/collection-uuid +``` + +### Response (200 OK - OPDS 1.2 XML) + +Returns OPDS feed with books in the specified collection. + +## Publication Feeds by Shelf + +**Endpoint**: `GET /opds/devices/{deviceId}/shelves/{shelfName}` +**Auth**: Device token required + +### Example Request + +```http +GET /opds/devices/kobo-id/shelves/Favorites +``` + +### Response (200 OK - OPDS 1.2 XML) + +Returns OPDS feed with books on the specified device shelf. + +## Try It Out + +