- Removed comment about 'Ebook notes handlers (backward compatibility using views)'
- Removed comment references to non-existent GetEbookNotes and GetEbookHighlights
- Cleaned up misleading legacy documentation
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
Implement real-time collection updates when books are added/removed:
Backend Changes:
- Added connManager to CollectionHandler struct
- Updated constructor to accept ConnectionManager
- Updated all NewCollectionHandler() calls in ebook.go and main.go
- Added WebSocket broadcasts in AddBooks() handler
- Added WebSocket broadcasts in BulkRemoveBooks() handler
- Broadcasts collection_updated events with:
- collection_id: Which collection changed
- action: books_added or books_removed
- book_ids: Array of affected book IDs
- count: Number of books changed
Frontend Changes:
- Added WebSocket connection in collections UI
- connectWebSocket() establishes connection to /ws/sync
- Listens for collection_updated events
- Shows toast notification on collection change
- Auto-reloads page after 1 second to show updated book list
- Auto-reconnect on disconnect (5s delay)
- Error handling for WebSocket failures
WebSocket Event Format:
{
"type": "collection_updated",
"timestamp": "2026-02-01T12:00:00Z",
"data": {
"collection_id": "uuid",
"action": "books_added",
"book_ids": ["uuid1", "uuid2"],
"count": 2
}
}
User Experience:
- When another user adds books to a collection, all connected clients see:
1. Toast notification: "Collection updated: books_added (2 books)"
2. Page auto-refreshes after 1 second
3. Updated book list displays
- Same for book removal
- Works across multiple browser tabs/devices
- No manual refresh needed
Technical Notes:
- Broadcasts to ALL connected WebSocket clients
- Client-side filtering by collection_id
- Existing progress/conflict broadcasts continue to work
- Connection manager handles broadcast distribution
Resolves Limitation #4: Real-time Collection Updates
Complete bulk operations for collections management:
BULK ADD BOOKS:
- Implemented searchBooks() with real API integration
- Multi-select checkboxes for book selection
- SelectedBooks Set tracks chosen books
- AddSelectedBooks() sends array to existing endpoint
- Uses existing POST /api/collections/:id/books endpoint
BULK REMOVE BOOKS:
- New endpoint: POST /api/collections/:id/books/bulk-remove
- Checkboxes on each book card for selection
- BooksToRemove Set tracks selections
- Live counter showing selected count
- BulkRemoveBooks() handler removes all in one API call
- More efficient than N individual DELETE requests
Frontend Changes:
- Selected counter badge shows number selected
- Bulk remove button (enabled when books selected)
- Checkboxes on all books for multi-select
- Confirmation dialog for bulk operations
- Toast notifications with counts
Backend Changes:
- BulkRemoveBooks() handler in collections.go
- Accepts book_ids array, returns removed/total counts
- Iterates and removes, counting successes
- Route: POST /api/collections/:id/books/bulk-remove
API Request:
{
"book_ids": ["uuid1", "uuid2", "uuid3"]
}
API Response:
{
"removed": 3,
"total": 3
}
Tests Added:
- TestCompareValues_* (existing)
- TestEvaluateRule_* (existing)
Resolves Limitations #2 (Bulk Operations) and #5 (Bulk Remove)
Add comprehensive API support for Phase 9 features:
Collections API (/api/collections):
- GET /collections: List all user collections
- POST /collections: Create new collection
- GET /collections/🆔 Get collection details
- PUT /collections/🆔 Update collection
- DELETE /collections/🆔 Delete collection
- GET /collections/:id/books: Get books in collection
- POST /collections/:id/books: Add books to collection
- DELETE /collections/:id/books/:bookId: Remove book from collection
Device Shelf Mapping API (/api/devices/:id/collections):
- GET: Get all collection-to-shelf mappings for device
- POST: Create new mapping
- PUT /:collectionId: Update mapping
- DELETE /:collectionId: Delete mapping
Book Matching API:
- POST /sync/books/query: Query books by identifiers
- POST /devices/:deviceId/sync/link-book: Manual book linking
- GET /devices/:deviceId/sync/unlinked-books: List unmatched books
- GET /devices/:id/file-aliases: Get device file aliases
- POST /devices/:id/file-aliases: Create file alias
- PUT /devices/:id/file-aliases/:aliasId: Update alias
- DELETE /devices/:id/file-aliases/:aliasId: Delete alias
- GET /books/match: Search for book matches
All new endpoints - no existing APIs modified.
Add WebSocket ConnectionManager to Handler:
- Add connManager field to Handler struct
- Update NewHandler to accept ConnectionManager parameter
- Update SetupRoutes to pass ConnectionManager through
- Import sync package with alias to avoid conflicts
This enables progress handlers to broadcast updates via WebSocket.
- Add POST /api/libraries/:id/scan endpoint for admin library scanning
- Add GET /api/libraries/:id/media-items endpoint for library media items
- Move /api/libraries/types to public endpoint (no auth required)
- Update ScanEbooks handler to support library_id parameter
- Fix CreateMediaItem ISBN field to use pgtype.Text wrapper
- Fix UpdateMediaItem to use correct Isbn field name
- Resolve type mismatch between request and database params
Resolves compilation errors in media item handlers
- Add GET /api/media-items/search endpoint
- Try partial matching first (ILIKE with wildcards)
- Fallback to fuzzy search if no results found
- Return 404 with 'no results found' when no matches
- Limit results to 50 items by default
- Supports search across title, author, series, tags, contributors
- Respects library visibility settings per user
- Fix scheduler.go log.Printf calls to convert pgtype.UUID to string before formatting
- Fix ebook.go fmt.Printf calls to convert pgtype.UUID to string before formatting
- Add missing Enabled field to rate limiter config in security test
- Prevents format string errors when logging library IDs
This resolves compilation errors where pgtype.UUID was being formatted
with %s which expects a string, not a UUID struct.
- Fix type assertion panics in library.go (lines 58, 109, 237)
Changed from *database.Users to database.Users to match JWT middleware
- Fix ISBN type mismatch in ebook.go (lines 249, 308)
Changed from pgtype.Text to string to match database schema
- Fix ISBN type mismatch in ebook_scanner.go (line 421)
Changed from pgtype.Text to string to match database schema
These changes fix 500 errors in library creation and ebook operations.
- Increase ISBN column from VARCHAR(13) to VARCHAR(17) to support ISBN-13 with hyphens
- Add normalize_isbn() database function to automatically remove hyphens and spaces
- Create trigger to auto-normalize ISBNs on INSERT/UPDATE operations
- Update all Ebook and MediaItem queries to use ISBN normalization
- Add GetEbookLibraryID query to check for existing ebook libraries
- Add graceful error handling when no ebook library exists
- Return helpful error message: 'no ebook library found. Please create an ebook library first'
- Create comprehensive tests for ISBN normalization and library selection
- Add Bruno test files for various ISBN formats and error scenarios
- Update documentation with ISBN normalization details
- Update scanner to run asynchronously in background worker pool
- POST /api/scanner/scan now returns immediately with job ID (HTTP 202)
- Add GET /api/scanner/status/:jobId for checking scan job progress
- Integrate watch mode with library system for instant ebook detection
- Auto-start watch mode for all libraries on server startup
- Add endpoints for managing watch mode per library:
- POST /api/scanner/watch/start
- POST /api/scanner/watch/stop
- GET /api/scanner/watch/status
- Track which libraries are currently being watched
- Auto-start scheduler on server boot
- Enforce maximum pagination limit of 1000 items per request
- Prevent negative offset values in pagination
- Apply limits to both /api/ebooks and /api/media-items endpoints
- Protect against DoS attacks from large limit values
Fixes security issue: No maximum pagination limit
- Add complete CRUD API for media items notes (/api/media-items/:id/notes/*)
- Add complete CRUD API for media highlights (/api/media-items/:id/highlights/*)
- Add backward compatibility endpoints for ebooks (/api/ebooks/:id/notes/*, /api/ebooks/:id/highlights/*)
- Implement proper validation for request payloads and UUIDs
- Support hex color codes for highlights with default yellow (#ffff00)
- Support position tracking (page:offset or CFI formats)
- Support optional note association with highlights
- Add library routes to main router configuration
- Implement media items API endpoints for library content
- Update existing ebook handlers to use new schema
- Add media rating and progress tracking
- Maintain backward compatibility with existing endpoints
- Support library-specific media item queries
Updates application to support new multi-library architecture
- Update ebook handlers to require admin role for CRUD operations
- Modify folder operations to be admin-only
- Update ebook scanner to associate books with admin who added them
- Add admin ID tracking to CreateEbook operations
- Restrict scanner operations to admin users only
- Change rating validation from 1-5 to 1-10
- Enable half-star precision support in backend
- Maintain compatibility with frontend conversion logic
- Support odd numbers for half-star ratings (1,3,5,7,9)
- Add pgx.ErrNoRows checks in GetEbook and GetReadingProgress
- Improve error handling in GetEbookRating with proper status codes
- Return consistent error responses across all endpoints
- Add missing pgx import for proper error comparison
- Move migrations/ to database/schema/ for clarity on database schema definitions
- Move sqlc.yaml to internal/database/ to group with database code
- Move static/ to cmd/server/static/ to co-locate with server
- Update all configuration files and documentation
- Follow Go project conventions for better organization
- Change Go module name back from 'shelf' to 'bookmann'
- Update all import paths back to 'bookmann' module
- Update README.md project name back to 'Bookmann'
- Update docker-compose.yml container names back to 'bookmann' and 'bookmann_db'
- Regenerate database code with restored module imports
- Rename project from 'bookmann' to 'shelf'
- Move all backend/ contents to root level (flatten structure)
- Update Go module name from 'bookmann' to 'shelf'
- Update all import paths to use new 'shelf' module
- Update Dockerfile to work without backend/ subdirectory
- Update docker-compose.yml to use new structure and rename containers
- Update .gitignore for new file paths
- Update README.md with new project name and structure
- Regenerate database code with new module imports
john-okeefe