Draft
Conversation
- Create spec-003 for supporting manual and external provider books - Add comprehensive user stories for manual book addition, sync isolation, filtering, and external metadata integration - Include clarifications session covering uniqueness enforcement, API timeouts, form validation, rate limiting, and page count validation - Define 12 functional requirements with validation rules - Specify measurable success criteria and edge case handling - Document assumptions, dependencies, and out-of-scope items
- Phase 0 research: 10 architectural decisions documented - Provider interface design with capability flags - Federated search with parallel execution - Circuit breaker pattern for resilience - Source migration with transaction safety - Data model with schema changes and migrations Architecture aligns with constitution: - Zero external dependencies (SQLite only) - Repository pattern for all data access - Self-contained deployment - Preserves complete history Next: Generate API contracts and quickstart guide
- Extended books schema with source/externalId fields for multi-source support - Made calibreId, path, lastSynced nullable (non-Calibre books) - Created provider_configs table for provider runtime configuration - Generated Drizzle migration 0022 with data preservation - Created companion migration to seed default provider configs - Implemented IMetadataProvider interface with capability flags - Implemented ProviderRegistry for provider management - Fixed existing code to handle nullable calibreId fields - Updated rating sync to only affect Calibre books Phase 1 Complete: ✅ T001-T008: Database schema, migrations, provider interface ✅ All TypeScript errors resolved ✅ Backward compatible with existing Calibre books Next: Phase 2 - Repository extensions and services
- Created ProviderConfigRepository with full CRUD operations (T009) - Extended BookRepository with source filtering methods (T010): * findBySource() - get all books from a specific source * findBySourceAndExternalId() - check for existing external books * countBySource() - count books per source - Added source filter parameter to findWithFilters() (T011) - Updated findNotInCalibreIds() to only check Calibre books (T012) * CRITICAL: Prevents orphaning manual/external books during sync Repository Layer Complete: ✅ T009-T012: Source-aware repository methods ✅ Multi-source book tracking foundation ready Next: T013-T020 - Service layer and provider implementations
- Implemented CircuitBreakerService with state machine (T013) - Created ManualProvider stub (T016) - Updated tasks.md to reflect progress Circuit Breaker Features: - State machine: CLOSED→OPEN→HALF_OPEN transitions - Failure tracking with configurable thresholds - 60s cooldown period before retry - Persistence via providerConfigRepository Next: T014-T020 (ProviderService, remaining provider stubs)
Completed tasks T014-T020: Service Layer (T014-T015): - ProviderService: Orchestration layer with circuit breaker protection - Wraps search, fetchMetadata, sync operations - Health check coordination - Provider enable/disable at runtime - MigrationService: Source migration with pessimistic locking - Transactional updates with FOR UPDATE locking - Validation rules (manual → external only) - Metadata update during migration Provider Implementations (T016-T020): - ManualProvider: Stub for user-entered books (no external API) - CalibreProvider: Wraps existing syncCalibreLibrary functionality - Implements sync() and fetchMetadata() methods - Health check via database connectivity test - HardcoverProvider: Stub with search/fetch placeholders - OpenLibraryProvider: Stub with search/fetch placeholders - Provider registration: initializeProviders() function in ProviderRegistry Architecture: - All providers implement IMetadataProvider interface - Circuit breaker protects all provider operations - Health checks run independently per provider - Priority-based provider ordering (Calibre=1, Hardcover=10, OpenLibrary=20, Manual=99) Phase 2 Status: 20/20 tasks complete ✅ Next: Phase 3 (Manual Book Addition UI + Backend)
Completed backend tasks for manual book addition: Validation (T022, T025, T027): - Created manual-book.schema.ts with Zod validation - Required: title, authors (1+ non-empty strings) - Optional: ISBN, publisher, pubDate, totalPages (1-10000), series, seriesIndex, tags - Comprehensive validation rules with user-friendly error messages Duplicate Detection (T023, T024): - Created duplicate-detection.service.ts with Levenshtein algorithm - 85% similarity threshold for title matching - Author matching with normalization - Returns potential duplicates sorted by similarity - Warning-only (doesn't prevent creation) Book Service Extensions (T022, T024): - Added createManualBook() method to bookService - Validates input using Zod schema - Checks for duplicates before creation - Creates book with source='manual', externalId=null, calibreId=null - Auto-creates initial 'to-read' session - Returns book + duplicate detection result - Added checkForDuplicates() for real-time UI checks - Fixed syncRatingToCalibre() to skip sync for non-Calibre books API Routes (T021, T026): - Extended POST /api/books for manual book creation - Detects manual creation vs legacy calibreId updates - Returns 201 Created with book + duplicates - Returns 400 with validation errors on invalid input - Created POST /api/books/validate endpoint - Real-time validation without creating book - Returns validation errors and duplicate detection results Next: Frontend components (ManualBookForm, DuplicateWarning, ProviderBadge)
…omponents (T028-T033) - Add ManualBookForm component with full validation and duplicate detection - Add ProviderBadge component for visual source indicators - Implement real-time validation on blur - Add duplicate warning flow with 'Add Anyway' option - Integrate with BaseModal pattern and toast notifications - Support all book fields (required: title, authors; optional: ISBN, publisher, etc.) Co-authored-by: AI Assistant <ai@example.com>
…roviderBadge display (T032-T036) - Add 'Add Book' button to LibraryHeader component - Integrate ManualBookForm modal in library page with success handler - Display ProviderBadge in BookCard component (top-right corner) - Display ProviderBadge in book detail page metadata section - Include source field in GET /api/books response - Update Book interface to include source and nullable calibreId - Add source to book repository findWithFiltersAndRelations query T032: ✅ Add 'Add Manual Book' button to library page T033: ✅ Integrate ManualBookForm with refresh on success T034: ✅ Add source badge to BookCard component T035: ✅ Add source badge to book detail page T036: ✅ Verify GET /api/books includes source field Co-authored-by: AI Assistant <ai@example.com>
- Set source='calibre' for all books synced from Calibre library - Filter orphan detection to only Calibre-sourced books (repository already implemented) - Add source-aware logging for sync operations - Fix calibreId type handling (now nullable, filter non-null values) T039: ✅ Set source='calibre' during sync operations T040: ✅ Orphan detection filters by source='calibre' (repository level) T041: ✅ All synced books have source='calibre' set explicitly T042: ✅ CalibreProvider respects source boundaries (via sync-service) T047: ✅ Add Pino logging with source filtering details Manual books are now protected from Calibre sync operations. Co-authored-by: AI Assistant <ai@example.com>
- Add default source='calibre' to test fixture helper - Required by Phase 1 schema changes (source field now required) Note: Some tests are flaky due to createdAt timestamp precision (second-level) when books are created in rapid succession. This is a pre-existing timing issue that should be addressed separately by using millisecond-precision timestamps or adding explicit ordering in tests. Related to spec-003 Phase 4 completion. Co-authored-by: AI Assistant <ai@example.com>
- Add source[] query parameter parsing to GET /api/books endpoint - Implement multi-source filtering in BookRepository.findWithFiltersAndRelations - Support both single source and array of sources (OR logic) - Filter uses inArray for multiple sources, eq for single source T048: ✅ Extend GET /api/books to accept source[] query parameter T049: ✅ Update BookRepository with multi-source filtering logic Example: GET /api/books?sources=calibre,manual returns books from Calibre OR manual sources Co-authored-by: AI Assistant <ai@example.com>
Implements T051-T053 from spec-003: Source-based filtering UI Changes: - Add source filter dropdown to LibraryFilters component (multi-select) - Update library page to handle source filter state and URL persistence - Add sources parameter to LibraryService and useLibraryData hook - Include sources in cache keys and query keys - Update all filter handlers to preserve sources state - Add sources to 'Clear All Filters' functionality UI Features: - Multi-select dropdown with checkboxes (calibre, manual, hardcover, openlibrary) - Visual indicator when sources are selected (ring accent + count) - Click-outside-to-close behavior - Persists in URL query params for deep linking - Works with all other filters (tags, status, rating, shelf, etc.) Backend already supports sources filtering via T048-T049 (previous commit). Testing: - Created manual book via API (source='manual') - Verified source filter works: ?sources=manual returns 1 book - Verified multi-source: ?sources=calibre,manual returns 819 books - All 852 existing books have source='calibre' from migration
Implements T073-T074 from spec-003: Provider search methods Hardcover Provider (GraphQL): - Implements search() using Hardcover GraphQL API - Queries Typesense search endpoint with Book type - 5-second timeout using AbortSignal - Parses JSON results into SearchResult format - Handles rate limits and GraphQL errors - Returns up to 25 results per search OpenLibrary Provider (REST): - Implements search() using OpenLibrary Solr API - REST endpoint at /search.json - 5-second timeout using AbortSignal - Extracts work IDs from keys - Constructs cover image URLs from cover_i field - Returns up to 25 results per search Both providers: - Follow IMetadataProvider interface - Include timeout handling (T069) - Log errors and timeouts via Pino - Return normalized SearchResult[] format - Handle missing/malformed data gracefully Testing: - Verified OpenLibrary API with curl - Both providers ready for federated search integration Next: SearchService for Promise.allSettled orchestration
Implements T068, T070-T072, T076 from spec-003: Federated search SearchService (lib/services/search.service.ts): - Implements federatedSearch() with Promise.allSettled (T068) - Searches Hardcover and OpenLibrary in parallel - Per-provider timeout handled by providers (5s, T069) - Search result caching with 5min TTL (T070) - Hardcoded provider priority: Hardcover → OpenLibrary (T071) - Graceful degradation when providers fail (T072) - LRU cache with 100-entry max - Detailed Pino logging per provider - Returns ProviderSearchResult[] with status per provider API Endpoint (POST /api/providers/search): - Zod validation for query parameter (T076) - Calls searchService.federatedSearch() - Returns success/error with provider-level details - Returns totalResults, successfulProviders, failedProviders - 400 for validation errors, 500 for search failures Testing: - Tested with 'harry potter' query - OpenLibrary: 25 results, success - Hardcover: 401 unauthorized (no API key configured) - Demonstrates graceful degradation (T072) Next: FederatedSearchModal UI component (T080-T082)
Implements Phase 7 Frontend (T080-T083): Components: - ProviderBadge: Color-coded badges for each provider (Calibre, Manual, Hardcover, OpenLibrary) - SearchResultCard: Displays book metadata from search results with covers - FederatedSearchModal: Full search flow with provider results, selection, and editable metadata form Features: - Search input with API call to POST /api/providers/search - Per-provider collapsible result sections with status indicators - Result selection pre-fills editable metadata form - Duplicate detection before adding books - Error handling with graceful degradation and fallback to manual entry - Integration with LibraryHeader dropdown menu User Flow: 1. Click "Add Book" dropdown → "Search Providers" 2. Enter search query (e.g., "Harry Potter") 3. View results grouped by provider (Hardcover, OpenLibrary) 4. Select a result to pre-fill metadata 5. Edit any fields before adding 6. Handle duplicate warnings if applicable 7. Book added with correct source (hardcover/openlibrary) Tested: - API endpoint returns results from OpenLibrary (25 results for "the hobbit") - Hardcover gracefully fails with 401 when no API key present - Existing tests pass (4 flaky pre-existing failures unrelated to changes)
- Move FederatedSearchModal and SearchResultCard to components/Providers/ - Enhance ProviderBadge with status indicators (success, error, timeout) - Fix import paths to use correct case-sensitive directory - Update specs/003-non-calibre-books/tasks.md to mark Phase 7 tasks complete - Consolidate duplicate ProviderBadge.tsx from providers/ into Providers/ Resolves case-sensitivity issue between components/providers and components/Providers directories.
Implements provider settings management interface with API endpoints for configuring metadata providers (Calibre, Manual, Hardcover, OpenLibrary). **Provider Settings UI:** - Created /settings/providers page with provider toggles and credentials form - ProviderToggles: Enable/disable providers, health checks, circuit breaker status - ProviderCredentials: Secure API key management with show/hide functionality - Added link to provider settings from main settings page **API Endpoints:** - GET /api/providers - List all providers with configuration and health status - GET /api/providers/[providerId]/config - Get detailed provider configuration - PATCH /api/providers/[providerId]/config - Update provider settings/credentials/enabled state **Key Features:** - Real-time provider health monitoring - Circuit breaker state visualization - Secure credential storage (show/hide API keys) - Provider enable/disable without restart - Capability badges (Search, Metadata, Sync) - Success/error notifications **Architecture Updates:** - Updated ARCHITECTURE.md with multi-source support and provider architecture - Documented provider system, circuit breaker, federated search - Added provider priority and capabilities information **Tasks Completed:** - T085: Provider settings page (app/settings/providers/page.tsx) - T086: Provider enable/disable toggles (components/Settings/ProviderToggles.tsx) - T087: API key configuration form (components/Settings/ProviderCredentials.tsx) - T077: GET /api/providers endpoint (app/api/providers/route.ts) - T078: PATCH /api/providers/[providerId]/config endpoint - T088: Updated ARCHITECTURE.md with multi-source support **Testing:** - Verified API endpoints return correct provider data - Tested credential updates (hasCredentials flag updates correctly) - Tested provider enable/disable toggle - Confirmed provider initialization on API access **Related:** spec-003 (Support Non-Calibre Books) Co-authored-by: Claude <ai@anthropic.com>
- Updated task completion status (T021-T038) - Phase 3 (Manual Book Addition) fully tested and verified - Overall progress: 64/89 tasks (72%) - Created phase3-verification-results.md with test evidence Testing completed: - Manual book creation API (book ID 447306) - Duplicate detection (85% threshold, Levenshtein distance) - Real-time validation UI - Source badges in book cards and detail pages - Source filtering works correctly - Search includes manual books - Rating updates work without Calibre sync All 18 Phase 3 tasks complete and ready for Phase 4 (sync isolation).
- T039-T042, T047: Sync isolation code already implemented - syncCalibreLibrary() only processes Calibre DB books - findNotInCalibreIds() filters by source='calibre' (book.repository.ts:658) - All synced books get source='calibre' (sync-service.ts:225) - CalibreProvider respects source boundaries - Pino logging includes source filtering details Remaining work: - T043-T046: Formal integration tests (code already works) Overall progress: 68/89 tasks code-complete (76%)
- Changed requiresAuth from false to true - Enables API key configuration in Settings UI - API keys needed for higher rate limits and full features - Fixes issue where Hardcover credentials section was hidden
The search modal was incorrectly parsing the API response structure,
causing 'searchResponse.results is undefined' error. The API returns
{ success: true, data: FederatedSearchResponse } but the component
was treating the entire response as FederatedSearchResponse.
Fixed by destructuring the 'data' field from the API response before
setting searchResponse state.
Fixes: Phase 7 federated search functionality (T080-T083)
Hardcover API requires authentication. Updated provider to: - Check for HARDCOVER_API_KEY environment variable - Include Authorization header in API requests - Return clear error message when API key is missing or invalid - Gracefully degrade to OpenLibrary-only search when unconfigured Updated .env.example with Hardcover API key documentation. Fixes 401 Unauthorized errors in federated search (Phase 7). Related: specs/003-non-calibre-books (T073)
Changed Hardcover provider to load API keys from provider_configs database instead of environment variables. This enables: - Runtime configuration through Settings UI without server restart - Proper requiresAuth capability flag (set to true) - User-friendly error message directing to Settings page - Hot-reload when credentials are updated Also fixed companion migration to seed Hardcover with requiresAuth: true. Related: specs/003-non-calibre-books (Phase 7, T073, T077-T078)
- Fix 'results.map is not a function' error by handling Typesense response structure
- Hardcover API returns results as: { hits: [{ document: {...} }], found: N }
- Add TypeScript interfaces for HardcoverSearchResponse and TypesenseSearchResponse
- Extract documents from hits[] array in Typesense wrapper
- Add comprehensive defensive type checking for all possible response formats
- Add diagnostic logging to capture actual API response structure
- Enhance GraphQL query to include ids, query, page, per_page fields
- Update parseSearchResults with safety checks and better error messages
- Fix BookHeader to handle nullable calibreId (support for non-Calibre books)
- Export BookSource type from ProviderBadge for use in other components
Tested with queries 'Dune' and '1984' - now successfully returning 25 results each.
Resolves the Hardcover provider error shown in federated search UI.
- Add totalPages field to SearchResult interface for metadata providers - Update Hardcover provider to map 'pages' field from API response - Update OpenLibrary provider to request and map 'number_of_pages_median' - Display page count in SearchResultCard UI with BookOpen icon - Auto-populate page count in form when user selects search result Benefits: - Helps users distinguish between different editions (paperback vs hardcover) - Improves data quality by pre-filling accurate page counts - Maintains backward compatibility with optional field Test results: - Hardcover API returns page counts for most results (e.g., Oathbringer: 1243 pages) - OpenLibrary API returns median page count across editions - Gracefully handles missing page counts (conditional rendering) - All search service tests passing (18/18)
- Add parsePublishDate() utility to dateHelpers.server.ts - Handles 6+ date formats: ISO, full text, month/year, year-only, partial ISO - Robust error handling for invalid/unparseable formats - 55 comprehensive unit tests (all passing) - Update OpenLibrary provider to use publish_date field - Previously only captured year (first_publish_year) - Now captures full dates when available (e.g., '2019-05-16' vs '2019-01-01') - Falls back gracefully to year-only when full date unavailable - Enhance Hardcover provider to support release_date_i - Handles both Unix timestamp and YYYYMMDD integer formats - Falls back to release_year if integer parsing fails - Maintains backward compatibility Benefits: - More accurate book metadata from external providers - Better user experience with precise publication dates - Maintains backward compatibility with year-only dates - No database schema changes required Tested: - 55 unit tests for date parser (all passing) - Manual verification with OpenLibrary API - No new test failures introduced (3828/3833 passing)
…sing The Hardcover API returns release_date as a string in YYYY-MM-DD format (e.g., '2009-01-01'), not as an integer. Previous implementation incorrectly treated it as an integer and attempted to parse Unix timestamps or YYYYMMDD integers. Changes: - Update HardcoverBook interface: release_date_i (number) → release_date (string) - Simplify date parsing to pass string directly to parsePublishDate() - Remove complex integer parsing logic (Unix timestamp/YYYYMMDD detection) - Maintain fallback to release_year for backward compatibility This aligns with OpenLibrary provider pattern and leverages existing parsePublishDate() function that already handles YYYY-MM-DD format.
…reation paths - Add SessionService.buildInitialSessionData() as canonical session structure - Fix manual book creation: use NULL startedDate for 'to-read' status (not ISO timestamp) - Update Calibre sync to use SessionService data builder for consistency - Implement sequential book+session creation with rollback on failure - Maintain Repository Pattern per constitution (no direct Drizzle operations) Fixes 'invalid time' error when moving manual books to 'reading' status. Root cause: startedDate was ISO timestamp (2026-02-17T22:03:00.294Z) instead of YYYY-MM-DD format (2026-02-17), causing formatDate() to fail. Sessions now consistently use NULL startedDate for 'to-read' books, set to YYYY-MM-DD when status changes to 'reading'.
Discovery: All file path operations query Calibre DB directly. The books.path column in Tome DB was being populated but never read by the application. Changes: - Remove path field from books schema (lib/db/schema/books.ts) - Remove path population from sync service - Remove metadata type interfaces (CalibreMetadata, etc) - Remove getCalibrePath() method (zero callers) - Remove path from all test data - Delete companion migration 0024 - Update drizzle snapshot (0023 -> 0024) Result: Cleaner schema, Calibre DB remains source of truth for paths. Tests: 3946/3948 pass (1 pre-existing failure) Closes #375
- Add book_series field to fetchMetadata GraphQL query - Filter for featured series only (featured = true) - Extract series name from book_series[0].series.name - Extract series index from book_series[0].position - Add series and seriesIndex to BookMetadata return object - Add debug logging when series information is found - Gracefully handle books without series (fields undefined) Tested with: - Oathbringer (Stormlight Archive #3) - ✓ series data retrieved - Dune (Dune #1) - ✓ series data retrieved - The Martian (standalone) - ✓ no series, no errors Relates to Hardcover API documentation: https://docs.hardcover.app/api/graphql/schemas/bookseries/ Co-authored-by: OpenCode <noreply@opencode.ai>
- Add Series and Series Index form fields to FederatedSearchModal - Pre-fill series fields when fetching metadata from providers - Include series data in book creation payload - Reset series fields when form is cleared - Display series fields after Publisher/Publication Date fields Now users can see and edit series information when adding books from Hardcover or other providers. Co-authored-by: OpenCode <noreply@opencode.ai>
- Add toast notification when validation errors occur - Show which fields have validation errors in the toast - Add inline error display for tags field - Ensures users are aware of validation failures Previously, validation errors were captured but not shown to the user, leaving them unaware that their submission failed. Now errors are displayed both as a toast notification and inline below the affected fields. Fixes issue where tags validation error (too many tags or tags too long) was not visible to the user. Co-authored-by: OpenCode <noreply@opencode.ai>
- Hardcover can return 200+ tags which exceeds validation limit of 50 - Now limiting extracted tags to first 50 tags - Truncating individual tag strings to 50 characters max - Added warning log when tags are truncated - Prevents validation errors when creating books from Hardcover provider
- Remove toast notification for tag validation errors - Remove inline error display for tags field - No longer needed since we now defensively limit tags at the Hardcover provider level (commit 76ffae7) - Simplifies error handling by preventing the issue at the source This reverts the changes from commit 97c0f8f
- Deduplicate tags when creating manual books (prevent duplicates at source) - Use index-based keys for tag rendering to handle edge cases - Fixes React warning: 'Encountered two children with the same key' - Improves data quality by ensuring tags are unique per book Example: Book 736240 had 50 tags with many duplicates (Fantasy x4, Young Adult x3, Fiction x4, etc.), now reduced to 29 unique tags.
- Changed key from 'tag' to '${tag}-${index}' in TagEditor
- Prevents React duplicate key warnings if books have duplicate tags
- Added comment documenting that remove removes ALL instances of a tag
- This is expected behavior - clicking 'Fantasy' should remove all 'Fantasy' tags
- Automatically deduplicate tags when TagEditor modal opens - Show blue notice when duplicates were found and removed - Deduplicate tags before saving to database (defensive measure) - Fixes issue where books with 50 tags (many duplicates) show correctly Example: Book 736240 had Fantasy x4, Young Adult x3, Fiction x3, etc. Now shows only unique tags in the editor and saves deduplicated version.
- Deduplicate tags at the source (Hardcover provider) not downstream - Remove unnecessary deduplication from TagEditor modal - Remove unnecessary deduplication from useBookDetail hook - Keep deduplication in createManualBook (handles direct user input) - Simplifies codebase by handling issue at origin This is cleaner architecture - prevent the problem upstream rather than fix it downstream in multiple places.
When uploading a new cover image (via file or URL), the browser continued displaying the old cached image because the book's updatedAt timestamp was not being updated. This caused the cache-busting URL query parameter (?t=timestamp) to remain unchanged. Changes: - Update book.updatedAt after successful cover save in POST handler - Add server-side cover download from URL (bypass CORS) - Simplify client components to send URL directly to API - Extract CoverUploadField component for DRY principle The cache-busting mechanism (getCoverUrl) uses updatedAt as the timestamp, so updating it after cover upload forces browsers to fetch the new image immediately without requiring hard refresh. Fixes cover caching issue where new covers wouldn't display after upload.
…rnal sources Manual books (books created directly in Tome) have no entry in the book_sources table. The previous source filter logic only checked for books IN book_sources, which meant the 'manual' filter returned zero results. Updated filtering logic in both findWithFilters() and findWithFiltersAndRelations() methods to: - For 'calibre' and other external providers: find books IN book_sources - For 'manual': find books NOT IN book_sources (no external source) - For multiple sources: use OR logic (show books from ANY source) This fix allows users to filter their library by manual books, addressing the issue where book ID 736242 and other manual books weren't appearing when filtering by 'manual' source. Tested with 2 manual books and 851 Calibre books (non-orphaned). All repository tests pass (71 tests).
…layout - Move Sources and Shelves filters into a 2-column grid layout (50/50 split on desktop) - Remove duplicate Shelves filter section that was positioned after Tags - Tags filter remains as the last filter item - Maintains responsive behavior (will stack vertically on mobile via grid)
Remove the source badges (Calibre, Audiobookshelf, etc.) overlay from book card covers for a cleaner UI
…pills Replace simple comma-separated text inputs with interactive tag management UI in both 'Add Book from Search' and 'Add Manual Book' modals. Users can now: - Search and select from existing tags with autocomplete - See selected tags as visual pills with X buttons for removal - Create new tags by pressing Enter - Remove all tags at once with 'Remove All' button This makes tag entry more discoverable, prevents typos, and provides consistent UX with the existing 'Edit Tags' modal. Implementation uses the inline pattern (reusing TagSelector component) rather than creating a shared abstraction for flexibility. Changes: - Add TagSelector component with autocomplete dropdown - Fetch available tags from /api/tags on modal open - Display selected tags as removable Button pills - Change tags state from string to string[] in both modals - Update submit logic to use array directly (no comma-splitting) Tests: 3946 passed, no regressions introduced
Make TagSelector dropdown intelligently decide whether to close based on user interaction context: - When user searches and clicks a tag, close dropdown (they found what they wanted) - When user browses without search and clicks tags, keep open for rapid multi-selection - Keyboard Enter behavior unchanged (stays open for power users) This improves UX in both Edit Tags modal (/books/:id) and Add Manual Book modal (/library)
Fixes issue where deleted books remained visible on /library page until
manual refresh. Problem was multi-layer cache invalidation failure.
Changes:
- Add revalidatePath('/library') to DELETE endpoint for server cache
- Clear LibraryService cache before navigation in DeleteBookModal
- Add router.refresh() to force Next.js router cache refresh
- Remove 500ms setTimeout delay (unnecessary with proper cache clearing)
The issue required clearing three separate caches:
1. Next.js App Router server-side cache (revalidatePath)
2. LibraryService client-side in-memory cache (clearCache)
3. Next.js router client-side cache (router.refresh)
Tested: Books remain properly removed from library view on redirect.
When creating manual books or adding books from search providers with cover images, covers would not display until browser cache was refreshed. This occurred because: 1. ManualBookForm: Cover uploaded after book creation, but React Query cache not invalidated - frontend kept stale book object with old updatedAt timestamp 2. FederatedSearchModal: Server-side async cover download didn't update book timestamp, so cache-busting URL never changed 3. Background downloads in book.service.ts saved covers but didn't update updatedAt Changes: - ManualBookForm: Invalidate React Query cache after successful cover upload - FederatedSearchModal: Invalidate cache with 2s delay for async server download - book.service.ts: Update book.updatedAt after background cover download completes This ensures cache-busting URLs (?t=timestamp) get new timestamps when covers are ready, forcing browsers to fetch the actual cover instead of cached placeholders. Fixes issue where duplicate books from search providers consistently showed fallback images until hard refresh.
…base Replace all occurrences of 'Manual' terminology with 'Local' to better reflect that these books are stored locally in Tome's database rather than being sourced from external providers. Breaking Changes: - API: Query parameter 'sources=manual' → 'sources=local' - Types: ManualBookInput → LocalBookInput, ManualBookUpdate → LocalBookUpdate - Components: ManualBookForm → LocalBookForm - Service methods: createManualBook() → createLocalBook() - Strategy: manualSessionUpdateStrategy() → localSessionUpdateStrategy() Changes: - Update database schema: remove 'manual' from provider_configs enum - Rename validation schemas: manual-book.schema.ts → local-book.schema.ts - Update all service methods and repository filters - Update all React components and UI text - Update API routes and validation - Update tests to use new terminology - Update documentation (ARCHITECTURE.md, TODOS.md) Bonus Fix: - Remove premature 'audiobookshelf' from ProviderId type (not yet implemented) Tests: 3946 passed (1 pre-existing failure unrelated to changes) Build: Successful
Migration 0022 recreated the books table to make calibre_id nullable, which dropped the rating check triggers originally created in migration 0005. SQLite automatically drops all triggers when a table is dropped. This migration restores the triggers that enforce rating must be between 1 and 5. Fixes failing test: 'should enforce rating between 1 and 5 on books table'
Change Calibre icon from Database to LibraryBig and Local icon from User to Database in both the library filter dropdown and provider badges for more intuitive visual representation of source types.
…lidation error UX - Add tag truncation (50 chars max) and deduplication to OpenLibrary provider - Mirrors existing Hardcover provider implementation (commits f2868b4, 76ffae7) - Prevents validation errors by limiting to 50 unique tags at provider level - Add toast notifications for all validation errors in FederatedSearchModal - Add inline error display for tags field validation - Improve tag validation error messages to show specific limits (50 tags max, 50 chars per tag) - Makes it immediately clear when form submission fails validation Fixes issue where OpenLibrary could return 200+ tags causing silent validation failures. Users now see clear error messages for all validation issues with specific limits.
When books were added via Search Providers (OpenLibrary/Hardcover), covers would display as fallback images until page refresh. This was caused by a race condition: 1. Book created and returned to client immediately 2. Browser rendered book list and requested cover within ~150ms 3. Background cover download still in progress (~300-400ms) 4. Cover API served fallback image which browser cached 5. By the time download completed and cache invalidation fired (2s), browser had already cached the wrong image Solution: Change from fire-and-forget async downloads to synchronous awaited downloads. Server now blocks until cover is downloaded before returning the book response. This ensures: - Cover is available when browser first requests it - updatedAt timestamp is current from the start - No need for client-side delayed cache invalidation Book creation now takes ~300-400ms longer (download time) but provides better UX with covers displaying immediately. Downloads are still wrapped in try-catch to ensure book creation succeeds even if cover download fails. Affects both OpenLibrary and Hardcover providers equally.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A major architectural shift: decoupling Tome's books schema from Calibre. This is an extensible, provider-driven architecture that enables us to add additional metadata and sync providers into the future, like an #364.
This PR is draft because it is still a heavy work in progress.