Add preview endpoint for custom section builder and rule evaluation:
Handler Implementation (internal/handlers/collections.go):
- PreviewCollection method: Evaluates filter rules and returns matching items without saving
* Accepts library_id, rules array, manual_book_ids array, and limit
* Evaluates rules against all library items using collectionService.EvaluateRules
* Adds manually selected books to results
* Deduplicates manual books (avoids adding same book twice)
* Applies limit (default: 20, max: 100)
* Returns array of BookInfo with matching items
- Helper function: mediaItemsToListMediaItemsRow
* Converts database.MediaItems to database.ListMediaItemsRow
* Required for EvaluateRules which expects ListMediaItemsRow type
Route Registration (internal/router/collections.go):
- POST /api/collections/preview
- Protected by JWT middleware
- Part of collections API group
Why This Endpoint is Necessary:
- Allows users to see what books match their filter rules BEFORE saving
- Avoids creating incorrect collections
- Enables testing different rule combinations quickly
- Reuses existing service logic (collectionService.EvaluateRules)
- Client-side preview would require downloading entire library (10,000+ books)
- Would duplicate 500+ lines of rule evaluation logic in TypeScript
- Would create maintenance nightmare keeping Go and TypeScript in sync
Bruno Test (bruno/collections/preview-collection.bru):
- Tests POST /api/collections/preview endpoint
- Validates status 200 response
- Validates items array in response
- Example request with genre filter rule
This endpoint is required for both the web UI Custom Section Builder and future mobile apps.
Update and create Bruno API tests to reflect new unified collections architecture:
Updated Tests:
1. get-dashboard-sections.yml
- Updated response structure documentation
- Changed from type field to is_system boolean
- Changed from id to media_item_id in items
- Added priority field documentation
- Updated example response to show unified collections structure
- Added test for sections array in response
2. update-preferences.yml
- Changed HTTP method from POST to PUT (matching handler implementation)
- Updated request body field names:
* hidden_sections → hidden_collections
* section_order → collection_order
- Updated documentation with new field names
- Updated example request with valid system collection names
New Tests:
3. restore-system-collection.yml
- Tests POST /api/dashboard/restore-system-collection endpoint
- Validates collection_name against allowed system collections
- Tests success response with message
- Documents valid collection names:
* continue-reading
* recently-added
* recently-read
* not-started
Test Coverage:
- GET /api/dashboard/sections: Returns all dashboard sections
- PUT /api/dashboard/preferences: Updates user preferences
- POST /api/dashboard/restore-system-collection: Resets system collection
All tests follow Bruno YAML format with proper authentication via auth: inherit.
Add after-response scripts to automatically save access and refresh tokens to Bruno environment variables after successful authentication. This eliminates manual token copying during testing.
Changes:
- Refresh Token.yml: Add script to save tokens from refresh response
- Register User.yml: Add script to save tokens from registration response
- Move all files from bruno-yaml/* to bruno/*
- Maintains existing directory structure within categories
- Updates bruno/user/auth files with OAuth2 refresh token flow
- Updates bruno/user/profile files for user profile management
- Adds bruno/dashboard/ directory with dashboard API tests
- Preserves all existing test scenarios and OpenCollection YAML format
- No functional changes - file reorganization only
- Remove 'auth: inherit' from POST request configuration
- Remove post-response script that set token environment variable
- Clean up documentation formatting
This simplifies the login request configuration as authentication
will now be handled via HTTP-only cookies instead of bearer tokens.
- Add IMPLEMENTATION_EXACT.md with exact code changes for all phases
- Update IMPLEMENTATION_PLAN.md with clarifications on two-field approach:
- device_identifier: Serial number (Kobo) or UUID (KOReader)
- auth_token: Auto-generated API key for authentication
- Resolve all user questions with ✅ marked decisions
- Add verification steps for documentation accuracy
- Document Kobo vs KOReader registration workflow differences
- Add SQL query for token regeneration (UpdateDeviceAuthToken)
- Include TypeScript device management code
- Add Bruno API test files for all new endpoints
- Update Kobo setup documentation for URL path token approach
- Fix TestUpdateDevice: Use correct JSON field name and handle float64 type
- Fix TestRejectDeviceRegistration: Expect message response instead of boolean
- Update approve device docs: Add missing response fields
- Update reject device docs: Correct message text and format
- Update Bruno API: Fix example response for reject endpoint
Both integration tests now pass while maintaining API consistency.
System Settings Bruno Tests (new):
- bruno/system/get-scan-settings.bru
- bruno/system/update-scan-settings.bru
- Test GET endpoint for retrieving system scan settings
- Test PUT endpoint for updating system scan settings
- Include admin authentication requirements
- Document response structures
List Users Bruno Test (update):
- bruno/user/admin/List Users.bru
- Add max_devices to response documentation
- Add device_count to response documentation
- Update feature descriptions
These Bruno tests provide API contract verification for the new
system settings endpoints and document the enhanced user list response.
- Add test_create_media_item_no_folders test case
- Document 400 error for libraries without folders
- Add prerequisites section explaining folder requirement
- Include setup workflow example
- Link to Add Library Folder Bruno request
Related: Handler validation and service layer changes
- Convert all existing .bru files from JSON to Bruno DSL format
- Remove obsolete files (conflicts/api.bru, kobo/Kobo Initialization.bru)
- Update auth configuration to use 'inherit' instead of explicit bearer tokens
- Add comprehensive documentation to all test files
- Improve test scripts with proper assertions and error handling
- Rename ebook_id environment variable to media_item_id
- Update scanner endpoint example paths and documentation
- Update library endpoint documentation
- Keep library type 'ebooks' where appropriate (valid type value)
Update Update Media Item.bru to document normalization behavior:
- Note that tags and contributors are auto-normalized (same as Create)
- Document response includes updated search fields
Relates to Tags & Contributors Migration documentation updates
Update Bulk Update Books.bru to demonstrate tag and contributor updates:
- Add tags update example with normalized output
- Add contributors update example
- Shows punctuation preference behavior
Demonstrates that tags and contributors are automatically normalized
when updated via bulk operations, ensuring consistency across the database.
Relates to Tags & Contributors Migration documentation updates
Convert tags and contributors columns from comma-separated strings to PostgreSQL
TEXT[] arrays for better data normalization and query performance.
Database Changes:
- schema.sql: Change tags/contributors from TEXT to TEXT[]
- schema.sql: Add GIN indexes for fast array searches
- queries.sql: Update search queries to use ANY() operator
- queries.sql: Update fuzzy search with unnest() for arrays
Generated Code (sqlc):
- models.go: Auto-generated with []string types for tags/contributors
- queries.sql.go: Auto-generated with proper array handling
Handler Changes:
- media.go: Update request structs to use []string for tags/contributors
- media.go: Remove pgtype.Text wrapping, use direct array assignment
- media.go: Add tag normalization in CreateMediaItemHandler
- collections.go: Update tags evaluation to join arrays for comparison
- collections.go: Add strings import for Join() function
Service Changes:
- ebook_scanner.go: Update EbookMetadata struct to use []string
- ebook_scanner.go: Remove string Join(), assign arrays directly
- collection_service.go: Update tags rule evaluation to join arrays
- collection_service.go: Add strings import
New Utilities:
- internal/utils/tags.go: Create NormalizeTags(), JoinTags(), SplitTags()
- Normalizes tags by trimming, lowercasing, removing duplicates/empties
API Documentation:
- bruno/media-items/Create Media Item.bru: Update examples to use arrays
- bruno/media-items/Update Media Item.bru: Update examples to use arrays
- Update docs: tags/contributors now array of string
Breaking Change:
- JSON format changes from "tags": "tag1,tag2" to "tags": ["tag1", "tag2"]
- Tests already use array format (no changes needed)
Benefits:
- GIN indexes enable faster array searches
- Normalization prevents data quality issues (case, duplicates)
- Array operations use PostgreSQL native operators (ANY, &&, unnest)
- Better separation of concerns (no string parsing in application)
- Update Login User.bru to use testuser@example.com
- Update Register User.bru to use testuser@example.com
- Update Register Admin User.bru to use maxdevices@example.com
- Standardize password to Test@Pass123! across all tests
- Add TEST_DATA.md documenting shared test credentials
- Update bruno.json with documentation reference
- Add comments linking to TEST_DATA.md for cross-reference
This alignment makes it easier to verify test failures between
Bruno API tests and Go integration tests using identical credentials.
- Fix device registration API test parameters
- Update admin user registration test with proper fields
- Ensure API tests match current endpoint behavior
- Improve API documentation accuracy
- Update PROJECT_GUIDELINES.md to reflect current architecture (Hybrid SSR)
- Integrate service layer and SSR rules into existing sections
- Update README.md paths to match new docs structure (docs/developer/api, docs/user/devices)
- Remove redundant README.md files from bruno/ directories
- Update bruno/collection.bru documentation to current API standard
- Fix architectural pattern description from API-driven to Hybrid SSR
Documentation updates:
- All docs/ files: Update project references
- Bruno API collection: Update collection name and tests
- Device setup guides: Update all examples
- Implementation plan: Update database schema examples
- README files: Update project references
Part of project rename to Bookhoard.
Bruno API test updates:
- Update test assertions: X-Bookmann-* → X-Bookhoard-*
- Update variable names and references in test scripts
- Update documentation and comments in API tests
This is part 4 of the project rename to Bookhoard.
Sync-Kobo:
- Auto link books endpoint tests
- Bulk link books endpoint tests
- Get unlinked book suggestions endpoint tests
OPDS:
- Download book with on-the-fly KEPUB conversion tests
All tests cover no user, user, and admin contexts
Add comprehensive Bruno tests for Phase 9 limitations features:
Test Collection Rules.bru:
- Test rule: genre equals "Science Fiction"
- Test rule: author contains "Asimov"
- Test rule: copyright_year greater than 2000
- Test rule: non-existent genre (expects 0 matches)
- Test validation: empty rules array (expects 400)
Bulk Remove Books.bru:
- Setup: Create test collection
- Add multiple books to collection
- Test 1: Bulk remove all books
- Test 2: Bulk remove with some invalid IDs
- Test 3: Empty list validation
- Test 4: Single book removal (bulk should work for 1 too)
- Cleanup: Delete test collection
Test Coverage:
- Rule evaluation API endpoint
- Bulk remove API endpoint
- Request validation
- Response structure verification
- Edge cases and error handling
Bruno Test Format:
- JSON request bodies
- Status code assertions
- Response structure validation
- Setup/teardown for integration tests
These tests ensure the new Phase 9 API endpoints work correctly
and maintain backward compatibility.
- 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
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
- 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 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
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 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
- 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
- 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.
- 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
- 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 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
- Test password complexity requirements
- Test account lockout mechanism
- Test rate limiting functionality
- Test JWT expiration (1 hour)
- Test refresh token expiration (7 days)
- Test password requirements list
- Verify transaction manager and error handler types
- All tests passing
john-okeefe