- 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.
Add device token validation method for WebSocket authentication:
- Validates device auth tokens against database
- Returns device information for valid tokens
- Used by WebSocket handler for device authentication
This enables devices to authenticate WebSocket connections
using their bearer tokens.
Add ConnectionManager for real-time WebSocket communication:
- Message types for progress updates, annotations, conflicts
- Broadcast message structure with source device tracking
- Device connection tracking with user and device metadata
- Automatic broadcast loop with concurrent message delivery
- Connection management (add, remove, get by ID/user)
- Stale connection cleanup (2-minute timeout)
- Connection statistics by device type
- Background cleanup task runs every minute
This implements the core WebSocket infrastructure needed for
Week 9 of the Universal Sync Implementation Guide.
- Add bulk_update_progress_from_koreader() function for batch processing
- Handles progress, annotations, and conflict detection
- Returns success/failure status for each book
- Supports device matching by UUID, file path, or title/author
- Implements automatic conflict detection for concurrent syncs
- Part of Phase 3 KOReader Integration implementation
- Add KOReader sync endpoints to main application router
- Create Bruno API collection for testing KOReader endpoints
- Add integration tests for KOReader functionality
- Include comprehensive README with setup instructions
- Test coverage for progress, metadata, library, and bookmarks sync
- Part of Phase 3 KOReader Integration implementation
- Update device auth middleware to set actual device object
- Change from DeviceContext to database.Devices
- Fix RequirePermission to use database.Devices
- Ensures handlers can access full device information
- Required for KOReader sync handlers to function properly
- Create SyncProgress for bidirectional progress synchronization
- Create GetMetadata for book progress and annotation retrieval
- Create GetLibrary for user library sync
- Create SyncBookmarks for annotation management
- Support device matching by UUID, file path, or title/author
- Implement immediate and checkpoint sync modes
- Handle bookmarks, highlights, and notes synchronization
- Part of Phase 3 KOReader Integration implementation
- Add GetMediaItemByFilePathForSync for file path matching
- Add GetUserProgressForBooks for bulk progress retrieval
- Add GetAnnotationsForBook for annotation sync
- Add UpdateDeviceSyncTimestamp for device tracking
- Add GetUserMediaItemsForSync for library sync
- Add CheckForProgressConflicts for conflict detection
- Regenerate sqlc code for all new queries
- Part of Phase 3 KOReader Integration implementation
- Add bulk_update_progress_from_koreader() function for batch processing
- Handles progress, annotations, and conflict detection
- Returns success/failure status for each book
- Supports device matching by UUID, file path, or title/author
- Implements automatic conflict detection for concurrent syncs
- Part of Phase 3 KOReader Integration implementation
- 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
- Remove manual device ID generation, use database-generated IDs
- Add comprehensive test helpers (setupTestServer, loginTestUser, getTestUserID)
- Add cleanup step for existing test users in integration tests
- Fix UUID parsing from database responses
Test Files Added:
- integration_test.sh: Automated integration test script
* Tests full user flow: register, login, library creation, scanning
* Tests device registration and management
* Color-coded output with pass/fail tracking
* Generates detailed test results report
- cmd/server/tests/device_test.go: Unit tests for device endpoints
* TestDeviceRegistrationFlow: Full registration flow test
* TestListDevices: Device listing functionality
* TestUpdateDevice: Device settings updates
* TestDeleteDevice: Device removal
* TestDeviceAuthentication: Device auth middleware test
- cmd/server/tests/phase1_integration_test.go: Phase 1 integration tests
* Tests universal progress tracking
* Tests format group detection
* Tests progress conversion
Test Coverage:
- Device registration with web-based approval flow
- Device management (list, update, delete)
- Device authentication and token validation
- User authentication and authorization
- Library creation and management
- Scanner integration
- Media items listing
Notes:
- Tests designed to run against live server on localhost:8765
- Integration test script uses bash/curl for endpoint testing
- Device tests require helper functions to be implemented
- Add internal/sync package with format detection
- FormatGroup types: reflowable, fixed_layout, comic_archive
- DetectFormatGroup() function based on mimetype and file extension
- MimeType mappings for common ebook formats
- Progress conversion engine with:
- ConvertProgress() between format groups
- Extract percentage from various progress formats
- PageToPercentage / PercentageToPage helpers
- CharacterToPercentage / PercentageToCharacter helpers
- MergeProgress() with 'max progress wins' strategy
- FormatProgressForDisplay() for UI rendering
- Add sqlc queries for format detection and progress updates
- BulkUpdateFormatGroups query for auto-format detection
- GetUniversalProgress query with all location references
- UpdateUniversalProgress query with device sync metadata
- ReadingHistory queries for session tracking
Add missing Bruno requests for all API endpoints:
Library Management:
- Get Library - retrieve single library details
- Update Library - modify existing library
- Delete Library - remove library and media items
- Delete Library Folder - remove folder from library
- Get Library Stats - retrieve library statistics
Media Items Management:
- Create Media Item - add new media with full metadata
- Update Media Item - modify existing media metadata
- Delete Media Item - remove media from library
- Get Media Rating - retrieve single media rating
- Delete Media Rating - remove user's media rating
Coverage now complete: 47/47 API endpoints have Bruno requests
Organized requests in proper folder structure for maintainability
- Remove MIGRATION_FINAL_STATUS.md - migration is complete
- Remove REMOVE_EBOOKS_SYSTEM.md - system cleanup finished
- Repository now focused on current working code
- Remove ebook-specific test files (ebook_test.go, integration_test.go, notes_highlights_test.go)
- Update search_test.go for media-items API paths
- Regenerate templates (bookshelf_templ.go, header_templ.go)
- Add ISBN normalization utility function
- Clean up test suite to focus on media-items functionality
Aligns tests and templates with unified media-items architecture
- Remove all ebook-specific API requests (15 files deleted)
- Rename Scan Ebooks.bru to Scan Media Items.bru
- Update API paths from /api/ebooks to /api/media-items
- Update base URL and environment configuration
- Maintain all existing media-items, library, auth, and progress tests
Aligns Bruno collection with unified media-items API architecture
- Remove API_TESTING_SUMMARY.md, IMPLEMENTATION_SUMMARY.md
- Remove MIGRATION_PROGRESS.md, SECURITY_*.md files
- Clean up temporary documentation files from previous sessions
- Repository now focused on current working code
- ebook_scanner.go:293 now compiles successfully
- GetLibraryByFolder method available after database code regeneration
- Scanner service can properly find libraries by folder path
Fixes primary compilation error blocking build
- 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
Major changes:
- Rename testEbooks() function to testMediaItems()
- Remove all old ebook test cases
- Update all /api/ebooks paths to /api/media-items
- Update TestContext: remove EbookID, add MediaItemID field
- Add admin media-items tests (Create, Update, Delete)
- Fix compilation errors and missing imports
Tests updated to use new API structure while maintaining test coverage.
Breaking change: /api/ebooks endpoints removed (use /api/media-items instead)
- README: Document new sorting options (12 fields)
- README: Document new filtering capabilities (6 filter types)
- README: Document enhanced metadata fields (9 new fields)
- README: Update prerequisites to mention Podman
- IMPLEMENTATION_SUMMARY: Mark all phases as complete
- Add API usage examples for sorting and filtering
- Add integration tests for sorting (sorting_test.go)
- Test sort by title, author, page_count, copyright_year, genre
- Test pagination with sorting
- Test invalid sort parameter defaults
- Cover no user, user, and admin contexts
- Add integration tests for filtering (filtering_test.go)
- Test filter by genre, language, year range, has_cover
- Test combining multiple filters
- Test filtering with pagination and sorting
- Cover no user, user, and admin contexts
- Add Bruno API test for sorting
- Add Bruno API test for filtering
Comprehensive documentation of:
- Create Library 500 error bug and fix
- Root cause analysis (type mismatch in context extraction)
- Testing issues discovered (poor error reporting, mock vs real tests)
- Test improvements implemented
- Tomorrow's 5-phase action plan for API reliability
- Complete endpoint checklist for testing
- Correct vs incorrect code patterns
- Success criteria for "rock solid" API
Reference document for tomorrow's comprehensive API review session.
- Add explicit status code check (require.Equal 201)
- Remove conditional success/failure branching
- Provide clear error message with actual vs expected status
Now if CreateLibrary returns 500, test will clearly show:
"Failed to create library: expected 201, got 500"
Instead of vague "Library ID is empty" message that hid the 500 error.
- Use c.Get("user").(database.Users) instead of c.Get("user_id").(string)
- Extract userUUID from user.ID.Bytes ([16]byte)
- Properly convert to pgtype.UUID for service layer
- Remove unnecessary uuid.Parse call
This fixes 500 Internal Server Error when creating libraries via API.
The JWT middleware sets user as database.Users struct, not string.
Related to Bruno Create Library request testing.
- Document search capabilities in Media Management section
- Add API endpoint documentation for /api/media-items/search
- Include search behavior, ranking, and examples
- Document fuzzy search fallback for typos
- Add comprehensive search integration tests (search_test.go)
- Test no user, user, and admin contexts
- Test partial matching, fuzzy fallback, special characters
- Add Bruno API test for search endpoint
- Fix missing closing parenthesis in test structure
- Create search.js with debounced input (300ms)
- Display results in dropdown modal with highlighted matches
- Support keyboard navigation (arrows, Enter, Escape)
- Show result count and 'no results' state
- Highlight matching terms in results
- Add autocomplete attribute to search input
- Minimum 2 characters to trigger search
- Fix scoping issue with err variable in os.Stat check
- Properly check for non-existent vs inaccessible folders
- Use reassignment (=) instead of declaration (:=) since err already declared
- 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
- Add SearchMediaItems query with ILIKE partial matching
- Add SearchMediaItemsFuzzy query with word_similarity()
- Use sqlc.narg() for named parameters (search_pattern, search_query)
- Rank results by relevance: title > author > series > tags
- Fuzzy threshold set to 0.3 for word_similarity
- Generated Go models with proper parameter types
- Changed Header component calls from text to proper templ syntax (@Header)
- Header now properly renders navigation, search, theme switcher, and user menu
- Fixed both bookshelf.templ and dashboard.templ templates
- Added direct /bookshelf route that works with both Authorization header and cookie token
- Imported missing strings package
- Users can now access /bookshelf directly instead of /api/bookshelf
- Regenerate all template files after adding header component
- Clean up generated session files
- Templates now use new header component consistently
All templates have been regenerated to include the new
header functionality and updated routing.
- Replace navigation bar with Header() component
- Remove duplicate logout function (now in header.js)
- Maintain consistent header across pages
- Update generated template files
This provides consistent navigation and theme switching
functionality across all pages using the reusable header component.
- Add JavaScript to check for valid JWT token on homepage load
- Auto-redirect to /bookshelf if user is already logged in
- Shows login/register form if not authenticated
- Improves UX by taking logged-in users directly to bookshelf
Implementation:
- Fetch /api/auth/profile with stored token
- On success, redirect to /bookshelf
- On failure, silently stay on homepage
- Runs on DOMContentLoaded for fast execution
- Add /bookshelf route as default page for logged-in users
- Update login and register handlers to redirect to /bookshelf
- Update homepage to auto-redirect to /bookshelf when logged in
- Preserve /dashboard route for backward compatibility
- Update test redirects to use /bookshelf
Changes:
- main.go: Add /bookshelf protected route
- auth.go: Change login/register redirects from /api/dashboard to /bookshelf (2 locations)
- edge_cases_test.go: Update test redirect to /bookshelf
- Maintains backward compatibility with existing /dashboard route
This makes the beautiful bookshelf the default landing page
for all authenticated users while keeping the old dashboard accessible.
- Create bookshelf.templ with beautiful visual bookshelf interface
- Implement wooden shelf appearance with CSS gradients
- Add responsive grid layout (2/3/6 columns based on screen size)
- Books display with 3D spine effect and hover animations
- Auto-select first library and load books on page load
- Empty state and loading state handling
Visual Features:
- Wooden shelves with gradient shadows (12px bottom border)
- Books hover with lift (translateY) and rotation effects
- Book covers with aspect ratio 2/3 and inset spine highlight
- Error handling falls back to placeholder-book.svg
- 6 books per shelf for optimal display
JavaScript Features:
- Fetch visible libraries from API
- Populate library selector dropdown
- Load and display media items on shelves
- Handle empty states gracefully
- Book detail placeholder (to be implemented)
- Add header.templ component with app title, search, theme switcher, user menu
- Implement dropdown menus for theme selection and user actions
- Add wood theme options (Wood Light, Wood Dark, Wood Mahogany)
- Support all existing themes with visual color swatches
- Auto-close dropdowns when clicking outside
- TypeScript header functionality with proper type safety
Features:
- Left: App title "📚 Bookmann" linking to /bookshelf
- Center: Search box (ready for future search functionality)
- Right: Theme switcher button with color dropdown → User icon menu
- User menu includes Settings, Admin Panel (if admin), and Logout
- Theme persistence to localStorage and server via API
- Add fallback to login when user registration returns 409 Conflict
- Prevents empty user token error when test user already exists
- Allows integration tests to run reliably across multiple executions
- Test now attempts to log in with existing credentials if registration fails
This fixes the issue where the test would fail if the user
'integrationuser@test.com' already existed from a previous test run.
- 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.
- Change from htmx:beforeSwap to htmx:afterSwap event for better error timing
- Simplify event listener setup (removed duplicate handlers)
- Remove 'export {}' statement that was causing syntax errors
- Add proper TypeScript interface for HTMX event details
- Errors now detected after content swap, ensuring accurate error messages
- Toast notifications work correctly for all backend HTTP errors
Resolves JavaScript syntax error on page load and improves error handling.
- Change module setting from 'ES2020' to 'none'
- Remove resolveJsonModule and moduleResolution options (incompatible with module: none)
- Prevents TypeScript from adding 'export {}' statements to compiled JS
- Scripts are loaded as regular JavaScript, not ES modules
- Fixes 'Unexpected token export' error in browser
This allows TypeScript type checking while generating plain JavaScript
that works with traditional script tags in HTML.
- Extract inline JavaScript from index.templ
- Replace with external script include for theme.js
- All templates reference /static/ for assets
- Cleaner separation of concerns between markup and logic
- Create web/src/ for TypeScript source files
- Create web/static/ for compiled assets and runtime files
- Move input.css and style.css to web/static/
- Add toast.ts - Functional toast notification system
- Add theme.ts - Functional theme management system
- All code uses functional programming (no classes, no OOP)
- TypeScript provides full type safety
Separates frontend code from backend for better organization.
- Add node_modules/ and npm debug logs
- Add TypeScript build artifacts (*.tsbuildinfo)
- Ignore compiled JS files in web/static/
- Keep htmx.min.js (third-party library)
- Add IDE ignores (.idea, .vscode)
- Add OS ignores (DS_Store, Thumbs.db)
- Add database and uploads directories
- Ignore package-lock.json (use npm shrinkwrap for production if needed)
Standard ignore patterns for modern web development with Go backend.
- Add Makefile with convenient test targets (test, test-integration, test-env-up, test-env-down)
- Add .env.test with test-specific configuration
- Update .env.example with test configuration options and warnings
- Update README.md with comprehensive testing documentation
- Document all environment variables with safety warnings
This makes it easy to run tests without rate limiting issues while
keeping production security intact.
- Fix SetLibraryVisibility request format (library_ids -> library_id)
- Fix UpdateReadingProgress HTTP method (POST -> PUT)
- Fix DeleteMediaNote expected status (200 -> 204)
- Add cleanupTestData() helper for better test cleanup
- Improve Setup_CreateDuplicateTestUsers to handle existing data
- Add graceful handling of 409 and 429 responses
- Update password test to create/delete temporary user
- Add test requirements comment at top of file
These changes improve test reliability and reduce flakiness.
- Add TestMode, RateLimitEnabled, RequestsPerMinute to Config
- Add getEnvBool() and getEnvInt() helper functions
- Update rate limiter to support enabled/disabled state
- Pass test environment variables through docker-compose
- Configure rate limiter dynamically in main.go
This allows disabling rate limiting for integration testing while
maintaining security in production environments.
- ListLibraries now returns {"data": []} instead of []
- ListUsers now returns {"data": []} instead of []
- ListMediaItems now returns {"data": []} instead of []
This provides consistent response structure across all list endpoints
and aligns with integration test expectations.
- 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.
- Add ISBN normalization documentation
- Document background scanning and watch mode features
- Add scan settings API endpoints
- Include integration testing section
- Update architecture section with new services
- Document auto-starting services
- Add recently added features section
- Update testing documentation with integration tests
- Enhance security section with ISBN validation
- 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
Standardize all Bruno environment variables to use snake_case convention
(aligned with Go naming practices) and remove duplicate camelCase variants.
Changes:
- Environment file cleanup:
- Remove: baseUrl, ebookid, fakebookid, libraryId, mediaItemId, isVisible, refreshToken
- Standardize: fakebookid → fake_book_id, isVisible → is_visible, refreshToken → refresh_token
- All variables now use consistent snake_case format
- Update all Bruno requests to use standardized variables:
- ebooks: {{ebookid}} → {{ebook_id}}
- library: {{libraryId}} → {{library_id}}
- media-items: {{mediaItemId}} → {{media_item_id}}
- visibility: {{isVisible}} → {{is_visible}}
- auth: {{refreshToken}} → {{refresh_token}}
Benefits:
- Single source of truth for each variable
- Consistent with Go naming conventions
- No ambiguity about which variable name to use
- Cleaner, more maintainable codebase
- Add missing variables to Bookmann environment:
- library_id (snake_case variant)
- media_item_id (snake_case variant)
- job_id for scan status tracking
- baseUrl (camelCase variant for compatibility)
- refreshToken to secret vars
- Remove invalid vars sections from request files
- Variables should be referenced directly from environment
- Vars sections are for request-specific overrides, not env references
- All variables now properly defined and accessible
- Update scan endpoint test to expect HTTP 202 with job ID
- Add tests for new scan job status endpoint
- Add tests for watch mode start/stop/status endpoints
- Update all scanner tests to reflect async behavior
- All tests passing
- Update Scan Ebooks.bru to reflect async background scanning
- Add Get Scan Status.bru for checking job progress
- Add Start Watch Mode.bru for instant file monitoring
- Add Stop Watch Mode.bru for stopping library monitoring
- Add Get Watch Mode Status.bru for checking watched libraries
- Document all new endpoints with examples and status codes
- Add RequestTracingMiddleware to middleware chain
- Auto-start scheduler for auto-scanning on server boot
- Auto-start watch mode for all libraries with 2-second delay
- Update SetupRoutes to return handler for service management
- 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
- Add Worker service with configurable worker pool for async job processing
- Implement job queue with status tracking (pending, running, completed, failed, cancelled)
- Add Scheduler service for auto-scanning based on user scan settings
- Check scan settings every 5 minutes and schedule background scan jobs
- Support multiple libraries with individual scan frequencies (15-1440 minutes)
- Regenerate queries.sql.go with refresh token queries
- Update models.go with RefreshTokens type
- Update querier.go with new query methods
- Update db.go with generated code
john-okeefe