- Add book matching service for intelligent book deduplication
- Add collection service for collection management
- Add test files for book matching and collections
- Add OPDS handler for device catalog and book downloads
- Add collections handler for collection CRUD
- Add book matching service for cross-device book linking
- Add sidecar handler for Kobo metadata sync
- Add sync handler for device synchronization
- Remove large UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md
- Replace with more focused implementation plan
- Update documentation structure for better maintainability
- Add /devices route for device management interface
- Add /conflicts route for sync conflict resolution
- Add /queue route for sync queue management
- Add comprehensive tests for device cap management
- Add test suite for queue management
- Add comprehensive implementation plan for universal sync system
- Update README with API reference and device setup guides
- Add KOBO_SETUP.md device configuration guide
This plan implements:
- Universal book identification (SHA-256, UUID, ISBN, ASIN, OPF identifiers)
- Enhanced collection management with auto-assign rules
- OPDS-based wireless book delivery for Kobo, KOReader, Web, and Mobile
- Bidirectional progress sync with ContentId mapping
- Device-specific shelf mappings and configuration
- Complete database schema with 7 new tables
- 50+ documented API endpoints
- 10-week phased implementation plan
Features include:
- Cross-device book matching regardless of file paths
- Collections as device-neutral metadata with per-device shelf mapping
- Format conversion (EPUB → KEPUB) with hash integrity preservation
- Three-tier authentication (JWT, device tokens, OPDS)
- Two-layer architecture: OPDS for acquisition + internal APIs for state management
Key design principles:
1. Canonical UUID (Bookmann UUID) always wins for progress tracking
2. Collections ≠ device inventory - organizational metadata only
3. OPDS primary for all devices, internal APIs for web/mobile
4. Dual hash storage prevents format conversion issues
See IMPLEMENTATION_PLAN.md for complete technical details.
- Add SECURITY_AUDIT.md with A- security rating
- Add SECURITY_ENHANCEMENTS.md for improvements
- Add DEVICE_CAP_IMPLEMENTATION.md complete guide
- Add KOREADER_SETUP.md device setup guide
- Add SYNC_USER_GUIDE.md user documentation
- Document all API endpoints and features
- Include security considerations and best practices
- Update User Max Devices - Complete API documentation
- Update User Max Devices - Success test case
- Update User Max Devices - Invalid Zero test case
- Update User Max Devices - Exceeds Maximum test case
- Update User Max Devices - Missing ID test case
- Include validation rules and example payloads
- Document all status codes and error responses
- Test successful updates (5, 10, 50, 100 devices)
- Test validation failures (0, -1, 101, 1000 devices)
- Test authentication requirements (no token, non-admin)
- Test non-existent user ID
- Test missing user ID in URL
- Test max_devices field in user list response
- Add 20+ test cases across 7 test functions
- Helper functions for admin user creation and login
- Add max_devices column to users table (default: 10)
- Add UpdateUserMaxDevices database query
- Add CountUserDevices database query
- Add UpdateUserMaxDevices handler with validation (1-100 devices)
- Add PUT /api/auth/users/:id/max-devices endpoint (admin only)
- Update UserList struct to include max_devices field
- Validate user ID format and max_devices range
- Return appropriate errors for invalid requests
- Add 12 composite database indexes for sync operations
- Composite indexes for sync_queue (device/status/priority)
- Composite indexes for reading_progress (user/media timestamps)
- Composite indexes for devices (user/sync_enabled)
- Composite indexes for annotations (user/media)
- Comment out ALTER SYSTEM commands for sqlc compatibility
- PostgreSQL tuning recommendations included for manual application
Implement conflict detection for concurrent reading progress updates from different devices. Adds conflict management endpoints for listing, viewing, and resolving conflicts.
- Add ConflictHandler with CRUD endpoints for conflict management
- Implement automatic conflict detection in KOReader progress updates
- Add WebSocket broadcast for real-time conflict notifications
- Add database query for listing user conflicts by status
- Add integration tests and Bruno API test collection
- Test login returns both access_token and refresh_token
- Test refresh endpoint accepts UUID token and returns new access_token
- Verifies end-to-end refresh token flow works correctly
- Add parseTokenUUID() helper to convert string to pgtype.UUID
- Update RefreshAccessToken to parse token string to UUID before validation
- Update Logout to parse token string to UUID before revoking
- Update CreateRefreshToken to pass UUID directly to database
- Update auth.go: fix return value order from CreateRefreshToken
- Remove unnecessary comments for cleaner code
- Change token column type from VARCHAR(255) to UUID
- Add gen_random_uuid() as default value for token
- Improves type safety and performance for token storage
- Remove integration_test.sh (redundant with Go integration tests)
- Remove BRUNO_PHASE1_TEST_REPORT.md (temporary test report)
- Remove integration_test_results.txt (temporary test output)
Go-based tests in cmd/server/tests/ provide comprehensive coverage and
are better integrated with the project testing infrastructure.
- Add Kobo sync handler with markup, bookmark, analytics, and initialization endpoints
- Add Kobo integration tests and Bruno API test collection
- Move device approve/reject routes from public to protected routes
- Enhance test infrastructure with DATABASE_URL support and helper functions
- Fix device GetDevice handler nil pointer handling
- Clean up test reports and session files
Add Bruno v3.0 request for testing WebSocket endpoint:
- WebSocket connection type
- JWT token authentication via query parameter
- Ping message body for heartbeat testing
- Assertions for successful WebSocket upgrade (101 status)
Provides API documentation and testing capability for
WebSocket connection functionality per project standards.
Add WebSocket infrastructure to main server:
- Import sync package for ConnectionManager
- Create and start ConnectionManager with cleanup task
- Initialize WSHandler with auth dependencies
- Add /ws/sync WebSocket endpoint
- Update handler initialization to pass ConnectionManager
The WebSocket endpoint at /ws/sync enables real-time progress
updates across all connected clients (web, mobile, devices).
Add WebSocket broadcast to KOReader progress sync:
- Integrate ConnectionManager into KOReaderHandler
- Broadcast progress updates on successful sync
- Include source device information (model, type)
- Real-time updates to all connected clients
When KOReader devices sync reading progress, all connected
WebSocket clients (web browsers, mobile apps, other devices)
receive instant updates.
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.
john-okeefe