feat: implement collection library filter with WebSocket improvements and test coverage
This commit adds comprehensive functionality for filtering collections by library, improves WebSocket real-time updates with user activity detection, and adds extensive test coverage. ## Core Features ### Collection Library Filter - Added library_id parameter to media-items search API - Collections can now be filtered by specific library - Toggle UI component for enabling/disabling library filter - Default state is "checked" when library_id is present - Consistent behavior across partial and fuzzy search modes ### WebSocket Auto-Reload Mitigation - Added user activity detection to prevent disruptive page reloads - Checks if user is actively typing in INPUT/TEXTAREA/SELECT elements - Skips auto-reload when user is interacting with form elements - Toast notifications still show for awareness - Prevents data loss during editing operations ## Implementation Changes ### Backend - internal/database/queries.sql.go: Added library filter support to search queries - internal/handlers/media.go: Enhanced search with library_id parameter validation - internal/handlers/collections.go: Updated collection handlers with library filtering - internal/sync/websocket.go: Improved broadcast mechanism with user-scoped updates - internal/router/frontend.go: Pass libraryID to collection templates ### Frontend - templates/collections.templ: Added library filter toggle UI component - web/src/collections.ts: TypeScript implementation with WebSocket integration - templates/collections_templ.go: Generated template code ### Testing - cmd/server/tests/search_test.go: Added TestCollectionSearchLibraryFilter - cmd/server/tests/websocket_test.go: Added TestWebSocketUserScopedBroadcast - New helper functions for creating libraries and media items via API - Comprehensive test coverage for library filtering and user-scoped broadcasts ## API Documentation Updates ### Bruno Tests (Comprehensive Documentation) - bruno/collections/*: Added detailed API documentation for all collection endpoints - bruno/devices/*: Added device management and sync API documentation - bruno/devices/kobo/api.yml: Kobo-specific sync protocol docs - bruno/devices/koreader/api.yml: KOReader-specific sync protocol docs - bruno/opds/*: Added OPDS feed and download endpoint documentation - bruno/library/browse-folders.yml: Library folder browsing API docs ### New Bruno Tests - bruno/media-items/Search All Libraries.yml: Test search without library filter - bruno/media-items/Search Specific Library.yml: Test search with library filter - bruno/media-items/Search Invalid Library ID.yml: Test error handling ## Documentation - docs/developer/api/media-items/search_media_items.md: Updated with library_id parameter - IMPLEMENTATION_COLLECTION_FIX.md: Comprehensive implementation guide with test scenarios ## Testing ### Integration Tests - Library filter tests verify correct filtering across multiple libraries - Invalid library_id tests ensure proper error handling - WebSocket tests verify user-scoped broadcast behavior - User A no longer receives User B's collection updates ### Manual Testing Scenarios - Open collection in multiple tabs - updates propagate correctly - Type in search box while another tab adds books - no disruptive reload - Add/remove books from collection - toast notifications appear - Toggle library filter - results update dynamically ## Technical Details - WebSocket broadcasts are now user-scoped for privacy - Active element detection uses tagName and contenteditable attributes - Library ID validation uses UUID format checking - Progressive enhancement maintained - page works without JavaScript - All changes follow PROJECT_GUIDELINES.md conventions - TypeScript only for frontend logic - TailwindCSS only for styling - Procedural programming style throughout ## Breaking Changes None - all changes are additive and backward compatible.
This commit is contained in:
@@ -8,4 +8,31 @@ http:
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{book_id_1"
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{book_id_1}}"
|
||||
|
||||
docs: |-
|
||||
## Add Books to Collection
|
||||
|
||||
Adds multiple books to an existing collection.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}/books
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Request Body:**
|
||||
- `book_ids` (array of strings, required): List of book IDs to add
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
- `added_count` (integer): Number of books added
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
|
||||
@@ -13,3 +13,35 @@ http:
|
||||
,\n \"auto_assign_rules\": [\n {\n \"id\": \"rule-1\",\n \
|
||||
\ \"field\": \"genre\",\n \"operator\": \"equals\",\n \"value\"\
|
||||
: \"Science Fiction\",\n \"priority\": 8"
|
||||
|
||||
docs: |-
|
||||
## Create Collection
|
||||
|
||||
Creates a new collection for organizing books.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
- `name` (string, required): Collection name (max 100 chars)
|
||||
- `description` (string, optional): Collection description (max 500 chars)
|
||||
- `color` (string, optional): Hex color code (default #3498db)
|
||||
- `icon` (string, optional): Emoji icon (default 📚)
|
||||
- `auto_assign_rules` (array, optional): Auto-assignment rules
|
||||
- `id` (string): Rule ID
|
||||
- `field` (string): Field to match (genre, author, series, etc.)
|
||||
- `operator` (string): Comparison operator (equals, contains, startsWith)
|
||||
- `value` (string): Value to match
|
||||
- `priority` (integer): Rule priority (1-10)
|
||||
|
||||
**Response:**
|
||||
- Collection object with generated ID
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Created
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 409: Collection name already exists
|
||||
|
||||
@@ -8,4 +8,32 @@ http:
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"collection_id\": \"{{collection_id"
|
||||
jsonBody: "{\n \"collection_id\": \"{{collection_id}}"
|
||||
|
||||
docs: |-
|
||||
## Create Device Mapping
|
||||
|
||||
Maps a collection to a device shelf for synchronization.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Request Body:**
|
||||
- `collection_id` (string, required): Collection ID to map
|
||||
- `device_shelf_name` (string, optional): Custom shelf name on device
|
||||
- `sync_direction` (string, optional): sync direction (book_to_device, device_to_book, bidirectional)
|
||||
|
||||
**Response:**
|
||||
- Mapping object with generated ID
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Created
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Device or collection not found
|
||||
|
||||
@@ -6,3 +6,25 @@ http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Delete Collection
|
||||
|
||||
Permanently deletes a collection and all its mappings.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
|
||||
@@ -6,3 +6,26 @@ http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections/{{mapping_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Delete Device Mapping
|
||||
|
||||
Removes a collection-to-device mapping.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections/{mapping_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `mapping_id` (string): Mapping ID
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device or mapping not found
|
||||
|
||||
@@ -19,3 +19,26 @@ settings:
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs: |-
|
||||
## Get Book Collections
|
||||
|
||||
Retrieves all collections that a specific book belongs to.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/collections/books
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `book_id` (string, required): Book ID
|
||||
|
||||
**Response:**
|
||||
- Array of collection objects containing the book
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Book not found
|
||||
|
||||
@@ -6,3 +6,25 @@ http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Collection
|
||||
|
||||
Retrieves detailed information about a specific collection.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Response:**
|
||||
- Collection object with all fields including books, rules, and mappings
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
|
||||
@@ -6,3 +6,26 @@ http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections?include_auto=true&sort_by=name'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Collections
|
||||
|
||||
Retrieves all collections for the authenticated user.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `include_auto` (boolean, optional): Include auto-created collections (default false)
|
||||
- `sort_by` (string, optional): Sort field (name, created_at, book_count)
|
||||
- `order` (string, optional): Sort order (asc, desc)
|
||||
|
||||
**Response:**
|
||||
- Array of collection objects
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
@@ -6,3 +6,25 @@ http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Device Mappings
|
||||
|
||||
Retrieves all collection mappings for a specific device.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Response:**
|
||||
- Array of device mapping objects with collection details
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
|
||||
@@ -6,3 +6,26 @@ http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/{{book_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Remove Book from Collection
|
||||
|
||||
Removes a single book from a collection.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}/books/{book_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
- `book_id` (string): Book ID
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Collection or book not found
|
||||
|
||||
@@ -13,3 +13,34 @@ http:
|
||||
auto_assign_rules\": [\n {\n \"id\": \"rule-2\",\n \"field\"\
|
||||
: \"series\",\n \"operator\": \"equals\",\n \"value\": \"Foundation\"\
|
||||
,\n \"priority\": 9"
|
||||
|
||||
docs: |-
|
||||
## Update Collection
|
||||
|
||||
Updates an existing collection's properties.
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Request Body:**
|
||||
- `name` (string, optional): New collection name
|
||||
- `description` (string, optional): New description
|
||||
- `color` (string, optional): New hex color code
|
||||
- `icon` (string, optional): New emoji icon
|
||||
- `auto_assign_rules` (array, optional): Updated auto-assignment rules
|
||||
|
||||
**Response:**
|
||||
- Updated collection object
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
- 409: Collection name already exists
|
||||
|
||||
@@ -10,3 +10,31 @@ http:
|
||||
type: json
|
||||
jsonBody: "{\n \"device_shelf_name\": \"Science Fiction\",\n \"sync_direction\"\
|
||||
: \"book_to_device\""
|
||||
|
||||
docs: |-
|
||||
## Update Device Mapping
|
||||
|
||||
Updates settings for a collection-to-device mapping.
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections/{mapping_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `mapping_id` (string): Mapping ID
|
||||
|
||||
**Request Body:**
|
||||
- `device_shelf_name` (string, optional): Custom shelf name on device
|
||||
- `sync_direction` (string, optional): Sync direction (book_to_device, device_to_book, bidirectional)
|
||||
|
||||
**Response:**
|
||||
- Updated mapping object
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Device or mapping not found
|
||||
|
||||
@@ -5,3 +5,18 @@ info:
|
||||
http:
|
||||
method: POST
|
||||
url: '"http://localhost:8765/api"'
|
||||
|
||||
docs: |-
|
||||
## Bookhoard Device Management API
|
||||
|
||||
Collection of endpoints for managing e-reader devices and their synchronization settings.
|
||||
|
||||
**Base URL:** http://localhost:8765/api
|
||||
|
||||
**Authentication:** Most endpoints require Bearer token authentication
|
||||
|
||||
**Endpoints:**
|
||||
- Device registration and management
|
||||
- Device authentication tokens
|
||||
- Sync configuration
|
||||
- Device-to-collection mappings
|
||||
|
||||
@@ -5,3 +5,18 @@ info:
|
||||
http:
|
||||
method: POST
|
||||
url: '"http://localhost:8765/api"'
|
||||
|
||||
docs: |-
|
||||
## Bookhoard Kobo Sync API
|
||||
|
||||
Collection of endpoints specifically for Kobo e-reader device synchronization.
|
||||
|
||||
**Base URL:** http://localhost:8765/api
|
||||
|
||||
**Authentication:** Device token or Bearer token required
|
||||
|
||||
**Endpoints:**
|
||||
- Kobo-specific sync protocols
|
||||
- Kobo store integration
|
||||
- Metadata synchronization
|
||||
- Reading progress sync
|
||||
|
||||
@@ -5,3 +5,18 @@ info:
|
||||
http:
|
||||
method: POST
|
||||
url: '"http://localhost:8765/api"'
|
||||
|
||||
docs: |-
|
||||
## Bookhoard KOReader Sync API
|
||||
|
||||
Collection of endpoints specifically for KOReader e-reader device synchronization.
|
||||
|
||||
**Base URL:** http://localhost:8765/api
|
||||
|
||||
**Authentication:** Device token or Bearer token required
|
||||
|
||||
**Endpoints:**
|
||||
- KOReader-specific sync protocols
|
||||
- Metadata synchronization
|
||||
- Reading progress sync
|
||||
- Highlights and notes sync
|
||||
|
||||
@@ -8,4 +8,30 @@ http:
|
||||
auth: none
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"registration_id\": \"{{registrationId"
|
||||
jsonBody: "{\n \"registration_id\": \"{{registrationId}}"
|
||||
|
||||
docs: |-
|
||||
## Check Registration Status
|
||||
|
||||
Checks the current status of a device registration request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/register/status
|
||||
|
||||
**Authentication:** None
|
||||
|
||||
**Request Body:**
|
||||
- `registration_id` (string, required): Registration request ID
|
||||
|
||||
**Response:**
|
||||
- `status` (string): Registration status (pending, approved, rejected, expired)
|
||||
- `device_name` (string): Device name
|
||||
- `device_type` (string): Device type
|
||||
- `created_at` (string): Request timestamp
|
||||
- `expires_at` (string): Expiration timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 404: Registration ID not found
|
||||
- 410: Registration expired
|
||||
|
||||
@@ -10,3 +10,30 @@ http:
|
||||
type: json
|
||||
jsonBody: "{\n \"device_name\": \"My Kindle Paperwhite\",\n \"device_type\"\
|
||||
: \"koreader\",\n \"device_identifier\": \"kindle-pw5-hardware-id-12345\""
|
||||
|
||||
docs: |-
|
||||
## Initiate Device Registration
|
||||
|
||||
Initiates a new device registration request that requires admin approval.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/register
|
||||
|
||||
**Authentication:** None (open endpoint)
|
||||
|
||||
**Request Body:**
|
||||
- `device_name` (string, required): Human-readable device name (max 100 chars)
|
||||
- `device_type` (string, required): Device type (kobo, koreader, kindle, etc.)
|
||||
- `device_identifier` (string, required): Unique hardware ID (max 200 chars)
|
||||
|
||||
**Response:**
|
||||
- `registration_id` (string): Unique registration request ID
|
||||
- `status` (string): Initial status (pending)
|
||||
- `expires_at` (string): Expiration timestamp (usually 24 hours)
|
||||
- `message` (string): Informational message
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Registration initiated
|
||||
- 400: Invalid request
|
||||
- 409: Device already registered
|
||||
|
||||
@@ -10,3 +10,33 @@ http:
|
||||
type: json
|
||||
jsonBody: "{\n \"device_name\": \"My Updated Kindle\",\n \"sync_enabled\"\
|
||||
: true,\n \"auto_sync\": true,\n \"sync_frequency_minutes\": 10"
|
||||
|
||||
docs: |-
|
||||
## Update Device
|
||||
|
||||
Updates device settings and synchronization preferences.
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}
|
||||
|
||||
**Authentication:** Required (Bearer token, admin or device owner)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Request Body:**
|
||||
- `device_name` (string, optional): New device name (max 100 chars)
|
||||
- `sync_enabled` (boolean, optional): Enable/disable synchronization
|
||||
- `auto_sync` (boolean, optional): Enable automatic synchronization
|
||||
- `sync_frequency_minutes` (integer, optional): Sync frequency in minutes (5-1440)
|
||||
|
||||
**Response:**
|
||||
- Updated device object
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (not device owner)
|
||||
- 404: Device not found
|
||||
|
||||
@@ -23,3 +23,30 @@ req:
|
||||
url: "{{base_url}}/api/libraries/browse?path=/tmp"
|
||||
headers:
|
||||
Authorization: "Bearer {{ADMIN_TOKEN}}"
|
||||
|
||||
docs: |-
|
||||
## Browse Library Folders
|
||||
|
||||
Navigates through the filesystem to browse folders for library configuration.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/libraries/browse
|
||||
|
||||
**Authentication:** Required (Bearer token, Admin only)
|
||||
|
||||
**Query Parameters:**
|
||||
- `path` (string, required): Filesystem path to browse
|
||||
|
||||
**Response:**
|
||||
- `current_path` (string): Current browsing path
|
||||
- `parent_path` (string): Parent directory path
|
||||
- `directories` (array): List of subdirectories
|
||||
- `files` (array): List of files (optional)
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid path
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (admin access required)
|
||||
- 404: Path not found
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
info:
|
||||
name: Search All Libraries
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: "{{base_url}}/api/media-items/search"
|
||||
params:
|
||||
- name: q
|
||||
value: "harry"
|
||||
type: query
|
||||
disabled: false
|
||||
auth: inherit
|
||||
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs: |-
|
||||
## Search All Libraries
|
||||
|
||||
Searches for media items across all libraries without filtering.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/media-items/search
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `q` (string, required): Search query (minimum 2 characters)
|
||||
|
||||
**Response:** HTTP 200 (OK)
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Harry Potter and the Sorcerer's Stone",
|
||||
"author": "J.K. Rowling",
|
||||
"library_id": "uuid",
|
||||
"library_name": "E-Books"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- Status: 200
|
||||
- Returns array of media items from all libraries
|
||||
- Results match search query
|
||||
@@ -0,0 +1,54 @@
|
||||
info:
|
||||
name: Search Invalid Library ID
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: "{{base_url}}/api/media-items/search"
|
||||
params:
|
||||
- name: q
|
||||
value: "test"
|
||||
type: query
|
||||
disabled: false
|
||||
- name: library_id
|
||||
value: "invalid-uuid"
|
||||
type: query
|
||||
disabled: false
|
||||
auth: inherit
|
||||
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs: |-
|
||||
## Search Invalid Library ID
|
||||
|
||||
Tests error handling when an invalid library_id is provided.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/media-items/search
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `q` (string, required): Search query
|
||||
- `library_id` (string, invalid): Malformed UUID
|
||||
|
||||
**Response:** HTTP 400 (Bad Request)
|
||||
```json
|
||||
{
|
||||
"error": "invalid library_id"
|
||||
}
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- Status: 400
|
||||
- Returns error message indicating invalid library_id
|
||||
|
||||
**Edge Cases Tested:**
|
||||
- Malformed UUID (not valid UUID format)
|
||||
- Validates input sanitization
|
||||
@@ -0,0 +1,60 @@
|
||||
info:
|
||||
name: Search Specific Library
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: "{{base_url}}/api/media-items/search"
|
||||
params:
|
||||
- name: q
|
||||
value: "harry"
|
||||
type: query
|
||||
disabled: false
|
||||
- name: library_id
|
||||
value: "{{libraryId}}"
|
||||
type: query
|
||||
disabled: false
|
||||
auth: inherit
|
||||
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs: |-
|
||||
## Search Specific Library
|
||||
|
||||
Searches for media items within a specific library using the library_id filter.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/media-items/search
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `q` (string, required): Search query (minimum 2 characters)
|
||||
- `library_id` (string/UUID, required): Filter results to specific library
|
||||
|
||||
**Response:** HTTP 200 (OK)
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Harry Potter and the Sorcerer's Stone",
|
||||
"author": "J.K. Rowling",
|
||||
"library_id": "{{libraryId}}",
|
||||
"library_name": "My Library"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- Status: 200
|
||||
- All results have `library_id` matching the filter
|
||||
- Results match search query
|
||||
|
||||
**Test Setup:**
|
||||
- Set `libraryId` environment variable to a valid library UUID
|
||||
@@ -5,3 +5,30 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/download/{{book_id}}'
|
||||
|
||||
docs: |-
|
||||
## Download Book (EPUB)
|
||||
|
||||
Downloads a book in standard EPUB format for reading on e-reader devices.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/download/{book_id}
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `book_id` (string): Book ID
|
||||
|
||||
**Query Parameters:**
|
||||
- `format` (string, optional): File format (epub, default)
|
||||
|
||||
**Response:**
|
||||
- Binary EPUB file content
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (file download)
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (device not authorized for this book)
|
||||
- 404: Book not found
|
||||
|
||||
@@ -5,3 +5,30 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/download/{{book_id}}?format=kepub'
|
||||
|
||||
docs: |-
|
||||
## Download Book (KEPUB)
|
||||
|
||||
Downloads a book in Kobo-specific KEPUB format, optimized for Kobo e-readers.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/download/{book_id}
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `book_id` (string): Book ID
|
||||
|
||||
**Query Parameters:**
|
||||
- `format` (string, required): File format (kepub for Kobo devices)
|
||||
|
||||
**Response:**
|
||||
- Binary KEPUB file content (EPUB with Kobo-specific enhancements)
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (file download)
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (device not authorized for this book)
|
||||
- 404: Book not found
|
||||
|
||||
@@ -5,3 +5,31 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/cover/{{book_id}}'
|
||||
|
||||
docs: |-
|
||||
## Get Cover Image
|
||||
|
||||
Retrieves the cover image for a specific book.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/cover/{book_id}
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `book_id` (string): Book ID
|
||||
|
||||
**Query Parameters:**
|
||||
- `width` (integer, optional): Desired width in pixels
|
||||
- `height` (integer, optional): Desired height in pixels
|
||||
- `quality` (integer, optional): Image quality (1-100, default 85)
|
||||
|
||||
**Response:**
|
||||
- Binary image file (JPEG or PNG)
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (image file)
|
||||
- 401: Unauthorized
|
||||
- 404: Book or cover not found
|
||||
|
||||
@@ -5,3 +5,31 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/catalog?page=1&per_page=50'
|
||||
|
||||
docs: |-
|
||||
## Get Device Catalog
|
||||
|
||||
Retrieves a paginated catalog of books available for the device, compatible with OPDS feed format.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/catalog
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (integer, optional): Page number (default 1)
|
||||
- `per_page` (integer, optional): Items per page (default 50, max 200)
|
||||
- `sort_by` (string, optional): Sort field (title, author, date_added)
|
||||
- `order` (string, optional): Sort order (asc, desc)
|
||||
|
||||
**Response:**
|
||||
- OPDS 2.0 feed with book entries including metadata and download links
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
|
||||
@@ -5,3 +5,30 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/nav'
|
||||
|
||||
docs: |-
|
||||
## Get Device Navigation
|
||||
|
||||
Provides OPDS navigation feed for device, including collections and series groups.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/nav
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Response:**
|
||||
- OPDS navigation feed with links to:
|
||||
- All books
|
||||
- Collections
|
||||
- Series
|
||||
- Authors
|
||||
- Recent additions
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
|
||||
@@ -5,3 +5,30 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/formats/{{book_id}}'
|
||||
|
||||
docs: |-
|
||||
## List Formats
|
||||
|
||||
Lists all available file formats for a specific book.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/formats/{book_id}
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `book_id` (string): Book ID
|
||||
|
||||
**Response:**
|
||||
- Array of available formats:
|
||||
- `format` (string): Format identifier (epub, kepub, pdf, etc.)
|
||||
- `file_size` (integer): File size in bytes
|
||||
- `download_url` (string): Download link
|
||||
- `optimized_for` (array): Compatible device types
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Book not found
|
||||
|
||||
@@ -5,3 +5,31 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '{{opds_base_url}}/devices/{{device_id}}/search?q=hobbit'
|
||||
|
||||
docs: |-
|
||||
## Search Device Catalog
|
||||
|
||||
Searches the device's book catalog for matching titles, authors, or series.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /devices/{device_id}/search
|
||||
|
||||
**Authentication:** Required (Device token or Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Query Parameters:**
|
||||
- `q` (string, required): Search query
|
||||
- `page` (integer, optional): Page number (default 1)
|
||||
- `per_page` (integer, optional): Items per page (default 50)
|
||||
- `search_in` (string, optional): Search fields (title, author, series, all)
|
||||
|
||||
**Response:**
|
||||
- OPDS 2.0 feed with matching book entries
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid query
|
||||
- 401: Unauthorized
|
||||
|
||||
@@ -5,3 +5,34 @@ info:
|
||||
http:
|
||||
method: GET
|
||||
url: '"http://localhost:8765/api"'
|
||||
|
||||
docs: |-
|
||||
## Bookhoard Sync Queue API
|
||||
|
||||
Collection of endpoints for managing the synchronization queue that handles
|
||||
background processing of sync operations between devices and the server.
|
||||
|
||||
**Base URL:** http://localhost:8765/api
|
||||
|
||||
**Authentication:** Bearer token required for most endpoints
|
||||
|
||||
**Endpoints:**
|
||||
- Queue item management (create, process, retry, delete)
|
||||
- Queue statistics and monitoring
|
||||
- Device-specific queue operations
|
||||
- Filtering by type (highlights, notes, bookmarks, progress)
|
||||
- Filtering by status (pending, completed, failed)
|
||||
- Bulk operations (clear device queue, clear failed items)
|
||||
|
||||
**Queue Item Types:**
|
||||
- `highlight`: Highlight synchronization
|
||||
- `note`: Note synchronization
|
||||
- `bookmark`: Bookmark synchronization
|
||||
- `progress`: Reading progress synchronization
|
||||
|
||||
**Queue Status Values:**
|
||||
- `pending`: Awaiting processing
|
||||
- `processing`: Currently being processed
|
||||
- `completed`: Successfully processed
|
||||
- `failed`: Processing failed (retryable)
|
||||
- `cancelled`: Item was cancelled
|
||||
|
||||
Reference in New Issue
Block a user