Add a volume-mapping guide and surface build/version metadata throughout the project.
Changes included:
- documentation: Add documentation/deployment/volume-mapping.md and update TABLEOFCONTENTS.md and README to reference it (helps users align download client and RMAB paths).
- CI: Capture package.json version in .github/workflows/build-unified-image.yml, pass APP_VERSION as a build-arg, and update the Discord notification to show the semantic version and pull `:latest`.
- Docker: Declare ARG APP_VERSION and expose NEXT_PUBLIC_APP_VERSION / APP_VERSION / GIT_COMMIT env vars in dockerfile.unified so runtime and client can read the semantic version and commit.
- App API/UI: Update src/app/api/version/route.ts and src/components/ui/VersionBadge.tsx to prefer semantic app version (APP_VERSION / NEXT_PUBLIC_APP_VERSION), include fullVersion and commit info, show commit in tooltip, and adjust fallback/dev labels.
- Tests: Update tests (system.routes.test.ts and VersionBadge.test.tsx) to reflect the new version/commit fields and behavior.
- Audible integration: Add ipRedirectOverride query param to multiple Audible requests to avoid IP-based region redirects.
- Misc: Bump package.json version to 1.0.0.
These changes make version information consistent between build, runtime, and UI, improve CI notifications, add user guidance for common volume-mapping issues, and harden Audible scraping against region redirects.
improve container startup for rootless Podman, plus related refactors and tests. Key changes:
- Add/modify Audiobookshelf-related code and wiring (src/lib/services/audiobookshelf/api.ts, library service refs) and update documentation TABLEOFCONTENTS to reference ABS implementation.
- Detect user namespace in docker/unified app-start.sh and redis-start.sh and skip gosu when running in rootless Podman to preserve UID mapping; improve startup logging and verification.
- Add utility/service files (auth-token-cache.service.ts, credential-migration.service.ts, cleanup-helpers.ts) and corresponding tests; update chapter-merger and metadata-tagger utilities/tests.
- Update many admin/auth API routes and tests to reflect changes in settings and integrations.
- Remove large AI agent and Audiobookshelf implementation guide docs (AGENTS.md and the implementation guide) and add README note about AI-assisted workflow.
These changes enable Audiobookshelf backend mode, improve compatibility with rootless container runtimes, and include cleanup/refactor work and unit tests.
Add bidirectional path mapping and complete_dir-aware category sync to the SABnzbd integration. Introduces PathMapper usage, complete_dir extraction, calculateCategoryPath(), and ensureCategory() logic to choose empty/relative/absolute category paths; ensureCategory is invoked before adding NZBs. Update singleton factory to load download_dir and path-mapping config from DownloadClientManager and recreate the service when config is not loaded. Make DownloadClientManager pass path-mapping config into the SABnzbd service. Change request deletion to remove plex_library records by ASIN (deleteMany) with a fallback to exact title/author matches so availability checks and deletions are consistent. Update documentation and tests to reflect the new behavior and APIs.
Ensure ensureCategory applies reverse path mapping (local → remote) before creating or editing qBittorrent categories. Uses PathMapper.reverseTransform to compute the remote save path and updates logging and error details to reference the transformed path. Adds integration tests covering category creation, updating, and no-op when the remote path already matches.
Implements support for configuring both qBittorrent and SABnzbd simultaneously, including migration from legacy config, protocol-aware routing, and protocol filtering. Adds new CRUD API routes for download clients, new UI management components, and updates setup and settings flows to use the new multi-client architecture. Updates documentation to describe the new structure and usage.
Adds file hash-based matching for Audiobookshelf library items to ensure 100% accurate ASIN assignment for RMAB-organized content. Removes fuzzy matching from library availability checks, making all matching ASIN-only to eliminate false positives and race conditions. Updates database schema, processors, and matcher utilities; adds new tests and documentation for the new matching strategy. Removes obsolete scripts, Dockerfile, and related tests; updates docker-compose for test environments.
Introduces 'series' and 'seriesPart' fields to the Audiobook model and database schema. Updates API routes, file organization, and path template utilities to support series metadata. Enhances chapter merging logic, improves notification backend testing, and expands test coverage for admin and API routes.
Introduces a full notification system with support for Discord and Pushover backends, event triggers, and message formatting. Adds backend services, processors, and API endpoints for managing notifications, as well as a new Notifications tab in the admin settings UI. Updates documentation, database schema, and tests to cover notification features and approval workflow improvements. Also changes project license from MIT to AGPL v3.
Implements pure CSS card stack animations for BookDate recommendations, including smooth exit and advance transitions. Adds local caching of library cover thumbnails during scans, updates database schema and API to serve cached covers, and enhances BookDate to support 'favorites' scope with a book picker modal. Updates admin settings validation logic for Prowlarr, improves indexer state management, and documents new features and backend changes.
Introduces a fetchWithRetry method to handle network errors and rate limiting (503, 429) with exponential backoff in AudibleService. Updates getPopularAudiobooks and getNewReleases to use this retry logic and improves error handling to stop pagination on errors but return collected results. Test cases are updated to use non-retryable errors (404) for more accurate coverage.
Refactors admin settings to use a new IndexersTab and card-based indexer management UI, supporting category selection and improved configuration. Updates backend and API routes to handle indexer categories, propagate ASIN for better search scoring, and group indexers by categories to optimize Prowlarr searches. Enhances documentation to clarify non-terminal request matching and auto-completion behavior. Adds new reusable components for indexer management and category selection.
Implements configurable Audible region selection in setup and admin settings, affecting all Audible API calls and triggering data refresh on change. Adds a user-facing 'Change Password' modal in the header for local users, moving password change from admin-only to all local users via a new /api/auth/change-password endpoint. Updates documentation, API routes, and context to support these features, and removes the old admin-only password change flow.
Introduces support for custom OpenAI-compatible AI providers with configurable base URLs, including UI, backend validation, and connection testing. Enhances qBittorrent integration to support HTTP Basic Auth for reverse proxies, adds detailed debug logging, and updates documentation for both features. Also improves login page description logic and AI prompt generation for recommendations.
Replaces scattered console statements with a unified RMABLogger across backend API routes and services. Adds LOG_LEVEL-based filtering, job-aware database persistence, and context-based logging. Updates documentation to describe the new logging system and usage patterns. Also documents qBittorrent CSRF header fix
Added automatic chapter merging to M4B with admin/config toggles, UI controls, and backend logic. Updated documentation to reflect implementation. Refactored ranking algorithm: increased Title/Author match points, removed size scoring, and improved Usenet/torrent handling. Enhanced Prowlarr integration for protocol detection and filtering. Improved file organizer to support chapter merging. Various bug fixes and logging improvements.
Introduces an API endpoint to trigger e-book downloads for completed requests, with admin UI integration in RecentRequestsTable and RequestActionsDropdown. Updates the admin dashboard to detect e-book sidecar feature availability from settings. Enhances torrent search result handling with info URLs, improves ranking algorithm normalization, and refines interactive search to show all results without threshold filtering. Also allows nullable ratings in request schemas.
Clear credentials when switching download client types in the admin settings page and update validation logic for enabling the test connection button. In SABnzbd service, trim API key input and add explicit validation and error handling for missing or invalid API keys during connection tests.
Introduces SABnzbd as a supported download client for Usenet/NZB alongside qBittorrent, including service implementation, setup wizard and admin settings UI updates, and protocol-specific job processor logic. Updates documentation, PRD, and database schema to support NZB downloads, adds comprehensive technical details and testing strategies, and fixes Audible integration issues related to search and ASIN extraction.
Implements configurable indexer flag bonuses/penalties for torrent ranking, including UI for admin settings and support in ranking-algorithm. Adds an option to disable SSL certificate verification for qBittorrent connections (for self-signed certs), with UI in both setup and admin settings, and persists the setting. Updates documentation, API routes, and ranking logic to support these features. Also includes minor UI improvements and bug fixes.
Adds detection of local users for authentication validation and login, prevents role changes for OIDC users, and clarifies user management UI. Enhances active downloads API to include speed and ETA from qBittorrent, and improves file path handling in download monitoring. Also updates torrent tagging and user info returned by APIs.
Update axios paramsSerializer and request logic to send indexerIds as repeated query parameters (indexerIds=1&indexerIds=2) instead of a comma-separated string. This ensures compatibility with Prowlarr's expected API format.
Introduces `asin` and `isbn` fields to the PlexLibrary schema and database, with migration and indexing for fast lookups. Updates scan and recently-added processors to persist ASIN/ISBN from both Plex and Audiobookshelf backends. Enhances matching logic to prioritize exact ASIN matches using the new fields, improving match accuracy for Audiobookshelf users. Also includes minor improvements: fixes cover art handling for cached thumbnails, adds download URL validation in Prowlarr and qBittorrent integrations, and updates documentation to reflect these changes.
Root cause: Singleton caching issue
The qBittorrent service uses a singleton pattern with a configLoaded flag.
Once initialized, it NEVER re-reads the database config, even when the
user changes settings via the admin settings page.
Flow showing the bug:
1. Wizard saves download_dir to database ✓
2. First torrent: service reads config, creates singleton, sets configLoaded=true ✓
3. User changes download_dir in settings page ✓ (database updated)
4. Next torrent: getQBittorrentService() returns CACHED singleton ✗
5. Cached singleton has OLD download_dir value in this.defaultSavePath ✗
6. Category check shows "already has correct save path: /old/path" ✗
7. Download goes to wrong location ✗
The singleton check (line 745):
if (!qbittorrentService || !configLoaded) {
// Only runs if service doesn't exist or config failed
}
Once both exist, this block is SKIPPED forever!
Fix:
1. Added invalidateQBittorrentService() function
- Resets qbittorrentService = null
- Resets configLoaded = false
- Forces reload from database on next use
2. Call invalidation from settings APIs:
- After updating paths (download_dir, media_dir)
- After updating download client (URL, credentials)
3. Next torrent addition:
- getQBittorrentService() sees null singleton
- Re-reads config from database
- Creates new service with current download_dir
- Category updated with correct path
Benefits:
- Settings changes take effect immediately
- No app restart needed
- Category save path always matches current config
- Download client credentials always current
Updated documentation to explain singleton invalidation pattern.
Root cause: We were blindly calling createCategory (409 if exists) then
editCategory (409 for unknown reason), but editCategory was failing and
the category kept its old save path, causing downloads to wrong location.
The 409 from editCategory doesn't mean 'already has this path', it means
the operation failed. Without checking first, we don't know why.
New approach:
1. GET /torrents/categories first to check current state
2. If category doesn't exist: create it with correct save path
3. If category exists with wrong path: edit to update save path
4. If category exists with correct path: skip (no API call needed)
Benefits:
- Avoids unnecessary 409 errors
- Only calls editCategory when actually needed
- Logs show exactly what's happening (create/update/skip)
- Handles both savePath and save_path response formats (v4.4.0+ compat)
- Better error logging with full response details
This ensures category save path is ACTUALLY updated when user changes
download_dir setting, fixing downloads going to wrong location.
References:
- qBittorrent API docs: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)
- Issue #15969: save_path vs savePath inconsistency in API v2.8.4+
qBittorrent's /torrents/editCategory endpoint returns 409 (Conflict) when
the category already has the specified save path (no change needed).
This is expected behavior when:
- User hasn't changed download_dir setting since last torrent
- Category already has correct save path
Previously logged as warning with full error stack trace, making it look
like an error when it's actually normal operation.
Changes:
- Check for 409 status code from editCategory
- Log friendly message: 'Category already has save path: /path'
- Only log unexpected errors with console.warn
Now both createCategory and editCategory handle 409 gracefully:
- createCategory 409 = category exists
- editCategory 409 = category already has this path
Both are expected, not errors.
The 409 (Conflict) status code from qBittorrent's createCategory endpoint
means 'category already exists', which is expected behavior, not an error.
Previously, the full error object was logged with console.log(), making it
look like an error in the logs when it's actually normal operation.
Changes:
- Check for 409 status code specifically
- Log friendly message: 'Category already exists' for 409
- Only log unexpected errors with console.warn
- Cleaner logs that don't alarm users
The flow still works correctly:
1. Try createCategory (succeeds if new, 409 if exists)
2. Always editCategory to update save path to match current config
3. Both operations complete successfully
Previously, when a user changed the download_dir setting after initial
setup, the qBittorrent category "readmeabook" would retain the old save
path. This could cause torrents to download to the wrong location,
depending on qBittorrent's Automatic Torrent Management (ATM) settings.
Root cause:
- ensureCategory() only created the category if it didn't exist
- createCategory API is idempotent but doesn't update existing categories
- If download_dir changed from /downloads to /downloads/RMAB, category
would still have savePath=/downloads
qBittorrent behavior:
- If ATM enabled: category savePath overrides per-torrent savepath
- If ATM disabled: per-torrent savepath takes precedence
Fix:
- ensureCategory() now calls both createCategory AND editCategory
- createCategory: ensures category exists (idempotent)
- editCategory: updates save path to match current download_dir config
- This guarantees category path is always synced with database config
Benefits:
- Users can change download_dir setting and it takes effect immediately
- Works regardless of ATM settings in qBittorrent
- No manual qBittorrent category management needed
Updated documentation/phase3/qbittorrent.md to explain category
management and save path synchronization.
**Problem:** Prowlarr searches were querying ALL indexers instead of only
the ones enabled in user settings, causing torrents to be selected from
disabled/untrusted indexers.
**Root Cause:** The prowlarr.search() method didn't filter by indexer IDs,
and callers weren't passing enabled indexer IDs to the search.
**Changes:**
1. Added indexerIds parameter to SearchFilters interface
2. Updated prowlarr.service.ts search() to filter by indexerIds
3. Updated search-indexers.processor.ts to fetch and pass enabled indexer IDs
4. Updated interactive-search route to fetch and pass enabled indexer IDs
5. Added validation: search fails if no indexers are configured/enabled
6. Updated documentation to reflect indexer filtering behavior
**Impact:**
- Manual search: Only searches enabled indexers
- Interactive search: Only searches enabled indexers
- RSS monitoring: Already correctly filtered (no changes needed)
**Testing:** TypeScript type checking passed with no errors
kikootwo